GstEvent

GstEvent — Structure describing events that are passed up and down a pipeline

Synopsis


#include <gst/gst.h>


struct      GstEvent;
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)
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            ()
GstEvent*   gst_event_new_filler_stamped    (guint64 time,
                                             guint64 duration);
guint64     gst_event_filler_get_duration   (GstEvent *event);
#define     gst_event_new_flush             ()

Description

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.

Details

struct GstEvent

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;

enum GstEventType

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`

GST_EVENT_ANY

#define GST_EVENT_ANY GST_EVENT_NAVIGATION

GST_EVENT_TRACE_NAME

#define GST_EVENT_TRACE_NAME	"GstEvent"

The name used for memory allocation tracing

GST_EVENT_TYPE()

#define GST_EVENT_TYPE(event)		(GST_EVENT(event)->type)

Get the event type.

event : The event to query.

GST_EVENT_TIMESTAMP()

#define GST_EVENT_TIMESTAMP(event)	(GST_EVENT(event)->timestamp)

Get the timestamp of the event.

event : The event to query.

GST_EVENT_SRC()

#define GST_EVENT_SRC(event)		(GST_EVENT(event)->src)

The source object that generated this event

event : The event to query

GST_EVENT_IS_INTERRUPT()

#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

GST_SEEK_FORMAT_SHIFT

#define GST_SEEK_FORMAT_SHIFT	0

Shift for the format in the GstSeekType

GST_SEEK_METHOD_SHIFT

#define GST_SEEK_METHOD_SHIFT	16

Shift for the method in the GstSeekType

GST_SEEK_FLAGS_SHIFT

#define GST_SEEK_FLAGS_SHIFT	20

Shift for the flags in the GstSeekType

GST_SEEK_FORMAT_MASK

#define GST_SEEK_FORMAT_MASK	0x0000ffff

Mask for the format in the GstSeekType

GST_SEEK_METHOD_MASK

#define GST_SEEK_METHOD_MASK	0x000f0000

Mask for the method in the GstSeekType

GST_SEEK_FLAGS_MASK

#define GST_SEEK_FLAGS_MASK	0xfff00000

Mask for the flags in the GstSeekType

enum GstEventFlag

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

GST_EVENT_MASK_FUNCTION()

#define     GST_EVENT_MASK_FUNCTION(type,functionname, ...)

Warning

GST_EVENT_MASK_FUNCTION is deprecated and should not be used in newly-written code.

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

enum GstSeekType

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 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

typedef enum {
  GST_SEEK_CERTAIN,
  GST_SEEK_FUZZY
} GstSeekAccuracy;

The accuracy about a seek operation gives more information of how the seek was performed, namly 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

GST_EVENT_SEEK_TYPE()

#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.

GST_EVENT_SEEK_FORMAT()

#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

GST_EVENT_SEEK_METHOD()

#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

GST_EVENT_SEEK_FLAGS()

#define GST_EVENT_SEEK_FLAGS(event)		(GST_EVENT_SEEK_TYPE(event) & GST_SEEK_FLAGS_MASK)

The optional seek flags

event : The event operate on

GST_EVENT_SEEK_OFFSET()

#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.

GST_EVENT_SEEK_ENDOFFSET()

#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

GST_EVENT_SEEK_ACCURACY()

#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

GST_EVENT_DISCONT_NEW_MEDIA()

#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

GST_EVENT_DISCONT_OFFSET()

#define GST_EVENT_DISCONT_OFFSET(event,i)	(GST_EVENT(event)->event_data.discont.offsets[i])

The offset of the discont event. A discont event can hold up to 8 different format/value pairs.

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

GST_EVENT_DISCONT_OFFSET_LEN()

#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.

GST_EVENT_SIZE_FORMAT()

#define GST_EVENT_SIZE_FORMAT(event)		(GST_EVENT(event)->event_data.size.format)

The format of the size event.

event : The event to query

GST_EVENT_SIZE_VALUE()

#define GST_EVENT_SIZE_VALUE(event)		(GST_EVENT(event)->event_data.size.value)

The value of the size event

event : The event to query

GST_EVENT_RATE_VALUE()

#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

gst_event_new ()

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.

gst_event_ref()

#define         gst_event_ref(ev)		GST_EVENT (gst_data_ref (GST_DATA (ev)))

Increase the refcount of this event

ev : The event to refcount

gst_event_ref_by_count()

#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

gst_event_unref()

#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

gst_event_copy()

#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

gst_event_masks_contains ()

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

gst_event_new_seek ()

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.

gst_event_new_segment_seek ()

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.

gst_event_new_size ()

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.

gst_event_new_discontinuous ()

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.

gst_event_new_discontinuous_valist ()

GstEvent*   gst_event_new_discontinuous_valist
                                            (gboolean new_media,
                                             GstFormat format1,
                                             va_list var_args);

`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.

