gstdataprotocol

gstdataprotocol — implements GStreamer Data Protocol to serialize buffers, caps and events.

Synopsis


#include <gst/dataprotocol/dataprotocol.h>


enum        GstDPHeaderFlag;
enum        GstDPPayloadType;
#define     GST_DP_HEADER_LENGTH
#define     GST_DP_VERSION_MAJOR
#define     GST_DP_VERSION_MINOR
void        gst_dp_init                     (void);
guint32     gst_dp_header_payload_length    (const guint8 *header);
GstDPPayloadType gst_dp_header_payload_type (const guint8 *header);
gboolean    gst_dp_header_from_buffer       (const GstBuffer *buffer,
                                             GstDPHeaderFlag flags,
                                             guint *length,
                                             guint8 **header);
gboolean    gst_dp_packet_from_caps         (const GstCaps *caps,
                                             GstDPHeaderFlag flags,
                                             guint *length,
                                             guint8 **header,
                                             guint8 **payload);
gboolean    gst_dp_packet_from_event        (const GstEvent *event,
                                             GstDPHeaderFlag flags,
                                             guint *length,
                                             guint8 **header,
                                             guint8 **payload);
GstBuffer*  gst_dp_buffer_from_header       (guint header_length,
                                             const guint8 *header);
GstCaps*    gst_dp_caps_from_packet         (guint header_length,
                                             const guint8 *header,
                                             const guint8 *payload);
GstEvent*   gst_dp_event_from_packet        (guint header_length,
                                             const guint8 *header,
                                             const guint8 *payload);
gboolean    gst_dp_validate_header          (guint header_length,
                                             const guint8 *header);
gboolean    gst_dp_validate_payload         (guint header_length,
                                             const guint8 *header,
                                             const guint8 *payload);
gboolean    gst_dp_validate_packet          (guint header_length,
                                             const guint8 *header,
                                             const guint8 *payload);

Description

This helper library provides serialization of GstBuffer, GstCaps and GstEvent structures.

This serialization can be useful when GStreamer needs to interface with the outside world to transport data between different GStreamer pipelines. The connections with the outside world generally don't have mechanisms to transport properties of these structures.

For example, transporting buffers across named pipes doesn't keep the buffer size. Network elements that transport GStreamer data across network connections also need a protocol to do this.

Details

enum GstDPHeaderFlag

typedef enum {
  GST_DP_HEADER_FLAG_NONE        = 0,
  GST_DP_HEADER_FLAG_CRC_HEADER  = (1 << 0),
  GST_DP_HEADER_FLAG_CRC_PAYLOAD = (1 << 1),
  GST_DP_HEADER_FLAG_CRC         = (1 << 1) | (1 <<0),
} GstDPHeaderFlag;

header flags for the dataprotocol.

GST_DP_HEADER_FLAG_NONE No flag present.
GST_DP_HEADER_FLAG_CRC_HEADER a header CRC field is present.
GST_DP_HEADER_FLAG_CRC_PAYLOAD a payload CRC field is present.
GST_DP_HEADER_FLAG_CRC a CRC for header and payload is present.

enum GstDPPayloadType

typedef enum {
  GST_DP_PAYLOAD_NONE            = 0,
  GST_DP_PAYLOAD_BUFFER,
  GST_DP_PAYLOAD_CAPS,
  GST_DP_PAYLOAD_EVENT_NONE      = 64,
} GstDPPayloadType;

The GDP payload types. a GstEvent payload type is encoded with the event type number starting from GST_DP_PAYLOAD_EVENT_NONE.

GST_DP_PAYLOAD_NONE Invalid payload type.
GST_DP_PAYLOAD_BUFFER GstBuffer payload packet.
GST_DP_PAYLOAD_CAPS GstCaps payload packet.
GST_DP_PAYLOAD_EVENT_NONE First value of GstEvent payload packets.

GST_DP_HEADER_LENGTH

#define GST_DP_HEADER_LENGTH 62 

The header size in bytes.


GST_DP_VERSION_MAJOR

#define GST_DP_VERSION_MAJOR 0

The major version number of the GStreamer Data Protocol.


GST_DP_VERSION_MINOR

#define GST_DP_VERSION_MINOR 2

The minor version number of the GStreamer Data Protocol.


gst_dp_init ()

void        gst_dp_init                     (void);

Initialize GStreamer Data Protocol library.

Should be called before using these functions from source linking to this source file.


