## gstrtpbuffer

gstrtpbuffer — Helper methods for dealing with RTP buffers

## Synopsis

    #include <gst/rtp/gstrtpbuffer.h>

    #define             GST_RTP_VERSION
    void                gst_rtp_buffer_allocate_data        (GstBuffer *buffer,
                                                             guint payload_len,
                                                             guint8 pad_len,
                                                             guint8 csrc_count);
    GstBuffer*          gst_rtp_buffer_new_take_data        (gpointer data,
                                                             guint len);
    GstBuffer*          gst_rtp_buffer_new_copy_data        (gpointer data,
                                                             guint len);
    GstBuffer*          gst_rtp_buffer_new_allocate         (guint payload_len,
                                                             guint8 pad_len,
                                                             guint8 csrc_count);
    GstBuffer*          gst_rtp_buffer_new_allocate_len     (guint packet_len,
                                                             guint8 pad_len,
                                                             guint8 csrc_count);
    guint               gst_rtp_buffer_calc_header_len      (guint8 csrc_count);
    guint               gst_rtp_buffer_calc_packet_len      (guint payload_len,
                                                             guint8 pad_len,
                                                             guint8 csrc_count);
    guint               gst_rtp_buffer_calc_payload_len     (guint packet_len,
                                                             guint8 pad_len,
                                                             guint8 csrc_count);
    gboolean            gst_rtp_buffer_validate             (GstBuffer *buffer);
    gboolean            gst_rtp_buffer_validate_data        (guint8 *data,
                                                             guint len);
    void                gst_rtp_buffer_set_packet_len       (GstBuffer *buffer,
                                                             guint len);
    guint               gst_rtp_buffer_get_packet_len       (GstBuffer *buffer);
    guint               gst_rtp_buffer_get_header_len       (GstBuffer *buffer);
    guint8              gst_rtp_buffer_get_version          (GstBuffer *buffer);
    void                gst_rtp_buffer_set_version          (GstBuffer *buffer,
                                                             guint8 version);
    gboolean            gst_rtp_buffer_get_padding          (GstBuffer *buffer);
    void                gst_rtp_buffer_set_padding          (GstBuffer *buffer,
                                                             gboolean padding);
    void                gst_rtp_buffer_pad_to               (GstBuffer *buffer,
                                                             guint len);
    gboolean            gst_rtp_buffer_get_extension        (GstBuffer *buffer);
    void                gst_rtp_buffer_set_extension        (GstBuffer *buffer,
                                                             gboolean extension);
    gboolean            gst_rtp_buffer_get_extension_data   (GstBuffer *buffer,
                                                             guint16 *bits,
                                                             gpointer *data,
                                                             guint *wordlen);
    guint32             gst_rtp_buffer_get_ssrc             (GstBuffer *buffer);
    void                gst_rtp_buffer_set_ssrc             (GstBuffer *buffer,
                                                             guint32 ssrc);
    guint8              gst_rtp_buffer_get_csrc_count       (GstBuffer *buffer);
    guint32             gst_rtp_buffer_get_csrc             (GstBuffer *buffer,
                                                             guint8 idx);
    void                gst_rtp_buffer_set_csrc             (GstBuffer *buffer,
                                                             guint8 idx,
                                                             guint32 csrc);
    gboolean            gst_rtp_buffer_get_marker           (GstBuffer *buffer);
    void                gst_rtp_buffer_set_marker           (GstBuffer *buffer,
                                                             gboolean marker);
    guint8              gst_rtp_buffer_get_payload_type     (GstBuffer *buffer);
    void                gst_rtp_buffer_set_payload_type     (GstBuffer *buffer,
                                                             guint8 payload_type);
    guint16             gst_rtp_buffer_get_seq              (GstBuffer *buffer);
    void                gst_rtp_buffer_set_seq              (GstBuffer *buffer,
                                                             guint16 seq);
    guint32             gst_rtp_buffer_get_timestamp        (GstBuffer *buffer);
    void                gst_rtp_buffer_set_timestamp        (GstBuffer *buffer,
                                                             guint32 timestamp);
    GstBuffer*          gst_rtp_buffer_get_payload_buffer   (GstBuffer *buffer);
    GstBuffer*          gst_rtp_buffer_get_payload_subbuffer
                                                            (GstBuffer *buffer,
                                                             guint offset,
                                                             guint len);
    guint               gst_rtp_buffer_get_payload_len      (GstBuffer *buffer);
    gpointer            gst_rtp_buffer_get_payload          (GstBuffer *buffer);
    guint32             gst_rtp_buffer_default_clock_rate   (guint8 payload_type);
    gint                gst_rtp_buffer_compare_seqnum       (guint16 seqnum1,
                                                             guint16 seqnum2);
    guint64             gst_rtp_buffer_ext_timestamp        (guint64 *exttimestamp,
                                                             guint32 timestamp);

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