gst_event_discont_get_value ()

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.

gst_event_new_filler()

#define		gst_event_new_filler()		gst_event_new(GST_EVENT_FILLER)

Create a new dummy event that should be ignored

gst_event_new_filler_stamped ()

GstEvent*   gst_event_new_filler_stamped    (guint64 time,
                                             guint64 duration);

Creates "filler" data, which is basically empty data that is used to synchronize streams if one stream has no data for a while. This is used to prevent deadlocks.

`time` :	timestamp of the filler, in nanoseconds.
`duration` :	duration of the filler, in nanoseconds.
Returns :	the newly created event.

gst_event_filler_get_duration ()

guint64     gst_event_filler_get_duration   (GstEvent *event);

Filler events are used to synchronize streams (and thereby prevent application deadlocks) if one stream receives no data for a while. This function gets the duration of a filler event, which is the amount of time from the start of this event (see GST_EVENT_TIMESTAMP()) that no data is available.

`event` :	the event to get the duration from.
Returns :	duration of the lack of data, or GST_CLOCK_TIME_NONE.

gst_event_new_flush()

#define		gst_event_new_flush()		gst_event_new(GST_EVENT_FLUSH)

Create a new flush event.

GstEvent

Synopsis

Description

Details

struct GstEvent

enum GstEventType

GST_EVENT_ANY

GST_EVENT_TRACE_NAME

GST_EVENT_TYPE()

GST_EVENT_TIMESTAMP()

GST_EVENT_SRC()

GST_EVENT_IS_INTERRUPT()

GST_SEEK_FORMAT_SHIFT

GST_SEEK_METHOD_SHIFT

GST_SEEK_FLAGS_SHIFT

GST_SEEK_FORMAT_MASK

GST_SEEK_METHOD_MASK

GST_SEEK_FLAGS_MASK

enum GstEventFlag

GST_EVENT_MASK_FUNCTION()

Warning

enum GstSeekType

enum GstSeekAccuracy

GST_EVENT_SEEK_TYPE()

GST_EVENT_SEEK_FORMAT()

GST_EVENT_SEEK_METHOD()

GST_EVENT_SEEK_FLAGS()

GST_EVENT_SEEK_OFFSET()

GST_EVENT_SEEK_ENDOFFSET()

GST_EVENT_SEEK_ACCURACY()

GST_EVENT_DISCONT_NEW_MEDIA()

GST_EVENT_DISCONT_OFFSET()

GST_EVENT_DISCONT_OFFSET_LEN()

GST_EVENT_SIZE_FORMAT()

GST_EVENT_SIZE_VALUE()

GST_EVENT_RATE_VALUE()

gst_event_new ()

gst_event_ref()

gst_event_ref_by_count()

gst_event_unref()

gst_event_copy()

gst_event_masks_contains ()

gst_event_new_seek ()

gst_event_new_segment_seek ()

gst_event_new_size ()

gst_event_new_discontinuous ()

gst_event_new_discontinuous_valist ()

gst_event_discont_get_value ()

gst_event_new_filler()

gst_event_new_filler_stamped ()

gst_event_filler_get_duration ()

gst_event_new_flush()

See Also