SDP Parsing and Data Structure

SDP data structure representation and parsing. More...

Data Structures
struct	pjmedia_sdp_attr
struct	pjmedia_sdp_rtpmap
struct	pjmedia_sdp_fmtp
struct	pjmedia_sdp_rtcp_attr
struct	pjmedia_sdp_ssrc_attr
struct	pjmedia_sdp_conn
struct	pjmedia_sdp_bandw
struct	pjmedia_sdp_media
struct	pjmedia_sdp_session

Macros
#define	PJMEDIA_MAX_SDP_FMT   32
#define	PJMEDIA_MAX_SDP_BANDW   4
#define	PJMEDIA_MAX_SDP_ATTR   (PJMEDIA_MAX_SDP_FMT*2 + 4)
#define	PJMEDIA_MAX_SDP_MEDIA   16

Functions
pjmedia_sdp_attr *	pjmedia_sdp_attr_create (pj_pool_t *pool, const char *name, const pj_str_t *value)
pjmedia_sdp_attr *	pjmedia_sdp_attr_clone (pj_pool_t *pool, const pjmedia_sdp_attr *attr)
pjmedia_sdp_attr *	pjmedia_sdp_attr_find (unsigned count, pjmedia_sdp_attr *const attr_array[], const pj_str_t *name, const pj_str_t *fmt)
pjmedia_sdp_attr *	pjmedia_sdp_attr_find2 (unsigned count, pjmedia_sdp_attr *const attr_array[], const char *name, const pj_str_t *fmt)
pj_status_t	pjmedia_sdp_attr_add (unsigned *count, pjmedia_sdp_attr *attr_array[], pjmedia_sdp_attr *attr)
unsigned	pjmedia_sdp_attr_remove_all (unsigned *count, pjmedia_sdp_attr *attr_array[], const char *name)
pj_status_t	pjmedia_sdp_attr_remove (unsigned *count, pjmedia_sdp_attr *attr_array[], pjmedia_sdp_attr *attr)
pj_status_t	pjmedia_sdp_attr_to_rtpmap (pj_pool_t *pool, const pjmedia_sdp_attr *attr, pjmedia_sdp_rtpmap **p_rtpmap)
pj_status_t	pjmedia_sdp_attr_get_rtpmap (const pjmedia_sdp_attr *attr, pjmedia_sdp_rtpmap *rtpmap)
pj_status_t	pjmedia_sdp_rtpmap_to_attr (pj_pool_t *pool, const pjmedia_sdp_rtpmap *rtpmap, pjmedia_sdp_attr **p_attr)
pj_status_t	pjmedia_sdp_attr_get_fmtp (const pjmedia_sdp_attr *attr, pjmedia_sdp_fmtp *fmtp)
pj_status_t	pjmedia_sdp_attr_get_rtcp (const pjmedia_sdp_attr *attr, pjmedia_sdp_rtcp_attr *rtcp)
pjmedia_sdp_attr *	pjmedia_sdp_attr_create_rtcp (pj_pool_t *pool, const pj_sockaddr *a)
pj_status_t	pjmedia_sdp_attr_get_ssrc (const pjmedia_sdp_attr *attr, pjmedia_sdp_ssrc_attr *rtcp)
pjmedia_sdp_attr *	pjmedia_sdp_attr_create_ssrc (pj_pool_t *pool, pj_uint32_t ssrc, const pj_str_t *cname)
pjmedia_sdp_conn *	pjmedia_sdp_conn_clone (pj_pool_t *pool, const pjmedia_sdp_conn *rhs)
pj_status_t	pjmedia_sdp_conn_cmp (const pjmedia_sdp_conn *conn1, const pjmedia_sdp_conn *conn2, unsigned option)
pjmedia_sdp_bandw *	pjmedia_sdp_bandw_clone (pj_pool_t *pool, const pjmedia_sdp_bandw *rhs)
int	pjmedia_sdp_media_print (const pjmedia_sdp_media *media, char *buf, pj_size_t size)
pjmedia_sdp_media *	pjmedia_sdp_media_clone (pj_pool_t *pool, const pjmedia_sdp_media *rhs)
pjmedia_sdp_attr *	pjmedia_sdp_media_find_attr (const pjmedia_sdp_media *m, const pj_str_t *name, const pj_str_t *fmt)
pjmedia_sdp_attr *	pjmedia_sdp_media_find_attr2 (const pjmedia_sdp_media *m, const char *name, const pj_str_t *fmt)
pj_status_t	pjmedia_sdp_media_add_attr (pjmedia_sdp_media *m, pjmedia_sdp_attr *attr)
unsigned	pjmedia_sdp_media_remove_all_attr (pjmedia_sdp_media *m, const char *name)
pj_status_t	pjmedia_sdp_media_remove_attr (pjmedia_sdp_media *m, pjmedia_sdp_attr *attr)
pj_status_t	pjmedia_sdp_media_cmp (const pjmedia_sdp_media *sd1, const pjmedia_sdp_media *sd2, unsigned option)
pj_status_t	pjmedia_sdp_transport_cmp (const pj_str_t *t1, const pj_str_t *t2)
pj_uint32_t	pjmedia_sdp_transport_get_proto (const pj_str_t *tp)
pj_status_t	pjmedia_sdp_media_deactivate (pj_pool_t *pool, pjmedia_sdp_media *m)
pjmedia_sdp_media *	pjmedia_sdp_media_clone_deactivate (pj_pool_t *pool, const pjmedia_sdp_media *rhs)
pj_status_t	pjmedia_sdp_parse (pj_pool_t *pool, char *buf, pj_size_t len, pjmedia_sdp_session **p_sdp)
int	pjmedia_sdp_print (const pjmedia_sdp_session *sdp, char *buf, pj_size_t size)
pj_status_t	pjmedia_sdp_validate (const pjmedia_sdp_session *sdp)
pj_status_t	pjmedia_sdp_validate2 (const pjmedia_sdp_session *sdp, pj_bool_t strict)
pjmedia_sdp_session *	pjmedia_sdp_session_clone (pj_pool_t *pool, const pjmedia_sdp_session *sdp)
pj_status_t	pjmedia_sdp_session_cmp (const pjmedia_sdp_session *sd1, const pjmedia_sdp_session *sd2, unsigned option)
pj_status_t	pjmedia_sdp_session_add_attr (pjmedia_sdp_session *s, pjmedia_sdp_attr *attr)

