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
 514   g_return_val_if_fail (percent >= 0 && percent <= 100, NULL);
 515
 516   structure = gst_structure_new_id (GST_QUARK (MESSAGE_BUFFERING),
 517       GST_QUARK (BUFFER_PERCENT), G_TYPE_INT, percent,
 518       GST_QUARK (BUFFERING_MODE), GST_TYPE_BUFFERING_MODE, GST_BUFFERING_STREAM,
 519       GST_QUARK (AVG_IN_RATE), G_TYPE_INT, -1,
 520       GST_QUARK (AVG_OUT_RATE), G_TYPE_INT, -1,
 521       GST_QUARK (BUFFERING_LEFT), G_TYPE_INT64, G_GINT64_CONSTANT (-1),
 522       GST_QUARK (ESTIMATED_TOTAL), G_TYPE_INT64, G_GINT64_CONSTANT (-1), NULL);
 523   message = gst_message_new_custom (GST_MESSAGE_BUFFERING, src, structure);
 524
 525   return message;
 526 }
 527
 528 /**
 529  * gst_message_new_state_changed:
 530  * @src: (transfer none): the object originating the message
 531  * @oldstate: the previous state
 532  * @newstate: the new (current) state
 533  * @pending: the pending (target) state
 534  *
 535  * Create a state change message. This message is posted whenever an element
 536  * changed its state.
 537  *
 538  * Returns: (transfer full): the new state change message.
 539  *
 540  * MT safe.
 541  */
 542 GstMessage *
 543 gst_message_new_state_changed (GstObject * src,
 544     GstState oldstate, GstState newstate, GstState pending)
 545 {
 546   GstMessage *message;
 547   GstStructure *structure;
 548
 549   structure = gst_structure_new_id (GST_QUARK (MESSAGE_STATE_CHANGED),
 550       GST_QUARK (OLD_STATE), GST_TYPE_STATE, (gint) oldstate,
 551       GST_QUARK (NEW_STATE), GST_TYPE_STATE, (gint) newstate,
 552       GST_QUARK (PENDING_STATE), GST_TYPE_STATE, (gint) pending, NULL);
 553   message = gst_message_new_custom (GST_MESSAGE_STATE_CHANGED, src, structure);
 554
 555   return message;
 556 }
 557
 558 /**
 559  * gst_message_new_state_dirty:
 560  * @src: (transfer none): the object originating the message
 561  *
 562  * Create a state dirty message. This message is posted whenever an element
 563  * changed its state asynchronously and is used internally to update the
 564  * states of container objects.
 565  *
 566  * Returns: (transfer full): the new state dirty message.
 567  *
 568  * MT safe.
 569  */
 570 GstMessage *
 571 gst_message_new_state_dirty (GstObject * src)
 572 {
 573   GstMessage *message;
 574
 575   message = gst_message_new_custom (GST_MESSAGE_STATE_DIRTY, src, NULL);
 576
 577   return message;
 578 }
 579
 580 /**
 581  * gst_message_new_clock_provide:
 582  * @src: (transfer none): the object originating the message.
 583  * @clock: (transfer none): the clock it provides
 584  * @ready: TRUE if the sender can provide a clock
 585  *
 586  * Create a clock provide message. This message is posted whenever an
 587  * element is ready to provide a clock or lost its ability to provide
 588  * a clock (maybe because it paused or became EOS).
 589  *
 590  * This message is mainly used internally to manage the clock
 591  * selection.
 592  *
 593  * Returns: (transfer full): the new provide clock message.
 594  *
 595  * MT safe.
 596  */
 597 GstMessage *
 598 gst_message_new_clock_provide (GstObject * src, GstClock * clock,
 599     gboolean ready)
 600 {
 601   GstMessage *message;
 602   GstStructure *structure;
 603
 604   structure = gst_structure_new_id (GST_QUARK (MESSAGE_CLOCK_PROVIDE),
 605       GST_QUARK (CLOCK), GST_TYPE_CLOCK, clock,
 606       GST_QUARK (READY), G_TYPE_BOOLEAN, ready, NULL);
 607   message = gst_message_new_custom (GST_MESSAGE_CLOCK_PROVIDE, src, structure);
 608
 609   return message;
 610 }
 611
 612 /**
 613  * gst_message_new_clock_lost:
 614  * @src: (transfer none): the object originating the message.
 615  * @clock: (transfer none): the clock that was lost
 616  *
 617  * Create a clock lost message. This message is posted whenever the
 618  * clock is not valid anymore.
 619  *
 620  * If this message is posted by the pipeline, the pipeline will
 621  * select a new clock again when it goes to PLAYING. It might therefore
 622  * be needed to set the pipeline to PAUSED and PLAYING again.
 623  *
 624  * Returns: (transfer full): The new clock lost message.
 625  *
 626  * MT safe.
 627  */
 628 GstMessage *
 629 gst_message_new_clock_lost (GstObject * src, GstClock * clock)
 630 {
 631   GstMessage *message;
 632   GstStructure *structure;
 633
 634   structure = gst_structure_new_id (GST_QUARK (MESSAGE_CLOCK_LOST),
 635       GST_QUARK (CLOCK), GST_TYPE_CLOCK, clock, NULL);
 636   message = gst_message_new_custom (GST_MESSAGE_CLOCK_LOST, src, structure);
 637
 638   return message;
 639 }
 640
 641 /**
 642  * gst_message_new_new_clock:
 643  * @src: (transfer none): The object originating the message.
 644  * @clock: (transfer none): the new selected clock
 645  *
 646  * Create a new clock message. This message is posted whenever the
 647  * pipeline selectes a new clock for the pipeline.
 648  *
 649  * Returns: (transfer full): The new new clock message.
 650  *
 651  * MT safe.
 652  */
 653 GstMessage *
 654 gst_message_new_new_clock (GstObject * src, GstClock * clock)
 655 {
 656   GstMessage *message;
 657   GstStructure *structure;
 658
 659   structure = gst_structure_new_id (GST_QUARK (MESSAGE_NEW_CLOCK),
 660       GST_QUARK (CLOCK), GST_TYPE_CLOCK, clock, NULL);
 661   message = gst_message_new_custom (GST_MESSAGE_NEW_CLOCK, src, structure);
 662
 663   return message;
 664 }
 665
 666 /**
 667  * gst_message_new_structure_change:
 668  * @src: (transfer none): The object originating the message.
 669  * @type: The change type.
 670  * @owner: (transfer none): The owner element of @src.
 671  * @busy: Whether the structure change is busy.
 672  *
 673  * Create a new structure change message. This message is posted when the
 674  * structure of a pipeline is in the process of being changed, for example
 675  * when pads are linked or unlinked.
 676  *
 677  * @src should be the sinkpad that unlinked or linked.
 678  *
 679  * Returns: (transfer full): the new structure change message.
 680  *
 681  * MT safe.
 682  */
 683 GstMessage *
 684 gst_message_new_structure_change (GstObject * src, GstStructureChangeType type,
 685     GstElement * owner, gboolean busy)
 686 {
 687   GstMessage *message;
 688   GstStructure *structure;
 689
 690   g_return_val_if_fail (GST_IS_PAD (src), NULL);
 691   /* g_return_val_if_fail (GST_PAD_DIRECTION (src) == GST_PAD_SINK, NULL); */
 692   g_return_val_if_fail (GST_IS_ELEMENT (owner), NULL);
 693
 694   structure = gst_structure_new_id (GST_QUARK (MESSAGE_STRUCTURE_CHANGE),
 695       GST_QUARK (TYPE), GST_TYPE_STRUCTURE_CHANGE_TYPE, type,
 696       GST_QUARK (OWNER), GST_TYPE_ELEMENT, owner,
 697       GST_QUARK (BUSY), G_TYPE_BOOLEAN, busy, NULL);
 698
 699   message = gst_message_new_custom (GST_MESSAGE_STRUCTURE_CHANGE, src,
 700       structure);
 701
 702   return message;
 703 }
 704
 705 /**
 706  * gst_message_new_segment_start:
 707  * @src: (transfer none): The object originating the message.
 708  * @format: The format of the position being played
 709  * @position: The position of the segment being played
 710  *
 711  * Create a new segment message. This message is posted by elements that
 712  * start playback of a segment as a result of a segment seek. This message
 713  * is not received by the application but is used for maintenance reasons in
 714  * container elements.
 715  *
 716  * Returns: (transfer full): the new segment start message.
 717  *
 718  * MT safe.
 719  */
 720 GstMessage *
 721 gst_message_new_segment_start (GstObject * src, GstFormat format,
 722     gint64 position)
 723 {
 724   GstMessage *message;
 725   GstStructure *structure;
 726
 727   structure = gst_structure_new_id (GST_QUARK (MESSAGE_SEGMENT_START),
 728       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 729       GST_QUARK (POSITION), G_TYPE_INT64, position, NULL);
 730   message = gst_message_new_custom (GST_MESSAGE_SEGMENT_START, src, structure);
 731
 732   return message;
 733 }
 734
 735 /**
 736  * gst_message_new_segment_done:
 737  * @src: (transfer none): the object originating the message.
 738  * @format: The format of the position being done
 739  * @position: The position of the segment being done
 740  *
 741  * Create a new segment done message. This message is posted by elements that
 742  * finish playback of a segment as a result of a segment seek. This message
 743  * is received by the application after all elements that posted a segment_start
 744  * have posted the segment_done.
 745  *
 746  * Returns: (transfer full): the new segment done message.
 747  *
 748  * MT safe.
 749  */
 750 GstMessage *
 751 gst_message_new_segment_done (GstObject * src, GstFormat format,
 752     gint64 position)
 753 {
 754   GstMessage *message;
 755   GstStructure *structure;
 756
 757   structure = gst_structure_new_id (GST_QUARK (MESSAGE_SEGMENT_DONE),
 758       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 759       GST_QUARK (POSITION), G_TYPE_INT64, position, NULL);
 760   message = gst_message_new_custom (GST_MESSAGE_SEGMENT_DONE, src, structure);
 761
 762   return message;
 763 }
 764
 765 /**
 766  * gst_message_new_application:
 767  * @src: (transfer none): the object originating the message.
 768  * @structure: (transfer full): the structure for the message. The message
 769  *     will take ownership of the structure.
 770  *
 771  * Create a new application-typed message. GStreamer will never create these
 772  * messages; they are a gift from us to you. Enjoy.
 773  *
 774  * Returns: (transfer full): The new application message.
 775  *
 776  * MT safe.
 777  */
 778 GstMessage *
 779 gst_message_new_application (GstObject * src, GstStructure * structure)
 780 {
 781   return gst_message_new_custom (GST_MESSAGE_APPLICATION, src, structure);
 782 }
 783
 784 /**
 785  * gst_message_new_element:
 786  * @src: (transfer none): The object originating the message.
 787  * @structure: (transfer full): The structure for the message. The message
 788  *     will take ownership of the structure.
 789  *
 790  * Create a new element-specific message. This is meant as a generic way of
 791  * allowing one-way communication from an element to an application, for example
 792  * "the firewire cable was unplugged". The format of the message should be
 793  * documented in the element's documentation. The structure field can be NULL.
 794  *
 795  * Returns: (transfer full): The new element message.
 796  *
 797  * MT safe.
 798  */
 799 GstMessage *
 800 gst_message_new_element (GstObject * src, GstStructure * structure)
 801 {
 802   return gst_message_new_custom (GST_MESSAGE_ELEMENT, src, structure);
 803 }
 804
 805 /**
 806  * gst_message_new_duration:
 807  * @src: (transfer none): The object originating the message.
 808  * @format: The format of the duration
 809  * @duration: The new duration
 810  *
 811  * Create a new duration message. This message is posted by elements that
 812  * know the duration of a stream in a specific format. This message
 813  * is received by bins and is used to calculate the total duration of a
 814  * pipeline. Elements may post a duration message with a duration of
 815  * GST_CLOCK_TIME_NONE to indicate that the duration has changed and the
 816  * cached duration should be discarded. The new duration can then be
 817  * retrieved via a query.
 818  *
 819  * Returns: (transfer full): The new duration message.
 820  *
 821  * MT safe.
 822  */
 823 GstMessage *
 824 gst_message_new_duration (GstObject * src, GstFormat format, gint64 duration)
 825 {
 826   GstMessage *message;
 827   GstStructure *structure;
 828
 829   structure = gst_structure_new_id (GST_QUARK (MESSAGE_DURATION),
 830       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
 831       GST_QUARK (DURATION), G_TYPE_INT64, duration, NULL);
 832   message = gst_message_new_custom (GST_MESSAGE_DURATION, src, structure);
 833
 834   return message;
 835 }
 836
 837 /**
 838  * gst_message_new_async_start:
 839  * @src: (transfer none): The object originating the message.
 840  *
 841  * This message is posted by elements when they start an ASYNC state change.
 842  *
 843  * Returns: (transfer full): The new async_start message.
 844  *
 845  * MT safe.
 846  */
 847 GstMessage *
 848 gst_message_new_async_start (GstObject * src)
 849 {
 850   GstMessage *message;
 851
 852   message = gst_message_new_custom (GST_MESSAGE_ASYNC_START, src, NULL);
 853
 854   return message;
 855 }
 856
 857 /**
 858  * gst_message_new_async_done:
 859  * @src: (transfer none): The object originating the message.
 860  * @running_time: the desired running_time
 861  *
 862  * The message is posted when elements completed an ASYNC state change.
 863  * @running_time contains the time of the desired running_time when this
 864  * elements goes to PLAYING. A value of #GST_CLOCK_TIME_NONE for @running_time
 865  * means that the element has no clock interaction and thus doesn't care about
 866  * the running_time of the pipeline.
 867  *
 868  * Returns: (transfer full): The new async_done message.
 869  *
 870  * MT safe.
 871  */
 872 GstMessage *
 873 gst_message_new_async_done (GstObject * src, GstClockTime running_time)
 874 {
 875   GstMessage *message;
 876   GstStructure *structure;
 877
 878   structure = gst_structure_new_id (GST_QUARK (MESSAGE_ASYNC_DONE),
 879       GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time, NULL);
 880   message = gst_message_new_custom (GST_MESSAGE_ASYNC_DONE, src, structure);
 881
 882   return message;
 883 }
 884
 885 /**
 886  * gst_message_new_latency:
 887  * @src: (transfer none): The object originating the message.
 888  *
 889  * This message can be posted by elements when their latency requirements have
 890  * changed.
 891  *
 892  * Returns: (transfer full): The new latency message.
 893  *
 894  * MT safe.
 895  */
 896 GstMessage *
 897 gst_message_new_latency (GstObject * src)
 898 {
 899   GstMessage *message;
 900
 901   message = gst_message_new_custom (GST_MESSAGE_LATENCY, src, NULL);
 902
 903   return message;
 904 }
 905
 906 /**
 907  * gst_message_new_request_state:
 908  * @src: (transfer none): the object originating the message.
 909  * @state: The new requested state
 910  *
 911  * This message can be posted by elements when they want to have their state
 912  * changed. A typical use case would be an audio server that wants to pause the
 913  * pipeline because a higher priority stream is being played.
 914  *
 915  * Returns: (transfer full): the new requst state message.
 916  *
 917  * MT safe.
 918  */
 919 GstMessage *
 920 gst_message_new_request_state (GstObject * src, GstState state)
 921 {
 922   GstMessage *message;
 923   GstStructure *structure;
 924
 925   structure = gst_structure_new_id (GST_QUARK (MESSAGE_REQUEST_STATE),
 926       GST_QUARK (NEW_STATE), GST_TYPE_STATE, (gint) state, NULL);
 927   message = gst_message_new_custom (GST_MESSAGE_REQUEST_STATE, src, structure);
 928
 929   return message;
 930 }
 931
 932 /**
 933  * gst_message_get_structure:
 934  * @message: The #GstMessage.
 935  *
 936  * Access the structure of the message.
 937  *
 938  * Returns: (transfer none): The structure of the message. The structure is
 939  * still owned by the message, which means that you should not free it and
 940  * that the pointer becomes invalid when you free the message.
 941  *
 942  * MT safe.
 943  */
 944 const GstStructure *
 945 gst_message_get_structure (GstMessage * message)
 946 {
 947   g_return_val_if_fail (GST_IS_MESSAGE (message), NULL);
 948
 949   return GST_MESSAGE_STRUCTURE (message);
 950 }
 951
 952 /**
 953  * gst_message_has_name:
 954  * @message: The #GstMessage.
 955  * @name: name to check
 956  *
 957  * Checks if @message has the given @name. This function is usually used to
 958  * check the name of a custom message.
 959  *
 960  * Returns: %TRUE if @name matches the name of the message structure.
 961  */
 962 gboolean
 963 gst_message_has_name (GstMessage * message, const gchar * name)
 964 {
 965   GstStructure *structure;
 966
 967   g_return_val_if_fail (GST_IS_MESSAGE (message), FALSE);
 968
 969   structure = GST_MESSAGE_STRUCTURE (message);
 970   if (structure == NULL)
 971     return FALSE;
 972
 973   return gst_structure_has_name (structure, name);
 974 }
 975
 976 /**
 977  * gst_message_parse_tag:
 978  * @message: A valid #GstMessage of type GST_MESSAGE_TAG.
 979  * @tag_list: (out callee-allocates): return location for the tag-list.
 980  *
 981  * Extracts the tag list from the GstMessage. The tag list returned in the
 982  * output argument is a copy; the caller must free it when done.
 983  *
 984  * Typical usage of this function might be:
 985  * |[
 986  *   ...
 987  *   switch (GST_MESSAGE_TYPE (msg)) {
 988  *     case GST_MESSAGE_TAG: {
 989  *       GstTagList *tags = NULL;
 990  *
 991  *       gst_message_parse_tag (msg, &amp;tags);
 992  *       g_print ("Got tags from element %s\n", GST_OBJECT_NAME (msg->src));
 993  *       handle_tags (tags);
 994  *       gst_tag_list_unref (tags);
 995  *       break;
 996  *     }
 997  *     ...
 998  *   }
 999  *   ...
1000  * ]|
1001  *
1002  * MT safe.
1003  */
1004 void
1005 gst_message_parse_tag (GstMessage * message, GstTagList ** tag_list)
1006 {
1007   g_return_if_fail (GST_IS_MESSAGE (message));
1008   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_TAG);
1009   g_return_if_fail (tag_list != NULL);
1010
1011   gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
1012       GST_QUARK (TAGLIST), GST_TYPE_TAG_LIST, tag_list, NULL);
1013 }
1014
1015 /**
1016  * gst_message_parse_buffering:
1017  * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
1018  * @percent: (out) (allow-none): Return location for the percent.
1019  *
1020  * Extracts the buffering percent from the GstMessage. see also
1021  * gst_message_new_buffering().
1022  *
1023  * MT safe.
1024  */
1025 void
1026 gst_message_parse_buffering (GstMessage * message, gint * percent)
1027 {
1028   g_return_if_fail (GST_IS_MESSAGE (message));
1029   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
1030
1031   if (percent)
1032     *percent =
1033         g_value_get_int (gst_structure_id_get_value (GST_MESSAGE_STRUCTURE
1034             (message), GST_QUARK (BUFFER_PERCENT)));
1035 }
1036
1037 /**
1038  * gst_message_set_buffering_stats:
1039  * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
1040  * @mode: a buffering mode
1041  * @avg_in: the average input rate
1042  * @avg_out: the average output rate
1043  * @buffering_left: amount of buffering time left in milliseconds
1044  *
1045  * Configures the buffering stats values in @message.
1046  */
1047 void
1048 gst_message_set_buffering_stats (GstMessage * message, GstBufferingMode mode,
1049     gint avg_in, gint avg_out, gint64 buffering_left)
1050 {
1051   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
1052
1053   gst_structure_id_set (GST_MESSAGE_STRUCTURE (message),
1054       GST_QUARK (BUFFERING_MODE), GST_TYPE_BUFFERING_MODE, mode,
1055       GST_QUARK (AVG_IN_RATE), G_TYPE_INT, avg_in,
1056       GST_QUARK (AVG_OUT_RATE), G_TYPE_INT, avg_out,
1057       GST_QUARK (BUFFERING_LEFT), G_TYPE_INT64, buffering_left, NULL);
1058 }
1059
1060 /**
1061  * gst_message_parse_buffering_stats:
1062  * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
1063  * @mode: (out) (allow-none): a buffering mode, or NULL
1064  * @avg_in: (out) (allow-none): the average input rate, or NULL
1065  * @avg_out: (out) (allow-none): the average output rate, or NULL
1066  * @buffering_left: (out) (allow-none): amount of buffering time left in
1067  *     milliseconds, or NULL
1068  *
1069  * Extracts the buffering stats values from @message.
1070  */
1071 void
1072 gst_message_parse_buffering_stats (GstMessage * message,
1073     GstBufferingMode * mode, gint * avg_in, gint * avg_out,
1074     gint64 * buffering_left)
1075 {
1076   GstStructure *structure;
1077
1078   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
1079
1080   structure = GST_MESSAGE_STRUCTURE (message);
1081   if (mode)
1082     *mode = (GstBufferingMode)
1083         g_value_get_enum (gst_structure_id_get_value (structure,
1084             GST_QUARK (BUFFERING_MODE)));
1085   if (avg_in)
1086     *avg_in = g_value_get_int (gst_structure_id_get_value (structure,
1087             GST_QUARK (AVG_IN_RATE)));
1088   if (avg_out)
1089     *avg_out = g_value_get_int (gst_structure_id_get_value (structure,
1090             GST_QUARK (AVG_OUT_RATE)));
1091   if (buffering_left)
1092     *buffering_left =
1093         g_value_get_int64 (gst_structure_id_get_value (structure,
1094             GST_QUARK (BUFFERING_LEFT)));
1095 }
1096
1097 /**
1098  * gst_message_parse_state_changed:
1099  * @message: a valid #GstMessage of type GST_MESSAGE_STATE_CHANGED
1100  * @oldstate: (out) (allow-none): the previous state, or NULL
1101  * @newstate: (out) (allow-none): the new (current) state, or NULL
1102  * @pending: (out) (allow-none): the pending (target) state, or NULL
1103  *
1104  * Extracts the old and new states from the GstMessage.
1105  *
1106  * Typical usage of this function might be:
1107  * |[
1108  *   ...
1109  *   switch (GST_MESSAGE_TYPE (msg)) {
1110  *     case GST_MESSAGE_STATE_CHANGED: {
1111  *       GstState old_state, new_state;
1112  *
1113  *       gst_message_parse_state_changed (msg, &amp;old_state, &amp;new_state, NULL);
1114  *       g_print ("Element %s changed state from %s to %s.\n",
1115  *           GST_OBJECT_NAME (msg->src),
1116  *           gst_element_state_get_name (old_state),
1117  *           gst_element_state_get_name (new_state));
1118  *       break;
1119  *     }
1120  *     ...
1121  *   }
1122  *   ...
1123  * ]|
1124  *
1125  * MT safe.
1126  */
1127 void
1128 gst_message_parse_state_changed (GstMessage * message,
1129     GstState * oldstate, GstState * newstate, GstState * pending)
1130 {
1131   GstStructure *structure;
1132
1133   g_return_if_fail (GST_IS_MESSAGE (message));
1134   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STATE_CHANGED);
1135
1136   structure = GST_MESSAGE_STRUCTURE (message);
1137   if (oldstate)
1138     *oldstate = (GstState)
1139         g_value_get_enum (gst_structure_id_get_value (structure,
1140             GST_QUARK (OLD_STATE)));
1141   if (newstate)
1142     *newstate = (GstState)
1143         g_value_get_enum (gst_structure_id_get_value (structure,
1144             GST_QUARK (NEW_STATE)));
1145   if (pending)
1146     *pending = (GstState)
1147         g_value_get_enum (gst_structure_id_get_value (structure,
1148             GST_QUARK (PENDING_STATE)));
1149 }
1150
1151 /**
1152  * gst_message_parse_clock_provide:
1153  * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_PROVIDE.
1154  * @clock: (out) (allow-none) (transfer none): a pointer to  hold a clock
1155  *     object, or NULL
1156  * @ready: (out) (allow-none): a pointer to hold the ready flag, or NULL
1157  *
1158  * Extracts the clock and ready flag from the GstMessage.
1159  * The clock object returned remains valid until the message is freed.
1160  *
1161  * MT safe.
1162  */
1163 void
1164 gst_message_parse_clock_provide (GstMessage * message, GstClock ** clock,
1165     gboolean * ready)
1166 {
1167   const GValue *clock_gvalue;
1168   GstStructure *structure;
1169
1170   g_return_if_fail (GST_IS_MESSAGE (message));
1171   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_CLOCK_PROVIDE);
1172
1173   structure = GST_MESSAGE_STRUCTURE (message);
1174   clock_gvalue = gst_structure_id_get_value (structure, GST_QUARK (CLOCK));
1175   g_return_if_fail (clock_gvalue != NULL);
1176   g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);
1177
1178   if (ready)
1179     *ready =
1180         g_value_get_boolean (gst_structure_id_get_value (structure,
1181             GST_QUARK (READY)));
1182   if (clock)
1183     *clock = (GstClock *) g_value_get_object (clock_gvalue);
1184 }
1185
1186 /**
1187  * gst_message_parse_clock_lost:
1188  * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_LOST.
1189  * @clock: (out) (allow-none) (transfer none): a pointer to hold the lost clock
1190  *
1191  * Extracts the lost clock from the GstMessage.
1192  * The clock object returned remains valid until the message is freed.
1193  *
1194  * MT safe.
1195  */
1196 void
1197 gst_message_parse_clock_lost (GstMessage * message, GstClock ** clock)
1198 {
1199   const GValue *clock_gvalue;
1200   GstStructure *structure;
1201
1202   g_return_if_fail (GST_IS_MESSAGE (message));
1203   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_CLOCK_LOST);
1204
1205   structure = GST_MESSAGE_STRUCTURE (message);
1206   clock_gvalue = gst_structure_id_get_value (structure, GST_QUARK (CLOCK));
1207   g_return_if_fail (clock_gvalue != NULL);
1208   g_return_if_fail (G_VALUE_TYPE (clock_gvalue) == GST_TYPE_CLOCK);
1209
1210   if (clock)
1211     *clock = (GstClock *) g_value_get_object (clock_gvalue);
1212 }
1213
1214 /**
1215  * gst_message_parse_new_clock:
1216  * @message: A valid #GstMessage of type GST_MESSAGE_NEW_CLOCK.
1217  * @clock: (out) (allow-none) (transfer none): a pointer to hold the selected
1218  *     new clock
1219  *
1220  * Extracts the new 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_new_clock (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_NEW_CLOCK);
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_structure_change:
1245  * @message: A valid #GstMessage of type GST_MESSAGE_STRUCTURE_CHANGE.
1246  * @type: (out): A pointer to hold the change type
1247  * @owner: (out) (allow-none) (transfer none): The owner element of the
1248  *     message source
1249  * @busy: (out) (allow-none): a pointer to hold whether the change is in
1250  *     progress or has been completed
1251  *
1252  * Extracts the change type and completion status from the GstMessage.
1253  *
1254  * MT safe.
1255  */
1256 void
1257 gst_message_parse_structure_change (GstMessage * message,
1258     GstStructureChangeType * type, GstElement ** owner, gboolean * busy)
1259 {
1260   const GValue *owner_gvalue;
1261   GstStructure *structure;
1262
1263   g_return_if_fail (GST_IS_MESSAGE (message));
1264   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STRUCTURE_CHANGE);
1265
1266   structure = GST_MESSAGE_STRUCTURE (message);
1267   owner_gvalue = gst_structure_id_get_value (structure, GST_QUARK (OWNER));
1268   g_return_if_fail (owner_gvalue != NULL);
1269   g_return_if_fail (G_VALUE_TYPE (owner_gvalue) == GST_TYPE_ELEMENT);
1270
1271   if (type)
1272     *type = (GstStructureChangeType)
1273         g_value_get_enum (gst_structure_id_get_value (structure,
1274             GST_QUARK (TYPE)));
1275   if (owner)
1276     *owner = (GstElement *) g_value_get_object (owner_gvalue);
1277   if (busy)
1278     *busy =
1279         g_value_get_boolean (gst_structure_id_get_value (structure,
1280             GST_QUARK (BUSY)));
1281 }
1282
1283 /**
1284  * gst_message_parse_error:
1285  * @message: A valid #GstMessage of type GST_MESSAGE_ERROR.
1286  * @gerror: (out) (allow-none) (transfer full): location for the GError
1287  * @debug: (out) (allow-none) (transfer full): location for the debug message,
1288  *     or NULL
1289  *
1290  * Extracts the GError and debug string from the GstMessage. The values returned
1291  * in the output arguments are copies; the caller must free them when done.
1292  *
1293  * Typical usage of this function might be:
1294  * |[
1295  *   ...
1296  *   switch (GST_MESSAGE_TYPE (msg)) {
1297  *     case GST_MESSAGE_ERROR: {
1298  *       GError *err = NULL;
1299  *       gchar *dbg_info = NULL;
1300  *
1301  *       gst_message_parse_error (msg, &amp;err, &amp;dbg_info);
1302  *       g_printerr ("ERROR from element %s: %s\n",
1303  *           GST_OBJECT_NAME (msg->src), err->message);
1304  *       g_printerr ("Debugging info: %s\n", (dbg_info) ? dbg_info : "none");
1305  *       g_error_free (err);
1306  *       g_free (dbg_info);
1307  *       break;
1308  *     }
1309  *     ...
1310  *   }
1311  *   ...
1312  * ]|
1313  *
1314  * MT safe.
1315  */
1316 void
1317 gst_message_parse_error (GstMessage * message, GError ** gerror, gchar ** debug)
1318 {
1319   const GValue *error_gvalue;
1320   GError *error_val;
1321   GstStructure *structure;
1322
1323   g_return_if_fail (GST_IS_MESSAGE (message));
1324   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_ERROR);
1325
1326   structure = GST_MESSAGE_STRUCTURE (message);
1327   error_gvalue = gst_structure_id_get_value (structure, GST_QUARK (GERROR));
1328   g_return_if_fail (error_gvalue != NULL);
1329   g_return_if_fail (G_VALUE_TYPE (error_gvalue) == G_TYPE_ERROR);
1330
1331   error_val = (GError *) g_value_get_boxed (error_gvalue);
1332   if (error_val)
1333     *gerror = g_error_copy (error_val);
1334   else
1335     *gerror = NULL;
1336
1337   if (debug)
1338     *debug =
1339         g_value_dup_string (gst_structure_id_get_value (structure,
1340             GST_QUARK (DEBUG)));
1341 }
1342
1343 /**
1344  * gst_message_parse_warning:
1345  * @message: A valid #GstMessage of type GST_MESSAGE_WARNING.
1346  * @gerror: (out) (allow-none) (transfer full): location for the GError
1347  * @debug: (out) (allow-none) (transfer full): location for the debug message,
1348  *     or NULL
1349  *
1350  * Extracts the GError and debug string from the GstMessage. The values returned
1351  * in the output arguments are copies; the caller must free them when done.
1352  *
1353  * MT safe.
1354  */
1355 void
1356 gst_message_parse_warning (GstMessage * message, GError ** gerror,
1357     gchar ** debug)
1358 {
1359   const GValue *error_gvalue;
1360   GError *error_val;
1361   GstStructure *structure;
1362
1363   g_return_if_fail (GST_IS_MESSAGE (message));
1364   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_WARNING);
1365
1366   structure = GST_MESSAGE_STRUCTURE (message);
1367   error_gvalue = gst_structure_id_get_value (structure, GST_QUARK (GERROR));
1368   g_return_if_fail (error_gvalue != NULL);
1369   g_return_if_fail (G_VALUE_TYPE (error_gvalue) == G_TYPE_ERROR);
1370
1371   error_val = (GError *) g_value_get_boxed (error_gvalue);
1372   if (error_val)
1373     *gerror = g_error_copy (error_val);
1374   else
1375     *gerror = NULL;
1376
1377   if (debug)
1378     *debug =
1379         g_value_dup_string (gst_structure_id_get_value (structure,
1380             GST_QUARK (DEBUG)));
1381 }
1382
1383 /**
1384  * gst_message_parse_info:
1385  * @message: A valid #GstMessage of type GST_MESSAGE_INFO.
1386  * @gerror: (out) (allow-none) (transfer full): location for the GError
1387  * @debug: (out) (allow-none) (transfer full): location for the debug message,
1388  *     or NULL
1389  *
1390  * Extracts the GError and debug string from the GstMessage. The values returned
1391  * in the output arguments are copies; the caller must free them when done.
1392  *
1393  * MT safe.
1394  */
1395 void
1396 gst_message_parse_info (GstMessage * message, GError ** gerror, gchar ** debug)
1397 {
1398   const GValue *error_gvalue;
1399   GError *error_val;
1400   GstStructure *structure;
1401
1402   g_return_if_fail (GST_IS_MESSAGE (message));
1403   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_INFO);
1404
1405   structure = GST_MESSAGE_STRUCTURE (message);
1406   error_gvalue = gst_structure_id_get_value (structure, GST_QUARK (GERROR));
1407   g_return_if_fail (error_gvalue != NULL);
1408   g_return_if_fail (G_VALUE_TYPE (error_gvalue) == G_TYPE_ERROR);
1409
1410   error_val = (GError *) g_value_get_boxed (error_gvalue);
1411   if (error_val)
1412     *gerror = g_error_copy (error_val);
1413   else
1414     *gerror = NULL;
1415
1416   if (debug)
1417     *debug =
1418         g_value_dup_string (gst_structure_id_get_value (structure,
1419             GST_QUARK (DEBUG)));
1420 }
1421
1422 /**
1423  * gst_message_parse_segment_start:
1424  * @message: A valid #GstMessage of type GST_MESSAGE_SEGMENT_START.
1425  * @format: (out): Result location for the format, or NULL
1426  * @position: (out): Result location for the position, or NULL
1427  *
1428  * Extracts the position and format from the segment start message.
1429  *
1430  * MT safe.
1431  */
1432 void
1433 gst_message_parse_segment_start (GstMessage * message, GstFormat * format,
1434     gint64 * position)
1435 {
1436   GstStructure *structure;
1437
1438   g_return_if_fail (GST_IS_MESSAGE (message));
1439   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_SEGMENT_START);
1440
1441   structure = GST_MESSAGE_STRUCTURE (message);
1442   if (format)
1443     *format = (GstFormat)
1444         g_value_get_enum (gst_structure_id_get_value (structure,
1445             GST_QUARK (FORMAT)));
1446   if (position)
1447     *position =
1448         g_value_get_int64 (gst_structure_id_get_value (structure,
1449             GST_QUARK (POSITION)));
1450 }
1451
1452 /**
1453  * gst_message_parse_segment_done:
1454  * @message: A valid #GstMessage of type GST_MESSAGE_SEGMENT_DONE.
1455  * @format: (out): Result location for the format, or NULL
1456  * @position: (out): Result location for the position, or NULL
1457  *
1458  * Extracts the position and format from the segment start message.
1459  *
1460  * MT safe.
1461  */
1462 void
1463 gst_message_parse_segment_done (GstMessage * message, GstFormat * format,
1464     gint64 * position)
1465 {
1466   GstStructure *structure;
1467
1468   g_return_if_fail (GST_IS_MESSAGE (message));
1469   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_SEGMENT_DONE);
1470
1471   structure = GST_MESSAGE_STRUCTURE (message);
1472   if (format)
1473     *format = (GstFormat)
1474         g_value_get_enum (gst_structure_id_get_value (structure,
1475             GST_QUARK (FORMAT)));
1476   if (position)
1477     *position =
1478         g_value_get_int64 (gst_structure_id_get_value (structure,
1479             GST_QUARK (POSITION)));
1480 }
1481
1482 /**
1483  * gst_message_parse_duration:
1484  * @message: A valid #GstMessage of type GST_MESSAGE_DURATION.
1485  * @format: (out): Result location for the format, or NULL
1486  * @duration: (out): Result location for the duration, or NULL
1487  *
1488  * Extracts the duration and format from the duration message. The duration
1489  * might be GST_CLOCK_TIME_NONE, which indicates that the duration has
1490  * changed. Applications should always use a query to retrieve the duration
1491  * of a pipeline.
1492  *
1493  * MT safe.
1494  */
1495 void
1496 gst_message_parse_duration (GstMessage * message, GstFormat * format,
1497     gint64 * duration)
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_DURATION);
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 (duration)
1510     *duration =
1511         g_value_get_int64 (gst_structure_id_get_value (structure,
1512             GST_QUARK (DURATION)));
1513 }
1514
1515 /**
1516  * gst_message_parse_async_done:
1517  * @message: A valid #GstMessage of type GST_MESSAGE_ASYNC_DONE.
1518  * @running_time: (out): Result location for the running_time or NULL
1519  *
1520  * Extract the running_time from the async_done message.
1521  *
1522  * MT safe.
1523  */
1524 void
1525 gst_message_parse_async_done (GstMessage * message, GstClockTime * running_time)
1526 {
1527   GstStructure *structure;
1528
1529   g_return_if_fail (GST_IS_MESSAGE (message));
1530   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_ASYNC_DONE);
1531
1532   structure = GST_MESSAGE_STRUCTURE (message);
1533   if (running_time)
1534     *running_time =
1535         g_value_get_uint64 (gst_structure_id_get_value (structure,
1536             GST_QUARK (RUNNING_TIME)));
1537 }
1538
1539 /**
1540  * gst_message_parse_request_state:
1541  * @message: A valid #GstMessage of type GST_MESSAGE_REQUEST_STATE.
1542  * @state: (out): Result location for the requested state or NULL
1543  *
1544  * Extract the requested state from the request_state message.
1545  *
1546  * MT safe.
1547  */
1548 void
1549 gst_message_parse_request_state (GstMessage * message, GstState * state)
1550 {
1551   GstStructure *structure;
1552
1553   g_return_if_fail (GST_IS_MESSAGE (message));
1554   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_REQUEST_STATE);
1555
1556   structure = GST_MESSAGE_STRUCTURE (message);
1557   if (state)
1558     *state = (GstState)
1559         g_value_get_enum (gst_structure_id_get_value (structure,
1560             GST_QUARK (NEW_STATE)));
1561 }
1562
1563 /**
1564  * gst_message_new_stream_status:
1565  * @src: The object originating the message.
1566  * @type: The stream status type.
1567  * @owner: (transfer none): the owner element of @src.
1568  *
1569  * Create a new stream status message. This message is posted when a streaming
1570  * thread is created/destroyed or when the state changed.
1571  *
1572  * Returns: (transfer full): the new stream status message.
1573  *
1574  * MT safe.
1575  */
1576 GstMessage *
1577 gst_message_new_stream_status (GstObject * src, GstStreamStatusType type,
1578     GstElement * owner)
1579 {
1580   GstMessage *message;
1581   GstStructure *structure;
1582
1583   structure = gst_structure_new_id (GST_QUARK (MESSAGE_STREAM_STATUS),
1584       GST_QUARK (TYPE), GST_TYPE_STREAM_STATUS_TYPE, (gint) type,
1585       GST_QUARK (OWNER), GST_TYPE_ELEMENT, owner, NULL);
1586   message = gst_message_new_custom (GST_MESSAGE_STREAM_STATUS, src, structure);
1587
1588   return message;
1589 }
1590
1591 /**
1592  * gst_message_parse_stream_status:
1593  * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
1594  * @type: (out): A pointer to hold the status type
1595  * @owner: (out) (transfer none): The owner element of the message source
1596  *
1597  * Extracts the stream status type and owner the GstMessage. The returned
1598  * owner remains valid for as long as the reference to @message is valid and
1599  * should thus not be unreffed.
1600  *
1601  * MT safe.
1602  */
1603 void
1604 gst_message_parse_stream_status (GstMessage * message,
1605     GstStreamStatusType * type, GstElement ** owner)
1606 {
1607   const GValue *owner_gvalue;
1608   GstStructure *structure;
1609
1610   g_return_if_fail (GST_IS_MESSAGE (message));
1611   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_STATUS);
1612
1613   structure = GST_MESSAGE_STRUCTURE (message);
1614   owner_gvalue = gst_structure_id_get_value (structure, GST_QUARK (OWNER));
1615   g_return_if_fail (owner_gvalue != NULL);
1616
1617   if (type)
1618     *type = (GstStreamStatusType)
1619         g_value_get_enum (gst_structure_id_get_value (structure,
1620             GST_QUARK (TYPE)));
1621   if (owner)
1622     *owner = (GstElement *) g_value_get_object (owner_gvalue);
1623 }
1624
1625 /**
1626  * gst_message_set_stream_status_object:
1627  * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
1628  * @object: the object controlling the streaming
1629  *
1630  * Configures the object handling the streaming thread. This is usually a
1631  * GstTask object but other objects might be added in the future.
1632  */
1633 void
1634 gst_message_set_stream_status_object (GstMessage * message,
1635     const GValue * object)
1636 {
1637   GstStructure *structure;
1638
1639   g_return_if_fail (GST_IS_MESSAGE (message));
1640   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_STATUS);
1641
1642   structure = GST_MESSAGE_STRUCTURE (message);
1643   gst_structure_id_set_value (structure, GST_QUARK (OBJECT), object);
1644 }
1645
1646 /**
1647  * gst_message_get_stream_status_object:
1648  * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
1649  *
1650  * Extracts the object managing the streaming thread from @message.
1651  *
1652  * Returns: a GValue containing the object that manages the streaming thread.
1653  * This object is usually of type GstTask but other types can be added in the
1654  * future. The object remains valid as long as @message is valid.
1655  */
1656 const GValue *
1657 gst_message_get_stream_status_object (GstMessage * message)
1658 {
1659   const GValue *result;
1660   GstStructure *structure;
1661
1662   g_return_val_if_fail (GST_IS_MESSAGE (message), NULL);
1663   g_return_val_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STREAM_STATUS,
1664       NULL);
1665
1666   structure = GST_MESSAGE_STRUCTURE (message);
1667   result = gst_structure_id_get_value (structure, GST_QUARK (OBJECT));
1668
1669   return result;
1670 }
1671
1672 /**
1673  * gst_message_new_step_done:
1674  * @src: The object originating the message.
1675  * @format: the format of @amount
1676  * @amount: the amount of stepped data
1677  * @rate: the rate of the stepped amount
1678  * @flush: is this an flushing step
1679  * @intermediate: is this an intermediate step
1680  * @duration: the duration of the data
1681  * @eos: the step caused EOS
1682  *
1683  * This message is posted by elements when they complete a part, when @intermediate set
1684  * to TRUE, or a complete step operation.
1685  *
1686  * @duration will contain the amount of time (in GST_FORMAT_TIME) of the stepped
1687  * @amount of media in format @format.
1688  *
1689  * Returns: (transfer full): the new step_done message.
1690  *
1691  * MT safe.
1692  */
1693 GstMessage *
1694 gst_message_new_step_done (GstObject * src, GstFormat format, guint64 amount,
1695     gdouble rate, gboolean flush, gboolean intermediate, guint64 duration,
1696     gboolean eos)
1697 {
1698   GstMessage *message;
1699   GstStructure *structure;
1700
1701   structure = gst_structure_new_id (GST_QUARK (MESSAGE_STEP_DONE),
1702       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1703       GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1704       GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1705       GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1706       GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate,
1707       GST_QUARK (DURATION), G_TYPE_UINT64, duration,
1708       GST_QUARK (EOS), G_TYPE_BOOLEAN, eos, NULL);
1709   message = gst_message_new_custom (GST_MESSAGE_STEP_DONE, src, structure);
1710
1711   return message;
1712 }
1713
1714 /**
1715  * gst_message_parse_step_done:
1716  * @message: A valid #GstMessage of type GST_MESSAGE_STEP_DONE.
1717  * @format: (out) (allow-none): result location for the format
1718  * @amount: (out) (allow-none): result location for the amount
1719  * @rate: (out) (allow-none): result location for the rate
1720  * @flush: (out) (allow-none): result location for the flush flag
1721  * @intermediate: (out) (allow-none): result location for the intermediate flag
1722  * @duration: (out) (allow-none): result location for the duration
1723  * @eos: (out) (allow-none): result location for the EOS flag
1724  *
1725  * Extract the values the step_done message.
1726  *
1727  * MT safe.
1728  */
1729 void
1730 gst_message_parse_step_done (GstMessage * message, GstFormat * format,
1731     guint64 * amount, gdouble * rate, gboolean * flush, gboolean * intermediate,
1732     guint64 * duration, gboolean * eos)
1733 {
1734   GstStructure *structure;
1735
1736   g_return_if_fail (GST_IS_MESSAGE (message));
1737   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STEP_DONE);
1738
1739   structure = GST_MESSAGE_STRUCTURE (message);
1740   gst_structure_id_get (structure,
1741       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1742       GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1743       GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1744       GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1745       GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate,
1746       GST_QUARK (DURATION), G_TYPE_UINT64, duration,
1747       GST_QUARK (EOS), G_TYPE_BOOLEAN, eos, NULL);
1748 }
1749
1750 /**
1751  * gst_message_new_step_start:
1752  * @src: The object originating the message.
1753  * @active: if the step is active or queued
1754  * @format: the format of @amount
1755  * @amount: the amount of stepped data
1756  * @rate: the rate of the stepped amount
1757  * @flush: is this an flushing step
1758  * @intermediate: is this an intermediate step
1759  *
1760  * This message is posted by elements when they accept or activate a new step
1761  * event for @amount in @format.
1762  *
1763  * @active is set to FALSE when the element accepted the new step event and has
1764  * queued it for execution in the streaming threads.
1765  *
1766  * @active is set to TRUE when the element has activated the step operation and
1767  * is now ready to start executing the step in the streaming thread. After this
1768  * message is emited, the application can queue a new step operation in the
1769  * element.
1770  *
1771  * Returns: (transfer full): The new step_start message.
1772  *
1773  * MT safe.
1774  */
1775 GstMessage *
1776 gst_message_new_step_start (GstObject * src, gboolean active, GstFormat format,
1777     guint64 amount, gdouble rate, gboolean flush, gboolean intermediate)
1778 {
1779   GstMessage *message;
1780   GstStructure *structure;
1781
1782   structure = gst_structure_new_id (GST_QUARK (MESSAGE_STEP_START),
1783       GST_QUARK (ACTIVE), G_TYPE_BOOLEAN, active,
1784       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1785       GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1786       GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1787       GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1788       GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate, NULL);
1789   message = gst_message_new_custom (GST_MESSAGE_STEP_START, src, structure);
1790
1791   return message;
1792 }
1793
1794 /**
1795  * gst_message_parse_step_start:
1796  * @message: A valid #GstMessage of type GST_MESSAGE_STEP_DONE.
1797  * @active: (out) (allow-none): result location for the active flag
1798  * @format: (out) (allow-none): result location for the format
1799  * @amount: (out) (allow-none): result location for the amount
1800  * @rate: (out) (allow-none): result location for the rate
1801  * @flush: (out) (allow-none): result location for the flush flag
1802  * @intermediate: (out) (allow-none): result location for the intermediate flag
1803  *
1804  * Extract the values from step_start message.
1805  *
1806  * MT safe.
1807  */
1808 void
1809 gst_message_parse_step_start (GstMessage * message, gboolean * active,
1810     GstFormat * format, guint64 * amount, gdouble * rate, gboolean * flush,
1811     gboolean * intermediate)
1812 {
1813   GstStructure *structure;
1814
1815   g_return_if_fail (GST_IS_MESSAGE (message));
1816   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_STEP_START);
1817
1818   structure = GST_MESSAGE_STRUCTURE (message);
1819   gst_structure_id_get (structure,
1820       GST_QUARK (ACTIVE), G_TYPE_BOOLEAN, active,
1821       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1822       GST_QUARK (AMOUNT), G_TYPE_UINT64, amount,
1823       GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
1824       GST_QUARK (FLUSH), G_TYPE_BOOLEAN, flush,
1825       GST_QUARK (INTERMEDIATE), G_TYPE_BOOLEAN, intermediate, NULL);
1826 }
1827
1828 /**
1829  * gst_message_new_qos:
1830  * @src: The object originating the message.
1831  * @live: if the message was generated by a live element
1832  * @running_time: the running time of the buffer that generated the message
1833  * @stream_time: the stream time of the buffer that generated the message
1834  * @timestamp: the timestamps of the buffer that generated the message
1835  * @duration: the duration of the buffer that generated the message
1836  *
1837  * A QOS message is posted on the bus whenever an element decides to drop a
1838  * buffer because of QoS reasons or whenever it changes its processing strategy
1839  * because of QoS reasons (quality adjustments such as processing at lower
1840  * accuracy).
1841  *
1842  * This message can be posted by an element that performs synchronisation against the
1843  * clock (live) or it could be dropped by an element that performs QoS because of QOS
1844  * events received from a downstream element (!live).
1845  *
1846  * @running_time, @stream_time, @timestamp, @duration should be set to the
1847  * respective running-time, stream-time, timestamp and duration of the (dropped)
1848  * buffer that generated the QoS event. Values can be left to
1849  * GST_CLOCK_TIME_NONE when unknown.
1850  *
1851  * Returns: (transfer full): The new qos message.
1852  *
1853  * MT safe.
1854  */
1855 GstMessage *
1856 gst_message_new_qos (GstObject * src, gboolean live, guint64 running_time,
1857     guint64 stream_time, guint64 timestamp, guint64 duration)
1858 {
1859   GstMessage *message;
1860   GstStructure *structure;
1861
1862   structure = gst_structure_new_id (GST_QUARK (MESSAGE_QOS),
1863       GST_QUARK (LIVE), G_TYPE_BOOLEAN, live,
1864       GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time,
1865       GST_QUARK (STREAM_TIME), G_TYPE_UINT64, stream_time,
1866       GST_QUARK (TIMESTAMP), G_TYPE_UINT64, timestamp,
1867       GST_QUARK (DURATION), G_TYPE_UINT64, duration,
1868       GST_QUARK (JITTER), G_TYPE_INT64, (gint64) 0,
1869       GST_QUARK (PROPORTION), G_TYPE_DOUBLE, (gdouble) 1.0,
1870       GST_QUARK (QUALITY), G_TYPE_INT, (gint) 1000000,
1871       GST_QUARK (FORMAT), GST_TYPE_FORMAT, GST_FORMAT_UNDEFINED,
1872       GST_QUARK (PROCESSED), G_TYPE_UINT64, (guint64) - 1,
1873       GST_QUARK (DROPPED), G_TYPE_UINT64, (guint64) - 1, NULL);
1874   message = gst_message_new_custom (GST_MESSAGE_QOS, src, structure);
1875
1876   return message;
1877 }
1878
1879 /**
1880  * gst_message_set_qos_values:
1881  * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
1882  * @jitter: The difference of the running-time against the deadline.
1883  * @proportion: Long term prediction of the ideal rate relative to normal rate
1884  * to get optimal quality.
1885  * @quality: An element dependent integer value that specifies the current
1886  * quality level of the element. The default maximum quality is 1000000.
1887  *
1888  * Set the QoS values that have been calculated/analysed from the QoS data
1889  *
1890  * MT safe.
1891  */
1892 void
1893 gst_message_set_qos_values (GstMessage * message, gint64 jitter,
1894     gdouble proportion, gint quality)
1895 {
1896   GstStructure *structure;
1897
1898   g_return_if_fail (GST_IS_MESSAGE (message));
1899   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
1900
1901   structure = GST_MESSAGE_STRUCTURE (message);
1902   gst_structure_id_set (structure,
1903       GST_QUARK (JITTER), G_TYPE_INT64, jitter,
1904       GST_QUARK (PROPORTION), G_TYPE_DOUBLE, proportion,
1905       GST_QUARK (QUALITY), G_TYPE_INT, quality, NULL);
1906 }
1907
1908 /**
1909  * gst_message_set_qos_stats:
1910  * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
1911  * @format: Units of the 'processed' and 'dropped' fields. Video sinks and video
1912  * filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters
1913  * will likely use GST_FORMAT_DEFAULT (samples).
1914  * @processed: Total number of units correctly processed since the last state
1915  * change to READY or a flushing operation.
1916  * @dropped: Total number of units dropped since the last state change to READY
1917  * or a flushing operation.
1918  *
1919  * Set the QoS stats representing the history of the current continuous pipeline
1920  * playback period.
1921  *
1922  * When @format is @GST_FORMAT_UNDEFINED both @dropped and @processed are
1923  * invalid. Values of -1 for either @processed or @dropped mean unknown values.
1924  *
1925  * MT safe.
1926  */
1927 void
1928 gst_message_set_qos_stats (GstMessage * message, GstFormat format,
1929     guint64 processed, guint64 dropped)
1930 {
1931   GstStructure *structure;
1932
1933   g_return_if_fail (GST_IS_MESSAGE (message));
1934   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
1935
1936   structure = GST_MESSAGE_STRUCTURE (message);
1937   gst_structure_id_set (structure,
1938       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
1939       GST_QUARK (PROCESSED), G_TYPE_UINT64, processed,
1940       GST_QUARK (DROPPED), G_TYPE_UINT64, dropped, NULL);
1941 }
1942
1943 /**
1944  * gst_message_parse_qos:
1945  * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
1946  * @live: (out) (allow-none): if the message was generated by a live element
1947  * @running_time: (out) (allow-none): the running time of the buffer that
1948  *     generated the message
1949  * @stream_time: (out) (allow-none): the stream time of the buffer that
1950  *     generated the message
1951  * @timestamp: (out) (allow-none): the timestamps of the buffer that
1952  *     generated the message
1953  * @duration: (out) (allow-none): the duration of the buffer that
1954  *     generated the message
1955  *
1956  * Extract the timestamps and live status from the QoS message.
1957  *
1958  * The returned values give the running_time, stream_time, timestamp and
1959  * duration of the dropped buffer. Values of GST_CLOCK_TIME_NONE mean unknown
1960  * values.
1961  *
1962  * MT safe.
1963  */
1964 void
1965 gst_message_parse_qos (GstMessage * message, gboolean * live,
1966     guint64 * running_time, guint64 * stream_time, guint64 * timestamp,
1967     guint64 * duration)
1968 {
1969   GstStructure *structure;
1970
1971   g_return_if_fail (GST_IS_MESSAGE (message));
1972   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
1973
1974   structure = GST_MESSAGE_STRUCTURE (message);
1975   gst_structure_id_get (structure,
1976       GST_QUARK (LIVE), G_TYPE_BOOLEAN, live,
1977       GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time,
1978       GST_QUARK (STREAM_TIME), G_TYPE_UINT64, stream_time,
1979       GST_QUARK (TIMESTAMP), G_TYPE_UINT64, timestamp,
1980       GST_QUARK (DURATION), G_TYPE_UINT64, duration, NULL);
1981 }
1982
1983 /**
1984  * gst_message_parse_qos_values:
1985  * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
1986  * @jitter: (out) (allow-none): The difference of the running-time against
1987  *     the deadline.
1988  * @proportion: (out) (allow-none): Long term prediction of the ideal rate
1989  *     relative to normal rate to get optimal quality.
1990  * @quality: (out) (allow-none): An element dependent integer value that
1991  *     specifies the current quality level of the element. The default
1992  *     maximum quality is 1000000.
1993  *
1994  * Extract the QoS values that have been calculated/analysed from the QoS data
1995  *
1996  * MT safe.
1997  */
1998 void
1999 gst_message_parse_qos_values (GstMessage * message, gint64 * jitter,
2000     gdouble * proportion, gint * quality)
2001 {
2002   GstStructure *structure;
2003
2004   g_return_if_fail (GST_IS_MESSAGE (message));
2005   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
2006
2007   structure = GST_MESSAGE_STRUCTURE (message);
2008   gst_structure_id_get (structure,
2009       GST_QUARK (JITTER), G_TYPE_INT64, jitter,
2010       GST_QUARK (PROPORTION), G_TYPE_DOUBLE, proportion,
2011       GST_QUARK (QUALITY), G_TYPE_INT, quality, NULL);
2012 }
2013
2014 /**
2015  * gst_message_parse_qos_stats:
2016  * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
2017  * @format: (out) (allow-none): Units of the 'processed' and 'dropped' fields.
2018  *     Video sinks and video filters will use GST_FORMAT_BUFFERS (frames).
2019  *     Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT
2020  *     (samples).
2021  * @processed: (out) (allow-none): Total number of units correctly processed
2022  *     since the last state change to READY or a flushing operation.
2023  * @dropped: (out) (allow-none): Total number of units dropped since the last
2024  *     state change to READY or a flushing operation.
2025  *
2026  * Extract the QoS stats representing the history of the current continuous
2027  * pipeline playback period.
2028  *
2029  * When @format is @GST_FORMAT_UNDEFINED both @dropped and @processed are
2030  * invalid. Values of -1 for either @processed or @dropped mean unknown values.
2031  *
2032  * MT safe.
2033  */
2034 void
2035 gst_message_parse_qos_stats (GstMessage * message, GstFormat * format,
2036     guint64 * processed, guint64 * dropped)
2037 {
2038   GstStructure *structure;
2039
2040   g_return_if_fail (GST_IS_MESSAGE (message));
2041   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_QOS);
2042
2043   structure = GST_MESSAGE_STRUCTURE (message);
2044   gst_structure_id_get (structure,
2045       GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
2046       GST_QUARK (PROCESSED), G_TYPE_UINT64, processed,
2047       GST_QUARK (DROPPED), G_TYPE_UINT64, dropped, NULL);
2048 }
2049
2050 /**
2051  * gst_message_new_progress:
2052  * @src: The object originating the message.
2053  * @type: a #GstProgressType
2054  * @code: a progress code
2055  * @text: free, user visible text describing the progress
2056  *
2057  * Progress messages are posted by elements when they use an asynchronous task
2058  * to perform actions triggered by a state change.
2059  *
2060  * @code contains a well defined string describing the action.
2061  * @test should contain a user visible string detailing the current action.
2062  *
2063  * Returns: (transfer full): The new qos message.
2064  */
2065 GstMessage *
2066 gst_message_new_progress (GstObject * src, GstProgressType type,
2067     const gchar * code, const gchar * text)
2068 {
2069   GstMessage *message;
2070   GstStructure *structure;
2071   gint percent = 100, timeout = -1;
2072
2073   g_return_val_if_fail (code != NULL, NULL);
2074   g_return_val_if_fail (text != NULL, NULL);
2075
2076   if (type == GST_PROGRESS_TYPE_START || type == GST_PROGRESS_TYPE_CONTINUE)
2077     percent = 0;
2078
2079   structure = gst_structure_new_id (GST_QUARK (MESSAGE_PROGRESS),
2080       GST_QUARK (TYPE), GST_TYPE_PROGRESS_TYPE, type,
2081       GST_QUARK (CODE), G_TYPE_STRING, code,
2082       GST_QUARK (TEXT), G_TYPE_STRING, text,
2083       GST_QUARK (PERCENT), G_TYPE_INT, percent,
2084       GST_QUARK (TIMEOUT), G_TYPE_INT, timeout, NULL);
2085   message = gst_message_new_custom (GST_MESSAGE_PROGRESS, src, structure);
2086
2087   return message;
2088 }
2089
2090 /**
2091  * gst_message_parse_progress:
2092  * @message: A valid #GstMessage of type GST_MESSAGE_PROGRESS.
2093  * @type: (out) (allow-none): location for the type
2094  * @code: (out) (allow-none) (transfer full): location for the code
2095  * @text: (out) (allow-none) (transfer full): location for the text
2096  *
2097  * Parses the progress @type, @code and @text.
2098  */
2099 void
2100 gst_message_parse_progress (GstMessage * message, GstProgressType * type,
2101     gchar ** code, gchar ** text)
2102 {
2103   GstStructure *structure;
2104
2105   g_return_if_fail (GST_IS_MESSAGE (message));
2106   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_PROGRESS);
2107
2108   structure = GST_MESSAGE_STRUCTURE (message);
2109   gst_structure_id_get (structure,
2110       GST_QUARK (TYPE), GST_TYPE_PROGRESS_TYPE, type,
2111       GST_QUARK (CODE), G_TYPE_STRING, code,
2112       GST_QUARK (TEXT), G_TYPE_STRING, text, NULL);
2113 }
2114
2115 /**
2116  * gst_message_new_toc:
2117  * @src: the object originating the message.
2118  * @toc: (transfer none): #GstToc structure for the message.
2119  * @updated: whether TOC was updated or not.
2120  *
2121  * Create a new TOC message. The message is posted by elements
2122  * that discovered or updated a TOC.
2123  *
2124  * Returns: (transfer full): a new TOC message.
2125  *
2126  * MT safe.
2127  */
2128 GstMessage *
2129 gst_message_new_toc (GstObject * src, GstToc * toc, gboolean updated)
2130 {
2131   GstStructure *toc_struct;
2132
2133   g_return_val_if_fail (toc != NULL, NULL);
2134
2135   toc_struct = gst_structure_new_id (GST_QUARK (MESSAGE_TOC),
2136       GST_QUARK (TOC), GST_TYPE_TOC, toc,
2137       GST_QUARK (UPDATED), G_TYPE_BOOLEAN, updated, NULL);
2138
2139   return gst_message_new_custom (GST_MESSAGE_TOC, src, toc_struct);
2140 }
2141
2142 /**
2143  * gst_message_parse_toc:
2144  * @message: a valid #GstMessage of type GST_MESSAGE_TOC.
2145  * @toc: (out) (transfer full): return location for the TOC.
2146  * @updated: (out): return location for the updated flag.
2147  *
2148  * Extract thef TOC from the #GstMessage. The TOC returned in the
2149  * output argument is a copy; the caller must free it with
2150  * gst_toc_unref() when done.
2151  *
2152  * MT safe.
2153  */
2154 void
2155 gst_message_parse_toc (GstMessage * message, GstToc ** toc, gboolean * updated)
2156 {
2157   g_return_if_fail (GST_IS_MESSAGE (message));
2158   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_TOC);
2159   g_return_if_fail (toc != NULL);
2160
2161   gst_structure_id_get (GST_MESSAGE_STRUCTURE (message),
2162       GST_QUARK (TOC), GST_TYPE_TOC, toc,
2163       GST_QUARK (UPDATED), G_TYPE_BOOLEAN, updated, NULL);
2164 }
2165
2166 /**
2167  * gst_message_new_reset_time:
2168  * @src: (transfer none): The object originating the message.
2169  * @running_time: the requested running-time
2170  *
2171  * This message is posted when the pipeline running-time should be reset to
2172  * @running_time, like after a flushing seek.
2173  *
2174  * Returns: (transfer full): The new reset_time message.
2175  *
2176  * MT safe.
2177  */
2178 GstMessage *
2179 gst_message_new_reset_time (GstObject * src, GstClockTime running_time)
2180 {
2181   GstMessage *message;
2182   GstStructure *structure;
2183
2184   structure = gst_structure_new_id (GST_QUARK (MESSAGE_RESET_TIME),
2185       GST_QUARK (RUNNING_TIME), G_TYPE_UINT64, running_time, NULL);
2186   message = gst_message_new_custom (GST_MESSAGE_RESET_TIME, src, structure);
2187
2188   return message;
2189 }
2190
2191 /**
2192  * gst_message_parse_reset_time:
2193  * @message: A valid #GstMessage of type GST_MESSAGE_RESET_TIME.
2194  * @running_time: (out): Result location for the running_time or NULL
2195  *
2196  * Extract the running-time from the RESET_TIME message.
2197  *
2198  * MT safe.
2199  */
2200 void
2201 gst_message_parse_reset_time (GstMessage * message, GstClockTime * running_time)
2202 {
2203   GstStructure *structure;
2204
2205   g_return_if_fail (GST_IS_MESSAGE (message));
2206   g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_RESET_TIME);
2207
2208   structure = GST_MESSAGE_STRUCTURE (message);
2209   if (running_time)
2210     *running_time =
2211         g_value_get_uint64 (gst_structure_id_get_value (structure,
2212             GST_QUARK (RUNNING_TIME)));
2213 }
2214
2215 /**
2216  * gst_message_new_stream_start:
2217  * @src: (transfer none): The object originating the message.
2218  *
2219  * Create a new stream_start message. This message is generated and posted in
2220  * the sink elements of a GstBin. The bin will only forward the STREAM_START
2221  * message to the application if all sinks have posted an STREAM_START message.
2222  *
2223  * Returns: (transfer full): The new stream_start message.
2224  *
2225  * MT safe.
2226  */
2227 GstMessage *
2228 gst_message_new_stream_start (GstObject * src)
2229 {
2230   GstMessage *message;
2231
2232   message = gst_message_new_custom (GST_MESSAGE_STREAM_START, src, NULL);
2233
2234   return message;
2235 }