gstreamer/docs/design/part-messages.txt

Messages
--------

Messages are refcounted lightweight objects to signal the application
of pipeline events. 

Messages are implemented as a subclass of GstMiniObject with a generic 
GstStructure as the content. This allows for writing custom messages without
requiring an API change while allowing a wide range of different types
of messages.

Messages are posted by objects in the pipeline and are passed to the 
application using the GstBus. 


Message types
-------------

  GST_MESSAGE_EOS:

    Posted by sink elements. This message is posted to the application when
    all the sinks in a pipeline posted an EOS message. When performing a seek,
    the EOS state of the pipeline and sinks is undone.
  
  GST_MESSAGE_ERROR:
  
    An element in the pipeline got into an error state. The message carries
    a GError and a debug string describing the error. This usually means that
    part of the pipeline is not streaming anymore.
  
  GST_MESSAGE_WARNING:
  
    An element in the pipeline encountered a condition that made it produce a
    warning. This could be a recoverable decoding error or some other non fatal
    event. The pipeline continues streaming after a warning.
  
  GST_MESSAGE_INFO:

    An element produced an informational message.
  
  GST_MESSAGE_TAG:

    An element decoded metadata about the stream. The message carries a GstTagList
    with the tag information.
  
  GST_MESSAGE_BUFFERING:
  
    An element is buffering data and that could potentially take some time. This
    message is typically emited by elements that perform some sort of network
    buffering. While the pipeline is buffering it should remain in the PAUSED
    state. When the buffering is finished, it can resume PLAYING.
  
  GST_MESSAGE_STATE_CHANGED:

    An element changed state in the pipeline. The message carries the old, new
    and pending state of the element.
  
  GST_MESSAGE_STEP_DONE:

    An element stepping frames has finished.
  
  GST_MESSAGE_CLOCK_PROVIDE:

    An element notifies it capability of providing a clock for the pipeline.

  GST_MESSAGE_CLOCK_LOST:

    The current clock as selected by the pipeline became unusable. The pipeline 
    will select a new clock on the next PLAYING state change.

  GST_MESSAGE_NEW_CLOCK:

    A new clock was selected for the pipeline.

  GST_MESSAGE_STRUCTURE_CHANGE:

    The pipeline changed of structure, This means elements were added or removed or
    pads were linked or unlinked.

  GST_MESSAGE_STREAM_STATUS:

    An element posted information about the stream it is handling. This could include
    information about the length of the stream.
    
  GST_MESSAGE_APPLICATION:

    The application posted a message.

  GST_MESSAGE_ELEMENT:

    Element-specific message, see the specific element's documentation

  GST_MESSAGE_SEGMENT_START:

    An element started playback of a new segment. This message is not forwarded
    the the application but is used internally to schedule SEGMENT_DONE messages.

  GST_MESSAGE_SEGMENT_DONE:

    An element or bin completed playback of a segment. This message is only posted
    on the bus if a SEGMENT seek is performed on a pipeline.