gstrtcpbuffer

gstrtcpbuffer — Helper methods for dealing with RTCP buffers

Synopsis


#include <gst/rtp/gstrtcpbuffer.h>


#define             GST_RTCP_VERSION
#define             GST_RTCP_MAX_SDES
#define             GST_RTCP_VALID_MASK
#define             GST_RTCP_VALID_VALUE
enum                GstRTCPType;
                    GstRTCPPacket;
enum                GstRTCPSDESType;
gboolean            gst_rtcp_buffer_add_packet          (GstBuffer *buffer,
                                                         GstRTCPType type,
                                                         GstRTCPPacket *packet);
gboolean            gst_rtcp_buffer_get_first_packet    (GstBuffer *buffer,
                                                         GstRTCPPacket *packet);
guint               gst_rtcp_buffer_get_packet_count    (GstBuffer *buffer);
GstBuffer*          gst_rtcp_buffer_new_copy_data       (gpointer data,
                                                         guint len);
GstBuffer*          gst_rtcp_buffer_new_take_data       (gpointer data,
                                                         guint len);
gboolean            gst_rtcp_buffer_validate            (GstBuffer *buffer);
gboolean            gst_rtcp_buffer_validate_data       (guint8 *data,
                                                         guint len);
gboolean            gst_rtcp_packet_add_rb              (GstRTCPPacket *packet,
                                                         guint32 ssrc,
                                                         guint8 fractionlost,
                                                         gint32 packetslost,
                                                         guint32 exthighestseq,
                                                         guint32 jitter,
                                                         guint32 lsr,
                                                         guint32 dlsr);
gboolean            gst_rtcp_packet_bye_add_ssrc        (GstRTCPPacket *packet,
                                                         guint32 ssrc);
gboolean            gst_rtcp_packet_bye_add_ssrcs       (GstRTCPPacket *packet,
                                                         guint32 *ssrc,
                                                         guint len);
guint32             gst_rtcp_packet_bye_get_nth_ssrc    (GstRTCPPacket *packet,
                                                         guint nth);
gchar*              gst_rtcp_packet_bye_get_reason      (GstRTCPPacket *packet);
guint8              gst_rtcp_packet_bye_get_reason_len  (GstRTCPPacket *packet);
guint               gst_rtcp_packet_bye_get_ssrc_count  (GstRTCPPacket *packet);
gboolean            gst_rtcp_packet_bye_set_reason      (GstRTCPPacket *packet,
                                                         const gchar *reason);
guint8              gst_rtcp_packet_get_count           (GstRTCPPacket *packet);
guint16             gst_rtcp_packet_get_length          (GstRTCPPacket *packet);
gboolean            gst_rtcp_packet_get_padding         (GstRTCPPacket *packet);
void                gst_rtcp_packet_get_rb              (GstRTCPPacket *packet,
                                                         guint nth,
                                                         guint32 *ssrc,
                                                         guint8 *fractionlost,
                                                         gint32 *packetslost,
                                                         guint32 *exthighestseq,
                                                         guint32 *jitter,
                                                         guint32 *lsr,
                                                         guint32 *dlsr);
guint               gst_rtcp_packet_get_rb_count        (GstRTCPPacket *packet);
GstRTCPType         gst_rtcp_packet_get_type            (GstRTCPPacket *packet);
gboolean            gst_rtcp_packet_move_to_next        (GstRTCPPacket *packet);
void                gst_rtcp_packet_remove              (GstRTCPPacket *packet);
guint32             gst_rtcp_packet_rr_get_ssrc         (GstRTCPPacket *packet);
void                gst_rtcp_packet_rr_set_ssrc         (GstRTCPPacket *packet,
                                                         guint32 ssrc);
gboolean            gst_rtcp_packet_sdes_first_item     (GstRTCPPacket *packet);
guint32             gst_rtcp_packet_sdes_get_ssrc       (GstRTCPPacket *packet);
gboolean            gst_rtcp_packet_sdes_next_item      (GstRTCPPacket *packet);
void                gst_rtcp_packet_set_rb              (GstRTCPPacket *packet,
                                                         guint nth,
                                                         guint32 ssrc,
                                                         guint8 fractionlost,
                                                         gint32 packetslost,
                                                         guint32 exthighestseq,
                                                         guint32 jitter,
                                                         guint32 lsr,
                                                         guint32 dlsr);
