Event

The event class provides factory methods to construct events for sending and functions to query (parse) received events.

Events are usually created with gst_event_new_*() which takes event-type specific parameters as arguments. To send an event application will usually use Element.sendEvent and elements will use Pad.sendEvent or Pad.pushEvent. The event should be unreffed with Event.unref if it has not been sent.

Events that have been received can be parsed with their respective gst_event_parse_*() functions. It is valid to pass NULL for unwanted details.

Events are passed between elements in parallel to the data stream. Some events are serialized with buffers, others are not. Some events only travel downstream, others only upstream. Some events can travel both upstream and downstream.

The events are used to signal special conditions in the datastream such as EOS (end of stream) or the start of a new stream-segment. Events are also used to flush the pipeline of any pending data.

Most of the event API is used inside plugins. Applications usually only construct and use seek events. To do that Event.newSeek is used to create a seek event. It takes the needed parameters to specify seeking time and mode.

GstEvent *event;
gboolean result;
...
// construct a seek event to play the media from second 2 to 5, flush
// the pipeline to decrease latency.
event = gst_event_new_seek (1.0,
GST_FORMAT_TIME,
GST_SEEK_FLAG_FLUSH,
GST_SEEK_TYPE_SET, 2 * GST_SECOND,
GST_SEEK_TYPE_SET, 5 * GST_SECOND);
...
result = gst_element_send_event (pipeline, event);
if (!result)
g_warning ("seek failed");
...

class Event {

GstEvent* gstEvent;

protected

bool ownedRef;

GstEvent* getEventStruct(bool transferOwnership);

void* getStruct();

this(GstEvent* gstEvent, bool ownedRef);

static Event newEOS();

static Event newFlushStart();

static Event newTocSelect(string uid);

static GType getType();

this(GstFormat format, long minsize, long maxsize, bool async);

this(Caps caps);

this(GstEventType type, Structure structure);

this(bool resetTime);

this(GstClockTime timestamp, GstClockTime duration);

this(GstClockTime latency);

this(Structure structure);

this(string systemId, Buffer data, string origin);

this(GstQOSType type, double proportion, GstClockTimeDiff diff, GstClockTime timestamp);

this(double rate, GstFormat format, GstSeekFlags flags, GstSeekType startType, long start, GstSeekType stopType, long stop);

this(Segment segment);

this(GstFormat format, long position);

this(ListG streams);

this(string name, Message msg);

this(GstFormat format, ulong amount, double rate, bool flush, bool intermediate);

this(StreamCollection collection);

this(uint groupId);

this(string streamId);

this(TagList taglist);

this(Toc toc, bool updated);

void copySegment(Segment segment);

long getRunningTimeOffset();

uint getSeqnum();

Structure getStructure();

bool hasName(string name);

void parseBufferSize(GstFormat format, long minsize, long maxsize, bool async);

void parseCaps(Caps caps);

void parseFlushStop(bool resetTime);

void parseGap(GstClockTime timestamp, GstClockTime duration);

bool parseGroupId(uint groupId);

void parseLatency(GstClockTime latency);

void parseProtection(string systemId, Buffer data, string origin);

void parseQos(GstQOSType type, double proportion, GstClockTimeDiff diff, GstClockTime timestamp);

void parseSeek(double rate, GstFormat format, GstSeekFlags flags, GstSeekType startType, long start, GstSeekType stopType, long stop);

void parseSeekTrickmodeInterval(GstClockTime interval);

void parseSegment(Segment segment);

void parseSegmentDone(GstFormat format, long position);

void parseSelectStreams(ListG streams);

void parseSinkMessage(Message msg);

void parseStep(GstFormat format, ulong amount, double rate, bool flush, bool intermediate);

void parseStream(Stream stream);

void parseStreamCollection(StreamCollection collection);

void parseStreamFlags(GstStreamFlags flags);

void parseStreamGroupDone(uint groupId);

void parseStreamStart(string streamId);

void parseTag(TagList taglist);

void parseToc(Toc toc, bool updated);

void parseTocSelect(string uid);

void setGroupId(uint groupId);

void setRunningTimeOffset(long offset);

void setSeekTrickmodeInterval(GstClockTime interval);

void setSeqnum(uint seqnum);

void setStream(Stream stream);

void setStreamFlags(GstStreamFlags flags);

Structure writableStructure();

static GstEventTypeFlags typeGetFlags(GstEventType type);

static string typeGetName(GstEventType type);

static GQuark typeToQuark(GstEventType type);

}

Constructors

