## GstEvent

GstEvent — Event definitions.

## Synopsis

    #include <gst/gst.h>

    enum        GstEventType;
    #define     GST_EVENT_TYPE                  (event)
    #define     GST_EVENT_SRC                   (event)
    #define     GST_EVENT_TIMESTAMP             (event)
    enum        GstEventFlag;
    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_ACCURACY         (event)
    #define     GST_SEEK_FLAGS_MASK
    #define     GST_SEEK_FLAGS_SHIFT
    #define     GST_SEEK_FORMAT_MASK
    #define     GST_SEEK_FORMAT_SHIFT
    #define     GST_SEEK_METHOD_MASK
    #define     GST_SEEK_METHOD_SHIFT
    #define     GST_EVENT_DISCONT_NEW_MEDIA     (event)
    #define     GST_EVENT_DISCONT_OFFSET        (event,i)
    #define     GST_EVENT_DISCONT_OFFSET_LEN    (event)
    #define     GST_EVENT_RATE_VALUE            (event)
    #define     GST_EVENT_SEEK_ENDOFFSET        (event)
    #define     GST_EVENT_SIZE_FORMAT           (event)
    #define     GST_EVENT_SIZE_VALUE            (event)
    struct      GstEvent;
    GstEvent*   gst_event_new                   (GstEventType type);
    #define     gst_event_copy                  (ev)
    #define     gst_event_ref                   (ev)
    #define     gst_event_ref_by_count          (ev,c)
    #define     gst_event_unref                 (ev)
    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,
                                                 ...);
    gboolean    gst_event_discont_get_value     (GstEvent *event,
                                                 GstFormat format,
                                                 gint64 *value);
    #define     gst_event_new_filler            ()
    #define     gst_event_new_flush             ()
    void        gst_event_print_stats           (void);
    #define     GST_EVENT_MASK_FUNCTION         (type,functionname, ...)

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

### enum GstEventType

    typedef enum {
      GST_EVENT_UNKNOWN,
      GST_EVENT_EOS,
      GST_EVENT_FLUSH,
      GST_EVENT_EMPTY,
      GST_EVENT_DISCONTINUOUS,
      GST_EVENT_NEW_MEDIA,
      GST_EVENT_QOS,
      GST_EVENT_SEEK,
      GST_EVENT_SEEK_SEGMENT,
      GST_EVENT_SEGMENT_DONE,
      GST_EVENT_SIZE,
      GST_EVENT_RATE,
      GST_EVENT_FILLER,
      GST_EVENT_TS_OFFSET,
      GST_EVENT_INTERRUPT
    } 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_NEW_MEDIA` | a new media stream is started
`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` |

### GST_EVENT_TYPE()

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

Get the event type.

`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_TIMESTAMP()

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

Get the timestamp of the event.

`event` : | The event to query.

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

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

`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

### enum GstSeekAccuracy

    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

### 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_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_SEEK_FLAGS_MASK

    #define GST_SEEK_FLAGS_MASK	0xfff00000

Mask for the flags 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_FORMAT_SHIFT

    #define GST_SEEK_FORMAT_SHIFT	0

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

    #define GST_SEEK_METHOD_SHIFT	16

Shift for the method in the GstSeekType

### 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 evetn 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_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_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_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

### 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;
      } event_data;
    };

The event structure

### 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_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_ref()

    #define         gst_event_ref(ev)             	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_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_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 geven format/value pairs.

`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_discont_get_value ()

    gboolean    gst_event_discont_get_value     (GstEvent *event,
                                                 GstFormat format,
                                                 gint64 *value);

Get the value for the given format in the dicont event.

`event` : | The event to query
`format` : | The format of the discont value
`value` : | A pointer to the value
Returns : | TRUE if the discont event caries 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_flush()

    #define		gst_event_new_flush()		gst_event_new(GST_EVENT_FLUSH)

Create a new flush event.

### gst_event_print_stats ()

    void        gst_event_print_stats           (void);

Logs statistics about live events (using g_log).

### GST_EVENT_MASK_FUNCTION()

    #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

## See Also

GstPad