<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Upstream events</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="Events: Seeking, Navigation and More"
HREF="chapter-advanced-events.html"><LINK
REL="NEXT"
TITLE="All Events Together"
HREF="section-events-definitions.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="chapter-advanced-events.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="section-events-definitions.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="section-events-upstream"
>20.2. Upstream events</A
></H1
><P
> Upstream events are generated by an element somewhere in the pipeline and
sent using the <CODE
CLASS="function"
>gst_pad_send_event</CODE
> function. This
function simply realizes the pad and call the default event handler of that
pad. The default event handler of pads is <CODE
CLASS="function"
>gst_pad_event_default</CODE
>
, it basically sends the event to the peer pad. So upstream events always
arrive on the src pad of your element and are handled by the default event
handler except if you override that handler to handle it yourself. There
are some specific cases where you have to do that :
</P
><P
></P
><UL
><LI
STYLE="list-style-type: opencircle"
><P
> If you have multiple sink pads in your element. In that case you will
have to decide which one of the sink pads you will send the event to.
</P
></LI
><LI
STYLE="list-style-type: opencircle"
><P
> If you need to handle that event locally. For example a navigation
event that you will want to convert before sending it upstream.
</P
></LI
></UL
><P
> The processing you will do in that event handler does not really matter
but there are important rules you have to absolutely respect because
one broken element event handler is breaking the whole pipeline event
handling. Here they are :
</P
><P
></P
><UL
><LI
STYLE="list-style-type: opencircle"
><P
> Always forward events you won't handle upstream using the default
<CODE
CLASS="function"
>gst_pad_event_default</CODE
> method.
</P
></LI
><LI
STYLE="list-style-type: opencircle"
><P
> If you are generating some new event based on the one you received
don't forget to gst_event_unref the event you received.
</P
></LI
><LI
STYLE="list-style-type: opencircle"
><P
> Event handler function are supposed to return TRUE or FALSE indicating
if the event has been handled or not. Never simply return TRUE/FALSE
in that handler except if you really know that you have handled that
event.
</P
></LI
></UL
><P
> Here is an example of correct upstream event handling for a plugin
that wants to modify navigation events.
</P
><PRE
CLASS="programlisting"
> static gboolean
gst_my_filter_handle_src_event (GstPad *pad,
GstEvent *event)
{
GstMyFilter *filter = GST_MY_FILTER (gst_pad_get_parent (pad));
switch (GST_EVENT_TYPE (event)) {
case GST_EVENT_NAVIGATION:
GstEvent *new_event = gst_event_new (GST_EVENT_NAVIGATION);;
/* Create a new event based on received one and then send it */
...
gst_event_unref (event);
return gst_pad_event_default (pad, new_event);
default:
/* Falling back to default event handling for that pad */
return gst_pad_event_default (pad, event);
}
}
</PRE
></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-advanced-events.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="section-events-definitions.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Events: Seeking, Navigation and More</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"
>All Events Together</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