Detailed Description

The basic SDP session descriptor and elements are described in header file <pjmedia/sdp.h>. This file contains declaration for SDP session descriptor and SDP media descriptor, along with their attributes. This file also declares functions to parse SDP message.

Macro Definition Documentation

PJMEDIA_MAX_SDP_FMT

#define PJMEDIA_MAX_SDP_FMT   32

The PJMEDIA_MAX_SDP_FMT macro defines maximum format in a media line.

PJMEDIA_MAX_SDP_BANDW

#define PJMEDIA_MAX_SDP_BANDW   4

The PJMEDIA_MAX_SDP_BANDW macro defines maximum bandwidth information lines in a media line.

PJMEDIA_MAX_SDP_ATTR

#define PJMEDIA_MAX_SDP_ATTR   (PJMEDIA_MAX_SDP_FMT*2 + 4)

The PJMEDIA_MAX_SDP_ATTR macro defines maximum SDP attributes in media and session descriptor.

PJMEDIA_MAX_SDP_MEDIA

#define PJMEDIA_MAX_SDP_MEDIA   16

The PJMEDIA_MAX_SDP_MEDIA macro defines maximum SDP media lines in a SDP session descriptor.

Function Documentation

pjmedia_sdp_attr_create()

pjmedia_sdp_attr * pjmedia_sdp_attr_create	(	pj_pool_t *	pool,
		const char *	name,
		const pj_str_t *	value
	)

Create SDP attribute.

Parameters

pool	Pool to create the attribute.
name	Attribute name.
value	Optional attribute value.

Returns

The new SDP attribute.

pjmedia_sdp_attr_clone()

pjmedia_sdp_attr * pjmedia_sdp_attr_clone	(	pj_pool_t *	pool,
		const pjmedia_sdp_attr *	attr
	)

Clone attribute

Parameters

pool	Pool to be used.
attr	The attribute to clone.

Returns

New attribute as cloned from the attribute.

pjmedia_sdp_attr_find()