void                gst_rtcp_packet_sr_get_sender_info  (GstRTCPPacket *packet,
                                                         guint32 *ssrc,
                                                         guint64 *ntptime,
                                                         guint32 *rtptime,
                                                         guint32 *packet_count,
                                                         guint32 *octet_count);
void                gst_rtcp_packet_sr_set_sender_info  (GstRTCPPacket *packet,
                                                         guint32 ssrc,
                                                         guint64 ntptime,
                                                         guint32 rtptime,
                                                         guint32 packet_count,
                                                         guint32 octet_count);

Description

Note: The API in this module is not yet declared stable.

The GstRTPCBuffer helper functions makes it easy to parse and create regular GstBuffer objects that contain compound RTCP packets. These buffers are typically of 'application/x-rtcp' GstCaps.

An RTCP buffer consists of 1 or more GstRTCPPacket structures that you can retrieve with gst_rtcp_buffer_get_first_packet(). GstRTCPPacket acts as a pointer into the RTCP buffer; you can move to the next packet with gst_rtcp_packet_move_to_next().

Details

GST_RTCP_VERSION

#define GST_RTCP_VERSION 2

The supported RTCP version 2.

GST_RTCP_MAX_SDES

#define GST_RTCP_MAX_SDES 255

The maximum text length for an SDES item.

GST_RTCP_VALID_MASK

#define GST_RTCP_VALID_MASK (0xc000 | 0x2000 | 0xfe)

Mask for version, padding bit and packet type pair

GST_RTCP_VALID_VALUE

#define GST_RTCP_VALID_VALUE ((GST_RTCP_VERSION << 14) | GST_RTCP_TYPE_SR)

Valid value for the first two bytes of an RTCP packet after applying GST_RTCP_VALID_MASK to them.

enum GstRTCPType

typedef enum
{
  GST_RTCP_TYPE_INVALID = 0,
  GST_RTCP_TYPE_SR      = 200,
  GST_RTCP_TYPE_RR      = 201,
  GST_RTCP_TYPE_SDES    = 202,
  GST_RTCP_TYPE_BYE     = 203,
  GST_RTCP_TYPE_APP     = 204
} GstRTCPType;

Different RTCP packet types.

GST_RTCP_TYPE_INVALID

 Invalid type

GST_RTCP_TYPE_SR

 Sender report

GST_RTCP_TYPE_RR

 Receiver report

GST_RTCP_TYPE_SDES

 Source description

GST_RTCP_TYPE_BYE

 Goodbye

GST_RTCP_TYPE_APP

 Application defined

GstRTCPPacket

typedef struct {
  GstBuffer   *buffer;
  guint        offset;
} GstRTCPPacket;

Data structure that points to a packet at offset in buffer. The size of the structure is made public to allow stack allocations.

GstBuffer *buffer;

 pointer to RTCP buffer

guint offset;

 offset of packet in buffer data

enum GstRTCPSDESType

typedef enum 
{
  GST_RTCP_SDES_INVALID  = -1,
  GST_RTCP_SDES_END      = 0,
  GST_RTCP_SDES_CNAME    = 1,
  GST_RTCP_SDES_NAME     = 2,
  GST_RTCP_SDES_EMAIL    = 3,
  GST_RTCP_SDES_PHONE    = 4,
  GST_RTCP_SDES_LOC      = 5,
  GST_RTCP_SDES_TOOL     = 6,
  GST_RTCP_SDES_NOTE     = 7,
  GST_RTCP_SDES_PRIV     = 8
} GstRTCPSDESType;

Different types of SDES content.

GST_RTCP_SDES_INVALID

 Invalid SDES entry

GST_RTCP_SDES_END

 End of SDES list

GST_RTCP_SDES_CNAME

 Canonical name

GST_RTCP_SDES_NAME

 User name

GST_RTCP_SDES_EMAIL

 User's electronic mail address

GST_RTCP_SDES_PHONE

 User's phone number

