Gstreamer-GstEvent
相关连接：https://blog.csdn.net/knowledgebao/article/details/84621238
Includes
#include
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 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
参考资料：
- https://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/GstEvent.html
有任何问题，请联系[email protected]