pjmedia_sdp_attr * pjmedia_sdp_attr_find	(	unsigned	count,
		pjmedia_sdp_attr *const	attr_array[],
		const pj_str_t *	name,
		const pj_str_t *	fmt
	)

Find the first attribute with the specified type.

Parameters

count	Number of attributes in the array.
attr_array	Array of attributes.
name	Attribute name to find.
fmt	Optional string to indicate which payload format to find for rtpmap and fmt attributes. For other types of attributes, the value should be NULL.

Returns

The specified attribute, or NULL if it can't be found.

See also

pjmedia_sdp_attr_find2, pjmedia_sdp_media_find_attr, pjmedia_sdp_media_find_attr2

pjmedia_sdp_attr_find2()

pjmedia_sdp_attr * pjmedia_sdp_attr_find2	(	unsigned	count,
		pjmedia_sdp_attr *const	attr_array[],
		const char *	name,
		const pj_str_t *	fmt
	)

Find the first attribute with the specified type.

Parameters

count	Number of attributes in the array.
attr_array	Array of attributes.
name	Attribute name to find.
fmt	Optional string to indicate which payload format to find for rtpmap and fmt attributes. For other types of attributes, the value should be NULL.

Returns

The specified attribute, or NULL if it can't be found.

See also

pjmedia_sdp_attr_find, pjmedia_sdp_media_find_attr, pjmedia_sdp_media_find_attr2

pjmedia_sdp_attr_add()

pj_status_t pjmedia_sdp_attr_add	(	unsigned *	count,
		pjmedia_sdp_attr *	attr_array[],
		pjmedia_sdp_attr *	attr
	)

Add a new attribute to array of attributes.

Parameters

count	Number of attributes in the array.
attr_array	Array of attributes.
attr	The attribute to add.

Returns

PJ_SUCCESS or the error code.

See also

pjmedia_sdp_media_add_attr

pjmedia_sdp_attr_remove_all()

unsigned pjmedia_sdp_attr_remove_all	(	unsigned *	count,
		pjmedia_sdp_attr *	attr_array[],
		const char *	name
	)

Remove all attributes with the specified name in array of attributes.

Parameters

count	Number of attributes in the array.
attr_array	Array of attributes.
name	Attribute name to find.

Returns

Number of attributes removed.

See also

pjmedia_sdp_media_remove_all_attr

pjmedia_sdp_attr_remove()

pj_status_t pjmedia_sdp_attr_remove	(	unsigned *	count,
		pjmedia_sdp_attr *	attr_array[],
		pjmedia_sdp_attr *	attr
	)

Remove the specified attribute from the attribute array.

Parameters

count	Number of attributes in the array.
attr_array	Array of attributes.
attr	The attribute instance to remove.

Returns

PJ_SUCCESS when attribute has been removed, or PJ_ENOTFOUND when the attribute can not be found.

See also

pjmedia_sdp_media_remove_attr

pjmedia_sdp_attr_to_rtpmap()

pj_status_t pjmedia_sdp_attr_to_rtpmap	(	pj_pool_t *	pool,
		const pjmedia_sdp_attr *	attr,
		pjmedia_sdp_rtpmap **	p_rtpmap
	)

Convert generic attribute to SDP rtpmap. This function allocates a new attribute and call pjmedia_sdp_attr_get_rtpmap().

Parameters

pool	Pool used to create the rtpmap attribute.
attr	Generic attribute to be converted to rtpmap, which name must be "rtpmap".
p_rtpmap	Pointer to receive SDP rtpmap attribute.

Returns

PJ_SUCCESS if the attribute can be successfully converted to rtpmap type.

See also

pjmedia_sdp_attr_get_rtpmap

pjmedia_sdp_attr_get_rtpmap()

pj_status_t pjmedia_sdp_attr_get_rtpmap	(	const pjmedia_sdp_attr *	attr,
		pjmedia_sdp_rtpmap *	rtpmap
	)

Get the rtpmap representation of the same SDP attribute.

Parameters

attr	Generic attribute to be converted to rtpmap, which name must be "rtpmap". Attribute value must be terminated with a NULL, CR, or LF character.
rtpmap	SDP rtpmap attribute to be initialized.

Returns

