docs/design/part-messages.txt

   1 Messages
   2 --------
   3
   4 Messages are refcounted lightweight objects to signal the application
   5 of pipeline events.
   6
   7 Messages are implemented as a subclass of GstMiniObject with a generic
   8 GstStructure as the content. This allows for writing custom messages without
   9 requiring an API change while allowing a wide range of different types
  10 of messages.
  11
  12 Messages are posted by objects in the pipeline and are passed to the
  13 application using the GstBus (See also part-gstbus.txt and part-gstpipeline.txt).
  14
  15
  16 Message types
  17 ~~~~~~~~~~~~~
  18
  19 GST_MESSAGE_EOS:
  20
  21   Posted by sink elements. This message is posted to the application when all
  22   the sinks in a pipeline have posted an EOS message. When performing a
  23   flushing seek, the EOS state of the pipeline and sinks is reset.
  24
  25 GST_MESSAGE_ERROR:
  26
  27   An element in the pipeline got into an error state. The message carries
  28   a GError and a debug string describing the error. This usually means that
  29   part of the pipeline is not streaming anymore.
  30
  31 GST_MESSAGE_WARNING:
  32
  33   An element in the pipeline encountered a condition that made it produce a
  34   warning. This could be a recoverable decoding error or some other non fatal
  35   event. The pipeline continues streaming after a warning.
  36
  37 GST_MESSAGE_INFO:
  38
  39   An element produced an informational message.
  40
  41 GST_MESSAGE_TAG:
  42
  43   An element decoded metadata about the stream. The message carries a GstTagList
  44   with the tag information.
  45
  46 GST_MESSAGE_BUFFERING:
  47
  48   An element is buffering data and that could potentially take some time. This
  49   message is typically emitted by elements that perform some sort of network
  50   buffering. While the pipeline is buffering it should remain in the PAUSED
  51   state. When the buffering is finished, it can resume PLAYING.
  52
  53 GST_MESSAGE_STATE_CHANGED:
  54
  55   An element changed state in the pipeline. The message carries the old, new
  56   and pending state of the element.
  57
  58 GST_MESSAGE_STATE_DIRTY:
  59
  60   An internal message used to instruct a pipeline hierarchy that a state
  61   recalculation must be performed because of an ASYNC state change completed.
  62   This message is not used anymore.
  63
  64 GST_MESSAGE_STEP_DONE:
  65
  66   An element stepping frames has finished. This is currently not used.
  67
  68 GST_MESSAGE_CLOCK_PROVIDE:
  69
  70   An element notifies its capability of providing a clock for the pipeline.
  71
  72 GST_MESSAGE_CLOCK_LOST:
  73
  74   The current clock, as selected by the pipeline, became unusable. The pipeline
  75   will select a new clock on the next PLAYING state change.
  76
  77 GST_MESSAGE_NEW_CLOCK:
  78
  79   A new clock was selected for the pipeline.
  80
  81 GST_MESSAGE_STRUCTURE_CHANGE:
  82
  83   The pipeline changed its structure, This means elements were added or removed or
  84   pads were linked or unlinked. This message is not yet used.
  85
  86 GST_MESSAGE_STREAM_STATUS:
  87
  88   Posted by an element when it starts/stops/pauses a streaming task. It
  89   contains information about the reason why the stream state changed along
  90   with the thread id. The application can use this information to detect
  91   failures in streaming threads and/or to adjust streaming thread priorities.
  92
  93 GST_MESSAGE_APPLICATION:
  94
  95   The application posted a message. This message must be used when the
  96   application posts a message on the bus.
  97
  98 GST_MESSAGE_ELEMENT:
  99
 100   Element-specific message. See the specific element's documentation
 101
 102 GST_MESSAGE_SEGMENT_START:
 103
 104   An element started playback of a new segment. This message is not forwarded
 105   to applications but is used internally to schedule SEGMENT_DONE messages.
 106
 107 GST_MESSAGE_SEGMENT_DONE:
 108
 109   An element or bin completed playback of a segment. This message is only posted
 110   on the bus if a SEGMENT seek is performed on a pipeline.
 111
 112 GST_MESSAGE_DURATION_CHANGED:
 113
 114   An element posts this message when it has detected or updated the stream duration.
 115
 116 GST_MESSAGE_ASYNC_START:
 117
 118   Posted by sinks when they start an asynchronous state change.
 119
 120 GST_MESSAGE_ASYNC_DONE:
 121
 122   Posted by sinks when they receive the first data buffer and complete the
 123   asynchronous state change.
 124
 125 GST_MESSAGE_LATENCY:
 126
 127   Posted by elements when the latency in a pipeline changed and a new global
 128   latency should be calculated by the pipeline or application.
 129
 130 GST_MESSAGE_REQUEST_STATE:
 131
 132   Posted by elements when they want to change the state of the pipeline they
 133   are in. A typical use case would be an audio sink that requests the pipeline
 134   to pause in order to play a higher priority stream.
 135
 136 GST_MESSAGE_STEP_START:
 137
 138   A Stepping operation has started.
 139
 140 GST_MESSAGE_QOS:
 141
 142   A buffer was dropped or an element changed its processing strategy for
 143   Quality of Service reasons.
 144
 145 GST_MESSAGE_PROGRESS:
 146
 147   A progress message was posted. Progress messages inform the application about
 148   the state of asynchronous operations.