gst/gstmessage.c

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