gstrtpbuffer

gstrtpbuffer — Helper methods for dealing with RTP buffers

Functions

void gst_rtp_buffer_allocate_data ()
GstBuffer * gst_rtp_buffer_new_take_data ()
GstBuffer * gst_rtp_buffer_new_copy_data ()
GstBuffer * gst_rtp_buffer_new_allocate ()
GstBuffer * gst_rtp_buffer_new_allocate_len ()
gboolean gst_rtp_buffer_map ()
void gst_rtp_buffer_unmap ()
guint gst_rtp_buffer_calc_header_len ()
guint gst_rtp_buffer_calc_packet_len ()
guint gst_rtp_buffer_calc_payload_len ()
void gst_rtp_buffer_set_packet_len ()
guint gst_rtp_buffer_get_packet_len ()
guint gst_rtp_buffer_get_header_len ()
guint8 gst_rtp_buffer_get_version ()
void gst_rtp_buffer_set_version ()
gboolean gst_rtp_buffer_get_padding ()
void gst_rtp_buffer_set_padding ()
void gst_rtp_buffer_pad_to ()
gboolean gst_rtp_buffer_get_extension ()
void gst_rtp_buffer_set_extension ()
gboolean gst_rtp_buffer_get_extension_data ()
guint32 gst_rtp_buffer_get_ssrc ()
void gst_rtp_buffer_set_ssrc ()
guint8 gst_rtp_buffer_get_csrc_count ()
guint32 gst_rtp_buffer_get_csrc ()
void gst_rtp_buffer_set_csrc ()
gboolean gst_rtp_buffer_get_marker ()
void gst_rtp_buffer_set_marker ()
guint8 gst_rtp_buffer_get_payload_type ()
void gst_rtp_buffer_set_payload_type ()
guint16 gst_rtp_buffer_get_seq ()
void gst_rtp_buffer_set_seq ()
guint32 gst_rtp_buffer_get_timestamp ()
void gst_rtp_buffer_set_timestamp ()
GstBuffer * gst_rtp_buffer_get_payload_buffer ()
GstBuffer * gst_rtp_buffer_get_payload_subbuffer ()
guint gst_rtp_buffer_get_payload_len ()
gpointer gst_rtp_buffer_get_payload ()
guint32 gst_rtp_buffer_default_clock_rate ()
gint gst_rtp_buffer_compare_seqnum ()
guint64 gst_rtp_buffer_ext_timestamp ()
gboolean gst_rtp_buffer_set_extension_data ()
gboolean gst_rtp_buffer_get_extension_onebyte_header ()
gboolean gst_rtp_buffer_get_extension_twobytes_header ()
gboolean gst_rtp_buffer_add_extension_onebyte_header ()
gboolean gst_rtp_buffer_add_extension_twobytes_header ()

Types and Values

Object Hierarchy


Includes

#include <gst/rtp/gstrtpbuffer.h>

Description

The GstRTPBuffer helper functions makes it easy to parse and create regular GstBuffer objects that contain RTP payloads. These buffers are typically of 'application/x-rtp' GstCaps.

Functions

gst_rtp_buffer_allocate_data ()

void
gst_rtp_buffer_allocate_data (GstBuffer *buffer,
                              guint payload_len,
                              guint8 pad_len,
                              guint8 csrc_count);

Allocate enough data in buffer to hold an RTP packet with csrc_count CSRCs, a payload length of payload_len and padding of pad_len . buffer must be writable and all previous memory in buffer will be freed. If pad_len is >0, the padding bit will be set. All other RTP header fields will be set to 0/FALSE.

Parameters

buffer

a GstBuffer

 

payload_len

the length of the payload

 

pad_len

the amount of padding

 

csrc_count

the number of CSRC entries

 

gst_rtp_buffer_new_take_data ()

GstBuffer *
gst_rtp_buffer_new_take_data (gpointer data,
                              gsize len);

Create a new buffer and set the data and size of the buffer to data and len respectively. data will be freed when the buffer is unreffed, so this function transfers ownership of data to the new buffer.

Parameters

data

data for the new buffer.

[array length=len][transfer full][element-type guint8]

len

the length of data

 

Returns

A newly allocated buffer with data and of size len .


gst_rtp_buffer_new_copy_data ()

GstBuffer *
gst_rtp_buffer_new_copy_data (gpointer data,
                              gsize len);

Create a new buffer and set the data to a copy of len bytes of data and the size to len . The data will be freed when the buffer is freed.

Parameters

data

data for the new buffer.

[array length=len][element-type guint8]

len

the length of data

 

Returns