Last reviewed on 2006-07-17 (0.10.10)

## Details

### GST_RTP_VERSION

    #define GST_RTP_VERSION 2

The supported RTP version 2.

### 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`. MALLOCDATA of `buffer` will be overwritten and will not be freed. All other RTP header fields will be set to 0/FALSE.

`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,
                                                             guint 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.

`data` : | data for the new buffer
`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,
                                                             guint 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.

`data` : | data for the new buffer
`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.

`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.

`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_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.

`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.

`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.

`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_validate ()

    gboolean            gst_rtp_buffer_validate             (GstBuffer *buffer);

Check if the data pointed to by `buffer` is a valid RTP packet using `gst_rtp_buffer_validate_data()`. Use this function to validate a packet before using the other functions in this module.

`buffer` : | the buffer to validate
Returns : | TRUE if `buffer` is a valid RTP packet.

### gst_rtp_buffer_validate_data ()

    gboolean            gst_rtp_buffer_validate_data        (guint8 *data,
                                                             guint len);

Check if the `data` and `size` point to the data of a valid RTP packet. This function checks the length, version and padding of the packet data. Use this function to validate a packet before using the other functions in this module.

`data` : | the data to validate
`len` : | the length of `data` to validate
Returns : | TRUE if the data points to a valid RTP packet.

### gst_rtp_buffer_set_packet_len ()

    void                gst_rtp_buffer_set_packet_len       (GstBuffer *buffer,
                                                             guint len);

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

`buffer` : | the buffer
`len` : | the new packet length

### gst_rtp_buffer_get_packet_len ()

    guint               gst_rtp_buffer_get_packet_len       (GstBuffer *buffer);

Return the total length of the packet in `buffer`.

`buffer` : | the buffer
Returns : | The total length of the packet in `buffer`.

### gst_rtp_buffer_get_header_len ()

    guint               gst_rtp_buffer_get_header_len       (GstBuffer *buffer);

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

`buffer` : | the buffer
Returns : | The total length of the header in `buffer`.

### gst_rtp_buffer_get_version ()

    guint8              gst_rtp_buffer_get_version          (GstBuffer *buffer);

Get the version number of the RTP packet in `buffer`.

`buffer` : | the buffer
Returns : | The version of `buffer`.

### gst_rtp_buffer_set_version ()

    void                gst_rtp_buffer_set_version          (GstBuffer *buffer,
                                                             guint8 version);

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

`buffer` : | the buffer
`version` : | the new version

### gst_rtp_buffer_get_padding ()

    gboolean            gst_rtp_buffer_get_padding          (GstBuffer *buffer);

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

`buffer` : | the buffer
Returns : | TRUE if `buffer` has the padding bit set.

### gst_rtp_buffer_set_padding ()

    void                gst_rtp_buffer_set_padding          (GstBuffer *buffer,
                                                             gboolean padding);

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

`buffer` : | the buffer
`padding` : | the new padding