GST_RTCP_SDES_LOC

 Geographic user location

GST_RTCP_SDES_TOOL

 Name of application or tool

GST_RTCP_SDES_NOTE

 Notice about the source

GST_RTCP_SDES_PRIV

 Private extensions

gst_rtcp_buffer_add_packet ()

gboolean            gst_rtcp_buffer_add_packet          (GstBuffer *buffer,
                                                         GstRTCPType type,
                                                         GstRTCPPacket *packet);

Add a new packet of type to buffer. packet will point to the newly created packet.

buffer :

 a valid RTCP buffer

type :

 the GstRTCPType of the new packet

packet :

 pointer to new packet

Returns :

 TRUE if the packet could be created. This function returns FALSE if the max mtu is exceeded for the buffer.

gst_rtcp_buffer_get_first_packet ()

gboolean            gst_rtcp_buffer_get_first_packet    (GstBuffer *buffer,
                                                         GstRTCPPacket *packet);

Initialize a new GstRTCPPacket pointer that points to the first packet in buffer.

buffer :

 a valid RTCP buffer

packet :

 a GstRTCPPacket

Returns :

 TRUE if the packet existed in buffer.

gst_rtcp_buffer_get_packet_count ()

guint               gst_rtcp_buffer_get_packet_count    (GstBuffer *buffer);

Get the number of RTCP packets in buffer.

buffer :

 a valid RTCP buffer

Returns :

 the number of RTCP packets in buffer.

gst_rtcp_buffer_new_copy_data ()

GstBuffer*          gst_rtcp_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_rtcp_buffer_new_take_data ()

GstBuffer*          gst_rtcp_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_rtcp_buffer_validate ()

gboolean            gst_rtcp_buffer_validate            (GstBuffer *buffer);

Check if the data pointed to by buffer is a valid RTCP packet using gst_rtcp_buffer_validate_data().

buffer :

 the buffer to validate

Returns :

 TRUE if buffer is a valid RTCP packet.

gst_rtcp_buffer_validate_data ()

gboolean            gst_rtcp_buffer_validate_data       (guint8 *data,
                                                         guint len);

Check if the data and size point to the data of a valid RTCP (compound) packet. 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 RTCP packet.

gst_rtcp_packet_add_rb ()

gboolean            gst_rtcp_packet_add_rb              (GstRTCPPacket *packet,
                                                         guint32 ssrc,
                                                         guint8 fractionlost,
                                                         gint32 packetslost,
                                                         guint32 exthighestseq,
                                                         guint32 jitter,
                                                         guint32 lsr,
                                                         guint32 dlsr);

Add a new report block to packet with the given values.

packet :

 a valid SR or RR GstRTCPPacket

ssrc :

 data source being reported

fractionlost :

 fraction lost since last SR/RR

packetslost :

 the cumululative number of packets lost

exthighestseq :

 the extended last sequence number received

jitter :

 the interarrival jitter

lsr :

 the last SR packet from this source

dlsr :

 the delay since last SR packet

Returns :

 TRUE if the packet was created. This function can return FALSE if the max MTU is exceeded or the number of report blocks is greater than GST_RTCP_MAX_RB_COUNT.

gst_rtcp_packet_bye_add_ssrc ()

gboolean            gst_rtcp_packet_bye_add_ssrc        (GstRTCPPacket *packet,
                                                         guint32 ssrc);

Add ssrc to the BYE packet.

packet :

 a valid BYE GstRTCPPacket

ssrc :

 an SSRC to add

Returns :

 TRUE if the ssrc was added. This function can return FALSE if the max MTU is exceeded or the number of sources blocks is greater than GST_RTCP_MAX_BYE_SSRC_COUNT.

gst_rtcp_packet_bye_add_ssrcs ()

gboolean            gst_rtcp_packet_bye_add_ssrcs       (GstRTCPPacket *packet,
                                                         guint32 *ssrc,
                                                         guint len);

Adds len SSRCs in ssrc to BYE packet.

packet :

 a valid BYE GstRTCPPacket

ssrc :

 an array of SSRCs to add

len :

 number of elements in ssrc