A newly allocated buffer with a copy of data and of size len .


gst_rtp_buffer_new_allocate ()

GstBuffer *
gst_rtp_buffer_new_allocate (guint payload_len,
                             guint8 pad_len,
                             guint8 csrc_count);

Allocate a new GstBuffer with enough data to hold an RTP packet with csrc_count CSRCs, a payload length of payload_len and padding of pad_len . All other RTP header fields will be set to 0/FALSE.

Parameters

payload_len

the length of the payload

 

pad_len

the amount of padding

 

csrc_count

the number of CSRC entries

 

Returns

A newly allocated buffer that can hold an RTP packet with given parameters.


gst_rtp_buffer_new_allocate_len ()

GstBuffer *
gst_rtp_buffer_new_allocate_len (guint packet_len,
                                 guint8 pad_len,
                                 guint8 csrc_count);

Create a new GstBuffer that can hold an RTP packet that is exactly packet_len long. The length of the payload depends on pad_len and csrc_count and can be calculated with gst_rtp_buffer_calc_payload_len(). All RTP header fields will be set to 0/FALSE.

Parameters

packet_len

the total length of the packet

 

pad_len

the amount of padding

 

csrc_count

the number of CSRC entries

 

Returns

A newly allocated buffer that can hold an RTP packet of packet_len .


gst_rtp_buffer_map ()

gboolean
gst_rtp_buffer_map (GstBuffer *buffer,
                    GstMapFlags flags,
                    GstRTPBuffer *rtp);

Map the contents of buffer into rtp .

Parameters

buffer

a GstBuffer

 

flags

GstMapFlags

 

rtp

a GstRTPBuffer.

[out]

Returns

TRUE if buffer could be mapped.


gst_rtp_buffer_unmap ()

void
gst_rtp_buffer_unmap (GstRTPBuffer *rtp);

Unmap rtp previously mapped with gst_rtp_buffer_map().

Parameters

rtp

a GstRTPBuffer

 

gst_rtp_buffer_calc_header_len ()

guint
gst_rtp_buffer_calc_header_len (guint8 csrc_count);

Calculate the header length of an RTP packet with csrc_count CSRC entries. An RTP packet can have at most 15 CSRC entries.

Parameters

csrc_count

the number of CSRC entries

 

Returns

The length of an RTP header with csrc_count CSRC entries.


gst_rtp_buffer_calc_packet_len ()

guint
gst_rtp_buffer_calc_packet_len (guint payload_len,
                                guint8 pad_len,
                                guint8 csrc_count);

Calculate the total length of an RTP packet with a payload size of payload_len , a padding of pad_len and a csrc_count CSRC entries.

Parameters

payload_len

the length of the payload

 

pad_len

the amount of padding

 

csrc_count

the number of CSRC entries

 

Returns

The total length of an RTP header with given parameters.


gst_rtp_buffer_calc_payload_len ()

guint
gst_rtp_buffer_calc_payload_len (guint packet_len,
                                 guint8 pad_len,
                                 guint8 csrc_count);

Calculate the length of the payload of an RTP packet with size packet_len , a padding of pad_len and a csrc_count CSRC entries.

Parameters

packet_len

the length of the total RTP packet

 

pad_len

the amount of padding

 

csrc_count

the number of CSRC entries

 

Returns

The length of the payload of an RTP packet with given parameters.


gst_rtp_buffer_set_packet_len ()

void
gst_rtp_buffer_set_packet_len (GstRTPBuffer *rtp,
                               guint len);

Set the total rtp size to len . The data in the buffer will be made larger if needed. Any padding will be removed from the packet.

Parameters

rtp

the RTP packet

 

len

the new packet length

 

gst_rtp_buffer_get_packet_len ()

guint
gst_rtp_buffer_get_packet_len (GstRTPBuffer *rtp);

Return the total length of the packet in buffer .

Parameters

rtp

the RTP packet

 

Returns

The total length of the packet in buffer .


gst_rtp_buffer_get_header_len ()

guint
gst_rtp_buffer_get_header_len (GstRTPBuffer *rtp);

Return the total length of the header in buffer . This include the length of the fixed header, the CSRC list and the extension header.

Parameters

rtp

the RTP packet

 

Returns

The total length of the header in buffer .


gst_rtp_buffer_get_version ()

guint8
gst_rtp_buffer_get_version (GstRTPBuffer *rtp);

Get the version number of the RTP packet in buffer .

Parameters

rtp

the RTP packet

 

Returns

The version of buffer .


gst_rtp_buffer_set_version ()

