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