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