Returns :

 TRUE if the all the SSRCs were added. This function can return FALSE if the max MTU is exceeded or the number of sources blocks is greater than GST_RTCP_MAX_BYE_SSRC_COUNT.

gst_rtcp_packet_bye_get_nth_ssrc ()

guint32             gst_rtcp_packet_bye_get_nth_ssrc    (GstRTCPPacket *packet,
                                                         guint nth);

Get the nth SSRC of the BYE packet.

packet :

 a valid BYE GstRTCPPacket

nth :

 the nth SSRC to get

Returns :

 The nth SSRC of packet.

gst_rtcp_packet_bye_get_reason ()

gchar*              gst_rtcp_packet_bye_get_reason      (GstRTCPPacket *packet);

Get the reason in packet.

packet :

 a valid BYE GstRTCPPacket

Returns :

 The reason for the BYE packet or NULL if the packet did not contain a reason string. The string must be freed with g_free() after usage.

gst_rtcp_packet_bye_get_reason_len ()

guint8              gst_rtcp_packet_bye_get_reason_len  (GstRTCPPacket *packet);

Get the length of the reason string.

packet :

 a valid BYE GstRTCPPacket

Returns :

 The length of the reason string or 0 when there is no reason string present.

gst_rtcp_packet_bye_get_ssrc_count ()

guint               gst_rtcp_packet_bye_get_ssrc_count  (GstRTCPPacket *packet);

Get the number of SSRC fields in packet.

packet :

 a valid BYE GstRTCPPacket

Returns :

 The number of SSRC fields in packet.

gst_rtcp_packet_bye_set_reason ()

gboolean            gst_rtcp_packet_bye_set_reason      (GstRTCPPacket *packet,
                                                         const gchar *reason);

Set the reason string to reason in packet.

packet :

 a valid BYE GstRTCPPacket

reason :

 a reason string

Returns :

 TRUE if the string could be set. Note: Not implemented.

gst_rtcp_packet_get_count ()

guint8              gst_rtcp_packet_get_count           (GstRTCPPacket *packet);

Get the count field in packet.

packet :

 a valid GstRTCPPacket

Returns :

 The count field in packet or -1 if packet does not point to a valid packet.

gst_rtcp_packet_get_length ()

guint16             gst_rtcp_packet_get_length          (GstRTCPPacket *packet);

Get the length field of packet. This is the length of the packet in 32-bit words minus one.

packet :

 a valid GstRTCPPacket

Returns :

 The length field of packet.

gst_rtcp_packet_get_padding ()

gboolean            gst_rtcp_packet_get_padding         (GstRTCPPacket *packet);

Get the packet padding of the packet pointed to by packet.

packet :

 a valid GstRTCPPacket

Returns :

 If the packet has the padding bit set.

gst_rtcp_packet_get_rb ()

void                gst_rtcp_packet_get_rb              (GstRTCPPacket *packet,
                                                         guint nth,
                                                         guint32 *ssrc,
                                                         guint8 *fractionlost,
                                                         gint32 *packetslost,
                                                         guint32 *exthighestseq,
                                                         guint32 *jitter,
                                                         guint32 *lsr,
                                                         guint32 *dlsr);

Parse the values of the nth report block in packet and store the result in the values.

packet :

 a valid SR or RR GstRTCPPacket

nth :

 the nth report block in packet

ssrc :

 result for data source being reported

fractionlost :

 result for fraction lost since last SR/RR

packetslost :

 result for the cumululative number of packets lost

exthighestseq :

 result for the extended last sequence number received

jitter :

 result for the interarrival jitter

lsr :

 result for the last SR packet from this source

dlsr :

 result for the delay since last SR packet

gst_rtcp_packet_get_rb_count ()

guint               gst_rtcp_packet_get_rb_count        (GstRTCPPacket *packet);

Get the number of report blocks in packet.

packet :

 a valid SR or RR GstRTCPPacket

Returns :

 The number of report blocks in packet.

gst_rtcp_packet_get_type ()

GstRTCPType         gst_rtcp_packet_get_type            (GstRTCPPacket *packet);

Get the packet type of the packet pointed to by packet.

packet :

 a valid GstRTCPPacket

Returns :

 The packet type.

