Upstream events are generated by an element somewhere downstream in the pipeline (example: a video sink may generate navigation events that informs upstream elements about the current position of the mouse pointer). This may also happen indirectly on request of the application, for example when the application executes a seek on a pipeline this seek request will be passed on to a sink element which will then in turn generate an upstream seek event.
The most common upstream events are seek events and Quality-of-Service (QoS) events.
An upstream event can be sent using the
gst_pad_send_event
function. This
function simply call the default event handler of that pad. The default
event handler of pads is gst_pad_event_default
, and
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 :
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 (if not all of them).
If you need to handle that event locally. For example a navigation event that you will want to convert before sending it upstream, or a QoS event that you want to handle.
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 :
Always forward events you won't handle upstream using the default
gst_pad_event_default
method.
If you are generating some new event based on the one you received don't forget to gst_event_unref the event you received.
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.
Remember that the event handler might be called from a different
thread than the streaming thread, so make sure you use
appropriate locking everywhere and at the beginning of the function
obtain a reference to your element via the
gst_pad_get_parent()
(and release it again at
the end of the function with gst_object_unref ()
.