PJ_SUCCESS if the attribute can be successfully converted to rtpmap attribute.

See also

pjmedia_sdp_attr_to_rtpmap

pjmedia_sdp_rtpmap_to_attr()

pj_status_t pjmedia_sdp_rtpmap_to_attr	(	pj_pool_t *	pool,
		const pjmedia_sdp_rtpmap *	rtpmap,
		pjmedia_sdp_attr **	p_attr
	)

Convert rtpmap attribute to generic attribute.

Parameters

pool	Pool to be used.
rtpmap	The rtpmap attribute.
p_attr	Pointer to receive the generic SDP attribute.

Returns

PJ_SUCCESS on success.

pjmedia_sdp_attr_get_fmtp()

pj_status_t pjmedia_sdp_attr_get_fmtp	(	const pjmedia_sdp_attr *	attr,
		pjmedia_sdp_fmtp *	fmtp
	)

Get the fmtp representation of the same SDP attribute.

Parameters

attr	Generic attribute to be converted to fmtp, which name must be "fmtp".
fmtp	SDP fmtp attribute to be initialized.

Returns

PJ_SUCCESS on success.

pjmedia_sdp_attr_get_rtcp()

pj_status_t pjmedia_sdp_attr_get_rtcp	(	const pjmedia_sdp_attr *	attr,
		pjmedia_sdp_rtcp_attr *	rtcp
	)

Parse a generic SDP attribute to get SDP rtcp attribute values.

Parameters

attr	Generic attribute to be converted to rtcp, which name must be "rtcp".
rtcp	SDP rtcp attribute to be initialized.

Returns

PJ_SUCCESS on success.

pjmedia_sdp_attr_create_rtcp()

pjmedia_sdp_attr * pjmedia_sdp_attr_create_rtcp	(	pj_pool_t *	pool,
		const pj_sockaddr *	a
	)

Create a=rtcp attribute.

Parameters

pool	Pool to create the attribute.
a	Socket address.

Returns

SDP RTCP attribute.

pjmedia_sdp_attr_get_ssrc()

pj_status_t pjmedia_sdp_attr_get_ssrc	(	const pjmedia_sdp_attr *	attr,
		pjmedia_sdp_ssrc_attr *	rtcp
	)

Parse a generic SDP attribute to get SDP ssrc attribute values.

Parameters

attr	Generic attribute to be converted to ssrc, which name must be "ssrc".
rtcp	SDP ssrc attribute to be initialized.

Returns

PJ_SUCCESS on success.

pjmedia_sdp_attr_create_ssrc()

pjmedia_sdp_attr * pjmedia_sdp_attr_create_ssrc	(	pj_pool_t *	pool,
		pj_uint32_t	ssrc,
		const pj_str_t *	cname
	)

Create a=ssrc attribute.

Parameters

pool	Pool to create the attribute.
ssrc	SSRC identifier.
cname	CNAME.

Returns

SDP SSRC attribute.

pjmedia_sdp_conn_clone()

pjmedia_sdp_conn * pjmedia_sdp_conn_clone	(	pj_pool_t *	pool,
		const pjmedia_sdp_conn *	rhs
	)

Clone connection info.

Parameters

pool	Pool to allocate memory for the new connection info.
rhs	The connection into to clone.

Returns

The new connection info.

pjmedia_sdp_conn_cmp()

pj_status_t pjmedia_sdp_conn_cmp	(	const pjmedia_sdp_conn *	conn1,
		const pjmedia_sdp_conn *	conn2,
		unsigned	option
	)

Compare connection info.

Parameters

conn1	The first connection info to compare.
conn2	The second connection info to compare.
option	Comparison option, which should be zero for now.

Returns

PJ_SUCCESS when both connection info are equal, otherwise returns PJMEDIA_SDP_ECONNNOTEQUAL.

pjmedia_sdp_bandw_clone()

pjmedia_sdp_bandw * pjmedia_sdp_bandw_clone	(	pj_pool_t *	pool,
		const pjmedia_sdp_bandw *	rhs
	)

Clone bandwidth info.

Parameters

pool	Pool to allocate memory for the new bandwidth info.
rhs	The bandwidth into to clone.

Returns

The new bandwidth info.

pjmedia_sdp_media_print()

