<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Message types</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79;charset=UTF-8"><LINK
REL="HOME"
TITLE="GStreamer Application Development Manual (0.10.36)"
HREF="index.html"><LINK
REL="UP"
TITLE="Bus"
HREF="chapter-bus.html"><LINK
REL="PREVIOUS"
TITLE="Bus"
HREF="chapter-bus.html"><LINK
REL="NEXT"
TITLE="Pads and capabilities"
HREF="chapter-pads.html"></HEAD
><BODY
CLASS="sect1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
><SPAN
CLASS="application"
>GStreamer</SPAN
> Application Development Manual (0.10.36)</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="chapter-bus.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 7. Bus</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="chapter-pads.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="section-bus-message-types"
>7.2. Message types</A
></H1
><P
> <SPAN
CLASS="application"
>GStreamer</SPAN
> has a few pre-defined message types that can be passed
over the bus. The messages are extensible, however. Plug-ins can
define additional messages, and applications can decide to either
have specific code for those or ignore them. All applications are
strongly recommended to at least handle error messages by providing
visual feedback to the user.
</P
><P
> All messages have a message source, type and timestamp. The message
source can be used to see which element emitted the message. For some
messages, for example, only the ones emitted by the top-level pipeline
will be interesting to most applications (e.g. for state-change
notifications). Below is a list of all messages and a short explanation
of what they do and how to parse message-specific content.
</P
><P
></P
><UL
><LI
><P
> Error, warning and information notifications: those are used
by elements if a message should be shown to the user about the
state of the pipeline. Error messages are fatal and terminate
the data-passing. The error should be repaired to resume pipeline
activity. Warnings are not fatal, but imply a problem nevertheless.
Information messages are for non-problem notifications. All those
messages contain a <CODE
CLASS="classname"
>GError</CODE
> with the main
error type and message, and optionally a debug string. Both
can be extracted using <CODE
CLASS="function"
>gst_message_parse_error
()</CODE
>, <CODE
CLASS="function"
>_parse_warning ()</CODE
> and
<CODE
CLASS="function"
>_parse_info ()</CODE
>. Both error and debug strings
should be freed after use.
</P
></LI
><LI
><P
> End-of-stream notification: this is emitted when the stream has
ended. The state of the pipeline will not change, but further
media handling will stall. Applications can use this to skip to
the next song in their playlist. After end-of-stream, it is also
possible to seek back in the stream. Playback will then continue
automatically. This message has no specific arguments.
</P
></LI
><LI
><P
> Tags: emitted when metadata was found in the stream. This can be
emitted multiple times for a pipeline (e.g. once for descriptive
metadata such as artist name or song title, and another one for
stream-information, such as samplerate and bitrate). Applications
should cache metadata internally. <CODE
CLASS="function"
>gst_message_parse_tag
()</CODE
> should be used to parse the taglist, which should
be <CODE
CLASS="function"
>gst_tag_list_free ()</CODE
>'ed when no longer
needed.
</P
></LI
><LI
><P
> State-changes: emitted after a successful state change.
<CODE
CLASS="function"
>gst_message_parse_state_changed ()</CODE
> can be
used to parse the old and new state of this transition.
</P
></LI
><LI
><P
> Buffering: emitted during caching of network-streams. One can
manually extract the progress (in percent) from the message by
extracting the <SPAN
CLASS="QUOTE"
>"buffer-percent"</SPAN
> property from the
structure returned by <CODE
CLASS="function"
>gst_message_get_structure
()</CODE
>.
</P
></LI
><LI
><P
> Element messages: these are special messages that are unique to
certain elements and usually represent additional features. The
element's documentation should mention in detail which
element messages a particular element may send. As an example,
the 'qtdemux' QuickTime demuxer element may send a 'redirect'
element message on certain occasions if the stream contains a
redirect instruction.
</P
></LI
><LI
><P
> Application-specific messages: any information on those can
be extracted by getting the message structure (see above) and
reading its fields. Usually these messages can safely be ignored.
</P
><P
> Application messages are primarily meant for internal
use in applications in case the application needs to marshal
information from some thread into the main thread. This is
particularly useful when the application is making use of element
signals (as those signals will be emitted in the context of the
streaming thread).
</P
></LI
></UL
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="chapter-bus.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="chapter-pads.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Bus</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="chapter-bus.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Pads and capabilities</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
