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.

Skip Navigation Links
Exit Print View
	Programming Interfaces Guide Oracle Solaris 11 Information Library