int pjmedia_sdp_media_print	(	const pjmedia_sdp_media *	media,
		char *	buf,
		pj_size_t	size
	)

Print media description to a buffer.

Parameters

media	The media description.
buf	The buffer.
size	The buffer length.

Returns

the length printed, or -1 if the buffer is too short.

pjmedia_sdp_media_clone()

pjmedia_sdp_media * pjmedia_sdp_media_clone	(	pj_pool_t *	pool,
		const pjmedia_sdp_media *	rhs
	)

Clone SDP media description.

Parameters

pool	Pool to allocate memory for the new media description.
rhs	The media descriptin to clone.

Returns

New media description.

pjmedia_sdp_media_find_attr()

pjmedia_sdp_attr * pjmedia_sdp_media_find_attr	(	const pjmedia_sdp_media *	m,
		const pj_str_t *	name,
		const pj_str_t *	fmt
	)

Find the first occurence of the specified attribute name in the media descriptor. Optionally the format may be specified.

Parameters

m	The SDP media description.
name	Attribute name to find.
fmt	Optional payload type to match in the attribute list, when the attribute is rtpmap or fmtp. For other types of SDP attributes, this value should be NULL.

Returns

The first instance of the specified attribute or NULL.

pjmedia_sdp_media_find_attr2()

pjmedia_sdp_attr * pjmedia_sdp_media_find_attr2	(	const pjmedia_sdp_media *	m,
		const char *	name,
		const pj_str_t *	fmt
	)

Find the first occurence of the specified attribute name in the SDP media descriptor. Optionally the format may be specified.

Parameters

m	The SDP media description.
name	Attribute name to find.
fmt	Optional payload type to match in the attribute list, when the attribute is rtpmap or fmtp. For other types of SDP attributes, this value should be NULL.

Returns

The first instance of the specified attribute or NULL.

pjmedia_sdp_media_add_attr()

pj_status_t pjmedia_sdp_media_add_attr	(	pjmedia_sdp_media *	m,
		pjmedia_sdp_attr *	attr
	)

Add new attribute to the media descriptor.

Parameters

m	The SDP media description.
attr	Attribute to add.

Returns

PJ_SUCCESS or the appropriate error code.

pjmedia_sdp_media_remove_all_attr()

unsigned pjmedia_sdp_media_remove_all_attr	(	pjmedia_sdp_media *	m,
		const char *	name
	)

Remove all attributes with the specified name from the SDP media descriptor.

Parameters

m	The SDP media description.
name	Attribute name to remove.

Returns

The number of attributes removed.

pjmedia_sdp_media_remove_attr()

pj_status_t pjmedia_sdp_media_remove_attr	(	pjmedia_sdp_media *	m,
		pjmedia_sdp_attr *	attr
	)

Remove the occurence of the specified attribute from the SDP media descriptor.

Parameters

m	The SDP media descriptor.
attr	The attribute to find and remove.

Returns

PJ_SUCCESS if the attribute can be found and has been removed from the array.

pjmedia_sdp_media_cmp()

pj_status_t pjmedia_sdp_media_cmp	(	const pjmedia_sdp_media *	sd1,
		const pjmedia_sdp_media *	sd2,
		unsigned	option
	)

Compare two SDP media for equality.

Parameters

sd1	The first SDP media to compare.
sd2	The second SDP media to compare.
option	Comparison option, which should be zero for now.

Returns

PJ_SUCCESS when both SDP medias are equal, or the appropriate status code describing which part of the descriptors that are not equal.

pjmedia_sdp_transport_cmp()

pj_status_t pjmedia_sdp_transport_cmp	(	const pj_str_t *	t1,
		const pj_str_t *	t2
	)

Compare two media transports for compatibility.

Parameters

t1	The first media transport to compare.
t2	The second media transport to compare.

Returns

PJ_SUCCESS when both media transports are compatible, otherwise returns PJMEDIA_SDP_ETPORTNOTEQUAL.

pjmedia_sdp_transport_get_proto()

pj_uint32_t pjmedia_sdp_transport_get_proto

(

const pj_str_t *

tp

)

Get media transport protocol info, i.e: base transport and profiles, from the provided SDP media transport name string.

Parameters