### gst_rtp_buffer_pad_to ()

    void                gst_rtp_buffer_pad_to               (GstBuffer *buffer,
                                                             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.

`buffer` : | the buffer
`len` : | the new amount of padding

### gst_rtp_buffer_get_extension ()

    gboolean            gst_rtp_buffer_get_extension        (GstBuffer *buffer);

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

`buffer` : | the buffer
Returns : | TRUE if `buffer` has the extension bit set.

### gst_rtp_buffer_set_extension ()

    void                gst_rtp_buffer_set_extension        (GstBuffer *buffer,
                                                             gboolean extension);

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

`buffer` : | the buffer
`extension` : | the new extension

### gst_rtp_buffer_get_extension_data ()

    gboolean            gst_rtp_buffer_get_extension_data   (GstBuffer *buffer,
                                                             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.

`buffer` : | the buffer
`bits` : | location for result bits
`data` : | location for data
`wordlen` : | location for length of `data` in 32 bits words
Returns : | TRUE if `buffer` had the extension bit set.

Since 0.10.15

### gst_rtp_buffer_get_ssrc ()

    guint32             gst_rtp_buffer_get_ssrc             (GstBuffer *buffer);

Get the SSRC of the RTP packet in `buffer`.

`buffer` : | the buffer
Returns : | the SSRC of `buffer` in host order.

### gst_rtp_buffer_set_ssrc ()

    void                gst_rtp_buffer_set_ssrc             (GstBuffer *buffer,
                                                             guint32 ssrc);

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

`buffer` : | the buffer
`ssrc` : | the new SSRC

### gst_rtp_buffer_get_csrc_count ()

    guint8              gst_rtp_buffer_get_csrc_count       (GstBuffer *buffer);

Get the CSRC count of the RTP packet in `buffer`.

`buffer` : | the buffer
Returns : | the CSRC count of `buffer`.

### gst_rtp_buffer_get_csrc ()

    guint32             gst_rtp_buffer_get_csrc             (GstBuffer *buffer,
                                                             guint8 idx);

Get the CSRC at index `idx` in `buffer`.

`buffer` : | the buffer
`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             (GstBuffer *buffer,
                                                             guint8 idx,
                                                             guint32 csrc);

Modify the CSRC at index `idx` in `buffer` to `csrc`.

`buffer` : | the buffer
`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           (GstBuffer *buffer);

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

`buffer` : | the buffer
Returns : | TRUE if `buffer` has the marker bit set.

### gst_rtp_buffer_set_marker ()

    void                gst_rtp_buffer_set_marker           (GstBuffer *buffer,
                                                             gboolean marker);

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

`buffer` : | the buffer
`marker` : | the new marker

### gst_rtp_buffer_get_payload_type ()

    guint8              gst_rtp_buffer_get_payload_type     (GstBuffer *buffer);

Get the payload type of the RTP packet in `buffer`.

`buffer` : | the buffer
Returns : | The payload type.

### gst_rtp_buffer_set_payload_type ()

    void                gst_rtp_buffer_set_payload_type     (GstBuffer *buffer,
                                                             guint8 payload_type);

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

`buffer` : | the buffer
`payload_type` : | the new type

### gst_rtp_buffer_get_seq ()

    guint16             gst_rtp_buffer_get_seq              (GstBuffer *buffer);

Get the sequence number of the RTP packet in `buffer`.

`buffer` : | the buffer
Returns : | The sequence number in host order.

### gst_rtp_buffer_set_seq ()

    void                gst_rtp_buffer_set_seq              (GstBuffer *buffer,
                                                             guint16 seq);

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

`buffer` : | the buffer
`seq` : | the new sequence number

### gst_rtp_buffer_get_timestamp ()

    guint32             gst_rtp_buffer_get_timestamp        (GstBuffer *buffer);

Get the timestamp of the RTP packet in `buffer`.

`buffer` : | the buffer
Returns : | The timestamp in host order.

### gst_rtp_buffer_set_timestamp ()

    void                gst_rtp_buffer_set_timestamp        (GstBuffer *buffer,
                                                             guint32 timestamp);

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

`buffer` : | the buffer
`timestamp` : | the new timestamp

### gst_rtp_buffer_get_payload_buffer ()

    GstBuffer*          gst_rtp_buffer_get_payload_buffer   (GstBuffer *buffer);

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.

`buffer` : | the buffer
Returns : | A new buffer with the data of the payload.

### gst_rtp_buffer_get_payload_subbuffer ()

    GstBuffer*          gst_rtp_buffer_get_payload_subbuffer
                                                            (GstBuffer *buffer,
                                                             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` if subbuffered.

`buffer` : | the buffer
`offset` : | the offset in the payload
`len` : | the length in the payload
Returns : | A new buffer with the specified data of the payload.

Since 0.10.10

### gst_rtp_buffer_get_payload_len ()

    guint               gst_rtp_buffer_get_payload_len      (GstBuffer *buffer);

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

`buffer` : | the buffer
Returns : | The length of the payload in `buffer`.

### gst_rtp_buffer_get_payload ()

    gpointer            gst_rtp_buffer_get_payload          (GstBuffer *buffer);

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

`buffer` : | the buffer
Returns : | A pointer to the payload data in `buffer`.

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

`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.

Since 0.10.13

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

`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`.

Since 0.10.15

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

`exttimestamp` : | a previous extended timestamp
`timestamp` : | a new timestamp
Returns : | The extended timestamp of `timestamp`.

Since 0.10.15

## See Also

GstBaseRTPPayload, GstBaseRTPDepayload, gstrtcpbuffer