gst_dp_header_payload_length ()

guint32     gst_dp_header_payload_length    (const guint8 *header);

Get the length of the payload described by header.

header : the byte header of the packet array
Returns : the length of the payload this header describes.

gst_dp_header_payload_type ()

GstDPPayloadType gst_dp_header_payload_type (const guint8 *header);

Get the type of the payload described by header.

header : the byte header of the packet array
Returns : the GstDPPayloadType the payload this header describes.

gst_dp_header_from_buffer ()

gboolean    gst_dp_header_from_buffer       (const GstBuffer *buffer,
                                             GstDPHeaderFlag flags,
                                             guint *length,
                                             guint8 **header);

Creates a GDP header from the given buffer.

buffer : a GstBuffer to create a header for
flags : the GDPHeaderFlags to create the header with
length : a guint pointer to store the header length in
header : a guint8 * pointer to store a newly allocated header byte array in
Returns : TRUE if the header was successfully created.

gst_dp_packet_from_caps ()

gboolean    gst_dp_packet_from_caps         (const GstCaps *caps,
                                             GstDPHeaderFlag flags,
                                             guint *length,
                                             guint8 **header,
                                             guint8 **payload);

Creates a GDP packet from the given caps.

caps : a GstCaps to create a packet for
flags : the GDPHeaderFlags to create the header with
length : a guint pointer to store the header length in
header : a guint8 pointer to store a newly allocated header byte array in
payload : a guint8 pointer to store a newly allocated payload byte array in
Returns : TRUE if the packet was successfully created.

gst_dp_packet_from_event ()

gboolean    gst_dp_packet_from_event        (const GstEvent *event,
                                             GstDPHeaderFlag flags,
                                             guint *length,
                                             guint8 **header,
                                             guint8 **payload);

Creates a GDP packet from the given event.

event : a GstEvent to create a packet for
flags : the GDPHeaderFlags to create the header with
length : a guint pointer to store the header length in
header : a guint8 pointer to store a newly allocated header byte array in
payload : a guint8 pointer to store a newly allocated payload byte array in
Returns : TRUE if the packet was successfully created.

gst_dp_buffer_from_header ()

GstBuffer*  gst_dp_buffer_from_header       (guint header_length,
                                             const guint8 *header);

Creates a newly allocated GstBuffer from the given header. The buffer data needs to be copied into it before validating.

Use this function if you want to pre-allocate a buffer based on the packet header to read the packet payload in to.

header_length : the length of the packet header
header : the byte array of the packet header
Returns : TRUE if the buffer was successfully created.

gst_dp_caps_from_packet ()

GstCaps*    gst_dp_caps_from_packet         (guint header_length,
                                             const guint8 *header,
                                             const guint8 *payload);

Creates a newly allocated GstCaps from the given packet.

header_length : the length of the packet header
header : the byte array of the packet header
payload : the byte array of the packet payload
Returns : TRUE if the caps was successfully created.

gst_dp_event_from_packet ()

GstEvent*   gst_dp_event_from_packet        (guint header_length,
                                             const guint8 *header,
                                             const guint8 *payload);

Creates a newly allocated GstEvent from the given packet.

header_length : the length of the packet header
header : the byte array of the packet header
payload : the byte array of the packet payload
Returns : TRUE if the event was successfully created.

gst_dp_validate_header ()

gboolean    gst_dp_validate_header          (guint header_length,
                                             const guint8 *header);

Validates the given packet header by checking the CRC checksum.

header_length : the length of the packet header
header : the byte array of the packet header
Returns : TRUE if the CRC matches, or no CRC checksum is present.

gst_dp_validate_payload ()

gboolean    gst_dp_validate_payload         (guint header_length,
                                             const guint8 *header,
                                             const guint8 *payload);

Validates the given packet payload using the given packet header by checking the CRC checksum.

header_length : the length of the packet header
header : the byte array of the packet header
payload : the byte array of the packet payload
Returns : TRUE if the CRC matches, or no CRC checksum is present.

gst_dp_validate_packet ()

gboolean    gst_dp_validate_packet          (guint header_length,
                                             const guint8 *header,
                                             const guint8 *payload);

Validates the given packet by checking version information and checksums.

header_length : the length of the packet header
header : the byte array of the packet header
payload : the byte array of the packet payload
Returns : TRUE if the packet validates.

See Also

GstBuffer, GstCaps, GstEvent