|  |  |  | GStreamer 0.8 Core API Reference (0.8.4) |  | 
|---|
GstEvent — Structure describing events that are passed up and down a pipeline
enum GstEventType; #define GST_EVENT_ANY #define GST_EVENT_TRACE_NAME #define GST_EVENT_TYPE (event) #define GST_EVENT_TIMESTAMP (event) #define GST_EVENT_SRC (event) #define GST_EVENT_IS_INTERRUPT (event) #define GST_SEEK_FORMAT_SHIFT #define GST_SEEK_METHOD_SHIFT #define GST_SEEK_FLAGS_SHIFT #define GST_SEEK_FORMAT_MASK #define GST_SEEK_METHOD_MASK #define GST_SEEK_FLAGS_MASK enum GstEventFlag; #define GST_EVENT_MASK_FUNCTION (type,functionname, ...) enum GstSeekType; enum GstSeekAccuracy; #define GST_EVENT_SEEK_TYPE (event) #define GST_EVENT_SEEK_FORMAT (event) #define GST_EVENT_SEEK_METHOD (event) #define GST_EVENT_SEEK_FLAGS (event) #define GST_EVENT_SEEK_OFFSET (event) #define GST_EVENT_SEEK_ENDOFFSET (event) #define GST_EVENT_SEEK_ACCURACY (event) #define GST_EVENT_DISCONT_NEW_MEDIA (event) #define GST_EVENT_DISCONT_OFFSET (event,i) #define GST_EVENT_DISCONT_OFFSET_LEN (event) #define GST_EVENT_SIZE_FORMAT (event) #define GST_EVENT_SIZE_VALUE (event) #define GST_EVENT_RATE_VALUE (event) struct GstEvent; GstEvent* gst_event_new (GstEventType type); #define gst_event_ref (ev) #define gst_event_ref_by_count (ev,c) #define gst_event_unref (ev) #define gst_event_copy (ev) gboolean gst_event_masks_contains (const GstEventMask *masks, GstEventMask *mask); GstEvent* gst_event_new_seek (GstSeekType type, gint64 offset); GstEvent* gst_event_new_segment_seek (GstSeekType type, gint64 start, gint64 stop); GstEvent* gst_event_new_size (GstFormat format, gint64 value); GstEvent* gst_event_new_discontinuous (gboolean new_media, GstFormat format1, ...); GstEvent* gst_event_new_discontinuous_valist (gboolean new_media, GstFormat format1, va_list var_args); gboolean gst_event_discont_get_value (GstEvent *event, GstFormat format, gint64 *value); #define gst_event_new_filler () #define gst_event_new_flush ()
The event classes are used to construct and query events.
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().
gst_event_new_seek() is a usually used to create a seek event and it takes the needed parameters for a seek event.
gst_event_new_flush() creates a new flush event.
typedef enum {
  GST_EVENT_UNKNOWN		= 0,
  GST_EVENT_EOS			= 1,
  GST_EVENT_FLUSH		= 2,
  GST_EVENT_EMPTY		= 3,
  GST_EVENT_DISCONTINUOUS	= 4,
  /*GST_EVENT_NEW_MEDIA		= 5, <- removed */
  GST_EVENT_QOS			= 6,
  GST_EVENT_SEEK		= 7,
  GST_EVENT_SEEK_SEGMENT	= 8,
  GST_EVENT_SEGMENT_DONE	= 9,
  GST_EVENT_SIZE		= 10,
  GST_EVENT_RATE		= 11,
  GST_EVENT_FILLER		= 12,
  GST_EVENT_TS_OFFSET		= 13,
  GST_EVENT_INTERRUPT		= 14,
  GST_EVENT_NAVIGATION		= 15,
  GST_EVENT_TAG			= 16
} GstEventType;
The different major types of events.
| 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 | 
#define GST_EVENT_TRACE_NAME "GstEvent"
The name used for memory allocation tracing
#define GST_EVENT_TYPE(event) (GST_EVENT(event)->type)
Get the event type.
| event : | The event to query. | 
#define GST_EVENT_TIMESTAMP(event) (GST_EVENT(event)->timestamp)
Get the timestamp of the event.
| event : | The event to query. | 
#define GST_EVENT_SRC(event) (GST_EVENT(event)->src)
The source object that generated this event
| event : | The event to query | 
#define GST_EVENT_IS_INTERRUPT(event) (GST_EVENT_TYPE (event) == GST_EVENT_INTERRUPT)
Check if the event is an interrupt event
| event : | The event to check | 
typedef enum {
  GST_EVENT_FLAG_NONE		= 0,
  /* indicates negative rates are supported */
  GST_RATE_FLAG_NEGATIVE	= (1 << 1)
} GstEventFlag;
Event flags are used when querying for supported events
| GST_EVENT_FLAG_NONE | no value | 
| GST_RATE_FLAG_NEGATIVE | indicates negative rates are supported | 
#define GST_EVENT_MASK_FUNCTION(type,functionname, ...)
A convenience macro to create event mask functions
| 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 | 
typedef enum {
  /* | with some format */
  /* | with one of these */
  GST_SEEK_METHOD_CUR		= (1 << (GST_SEEK_METHOD_SHIFT + 0)),
  GST_SEEK_METHOD_SET		= (1 << (GST_SEEK_METHOD_SHIFT + 1)),
  GST_SEEK_METHOD_END		= (1 << (GST_SEEK_METHOD_SHIFT + 2)),
  /* | with optional seek flags */
  /* seek flags */
  GST_SEEK_FLAG_FLUSH		= (1 << (GST_SEEK_FLAGS_SHIFT + 0)),
  GST_SEEK_FLAG_ACCURATE	= (1 << (GST_SEEK_FLAGS_SHIFT + 1)),
  GST_SEEK_FLAG_KEY_UNIT	= (1 << (GST_SEEK_FLAGS_SHIFT + 2)),
  GST_SEEK_FLAG_SEGMENT_LOOP	= (1 << (GST_SEEK_FLAGS_SHIFT + 3))
	
} GstSeekType;
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 5. Insertion of a seek event into a pipeline
  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");
  }
  
