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