this this(GstEvent* gstEvent, bool ownedRef): Sets our main struct and passes it to the parent class.
this this(GstFormat format, long minsize, long maxsize, bool async): Create a new buffersize event. The event is sent downstream and notifies elements that they should provide a buffer of the specified dimensions.
this this(Caps caps): Create a new CAPS event for caps. The caps event can only travel downstream synchronized with the buffer flow and contains the format of the buffers that will follow after the event.
this this(GstEventType type, Structure structure): Create a new custom-typed event. This can be used for anything not handled by other event-specific functions to pass an event to another element.
this this(bool resetTime): Allocate a new flush stop event. The flush stop event can be sent upstream and downstream and travels serialized with the dataflow. It is typically sent after sending a FLUSH_START event to make the pads accept data again.
this this(GstClockTime timestamp, GstClockTime duration): Create a new GAP event. A gap event can be thought of as conceptually equivalent to a buffer to signal that there is no data for a certain amount of time. This is useful to signal a gap to downstream elements which may wait for data, such as muxers or mixers or overlays, especially for sparse streams such as subtitle streams.
this this(GstClockTime latency): Create a new latency event. The event is sent upstream from the sinks and notifies elements that they should add an additional latency to the running time before synchronising against the clock.
this this(Structure structure): Create a new navigation event from the given description.
this this(string systemId, Buffer data, string origin): Creates a new event containing information specific to a particular protection system (uniquely identified by system_id), by which that protection system can acquire key(s) to decrypt a protected stream.
this this(GstQOSType type, double proportion, GstClockTimeDiff diff, GstClockTime timestamp): Allocate a new qos event with the given values. The QOS event is generated in an element that wants an upstream element to either reduce or increase its rate because of high/low CPU load or other resource usage such as network performance or throttling. Typically sinks generate these events for each buffer they receive.
this this(): Create a new reconfigure event. The purpose of the reconfigure event is to travel upstream and make elements renegotiate their caps or reconfigure their buffer pools. This is useful when changing properties on elements or changing the topology of the pipeline.
this this(double rate, GstFormat format, GstSeekFlags flags, GstSeekType startType, long start, GstSeekType stopType, long stop): Allocate a new seek event with the given parameters.
this this(Segment segment): Create a new SEGMENT event for segment. The segment event can only travel downstream synchronized with the buffer flow and contains timing information and playback properties for the buffers that will follow.
this this(GstFormat format, long position): Create a new segment-done event. This event is sent by elements that finish playback of a segment as a result of a segment seek.
this this(ListG streams): Allocate a new select-streams event.
this this(string name, Message msg): Create a new sink-message event. The purpose of the sink-message event is to instruct a sink to post the message contained in the event synchronized with the stream.
this this(GstFormat format, ulong amount, double rate, bool flush, bool intermediate): Create a new step event. The purpose of the step event is to instruct a sink to skip amount (expressed in format) of media. It can be used to implement stepping through the video frame by frame or for doing fast trick modes.
this this(StreamCollection collection): Create a new STREAM_COLLECTION event. The stream collection event can only travel downstream synchronized with the buffer flow.
this this(uint groupId): Create a new Stream Group Done event. The stream-group-done event can only travel downstream synchronized with the buffer flow. Elements that receive the event on a pad should handle it mostly like EOS, and emit any data or pending buffers that would depend on more data arriving and unblock, since there won't be any more data.
this this(string streamId): Create a new STREAM_START event. The stream start event can only travel downstream synchronized with the buffer flow. It is expected to be the first event that is sent for a new stream.
this this(TagList taglist): Generates a metadata tag event from the given taglist.
this this(Toc toc, bool updated): Generate a TOC event from the given toc. The purpose of the TOC event is to inform elements that some kind of the TOC was found.

Members

Functions

