Chapter 3 Session Description Protocol API
The Session Description Protocol (SDP) describes multimedia sessions. The SDP API discussed in this chapter contains function calls you can use to add SDP functionality to your applications.
Session Description API Overview
The function calls that make up the SDP API are provided by the shared object libcommputil.so.1. The functions in this shared object parse the SDP description and check the description's syntax.
The sdp.h header file defines the sdp_session_t structure, which contains the following members:
typedef struct sdp_session {
int sdp_session_version; /* SDP session verstion */
int s_version; /* SDP version field */
sdp_origin_t *s_origin; /* SDP origin field */
char *s_name; /* SDP name field */
char *s_info; /* SDP info field */
char *s_uri; /* SDP uri field */
sdp_list_t *s_email; /* SDP email field */
sdp_list_t *s_phone; /* SDP phone field */
sdp_conn_t *s_conn; /* SDP connection field */
sdp_bandwidth_t *s_bw; /* SDP bandwidth field */
sdp_time_t *s_time; /* SDP time field */
sdp_zone_t *s_zone; /* SDP zone field */
sdp_key_t *s_key; /* SDP key field */
sdp_attr_t *s_attr; /* SDP attribute field */
sdp_media_t *s_media; /* SDP media field */
} sdp_session_t;
The sdp_session_version member tracks the version of the structure. The initial value of the sdp_session_version member is SDP_SESSION_VERSION_1.
The sdp_origin_t structure contains the following members:
typedef struct sdp_origin {
char *o_username; /* username of the originating host */
uint64_t o_id; /* session id */
uint64_t o_version; /* version number of this session */
/* description */
char *o_nettype; /* type of network */
char *o_addrtype; /* type of the address */
char *o_address; /* address of the machine from which */
/* session was created */
} sdp_origin_t;
The sdp_conn_t structure contains the following members:
typedef struct sdp_conn {
char *c_nettype; /* type of network */
char *c_addrtype; /* type of the address */
char *c_address; /* unicast-address or multicast */
/* address */
int c_addrcount; /* number of addresses (case of */
/* multicast address with layered */
/* encodings */
struct sdp_conn *c_next; /* pointer to next connection */
/* structure; there could be several */
/* connection fields in SDP description */
uint8_t c_ttl; /* TTL value for IPV4 multicast address */
} sdp_conn_t;
The sdp_bandwidth_t structure contains the following members:
typedef struct sdp_bandwidth {
char *b_type; /* info needed to interpret b_value */
uint64_t b_value; /* bandwidth value */
struct sdp_bandwidth *b_next; /* pointer to next bandwidth structure*/
/* (there could be several bandwidth */
/* fields in SDP description */
} sdp_bandwidth_t;
The sdp_list_t structure is a linked list of void pointers. This structure holds SDP fields. In the case of SDP structure fields such as email and phone, the void pointers point to character buffers. Use this structure to hold information in cases where the number of elements is not predefined, as in the case of repeated offset fields, where the void pointer holds integer values.
The sdp_list_t structure contains the following members:
typedef struct sdp_list {
void *value; /* string values in case of email, phone and */
/* format (in media field) or integer values */
/* in case of offset (in repeat field) */
struct sdp_list *next; /* pointer to the next node in the list */
} sdp_list_t;
The sdp_repeat_t structure will always be part of the time structure sdp_time_t. The repeat field does not appear alone in SDP descriptions and is always associated with the time field.
The sdp_repeat_t structure contains the following members:
typedef struct sdp_repeat {
uint64_t r_interval; /* repeat interval, e.g. 86400 seconds */
/* (1 day) */
uint64_t r_duration; /* duration of session, e.g. 3600 */
/* seconds (1 hour) */
sdp_list_t *r_offset; /* linked list of offset values; each */
/* represents offset from start-time */
/* in the SDP time field */
struct sdp_repeat *r_next; /* pointer to next repeat structure; */
/* there could be several repeat */
/* fields in the SDP description */
The sdp_time_t structure contains the following members:
typedef struct sdp_time {
uint64_t t_start; /* start-time for a session */
uint64_t t_stop; /* end-time for a session */
sdp_repeat_t *t_repeat; /* points to the SDP repeat field */
struct sdp_time *t_next; /* pointer to next time field; there */
/* could there could be several time */
/* fields in SDP description */
} sdp_time_t;
The sdp_zone_t structure contains the following members:
typedef struct sdp_zone {
uint64_t z_time; /* base time */
char *z_offset; /* offset added to z_time to determine */
/* session time; mainly used for daylight */
/* saving time conversions */
struct sdp_zone *z_next; /* pointer to next zone field; there */
/* could be several <adjustment-time> */
/* <offset> pairs within a zone field */
} sdp_zone_t;
The sdp_key_t structure contains the following members:
typedef struct sdp_key {
char *k_method; /* key type */
char *k_enckey; /* encryption key */
} sdp_key_t;
The sdp_attr_t structure contains the following members:
typedef struct sdp_attr {
char *a_name; /* name of the attribute */
char *a_value; /* value of the attribute */
struct sdp_attr *a_next; /* pointer to the next attribute */
/* structure; there could be several */
/* attribute fields within SDP description */
} sdp_attr_t;
The sdp_media_t structure contains the following members:
typedef struct sdp_media {
char *m_name; /* name of the media such as "audio", */
/* "video", "message" */
uint_t m_port; /* transport layer port information */
int m_portcount; /* number of ports in case of */
/* hierarchically encoded streams */
char *m_proto; /* transport protocol */
sdp_list_t *m_format; /* media format description */
char *m_info; /* media info field */
sdp_conn_t *m_conn; /* media connection field */
sdp_bandwidth_t *m_bw; /* media bandwidth field */
sdp_key_t *m_key; /* media key field */
sdp_attr_t *m_attr; /* media attribute field */
struct sdp_media *m_next; /* pointer to next media structure; */
/* there could be several media */
/* sections in SDP description */
sdp_session_t *m_session; /* pointer to the session structure */
} sdp_media_t;
SDP Library Functions
The API library functions support the following operations:
-
Creating the SDP session structure
-
Searching within the SDP session structure
-
Shutting down an SDP session structure
-
Utility functions
Creating the SDP Session Structure
The first step in creating a new SDP session structure is allocating memory for the new structure by calling the sdp_new_session() function. This function returns a pointer to the new session structure. The other functions in this section use that pointer to construct the new session structure. Once you are done constructing the new session structure, convert it to a string representation with the sdp_session_to_str() function.
Creating a New SDP Session Structure
sdp_session_t *sdp_new_session();The sdp_new_session() function allocates memory for a new SDP session structure that is specified by the session parameter and assigns a version number to that new structure. You can free the memory that is allocated to the session structure by calling the sdp_free_session() function.
Return Values: The sdp_new_session() function returns the newly allocated SDP session structure when the function completes successfully. The function returns NULL in the case of failure.
Adding an Origin Field to the SDP Session Structure
int sdp_add_origin(sdp_session_t *session, const char *name, uint64_t id, uint64_t ver, const char *nettype, const char *addrtype, const char *address);The sdp_add_origin() function adds the ORIGIN (o=) SDP field to the session structure that is specified by the value of the session parameter (sdp_session_t) using the name, id, ver, nettype, addrtype, and address parameters.
Return Values: The sdp_add_origin() function returns 0 when the function completes successfully. When mandatory parameters are not present, the function returns EINVAL. When memory allocation fails, the function returns ENOMEM. The value of errno does not change in the event of an error.
Adding a Name Field to the SDP Session Structure
int sdp_add_name(sdp_session_t *session, const char *name);The sdp_add_name() function adds the NAME (s=) SDP field to the session structure that is specified by the value of the session parameter (sdp_session_t) using the name parameter.
Return Values: The sdp_add_name() function returns 0 when the function completes successfully. When mandatory parameters are not present, the function returns EINVAL. When memory allocation fails, the function returns ENOMEM. The value of errno does not change in the event of an error.
Adding an Information Field to the SDP Session Structure
int sdp_add_information(char **information, const char *value);The sdp_add_information() function adds the INFO (i=) SDP field to the session structure (sdp_session_t) or the media structure (sdp_media_t) using the value parameter. This field can go into the media or the session section of an SDP description. You must pass either &session->s_info or &media->m_info as the first argument to specify the section.
Return Values: The sdp_add_information() function returns 0 when the function completes successfully. When mandatory parameters are not present, the function returns EINVAL. When memory allocation fails, the function returns ENOMEM. The value of errno does not change in the event of an error.
Adding a URI Field to the SDP Session Structure
int sdp_add_uri(sdp_session_t *session, const char *uri);The sdp_add_uri() function adds the URI (u=) SDP field to the session structure that is specified by the value of the session parameter (sdp_session_t) using the uri parameter.
Return Values: The sdp_add_uri() function returns 0 when the function completes successfully. When mandatory parameters are not present, the function returns EINVAL. When memory allocation fails, the function returns ENOMEM. The value of errno does not change in the event of an error.
Adding an Email Field to the SDP Session Structure
int sdp_add_email(sdp_session_t *session, const char *email);The sdp_add_email() function adds the EMAIL (e=) SDP field to the session structure that is specified by the value of the session parameter (sdp_session_t) using the email parameter.
Return Values: The sdp_add_email() function returns 0 when the function completes successfully. When mandatory parameters are not present, the function returns EINVAL. When memory allocation fails, the function returns ENOMEM. The value of errno does not change in the event of an error.
Adding a Telephone Field to the SDP Session Structure
int sdp_add_phone(sdp_session_t *session, const char *email);The sdp_add_phone() function adds the PHONE (p=) SDP field to the session structure that is specified by the value of the session parameter (sdp_session_t) using the phone parameter.
Return Values: The sdp_add_phone() function returns 0 when the function completes successfully. When mandatory parameters are not present, the function returns EINVAL. When memory allocation fails, the function returns ENOMEM. The value of errno does not change in the event of an error.
Adding a Connection Field to the SDP Session Structure
int sdp_add_connection(sdp_conn_t **conn, const char *nettype, const char *addrtype, const char *address, uint8_t ttl, int addrcount);The sdp_add_connection() function adds the CONNECTION (c=) SDP field to either the session structure (sdp_session_t) or the media structure (sdp_media_t) using the nettype, addrtype, address, ttl, and addrcount parameters. For IPv4 or IPv6 unicast addresses, set the values of the ttl and addrcount parameters to zero. For multicast addresses, set the value of the ttl parameter between zero and 255. A multicast address cannot have an addrcount parameter with a value of zero.
This field can go into the media or the session section of an SDP description. You must pass either &session->s_info or &media->m_info as the first argument to specify the section.
Return Values: The sdp_add_connection() function returns 0 when the function completes successfully. When mandatory parameters are not present, the function returns EINVAL. When memory allocation fails, the function returns ENOMEM. The value of errno does not change in the event of an error.
Adding a Bandwidth Field to the SDP Session Structure
int sdp_add_bandwidth(sdp_bandwidth_t **bw, const char *type, uint64_t value);The sdp_add_bandwidth() function adds the BANDWIDTH (b=) SDP field to either the session structure (sdp_session_t) or the media structure (sdp_media_t) using the type and value parameters.
This field can go into the media or the session section of an SDP description. You must pass either &session->s_info or &media->m_info as the first argument to specify the section.
Return Values: The sdp_add_bandwidth() function returns 0 when the function completes successfully. When mandatory parameters are not present, the function returns EINVAL. When memory allocation fails, the function returns ENOMEM. The value of errno does not change in the event of an error.
Adding a Time Field to the SDP Session Structure
int sdp_add_time(sdp_session_t *session, uint64_t starttime, uint64_t stoptime, sdp_time_t **time);The sdp_add_time() function adds the TIME (t=) SDP field to the session structure using the values of the starttime and stoptime parameters. This function creates a new time structure and returns the pointer to that structure in the time parameter.
Return Values: The sdp_add_time() function returns 0 when the function completes successfully. When mandatory parameters are not present, the function returns EINVAL. When memory allocation fails, the function returns ENOMEM. The value of errno does not change in the event of an error.
Adding a Repeat Field to the SDP Session Structure
int sdp_add_repeat(sdp_time_t *time, uint64_t interval, uint64_t duration, const char *offset);The sdp_add_repeat() function adds the REPEAT (r=) SDP field to the session structure using the values of the interval, duration, and offset parameters. The value of the offset parameter is a string that holds one or more offset values, such as 60 or 60 1d 3h. The value of the time parameter is the pointer to the time structure that the sdp_add_time() function creates.
Return Values: The sdp_add_repeat() function returns 0 when the function completes successfully. When mandatory parameters are not present, the function returns EINVAL. When memory allocation fails, the function returns ENOMEM. The value of errno does not change in the event of an error.
Adding a Zone Field to the SDP Session Structure
int sdp_add_zone(sdp_session_t *session, uint64_t time, const char *offset);The sdp_add_zone() function adds the ZONE (z=) SDP field to the session structure that is specified by the value of the session parameter (sdp_session_t) using the time and offset parameters. You can add multiple time and offset values for a single zone field by calling this function for each time/offset value pair.
Return Values: The sdp_add_zone() function returns 0 when the function completes successfully. When mandatory parameters are not present, the function returns EINVAL. When memory allocation fails, the function returns ENOMEM. The value of errno does not change in the event of an error.
Adding a Key Field to the SDP Session Structure
int sdp_add_key(sdp_key_t **key, const char *method, const char *enckey);The sdp_add_key() function adds the KEY (k=) SDP field to the session structure (sdp_session_t) or the media structure (sdp_media_t) using the method and enckey parameters. This field can go into the media or the session section of an SDP description. You must pass either &session->s_info or &media->m_info as the first argument to specify the section.
Return Values: The sdp_add_key() function returns 0 when the function completes successfully. When mandatory parameters are not present, the function returns EINVAL. When memory allocation fails, the function returns ENOMEM. The value of errno does not change in the event of an error.
Adding an Attribute Field to the SDP Session Structure
int sdp_add_attribute(sdp_attr_t **attr, const char *name, const char *value);The sdp_add_attribute() function adds the ATTRIBUTE (a=) SDP field to the session structure (sdp_session_t) or the media structure (sdp_media_t) using the name and value parameters. This field can go into the media or the session section of an SDP description. You must pass either &session->s_info or &media->m_info as the first argument to specify the section.
Return Values: The sdp_add_attribute() function returns 0 when the function completes successfully. When mandatory parameters are not present, the function returns EINVAL. When memory allocation fails, the function returns ENOMEM. The value of errno does not change in the event of an error.
Adding a Media Field to the SDP Session Structure
int sdp_add_media(sdp_session_t *session, const char *name, uint_t port, int portcount, const char *protocol, const char *format, sdp_media_t **media);The sdp_add_media() function adds the MEDIA (m=) SDP field to the session structure that is specified by the value of the session parameter (sdp_session_t) using the values of the name, port, portcount, protocol, and format parameters. The format parameter is a string that holds one or more values, such as the string 0 32 97.
This function creates a new media structure and returns a pointer to that structure in the media parameter. Functions that add SDP fields to the media structure use this pointer.
Return Values: The sdp_add_media() function returns 0 when the function completes successfully. When mandatory parameters are not present, the function returns EINVAL. When memory allocation fails, the function returns ENOMEM. The value of errno does not change in the event of an error.
Code Sample: Building an SDP Session Structure
This example uses the functions in this section to create a new SDP session structure, add fields to the structure, and convert a finished structure to its string representation. At the end of the example, the program calls the sdp_free_session() function to free the session.
Example 3–1 Building an SDP Session Structure
/* SDP Message we will be building
"v=0\r\n\
o=Alice 2890844526 2890842807 IN IP4 10.47.16.5\r\n\
s=-\r\n\
i=A Seminar on the session description protocol\r\n\
u=http://www.example.com/seminars/sdp.pdf\r\n\
e=alice@example.com (Alice Smith)\r\n\
p=+1 911-345-1160\r\n\
c=IN IP4 10.47.16.5\r\n\
b=CT:1024\r\n\
t=2854678930 2854679000\r\n\
r=604800 3600 0 90000\r\n\
z=2882844526 -1h 2898848070 0h\r\n\
a=recvonly\r\n\
m=audio 49170 RTP/AVP 0\r\n\
i=audio media\r\n\
b=CT:1000\r\n\
k=prompt\r\n\
m=video 51372 RTP/AVP 99 90\r\n\
i=video media\r\n\
a=rtpmap:99 h232-199/90000\r\n\
a=rtpmap:90 h263-1998/90000\r\n"
*/
#include stdio.h>
#include string.h>
#include errno.h>
#include sdp.h>
int main ()
{
sdp_session_t *my_sess;
sdp_media_t *my_media;
sdp_time_t *my_time;
char *b_sdp;
my_sess = sdp_new_session();
if (my_sess == NULL) {
return (ENOMEM);
}
my_sess->version = 0;
if (sdp_add_name(my_sess, "-") != 0)
goto err_ret;
if (sdp_add_origin(my_sess, "Alice", 2890844526ULL, 2890842807ULL,
"IN", "IP4", "10.47.16.5") != 0)
goto err_ret;
if (sdp_add_information(&my_sess->s_info, "A Seminar on the session"
"description protocol") != 0)
goto err_ret;
if (sdp_add_uri (my_sess, "http://www.example.com/seminars/sdp.pdf")
!= 0)
goto err_ret;
if (sdp_add_email(my_sess, "alice@example.com (Alice smith)") != 0)
goto err_ret;
if (sdp_add_phone(my_sess, "+1 911-345-1160") != 0)
goto err_ret;
if (sdp_add_connection(&my_sess->s_conn, "IN", "IP4", "10.47.16.5",
0, 0) != 0)
goto err_ret;
if (sdp_add_bandwidth(&my_sess->s_bw, "CT", 1024) != 0)
goto err_ret;
if (sdp_add_time(my_sess, 2854678930ULL, 2854679000ULL, &my_time)
!= 0)
goto err_ret;
if (sdp_add_repeat(my_time, 604800ULL, 3600ULL, "0 90000") != 0)
goto err_ret;
if (sdp_add_zone(my_sess, 2882844526ULL, "-1h") != 0)
goto err_ret;
if (sdp_add_zone(my_sess, 2898848070ULL, "0h") != 0)
goto err_ret;
if (sdp_add_attribute(&my_sess->s_attr, "sendrecv", NULL) != 0)
goto err_ret;
if (sdp_add_media(my_sess, "audio", 49170, 1, "RTP/AVP",
"0", &my_media) != 0)
goto err_ret;
if (sdp_add_information(&my_media->m_info, "audio media") != 0)
goto err_ret;
if (sdp_add_bandwidth(&my_media->m_bw, "CT", 1000) != 0)
goto err_ret;
if (sdp_add_key(&my_media->m_key, "prompt", NULL) != 0)
goto err_ret;
if (sdp_add_media(my_sess, "video", 51732, 1, "RTP/AVP",
"99 90", &my_media) != 0)
goto err_ret;
if (sdp_add_information(&my_media->m_info, "video media") != 0)
goto err_ret;
if (sdp_add_attribute(&my_media->m_attr, "rtpmap",
"99 h232-199/90000") != 0)
goto err_ret;
if (sdp_add_attribute(&my_media->m_attr, "rtpmap",
"90 h263-1998/90000") != 0)
goto err_ret;
b_sdp = sdp_session_to_str(my_sess, &error);
/*
* b_sdp is the string representation of my_sess structure
*/
free(b_sdp);
sdp_free_session(my_sess);
return (0);
err_ret:
free(b_sdp);
sdp_free_session(my_sess);
return (1);
}
Searching the SDP Session Structure
The functions in this section search the SDP session structure for specific values and return pointers to those values.
Finding an Attribute in an SDP Session Structure
sdp_attr_t *sdp_find_attribute(sdp_attr_t *attr, const char *name);The sdp_find_attribute() function searches the attribute list that is specified by the attr parameter for the attribute name that is specified by the name parameter.
Return Values: The sdp_find_attribute() function returns a pointer to the attribute (sdp_attr_t *) that is specified by the name parameter when the function completes successfully. In all other cases, the sdp_find_attribute() function returns a value of NULL.
Example 3–2 Using the sdp_find_attribute() Function
The incomplete SDP description in this example has an audio section.
m=audio 49170 RTP/AVP 0 8 a=rtpmap:0 PCMU/8000 a=rtpmap:8 PCMA/8000 a=sendonly a=ptime:10000 a=maxptime:20000 /* * Assuming that above description is parsed using sdp_parse and that * the parsed structure is in "session" sdp_session_t structure. */ sdp_attr_t *ptime; sdp_attr_t *max_ptime; sdp_media_t *media = session->s_media; if ((ptime = sdp_find_attribute(media->m_attr, "ptime")) == NULL) /* ptime attribute not present */ else if((max_ptime = sdp_find_attribute(media->m_attr, "maxptime")) == NULL) /* max_ptime attribute not present */
Finding Media in an SDP Session Structure
sdp_media_t *sdp_find_media(sdp_media_t *media, const char *name);The sdp_find_media() function searches the media list that is specified by the media parameter for the media entry that is specified by the name parameter.
Return Values: The sdp_find_media() function returns a pointer to the media list entry (sdp_media_t *) that is specified by the name parameter when the function completes successfully. In all other cases, the sdp_find_media() function returns a value of NULL.
Example 3–3 Using the sdp_find_media() Function
The incomplete SDP description in this example has two sections, an audio section and a video section.
m=audio 49170 RTP/AVP 0 8 a=rtpmap:0 PCMU/8000 a=rtpmap:8 PCMA/8000 m=video 51372 RTP/AVP 31 32 a=rtpmap:31 H261/90000 a=rtpmap:32 MPV/90000 /* * Assuming that above description is parsed using sdp_parse() and that * the parsed structure is in "session" sdp_session_t structure. */ sdp_media_t *my_media; my_media = sdp_find_media(session->s_media, "video"); /* * my_media now points to the structure containg video media section * information */
Finding a Media Format in an SDP Session Structure
sdp_attr_t *sdp_find_media_rtpmap(sdp_media_t *media, const char *format);The sdp_find_media_rtpmap() function searches the attribute list of the media structure that is specified by the media parameter for the format entry that is specified by the format parameter.
Return Values: The sdp_find_media_rtpmap() function returns a pointer to the format entry (sdp_attr_t *) that is specified by the name parameter when the function completes successfully. In all other cases, the sdp_find_media() function returns a value of NULL.
Example 3–4 Using the sdp_find_media_rtpmap() Function
The incomplete SDP description in this example has two sections, an audio section and a video section.
m=audio 49170 RTP/AVP 0 8 a=rtpmap:0 PCMU/8000 a=rtpmap:8 PCMA/8000 m=video 51372 RTP/AVP 31 32 a=rtpmap:31 H261/90000 a=rtpmap:32 MPV/90000 /* * Assuming that above description is parsed using sdp_parse() and that * the parsed structure is in "session" sdp_session_t structure. */ sdp_media_t *video; sdp_attr_t *mpv; video = sdp_find_media(session->s_media, "video); mpv = sdp_find_media_rtpmap(video, "32"); /* * Now the attribute structure sdp_attr_t, mpv will be having * values from the attribute field "a=rtpmap:32 MPV/90000" */
Shutting Down the SDP Session Structure
The functions in this section perform the following functions:
-
Removing fields from an SDP session structure
-
Freeing an SDP session structure
Deleting Fields From the SDP Session Structure
int sdp_delete_all_field(sdp_session_t *session, const char field);The sdp_delete_all_field() function deletes all occurrences of the SDP field that is specified by the field parameter from the SDP structure. For example, if an SDP structure has three BANDWIDTH (b=) fields, calling this function with a value of SDP_BANDWIDTH_FIELD in the field parameter deletes all three BANDWIDTH fields from the session structure.
Return Values: The sdp_delete_all_field() function returns 0 when the function completes successfully. When the session argument is NULL or the field type is unknown, the function returns EINVAL. The value of errno does not change in the event of an error.
Deleting Fields From the SDP Media Structure
int sdp_delete_all_media_field(sdp_media_t *media, const char field);The sdp_delete_all_media_field() function deletes all occurrences of the SDP field that is specified by the field parameter from the SDP media structure.
Return Values: The sdp_delete_all_media_field() function returns 0 when the function completes successfully. When the session argument is NULL or the field type is unknown, the function returns EINVAL. The value of errno does not change in the event of an error.
Deleting Media From the SDP Media Structure
int sdp_delete_media(sdp_media_t **l_media, sdp_media_t *media);The sdp_delete_media() function deletes the media entry specified by the media parameter from the media list. This function finds the specified media entry by calling the sdp_find_media() function. This function frees the memory that is allocated to the media structure after deleting the media entry.
Return Values: The sdp_delete_media() function returns 0 when the function completes successfully. When the session argument is NULL or mandatory arguments do not exist, the function returns EINVAL. The value of errno does not change in the event of an error.
Deleting an Attribute From the SDP Media Structure
int sdp_delete_attribute(sdp_attr_t **l_attr, sdp_attr_t *attr);The sdp_delete_attribute() function deletes the attribute specified by the attr parameter from the media list. This function finds the specified attribute by calling either the sdp_find_media_rtpmap() function or the sdp_find_attribute() function. This function frees the memory that is allocated to the attribute structure after deleting the attribute.
Return Values: The sdp_delete_attribute() function returns 0 when the function completes successfully. When the session argument is NULL or mandatory arguments do not exist, the function returns EINVAL. The value of errno does not change in the event of an error.
Deleting an Attribute From the SDP Media Structure
void sdp_free_session(sdp_session_t *session);The sdp_free_session() function destroys the session specified by the session parameter and frees the resources that are associated with that structure.
SDP API Utility Functions
The functions in this section parse and populate the SDP session structure, clone an existing session, and convert an existing session to a string representation.
Parsing the SDP Session Structure
int sdp_parse(const char *sdp_info, int len, int flags, sdp_session_t **session, uint_t *p_error);The sdp_parse() function parses the SDP description in the sdp_info parameter and populates the sdp_session_t structure. The len parameter specifies the length of the character buffer sdp_info. The function allocates the memory required for the sdp_session_t structure. To free that memory, call the sdp_free_session() function.
The value of the flags parameter must be set to zero. When the flags parameter has a nonzero value, the sdp_parse() function fails with a return value of EINVAL and sets the value of *session to NULL.
The p_error parameter takes on the values of any fields that have parsing errors. This parameter cannot have a value of NULL. Possible values for the p_error parameter are in the following list:
SDP_VERSION_ERROR 0x00000001 SDP_ORIGIN_ERROR 0x00000002 SDP_NAME_ERROR 0x00000004 SDP_INFO_ERROR 0x00000008 SDP_URI_ERROR 0x00000010 SDP_EMAIL_ERROR 0x00000020 SDP_PHONE_ERROR 0x00000040 SDP_CONNECTION_ERROR 0x00000080 SDP_BANDWIDTH_ERROR 0x00000100 SDP_TIME_ERROR 0x00000200 SDP_REPEAT_TIME_ERROR 0x00000400 SDP_ZONE_ERROR 0x00000800 SDP_KEY_ERROR 0x00001000 SDP_ATTRIBUTE_ERROR 0x00002000 SDP_MEDIA_ERROR 0x00004000 SDP_FIELDS_ORDER_ERROR 0x00008000 SDP_MISSING_FIELDS 0x00010000
When the SDP structure violates RFC 4566 by having fields out of order, the sdp_parse() function sets the value of the p_error parameter to SDP_FIELDS_ORDER_ERROR. When the SDP structure violates RFC 4566 by lacking mandatory fields, the sdp_parse() function sets the value of the p_error parameter to SDP_MISSING_FIELDS.
The sdp_parse() function continues to parse after processing a field with a parsing error, but the field with the parsing error will not be present in the resulting sdp_session_t structure.
Return Values: The sdp_parse() function returns 0 when the function completes successfully. When the session arguments are invalid, the sdp_parse()function returns EINVAL. When memory allocation fails while the sdp_parse() function is parsing sdp_info, the function returns ENOMEM. The value of errno does not change in the event of an error.
Example 3–5 Example: Parsing an SDP Session Structure
In this example, the SDP session structure is as follows:
v=0\r\n o=jdoe 23423423 234234234 IN IP4 192.168.1.1\r\n s=SDP seminar\r\n i=A seminar on the session description protocol\r\n e=test@host.com c=IN IP4 156.78.90.1\r\n t=2873397496 2873404696\r\n
After calling the sdp_parse_t() function, the resulting sdp_session_t structure is as follows:
session {
sdp_session_version = 1
s_version = 0
s_origin {
o_username = "jdoe"
o_id = 23423423ULL
o_version = 234234234ULL
o_nettype = "IN"
o_addrtype = "IP4"
o_address = "192.168.1.1"
}
s_name = "SDP seminar"
s_info = "A seminar on the session description protocol"
s_uri = (nil)
s_email {
value = "test@host.com"
next = (nil)
}
s_phone = (nil)
s_conn {
c_nettype = "IN"
c_addrtype = "IP4"
c_address = "156.78.90.1"
c_addrcount = 0
c_ttl = 0
c_next = (nil)
}
s_bw = (nil)
s_time {
t_start = 2873397496ULL
t_stop = 2873404696ULL
t_repeat = (nil)
t_next = (nil)
}
s_zone = (nil)
s_key = (nil)
s_attr = (nil)
s_media = (nil)
}
Cloning an Existing SDP Session Structure
sdp_session_t sdp_clone_session(const sdp_session_t *session);The sdp_clone_session() function creates a new SDP session structure that is identical to the SDP session structure that is identified in the session parameter. The sdp_clone_session() function returns the cloned session structure upon successful completion. The sdp_clone_session() function returns NULL on failure.
Converting an SDP Session Structure to a String
char *sdp_session_to_str(const sdp_session_t *session, int *error);The sdp_session_to_str() function returns the string representation of the SDP session structure that is specified by the session parameter. The sdp_session_to_str() function appends a carriage return/line feed to the end of each SDP field before appending the field to the string.
Return Values: The sdp_session_to_str() function returns the string representation of the SDP session structure upon completing successfully. The sdp_session_to_str() function returns NULL in all other cases. The sdp_session_to_str() function returns an error pointer to EINVAL when the input is null. The sdp_session_to_str() function returns an error pointer to ENOMEM when a memory allocation failure occurs. The value of errno does not change in the event of an error.
- © 2010, Oracle Corporation and/or its affiliates