gst/gstmessage.c

   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 #include "gstquark.h"
  61
  62
  63 typedef struct
  64 {
  65   GstMessage message;
  66
  67   GstStructure *structure;
  68 } GstMessageImpl;
  69
  70 #define GST_MESSAGE_STRUCTURE(m)  (((GstMessageImpl *)(m))->structure)
  71
  72 typedef struct
  73 {
  74   const gint type;
  75   const gchar *name;
  76   GQuark quark;
  77 } GstMessageQuarks;
  78
  79 static GstMessageQuarks message_quarks[] = {
  80   {GST_MESSAGE_UNKNOWN, "unknown", 0},
  81   {GST_MESSAGE_EOS, "eos", 0},
  82   {GST_MESSAGE_ERROR, "error", 0},
  83   {GST_MESSAGE_WARNING, "warning", 0},
  84   {GST_MESSAGE_INFO, "info", 0},
  85   {GST_MESSAGE_TAG, "tag", 0},
  86   {GST_MESSAGE_BUFFERING, "buffering", 0},
  87   {GST_MESSAGE_STATE_CHANGED, "state-changed", 0},
  88   {GST_MESSAGE_STATE_DIRTY, "state-dirty", 0},
  89   {GST_MESSAGE_STEP_DONE, "step-done", 0},
  90   {GST_MESSAGE_CLOCK_PROVIDE, "clock-provide", 0},
  91   {GST_MESSAGE_CLOCK_LOST, "clock-lost", 0},
  92   {GST_MESSAGE_NEW_CLOCK, "new-clock", 0},
  93   {GST_MESSAGE_STRUCTURE_CHANGE, "structure-change", 0},
  94   {GST_MESSAGE_STREAM_STATUS, "stream-status", 0},
  95   {GST_MESSAGE_APPLICATION, "application", 0},
  96   {GST_MESSAGE_ELEMENT, "element", 0},
  97   {GST_MESSAGE_SEGMENT_START, "segment-start", 0},
  98   {GST_MESSAGE_SEGMENT_DONE, "segment-done", 0},
  99   {GST_MESSAGE_DURATION, "duration", 0},
 100   {GST_MESSAGE_LATENCY, "latency", 0},
 101   {GST_MESSAGE_ASYNC_START, "async-start", 0},
 102   {GST_MESSAGE_ASYNC_DONE, "async-done", 0},
 103   {GST_MESSAGE_REQUEST_STATE, "request-state", 0},
 104   {GST_MESSAGE_STEP_START, "step-start", 0},
 105   {GST_MESSAGE_QOS, "qos", 0},
 106   {GST_MESSAGE_PROGRESS, "progress", 0},
 107   {GST_MESSAGE_TOC, "toc", 0},
 108   {0, NULL, 0}
 109 };
 110
 111 static GType _gst_message_type = 0;
 112 GST_DEFINE_MINI_OBJECT_TYPE (GstMessage, gst_message);
 113
 114 void
 115 _priv_gst_message_initialize (void)
 116 {
 117   gint i;
 118
 119   GST_CAT_INFO (GST_CAT_GST_INIT, "init messages");
 120
 121   /* the GstMiniObject types need to be class_ref'd once before it can be
 122    * done from multiple threads;
 123    * see http://bugzilla.gnome.org/show_bug.cgi?id=304551 */
 124   gst_message_get_type ();
 125
 126   for (i = 0; message_quarks[i].name; i++) {
 127     message_quarks[i].quark =
 128         g_quark_from_static_string (message_quarks[i].name);
 129   }
 130
 131   _gst_message_type = gst_message_get_type ();
 132 }
 133
 134 /**
 135  * gst_message_type_get_name:
 136  * @type: the message type
 137  *
 138  * Get a printable name for the given message type. Do not modify or free.
 139  *
 140  * Returns: a reference to the static name of the message.
 141  */
 142 const gchar *
 143 gst_message_type_get_name (GstMessageType type)
 144 {
 145   gint i;
 146
 147   for (i = 0; message_quarks[i].name; i++) {
 148     if (type == message_quarks[i].type)
 149       return message_quarks[i].name;
 150   }
 151   return "unknown";
 152 }
 153
 154 /**
 155  * gst_message_type_to_quark:
 156  * @type: the message type
 157  *
 158  * Get the unique quark for the given message type.
 159  *
 160  * Returns: the quark associated with the message type
 161  */
 162 GQuark
 163 gst_message_type_to_quark (GstMessageType type)
 164 {
 165   gint i;
 166
 167   for (i = 0; message_quarks[i].name; i++) {
 168     if (type == message_quarks[i].type)
 169       return message_quarks[i].quark;
 170   }
 171   return 0;
 172 }
 173
 174 static void
 175 _gst_message_free (GstMessage * message)
 176 {
 177   GstStructure *structure;
 178
 179   g_return_if_fail (message != NULL);
 180
 181   GST_CAT_LOG (GST_CAT_MESSAGE, "finalize message %p, %s from %s", message,
 182       GST_MESSAGE_TYPE_NAME (message), GST_MESSAGE_SRC_NAME (message));
 183
 184   if (GST_MESSAGE_SRC (message)) {
 185     gst_object_unref (GST_MESSAGE_SRC (message));
 186     GST_MESSAGE_SRC (message) = NULL;
 187   }
 188
 189   if (message->lock.p) {
 190     GST_MESSAGE_LOCK (message);
 191     GST_MESSAGE_SIGNAL (message);
 192     GST_MESSAGE_UNLOCK (message);
 193   }
 194
 195   structure = GST_MESSAGE_STRUCTURE (message);
 196   if (structure) {
 197     gst_structure_set_parent_refcount (structure, NULL);
 198     gst_structure_free (structure);
 199   }
 200
 201   g_slice_free1 (sizeof (GstMessageImpl), message);
 202 }
 203
 204 static void
 205 gst_message_init (GstMessageImpl * message, GstMessageType type,
 206     GstObject * src);
 207
 208 static GstMessage *
 209 _gst_message_copy (GstMessage * message)
 210 {
 211   GstMessageImpl *copy;
 212   GstStructure *structure;
 213
 214   GST_CAT_LOG (GST_CAT_MESSAGE, "copy message %p, %s from %s", message,
 215       GST_MESSAGE_TYPE_NAME (message),
 216       GST_OBJECT_NAME (GST_MESSAGE_SRC (message)));
 217
 218   copy = g_slice_new0 (GstMessageImpl);
 219
 220   gst_message_init (copy, GST_MESSAGE_TYPE (message),
 221       GST_MESSAGE_SRC (message));
 222
 223   GST_MESSAGE_TIMESTAMP (copy) = GST_MESSAGE_TIMESTAMP (message);
 224   GST_MESSAGE_SEQNUM (copy) = GST_MESSAGE_SEQNUM (message);
 225
 226   structure = GST_MESSAGE_STRUCTURE (message);
 227   if (structure) {
 228     GST_MESSAGE_STRUCTURE (copy) = gst_structure_copy (structure);
 229     gst_structure_set_parent_refcount (GST_MESSAGE_STRUCTURE (copy),
 230         &copy->message.mini_object.refcount);
 231   } else {
 232     GST_MESSAGE_STRUCTURE (copy) = NULL;
 233   }
 234
 235   return GST_MESSAGE_CAST (copy);
 236 }
 237
 238 static void
 239 gst_message_init (GstMessageImpl * message, GstMessageType type,
 240     GstObject * src)
 241 {
 242   gst_mini_object_init (GST_MINI_OBJECT_CAST (message), _gst_message_type,
 243       (GstMiniObjectCopyFunction) _gst_message_copy, NULL,
 244       (GstMiniObjectFreeFunction) _gst_message_free);
 245
 246   GST_MESSAGE_TYPE (message) = type;
 247   if (src)
 248     gst_object_ref (src);
 249   GST_MESSAGE_SRC (message) = src;
 250   GST_MESSAGE_TIMESTAMP (message) = GST_CLOCK_TIME_NONE;
 251   GST_MESSAGE_SEQNUM (message) = gst_util_seqnum_next ();
 252 }
 253
 254
 255 /**
 256  * gst_message_new_custom:
 257  * @type: The #GstMessageType to distinguish messages
 258  * @src: The object originating the message.
 259  * @structure: (transfer full): the structure for the message. The message
 260  *     will take ownership of the structure.
 261  *
 262  * Create a new custom-typed message. This can be used for anything not
 263  * handled by other message-specific functions to pass a message to the
 264  * app. The structure field can be NULL.
 265  *
 266  * Returns: (transfer full): The new message.
 267  *
 268  * MT safe.
 269  */
 270 GstMessage *
 271 gst_message_new_custom (GstMessageType type, GstObject * src,
 272     GstStructure * structure)
 273 {
 274   GstMessageImpl *message;
 275
 276   message = g_slice_new0 (GstMessageImpl);
 277
 278   GST_CAT_LOG (GST_CAT_MESSAGE, "source %s: creating new message %p %s",
 279       (src ? GST_OBJECT_NAME (src) : "NULL"), message,
 280       gst_message_type_get_name (type));
 281
 282   if (structure) {
 283     /* structure must not have a parent */
 284     if (!gst_structure_set_parent_refcount (structure,
 285             &message->message.mini_object.refcount))
 286       goto had_parent;
 287   }
 288   gst_message_init (message, type, src);
 289
 290   GST_MESSAGE_STRUCTURE (message) = structure;
 291
 292   return GST_MESSAGE_CAST (message);
 293
 294   /* ERRORS */
 295 had_parent:
 296   {
 297     g_slice_free1 (sizeof (GstMessageImpl), message);
 298     g_warning ("structure is already owned by another object");
 299     return NULL;
 300   }
 301 }
 302
 303 /**
 304  * gst_message_get_seqnum:
 305  * @message: A #GstMessage.
 306  *
 307  * Retrieve the sequence number of a message.
 308  *
 309  * Messages have ever-incrementing sequence numbers, which may also be set
 310  * explicitly via gst_message_set_seqnum(). Sequence numbers are typically used
 311  * to indicate that a message corresponds to some other set of messages or
 312  * events, for example a SEGMENT_DONE message corresponding to a SEEK event. It
 313  * is considered good practice to make this correspondence when possible, though
 314  * it is not required.
 315  *
 316  * Note that events and messages share the same sequence number incrementor;
 317  * two events or messages will never have the same sequence number unless
 318  * that correspondence was made explicitly.
 319  *
 320  * Returns: The message's sequence number.
 321  *
 322  * MT safe.
 323  *
 324  * Since: 0.10.22
 325  */
 326 guint32
 327 gst_message_get_seqnum (GstMessage * message)
 328 {
 329   g_return_val_if_fail (GST_IS_MESSAGE (message), -1);
 330
 331   return GST_MESSAGE_SEQNUM (message);
 332 }
 333
 334 /**
 335  * gst_message_set_seqnum:
 336  * @message: A #GstMessage.
 337  * @seqnum: A sequence number.
 338  *
 339  * Set the sequence number of a message.
 340  *
 341  * This function might be called by the creator of a message to indicate that
 342  * the message relates to other messages or events. See gst_message_get_seqnum()
 343  * for more information.
 344  *
 345  * MT safe.
 346  *
 347  * Since: 0.10.22
 348  */
 349 void
 350 gst_message_set_seqnum (GstMessage * message, guint32 seqnum)
 351 {
 352   g_return_if_fail (GST_IS_MESSAGE (message));
 353
 354   GST_MESSAGE_SEQNUM (message) = seqnum;
 355 }
 356
 357 /**
 358  * gst_message_new_eos:
 359  * @src: (transfer none): The object originating the message.
 360  *
 361  * Create a new eos message. This message is generated and posted in
 362  * the sink elements of a GstBin. The bin will only forward the EOS
 363  * message to the application if all sinks have posted an EOS message.
 364  *
 365  * Returns: (transfer full): The new eos message.
 366  *
 367  * MT safe.
 368  */
 369 GstMessage *
 370 gst_message_new_eos (GstObject * src)
 371 {
 372   GstMessage *message;
 373
 374   message = gst_message_new_custom (GST_MESSAGE_EOS, src, NULL);
 375
 376   return message;
 377 }
 378
 379 /**
 380  * gst_message_new_error:
 381  * @src: (transfer none): The object originating the message.
 382  * @error: (transfer none): The GError for this message.
 383  * @debug: A debugging string.
 384  *
 385  * Create a new error message. The message will copy @error and
 386  * @debug. This message is posted by element when a fatal event
 387  * occured. The pipeline will probably (partially) stop. The application
 388  * receiving this message should stop the pipeline.
 389  *
 390  * Returns: (transfer full): the new error message.
 391  *
 392  * MT safe.
 393  */
 394 GstMessage *
 395 gst_message_new_error (GstObject * src, GError * error, const gchar * debug)
 396 {
 397   GstMessage *message;
 398   GstStructure *structure;
 399
 400   structure = gst_structure_new_id (GST_QUARK (MESSAGE_ERROR),
 401       GST_QUARK (GERROR), G_TYPE_ERROR, error,
 402       GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
 403   message = gst_message_new_custom (GST_MESSAGE_ERROR, src, structure);
 404
 405   return message;
 406 }
 407
 408 /**
 409  * gst_message_new_warning:
 410  * @src: (transfer none): The object originating the message.
 411  * @error: (transfer none): The GError for this message.
 412  * @debug: A debugging string.
 413  *
 414  * Create a new warning message. The message will make copies of @error and
 415  * @debug.
 416  *
 417  * Returns: (transfer full): The new warning message.
 418  *
 419  * MT safe.
 420  */
 421 GstMessage *
 422 gst_message_new_warning (GstObject * src, GError * error, const gchar * debug)
 423 {
 424   GstMessage *message;
 425   GstStructure *structure;
 426
 427   structure = gst_structure_new_id (GST_QUARK (MESSAGE_WARNING),
 428       GST_QUARK (GERROR), G_TYPE_ERROR, error,
 429       GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
 430   message = gst_message_new_custom (GST_MESSAGE_WARNING, src, structure);
 431
 432   return message;
 433 }
 434
 435 /**
 436  * gst_message_new_info:
 437  * @src: (transfer none): The object originating the message.
 438  * @error: (transfer none): The GError for this message.
 439  * @debug: A debugging string.
 440  *
 441  * Create a new info message. The message will make copies of @error and
 442  * @debug.
 443  *
 444  * MT safe.
 445  *
 446  * Returns: (transfer full): the new info message.
 447  *
 448  * Since: 0.10.12
 449  */
 450 GstMessage *
 451 gst_message_new_info (GstObject * src, GError * error, const gchar * debug)
 452 {
 453   GstMessage *message;
 454   GstStructure *structure;
 455
 456   structure = gst_structure_new_id (GST_QUARK (MESSAGE_INFO),
 457       GST_QUARK (GERROR), G_TYPE_ERROR, error,
 458       GST_QUARK (DEBUG), G_TYPE_STRING, debug, NULL);
 459   message = gst_message_new_custom (GST_MESSAGE_INFO, src, structure);
 460
 461   return message;
 462 }
 463
 464 /**
 465  * gst_message_new_tag:
 466  * @src: (transfer none): The object originating the message.
 467  * @tag_list: (transfer full): the tag list for the message.
 468  *
 469  * Create a new tag message. The message will take ownership of the tag list.
 470  * The message is posted by elements that discovered a new taglist.
 471  *
 472  * Returns: (transfer full): the new tag message.
 473  *
 474  * MT safe.
 475  */
 476 GstMessage *
 477 gst_message_new_tag (GstObject * src, GstTagList * tag_list)
 478 {
 479   GstStructure *s;
 480   GstMessage *message;
 481   GValue val = G_VALUE_INIT;
 482
 483   g_return_val_if_fail (GST_IS_TAG_LIST (tag_list), NULL);
 484
 485   s = gst_structure_new_id_empty (GST_QUARK (MESSAGE_TAG));
 486   g_value_init (&val, GST_TYPE_TAG_LIST);
 487   g_value_take_boxed (&val, tag_list);
 488   gst_structure_id_take_value (s, GST_QUARK (TAGLIST), &val);
 489   message = gst_message_new_custom (GST_MESSAGE_TAG, src, s);
 490   return message;
 491 }
 492
 493 /**
 494  * gst_message_new_buffering:
 495  * @src: (transfer none): The object originating the message.
 496  * @percent: The buffering percent
 497  *
 498  * Create a new buffering message. This message can be posted by an element that
 499  * needs to buffer data before it can continue processing. @percent should be a
 500  * value between 0 and 100. A value of 100 means that the buffering completed.
 501  *
 502  * When @percent is < 100 the application should PAUSE a PLAYING pipeline. When
 503  * @percent is 100, the application can set the pipeline (back) to PLAYING.
 504  * The application must be prepared to receive BUFFERING messages in the
 505  * PREROLLING state and may only set the pipeline to PLAYING after receiving a
 506  * message with @percent set to 100, which can happen after the pipeline
 507  * completed prerolling.
 508  *
 509  * MT safe.
 510  *
 511  * Returns: (transfer full): The new buffering message.
 512  *
 513  * Since: 0.10.11
 514  */
 515 GstMessage *
 516 gst_message_new_buffering (GstObject * src, gint percent)
 517 {
 518   GstMessage *message;
 519   GstStructure *structure;
 520
 521   g_return_val_if_fail (percent >= 0 && percent <= 100, NULL);
 522
 523   structure = gst_structure_new_id (GST_QUARK (MESSAGE_BUFFERING),
 524       GST_QUARK (BUFFER_PERCENT), G_TYPE_INT, percent,
 525       GST_QUARK (BUFFERING_MODE), GST_TYPE_BUFFERING_MODE, GST_BUFFERING_STREAM,
 526       GST_QUARK (AVG_IN_RATE), G_TYPE_INT, -1,
 527       GST_QUARK (AVG_OUT_RATE), G_TYPE_INT, -1,
 528       GST_QUARK (BUFFERING_LEFT), G_TYPE_INT64, G_GINT64_CONSTANT (-1),
 529       GST_QUARK (ESTIMATED_TOTAL), G_TYPE_INT64, G_GINT64_CONSTANT (-1), NULL);
 530   message = gst_message_new_custom (GST_MESSAGE_BUFFERING, src, structure);
 531
 532   return message;
 533 }
 534
 535 /**
 536  * gst_message_new_state_changed:
 537  * @src: (transfer none): the object originating the message
 538  * @oldstate: the previous state
 539  * @newstate: the new (current) state
 540  * @pending: the pending (target) state
 541  *
 542  * Create a state change message. This message is posted whenever an element
 543  * changed its state.
 544  *
 545  * Returns: (transfer full): the new state change message.
 546  *
 547  * MT safe.
 548  */
 549 GstMessage *
 550 gst_message_new_state_changed (GstObject * src,
 551     GstState oldstate, GstState newstate, GstState pending)
 552 {
 553   GstMessage *message;
 554   GstStructure *structure;
 555
 556   structure = gst_structure_new_id (GST_QUARK (MESSAGE_STATE_CHANGED),
 557       GST_QUARK (OLD_STATE), GST_TYPE_STATE, (gint) oldstate,
 558       GST_QUARK (NEW_STATE), GST_TYPE_STATE, (gint) newstate,
 559       GST_QUARK (PENDING_STATE), GST_TYPE_STATE, (gint) pending, NULL);
 560   message = gst_message_new_custom (GST_MESSAGE_STATE_CHANGED, src, structure);
 561
 562   return message;
 563 }
 564
 565 /**
 566  * gst_message_new_state_dirty:
 567  * @src: (transfer none): the object originating the message
 568  *
 569  * Create a state dirty message. This message is posted whenever an element
 570  * changed its state asynchronously and is used internally to update the
 571  * states of container objects.
 572  *
 573  * Returns: (transfer full): the new state dirty message.
 574  *
 575  * MT safe.
 576  */
 577 GstMessage *
 578 gst_message_new_state_dirty (GstObject * src)
 579 {
 580   GstMessage *message;
 581
 582   message = gst_message_new_custom (GST_MESSAGE_STATE_DIRTY, src, NULL);
 583
 584   return message;
 585 }
 586
 587 /**
 588  * gst_message_new_clock_provide:
 589  * @src: (transfer none): the object originating the message.
 590  * @clock: (transfer none): the clock it provides
 591  * @ready: TRUE if the sender can provide a clock
 592  *
 593  * Create a clock provide message. This message is posted whenever an
 594  * element is ready to provide a clock or lost its ability to provide
 595  * a clock (maybe because it paused or became EOS).
 596  *
 597  * This message is mainly used internally to manage the clock
 598  * selection.
 599  *
 600  * Returns: (transfer full): the new provide clock message.
 601  *
 602  * MT safe.
 603  */
 604 GstMessage *
 605 gst_message_new_clock_provide (GstObject * src, GstClock * clock,
 606     gboolean ready)
 607 {
 608   GstMessage *message;
 609   GstStructure *structure;
 610
 611   structure = gst_structure_new_id (GST_QUARK (MESSAGE_CLOCK_PROVIDE),
 612       GST_QUARK (CLOCK), GST_TYPE_CLOCK, clock,
 613       GST_QUARK (READY), G_TYPE_BOOLEAN, ready, NULL);
 614   message = gst_message_new_custom (GST_MESSAGE_CLOCK_PROVIDE, src, structure);
 615
 616   return message;
 617 }
 618
 619 /**
 620  * gst_message_new_clock_lost:
 621  * @src: (transfer none): the object originating the message.
 622  * @clock: (transfer none): the clock that was lost
 623  *
 624  * Create a clock lost message. This message is posted whenever the
 625  * clock is not valid anymore.
 626  *
 627  * If this message is posted by the pipeline, the pipeline will
 628  * select a new clock again when it goes to PLAYING. It might therefore
 629  * be needed to set the pipeline to PAUSED and PLAYING again.
 630  *
 631  * Returns: (transfer full): The new clock lost message.
 632  *
 633  * MT safe.
 634  */
 635 GstMessage *
 636 gst_message_new_clock_lost (GstObject * src, GstClock * clock)
 637 {
 638   GstMessage *message;
 639   GstStructure *structure;
 640
 641   structure = gst_structure_new_id (GST_QUARK (MESSAGE_CLOCK_LOST),
 642       GST_QUARK (CLOCK), GST_TYPE_CLOCK, clock, NULL);
 643   message = gst_message_new_custom (GST_MESSAGE_CLOCK_LOST, src, structure);
 644
 645   return message;
 646 }
 647
 648 /**
 649  * gst_message_new_new_clock:
 650  * @src: (transfer none): The object originating the message.
 651  * @clock: (transfer none): the new selected clock
 652  *
 653  * Create a new clock message. This message is posted whenever the
 654  * pipeline selectes a new clock for the pipeline.
 655  *
 656  * Returns: (transfer full): The new new clock message.
 657  *
 658  * MT safe.
 659  */
 660 GstMessage *
 661 gst_message_new_new_clock (GstObject * src, GstClock * clock)
 662 {
 663   GstMessage *message;
 664   GstStructure *structure;
 665
 666   structure = gst_structure_new_id (GST_QUARK (MESSAGE_NEW_CLOCK),
 667       GST_QUARK (CLOCK), GST_TYPE_CLOCK, clock, NULL);
 668   message = gst_message_new_custom (GST_MESSAGE_NEW_CLOCK, src, structure);
 669
 670   return message;
 671 }
 672
 673 /**
 674  * gst_message_new_structure_change:
 675  * @src: (transfer none): The object originating the message.
 676  * @type: The change type.
 677  * @owner: (transfer none): The owner element of @src.
 678  * @busy: Whether the structure change is busy.
 679  *
 680  * Create a new structure change message. This message is posted when the
 681  * structure of a pipeline is in the process of being changed, for example
 682  * when pads are linked or unlinked.
 683  *
 684  * @src should be the sinkpad that unlinked or linked.
 685  *
 686  * Returns: (transfer full): the new structure change message.
 687  *
 688  * MT safe.
 689  *
 690  * Since: 0.10.22.
 691  */
 692 GstMessage *
 693 gst_message_new_structure_change (GstObject * src, GstStructureChangeType type,
 694     GstElement * owner, gboolean busy)
 695 {
 696   GstMessage *message;
 697   GstStructure *structure;
 698
 699   g_return_val_if_fail (GST_IS_PAD (src), NULL);
 700   /* g_return_val_if_fail (GST_PAD_DIRECTION (src) == GST_PAD_SINK, NULL); */
 701   g_return_val_if_fail (GST_IS_ELEMENT (owner), NULL);
 702
 703   structure = gst_structure_new_id (GST_QUARK (MESSAGE_STRUCTURE_CHANGE),
 704       GST_QUARK (TYPE), GST_TYPE_STRUCTURE_CHANGE_TYPE, type,
 705       GST_QUARK (OWNER), GST_TYPE_ELEMENT, owner,
 706       GST_QUARK (BUSY), G_TYPE_BOOLEAN, busy, NULL);
 707
 708   message = gst_message_new_custom (GST_MESSAGE_STRUCTURE_CHANGE, src,
 709       structure);
 710
 711   return message;
 712 }
 713
 714 /**
 715  * gst_message_new_segment_start:
 716  * @src: (transfer none): The object originating the message.
 717  * @format: The format of the position being played
 718  * @position: The position of the segment being played
 719  *
 720  * Create a new segment message. This message is posted by elements that
 721  * start playback of a segment as a result of a segment seek. This message
 722  * is not received by the application but is used for maintenance reasons in
 723  * container elements.
 724  *
 725  * Returns: (transfer full): the new segment start message.
 726  *
 727  * MT safe.
 728  */
 729 GstMessage *
 730 gst_message_new_segment_start (GstObject * src, GstFormat format,
 731     gint64 position)
 732 {
 733   GstMessage *message;
 734   GstStructure *structure;
 735
 736   structure = gst_structure_new_id (GST_QUARK (MESSAGE_SEGMENT_START),
 737       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 738       GST_QUARK (POSITION), G_TYPE_INT64, position, NULL);
 739   message = gst_message_new_custom (GST_MESSAGE_SEGMENT_START, src, structure);
 740
 741   return message;
 742 }
 743
 744 /**
 745  * gst_message_new_segment_done:
 746  * @src: (transfer none): the object originating the message.
 747  * @format: The format of the position being done
 748  * @position: The position of the segment being done
 749  *
 750  * Create a new segment done message. This message is posted by elements that
 751  * finish playback of a segment as a result of a segment seek. This message
 752  * is received by the application after all elements that posted a segment_start
 753  * have posted the segment_done.
 754  *
 755  * Returns: (transfer full): the new segment done message.
 756  *
 757  * MT safe.
 758  */
 759 GstMessage *
 760 gst_message_new_segment_done (GstObject * src, GstFormat format,
 761     gint64 position)
 762 {
 763   GstMessage *message;
 764   GstStructure *structure;
 765
 766   structure = gst_structure_new_id (GST_QUARK (MESSAGE_SEGMENT_DONE),
 767       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 768       GST_QUARK (POSITION), G_TYPE_INT64, position, NULL);
 769   message = gst_message_new_custom (GST_MESSAGE_SEGMENT_DONE, src, structure);
 770
 771   return message;
 772 }
 773
 774 /**
 775  * gst_message_new_application:
 776  * @src: (transfer none): the object originating the message.
 777  * @structure: (transfer full): the structure for the message. The message
 778  *     will take ownership of the structure.
 779  *
 780  * Create a new application-typed message. GStreamer will never create these
 781  * messages; they are a gift from us to you. Enjoy.
 782  *
 783  * Returns: (transfer full): The new application message.
 784  *
 785  * MT safe.
 786  */
 787 GstMessage *
 788 gst_message_new_application (GstObject * src, GstStructure * structure)
 789 {
 790   return gst_message_new_custom (GST_MESSAGE_APPLICATION, src, structure);
 791 }
 792
 793 /**
 794  * gst_message_new_element:
 795  * @src: (transfer none): The object originating the message.
 796  * @structure: (transfer full): The structure for the message. The message
 797  *     will take ownership of the structure.
 798  *
 799  * Create a new element-specific message. This is meant as a generic way of
 800  * allowing one-way communication from an element to an application, for example
 801  * "the firewire cable was unplugged". The format of the message should be
 802  * documented in the element's documentation. The structure field can be NULL.
 803  *
 804  * Returns: (transfer full): The new element message.
 805  *
 806  * MT safe.
 807  */
 808 GstMessage *
 809 gst_message_new_element (GstObject * src, GstStructure * structure)
 810 {
 811   return gst_message_new_custom (GST_MESSAGE_ELEMENT, src, structure);
 812 }
 813
 814 /**
 815  * gst_message_new_duration:
 816  * @src: (transfer none): The object originating the message.
 817  * @format: The format of the duration
 818  * @duration: The new duration
 819  *
 820  * Create a new duration message. This message is posted by elements that
 821  * know the duration of a stream in a specific format. This message
 822  * is received by bins and is used to calculate the total duration of a
 823  * pipeline. Elements may post a duration message with a duration of
 824  * GST_CLOCK_TIME_NONE to indicate that the duration has changed and the
 825  * cached duration should be discarded. The new duration can then be
 826  * retrieved via a query.
 827  *
 828  * Returns: (transfer full): The new duration message.
 829  *
 830  * MT safe.
 831  */
 832 GstMessage *
 833 gst_message_new_duration (GstObject * src, GstFormat format, gint64 duration)
 834 {
 835   GstMessage *message;
 836   GstStructure *structure;
 837
 838   structure = gst_structure_new_id (GST_QUARK (MESSAGE_DURATION),
 839       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 840       GST_QUARK (DURATION), G_TYPE_INT64, duration, NULL);
 841   message = gst_message_new_custom (GST_MESSAGE_DURATION, src, structure);
 842
 843   return message;
 844 }
 845
 846 /**
 847  * gst_message_new_async_start:
 848  * @src: (transfer none): The object originating the message.
 849  *
 850  * This message is posted by elements when they start an ASYNC state change.
 851  *
 852  * Returns: (transfer full): The new async_start message.
 853  *
 854  * MT safe.
 855  */
 856 GstMessage *
 857 gst_message_new_async_start (GstObject * src)
 858 {
 859   GstMessage *message;
 860
 861   message = gst_message_new_custom (GST_MESSAGE_ASYNC_START, src, NULL);
 862
 863   return message;
 864 }
 865
 866 /**
 867  * gst_message_new_async_done:
 868  * @src: (transfer none): The object originating the message.
 869  * @running_time: the desired running_time
 870  *
 871  * The message is posted when elements completed an ASYNC state change.
 872  * @running_time contains the time of the desired running_time when this
 873  * elements goes to PLAYING. A value of #GST_CLOCK_TIME_NONE for @running_time
 874  * means that the element has no clock interaction and thus doesn't care about
 875  * the running_time of the pipeline.
 876  *
 877  * Returns: (transfer full): The new async_done message.
 878  *
 879  * MT safe.
 880  */
 881 GstMessage *
 882 gst_message_new_async_done (GstObject * src, GstClockTime running_time)
 883 {
 884   GstMessage *message;
 885   GstStructure *structure;
 886
 887   structure = gst_structure_new_id (GST_QUARK (MESSAGE_ASYNC_DONE),
 888       GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time, NULL);
 889   message = gst_message_new_custom (GST_MESSAGE_ASYNC_DONE, src, structure);
 890
 891   return message;
 892 }
 893
 894 /**
 895  * gst_message_new_latency:
 896  * @src: (transfer none): The object originating the message.
 897  *
 898  * This message can be posted by elements when their latency requirements have
 899  * changed.
 900  *
 901  * Returns: (transfer full): The new latency message.
 902  *
 903  * MT safe.
 904  *
 905  * Since: 0.10.12
 906  */
 907 GstMessage *
 908 gst_message_new_latency (GstObject * src)
 909 {
 910   GstMessage *message;
 911
 912   message = gst_message_new_custom (GST_MESSAGE_LATENCY, src, NULL);
 913
 914   return message;
 915 }
 916
 917 /**
 918  * gst_message_new_request_state:
 919  * @src: (transfer none): the object originating the message.
 920  * @state: The new requested state
 921  *
 922  * This message can be posted by elements when they want to have their state
 923  * changed. A typical use case would be an audio server that wants to pause the
 924  * pipeline because a higher priority stream is being played.
 925  *
 926  * Returns: (transfer full): the new requst state message.
 927  *
 928  * MT safe.
 929  *
 930  * Since: 0.10.23
 931  */
 932 GstMessage *
 933 gst_message_new_request_state (GstObject * src, GstState state)
 934 {
 935   GstMessage *message;
 936   GstStructure *structure;
 937
 938   structure = gst_structure_new_id (GST_QUARK (MESSAGE_REQUEST_STATE),
 939       GST_QUARK (NEW_STATE), GST_TYPE_STATE, (gint) state, NULL);
 940   message = gst_message_new_custom (GST_MESSAGE_REQUEST_STATE, src, structure);
 941
 942   return message;
 943 }
 944
 945 /**
 946  * gst_message_get_structure:
 947  * @message: The #GstMessage.
 948  *
 949  * Access the structure of the message.
 950  *
 951  * Returns: (transfer none): The structure of the message. The structure is
 952  * still owned by the message, which means that you should not free it and
 953  * that the pointer becomes invalid when you free the message.
 954  *
 955  * MT safe.
 956  */
 957 const GstStructure *
 958 gst_message_get_structure (GstMessage * message)
 959 {
 960   g_return_val_if_fail (GST_IS_MESSAGE (message), NULL);
 961
 962   return GST_MESSAGE_STRUCTURE (message);
 963 }
 964
 965 /**
 966  * gst_message_has_name:
 967  * @message: The #GstMessage.
 968  * @name: name to check
 969  *
 970  * Checks if @message has the given @name. This function is usually used to
 971  * check the name of a custom message.
 972  *
 973  * Returns: %TRUE if @name matches the name of the message structure.
 974  *
 975  * Since: 0.10.20
 976  */
 977 gboolean
 978 gst_message_has_name (GstMessage * message, const gchar * name)
 979 {
 980   GstStructure *structure;
 981
 982   g_return_val_if_fail (GST_IS_MESSAGE (message), FALSE);
 983
 984   structure = GST_MESSAGE_STRUCTURE (message);
 985   if (structure == NULL)
 986     return FALSE;
 987
 988   return gst_structure_has_name (structure, name);
 989 }
 990
 991 /**
 992  * gst_message_parse_tag:
 993  * @message: A valid #GstMessage of type GST_MESSAGE_TAG.
 994  * @tag_list: (out callee-allocates): return location for the tag-list.
 995  *
 996  * Extracts the tag list from the GstMessage. The tag list returned in the
 997  * output argument is a copy; the caller must free it when done.
 998  *
 999  * Typical usage of this function might be:
1000  * |[
1001  *   ...
1002  *   switch (GST_MESSAGE_TYPE (msg)) {
1003  *     case GST_MESSAGE_TAG: {
1004  *       GstTagList *tags = NULL;
1005  *
1006  *       gst_message_parse_tag (msg, &amp;tags);
1007  *       g_print ("Got tags from element %s\n", GST_OBJECT_NAME (msg->src));
1008  *       handle_tags (tags);
1009  *       gst_tag_list_unref (tags);
1010  *       break;
1011  *     }
1012  *     ...
1013  *   }
1014  *   ...
1015  * ]|
1016  *
1017  * MT safe.
1018  */
1019 void
1020 gst_message_parse_tag (GstMessage * message, GstTagList ** tag_list)
1021 {
1022   g_return_if_fail (GST_IS_MESSAGE (message));
1023   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_TAG);
1024   g_return_if_fail (tag_list != NULL);
1025
1026   gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
1027       GST_QUARK (TAGLIST), GST_TYPE_TAG_LIST, tag_list, NULL);
1028 }
1029
1030 /**
1031  * gst_message_parse_buffering:
1032  * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
1033  * @percent: (out) (allow-none): Return location for the percent.
1034  *
1035  * Extracts the buffering percent from the GstMessage. see also
1036  * gst_message_new_buffering().
1037  *
1038  * MT safe.
1039  *
1040  * Since: 0.10.11
1041  */
1042 void
1043 gst_message_parse_buffering (GstMessage * message, gint * percent)
1044 {
1045   g_return_if_fail (GST_IS_MESSAGE (message));
1046   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
1047
1048   if (percent)
1049     *percent =
1050         g_value_get_int (gst_structure_id_get_value (GST_MESSAGE_STRUCTURE
1051             (message), GST_QUARK (BUFFER_PERCENT)));
1052 }
1053
1054 /**
1055  * gst_message_set_buffering_stats:
1056  * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
1057  * @mode: a buffering mode
1058  * @avg_in: the average input rate
1059  * @avg_out: the average output rate
1060  * @buffering_left: amount of buffering time left in milliseconds
1061  *
1062  * Configures the buffering stats values in @message.
1063  *
1064  * Since: 0.10.20
1065  */
1066 void
1067 gst_message_set_buffering_stats (GstMessage * message, GstBufferingMode mode,
1068     gint avg_in, gint avg_out, gint64 buffering_left)
1069 {
1070   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
1071
1072   gst_structure_id_set (GST_MESSAGE_STRUCTURE (message),
1073       GST_QUARK (BUFFERING_MODE), GST_TYPE_BUFFERING_MODE, mode,
1074       GST_QUARK (AVG_IN_RATE), G_TYPE_INT, avg_in,
1075       GST_QUARK (AVG_OUT_RATE), G_TYPE_INT, avg_out,
1076       GST_QUARK (BUFFERING_LEFT), G_TYPE_INT64, buffering_left, NULL);
1077 }
1078
1079 /**
1080  * gst_message_parse_buffering_stats:
1081  * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
1082  * @mode: (out) (allow-none): a buffering mode, or NULL
1083  * @avg_in: (out) (allow-none): the average input rate, or NULL
1084  * @avg_out: (out) (allow-none): the average output rate, or NULL
1085  * @buffering_left: (out) (allow-none): amount of buffering time left in
1086  *     milliseconds, or NULL
1087  *
1088  * Extracts the buffering stats values from @message.
1089  *
1090  * Since: 0.10.20
1091  */
1092 void
1093 gst_message_parse_buffering_stats (GstMessage * message,
1094     GstBufferingMode * mode, gint * avg_in, gint * avg_out,
1095     gint64 * buffering_left)
1096 {
1097   GstStructure *structure;
1098
1099   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
1100
1101   structure = GST_MESSAGE_STRUCTURE (message);
1102   if (mode)
1103     *mode = (GstBufferingMode)
1104         g_value_get_enum (gst_structure_id_get_value (structure,
1105             GST_QUARK (BUFFERING_MODE)));
1106   if (avg_in)
1107     *avg_in = g_value_get_int (gst_structure_id_get_value (structure,
1108             GST_QUARK (AVG_IN_RATE)));
1109   if (avg_out)
1110     *avg_out = g_value_get_int (gst_structure_id_get_value (structure,
1111             GST_QUARK (AVG_OUT_RATE)));
1112   if (buffering_left)
1113     *buffering_left =
1114         g_value_get_int64 (gst_structure_id_get_value (structure,
1115             GST_QUARK (BUFFERING_LEFT)));
1116 }
1117
1118 /**
1119  * gst_message_parse_state_changed:
1120  * @message: a valid #GstMessage of type GST_MESSAGE_STATE_CHANGED
1121  * @oldstate: (out) (allow-none): the previous state, or NULL
1122  * @newstate: (out) (allow-none): the new (current) state, or NULL
1123  * @pending: (out) (allow-none): the pending (target) state, or NULL
1124  *
1125  * Extracts the old and new states from the GstMessage.
1126  *
1127  * Typical usage of this function might be:
1128  * |[
1129  *   ...
1130  *   switch (GST_MESSAGE_TYPE (msg)) {
1131  *     case GST_MESSAGE_STATE_CHANGED: {
1132  *       GstState old_state, new_state;
1133  *
1134  *       gst_message_parse_state_changed (msg, &amp;old_state, &amp;new_state, NULL);
1135  *       g_print ("Element %s changed state from %s to %s.\n",
1136  *           GST_OBJECT_NAME (msg->src),
1137  *           gst_element_state_get_name (old_state),
1138  *           gst_element_state_get_name (new_state));
1139  *       break;
1140  *     }
1141  *     ...
1142  *   }
1143  *   ...
1144  * ]|
1145  *
1146  * MT safe.
1147  */
1148 void
1149 gst_message_parse_state_changed (GstMessage * message,
1150     GstState * oldstate, GstState * newstate, GstState * pending)
1151 {
1152   GstStructure *structure;
1153
1154   g_return_if_fail (GST_IS_MESSAGE (message));
1155   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STATE_CHANGED);
1156
1157   structure = GST_MESSAGE_STRUCTURE (message);
1158   if (oldstate)
1159     *oldstate = (GstState)
1160         g_value_get_enum (gst_structure_id_get_value (structure,
1161             GST_QUARK (OLD_STATE)));
1162   if (newstate)
1163     *newstate = (GstState)
1164         g_value_get_enum (gst_structure_id_get_value (structure,
1165             GST_QUARK (NEW_STATE)));
1166   if (pending)
1167     *pending = (GstState)
1168         g_value_get_enum (gst_structure_id_get_value (structure,
1169             GST_QUARK (PENDING_STATE)));
1170 }
1171
1172 /**
1173  * gst_message_parse_clock_provide:
1174  * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_PROVIDE.
1175  * @clock: (out) (allow-none) (transfer none): a pointer to  hold a clock
1176  *     object, or NULL
1177  * @ready: (out) (allow-none): a pointer to hold the ready flag, or NULL
1178  *
1179  * Extracts the clock and ready flag from the GstMessage.
1180  * The clock object returned remains valid until the message is freed.
1181  *
1182  * MT safe.
1183  */
1184 void
1185 gst_message_parse_clock_provide (GstMessage * message, GstClock ** clock,
1186     gboolean * ready)
1187 {
1188   const GValue *clock_gvalue;
1189   GstStructure *structure;
1190
1191   g_return_if_fail (GST_IS_MESSAGE (message));
1192   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_CLOCK_PROVIDE);
1193
1194   structure = GST_MESSAGE_STRUCTURE (message);
1195   clock_gvalue = gst_structure_id_get_value (structure, GST_QUARK (CLOCK));
1196   g_return_if_fail (clock_gvalue != NULL);
1197   g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);
1198
1199   if (ready)
1200     *ready =
1201         g_value_get_boolean (gst_structure_id_get_value (structure,
1202             GST_QUARK (READY)));
1203   if (clock)
1204     *clock = (GstClock *) g_value_get_object (clock_gvalue);
1205 }
1206
1207 /**
1208  * gst_message_parse_clock_lost:
1209  * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_LOST.
1210  * @clock: (out) (allow-none) (transfer none): a pointer to hold the lost clock
1211  *
1212  * Extracts the lost clock from the GstMessage.
1213  * The clock object returned remains valid until the message is freed.
1214  *
1215  * MT safe.
1216  */
1217 void
1218 gst_message_parse_clock_lost (GstMessage * message, GstClock ** clock)
1219 {
1220   const GValue *clock_gvalue;
1221   GstStructure *structure;
1222
1223   g_return_if_fail (GST_IS_MESSAGE (message));
1224   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_CLOCK_LOST);
1225
1226   structure = GST_MESSAGE_STRUCTURE (message);
1227   clock_gvalue = gst_structure_id_get_value (structure, GST_QUARK (CLOCK));
1228   g_return_if_fail (clock_gvalue != NULL);
1229   g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);
1230
1231   if (clock)
1232     *clock = (GstClock *) g_value_get_object (clock_gvalue);
1233 }
1234
1235 /**
1236  * gst_message_parse_new_clock:
1237  * @message: A valid #GstMessage of type GST_MESSAGE_NEW_CLOCK.
1238  * @clock: (out) (allow-none) (transfer none): a pointer to hold the selected
1239  *     new clock
1240  *
1241  * Extracts the new clock from the GstMessage.
1242  * The clock object returned remains valid until the message is freed.
1243  *
1244  * MT safe.
1245  */
1246 void
1247 gst_message_parse_new_clock (GstMessage * message, GstClock ** clock)
1248 {
1249   const GValue *clock_gvalue;
1250   GstStructure *structure;
1251
1252   g_return_if_fail (GST_IS_MESSAGE (message));
1253   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_NEW_CLOCK);
1254
1255   structure = GST_MESSAGE_STRUCTURE (message);
1256   clock_gvalue = gst_structure_id_get_value (structure, GST_QUARK (CLOCK));
1257   g_return_if_fail (clock_gvalue != NULL);
1258   g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);
1259
1260   if (clock)
1261     *clock = (GstClock *) g_value_get_object (clock_gvalue);
1262 }
1263
1264 /**
1265  * gst_message_parse_structure_change:
1266  * @message: A valid #GstMessage of type GST_MESSAGE_STRUCTURE_CHANGE.
1267  * @type: (out): A pointer to hold the change type
1268  * @owner: (out) (allow-none) (transfer none): The owner element of the
1269  *     message source
1270  * @busy: (out) (allow-none): a pointer to hold whether the change is in
1271  *     progress or has been completed
1272  *
1273  * Extracts the change type and completion status from the GstMessage.
1274  *
1275  * MT safe.
1276  *
1277  * Since: 0.10.22
1278  */
1279 void
1280 gst_message_parse_structure_change (GstMessage * message,
1281     GstStructureChangeType * type, GstElement ** owner, gboolean * busy)
1282 {
1283   const GValue *owner_gvalue;
1284   GstStructure *structure;
1285
1286   g_return_if_fail (GST_IS_MESSAGE (message));
1287   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STRUCTURE_CHANGE);
1288
1289   structure = GST_MESSAGE_STRUCTURE (message);
1290   owner_gvalue = gst_structure_id_get_value (structure, GST_QUARK (OWNER));
1291   g_return_if_fail (owner_gvalue != NULL);
1292   g_return_if_fail (G_VALUE_TYPE (owner_gvalue) == GST_TYPE_ELEMENT);
1293
1294   if (type)
1295     *type = (GstStructureChangeType)
1296         g_value_get_enum (gst_structure_id_get_value (structure,
1297             GST_QUARK (TYPE)));
1298   if (owner)
1299     *owner = (GstElement *) g_value_get_object (owner_gvalue);
1300   if (busy)
1301     *busy =
1302         g_value_get_boolean (gst_structure_id_get_value (structure,
1303             GST_QUARK (BUSY)));
1304 }
1305
1306 /**
1307  * gst_message_parse_error:
1308  * @message: A valid #GstMessage of type GST_MESSAGE_ERROR.
1309  * @gerror: (out) (allow-none) (transfer full): location for the GError
1310  * @debug: (out) (allow-none) (transfer full): location for the debug message,
1311  *     or NULL
1312  *
1313  * Extracts the GError and debug string from the GstMessage. The values returned
1314  * in the output arguments are copies; the caller must free them when done.
1315  *
1316  * Typical usage of this function might be:
1317  * |[
1318  *   ...
1319  *   switch (GST_MESSAGE_TYPE (msg)) {
1320  *     case GST_MESSAGE_ERROR: {
1321  *       GError *err = NULL;
1322  *       gchar *dbg_info = NULL;
1323  *
1324  *       gst_message_parse_error (msg, &amp;err, &amp;dbg_info);
1325  *       g_printerr ("ERROR from element %s: %s\n",
1326  *           GST_OBJECT_NAME (msg->src), err->message);
1327  *       g_printerr ("Debugging info: %s\n", (dbg_info) ? dbg_info : "none");
1328  *       g_error_free (err);
1329  *       g_free (dbg_info);
1330  *       break;
1331  *     }
1332  *     ...
1333  *   }
1334  *   ...
1335  * ]|
1336  *
1337  * MT safe.
1338  */
1339 void
1340 gst_message_parse_error (GstMessage * message, GError ** gerror, gchar ** debug)
1341 {
1342   const GValue *error_gvalue;
1343   GError *error_val;
1344   GstStructure *structure;
1345
1346   g_return_if_fail (GST_IS_MESSAGE (message));
1347   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_ERROR);
1348
1349   structure = GST_MESSAGE_STRUCTURE (message);
1350   error_gvalue = gst_structure_id_get_value (structure, GST_QUARK (GERROR));
1351   g_return_if_fail (error_gvalue != NULL);
1352   g_return_if_fail (G_VALUE_TYPE (error_gvalue) == G_TYPE_ERROR);
1353
1354   error_val = (GError *) g_value_get_boxed (error_gvalue);
1355   if (error_val)
1356     *gerror = g_error_copy (error_val);
1357   else
1358     *gerror = NULL;
1359
1360   if (debug)
1361     *debug =
1362         g_value_dup_string (gst_structure_id_get_value (structure,
1363             GST_QUARK (DEBUG)));
1364 }
1365
1366 /**
1367  * gst_message_parse_warning:
1368  * @message: A valid #GstMessage of type GST_MESSAGE_WARNING.
1369  * @gerror: (out) (allow-none) (transfer full): location for the GError
1370  * @debug: (out) (allow-none) (transfer full): location for the debug message,
1371  *     or NULL
1372  *
1373  * Extracts the GError and debug string from the GstMessage. The values returned
1374  * in the output arguments are copies; the caller must free them when done.
1375  *
1376  * MT safe.
1377  */
1378 void
1379 gst_message_parse_warning (GstMessage * message, GError ** gerror,
1380     gchar ** debug)
1381 {
1382   const GValue *error_gvalue;
1383   GError *error_val;
1384   GstStructure *structure;
1385
1386   g_return_if_fail (GST_IS_MESSAGE (message));
1387   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_WARNING);
1388
1389   structure = GST_MESSAGE_STRUCTURE (message);
1390   error_gvalue = gst_structure_id_get_value (structure, GST_QUARK (GERROR));
1391   g_return_if_fail (error_gvalue != NULL);
1392   g_return_if_fail (G_VALUE_TYPE (error_gvalue) == G_TYPE_ERROR);
1393
1394   error_val = (GError *) g_value_get_boxed (error_gvalue);
1395   if (error_val)
1396     *gerror = g_error_copy (error_val);
1397   else
1398     *gerror = NULL;
1399
1400   if (debug)
1401     *debug =
1402         g_value_dup_string (gst_structure_id_get_value (structure,
1403             GST_QUARK (DEBUG)));
1404 }
1405
1406 /**
1407  * gst_message_parse_info:
1408  * @message: A valid #GstMessage of type GST_MESSAGE_INFO.
1409  * @gerror: (out) (allow-none) (transfer full): location for the GError
1410  * @debug: (out) (allow-none) (transfer full): location for the debug message,
1411  *     or NULL
1412  *
1413  * Extracts the GError and debug string from the GstMessage. The values returned
1414  * in the output arguments are copies; the caller must free them when done.
1415  *
1416  * MT safe.
1417  *
1418  * Since: 0.10.12
1419  */
1420 void
1421 gst_message_parse_info (GstMessage * message, GError ** gerror, gchar ** debug)
1422 {
1423   const GValue *error_gvalue;
1424   GError *error_val;
1425   GstStructure *structure;
1426
1427   g_return_if_fail (GST_IS_MESSAGE (message));
1428   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_INFO);
1429
1430   structure = GST_MESSAGE_STRUCTURE (message);
1431   error_gvalue = gst_structure_id_get_value (structure, GST_QUARK (GERROR));
1432   g_return_if_fail (error_gvalue != NULL);
1433   g_return_if_fail (G_VALUE_TYPE (error_gvalue) == G_TYPE_ERROR);
1434
1435   error_val = (GError *) g_value_get_boxed (error_gvalue);
1436   if (error_val)
1437     *gerror = g_error_copy (error_val);
1438   else
1439     *gerror = NULL;
1440
1441   if (debug)
1442     *debug =
1443         g_value_dup_string (gst_structure_id_get_value (structure,
1444             GST_QUARK (DEBUG)));
1445 }
1446
1447 /**
1448  * gst_message_parse_segment_start:
1449  * @message: A valid #GstMessage of type GST_MESSAGE_SEGMENT_START.
1450  * @format: (out): Result location for the format, or NULL
1451  * @position: (out): Result location for the position, or NULL
1452  *
1453  * Extracts the position and format from the segment start message.
1454  *
1455  * MT safe.
1456  */
1457 void
1458 gst_message_parse_segment_start (GstMessage * message, GstFormat * format,
1459     gint64 * position)
1460 {
1461   GstStructure *structure;
1462
1463   g_return_if_fail (GST_IS_MESSAGE (message));
1464   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_SEGMENT_START);
1465
1466   structure = GST_MESSAGE_STRUCTURE (message);
1467   if (format)
1468     *format = (GstFormat)
1469         g_value_get_enum (gst_structure_id_get_value (structure,
1470             GST_QUARK (FORMAT)));
1471   if (position)
1472     *position =
1473         g_value_get_int64 (gst_structure_id_get_value (structure,
1474             GST_QUARK (POSITION)));
1475 }
1476
1477 /**
1478  * gst_message_parse_segment_done:
1479  * @message: A valid #GstMessage of type GST_MESSAGE_SEGMENT_DONE.
1480  * @format: (out): Result location for the format, or NULL
1481  * @position: (out): Result location for the position, or NULL
1482  *
1483  * Extracts the position and format from the segment start message.
1484  *
1485  * MT safe.
1486  */
1487 void
1488 gst_message_parse_segment_done (GstMessage * message, GstFormat * format,
1489     gint64 * position)
1490 {
1491   GstStructure *structure;
1492
1493   g_return_if_fail (GST_IS_MESSAGE (message));
1494   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_SEGMENT_DONE);
1495
1496   structure = GST_MESSAGE_STRUCTURE (message);
1497   if (format)
1498     *format = (GstFormat)
1499         g_value_get_enum (gst_structure_id_get_value (structure,
1500             GST_QUARK (FORMAT)));
1501   if (position)
1502     *position =
1503         g_value_get_int64 (gst_structure_id_get_value (structure,
1504             GST_QUARK (POSITION)));
1505 }
1506
1507 /**
1508  * gst_message_parse_duration:
1509  * @message: A valid #GstMessage of type GST_MESSAGE_DURATION.
1510  * @format: (out): Result location for the format, or NULL
1511  * @duration: (out): Result location for the duration, or NULL
1512  *
1513  * Extracts the duration and format from the duration message. The duration
1514  * might be GST_CLOCK_TIME_NONE, which indicates that the duration has
1515  * changed. Applications should always use a query to retrieve the duration
1516  * of a pipeline.
1517  *
1518  * MT safe.
1519  */
1520 void
1521 gst_message_parse_duration (GstMessage * message, GstFormat * format,
1522     gint64 * duration)
1523 {
1524   GstStructure *structure;
1525
1526   g_return_if_fail (GST_IS_MESSAGE (message));
1527   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_DURATION);
1528
1529   structure = GST_MESSAGE_STRUCTURE (message);
1530   if (format)
1531     *format = (GstFormat)
1532         g_value_get_enum (gst_structure_id_get_value (structure,
1533             GST_QUARK (FORMAT)));
1534   if (duration)
1535     *duration =
1536         g_value_get_int64 (gst_structure_id_get_value (structure,
1537             GST_QUARK (DURATION)));
1538 }
1539
1540 /**
1541  * gst_message_parse_async_done:
1542  * @message: A valid #GstMessage of type GST_MESSAGE_ASYNC_DONE.
1543  * @running_time: (out): Result location for the running_time or NULL
1544  *
1545  * Extract the running_time from the async_done message.
1546  *
1547  * MT safe.
1548  */
1549 void
1550 gst_message_parse_async_done (GstMessage * message, GstClockTime * running_time)
1551 {
1552   GstStructure *structure;
1553
1554   g_return_if_fail (GST_IS_MESSAGE (message));
1555   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_ASYNC_DONE);
1556
1557   structure = GST_MESSAGE_STRUCTURE (message);
1558   if (running_time)
1559     *running_time =
1560         g_value_get_uint64 (gst_structure_id_get_value (structure,
1561             GST_QUARK (RUNNING_TIME)));
1562 }
1563
1564 /**
1565  * gst_message_parse_request_state:
1566  * @message: A valid #GstMessage of type GST_MESSAGE_REQUEST_STATE.
1567  * @state: (out): Result location for the requested state or NULL
1568  *
1569  * Extract the requested state from the request_state message.
1570  *
1571  * MT safe.
1572  *
1573  * Since: 0.10.23
1574  */
1575 void
1576 gst_message_parse_request_state (GstMessage * message, GstState * state)
1577 {
1578   GstStructure *structure;
1579
1580   g_return_if_fail (GST_IS_MESSAGE (message));
1581   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_REQUEST_STATE);
1582
1583   structure = GST_MESSAGE_STRUCTURE (message);
1584   if (state)
1585     *state = (GstState)
1586         g_value_get_enum (gst_structure_id_get_value (structure,
1587             GST_QUARK (NEW_STATE)));
1588 }
1589
1590 /**
1591  * gst_message_new_stream_status:
1592  * @src: The object originating the message.
1593  * @type: The stream status type.
1594  * @owner: (transfer none): the owner element of @src.
1595  *
1596  * Create a new stream status message. This message is posted when a streaming
1597  * thread is created/destroyed or when the state changed.
1598  *
1599  * Returns: (transfer full): the new stream status message.
1600  *
1601  * MT safe.
1602  *
1603  * Since: 0.10.24.
1604  */
1605 GstMessage *
1606 gst_message_new_stream_status (GstObject * src, GstStreamStatusType type,
1607     GstElement * owner)
1608 {
1609   GstMessage *message;
1610   GstStructure *structure;
1611
1612   structure = gst_structure_new_id (GST_QUARK (MESSAGE_STREAM_STATUS),
1613       GST_QUARK (TYPE), GST_TYPE_STREAM_STATUS_TYPE, (gint) type,
1614       GST_QUARK (OWNER), GST_TYPE_ELEMENT, owner, NULL);
1615   message = gst_message_new_custom (GST_MESSAGE_STREAM_STATUS, src, structure);
1616
1617   return message;
1618 }
1619
1620 /**
1621  * gst_message_parse_stream_status:
1622  * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
1623  * @type: (out): A pointer to hold the status type
1624  * @owner: (out) (transfer none): The owner element of the message source
1625  *
1626  * Extracts the stream status type and owner the GstMessage. The returned
1627  * owner remains valid for as long as the reference to @message is valid and
1628  * should thus not be unreffed.
1629  *
1630  * MT safe.
1631  *
1632  * Since: 0.10.24.
1633  */
1634 void
1635 gst_message_parse_stream_status (GstMessage * message,
1636     GstStreamStatusType * type, GstElement ** owner)
1637 {
1638   const GValue *owner_gvalue;
1639   GstStructure *structure;
1640
1641   g_return_if_fail (GST_IS_MESSAGE (message));
1642   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_STATUS);
1643
1644   structure = GST_MESSAGE_STRUCTURE (message);
1645   owner_gvalue = gst_structure_id_get_value (structure, GST_QUARK (OWNER));
1646   g_return_if_fail (owner_gvalue != NULL);
1647
1648   if (type)
1649     *type = (GstStreamStatusType)
1650         g_value_get_enum (gst_structure_id_get_value (structure,
1651             GST_QUARK (TYPE)));
1652   if (owner)
1653     *owner = (GstElement *) g_value_get_object (owner_gvalue);
1654 }
1655
1656 /**
1657  * gst_message_set_stream_status_object:
1658  * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
1659  * @object: the object controlling the streaming
1660  *
1661  * Configures the object handling the streaming thread. This is usually a
1662  * GstTask object but other objects might be added in the future.
1663  *
1664  * Since: 0.10.24
1665  */
1666 void
1667 gst_message_set_stream_status_object (GstMessage * message,
1668     const GValue * object)
1669 {
1670   GstStructure *structure;
1671
1672   g_return_if_fail (GST_IS_MESSAGE (message));
1673   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_STATUS);
1674
1675   structure = GST_MESSAGE_STRUCTURE (message);
1676   gst_structure_id_set_value (structure, GST_QUARK (OBJECT), object);
1677 }
1678
1679 /**
1680  * gst_message_get_stream_status_object:
1681  * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
1682  *
1683  * Extracts the object managing the streaming thread from @message.
1684  *
1685  * Returns: a GValue containing the object that manages the streaming thread.
1686  * This object is usually of type GstTask but other types can be added in the
1687  * future. The object remains valid as long as @message is valid.
1688  *
1689  * Since: 0.10.24
1690  */
1691 const GValue *
1692 gst_message_get_stream_status_object (GstMessage * message)
1693 {
1694   const GValue *result;
1695   GstStructure *structure;
1696
1697   g_return_val_if_fail (GST_IS_MESSAGE (message), NULL);
1698   g_return_val_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_STATUS,
1699       NULL);
1700
1701   structure = GST_MESSAGE_STRUCTURE (message);
1702   result = gst_structure_id_get_value (structure, GST_QUARK (OBJECT));
1703
1704   return result;
1705 }
1706
1707 /**
1708  * gst_message_new_step_done:
1709  * @src: The object originating the message.
1710  * @format: the format of @amount
1711  * @amount: the amount of stepped data
1712  * @rate: the rate of the stepped amount
1713  * @flush: is this an flushing step
1714  * @intermediate: is this an intermediate step
1715  * @duration: the duration of the data
1716  * @eos: the step caused EOS
1717  *
1718  * This message is posted by elements when they complete a part, when @intermediate set
1719  * to TRUE, or a complete step operation.
1720  *
1721  * @duration will contain the amount of time (in GST_FORMAT_TIME) of the stepped
1722  * @amount of media in format @format.
1723  *
1724  * Returns: (transfer full): the new step_done message.
1725  *
1726  * MT safe.
1727  *
1728  * Since: 0.10.24
1729  */
1730 GstMessage *
1731 gst_message_new_step_done (GstObject * src, GstFormat format, guint64 amount,
1732     gdouble rate, gboolean flush, gboolean intermediate, guint64 duration,
1733     gboolean eos)
1734 {
1735   GstMessage *message;
1736   GstStructure *structure;
1737
1738   structure = gst_structure_new_id (GST_QUARK (MESSAGE_STEP_DONE),
1739       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1740       GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1741       GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1742       GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1743       GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate,
1744       GST_QUARK (DURATION), G_TYPE_UINT64, duration,
1745       GST_QUARK (EOS), G_TYPE_BOOLEAN, eos, NULL);
1746   message = gst_message_new_custom (GST_MESSAGE_STEP_DONE, src, structure);
1747
1748   return message;
1749 }
1750
1751 /**
1752  * gst_message_parse_step_done:
1753  * @message: A valid #GstMessage of type GST_MESSAGE_STEP_DONE.
1754  * @format: (out) (allow-none): result location for the format
1755  * @amount: (out) (allow-none): result location for the amount
1756  * @rate: (out) (allow-none): result location for the rate
1757  * @flush: (out) (allow-none): result location for the flush flag
1758  * @intermediate: (out) (allow-none): result location for the intermediate flag
1759  * @duration: (out) (allow-none): result location for the duration
1760  * @eos: (out) (allow-none): result location for the EOS flag
1761  *
1762  * Extract the values the step_done message.
1763  *
1764  * MT safe.
1765  *
1766  * Since: 0.10.24
1767  */
1768 void
1769 gst_message_parse_step_done (GstMessage * message, GstFormat * format,
1770     guint64 * amount, gdouble * rate, gboolean * flush, gboolean * intermediate,
1771     guint64 * duration, gboolean * eos)
1772 {
1773   GstStructure *structure;
1774
1775   g_return_if_fail (GST_IS_MESSAGE (message));
1776   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STEP_DONE);
1777
1778   structure = GST_MESSAGE_STRUCTURE (message);
1779   gst_structure_id_get (structure,
1780       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1781       GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1782       GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1783       GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1784       GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate,
1785       GST_QUARK (DURATION), G_TYPE_UINT64, duration,
1786       GST_QUARK (EOS), G_TYPE_BOOLEAN, eos, NULL);
1787 }
1788
1789 /**
1790  * gst_message_new_step_start:
1791  * @src: The object originating the message.
1792  * @active: if the step is active or queued
1793  * @format: the format of @amount
1794  * @amount: the amount of stepped data
1795  * @rate: the rate of the stepped amount
1796  * @flush: is this an flushing step
1797  * @intermediate: is this an intermediate step
1798  *
1799  * This message is posted by elements when they accept or activate a new step
1800  * event for @amount in @format.
1801  *
1802  * @active is set to FALSE when the element accepted the new step event and has
1803  * queued it for execution in the streaming threads.
1804  *
1805  * @active is set to TRUE when the element has activated the step operation and
1806  * is now ready to start executing the step in the streaming thread. After this
1807  * message is emited, the application can queue a new step operation in the
1808  * element.
1809  *
1810  * Returns: (transfer full): The new step_start message.
1811  *
1812  * MT safe.
1813  *
1814  * Since: 0.10.24
1815  */
1816 GstMessage *
1817 gst_message_new_step_start (GstObject * src, gboolean active, GstFormat format,
1818     guint64 amount, gdouble rate, gboolean flush, gboolean intermediate)
1819 {
1820   GstMessage *message;
1821   GstStructure *structure;
1822
1823   structure = gst_structure_new_id (GST_QUARK (MESSAGE_STEP_START),
1824       GST_QUARK (ACTIVE), G_TYPE_BOOLEAN, active,
1825       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1826       GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1827       GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1828       GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1829       GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate, NULL);
1830   message = gst_message_new_custom (GST_MESSAGE_STEP_START, src, structure);
1831
1832   return message;
1833 }
1834
1835 /**
1836  * gst_message_parse_step_start:
1837  * @message: A valid #GstMessage of type GST_MESSAGE_STEP_DONE.
1838  * @active: (out) (allow-none): result location for the active flag
1839  * @format: (out) (allow-none): result location for the format
1840  * @amount: (out) (allow-none): result location for the amount
1841  * @rate: (out) (allow-none): result location for the rate
1842  * @flush: (out) (allow-none): result location for the flush flag
1843  * @intermediate: (out) (allow-none): result location for the intermediate flag
1844  *
1845  * Extract the values from step_start message.
1846  *
1847  * MT safe.
1848  *
1849  * Since: 0.10.24
1850  */
1851 void
1852 gst_message_parse_step_start (GstMessage * message, gboolean * active,
1853     GstFormat * format, guint64 * amount, gdouble * rate, gboolean * flush,
1854     gboolean * intermediate)
1855 {
1856   GstStructure *structure;
1857
1858   g_return_if_fail (GST_IS_MESSAGE (message));
1859   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STEP_START);
1860
1861   structure = GST_MESSAGE_STRUCTURE (message);
1862   gst_structure_id_get (structure,
1863       GST_QUARK (ACTIVE), G_TYPE_BOOLEAN, active,
1864       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1865       GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1866       GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1867       GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1868       GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate, NULL);
1869 }
1870
1871 /**
1872  * gst_message_new_qos:
1873  * @src: The object originating the message.
1874  * @live: if the message was generated by a live element
1875  * @running_time: the running time of the buffer that generated the message
1876  * @stream_time: the stream time of the buffer that generated the message
1877  * @timestamp: the timestamps of the buffer that generated the message
1878  * @duration: the duration of the buffer that generated the message
1879  *
1880  * A QOS message is posted on the bus whenever an element decides to drop a
1881  * buffer because of QoS reasons or whenever it changes its processing strategy
1882  * because of QoS reasons (quality adjustments such as processing at lower
1883  * accuracy).
1884  *
1885  * This message can be posted by an element that performs synchronisation against the
1886  * clock (live) or it could be dropped by an element that performs QoS because of QOS
1887  * events received from a downstream element (!live).
1888  *
1889  * @running_time, @stream_time, @timestamp, @duration should be set to the
1890  * respective running-time, stream-time, timestamp and duration of the (dropped)
1891  * buffer that generated the QoS event. Values can be left to
1892  * GST_CLOCK_TIME_NONE when unknown.
1893  *
1894  * Returns: (transfer full): The new qos message.
1895  *
1896  * MT safe.
1897  *
1898  * Since: 0.10.29
1899  */
1900 GstMessage *
1901 gst_message_new_qos (GstObject * src, gboolean live, guint64 running_time,
1902     guint64 stream_time, guint64 timestamp, guint64 duration)
1903 {
1904   GstMessage *message;
1905   GstStructure *structure;
1906
1907   structure = gst_structure_new_id (GST_QUARK (MESSAGE_QOS),
1908       GST_QUARK (LIVE), G_TYPE_BOOLEAN, live,
1909       GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time,
1910       GST_QUARK (STREAM_TIME), G_TYPE_UINT64, stream_time,
1911       GST_QUARK (TIMESTAMP), G_TYPE_UINT64, timestamp,
1912       GST_QUARK (DURATION), G_TYPE_UINT64, duration,
1913       GST_QUARK (JITTER), G_TYPE_INT64, (gint64) 0,
1914       GST_QUARK (PROPORTION), G_TYPE_DOUBLE, (gdouble) 1.0,
1915       GST_QUARK (QUALITY), G_TYPE_INT, (gint) 1000000,
1916       GST_QUARK (FORMAT), GST_TYPE_FORMAT, GST_FORMAT_UNDEFINED,
1917       GST_QUARK (PROCESSED), G_TYPE_UINT64, (guint64) - 1,
1918       GST_QUARK (DROPPED), G_TYPE_UINT64, (guint64) - 1, NULL);
1919   message = gst_message_new_custom (GST_MESSAGE_QOS, src, structure);
1920
1921   return message;
1922 }
1923
1924 /**
1925  * gst_message_set_qos_values:
1926  * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
1927  * @jitter: The difference of the running-time against the deadline.
1928  * @proportion: Long term prediction of the ideal rate relative to normal rate
1929  * to get optimal quality.
1930  * @quality: An element dependent integer value that specifies the current
1931  * quality level of the element. The default maximum quality is 1000000.
1932  *
1933  * Set the QoS values that have been calculated/analysed from the QoS data
1934  *
1935  * MT safe.
1936  *
1937  * Since: 0.10.29
1938  */
1939 void
1940 gst_message_set_qos_values (GstMessage * message, gint64 jitter,
1941     gdouble proportion, gint quality)
1942 {
1943   GstStructure *structure;
1944
1945   g_return_if_fail (GST_IS_MESSAGE (message));
1946   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
1947
1948   structure = GST_MESSAGE_STRUCTURE (message);
1949   gst_structure_id_set (structure,
1950       GST_QUARK (JITTER), G_TYPE_INT64, jitter,
1951       GST_QUARK (PROPORTION), G_TYPE_DOUBLE, proportion,
1952       GST_QUARK (QUALITY), G_TYPE_INT, quality, NULL);
1953 }
1954
1955 /**
1956  * gst_message_set_qos_stats:
1957  * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
1958  * @format: Units of the 'processed' and 'dropped' fields. Video sinks and video
1959  * filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters
1960  * will likely use GST_FORMAT_DEFAULT (samples).
1961  * @processed: Total number of units correctly processed since the last state
1962  * change to READY or a flushing operation.
1963  * @dropped: Total number of units dropped since the last state change to READY
1964  * or a flushing operation.
1965  *
1966  * Set the QoS stats representing the history of the current continuous pipeline
1967  * playback period.
1968  *
1969  * When @format is @GST_FORMAT_UNDEFINED both @dropped and @processed are
1970  * invalid. Values of -1 for either @processed or @dropped mean unknown values.
1971  *
1972  * MT safe.
1973  *
1974  * Since: 0.10.29
1975  */
1976 void
1977 gst_message_set_qos_stats (GstMessage * message, GstFormat format,
1978     guint64 processed, guint64 dropped)
1979 {
1980   GstStructure *structure;
1981
1982   g_return_if_fail (GST_IS_MESSAGE (message));
1983   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
1984
1985   structure = GST_MESSAGE_STRUCTURE (message);
1986   gst_structure_id_set (structure,
1987       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1988       GST_QUARK (PROCESSED), G_TYPE_UINT64, processed,
1989       GST_QUARK (DROPPED), G_TYPE_UINT64, dropped, NULL);
1990 }
1991
1992 /**
1993  * gst_message_parse_qos:
1994  * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
1995  * @live: (out) (allow-none): if the message was generated by a live element
1996  * @running_time: (out) (allow-none): the running time of the buffer that
1997  *     generated the message
1998  * @stream_time: (out) (allow-none): the stream time of the buffer that
1999  *     generated the message
2000  * @timestamp: (out) (allow-none): the timestamps of the buffer that
2001  *     generated the message
2002  * @duration: (out) (allow-none): the duration of the buffer that
2003  *     generated the message
2004  *
2005  * Extract the timestamps and live status from the QoS message.
2006  *
2007  * The returned values give the running_time, stream_time, timestamp and
2008  * duration of the dropped buffer. Values of GST_CLOCK_TIME_NONE mean unknown
2009  * values.
2010  *
2011  * MT safe.
2012  *
2013  * Since: 0.10.29
2014  */
2015 void
2016 gst_message_parse_qos (GstMessage * message, gboolean * live,
2017     guint64 * running_time, guint64 * stream_time, guint64 * timestamp,
2018     guint64 * duration)
2019 {
2020   GstStructure *structure;
2021
2022   g_return_if_fail (GST_IS_MESSAGE (message));
2023   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
2024
2025   structure = GST_MESSAGE_STRUCTURE (message);
2026   gst_structure_id_get (structure,
2027       GST_QUARK (LIVE), G_TYPE_BOOLEAN, live,
2028       GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time,
2029       GST_QUARK (STREAM_TIME), G_TYPE_UINT64, stream_time,
2030       GST_QUARK (TIMESTAMP), G_TYPE_UINT64, timestamp,
2031       GST_QUARK (DURATION), G_TYPE_UINT64, duration, NULL);
2032 }
2033
2034 /**
2035  * gst_message_parse_qos_values:
2036  * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
2037  * @jitter: (out) (allow-none): The difference of the running-time against
2038  *     the deadline.
2039  * @proportion: (out) (allow-none): Long term prediction of the ideal rate
2040  *     relative to normal rate to get optimal quality.
2041  * @quality: (out) (allow-none): An element dependent integer value that
2042  *     specifies the current quality level of the element. The default
2043  *     maximum quality is 1000000.
2044  *
2045  * Extract the QoS values that have been calculated/analysed from the QoS data
2046  *
2047  * MT safe.
2048  *
2049  * Since: 0.10.29
2050  */
2051 void
2052 gst_message_parse_qos_values (GstMessage * message, gint64 * jitter,
2053     gdouble * proportion, gint * quality)
2054 {
2055   GstStructure *structure;
2056
2057   g_return_if_fail (GST_IS_MESSAGE (message));
2058   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
2059
2060   structure = GST_MESSAGE_STRUCTURE (message);
2061   gst_structure_id_get (structure,
2062       GST_QUARK (JITTER), G_TYPE_INT64, jitter,
2063       GST_QUARK (PROPORTION), G_TYPE_DOUBLE, proportion,
2064       GST_QUARK (QUALITY), G_TYPE_INT, quality, NULL);
2065 }
2066
2067 /**
2068  * gst_message_parse_qos_stats:
2069  * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
2070  * @format: (out) (allow-none): Units of the 'processed' and 'dropped' fields.
2071  *     Video sinks and video filters will use GST_FORMAT_BUFFERS (frames).
2072  *     Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT
2073  *     (samples).
2074  * @processed: (out) (allow-none): Total number of units correctly processed
2075  *     since the last state change to READY or a flushing operation.
2076  * @dropped: (out) (allow-none): Total number of units dropped since the last
2077  *     state change to READY or a flushing operation.
2078  *
2079  * Extract the QoS stats representing the history of the current continuous
2080  * pipeline playback period.
2081  *
2082  * When @format is @GST_FORMAT_UNDEFINED both @dropped and @processed are
2083  * invalid. Values of -1 for either @processed or @dropped mean unknown values.
2084  *
2085  * MT safe.
2086  *
2087  * Since: 0.10.29
2088  */
2089 void
2090 gst_message_parse_qos_stats (GstMessage * message, GstFormat * format,
2091     guint64 * processed, guint64 * dropped)
2092 {
2093   GstStructure *structure;
2094
2095   g_return_if_fail (GST_IS_MESSAGE (message));
2096   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
2097
2098   structure = GST_MESSAGE_STRUCTURE (message);
2099   gst_structure_id_get (structure,
2100       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
2101       GST_QUARK (PROCESSED), G_TYPE_UINT64, processed,
2102       GST_QUARK (DROPPED), G_TYPE_UINT64, dropped, NULL);
2103 }
2104
2105 /**
2106  * gst_message_new_progress:
2107  * @src: The object originating the message.
2108  * @type: a #GstProgressType
2109  * @code: a progress code
2110  * @text: free, user visible text describing the progress
2111  *
2112  * Progress messages are posted by elements when they use an asynchronous task
2113  * to perform actions triggered by a state change.
2114  *
2115  * @code contains a well defined string describing the action.
2116  * @test should contain a user visible string detailing the current action.
2117  *
2118  * Returns: (transfer full): The new qos message.
2119  *
2120  * Since: 0.10.33
2121  */
2122 GstMessage *
2123 gst_message_new_progress (GstObject * src, GstProgressType type,
2124     const gchar * code, const gchar * text)
2125 {
2126   GstMessage *message;
2127   GstStructure *structure;
2128   gint percent = 100, timeout = -1;
2129
2130   g_return_val_if_fail (code != NULL, NULL);
2131   g_return_val_if_fail (text != NULL, NULL);
2132
2133   if (type == GST_PROGRESS_TYPE_START || type == GST_PROGRESS_TYPE_CONTINUE)
2134     percent = 0;
2135
2136   structure = gst_structure_new_id (GST_QUARK (MESSAGE_PROGRESS),
2137       GST_QUARK (TYPE), GST_TYPE_PROGRESS_TYPE, type,
2138       GST_QUARK (CODE), G_TYPE_STRING, code,
2139       GST_QUARK (TEXT), G_TYPE_STRING, text,
2140       GST_QUARK (PERCENT), G_TYPE_INT, percent,
2141       GST_QUARK (TIMEOUT), G_TYPE_INT, timeout, NULL);
2142   message = gst_message_new_custom (GST_MESSAGE_PROGRESS, src, structure);
2143
2144   return message;
2145 }
2146
2147 /**
2148  * gst_message_parse_progress:
2149  * @message: A valid #GstMessage of type GST_MESSAGE_PROGRESS.
2150  * @type: (out) (allow-none): location for the type
2151  * @code: (out) (allow-none) (transfer full): location for the code
2152  * @text: (out) (allow-none) (transfer full): location for the text
2153  *
2154  * Parses the progress @type, @code and @text.
2155  *
2156  * Since: 0.10.33
2157  */
2158 void
2159 gst_message_parse_progress (GstMessage * message, GstProgressType * type,
2160     gchar ** code, gchar ** text)
2161 {
2162   GstStructure *structure;
2163
2164   g_return_if_fail (GST_IS_MESSAGE (message));
2165   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_PROGRESS);
2166
2167   structure = GST_MESSAGE_STRUCTURE (message);
2168   gst_structure_id_get (structure,
2169       GST_QUARK (TYPE), GST_TYPE_PROGRESS_TYPE, type,
2170       GST_QUARK (CODE), G_TYPE_STRING, code,
2171       GST_QUARK (TEXT), G_TYPE_STRING, text, NULL);
2172 }
2173
2174 /**
2175  * gst_message_new_toc:
2176  * @src: the object originating the message.
2177  * @toc: #GstToc structure for the message.
2178  * @updated: whether TOC was updated or not.
2179  *
2180  * Create a new TOC message. The message is posted by elements
2181  * that discovered or updated a TOC.
2182  *
2183  * Returns: a new TOC message.
2184  *
2185  * MT safe.
2186  *
2187  * Since: 0.10.37
2188  */
2189 GstMessage *
2190 gst_message_new_toc (GstObject * src, GstToc * toc, gboolean updated)
2191 {
2192   GstStructure *toc_struct;
2193
2194   g_return_val_if_fail (toc != NULL, NULL);
2195
2196   toc_struct = __gst_toc_to_structure (toc);
2197
2198   if (G_LIKELY (toc_struct != NULL)) {
2199     __gst_toc_structure_set_updated (toc_struct, updated);
2200     return gst_message_new_custom (GST_MESSAGE_TOC, src, toc_struct);
2201   } else
2202     return NULL;
2203 }
2204
2205 /**
2206  * gst_message_parse_toc:
2207  * @message: a valid #GstMessage of type GST_MESSAGE_TOC.
2208  * @toc: (out): return location for the TOC.
2209  * @updated: (out): return location for the updated flag.
2210  *
2211  * Extract thef TOC from the #GstMessage. The TOC returned in the
2212  * output argument is a copy; the caller must free it with
2213  * gst_toc_free() when done.
2214  *
2215  * MT safe.
2216  *
2217  * Since: 0.10.37
2218  */
2219 void
2220 gst_message_parse_toc (GstMessage * message, GstToc ** toc, gboolean * updated)
2221 {
2222   g_return_if_fail (GST_IS_MESSAGE (message));
2223   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_TOC);
2224   g_return_if_fail (toc != NULL);
2225
2226   *toc = __gst_toc_from_structure (GST_MESSAGE_STRUCTURE (message));
2227
2228   if (updated != NULL)
2229     *updated =
2230         __gst_toc_structure_get_updated (GST_MESSAGE_STRUCTURE (message));
2231 }
2232
2233 /**
2234  * gst_message_new_reset_time:
2235  * @src: (transfer none): The object originating the message.
2236  * @running_time: the requested running-time
2237  *
2238  * This message is posted when the pipeline running-time should be reset to
2239  * @running_time, like after a flushing seek.
2240  *
2241  * Returns: (transfer full): The new reset_time message.
2242  *
2243  * MT safe.
2244  */
2245 GstMessage *
2246 gst_message_new_reset_time (GstObject * src, GstClockTime running_time)
2247 {
2248   GstMessage *message;
2249   GstStructure *structure;
2250
2251   structure = gst_structure_new_id (GST_QUARK (MESSAGE_RESET_TIME),
2252       GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time, NULL);
2253   message = gst_message_new_custom (GST_MESSAGE_RESET_TIME, src, structure);
2254
2255   return message;
2256 }
2257
2258 /**
2259  * gst_message_parse_reset_time:
2260  * @message: A valid #GstMessage of type GST_MESSAGE_RESET_TIME.
2261  * @running_time: (out): Result location for the running_time or NULL
2262  *
2263  * Extract the running-time from the RESET_TIME message.
2264  *
2265  * MT safe.
2266  */
2267 void
2268 gst_message_parse_reset_time (GstMessage * message, GstClockTime * running_time)
2269 {
2270   GstStructure *structure;
2271
2272   g_return_if_fail (GST_IS_MESSAGE (message));
2273   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_RESET_TIME);
2274
2275   structure = GST_MESSAGE_STRUCTURE (message);
2276   if (running_time)
2277     *running_time =
2278         g_value_get_uint64 (gst_structure_id_get_value (structure,
2279             GST_QUARK (RUNNING_TIME)));
2280 }