copySegment void copySegment(Segment segment): Parses a segment event and copies the gstreamer.Segment into the location given by segment.
getEventStruct GstEvent* getEventStruct(bool transferOwnership): Get the main Gtk struct
getRunningTimeOffset long getRunningTimeOffset(): Retrieve the accumulated running time offset of the event.
getSeqnum uint getSeqnum(): Retrieve the sequence number of a event.
getStruct void* getStruct(): the main Gtk struct as a void*
getStructure Structure getStructure(): Access the structure of the event.
hasName bool hasName(string name): Checks if event has the given name. This function is usually used to check the name of a custom event.
parseBufferSize void parseBufferSize(GstFormat format, long minsize, long maxsize, bool async): Get the format, minsize, maxsize and async-flag in the buffersize event.
parseCaps void parseCaps(Caps caps): Get the caps from event. The caps remains valid as long as event remains valid.
parseFlushStop void parseFlushStop(bool resetTime): Parse the FLUSH_STOP event and retrieve the reset_time member.
parseGap void parseGap(GstClockTime timestamp, GstClockTime duration): Extract timestamp and duration from a new GAP event.
parseGroupId bool parseGroupId(uint groupId)
parseLatency void parseLatency(GstClockTime latency): Get the latency in the latency event.
parseProtection void parseProtection(string systemId, Buffer data, string origin): Parses an event containing protection system specific information and stores the results in system_id, data and origin. The data stored in system_id, origin and data are valid until event is released.
parseQos void parseQos(GstQOSType type, double proportion, GstClockTimeDiff diff, GstClockTime timestamp): Get the type, proportion, diff and timestamp in the qos event. See Event.newQos for more information about the different QoS values.
parseSeek void parseSeek(double rate, GstFormat format, GstSeekFlags flags, GstSeekType startType, long start, GstSeekType stopType, long stop): Parses a seek event and stores the results in the given result locations.
parseSeekTrickmodeInterval void parseSeekTrickmodeInterval(GstClockTime interval): Retrieve the trickmode interval that may have been set on a seek event with Event.setSeekTrickmodeInterval.
parseSegment void parseSegment(Segment segment): Parses a segment event and stores the result in the given segment location. segment remains valid only until the event is freed. Don't modify the segment and make a copy if you want to modify it or store it for later use.
parseSegmentDone void parseSegmentDone(GstFormat format, long position): Extracts the position and format from the segment done message.
parseSelectStreams void parseSelectStreams(ListG streams): Parse the SELECT_STREAMS event and retrieve the contained streams.
parseSinkMessage void parseSinkMessage(Message msg): Parse the sink-message event. Unref msg after usage.
parseStep void parseStep(GstFormat format, ulong amount, double rate, bool flush, bool intermediate): Parse the step event.
parseStream void parseStream(Stream stream): Parse a stream-start event and extract the gstreamer.Stream from it.
parseStreamCollection void parseStreamCollection(StreamCollection collection): Retrieve new gstreamer.StreamCollection from STREAM_COLLECTION event event.
parseStreamFlags void parseStreamFlags(GstStreamFlags flags)
parseStreamGroupDone void parseStreamGroupDone(uint groupId): Parse a stream-group-done event and store the result in the given group_id location.
parseStreamStart void parseStreamStart(string streamId): Parse a stream-id event and store the result in the given stream_id location. The string stored in stream_id must not be modified and will remain valid only until event gets freed. Make a copy if you want to modify it or store it for later use.
parseTag void parseTag(TagList taglist): Parses a tag event and stores the results in the given taglist location. No reference to the taglist will be returned, it remains valid only until the event is freed. Don't modify or free the taglist, make a copy if you want to modify it or store it for later use.
parseToc void parseToc(Toc toc, bool updated): Parse a TOC event and store the results in the given toc and updated locations.
parseTocSelect void parseTocSelect(string uid): Parse a TOC select event and store the results in the given uid location.
setGroupId void setGroupId(uint groupId): All streams that have the same group id are supposed to be played together, i.e. all streams inside a container file should have the same group id but different stream ids. The group id should change each time the stream is started, resulting in different group ids each time a file is played for example.
setRunningTimeOffset void setRunningTimeOffset(long offset): Set the running time offset of a event. See Event.getRunningTimeOffset for more information.
setSeekTrickmodeInterval void setSeekTrickmodeInterval(GstClockTime interval): Sets a trickmode interval on a (writable) seek event. Elements that support TRICKMODE_KEY_UNITS seeks SHOULD use this as the minimal interval between each frame they may output.
setSeqnum void setSeqnum(uint seqnum): Set the sequence number of a event.
setStream void setStream(Stream stream): Set the stream on the stream-start event
setStreamFlags void setStreamFlags(GstStreamFlags flags)
writableStructure Structure writableStructure(): Get a writable version of the structure.

Static functions

getType GType getType()
newEOS Event newEOS(): Create a new EOS event. The eos event can only travel downstream synchronized with the buffer flow. Elements that receive the EOS event on a pad can return UNEXPECTED as a GstFlowReturn when data after the EOS event arrives. The EOS event will travel down to the sink elements in the pipeline which will then post the GST_MESSAGE_EOS on the bus after they have finished playing any buffered data. When all sinks have posted an EOS message, the EOS message is forwarded to the application.
newFlushStart Event newFlushStart(): Allocate a new flush start event. The flush start event can be send upstream and downstream and travels out-of-bounds with the dataflow. It marks pads as being in a WRONG_STATE to process more data. Elements unlock and blocking functions and exit their streaming functions as fast as possible. This event is typically generated after a seek to minimize the latency after the seek.
newTocSelect Event newTocSelect(string uid): Generate a TOC select event with the given uid. The purpose of the TOC select event is to start playback based on the TOC's entry with the given uid.
typeGetFlags GstEventTypeFlags typeGetFlags(GstEventType type): Gets the GstEventTypeFlags associated with type.
typeGetName string typeGetName(GstEventType type): Get a printable name for the given event type. Do not modify or free.
typeToQuark GQuark typeToQuark(GstEventType type): Get the unique quark for the given event type.

Variables

gstEvent GstEvent* gstEvent;: the main Gtk struct

gstreamer Event classes

Event