void
gst_rtp_buffer_set_version (GstRTPBuffer *rtp,
                            guint8 version);

Set the version of the RTP packet in buffer to version .

Parameters

rtp

the RTP packet

 

version

the new version

 

gst_rtp_buffer_get_padding ()

gboolean
gst_rtp_buffer_get_padding (GstRTPBuffer *rtp);

Check if the padding bit is set on the RTP packet in buffer .

Parameters

rtp

the RTP packet

 

Returns

TRUE if buffer has the padding bit set.


gst_rtp_buffer_set_padding ()

void
gst_rtp_buffer_set_padding (GstRTPBuffer *rtp,
                            gboolean padding);

Set the padding bit on the RTP packet in buffer to padding .

Parameters

rtp

the buffer

 

padding

the new padding

 

gst_rtp_buffer_pad_to ()

void
gst_rtp_buffer_pad_to (GstRTPBuffer *rtp,
                       guint len);

Set the amount of padding in the RTP packet in buffer to len . If len is 0, the padding is removed.

NOTE: This function does not work correctly.

Parameters

rtp

the RTP packet

 

len

the new amount of padding

 

gst_rtp_buffer_get_extension ()

gboolean
gst_rtp_buffer_get_extension (GstRTPBuffer *rtp);

Check if the extension bit is set on the RTP packet in buffer .

Parameters

rtp

the RTP packet

 

Returns

TRUE if buffer has the extension bit set.


gst_rtp_buffer_set_extension ()

void
gst_rtp_buffer_set_extension (GstRTPBuffer *rtp,
                              gboolean extension);

Set the extension bit on the RTP packet in buffer to extension .

Parameters

rtp

the RTP packet

 

extension

the new extension

 

gst_rtp_buffer_get_extension_data ()

gboolean
gst_rtp_buffer_get_extension_data (GstRTPBuffer *rtp,
                                   guint16 *bits,
                                   gpointer *data,
                                   guint *wordlen);

Get the extension data. bits will contain the extension 16 bits of custom data. data will point to the data in the extension and wordlen will contain the length of data in 32 bits words.

If buffer did not contain an extension, this function will return FALSE with bits , data and wordlen unchanged.

Parameters

rtp

the RTP packet

 

bits

location for result bits.

[out]

data

location for data.

[out][array][element-type guint8][transfer none]

wordlen

location for length of data in 32 bits words.

[out]

Returns

TRUE if buffer had the extension bit set.


gst_rtp_buffer_get_ssrc ()

guint32
gst_rtp_buffer_get_ssrc (GstRTPBuffer *rtp);

Get the SSRC of the RTP packet in buffer .

Parameters

rtp

the RTP packet

 

Returns

the SSRC of buffer in host order.


gst_rtp_buffer_set_ssrc ()

void
gst_rtp_buffer_set_ssrc (GstRTPBuffer *rtp,
                         guint32 ssrc);

Set the SSRC on the RTP packet in buffer to ssrc .

Parameters

rtp

the RTP packet

 

ssrc

the new SSRC

 

gst_rtp_buffer_get_csrc_count ()

guint8
gst_rtp_buffer_get_csrc_count (GstRTPBuffer *rtp);

Get the CSRC count of the RTP packet in buffer .

Parameters

rtp

the RTP packet

 

Returns

the CSRC count of buffer .


gst_rtp_buffer_get_csrc ()

guint32
gst_rtp_buffer_get_csrc (GstRTPBuffer *rtp,
                         guint8 idx);

Get the CSRC at index idx in buffer .

Parameters

rtp

the RTP packet

 

idx

the index of the CSRC to get

 

Returns

the CSRC at index idx in host order.


gst_rtp_buffer_set_csrc ()

void
gst_rtp_buffer_set_csrc (GstRTPBuffer *rtp,
                         guint8 idx,
                         guint32 csrc);

Modify the CSRC at index idx in buffer to csrc .

Parameters

rtp

the RTP packet

 

idx

the CSRC index to set

 

csrc

the CSRC in host order to set at idx

 

gst_rtp_buffer_get_marker ()

gboolean
gst_rtp_buffer_get_marker (GstRTPBuffer *rtp);

Check if the marker bit is set on the RTP packet in buffer .

Parameters

rtp

the RTP packet

 

Returns

TRUE if buffer has the marker bit set.


gst_rtp_buffer_set_marker ()

void
gst_rtp_buffer_set_marker (GstRTPBuffer *rtp,
                           gboolean marker);

Set the marker bit on the RTP packet in buffer to marker .

Parameters

rtp

the RTP packet

 

marker

the new marker

 

