1 /* GStreamer

     2  * Copyright (C) 2004 Wim Taymans <wim@fluendo.com>

     3  *

     4  * gstmessage.c: GstMessage subsystem

     5  *

     6  * This library is free software; you can redistribute it and/or

     7  * modify it under the terms of the GNU Library General Public

     8  * License as published by the Free Software Foundation; either

     9  * version 2 of the License, or (at your option) any later version.

    10  *

    11  * This library is distributed in the hope that it will be useful,

    12  * but WITHOUT ANY WARRANTY; without even the implied warranty of

    13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

    14  * Library General Public License for more details.

    15  *

    16  * You should have received a copy of the GNU Library General Public

    17  * License along with this library; if not, write to the

    18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,

    19  * Boston, MA 02111-1307, USA.

    20  */

    21 

    22 /**

    23  * SECTION:gstmessage

    24  * @short_description: Lightweight objects to signal the application of

    25  *                     pipeline events

    26  * @see_also: #GstBus, #GstMiniObject, #GstElement

    27  *

    28  * Messages are implemented as a subclass of #GstMiniObject with a generic

    29  * #GstStructure as the content. This allows for writing custom messages without

    30  * requiring an API change while allowing a wide range of different types

    31  * of messages.

    32  *

    33  * Messages are posted by objects in the pipeline and are passed to the

    34  * application using the #GstBus.

    35 

    36  * The basic use pattern of posting a message on a #GstBus is as follows:

    37  *

    38  * <example>

    39  * <title>Posting a #GstMessage</title>

    40  *   <programlisting>

    41  *    gst_bus_post (bus, gst_message_new_eos());

    42  *   </programlisting>

    43  * </example>

    44  *

    45  * A #GstElement usually posts messages on the bus provided by the parent

    46  * container using gst_element_post_message().

    47  *

    48  * Last reviewed on 2005-11-09 (0.9.4)

    49  */

    50 

    51 

    52 #include "gst_private.h"

    53 #include <string.h>             /* memcpy */

    54 #include "gsterror.h"

    55 #include "gstenumtypes.h"

    56 #include "gstinfo.h"

    57 #include "gstmessage.h"

    58 #include "gsttaglist.h"

    59 #include "gstutils.h"

    60 

    61 #ifdef __SYMBIAN32__

    62 #include <glib_global.h>

    63 #endif

    64 

    65 

    66 static void gst_message_init (GTypeInstance * instance, gpointer g_class);

    67 static void gst_message_class_init (gpointer g_class, gpointer class_data);

    68 static void gst_message_finalize (GstMessage * message);

    69 static GstMessage *_gst_message_copy (GstMessage * message);

    70 

    71 static GstMiniObjectClass *parent_class = NULL;

    72 #ifdef __SYMBIAN32__

    73 EXPORT_C

    74 #endif

    75 

    76 

    77 void

    78 _gst_message_initialize (void)

    79 {

    80   GST_CAT_INFO (GST_CAT_GST_INIT, "init messages");

    81 

    82   /* the GstMiniObject types need to be class_ref'd once before it can be

    83    * done from multiple threads;

    84    * see http://bugzilla.gnome.org/show_bug.cgi?id=304551 */

    85   g_type_class_ref (gst_message_get_type ());

    86 }

    87 

    88 typedef struct

    89 {

    90   const gint type;

    91   const gchar *name;

    92   GQuark quark;

    93 } GstMessageQuarks;

    94 

    95 static GstMessageQuarks message_quarks[] = {

    96   {GST_MESSAGE_UNKNOWN, "unknown", 0},

    97   {GST_MESSAGE_EOS, "eos", 0},

    98   {GST_MESSAGE_ERROR, "error", 0},

    99   {GST_MESSAGE_WARNING, "warning", 0},

   100   {GST_MESSAGE_INFO, "info", 0},

   101   {GST_MESSAGE_TAG, "tag", 0},

   102   {GST_MESSAGE_BUFFERING, "buffering", 0},

   103   {GST_MESSAGE_STATE_CHANGED, "state-changed", 0},

   104   {GST_MESSAGE_STATE_DIRTY, "state-dirty", 0},

   105   {GST_MESSAGE_STEP_DONE, "step-done", 0},

   106   {GST_MESSAGE_CLOCK_PROVIDE, "clock-provide", 0},

   107   {GST_MESSAGE_CLOCK_LOST, "clock-lost", 0},

   108   {GST_MESSAGE_NEW_CLOCK, "new-clock", 0},

   109   {GST_MESSAGE_STRUCTURE_CHANGE, "structure-change", 0},

   110   {GST_MESSAGE_STREAM_STATUS, "stream-status", 0},

   111   {GST_MESSAGE_APPLICATION, "application", 0},

   112   {GST_MESSAGE_ELEMENT, "element", 0},

   113   {GST_MESSAGE_SEGMENT_START, "segment-start", 0},

   114   {GST_MESSAGE_SEGMENT_DONE, "segment-done", 0},

   115   {GST_MESSAGE_DURATION, "duration", 0},

   116   {GST_MESSAGE_LATENCY, "latency", 0},

   117   {GST_MESSAGE_ASYNC_START, "async-start", 0},

   118   {GST_MESSAGE_ASYNC_DONE, "async-done", 0},

   119   {0, NULL, 0}

   120 };

   121 

   122 /**

   123  * gst_message_type_get_name:

   124  * @type: the message type

   125  *

   126  * Get a printable name for the given message type. Do not modify or free.

   127  *

   128  * Returns: a reference to the static name of the message.

   129  */

   130 #ifdef __SYMBIAN32__

   131 EXPORT_C

   132 #endif

   133 

   134 const gchar *

   135 gst_message_type_get_name (GstMessageType type)

   136 {

   137   gint i;

   138 

   139   for (i = 0; message_quarks[i].name; i++) {

   140     if (type == message_quarks[i].type)

   141       return message_quarks[i].name;

   142   }

   143   return "unknown";

   144 }

   145 

   146 /**

   147  * gst_message_type_to_quark:

   148  * @type: the message type

   149  *

   150  * Get the unique quark for the given message type.

   151  *

   152  * Returns: the quark associated with the message type

   153  */

   154 #ifdef __SYMBIAN32__

   155 EXPORT_C

   156 #endif

   157 

   158 GQuark

   159 gst_message_type_to_quark (GstMessageType type)

   160 {

   161   gint i;

   162 

   163   for (i = 0; message_quarks[i].name; i++) {

   164     if (type == message_quarks[i].type)

   165       return message_quarks[i].quark;

   166   }

   167   return 0;

   168 }

   169 #ifdef __SYMBIAN32__

   170 EXPORT_C

   171 #endif

   172 

   173 

   174 GType

   175 gst_message_get_type (void)

   176 {

   177   static GType _gst_message_type;

   178 

   179   if (G_UNLIKELY (_gst_message_type == 0)) {

   180     gint i;

   181     static const GTypeInfo message_info = {

   182       sizeof (GstMessageClass),

   183       NULL,

   184       NULL,

   185       gst_message_class_init,

   186       NULL,

   187       NULL,

   188       sizeof (GstMessage),

   189       0,

   190       gst_message_init,

   191       NULL

   192     };

   193 

   194     _gst_message_type = g_type_register_static (GST_TYPE_MINI_OBJECT,

   195         "GstMessage", &message_info, 0);

   196 

   197     for (i = 0; message_quarks[i].name; i++) {

   198       message_quarks[i].quark =

   199           g_quark_from_static_string (message_quarks[i].name);

   200     }

   201   }

   202   return _gst_message_type;

   203 }

   204 

   205 static void

   206 gst_message_class_init (gpointer g_class, gpointer class_data)

   207 {

   208   GstMessageClass *message_class = GST_MESSAGE_CLASS (g_class);

   209 

   210   parent_class = g_type_class_peek_parent (g_class);

   211 

   212   message_class->mini_object_class.copy =

   213       (GstMiniObjectCopyFunction) _gst_message_copy;

   214   message_class->mini_object_class.finalize =

   215       (GstMiniObjectFinalizeFunction) gst_message_finalize;

   216 }

   217 

   218 static void

   219 gst_message_init (GTypeInstance * instance, gpointer g_class)

   220 {

   221   GstMessage *message = GST_MESSAGE (instance);

   222 

   223   GST_CAT_LOG (GST_CAT_MESSAGE, "new message %p", message);

   224   GST_MESSAGE_TIMESTAMP (message) = GST_CLOCK_TIME_NONE;

   225 }

   226 

   227 static void

   228 gst_message_finalize (GstMessage * message)

   229 {

   230   g_return_if_fail (message != NULL);

   231 

   232   GST_CAT_LOG (GST_CAT_MESSAGE, "finalize message %p", message);

   233 

   234   if (GST_MESSAGE_SRC (message)) {

   235     gst_object_unref (GST_MESSAGE_SRC (message));

   236     GST_MESSAGE_SRC (message) = NULL;

   237   }

   238 

   239   if (message->lock) {

   240     GST_MESSAGE_LOCK (message);

   241     GST_MESSAGE_SIGNAL (message);

   242     GST_MESSAGE_UNLOCK (message);

   243   }

   244 

   245   if (message->structure) {

   246     gst_structure_set_parent_refcount (message->structure, NULL);

   247     gst_structure_free (message->structure);

   248   }

   249 

   250   GST_MINI_OBJECT_CLASS (parent_class)->finalize (GST_MINI_OBJECT (message));

   251 }

   252 

   253 static GstMessage *

   254 _gst_message_copy (GstMessage * message)

   255 {

   256   GstMessage *copy;

   257 

   258   GST_CAT_LOG (GST_CAT_MESSAGE, "copy message %p", message);

   259 

   260   copy = (GstMessage *) gst_mini_object_new (GST_TYPE_MESSAGE);

   261 

   262   /* FIXME, need to copy relevant data from the miniobject. */

   263   //memcpy (copy, message, sizeof (GstMessage));

   264 

   265   GST_MESSAGE_GET_LOCK (copy) = GST_MESSAGE_GET_LOCK (message);

   266   GST_MESSAGE_COND (copy) = GST_MESSAGE_COND (message);

   267   GST_MESSAGE_TYPE (copy) = GST_MESSAGE_TYPE (message);

   268   GST_MESSAGE_TIMESTAMP (copy) = GST_MESSAGE_TIMESTAMP (message);

   269 

   270   if (GST_MESSAGE_SRC (message)) {

   271     GST_MESSAGE_SRC (copy) = gst_object_ref (GST_MESSAGE_SRC (message));

   272   }

   273 

   274   if (message->structure) {

   275     copy->structure = gst_structure_copy (message->structure);

   276     gst_structure_set_parent_refcount (copy->structure,

   277         &copy->mini_object.refcount);

   278   }

   279 

   280   return copy;

   281 }

   282 

   283 /**

   284  * gst_message_new_custom:

   285  * @type: The #GstMessageType to distinguish messages

   286  * @src: The object originating the message.

   287  * @structure: The structure for the message. The message will take ownership of

   288  * the structure.

   289  *

   290  * Create a new custom-typed message. This can be used for anything not

   291  * handled by other message-specific functions to pass a message to the

   292  * app. The structure field can be NULL.

   293  *

   294  * Returns: The new message.

   295  *

   296  * MT safe.

   297  */

   298 #ifdef __SYMBIAN32__

   299 EXPORT_C

   300 #endif

   301 

   302 GstMessage *

   303 gst_message_new_custom (GstMessageType type, GstObject * src,

   304     GstStructure * structure)

   305 {

   306   GstMessage *message;

   307 

   308   message = (GstMessage *) gst_mini_object_new (GST_TYPE_MESSAGE);

   309 

   310   GST_CAT_LOG (GST_CAT_MESSAGE, "source %s: creating new message %p %s",

   311       (src ? GST_OBJECT_NAME (src) : "NULL"), message,

   312       gst_message_type_get_name (type));

   313 

   314   message->type = type;

   315 

   316   if (src)

   317     gst_object_ref (src);

   318   message->src = src;

   319 

   320   if (structure) {

   321     gst_structure_set_parent_refcount (structure,

   322         &message->mini_object.refcount);

   323   }

   324   message->structure = structure;

   325 

   326   return message;

   327 }

   328 

   329 /**

   330  * gst_message_new_eos:

   331  * @src: The object originating the message.

   332  *

   333  * Create a new eos message. This message is generated and posted in

   334  * the sink elements of a GstBin. The bin will only forward the EOS

   335  * message to the application if all sinks have posted an EOS message.

   336  *

   337  * Returns: The new eos message.

   338  *

   339  * MT safe.

   340  */

   341 #ifdef __SYMBIAN32__

   342 EXPORT_C

   343 #endif

   344 

   345 GstMessage *

   346 gst_message_new_eos (GstObject * src)

   347 {

   348   GstMessage *message;

   349 

   350   message = gst_message_new_custom (GST_MESSAGE_EOS, src, NULL);

   351 

   352   return message;

   353 }

   354 

   355 /**

   356  * gst_message_new_error:

   357  * @src: The object originating the message.

   358  * @error: The GError for this message.

   359  * @debug: A debugging string for something or other.

   360  *

   361  * Create a new error message. The message will copy @error and

   362  * @debug. This message is posted by element when a fatal event

   363  * occured. The pipeline will probably (partially) stop. The application

   364  * receiving this message should stop the pipeline.

   365  *

   366  * Returns: The new error message.

   367  *

   368  * MT safe.

   369  */

   370 #ifdef __SYMBIAN32__

   371 EXPORT_C

   372 #endif

   373 

   374 GstMessage *

   375 gst_message_new_error (GstObject * src, GError * error, gchar * debug)

   376 {

   377   GstMessage *message;

   378 

   379   message = gst_message_new_custom (GST_MESSAGE_ERROR, src,

   380       gst_structure_new ("GstMessageError", "gerror", GST_TYPE_G_ERROR, error,

   381           "debug", G_TYPE_STRING, debug, NULL));

   382 

   383   return message;

   384 }

   385 

   386 /**

   387  * gst_message_new_warning:

   388  * @src: The object originating the message.

   389  * @error: The GError for this message.

   390  * @debug: A debugging string for something or other.

   391  *

   392  * Create a new warning message. The message will make copies of @error and

   393  * @debug.

   394  *

   395  * Returns: The new warning message.

   396  *

   397  * MT safe.

   398  */

   399 #ifdef __SYMBIAN32__

   400 EXPORT_C

   401 #endif

   402 

   403 GstMessage *

   404 gst_message_new_warning (GstObject * src, GError * error, gchar * debug)

   405 {

   406   GstMessage *message;

   407 

   408   message = gst_message_new_custom (GST_MESSAGE_WARNING, src,

   409       gst_structure_new ("GstMessageWarning", "gerror", GST_TYPE_G_ERROR, error,

   410           "debug", G_TYPE_STRING, debug, NULL));

   411 

   412   return message;

   413 }

   414 

   415 /**

   416  * gst_message_new_info:

   417  * @src: The object originating the message.

   418  * @error: The GError for this message.

   419  * @debug: A debugging string for something or other.

   420  *

   421  * Create a new info message. The message will make copies of @error and

   422  * @debug.

   423  *

   424  * Returns: The new info message.

   425  *

   426  * Since: 0.10.12

   427  *

   428  * MT safe.

   429  */

   430 #ifdef __SYMBIAN32__

   431 EXPORT_C

   432 #endif

   433 

   434 GstMessage *

   435 gst_message_new_info (GstObject * src, GError * error, gchar * debug)

   436 {

   437   GstMessage *message;

   438 

   439   message = gst_message_new_custom (GST_MESSAGE_INFO, src,

   440       gst_structure_new ("GstMessageInfo", "gerror", GST_TYPE_G_ERROR, error,

   441           "debug", G_TYPE_STRING, debug, NULL));

   442 

   443   return message;

   444 }

   445 

   446 /**

   447  * gst_message_new_tag:

   448  * @src: The object originating the message.

   449  * @tag_list: The tag list for the message.

   450  *

   451  * Create a new tag message. The message will take ownership of the tag list.

   452  * The message is posted by elements that discovered a new taglist.

   453  *

   454  * Returns: The new tag message.

   455  *

   456  * MT safe.

   457  */

   458 #ifdef __SYMBIAN32__

   459 EXPORT_C

   460 #endif

   461 

   462 GstMessage *

   463 gst_message_new_tag (GstObject * src, GstTagList * tag_list)

   464 {

   465   GstMessage *message;

   466 

   467   g_return_val_if_fail (GST_IS_STRUCTURE (tag_list), NULL);

   468 

   469   message =

   470       gst_message_new_custom (GST_MESSAGE_TAG, src, (GstStructure *) tag_list);

   471 

   472   return message;

   473 }

   474 

   475 /**

   476  * gst_message_new_buffering:

   477  * @src: The object originating the message.

   478  * @percent: The buffering percent

   479  *

   480  * Create a new buffering message. This message can be posted by an element that

   481  * needs to buffer data before it can continue processing. @percent should be a

   482  * value between 0 and 100. A value of 100 means that the buffering completed.

   483  *

   484  * When @percent is < 100 the application should PAUSE a PLAYING pipeline. When

   485  * @percent is 100, the application can set the pipeline (back) to PLAYING.

   486  * The application must be prepared to receive BUFFERING messages in the

   487  * PREROLLING state and may only set the pipeline to PLAYING after receiving a

   488  * message with @percent set to 100, which can happen after the pipeline

   489  * completed prerolling. 

   490  *

   491  * Returns: The new buffering message.

   492  *

   493  * Since: 0.10.11

   494  *

   495  * MT safe.

   496  */

   497 #ifdef __SYMBIAN32__

   498 EXPORT_C

   499 #endif

   500 

   501 GstMessage *

   502 gst_message_new_buffering (GstObject * src, gint percent)

   503 {

   504   GstMessage *message;

   505 

   506   g_return_val_if_fail (percent >= 0 && percent <= 100, NULL);

   507 

   508   message = gst_message_new_custom (GST_MESSAGE_BUFFERING, src,

   509       gst_structure_new ("GstMessageBuffering",

   510           "buffer-percent", G_TYPE_INT, percent, NULL));

   511 

   512   return message;

   513 }

   514 

   515 /**

   516  * gst_message_new_state_changed:

   517  * @src: the object originating the message

   518  * @oldstate: the previous state

   519  * @newstate: the new (current) state

   520  * @pending: the pending (target) state

   521  *

   522  * Create a state change message. This message is posted whenever an element

   523  * changed its state.

   524  *

   525  * Returns: The new state change message.

   526  *

   527  * MT safe.

   528  */

   529 #ifdef __SYMBIAN32__

   530 EXPORT_C

   531 #endif

   532 

   533 GstMessage *

   534 gst_message_new_state_changed (GstObject * src,

   535     GstState oldstate, GstState newstate, GstState pending)

   536 {

   537   GstMessage *message;

   538 

   539   message = gst_message_new_custom (GST_MESSAGE_STATE_CHANGED, src,

   540       gst_structure_new ("GstMessageState",

   541           "old-state", GST_TYPE_STATE, (gint) oldstate,

   542           "new-state", GST_TYPE_STATE, (gint) newstate,

   543           "pending-state", GST_TYPE_STATE, (gint) pending, NULL));

   544 

   545   return message;

   546 }

   547 

   548 /**

   549  * gst_message_new_state_dirty:

   550  * @src: the object originating the message

   551  *

   552  * Create a state dirty message. This message is posted whenever an element

   553  * changed its state asynchronously and is used internally to update the

   554  * states of container objects.

   555  *

   556  * Returns: The new state dirty message.

   557  *

   558  * MT safe.

   559  */

   560 #ifdef __SYMBIAN32__

   561 EXPORT_C

   562 #endif

   563 

   564 GstMessage *

   565 gst_message_new_state_dirty (GstObject * src)

   566 {

   567   GstMessage *message;

   568 

   569   message = gst_message_new_custom (GST_MESSAGE_STATE_DIRTY, src, NULL);

   570 

   571   return message;

   572 }

   573 

   574 /**

   575  * gst_message_new_clock_provide:

   576  * @src: The object originating the message.

   577  * @clock: The clock it provides

   578  * @ready: TRUE if the sender can provide a clock

   579  *

   580  * Create a clock provide message. This message is posted whenever an

   581  * element is ready to provide a clock or lost its ability to provide

   582  * a clock (maybe because it paused or became EOS).

   583  *

   584  * This message is mainly used internally to manage the clock

   585  * selection.

   586  *

   587  * Returns: The new provide clock message.

   588  *

   589  * MT safe.

   590  */

   591 #ifdef __SYMBIAN32__

   592 EXPORT_C

   593 #endif

   594 

   595 GstMessage *

   596 gst_message_new_clock_provide (GstObject * src, GstClock * clock,

   597     gboolean ready)

   598 {

   599   GstMessage *message;

   600 

   601   message = gst_message_new_custom (GST_MESSAGE_CLOCK_PROVIDE, src,

   602       gst_structure_new ("GstMessageClockProvide",

   603           "clock", GST_TYPE_CLOCK, clock,

   604           "ready", G_TYPE_BOOLEAN, ready, NULL));

   605 

   606   return message;

   607 }

   608 

   609 /**

   610  * gst_message_new_clock_lost:

   611  * @src: The object originating the message.

   612  * @clock: the clock that was lost

   613  *

   614  * Create a clock lost message. This message is posted whenever the

   615  * clock is not valid anymore.

   616  *

   617  * If this message is posted by the pipeline, the pipeline will

   618  * select a new clock again when it goes to PLAYING. It might therefore

   619  * be needed to set the pipeline to PAUSED and PLAYING again.

   620  *

   621  * Returns: The new clock lost message.

   622  *

   623  * MT safe.

   624  */

   625 #ifdef __SYMBIAN32__

   626 EXPORT_C

   627 #endif

   628 

   629 GstMessage *

   630 gst_message_new_clock_lost (GstObject * src, GstClock * clock)

   631 {

   632   GstMessage *message;

   633 

   634   message = gst_message_new_custom (GST_MESSAGE_CLOCK_LOST, src,

   635       gst_structure_new ("GstMessageClockLost",

   636           "clock", GST_TYPE_CLOCK, clock, NULL));

   637 

   638   return message;

   639 }

   640 

   641 /**

   642  * gst_message_new_new_clock:

   643  * @src: The object originating the message.

   644  * @clock: the new selected clock

   645  *

   646  * Create a new clock message. This message is posted whenever the

   647  * pipeline selectes a new clock for the pipeline.

   648  *

   649  * Returns: The new new clock message.

   650  *

   651  * MT safe.

   652  */

   653 #ifdef __SYMBIAN32__

   654 EXPORT_C

   655 #endif

   656 

   657 GstMessage *

   658 gst_message_new_new_clock (GstObject * src, GstClock * clock)

   659 {

   660   GstMessage *message;

   661 

   662   message = gst_message_new_custom (GST_MESSAGE_NEW_CLOCK, src,

   663       gst_structure_new ("GstMessageNewClock",

   664           "clock", GST_TYPE_CLOCK, clock, NULL));

   665 

   666   return message;

   667 }

   668 

   669 /**

   670  * gst_message_new_segment_start:

   671  * @src: The object originating the message.

   672  * @format: The format of the position being played

   673  * @position: The position of the segment being played

   674  *

   675  * Create a new segment message. This message is posted by elements that

   676  * start playback of a segment as a result of a segment seek. This message

   677  * is not received by the application but is used for maintenance reasons in

   678  * container elements.

   679  *

   680  * Returns: The new segment start message.

   681  *

   682  * MT safe.

   683  */

   684 #ifdef __SYMBIAN32__

   685 EXPORT_C

   686 #endif

   687 

   688 GstMessage *

   689 gst_message_new_segment_start (GstObject * src, GstFormat format,

   690     gint64 position)

   691 {

   692   GstMessage *message;

   693 

   694   message = gst_message_new_custom (GST_MESSAGE_SEGMENT_START, src,

   695       gst_structure_new ("GstMessageSegmentStart",

   696           "format", GST_TYPE_FORMAT, format,

   697           "position", G_TYPE_INT64, position, NULL));

   698 

   699   return message;

   700 }

   701 

   702 /**

   703  * gst_message_new_segment_done:

   704  * @src: The object originating the message.

   705  * @format: The format of the position being done

   706  * @position: The position of the segment being done

   707  *

   708  * Create a new segment done message. This message is posted by elements that

   709  * finish playback of a segment as a result of a segment seek. This message

   710  * is received by the application after all elements that posted a segment_start

   711  * have posted the segment_done.

   712  *

   713  * Returns: The new segment done message.

   714  *

   715  * MT safe.

   716  */

   717 #ifdef __SYMBIAN32__

   718 EXPORT_C

   719 #endif

   720 

   721 GstMessage *

   722 gst_message_new_segment_done (GstObject * src, GstFormat format,

   723     gint64 position)

   724 {

   725   GstMessage *message;

   726 

   727   message = gst_message_new_custom (GST_MESSAGE_SEGMENT_DONE, src,

   728       gst_structure_new ("GstMessageSegmentDone",

   729           "format", GST_TYPE_FORMAT, format,

   730           "position", G_TYPE_INT64, position, NULL));

   731 

   732   return message;

   733 }

   734 

   735 /**

   736  * gst_message_new_application:

   737  * @src: The object originating the message.

   738  * @structure: The structure for the message. The message will take ownership of

   739  * the structure.

   740  *

   741  * Create a new application-typed message. GStreamer will never create these

   742  * messages; they are a gift from us to you. Enjoy.

   743  *

   744  * Returns: The new application message.

   745  *

   746  * MT safe.

   747  */

   748 #ifdef __SYMBIAN32__

   749 EXPORT_C

   750 #endif

   751 

   752 GstMessage *

   753 gst_message_new_application (GstObject * src, GstStructure * structure)

   754 {

   755   return gst_message_new_custom (GST_MESSAGE_APPLICATION, src, structure);

   756 }

   757 

   758 /**

   759  * gst_message_new_element:

   760  * @src: The object originating the message.

   761  * @structure: The structure for the message. The message will take ownership of

   762  * the structure.

   763  *

   764  * Create a new element-specific message. This is meant as a generic way of

   765  * allowing one-way communication from an element to an application, for example

   766  * "the firewire cable was unplugged". The format of the message should be

   767  * documented in the element's documentation. The structure field can be NULL.

   768  *

   769  * Returns: The new element message.

   770  *

   771  * MT safe.

   772  */

   773 #ifdef __SYMBIAN32__

   774 EXPORT_C

   775 #endif

   776 

   777 GstMessage *

   778 gst_message_new_element (GstObject * src, GstStructure * structure)

   779 {

   780   return gst_message_new_custom (GST_MESSAGE_ELEMENT, src, structure);

   781 }

   782 

   783 /**

   784  * gst_message_new_duration:

   785  * @src: The object originating the message.

   786  * @format: The format of the duration

   787  * @duration: The new duration 

   788  *

   789  * Create a new duration message. This message is posted by elements that

   790  * know the duration of a stream in a specific format. This message

   791  * is received by bins and is used to calculate the total duration of a

   792  * pipeline. Elements may post a duration message with a duration of

   793  * GST_CLOCK_TIME_NONE to indicate that the duration has changed and the 

   794  * cached duration should be discarded. The new duration can then be 

   795  * retrieved via a query.

   796  *

   797  * Returns: The new duration message.

   798  *

   799  * MT safe.

   800  */

   801 #ifdef __SYMBIAN32__

   802 EXPORT_C

   803 #endif

   804 

   805 GstMessage *

   806 gst_message_new_duration (GstObject * src, GstFormat format, gint64 duration)

   807 {

   808   GstMessage *message;

   809 

   810   message = gst_message_new_custom (GST_MESSAGE_DURATION, src,

   811       gst_structure_new ("GstMessageDuration",

   812           "format", GST_TYPE_FORMAT, format,

   813           "duration", G_TYPE_INT64, duration, NULL));

   814 

   815   return message;

   816 }

   817 

   818 /**

   819  * gst_message_new_async_start:

   820  * @src: The object originating the message.

   821  * @new_base_time: if a new base_time should be set on the element

   822  *

   823  * This message is posted by elements when they start an ASYNC state change. 

   824  * @new_base_time is set to TRUE when the element lost its state when it was

   825  * PLAYING.

   826  *

   827  * Returns: The new async_start message. 

   828  *

   829  * MT safe.

   830  *

   831  * Since: 0.10.13

   832  */

   833 #ifdef __SYMBIAN32__

   834 EXPORT_C

   835 #endif

   836 

   837 GstMessage *

   838 gst_message_new_async_start (GstObject * src, gboolean new_base_time)

   839 {

   840   GstMessage *message;

   841 

   842   message = gst_message_new_custom (GST_MESSAGE_ASYNC_START, src,

   843       gst_structure_new ("GstMessageAsyncStart",

   844           "new-base-time", G_TYPE_BOOLEAN, new_base_time, NULL));

   845 

   846   return message;

   847 }

   848 

   849 /**

   850  * gst_message_new_async_done:

   851  * @src: The object originating the message.

   852  *

   853  * The message is posted when elements completed an ASYNC state change.

   854  *

   855  * Returns: The new async_done message.

   856  *

   857  * MT safe.

   858  *

   859  * Since: 0.10.13

   860  */

   861 #ifdef __SYMBIAN32__

   862 EXPORT_C

   863 #endif

   864 

   865 GstMessage *

   866 gst_message_new_async_done (GstObject * src)

   867 {

   868   GstMessage *message;

   869 

   870   message = gst_message_new_custom (GST_MESSAGE_ASYNC_DONE, src, NULL);

   871 

   872   return message;

   873 }

   874 

   875 /**

   876  * gst_message_new_latency:

   877  * @src: The object originating the message.

   878  *

   879  * This message can be posted by elements when their latency requirements have

   880  * changed.

   881  *

   882  * Returns: The new latency message. 

   883  *

   884  * MT safe.

   885  *

   886  * Since: 0.10.12

   887  */

   888 #ifdef __SYMBIAN32__

   889 EXPORT_C

   890 #endif

   891 

   892 GstMessage *

   893 gst_message_new_latency (GstObject * src)

   894 {

   895   GstMessage *message;

   896 

   897   message = gst_message_new_custom (GST_MESSAGE_LATENCY, src, NULL);

   898 

   899   return message;

   900 }

   901 

   902 /**

   903  * gst_message_get_structure:

   904  * @message: The #GstMessage.

   905  *

   906  * Access the structure of the message.

   907  *

   908  * Returns: The structure of the message. The structure is still

   909  * owned by the message, which means that you should not free it and

   910  * that the pointer becomes invalid when you free the message.

   911  *

   912  * MT safe.

   913  */

   914 #ifdef __SYMBIAN32__

   915 EXPORT_C

   916 #endif

   917 

   918 const GstStructure *

   919 gst_message_get_structure (GstMessage * message)

   920 {

   921   g_return_val_if_fail (GST_IS_MESSAGE (message), NULL);

   922 

   923   return message->structure;

   924 }

   925 

   926 /**

   927  * gst_message_parse_tag:

   928  * @message: A valid #GstMessage of type GST_MESSAGE_TAG.

   929  * @tag_list: Return location for the tag-list.

   930  *

   931  * Extracts the tag list from the GstMessage. The tag list returned in the

   932  * output argument is a copy; the caller must free it when done.

   933  *

   934  * MT safe.

   935  */

   936 #ifdef __SYMBIAN32__

   937 EXPORT_C

   938 #endif

   939 

   940 void

   941 gst_message_parse_tag (GstMessage * message, GstTagList ** tag_list)

   942 {

   943   g_return_if_fail (GST_IS_MESSAGE (message));

   944   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_TAG);

   945   g_return_if_fail (tag_list != NULL);

   946 

   947   *tag_list = (GstTagList *) gst_structure_copy (message->structure);

   948 }

   949 

   950 /**

   951  * gst_message_parse_buffering:

   952  * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.

   953  * @percent: Return location for the percent.

   954  *

   955  * Extracts the buffering percent from the GstMessage. see also

   956  * gst_message_new_buffering().

   957  *

   958  * Since: 0.10.11

   959  *

   960  * MT safe.

   961  */

   962 #ifdef __SYMBIAN32__

   963 EXPORT_C

   964 #endif

   965 

   966 void

   967 gst_message_parse_buffering (GstMessage * message, gint * percent)

   968 {

   969   g_return_if_fail (GST_IS_MESSAGE (message));

   970   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);

   971 

   972   if (percent)

   973     gst_structure_get_int (message->structure, "buffer-percent", percent);

   974 }

   975 

   976 /**

   977  * gst_message_parse_state_changed:

   978  * @message: a valid #GstMessage of type GST_MESSAGE_STATE_CHANGED

   979  * @oldstate: the previous state, or NULL

   980  * @newstate: the new (current) state, or NULL

   981  * @pending: the pending (target) state, or NULL

   982  *

   983  * Extracts the old and new states from the GstMessage.

   984  *

   985  * MT safe.

   986  */

   987 #ifdef __SYMBIAN32__

   988 EXPORT_C

   989 #endif

   990 

   991 void

   992 gst_message_parse_state_changed (GstMessage * message,

   993     GstState * oldstate, GstState * newstate, GstState * pending)

   994 {

   995   g_return_if_fail (GST_IS_MESSAGE (message));

   996   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STATE_CHANGED);

   997 

   998   if (oldstate)

   999     gst_structure_get_enum (message->structure, "old-state",

  1000         GST_TYPE_STATE, (gint *) oldstate);

  1001   if (newstate)

  1002     gst_structure_get_enum (message->structure, "new-state",

  1003         GST_TYPE_STATE, (gint *) newstate);

  1004   if (pending)

  1005     gst_structure_get_enum (message->structure, "pending-state",

  1006         GST_TYPE_STATE, (gint *) pending);

  1007 }

  1008 

  1009 /**

  1010  * gst_message_parse_clock_provide:

  1011  * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_PROVIDE.

  1012  * @clock: A pointer to  hold a clock object.

  1013  * @ready: A pointer to hold the ready flag.

  1014  *

  1015  * Extracts the clock and ready flag from the GstMessage.

  1016  * The clock object returned remains valid until the message is freed.

  1017  *

  1018  * MT safe.

  1019  */

  1020 #ifdef __SYMBIAN32__

  1021 EXPORT_C

  1022 #endif

  1023 

  1024 void

  1025 gst_message_parse_clock_provide (GstMessage * message, GstClock ** clock,

  1026     gboolean * ready)

  1027 {

  1028   const GValue *clock_gvalue;

  1029 

  1030   g_return_if_fail (GST_IS_MESSAGE (message));

  1031   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_CLOCK_PROVIDE);

  1032 

  1033   clock_gvalue = gst_structure_get_value (message->structure, "clock");

  1034   g_return_if_fail (clock_gvalue != NULL);

  1035   g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);

  1036 

  1037   if (ready)

  1038     gst_structure_get_boolean (message->structure, "ready", ready);

  1039   if (clock)

  1040     *clock = (GstClock *) g_value_get_object (clock_gvalue);

  1041 }

  1042 

  1043 /**

  1044  * gst_message_parse_clock_lost:

  1045  * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_LOST.

  1046  * @clock: A pointer to hold the lost clock

  1047  *

  1048  * Extracts the lost clock from the GstMessage.

  1049  * The clock object returned remains valid until the message is freed.

  1050  *

  1051  * MT safe.

  1052  */

  1053 #ifdef __SYMBIAN32__

  1054 EXPORT_C

  1055 #endif

  1056 

  1057 void

  1058 gst_message_parse_clock_lost (GstMessage * message, GstClock ** clock)

  1059 {

  1060   const GValue *clock_gvalue;

  1061 

  1062   g_return_if_fail (GST_IS_MESSAGE (message));

  1063   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_CLOCK_LOST);

  1064 

  1065   clock_gvalue = gst_structure_get_value (message->structure, "clock");

  1066   g_return_if_fail (clock_gvalue != NULL);

  1067   g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);

  1068 

  1069   if (clock)

  1070     *clock = (GstClock *) g_value_get_object (clock_gvalue);

  1071 }

  1072 

  1073 /**

  1074  * gst_message_parse_new_clock:

  1075  * @message: A valid #GstMessage of type GST_MESSAGE_NEW_CLOCK.

  1076  * @clock: A pointer to hold the selected new clock

  1077  *

  1078  * Extracts the new clock from the GstMessage.

  1079  * The clock object returned remains valid until the message is freed.

  1080  *

  1081  * MT safe.

  1082  */

  1083 #ifdef __SYMBIAN32__

  1084 EXPORT_C

  1085 #endif

  1086 

  1087 void

  1088 gst_message_parse_new_clock (GstMessage * message, GstClock ** clock)

  1089 {

  1090   const GValue *clock_gvalue;

  1091 

  1092   g_return_if_fail (GST_IS_MESSAGE (message));

  1093   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_NEW_CLOCK);

  1094 

  1095   clock_gvalue = gst_structure_get_value (message->structure, "clock");

  1096   g_return_if_fail (clock_gvalue != NULL);

  1097   g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);

  1098 

  1099   if (clock)

  1100     *clock = (GstClock *) g_value_get_object (clock_gvalue);

  1101 }

  1102 

  1103 /**

  1104  * gst_message_parse_error:

  1105  * @message: A valid #GstMessage of type GST_MESSAGE_ERROR.

  1106  * @gerror: Location for the GError

  1107  * @debug: Location for the debug message, or NULL

  1108  *

  1109  * Extracts the GError and debug string from the GstMessage. The values returned

  1110  * in the output arguments are copies; the caller must free them when done.

  1111  *

  1112  * MT safe.

  1113  */

  1114 #ifdef __SYMBIAN32__

  1115 EXPORT_C

  1116 #endif

  1117 

  1118 void

  1119 gst_message_parse_error (GstMessage * message, GError ** gerror, gchar ** debug)

  1120 {

  1121   const GValue *error_gvalue;

  1122   GError *error_val;

  1123 

  1124   g_return_if_fail (GST_IS_MESSAGE (message));

  1125   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_ERROR);

  1126 

  1127   error_gvalue = gst_structure_get_value (message->structure, "gerror");

  1128   g_return_if_fail (error_gvalue != NULL);

  1129   g_return_if_fail (G_VALUE_TYPE (error_gvalue) == GST_TYPE_G_ERROR);

  1130 

  1131   error_val = (GError *) g_value_get_boxed (error_gvalue);

  1132   if (error_val)

  1133     *gerror = g_error_copy (error_val);

  1134   else