markdown/pwg/building/eventfn.md

   1 ---
   2 title: The event function
   3 ...
   4
   5 # The event function
   6
   7 The event function notifies you of special events that happen in the
   8 datastream (such as caps, end-of-stream, newsegment, tags, etc.). Events
   9 can travel both upstream and downstream, so you can receive them on sink
  10 pads as well as source pads.
  11
  12 Below follows a very simple event function that we install on the sink
  13 pad of our element.
  14
  15 ``` c
  16
  17 static gboolean gst_my_filter_sink_event (GstPad    *pad,
  18                                           GstObject *parent,
  19                                           GstEvent  *event);
  20
  21 [..]
  22
  23 static void
  24 gst_my_filter_init (GstMyFilter * filter)
  25 {
  26 [..]
  27   /* configure event function on the pad before adding
  28    * the pad to the element */
  29   gst_pad_set_event_function (filter->sinkpad,
  30       gst_my_filter_sink_event);
  31 [..]
  32 }
  33
  34 static gboolean
  35 gst_my_filter_sink_event (GstPad    *pad,
  36                   GstObject *parent,
  37                   GstEvent  *event)
  38 {
  39   gboolean ret;
  40   GstMyFilter *filter = GST_MY_FILTER (parent);
  41
  42   switch (GST_EVENT_TYPE (event)) {
  43     case GST_EVENT_CAPS:
  44       /* we should handle the format here */
  45
  46       /* push the event downstream */
  47       ret = gst_pad_push_event (filter->srcpad, event);
  48       break;
  49     case GST_EVENT_EOS:
  50       /* end-of-stream, we should close down all stream leftovers here */
  51       gst_my_filter_stop_processing (filter);
  52
  53       ret = gst_pad_event_default (pad, parent, event);
  54       break;
  55     default:
  56       /* just call the default handler */
  57       ret = gst_pad_event_default (pad, parent, event);
  58       break;
  59   }
  60   return ret;
  61 }
  62
  63
  64 ```
  65
  66 It is a good idea to call the default event handler
  67 `gst_pad_event_default ()` for unknown events. Depending on the event
  68 type, the default handler will forward the event or simply unref it. The
  69 CAPS event is by default not forwarded so we need to do this in the
  70 event handler ourselves.