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