Gstreamer-GstEvent

相关连接：https://blog.youkuaiyun.com/knowledgebao/article/details/84621238

---

Includes

#include <gst/gst.h>

Description

event类提供构造和解析events的方法，而events事件是通信的载体。

events通常调用类似 gst_event_new_*() 这样的函数去创建。应用程序一般通过gst_element_send_event() 函数发送events，而element通常通过 gst_pad_send_event() or gst_pad_push_event()发送events。如果events构建后没有被发送，需要调用gst_event_unref()去释放。如果发送了就由对方去释放。

events可以通过类似 gst_event_parse_*() 这样的函数去解析内容，当然events可以只有类型而没有内容，既内容可以为空。

events主要在一个bin里的element之间传递。一些events可以包含有数据流。一些events只能向下游传递，一些events只能向上游传递，一些events既可以向下游传递，也可以向上游传递。events一般用于在数据流中发出特殊的信号，比如EOS(流的结束)或新流段的开始。events也会被用于刷新任何挂起数据的pipeline。

大多数事件API是在插件中使用的。应用程序通常只构造和使用seek事件。使用gst_event_new_seek()创建一个seek事件。它使用所需的参数来指定查找时间和模式。如下边代码段：

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");
...

举例：

1，pad关联一个event处理函数，上游pad可以发送event事件给下游

#define gst_pad_set_event_function(p,f)   gst_pad_set_event_function_full((p),(f),NULL,NULL)
void gst_pad_set_event_function_full(GstPad *pad,GstPadEventFunction event,gpointer user_data,GDestroyNotify notify);
//解析函数定义及调用：
//设置指定pad接收函数
gst_pad_set_event_function(priv->sinkpad, GST_DEBUG_FUNCPTR(gst_ff_audio_enc_sink_event));
//定义及实现接收函数
static gboolean gst_ff_audio_enc_sink_event(GstPad * pad, GstObject * parent, GstEvent * event)
{
    GST_LOG_OBJECT(filter, "audio Enc * Received %s event: %" GST_PTR_FORMAT,
        GST_EVENT_TYPE_NAME(event), event);

    switch (GST_EVENT_TYPE(event)) {
    case GST_EVENT_EOS:
    {
        GST_FF_AUDIO_ENC_LOCK(priv);
        ret = gst_pad_push_event(priv->srcpad, event);
        gst_event_unref(event);
        GST_FF_AUDIO_ENC_UNLOCK(priv);
        break;
    }
    case GST_EVENT_CAPS:
    {
        GST_FF_AUDIO_ENC_LOCK(priv);
        GstCaps * caps;
        gst_event_parse_caps(event, &caps);
        ret = gst_ff_audio_enc_create(filter, caps);
        if (ret)
            ret = gst_ff_audio_enc_setcaps(filter);
        gst_event_unref(event);
        GST_FF_AUDIO_ENC_UNLOCK(priv);
        break;
    }
    default:
        ret = gst_pad_event_default(pad, parent, event);
        break;
    }

    return ret;
}
//上游发送events
ret = gst_pad_push_event(priv->srcpad, gst_event_new_caps(fixcaps));

Types and Values

struct	GstEvent	包含4个字段：父指针GstMiniObject mini_object；类型GstEventType type；序列号guint32 seqnum；
enum	GstEventTypeFlags	构建GstEventType的枚举参数，详见GstEventType
#define	GST_EVENT_TYPE_BOTH	GstEventTypeFlags中 GST_EVENT_TYPE_UPSTREAM | GST_EVENT_TYPE_DOWNSTREAM.
enum	GstEventType	GstEventType是一个枚举类型，这里的枚举类型是可以在管道中发送的标准事件类型。 自定义事件类型一般都携带一个GstStructure，通过GstStructure来传递内容。如何构造事件类型，详见GST_EVENT_MAKE_TYPE，一般用户自定义类型可能会重复，所以最好通过GstStructure内容来区分具体信息。用户自定义EventType仅作为第一道入口。
enum	GstStreamFlags	流类型，包括：稀疏型，必选型，非必选型等。通过函数 gst_event_set_stream_flags ()和gst_event_parse_stream_flags()设置和获取，对应stream-start event
enum	GstQOSType	函数gst_event_new_qos()的第一个参数，枚举GOS的类型。包括：数据太快，数据太慢，无所谓3中状态，具体参考gst_event_new_qos()
enum	GstSeekType	seek类型枚举，参考 gst_event_new_seek() or  gst_segment_do_seek().有3个值：不变，相对文件头，相对文件尾。
enum	GstSeekFlags	seek标签枚举，可以通过或多个同时使用，参考 gst_event_new_seek()  or  gst_segment_do_seek().有10几个标识，此处不具体描述。比如快进、快退、是否查找关键帧等。