| 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 accuratly 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 | 
typedef enum {
  GST_SEEK_CERTAIN,
  GST_SEEK_FUZZY
} GstSeekAccuracy;
The seekaccuracy gives more information of how the seek was performed, if the seek was accurate or fuzzy.
| GST_SEEK_CERTAIN | The seek was exact | 
| GST_SEEK_FUZZY | The seek was fuzzy, exact position can not be guaranteed | 
#define GST_EVENT_SEEK_TYPE(event) (GST_EVENT(event)->event_data.seek.type)
Get the seektype of the GST_EVENT_SEEK.
| event : | The event to query. | 
#define GST_EVENT_SEEK_FORMAT(event) (GST_EVENT_SEEK_TYPE(event) & GST_SEEK_FORMAT_MASK)
The format of the seek value
| event : | The event operate on | 
#define GST_EVENT_SEEK_METHOD(event) (GST_EVENT_SEEK_TYPE(event) & GST_SEEK_METHOD_MASK)
The seek method to use as one of GstSeekType
| event : | The event operate on | 
#define GST_EVENT_SEEK_FLAGS(event) (GST_EVENT_SEEK_TYPE(event) & GST_SEEK_FLAGS_MASK)
The optional seek flags
| event : | The event operate on | 
#define GST_EVENT_SEEK_OFFSET(event) (GST_EVENT(event)->event_data.seek.offset)
Get the offset of the seek event.
| event : | The event to query. | 
#define GST_EVENT_SEEK_ENDOFFSET(event) (GST_EVENT(event)->event_data.seek.endoffset)
The event stop position for a segment seek
| event : | The event to query | 
#define GST_EVENT_SEEK_ACCURACY(event) (GST_EVENT(event)->event_data.seek.accuracy)
Indicates how accurate the event was performed.
| event : | The event to query | 
#define GST_EVENT_DISCONT_NEW_MEDIA(event) (GST_EVENT(event)->event_data.discont.new_media)
Flag that indicates the discont event was because of a new media type.
| event : | The event to operate on | 
#define GST_EVENT_DISCONT_OFFSET(event,i) (GST_EVENT(event)->event_data.discont.offsets[i])
The offset of the discont event. A discont evetn can hold up to 8 different format/value pairs.
| event : | The event to query | 
| i : | The offset/value pair. | 
#define GST_EVENT_DISCONT_OFFSET_LEN(event) (GST_EVENT(event)->event_data.discont.noffsets)
Get the number of offset/value pairs this event has.
| event : | The event to query. | 
#define GST_EVENT_SIZE_FORMAT(event) (GST_EVENT(event)->event_data.size.format)
The format of the size event.
| event : | The event to query | 
#define GST_EVENT_SIZE_VALUE(event) (GST_EVENT(event)->event_data.size.value)
The value of the size event
| event : | The event to query | 
#define GST_EVENT_RATE_VALUE(event) (GST_EVENT(event)->event_data.rate.value)
Get access to the rate vale field
| event : | The event to query | 
struct GstEvent {
  GstData data;
  GstEventType  type;
  guint64	timestamp;
  GstObject	*src;
  union {
    struct {
      GstSeekType	type;
      gint64		offset;
      gint64		endoffset;
      GstSeekAccuracy	accuracy;
    } seek;
    struct {
      GstFormatValue	offsets[8];
      gint		noffsets;
      gboolean		new_media;
    } discont;
    struct {
      GstFormat		format;
      gint64		value;
    } size;
    struct {
      gdouble		value;
    } rate;
    struct {
      GstStructure	*structure;
    } structure;
  } event_data;
GstEvent* gst_event_new (GstEventType type);
Allocate a new event of the given type.
| type : | The type of the new event | 
| Returns : | A new event. | 
#define gst_event_ref(ev) GST_EVENT (gst_data_ref (GST_DATA (ev)))
Increase the refcount of this event
| ev : | The event to refcount | 
#define gst_event_ref_by_count(ev,c) GST_EVENT (gst_data_ref_by_count (GST_DATA (ev), c))
Increase the refcount of the event with the given value
| ev : | The event to refcount | 
| c : | The value to add to the refcount | 
#define gst_event_unref(ev) gst_data_unref (GST_DATA (ev))
Decrease the refcount of an event, freeing it if the refcount reaches 0
| ev : | The event to unref | 
#define gst_event_copy(ev) GST_EVENT (gst_data_copy (GST_DATA (ev)))
Copy the event using the event specific copy function
| ev : | The event to copy | 
| Returns : | A new event that is a copy of the given input event | 
gboolean    gst_event_masks_contains        (const GstEventMask *masks,
                                             GstEventMask *mask);See if the given eventmask is inside the eventmask array.
| masks : | The eventmask array to search | 
| mask : | the event mask to find | 
| Returns : | TRUE if the eventmask is found inside the array | 
GstEvent* gst_event_new_seek (GstSeekType type, gint64 offset);
Allocate a new seek event with the given parameters.
| type : | The type of the seek event | 
| offset : | The offset of the seek | 
| Returns : | A new seek event. | 
GstEvent* gst_event_new_segment_seek (GstSeekType type, gint64 start, gint64 stop);
Allocate a new segment seek event with the given parameters.
| type : | The type of the seek event | 
| start : | The start offset of the seek | 
| stop : | The stop offset of the seek | 
| Returns : | A new segment seek event. | 
GstEvent* gst_event_new_size (GstFormat format, gint64 value);
Create a new size event with the given values.
| format : | The format of the size value | 
| value : | The value of the size event | 
| Returns : | The new size event. | 
GstEvent* gst_event_new_discontinuous (gboolean new_media, GstFormat format1, ...);
Allocate a new discontinuous event with the given format/value pairs. Note that the values are of type gint64 - you may not use simple integers such as "0" when calling this function, always cast them like "(gint64) 0". Terminate the list with GST_FORMAT_UNDEFINED.
| new_media : | A flag indicating a new media type starts | 
| format1 : | The format of the discont value | 
| ... : | more discont values and formats | 
| Returns : | A new discontinuous event. | 
GstEvent* gst_event_new_discontinuous_valist (gboolean new_media, GstFormat format1, va_list var_args);
Allocate a new discontinuous event with the given format/value pairs. Note that the values are of type gint64 - you may not use simple integers such as "0" when calling this function, always cast them like "(gint64) 0". Terminate the list with GST_FORMAT_UNDEFINED.
| new_media : | A flag indicating a new media type starts | 
| format1 : | The format of the discont value | 
| var_args : | more discont values and formats | 
| Returns : | A new discontinuous event. | 
gboolean gst_event_discont_get_value (GstEvent *event, GstFormat format, gint64 *value);
Get the value for the given format in the discontinous event.
| event : | The event to query | 
| format : | The format of the discontinuous value | 
| value : | A pointer to the value | 
| Returns : | TRUE if the discontinuous event carries the specified format/value pair. | 
#define gst_event_new_filler() gst_event_new(GST_EVENT_FILLER)
Create a new dummy event that should be ignored
| << GstError | GstFormat >> |