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