gstreamer/docs/gst/tmpl/gstevent.sgml

<!-- ##### SECTION Title ##### -->
GstEvent

<!-- ##### SECTION Short_Description ##### -->
Structure describing events that are passed up and down a pipeline

<!-- ##### SECTION Long_Description ##### -->
<para>
The event classes are used to construct and query events.
</para>

<para>
Events are usually created with gst_event_new() which takes the event type as an argument.
properties specific to the event can be set afterwards with the provided macros. 
The event should be unreferenced with gst_event_unref().
</para>
<para>
gst_event_new_seek() is a usually used to create a seek event and it takes the 
needed parameters for a seek event. 
</para>
<para>
gst_event_new_flush() creates a new flush event.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
#GstPad, #GstElement
</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### STRUCT GstEvent ##### -->
<para>

</para>

@data: 
@type: 
@timestamp: 
@src: 

<!-- ##### ENUM GstEventType ##### -->
<para>
The different major types of events.
</para>

@GST_EVENT_UNKNOWN: unknown event.
@GST_EVENT_EOS: an end-of-stream event.
@GST_EVENT_FLUSH: a flush event.
@GST_EVENT_EMPTY: an empty event.
@GST_EVENT_DISCONTINUOUS: a discontinuous event to indicate the stream has a discontinuity.
@GST_EVENT_QOS: a quality of service event
@GST_EVENT_SEEK: a seek event.
@GST_EVENT_SEEK_SEGMENT: a segment seek with start and stop position
@GST_EVENT_SEGMENT_DONE: the event that will be emited when the segment seek has ended
@GST_EVENT_SIZE: a size suggestion for a peer element
@GST_EVENT_RATE: adjust the output rate of an element
@GST_EVENT_FILLER: a dummy event that should be ignored by plugins
@GST_EVENT_TS_OFFSET: an event to set the time offset on buffers
@GST_EVENT_INTERRUPT: mainly used by _get based elements when they were interrupted
                      while waiting for a buffer.
@GST_EVENT_NAVIGATION: 
@GST_EVENT_TAG: 

<!-- ##### MACRO GST_EVENT_ANY ##### -->
<para>

</para>



<!-- ##### MACRO GST_EVENT_TRACE_NAME ##### -->
<para>
The name used for memory allocation tracing
</para>



<!-- ##### MACRO GST_EVENT_TYPE ##### -->
<para>
Get the event type.
</para>

@event: The event to query.


<!-- ##### MACRO GST_EVENT_TIMESTAMP ##### -->
<para>
Get the timestamp of the event.
</para>

@event: The event to query.


<!-- ##### MACRO GST_EVENT_SRC ##### -->
<para>
The source object that generated this event
</para>

@event: The event to query


<!-- ##### MACRO GST_EVENT_IS_INTERRUPT ##### -->
<para>
Check if the event is an interrupt event
</para>

@event: The event to check


<!-- ##### MACRO GST_SEEK_FORMAT_SHIFT ##### -->
<para>
Shift for the format in the GstSeekType
</para>



<!-- ##### MACRO GST_SEEK_METHOD_SHIFT ##### -->
<para>
Shift for the method in the GstSeekType
</para>



<!-- ##### MACRO GST_SEEK_FLAGS_SHIFT ##### -->
<para>
Shift for the flags in the GstSeekType
</para>



<!-- ##### MACRO GST_SEEK_FORMAT_MASK ##### -->
<para>
Mask for the format in the GstSeekType
</para>



<!-- ##### MACRO GST_SEEK_METHOD_MASK ##### -->
<para>
Mask for the method in the GstSeekType
</para>



<!-- ##### MACRO GST_SEEK_FLAGS_MASK ##### -->
<para>
Mask for the flags in the GstSeekType
</para>



<!-- ##### ENUM GstEventFlag ##### -->
<para>
Event flags are used when querying for supported events
</para>

@GST_EVENT_FLAG_NONE: no value
@GST_RATE_FLAG_NEGATIVE: indicates negative rates are supported

<!-- ##### ENUM GstEventCommonFlag ##### -->
<para>

</para>

@GST_EVENT_COMMON_FLAG_NEED_RESPONSE: 
@GST_EVENT_COMMON_FLAG_LAST: 

<!-- ##### MACRO GST_EVENT_MASK_FUNCTION ##### -->
<para>
A convenience macro to create event mask functions
</para>

@type: The type of the first argument of the function
@functionname: the name of the function
@...: event masks, the last element is marked with 0


<!-- ##### ENUM GstSeekType ##### -->
<para>
The different types of seek events. When constructing a seek event a format,
a seek method and optional flags are OR-ed together. The seek event is then
inserted into the graph with #gst_pad_send_event() or #gst_element_send_event().

Following example illustrates how to insert a seek event (1 second in the stream)
in a pipeline.
<example>
<title>Insertion of a seek event into a pipeline</title>
  <programlisting>
  gboolean res;
  GstEvent *event;

  event = gst_event_new_seek (
            GST_FORMAT_TIME |		/* seek on time */
	    GST_SEEK_METHOD_SET |	/* set the absolute position */
	    GST_SEEK_FLAG_FLUSH,	/* flush any pending data */
	    1 * GST_SECOND);		/* the seek offset (1 second) */

  res = gst_element_send_event (GST_ELEMENT (osssink), event);
  if (!res) {
    g_warning ("seek failed");
  }
  </programlisting>
</example>
</para>