gst_rtcp_packet_move_to_next ()

gboolean            gst_rtcp_packet_move_to_next        (GstRTCPPacket *packet);

Move the packet pointer packet to the next packet in the payload. Use gst_rtcp_buffer_get_first_packet() to initialize packet.

packet :

 a GstRTCPPacket

Returns :

 TRUE if packet is pointing to a valid packet after calling this function.

gst_rtcp_packet_remove ()

void                gst_rtcp_packet_remove              (GstRTCPPacket *packet);

Removes the packet pointed to by packet.

Note: Not implemented.

packet :

 a GstRTCPPacket

gst_rtcp_packet_rr_get_ssrc ()

guint32             gst_rtcp_packet_rr_get_ssrc         (GstRTCPPacket *packet);

Get the ssrc field of the RR packet.

packet :

 a valid RR GstRTCPPacket

Returns :

 the ssrc.

gst_rtcp_packet_rr_set_ssrc ()

void                gst_rtcp_packet_rr_set_ssrc         (GstRTCPPacket *packet,
                                                         guint32 ssrc);

Set the ssrc field of the RR packet.

packet :

 a valid RR GstRTCPPacket

ssrc :

 the SSRC to set

gst_rtcp_packet_sdes_first_item ()

gboolean            gst_rtcp_packet_sdes_first_item     (GstRTCPPacket *packet);

Move to the first SDES item in packet.

packet :

 a valid SDES GstRTCPPacket

Returns :

 TRUE if there was a first item.

gst_rtcp_packet_sdes_get_ssrc ()

guint32             gst_rtcp_packet_sdes_get_ssrc       (GstRTCPPacket *packet);

Get the SSRC of the current SDES item.

packet :

 a valid SDES GstRTCPPacket

Returns :

 the SSRC of the current item.

gst_rtcp_packet_sdes_next_item ()

gboolean            gst_rtcp_packet_sdes_next_item      (GstRTCPPacket *packet);

Move to the next SDES item in packet.

packet :

 a valid SDES GstRTCPPacket

Returns :

 TRUE if there was a next item.

gst_rtcp_packet_set_rb ()

void                gst_rtcp_packet_set_rb              (GstRTCPPacket *packet,
                                                         guint nth,
                                                         guint32 ssrc,
                                                         guint8 fractionlost,
                                                         gint32 packetslost,
                                                         guint32 exthighestseq,
                                                         guint32 jitter,
                                                         guint32 lsr,
                                                         guint32 dlsr);

Set the nth new report block in packet with the given values.

Note: Not implemented.

packet :

 a valid SR or RR GstRTCPPacket

nth :

 the nth report block to set

ssrc :

 data source being reported

fractionlost :

 fraction lost since last SR/RR

packetslost :

 the cumululative number of packets lost

exthighestseq :

 the extended last sequence number received

jitter :

 the interarrival jitter

lsr :

 the last SR packet from this source

dlsr :

 the delay since last SR packet

gst_rtcp_packet_sr_get_sender_info ()

void                gst_rtcp_packet_sr_get_sender_info  (GstRTCPPacket *packet,
                                                         guint32 *ssrc,
                                                         guint64 *ntptime,
                                                         guint32 *rtptime,
                                                         guint32 *packet_count,
                                                         guint32 *octet_count);

Parse the SR sender info and store the values.

packet :

 a valid SR GstRTCPPacket

ssrc :

 result SSRC

ntptime :

 result NTP time

rtptime :

 result RTP time

packet_count :

 result packet count

octet_count :

 result octect count

gst_rtcp_packet_sr_set_sender_info ()

void                gst_rtcp_packet_sr_set_sender_info  (GstRTCPPacket *packet,
                                                         guint32 ssrc,
                                                         guint64 ntptime,
                                                         guint32 rtptime,
                                                         guint32 packet_count,
                                                         guint32 octet_count);

Set the given values in the SR packet packet.

packet :

 a valid SR GstRTCPPacket

ssrc :

 the SSRC

ntptime :

 the NTP time

rtptime :

 the RTP time

packet_count :

 the packet count

octet_count :

 the octect count

See Also

gstbasertppayload, gstbasertpdepayload