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