GStreamer Base Plugins 1.0 Library Reference Manual: gstrtpbuffer

## 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

#define | GST_RTP_VERSION
struct | GstRTPBuffer
#define | GST_RTP_BUFFER_INIT

## 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