| |
| <!-- ############ chapter ############# --> |
| |
| <chapter id="chapter-building-eventfn"> |
| <title>The event function</title> |
| <para> |
| The event function notifies you of special events that happen in |
| the datastream (such as caps, end-of-stream, newsegment, tags, etc.). |
| Events can travel both upstream and downstream, so you can receive them |
| on sink pads as well as source pads. |
| </para> |
| <para> |
| Below follows a very simple event function that we install on the sink |
| pad of our element. |
| </para> |
| <programlisting><!-- example-begin event.c a --><!-- |
| #include "init.func" |
| #include "caps.func" |
| static gboolean |
| gst_my_filter_event (GstPad * pad, GstObject * parent, GstEvent * event) |
| { |
| return gst_pad_event_default (pad, parent, event); |
| } |
| --><!-- example-end event.c a --> |
| static gboolean gst_my_filter_sink_event (GstPad *pad, |
| GstObject *parent, |
| GstBuffer *buf); |
| |
| [..] |
| |
| static void |
| gst_my_filter_init (GstMyFilter * filter) |
| { |
| [..] |
| /* configure event function on the pad before adding |
| * the pad to the element */ |
| gst_pad_set_event_function (filter->sinkpad, |
| gst_my_filter_sink_event); |
| [..] |
| } |
| |
| static gboolean |
| gst_my_filter_sink_event (GstPad *pad, |
| GstObject *parent, |
| GstEvent *event) |
| { |
| gboolean ret; |
| GstMyFilter *filter = GST_MY_FILTER (parent); |
| |
| switch (GST_EVENT_TYPE (event)) { |
| case GST_EVENT_CAPS: |
| /* we should handle the format here */ |
| |
| /* push the event downstream */ |
| ret = gst_pad_push_event (filter->srcpad, event); |
| break; |
| case GST_EVENT_EOS: |
| /* end-of-stream, we should close down all stream leftovers here */ |
| gst_my_filter_stop_processing (filter); |
| |
| ret = gst_pad_event_default (pad, parent, event); |
| break; |
| default: |
| /* just call the default handler */ |
| ret = gst_pad_event_default (pad, parent, event); |
| break; |
| } |
| return ret; |
| } |
| </programlisting> |
| <para> |
| It is a good idea to call the default event handler |
| <function>gst_pad_event_default ()</function> for unknown events. |
| Depending on the event type, the default handler will forward |
| the event or simply unref it. The CAPS event is by default not |
| forwarded so we need to do this in the event handler ourselves. |
| </para> |
| </chapter> |