gst/gstmessage.c

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