Functions

#define	GST_EVENT_MAKE_TYPE()	用户定义事件类型。#define GST_EVENT_MAKE_TYPE(num,flags) \     (((num) << GST_EVENT_NUM_SHIFT) | (flags))，用户定义num一般必须大于320；flag取值范围为GstEventTypeFlags。系统定义的类型详见GstEventType枚举。
#define	GST_EVENT_TYPE()	返回事件类型，具体类型参见GstEventTypeFlags
#define	GST_EVENT_TYPE_NAME()	和类型对应的描述信息
#define	GST_EVENT_TIMESTAMP()	返回事件创建时间
#define	GST_EVENT_SEQNUM()	返回seqnum
#define	GST_EVENT_IS_UPSTREAM()	Check if an event can travel upstream.详见GstEventTypeFlags
#define	GST_EVENT_IS_DOWNSTREAM()	Check if an event can travel downstream.详见GstEventTypeFlags
#define	GST_EVENT_IS_SERIALIZED()	Check if an event is serialized with the data stream.详见GstEventTypeFlags
#define	GST_EVENT_IS_STICKY()	Check if an event is sticky on the pads.详见GstEventTypeFlags
GstEventTypeFlags	gst_event_type_get_flags ()	详见GstEventTypeFlags
const gchar *	gst_event_type_get_name ()	返回event名称，系统自定义的event对应都定义了名称，比如：GST_EVENT_SEEK, "seek"或GST_EVENT_CAPS, "caps"等
GQuark	gst_event_type_to_quark ()	返回event的索引值，也就是GST_EVENT_SEEK,GST_EVENT_CAPS等这些大小。实际就是一个int值
GstEvent *	gst_event_ref ()	event索引+1
void	gst_event_unref ()	event索引-1
gboolean	gst_event_replace ()	event指针交换，原子操作。the old event is unreffed, the new one is reffed
GstEvent *	gst_event_copy ()	copy
GstEvent *	gst_event_steal ()	event指针转移，类似gst_event_replace ()
gboolean	gst_event_take ()	同gst_event_replace ()，唯一区别是此函数获取new_event的ownership(所有权)
#define	gst_event_is_writable()	是否可写
#define	gst_event_make_writable()	使其可写，如果不可写会调用gst_event_copy ()得到一份新的event
GstStructure *	gst_event_writable_structure ()	获取可写的Structure，无需释放
GstEvent *	gst_event_new_custom ()	构造用户Event，包含type和一个GstStructure，建议不要完全依赖type来区分事件，因为用户自定义type可能会重复，所以结合GstStructure内容来唯一确定事件
const GstStructure *	gst_event_get_structure ()	获取GSTStructure指针，无需释放，如果event被释放，此指针可能成为野指针。
gboolean	gst_event_has_name ()	检测event名称
guint32	gst_event_get_seqnum ()	同GST_EVENT_SEQNUM()
void	gst_event_set_seqnum ()	设置序列号，一般递增，但是可以做一些关联，取决于用户
gint64	gst_event_get_running_time_offset ()	获取event的运行时长
void	gst_event_set_running_time_offset ()	设置event的运行时长，暂时理解有点模糊，运行时长设置的作用？ Events passing through GstPads that have a running time offset set via gst_pad_set_offset() will get their offset adjusted according to the pad's offset. If the event contains any information that related to the running time, this information will need to be updated before usage with this offset.
GstEvent *	gst_event_new_flush_start ()	等价于gst_event_new_custom (GST_EVENT_FLUSH_START, NULL);创建一个开始刷新event。一般在Seek之后，用于清空之前的缓存。Any event (except a GST_EVENT_FLUSH_STOP) received on a flushing pad will return FALSE immediately.
GstEvent *	gst_event_new_flush_stop ()	等价于  event = gst_event_new_custom (GST_EVENT_FLUSH_STOP,       gst_structure_new_id (GST_QUARK (EVENT_FLUSH_STOP),           GST_QUARK (RESET_TIME), G_TYPE_BOOLEAN, reset_time, NULL));创建一个停止刷新event，一般在FLUSH_START event之后，用于重新开始正常缓存流动
void	gst_event_parse_flush_stop ()	解析gst_event_new_flush_stop ()创建的event
GstEvent *	gst_event_new_eos ()	创建一个流结束event,
GstEvent *	gst_event_new_gap ()	gap空白，产生一个空白消息，用于通知下游一小段时间内可能无数据，比如用于字幕流等。带一个时长的参数
void	gst_event_parse_gap ()	解析gst_event_new_gap ()产生的event
GstEvent *	gst_event_new_stream_start ()	Create a new STREAM_START event.一般作为第一个消息时间发送。一遍demux需要发送，待一个stream_id参数， gst_pad_create_stream_id() or gst_pad_create_stream_id_printf() can be used to create a stream-id.
void	gst_event_parse_stream_start ()	解析gst_event_new_stream_start ()创建的event
void	gst_event_set_stream_flags ()	给时间设置flag，参考GstStreamFlags
void	gst_event_parse_stream_flags ()	解析gst_event_set_stream_flags ()
void	gst_event_set_group_id ()	给event设置组ID，相关联的Streams应该有相同的组ID，不同的StreamID。组ID可以通过函数gst_util_group_id_next()获取 比如一个rtsp流，音频和视频流有相同的组ID不同的StreamID.
gboolean	gst_event_parse_group_id ()	解析gst_event_set_group_id ()
void	gst_event_set_stream ()	将stream绑定到event上
void	gst_event_parse_stream ()	解析gst_event_set_stream ()
GstEvent *	gst_event_new_segment ()	Create a new SEGMENT event for segment 。具体参考segment
void	gst_event_parse_segment ()	从event中解析出segment
void	gst_event_copy_segment ()	同上，解析出的segment 是本地的另一个，不依赖event
GstEvent *	gst_event_new_tag ()	Generates a metadata tag event from the given taglist .
void	gst_event_parse_tag ()	解析gst_event_parse_tag ()
GstEvent *	gst_event_new_buffer_size ()	Create a new buffersize event.
void	gst_event_parse_buffer_size ()	解析gst_event_new_buffer_size ()
GstEvent *	gst_event_new_qos ()	Allocate a new qos event with the given values.查考GstQOSType，用于数据太快、太慢
void	gst_event_parse_qos ()	解析gst_event_new_qos ()
GstEvent *	gst_event_new_seek ()	Allocate a new seek event with the given parameters.用于seek，快进、快退等
void	gst_event_parse_seek ()	解析gst_event_parse_seek ()
GstEvent *	gst_event_new_navigation ()	Create a new navigation event from the given description.一般自定义使用。参数是GstStructure
GstEvent *	gst_event_new_latency ()	Create a new latency event. 创建一个延迟消息，参数是GstClockTime
void	gst_event_parse_latency ()	解析gst_event_new_latency ()
GstEvent *	gst_event_new_step ()	Create a new step event. 主要用于rate等的改变
void	gst_event_parse_step ()	解析gst_event_new_step ()
GstEvent *	gst_event_new_sink_message ()	Create a new sink-message event. 具体参考GstMessage
void	gst_event_parse_sink_message ()	解析gst_event_new_sink_message ()
GstEvent *	gst_event_new_reconfigure ()	Create a new reconfigure event. 用于下游通知上游重新协商caps
GstEvent *	gst_event_new_caps ()	Create a new CAPS event for caps .
void	gst_event_parse_caps ()	解析gst_event_new_caps ()
GstEvent *	gst_event_new_toc ()	Generate a TOC event from the given toc ,具体参考SstToc，用于通知TOC发生变化
void	gst_event_parse_toc ()	解析gst_event_new_toc ()
GstEvent *	gst_event_new_toc_select ()	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 .
void	gst_event_parse_toc_select ()	解析gst_event_new_toc_select ()
GstEvent *	gst_event_new_segment_done ()	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.
void	gst_event_parse_segment_done ()	解析gst_event_parse_segment_done ()
GstEvent *	gst_event_new_protection ()	Creates a new event containing information specific to a particular protection system
void	gst_event_parse_protection ()	解析gst_event_parse_protection ()
GstEvent *	gst_event_new_select_streams ()	Allocate a new select-streams event.
void	gst_event_parse_select_streams ()	解析gst_event_parse_select_streams ()
GstEvent *	gst_event_new_stream_collection ()	Create a new STREAM_COLLECTION event.
void	gst_event_parse_stream_collection ()	解析gst_event_new_stream_collection ()
GstEvent *	gst_event_new_stream_group_done ()	Create a new Stream Group Done event. Elements that receive the event on a pad should handle it mostly like EOS
void	gst_event_parse_stream_group_done ()	解析gst_event_new_stream_group_done ()

Object Hierarchy

    GBoxed
    ╰── GstEvent

 

 

参考资料：

1. https://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/GstEvent.html

 

---

有任何问题，请联系knowledgebao@163.com