<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <HTML ><HEAD ><TITLE >All Events Together</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK REL="HOME" TITLE="GStreamer Plugin Writer's Guide" HREF="index.html"><LINK REL="UP" TITLE="Events: Seeking, Navigation and More" HREF="chapter-advanced-events.html"><LINK REL="PREVIOUS" TITLE="Upstream events" HREF="section-events-upstream.html"><LINK REL="NEXT" TITLE="Other Element Types" HREF="part-other.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 > Plugin Writer's Guide</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="section-events-upstream.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" >Chapter 20. Events: Seeking, Navigation and More</TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="part-other.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="sect1" ><H1 CLASS="sect1" ><A NAME="section-events-definitions" >20.3. All Events Together</A ></H1 ><P > In this chapter follows a list of all defined events that are currently being used, plus how they should be used/interpretted. Events are stored in a <CODE CLASS="classname" >GstEvent</CODE > structure, which is simply a big C union with the types for each event in it. For the next development cycle, we intend to switch events over to <CODE CLASS="classname" >GstStructure</CODE >, but you don't need to worry about that too much for now. </P ><P > In this chapter, we will discuss the following events: </P ><P ></P ><UL ><LI ><P ><A HREF="section-events-definitions.html#section-events-eos" >End of Stream (EOS)</A ></P ></LI ><LI ><P ><A HREF="section-events-definitions.html#section-events-flush" >Flush</A ></P ></LI ><LI ><P ><A HREF="section-events-definitions.html#section-events-discont" >Stream Discontinuity</A ></P ></LI ><LI ><P ><A HREF="section-events-definitions.html#section-events-seek" >Seek Request</A ></P ></LI ><LI ><P ><A HREF="section-events-definitions.html#section-events-filler" >Stream Filler</A ></P ></LI ><LI ><P ><A HREF="section-events-definitions.html#section-events-interrupt" >Interruption</A ></P ></LI ><LI ><P ><A HREF="section-events-definitions.html#section-events-nav" >Navigation</A ></P ></LI ><LI ><P ><A HREF="section-events-definitions.html#section-events-tag" >Tag (metadata)</A ></P ></LI ></UL ><DIV CLASS="sect2" ><H2 CLASS="sect2" ><A NAME="section-events-eos" >20.3.1. End of Stream (EOS)</A ></H2 ><P > End-of-stream events are sent if the stream that an element sends out is finished. An element receiving this event (from upstream, so it receives it on its sinkpad) will generally forward the event further downstream and set itself to EOS (<CODE CLASS="function" >gst_element_set_eos ()</CODE >). <CODE CLASS="function" >gst_pad_event_default ()</CODE > takes care of all this, so most elements do not need to support this event. Exceptions are elements that explicitely need to close a resource down on EOS, and N-to-1 elements. Note that the stream itself is <SPAN CLASS="emphasis" ><I CLASS="emphasis" >not</I ></SPAN > a resource that should be closed down on EOS! Applications might seek back to a point before EOS and set the pipeline to PLAYING again. N-to-1 elements have been discussed previously in <A HREF="chapter-loopbased-loopfn.html#section-loopfn-multiinput" >Multi-Input Elements</A >. </P ><P > The EOS event (<CODE CLASS="classname" >GST_EVENT_EOS</CODE >) has no properties, and that makes it one of the simplest events in <SPAN CLASS="application" >GStreamer</SPAN >. It is created using <CODE CLASS="function" >gst_event_new (GST_EVENT_EOS);</CODE >. </P ><P > Some elements support the EOS event upstream, too. This signals the element to go into EOS as soon as possible and signal the EOS event forward downstream. This is useful for elements that have no concept of end-of-stream themselves. Examples are TV card sources, audio card sources, etc. This is not (yet) part of the official specifications of this event, though. </P ></DIV ><DIV CLASS="sect2" ><H2 CLASS="sect2" ><A NAME="section-events-flush" >20.3.2. Flush</A ></H2 ><P > The flush event is being sent downstream if all buffers and caches in the pipeline should be emptied. <SPAN CLASS="QUOTE" >"Queue"</SPAN > elements will empty their internal list of buffers when they receive this event, for example. File sink elements (e.g. <SPAN CLASS="QUOTE" >"filesink"</SPAN >) will flush the kernel-to-disk cache (<CODE CLASS="function" >fdatasync ()</CODE > or <CODE CLASS="function" >fflush ()</CODE >) when they receive this event. Normally, elements receiving this event will simply just forward it, since most filter or filter-like elements don't have an internal cache of data. <CODE CLASS="function" >gst_pad_event_default ()</CODE > does just that, so for most elements, it is enough to forward the event using the default event handler. </P ><P > The flush event is created with <CODE CLASS="function" >gst_event_new (GST_EVENT_FLUSH);</CODE >. Like the EOS event, it has no properties. </P ></DIV ><DIV CLASS="sect2" ><H2 CLASS="sect2" ><A NAME="section-events-discont" >20.3.3. Stream Discontinuity</A ></H2 ><P > A discontinuity event is sent downstream to indicate a discontinuity in the data stream. This can happen because the application used the seek event to seek to a different position in the stream, but it can also be because a real-time network source temporarily lost the connection. After the connection is restored, the data stream will continue, but not at the same point where it got lost. Therefore, a discontinuity event is being sent downstream, too. </P ><P > Depending on the element type, the event can simply be forwarded using <CODE CLASS="function" >gst_pad_event_default ()</CODE >, or it should be parsed and a modified event should be sent on. The last is true for demuxers, which generally have a byte-to-time conversion concept. Their input is usually byte-based, so the incoming event will have an offset in byte units (<CODE CLASS="classname" >GST_FORMAT_BYTES</CODE >), too. Elements downstream, however, expect discontinuity events in time units, so that it can be used to update the pipeline clock. Therefore, demuxers and similar elements should not forward the event, but parse it, free it and send a new discontinuity event (in time units, <CODE CLASS="classname" >GST_FORMAT_TIME</CODE >) further downstream. </P ><P > The discontinuity event is created using the function <CODE CLASS="function" >gst_event_new_discontinuous ()</CODE >. It should set a boolean value which indicates if the discontinuity event is sent because of a new media type (this can happen if - during iteration - a new location was set on a network source or on a file source). then, it should give a list of formats and offsets in that format. The list should be terminated by 0 as format. </P ><PRE CLASS="programlisting" > static void my_filter_some_function (GstMyFilter *filter) { GstEvent *event; [..] event = gst_event_new_discontinuous (FALSE, GST_FORMAT_BYTES, 0, GST_FORMAT_TIME, 0, 0); gst_pad_push (filter->srcpad, GST_DATA (event)); [..] } </PRE ><P > Elements parsing this event can use macros and functions to access the various properties. <CODE CLASS="function" >GST_EVENT_DISCONT_NEW_MEDIA (event)</CODE > checks the new-media boolean value. <CODE CLASS="function" >gst_event_discont_get_value (event, format, &value)</CODE > gets the offset of the new stream position in the specified format. If that format was not specified when creating the event, the function returns FALSE. </P ></DIV ><DIV CLASS="sect2" ><H2 CLASS="sect2" ><A NAME="section-events-seek" >20.3.4. Seek Request</A ></H2 ><P > Seek events are meant to request a new stream position to elements. This new position can be set in several formats (time, bytes or <SPAN CLASS="QUOTE" >"units"</SPAN > [a term indicating frames for video, samples for audio, etc.]). Seeking can be done with respect to the end-of-file, start-of-file or current position, and can happen in both upstream and downstream direction. Elements receiving seek events should, depending on the element type, either forward it (filters, decoders), change the format in which the event is given and forward it (demuxers), handle the event by changing the file pointer in their internal stream resource (file sources) or something else. </P ><P > Seek events are, like discontinuity events, built up using positions in specified formats (time, bytes, units). They are created using the function <CODE CLASS="function" >gst_event_new_seek ()</CODE >, where the first argument is the seek type (indicating with respect to which position [current, end, start] the seek should be applied, and the format in which the new position is given (time, bytes, units), and an offset which is the requested position in the specified format. </P ><PRE CLASS="programlisting" > static void my_filter_some_function (GstMyFilter *filter) { GstEvent *event; [..] /* seek to the start of a resource */ event = gst_event_new_seek (GST_SEEK_SET | GST_FORMAT_BYTES, 0); gst_pad_push (filter->srcpad, GST_DATA (event)); [..] } </PRE ><P > Elements parsing this event can use macros and functions to access the properties. The seek type can be retrieved using <CODE CLASS="function" >GST_EVENT_SEEK_TYPE (event)</CODE >. This seek type contains both the indicator of with respect to what position the seek should be applied, and the format in which the seek event is given. To get either one of these properties separately, use <CODE CLASS="function" >GST_EVENT_SEEK_FORMAT (event)</CODE > or <CODE CLASS="function" >GST_EVENT_SEEK_METHOD (event)</CODE >. The requested position is available through <CODE CLASS="function" >GST_EVENT_SEEK_OFFSET (event)</CODE >, and is given in the specified format. </P ></DIV ><DIV CLASS="sect2" ><H2 CLASS="sect2" ><A NAME="section-events-filler" >20.3.5. Stream Filler</A ></H2 ><P > The filler event is, as the name says, a <SPAN CLASS="QUOTE" >"filler"</SPAN > of the stream which has no special meaning associated with itself. It is used to provide data to downstream elements and should be interpreted as a way of assuring that the normal data flow will continue further downstream. The event is especially intended for real-time MIDI source elements, which only generate data when something <SPAN CLASS="emphasis" ><I CLASS="emphasis" >changes</I ></SPAN >. MIDI decoders will therefore stall if nothing changes for several seconds, and therefore playback will stop. The filler event is sent downstream to assure the MIDI decoder that nothing changed, so that the normal decoding process will continue and playback will, too. Unless you intend to work with MIDI or other control-language-based data types, you don't need this event. You can mostly simply forward it with <CODE CLASS="function" >gst_pad_event_default ()</CODE >. </P ><P > The stream filler is created using <CODE CLASS="function" >gst_event_new (GST_EVENT_FILLER);</CODE >. It has no properties. </P ></DIV ><DIV CLASS="sect2" ><H2 CLASS="sect2" ><A NAME="section-events-interrupt" >20.3.6. Interruption</A ></H2 ><P > The interrupt event is generated by queue elements and sent downstream if a timeout occurs on the stream. The scheduler will use this event to get back in its own main loop and schedule other elements. This prevents deadlocks or a stream stall if no data is generated over a part of the pipeline for a considerable amount of time. The scheduler will process this event internally, so any normal elements do not need to generate or handle this event at all. </P ><P > The difference between the filler event and the interrupt event is that the filler event is a real part of a pipeline, so it will reach fellow elements, which can use it to "do nothing else than what I used to do". The interrupt event never reaches fellow elements. </P ><P > The interrupt event (<CODE CLASS="function" >gst_event_new (GST_EVENT_INTERRUPT);</CODE >) has no properties. </P ></DIV ><DIV CLASS="sect2" ><H2 CLASS="sect2" ><A NAME="section-events-nav" >20.3.7. Navigation</A ></H2 ><P > WRITEME </P ></DIV ><DIV CLASS="sect2" ><H2 CLASS="sect2" ><A NAME="section-events-tag" >20.3.8. Tag (metadata)</A ></H2 ><P > Tagging events are being sent downstream to indicate the tags as parsed from the stream data. This is currently used to preserve tags during stream transcoding from one format to the other. Tags are discussed extensively in <A HREF="chapter-advanced-tagging.html" >Chapter 19</A >. Most elements will simply forward the event by calling <CODE CLASS="function" >gst_pad_event_default ()</CODE >. </P ><P > The tag event is created using the function <CODE CLASS="function" >gst_event_new_tag ()</CODE >. It requires a filled taglist as argument. </P ><P > Elements parsing this event can use the function <CODE CLASS="function" >gst_event_tag_get_list (event)</CODE > to acquire the taglist that was parsed. </P ></DIV ></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="section-events-upstream.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="part-other.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Upstream events</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="chapter-advanced-events.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Other Element Types</TD ></TR ></TABLE ></DIV ></BODY ></HTML >