Go to main content

Oracle® Solaris 11.4 Programming Interfaces Guide

Exit Print View

Updated: November 2020
 
 

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. For more information, see the Deleting an Attribute From the SDP Media Structure.

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.

For more information, see the sdp_add_origin(3COMMPUTIL) man page.

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.

For more information, see the sdp_add_name(3COMMPUTIL) man page.

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.

For more information, see the sdp_add_information(3COMMPUTIL) man page.

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.

For more information, see the sdp_add_uri(3COMMPUTIL) man page.

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.

For more information, see the sdp_add_email(3COMMPUTIL) man page.

Adding a Telephone Field to the SDP Session Structure

int sdp_add_phone(sdp_session_t *session, const char *phone);

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.

For more information, see the sdp_add_phone(3COMMPUTIL) man page.

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.

For more information, see the sdp_add_connection(3COMMPUTIL) man page.

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.

For more information, see the sdp_add_bandwidth(3COMMPUTIL) man page.

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.

For more information, see the sdp_add_time(3COMMPUTIL) man page.

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.

For more information, see the sdp_add_repeat(3COMMPUTIL) man page.

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.

For more information, see the sdp_add_zone(3COMMPUTIL) man page.

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.

For more information, see the sdp_add_key(3COMMPUTIL) man page.

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.

For more information, see the sdp_add_attribute(3COMMPUTIL) man page.

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.

For more information, see the sdp_add_media(3COMMPUTIL) man page.

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

For more information, see the sdp_find_attribute(3COMMPUTIL) man page.

Example 2  Using sdp_find_attribute()

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.

For more information, see the sdp_find_media(3COMMPUTIL) man page.

Example 3  Using sdp_find_media()

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.

For more information, see the sdp_find_media_rtpmap(3COMMPUTIL) man page.

Example 4  Using sdp_find_media_rtpmap()

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.

For more information, see the sdp_delete_all_field(3COMMPUTIL) man page.

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.

For more information, see the sdp_delete_all_media_field(3COMMPUTIL) man page.

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.

For more information, see the sdp_delete_media(3COMMPUTIL) man page.

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.

For more information, see the sdp_delete_attribute(3COMMPUTIL) man page.

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.

For more information, see the sdp_free_session(3COMMPUTIL) man page.

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. For more information, see Deleting an Attribute From the SDP Media Structure.

Example 5  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@example.com
c=IN IP4 192.168.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@example.com"
                next = (nil)
        }
        s_phone = (nil)
        s_conn {
                c_nettype = "IN"
                c_addrtype = "IP4"
                c_address = "192.168.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.

For more information, see the sdp_clone_session(3COMMPUTIL) man page.

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.

For more information, see the sdp_session_to_str(3COMMPUTIL) man page.