@GST_SEEK_METHOD_CUR: Seek to an relative position
@GST_SEEK_METHOD_SET: Seek to an absolute position
@GST_SEEK_METHOD_END: Seek relative to the end of the stream
@GST_SEEK_FLAG_FLUSH: Flush any pending data while seeking
@GST_SEEK_FLAG_ACCURATE: Seek as accurately as possible
@GST_SEEK_FLAG_KEY_UNIT: Seek to a nearby key unit
@GST_SEEK_FLAG_SEGMENT_LOOP: Loop between start and stop in a segmented seek

<!-- ##### ENUM GstSeekAccuracy ##### -->
<para>
The accuracy about a seek operation gives more information of how the seek was
performed, namly if the seek was accurate or fuzzy.
</para>

@GST_SEEK_CERTAIN: The seek was exact
@GST_SEEK_FUZZY: The seek was fuzzy, exact position can not be guaranteed

<!-- ##### MACRO GST_EVENT_SEEK_TYPE ##### -->
<para>
Get the seektype of the GST_EVENT_SEEK.
</para>

@event: The event to query.


<!-- ##### MACRO GST_EVENT_SEEK_FORMAT ##### -->
<para>
The format of the seek value
</para>

@event: The event operate on


<!-- ##### MACRO GST_EVENT_SEEK_METHOD ##### -->
<para>
The seek method to use as one of #GstSeekType
</para>

@event: The event operate on


<!-- ##### MACRO GST_EVENT_SEEK_FLAGS ##### -->
<para>
The optional seek flags
</para>

@event: The event operate on


<!-- ##### MACRO GST_EVENT_SEEK_OFFSET ##### -->
<para>
Get the offset of the seek event.
</para>

@event: The event to query.


<!-- ##### MACRO GST_EVENT_SEEK_ENDOFFSET ##### -->
<para>
The event stop position for a segment seek
</para>

@event: The event to query


<!-- ##### MACRO GST_EVENT_SEEK_ACCURACY ##### -->
<para>
Indicates how accurate the event was performed.
</para>

@event: The event to query


<!-- ##### MACRO GST_EVENT_DISCONT_NEW_MEDIA ##### -->
<para>
Flag that indicates the discont event was because of a new media
type.
</para>

@event: The event to operate on


<!-- ##### MACRO GST_EVENT_DISCONT_OFFSET ##### -->
<para>
The offset of the discont event. A discont event can hold up to 8 different
format/value pairs.
</para>

@event: The event to query
@i: The offset/value pair.


<!-- ##### MACRO GST_EVENT_DISCONT_OFFSET_LEN ##### -->
<para>
Get the number of offset/value pairs this event has.
</para>

@event: The event to query.


<!-- ##### MACRO GST_EVENT_SIZE_FORMAT ##### -->
<para>
The format of the size event.
</para>

@event: The event to query


<!-- ##### MACRO GST_EVENT_SIZE_VALUE ##### -->
<para>
The value of the size event
</para>

@event: The event to query


<!-- ##### MACRO GST_EVENT_RATE_VALUE ##### -->
<para>
Get access to the rate vale field
</para>

@event: The event to query


<!-- ##### FUNCTION gst_event_new ##### -->
<para>

</para>

@type: 
@Returns: 


<!-- ##### MACRO gst_event_ref ##### -->
<para>
Increase the refcount of this event
</para>

@ev: The event to refcount


<!-- ##### MACRO gst_event_ref_by_count ##### -->
<para>
Increase the refcount of the event with the given value
</para>

@ev: The event to refcount
@c: The value to add to the refcount


<!-- ##### MACRO gst_event_unref ##### -->
<para>
Decrease the refcount of an event, freeing it if the refcount reaches 0
</para>

@ev: The event to unref


<!-- ##### MACRO gst_event_copy ##### -->
<para>
Copy the event using the event specific copy function
</para>

@ev: The event to copy
@Returns: A new event that is a copy of the given input event


<!-- ##### FUNCTION gst_event_masks_contains ##### -->
<para>

</para>

@masks: 
@mask: 
@Returns: 


<!-- ##### FUNCTION gst_event_new_seek ##### -->
<para>

</para>

@type: 
@offset: 
@Returns: 


<!-- ##### FUNCTION gst_event_new_segment_seek ##### -->
<para>

</para>

@type: 
@start: 
@stop: 
@Returns: 


<!-- ##### FUNCTION gst_event_new_size ##### -->
<para>

</para>

@format: 
@value: 
@Returns: 


<!-- ##### FUNCTION gst_event_new_discontinuous ##### -->
<para>

</para>

@new_media: 
@format1: 
@Varargs: 
@Returns: 


<!-- ##### FUNCTION gst_event_new_discontinuous_valist ##### -->
<para>

</para>

@new_media: 
@format1: 
@var_args: 
@Returns: 


<!-- ##### FUNCTION gst_event_discont_get_value ##### -->
<para>

</para>

@event: 
@format: 
@value: 
@Returns: 


<!-- ##### MACRO gst_event_new_filler ##### -->
<para>
Create a new dummy event that should be ignored
</para>



<!-- ##### FUNCTION gst_event_new_filler_stamped ##### -->
<para>

</para>

@time: 
@duration: 
@Returns: 


<!-- ##### FUNCTION gst_event_filler_get_duration ##### -->
<para>

</para>

@event: 
@Returns: 


<!-- ##### MACRO gst_event_new_flush ##### -->
<para>
Create a new flush event.
</para>