gst_rtp_buffer_get_payload_type ()

guint8
gst_rtp_buffer_get_payload_type (GstRTPBuffer *rtp);

Get the payload type of the RTP packet in buffer .

Parameters

rtp

the RTP packet

 

Returns

The payload type.


gst_rtp_buffer_set_payload_type ()

void
gst_rtp_buffer_set_payload_type (GstRTPBuffer *rtp,
                                 guint8 payload_type);

Set the payload type of the RTP packet in buffer to payload_type .

Parameters

rtp

the RTP packet

 

payload_type

the new type

 

gst_rtp_buffer_get_seq ()

guint16
gst_rtp_buffer_get_seq (GstRTPBuffer *rtp);

Get the sequence number of the RTP packet in buffer .

Parameters

rtp

the RTP packet

 

Returns

The sequence number in host order.


gst_rtp_buffer_set_seq ()

void
gst_rtp_buffer_set_seq (GstRTPBuffer *rtp,
                        guint16 seq);

Set the sequence number of the RTP packet in buffer to seq .

Parameters

rtp

the RTP packet

 

seq

the new sequence number

 

gst_rtp_buffer_get_timestamp ()

guint32
gst_rtp_buffer_get_timestamp (GstRTPBuffer *rtp);

Get the timestamp of the RTP packet in buffer .

Parameters

rtp

the RTP packet

 

Returns

The timestamp in host order.


gst_rtp_buffer_set_timestamp ()

void
gst_rtp_buffer_set_timestamp (GstRTPBuffer *rtp,
                              guint32 timestamp);

Set the timestamp of the RTP packet in buffer to timestamp .

Parameters

rtp

the RTP packet

 

timestamp

the new timestamp

 

gst_rtp_buffer_get_payload_buffer ()

GstBuffer *
gst_rtp_buffer_get_payload_buffer (GstRTPBuffer *rtp);

Create a buffer of the payload of the RTP packet in buffer . This function will internally create a subbuffer of buffer so that a memcpy can be avoided.

Parameters

rtp

the RTP packet

 

Returns

A new buffer with the data of the payload.


gst_rtp_buffer_get_payload_subbuffer ()

GstBuffer *
gst_rtp_buffer_get_payload_subbuffer (GstRTPBuffer *rtp,
                                      guint offset,
                                      guint len);

Create a subbuffer of the payload of the RTP packet in buffer . offset bytes are skipped in the payload and the subbuffer will be of size len . If len is -1 the total payload starting from offset is subbuffered.

Parameters

rtp

the RTP packet

 

offset

the offset in the payload

 

len

the length in the payload

 

Returns

A new buffer with the specified data of the payload.


gst_rtp_buffer_get_payload_len ()

guint
gst_rtp_buffer_get_payload_len (GstRTPBuffer *rtp);

Get the length of the payload of the RTP packet in buffer .

Parameters

rtp

the RTP packet

 

Returns

The length of the payload in buffer .


gst_rtp_buffer_get_payload ()

gpointer
gst_rtp_buffer_get_payload (GstRTPBuffer *rtp);

Get a pointer to the payload data in buffer . This pointer is valid as long as a reference to buffer is held.

Parameters

rtp

the RTP packet

 

Returns

A pointer to the payload data in buffer .

[array][element-type guint8][transfer none]


gst_rtp_buffer_default_clock_rate ()

guint32
gst_rtp_buffer_default_clock_rate (guint8 payload_type);

Get the default clock-rate for the static payload type payload_type .

Parameters

payload_type

the static payload type

 

Returns

the default clock rate or -1 if the payload type is not static or the clock-rate is undefined.


gst_rtp_buffer_compare_seqnum ()

gint
gst_rtp_buffer_compare_seqnum (guint16 seqnum1,
                               guint16 seqnum2);

Compare two sequence numbers, taking care of wraparounds. This function returns the difference between seqnum1 and seqnum2 .

Parameters

seqnum1

a sequence number

 

seqnum2

a sequence number

 

Returns

a negative value if seqnum1 is bigger than seqnum2 , 0 if they are equal or a positive value if seqnum1 is smaller than segnum2 .


gst_rtp_buffer_ext_timestamp ()

guint64
gst_rtp_buffer_ext_timestamp (guint64 *exttimestamp,
                              guint32 timestamp);

Update the exttimestamp field with timestamp . For the first call of the method, exttimestamp should point to a location with a value of -1.

This function makes sure that the returned value is a constantly increasing value even in the case where there is a timestamp wraparound.

Parameters

exttimestamp

a previous extended timestamp

 

timestamp

a new timestamp

 