tp	The SDP media transport name.

Returns

Media transport info, combination of transport protocol and profile bit flag defined in pjmedia_tp_proto.

pjmedia_sdp_media_deactivate()

pj_status_t pjmedia_sdp_media_deactivate	(	pj_pool_t *	pool,
		pjmedia_sdp_media *	m
	)

Deactivate SDP media.

Parameters

pool	Memory pool to allocate memory from.
m	The SDP media to deactivate.

Returns

PJ_SUCCESS when SDP media successfully deactivated, otherwise appropriate status code returned.

pjmedia_sdp_media_clone_deactivate()

pjmedia_sdp_media * pjmedia_sdp_media_clone_deactivate	(	pj_pool_t *	pool,
		const pjmedia_sdp_media *	rhs
	)

Clone SDP media description and deactivate the new SDP media.

Parameters

pool	Memory pool to allocate memory for the clone.
rhs	The SDP media to clone.

Returns

New media descrption with deactivated indication.

pjmedia_sdp_parse()

pj_status_t pjmedia_sdp_parse	(	pj_pool_t *	pool,
		char *	buf,
		pj_size_t	len,
		pjmedia_sdp_session **	p_sdp
	)

Parse SDP message.

Note that the input message buffer MUST be NULL terminated and have length at least len+1 (len MUST NOT include the NULL terminator).

Parameters

pool	The pool to allocate SDP session description.
buf	The message buffer, MUST be NULL terminated.
len	The length of the message, excluding NULL terminator.
p_sdp	Pointer to receive the SDP session descriptor.

Returns

PJ_SUCCESS if message was successfully parsed into SDP session descriptor.

pjmedia_sdp_print()

int pjmedia_sdp_print	(	const pjmedia_sdp_session *	sdp,
		char *	buf,
		pj_size_t	size
	)

Print SDP description to a buffer.

Parameters

sdp	The SDP session description.
buf	The buffer.
size	The buffer length.

Returns

the length printed, or -1 if the buffer is too short.

pjmedia_sdp_validate()

pj_status_t pjmedia_sdp_validate

(

const pjmedia_sdp_session *

sdp

)

Perform semantic validation for the specified SDP session descriptor. This function perform validation beyond just syntactic verification, such as to verify the value of network type and address type, check the connection line, and verify that rtpmap attribute is present when dynamic payload type is used.

Parameters

sdp	The SDP session descriptor to validate.

Returns

PJ_SUCCESS on success.

pjmedia_sdp_validate2()

pj_status_t pjmedia_sdp_validate2	(	const pjmedia_sdp_session *	sdp,
		pj_bool_t	strict
	)

Perform semantic validation for the specified SDP session descriptor. This function perform validation beyond just syntactic verification, such as to verify the value of network type and address type, check the connection line, and verify that rtpmap attribute is present when dynamic payload type is used.

Parameters

sdp	The SDP session descriptor to validate.
strict	Flag whether the check should be strict, i.e: allow media without connection line when port is zero.

Returns

PJ_SUCCESS on success.

pjmedia_sdp_session_clone()

pjmedia_sdp_session * pjmedia_sdp_session_clone	(	pj_pool_t *	pool,
		const pjmedia_sdp_session *	sdp
	)

Clone SDP session descriptor.

Parameters

pool	The pool used to clone the session.
sdp	The SDP session to clone.

Returns

New SDP session.

pjmedia_sdp_session_cmp()

pj_status_t pjmedia_sdp_session_cmp	(	const pjmedia_sdp_session *	sd1,
		const pjmedia_sdp_session *	sd2,
		unsigned	option
	)

Compare two SDP session for equality.

Parameters

sd1	The first SDP session to compare.
sd2	The second SDP session to compare.
option	Must be zero for now.

Returns

PJ_SUCCESS when both SDPs are equal, or otherwise the status code indicates which part of the session descriptors are not equal.

pjmedia_sdp_session_add_attr()

pj_status_t pjmedia_sdp_session_add_attr	(	pjmedia_sdp_session *	s,
		pjmedia_sdp_attr *	attr
	)

Add new attribute to the session descriptor.

Parameters

s	The SDP session description.
attr	Attribute to add.

Returns

PJ_SUCCESS or the appropriate error code.