Returns

The extended timestamp of timestamp .


gst_rtp_buffer_set_extension_data ()

gboolean
gst_rtp_buffer_set_extension_data (GstRTPBuffer *rtp,
                                   guint16 bits,
                                   guint16 length);

Set the extension bit of the rtp buffer and fill in the bits and length of the extension header. If the existing extension data is not large enough, it will be made larger.

Parameters

rtp

the RTP packet

 

bits

the bits specific for the extension

 

length

the length that counts the number of 32-bit words in the extension, excluding the extension header ( therefore zero is a valid length)

 

Returns

True if done.


gst_rtp_buffer_get_extension_onebyte_header ()

gboolean
gst_rtp_buffer_get_extension_onebyte_header
                               (GstRTPBuffer *rtp,
                                guint8 id,
                                guint nth,
                                gpointer *data,
                                guint *size);

Parses RFC 5285 style header extensions with a one byte header. It will return the nth extension with the requested id.

Parameters

rtp

the RTP packet

 

id

The ID of the header extension to be read (between 1 and 14).

 

nth

Read the nth extension packet with the requested ID

 

data

location for data.

[out][array length=size][element-type guint8][transfer none]

size

the size of the data in bytes.

[out]

Returns

TRUE if buffer had the requested header extension


gst_rtp_buffer_get_extension_twobytes_header ()

gboolean
gst_rtp_buffer_get_extension_twobytes_header
                               (GstRTPBuffer *rtp,
                                guint8 *appbits,
                                guint8 id,
                                guint nth,
                                gpointer *data,
                                guint *size);

Parses RFC 5285 style header extensions with a two bytes header. It will return the nth extension with the requested id.

Parameters

rtp

the RTP packet

 

appbits

Application specific bits.

[out]

id

The ID of the header extension to be read (between 1 and 14).

 

nth

Read the nth extension packet with the requested ID

 

data

location for data.

[out][array length=size][element-type guint8][transfer none]

size

the size of the data in bytes.

[out]

Returns

TRUE if buffer had the requested header extension


gst_rtp_buffer_add_extension_onebyte_header ()

gboolean
gst_rtp_buffer_add_extension_onebyte_header
                               (GstRTPBuffer *rtp,
                                guint8 id,
                                gpointer data,
                                guint size);

Adds a RFC 5285 header extension with a one byte header to the end of the RTP header. If there is already a RFC 5285 header extension with a one byte header, the new extension will be appended. It will not work if there is already a header extension that does not follow the mecanism described in RFC 5285 or if there is a header extension with a two bytes header as described in RFC 5285. In that case, use gst_rtp_buffer_add_extension_twobytes_header()

Parameters

rtp

the RTP packet

 

id

The ID of the header extension (between 1 and 14).

 

data

location for data.

[array length=size][element-type guint8]

size

the size of the data in bytes

 

Returns

TRUE if header extension could be added


gst_rtp_buffer_add_extension_twobytes_header ()

gboolean
gst_rtp_buffer_add_extension_twobytes_header
                               (GstRTPBuffer *rtp,
                                guint8 appbits,
                                guint8 id,
                                gpointer data,
                                guint size);

Adds a RFC 5285 header extension with a two bytes header to the end of the RTP header. If there is already a RFC 5285 header extension with a two bytes header, the new extension will be appended. It will not work if there is already a header extension that does not follow the mecanism described in RFC 5285 or if there is a header extension with a one byte header as described in RFC 5285. In that case, use gst_rtp_buffer_add_extension_onebyte_header()

Parameters

rtp

the RTP packet

 

appbits

Application specific bits

 

id

The ID of the header extension

 

data

location for data.

[array length=size][element-type guint8]

size

the size of the data in bytes

 

Returns

TRUE if header extension could be added

Types and Values

GST_RTP_VERSION

#define GST_RTP_VERSION 2

The supported RTP version 2.


struct GstRTPBuffer

struct GstRTPBuffer {
  GstBuffer   *buffer;
  guint        state;
  gpointer     data[4];
  gsize        size[4];
  GstMapInfo   map[4];
};

Data structure that points to an RTP packet. The size of the structure is made public to allow stack allocations.

Members

GstBuffer *buffer;

pointer to RTP buffer

 

guint state;

internal state

 

gpointer data[4];

array of data

 

gsize size[4];

array of size

 

GstMapInfo map[4];

array of GstMapInfo

 

GST_RTP_BUFFER_INIT

#define             GST_RTP_BUFFER_INIT

See Also

GstRTPBasePayload, GstRTPBaseDepayload, gstrtcpbuffer