share/man/man3commputil/sdp_add_origin.3commputil

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems Inc. All Rights Reserved.
   3 .\" Portions Copyright (c) The Internet Society (2006) All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH SDP_ADD_ORIGIN 3COMMPUTIL "Oct 12, 2007"
   8 .SH NAME
   9 sdp_add_origin, sdp_add_name, sdp_add_information, sdp_add_uri, sdp_add_email,
  10 sdp_add_phone, sdp_add_connection, sdp_add_bandwidth, sdp_add_repeat,
  11 sdp_add_time, sdp_add_zone, sdp_add_key, sdp_add_attribute, sdp_add_media \-
  12 add specific SDP fields to the SDP session structure
  13 .SH SYNOPSIS
  14 .LP
  15 .nf
  16 \fBcc\fR [ \fIflag\fR...] \fIfile\fR... -\fBlcommputil\fR [ \fIlibrary\fR...]
  17 #include <sdp.h>
  18
  19 \fBint\fR \fBsdp_add_origin\fR(\fBsdp_session_t *\fR\fIsession\fR, \fBconst char *\fR\fIname\fR,
  20      \fBuint64_t\fR \fIid\fR, \fBuint64_t\fR \fIver\fR, \fBconst char *\fR\fInettype\fR,
  21      \fBconst char *\fR\fIaddrtype\fR, \fBconst char *\fR\fIaddress\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR sdp_add_name(\fBsdp_session_t *\fR\fIsession\fR, \fBconst char *\fR\fIname\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBint\fR \fBsdp_add_information\fR(\fBchar **\fR\fIinformation\fR, \fBconst char *\fR\fIvalue\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBint\fR \fBsdp_add_uri\fR(\fBsdp_session_t *\fR\fIsession\fR, \fBconst char *\fR\fIuri\fR);
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBint\fR \fBsdp_add_email\fR(\fBsdp_session_t *\fR\fIsession\fR, \fBconst char *\fR\fIemail\fR);
  42 .fi
  43
  44 .LP
  45 .nf
  46 \fBint\fR \fBsdp_add_phone\fR(\fBsdp_session_t *\fR\fIsession\fR, \fBconst char *\fR\fIphone\fR);
  47 .fi
  48
  49 .LP
  50 .nf
  51 \fBint\fR \fBsdp_add_connection\fR(\fBsdp_conn_t **\fR\fIconn\fR, \fBconst char *\fR\fInettype\fR,
  52      \fBconst char *\fR\fIaddrtype\fR, \fBconst char *\fR\fIaddress\fR, \fBuint8_t\fR \fIttl\fR,
  53      \fBint\fR \fIaddrcount\fR);
  54 .fi
  55
  56 .LP
  57 .nf
  58 \fBint\fR \fBsdp_add_bandwidth\fR(\fBsdp_bandwidth_t **\fR\fIbw\fR, \fBconst char *\fR\fItype\fR,
  59      \fBuint64_t\fR \fIvalue\fR);
  60 .fi
  61
  62 .LP
  63 .nf
  64 \fBint\fR \fBsdp_add_repeat\fR(\fBsdp_time_t *\fR\fItime\fR, \fBuint64_t\fR \fIinterval\fR,
  65      \fBuint64_t\fR \fIduration\fR, \fBconst char *\fR\fIoffset\fR);
  66 .fi
  67
  68 .LP
  69 .nf
  70 \fBint\fR \fBsdp_add_time\fR(\fBsdp_session_t *\fR\fIsession\fR, \fBuint64_t\fR \fIstarttime\fR,
  71      \fBuint64_t\fR \fIstoptime\fR, \fBsdp_time_t **\fR\fItime\fR);
  72 .fi
  73
  74 .LP
  75 .nf
  76 \fBint\fR \fBsdp_add_zone\fR(\fBsdp_session_t *\fR\fIsession\fR, \fBuint64_t\fR \fItime\fR,
  77      \fBconst char *\fR\fIoffset\fR);
  78 .fi
  79
  80 .LP
  81 .nf
  82 \fBint\fR \fBsdp_add_key\fR(\fBsdp_key_t **\fR\fIkey\fR, \fBconst char *\fR\fImethod\fR,
  83      \fBconst char *\fR\fIenckey\fR);
  84 .fi
  85
  86 .LP
  87 .nf
  88 \fBint\fR \fBsdp_add_attribute\fR(\fBsdp_attr_t **\fR\fIattr\fR, \fBconst char *\fR\fIname\fR,
  89      \fBconst char *\fR\fIvalue\fR);
  90 .fi
  91
  92 .LP
  93 .nf
  94 \fBint\fR \fBsdp_add_media\fR(\fBsdp_session_t *\fR\fIsession\fR, \fBconst char *\fR\fIname\fR,
  95      \fBuint_t\fR \fIport\fR, \fBint\fR \fIportcount\fR, \fBconst char *\fR\fIprotocol\fR,
  96      \fBconst char *\fR\fIformat\fR, \fBsdp_media_t **\fR\fImedia\fR);
  97 .fi
  98
  99 .SH DESCRIPTION
 100 .sp
 101 .LP
 102 The caller has to first call \fBsdp_new_session\fR(3COMMPUTIL) and get pointer
 103 to a session structure. Then that pointer is used as argument in the following
 104 functions and the session structure is constructed. Once the structure is built
 105 the caller converts it to a string representation using
 106 \fBsdp_session_to_str\fR(3COMMPUTIL).
 107 .sp
 108 .LP
 109 The \fBsdp_add_origin()\fR function adds ORIGIN (o=) SDP field to the session
 110 structure (\fBsdp_session_t\fR) using \fIname\fR, \fIid\fR, \fIver\fR,
 111 \fInettype\fR, \fIaddrtype\fR, and \fIaddress\fR.
 112 .sp
 113 .LP
 114 The \fBsdp_add_name()\fR function adds NAME (s=) SDP field to the session
 115 structure (\fBsdp_session_t\fR) using \fIname\fR.
 116 .sp
 117 .LP
 118 The \fBsdp_add_information()\fR function adds INFO (i=) SDP field to the
 119 session structure (sdp_session_t) or media structure (\fBsdp_media_t\fR) using
 120 value. Since this field can be either in the media section or the session
 121 section of an SDP description the caller has to pass
 122 &\fIsession\fR\(->\fBs_info\fR or &\fImedia\fR\(->\fBm_info\fR as the first
 123 argument.
 124 .sp
 125 .LP
 126 The \fBsdp_add_uri()\fR function adds URI (u=) SDP field to the session
 127 structure (\fBsdp_session_t\fR) using \fIuri\fR.
 128 .sp
 129 .LP
 130 The \fBsdp_add_email()\fR function adds EMAIL (e=) SDP field to the session
 131 structure (\fBsdp_session_t\fR) using \fIemail\fR.
 132 .sp
 133 .LP
 134 The \fBsdp_add_phone()\fR function adds PHONE (p=) SDP field to the session
 135 structure (\fBsdp_session_t\fR) using \fIphone\fR.
 136 .sp
 137 .LP
 138 The \fBsdp_add_connection()\fR function adds CONNECTION (c=) SDP field to the
 139 session structure (\fBsdp_session_t\fR) or the media structure
 140 (\fBsdp_media_t\fR) using \fInettype\fR, \fIaddrtype\fR, \fIaddress\fR,
 141 \fIttl\fR, and \fIaddrcount\fR. While adding an IP4 or IP6 unicast address the
 142 \fIttl\fR and \fIaddrcount\fR should be set to 0. For multicast address the
 143 \fIttl\fR should be set a reasonable value (0 - 255) and \fIaddrcount\fR cannot
 144 be 0. Also since this field can be either in the media section or the session
 145 section of an SDP description, the caller has to pass
 146 &\fIsession\fR\(->\fBs_conn\fR or &\fImedia\fR\(->\fBm_conn\fR as the first
 147 argument.
 148 .sp
 149 .LP
 150 The \fBsdp_add_bandwidth()\fR function adds BANDWIDTH (b=) SDP field to the
 151 session structure (\fBsdp_session_t\fR) or the media structure
 152 (\fBsdp_media_t\fR) using \fItype\fR and \fIvalue\fR. Since this field can be
 153 either in the media section or the session section of an SDP description, the
 154 caller has to pass &\fBsession\fR\(->\fBs_bw\fR or &\fBmedia\fR\(->\fBm_bw\fR
 155 as the first argument.
 156 .sp
 157 .LP
 158 The \fBsdp_add_time()\fR function adds the TIME (t=) SDP field to the session
 159 structure using \fIstartime\fR and \fIstoptime\fR. The pointer to the newly
 160 created time structure is returned in \fItime\fR. This pointer is then used in
 161 \fBsdp_add_repeat()\fR function.
 162 .sp
 163 .LP
 164 The \fBsdp_add_repeat()\fR function adds the REPEAT (r=) SDP field to the
 165 session structure using interval, duration and offset. Here, offset is a string
 166 holding one or more offset values, for example "60" or "60 1d 3h".
 167 .sp
 168 .LP
 169 The \fBsdp_add_zone()\fR function adds the ZONE (z=) SDP field to the session
 170 structure using \fItime\fR and \fIoffset\fR. To add multiple time and offset
 171 values in a single zone field, call this function once for each pair. See the
 172 example below.
 173 .sp
 174 .LP
 175 The \fBsdp_add_key()\fR function adds the KEY (k=) SDP field to the session
 176 structure (\fBsdp_session_t\fR) or media structure (\fBsdp_media_t\fR) using
 177 \fImethod\fR and \fIenckey\fR.  Since this field can be either in the media
 178 section or the session section of an SDP description, the caller has to pass
 179 &\fIsession\fR\(->\fBs_key\fR or &\fImedia\fR\(->\fBm_key\fR as the first
 180 argument.
 181 .sp
 182 .LP
 183 The \fBsdp_add_attribute()\fR function adds the ATTRIBUTE (a=) SDP field to the
 184 session structure (\fBsdp_session_t\fR) or media structure (\fBsdp_media_t\fR)
 185 using \fIname\fR and \fIvalue\fR. Since this field can be either in the media
 186 section or the session section of an SDP description, the caller has to pass
 187 &\fIsession\fR\(->\fBs_attr\fR or &\fImedia\fR\(->\fBm_attr\fR as the first
 188 argument.
 189 .sp
 190 .LP
 191 The \fBsdp_add_media()\fR function adds the MEDIA (m=) SDP field to the session
 192 structure (\fBsdp_session_t\fR) using \fIname\fR, \fIport\fR, \fIportcount\fR,
 193 \fIprotocol\fR, and \fIformat\fR. Here, \fIformat\fR is a string holding
 194 possibly more than one value, for example, "0 31 32 97". The pointer to the
 195 newly created media structure is returned in \fImedia\fR. This pointer is then
 196 used to add SDP fields specific to that media section.
 197 .SH RETURN VALUES
 198 .sp
 199 .LP
 200 These functions return 0 on success and the appropriate error value on failure.
 201 The value of \fBerrno\fR is not changed by these calls in the event of an
 202 error.
 203 .SH ERRORS
 204 .sp
 205 .LP
 206 These functions will fail if:
 207 .sp
 208 .ne 2
 209 .na
 210 \fB\fBEINVAL\fR\fR
 211 .ad
 212 .RS 10n
 213 Mandatory parameters are not provided (they are null).
 214 .RE
 215
 216 .sp
 217 .ne 2
 218 .na
 219 \fB\fBENOMEM\fR\fR
 220 .ad
 221 .RS 10n
 222 The allocation of memory failed.
 223 .RE
 224
 225 .SH EXAMPLES
 226 .LP
 227 \fBExample 1 \fRBuild an SDP session structure
 228 .sp
 229 .LP
 230 In the following example we see how to build an SDP session structure using the
 231 functions described on this manual page. We first get a pointer to
 232 \fBsdp_session_t\fR structure by calling \fBsdp_new_session()\fR. Then to this
 233 newly created structure we add various SDP fields. Once the structure is built
 234 we obtain a string representation of the structure using
 235 \fBsdp_session_to_str()\fR function. Since its caller responsibility to free
 236 the session we call \fBsdp_free_session()\fR towards the end.
 237
 238 .sp
 239 .in +2
 240 .nf
 241 /* SDP Message we will be building
 242 "v=0\er\en\e
 243 o=Alice 2890844526 2890842807 IN IP4 10.47.16.5\er\en\e
 244 s=-\er\en\e
 245 i=A Seminar on the session description protocol\er\en\e
 246 u=http://www.example.com/seminars/sdp.pdf\er\en\e
 247 e=alice@example.com (Alice Smith)\er\en\e
 248 p=+1 911-345-1160\er\en\e
 249 c=IN IP4 10.47.16.5\er\en\e
 250 b=CT:1024\er\en\e
 251 t=2854678930 2854679000\er\en\e
 252 r=604800 3600 0 90000\er\en\e
 253 z=2882844526 -1h 2898848070 0h\er\en\e
 254 a=recvonly\er\en\e
 255 m=audio 49170 RTP/AVP 0\er\en\e
 256 i=audio media\er\en\e
 257 b=CT:1000\er\en\e
 258 k=prompt\er\en\e
 259 m=video 51372 RTP/AVP 99 90\er\en\e
 260 i=video media\er\en\e
 261 a=rtpmap:99 h232-199/90000\er\en\e
 262 a=rtpmap:90 h263-1998/90000\er\en"
 263 */
 264
 265 #include stdio.h>
 266 #include string.h>
 267 #include errno.h>
 268 #include sdp.h>
 269
 270 int main ()
 271 {
 272     sdp_session_t         *my_sess;
 273     sdp_media_t           *my_media;
 274     sdp_time_t            *my_time;
 275     char *b_sdp;
 276
 277     my_sess = sdp_new_session();
 278     if (my_sess == NULL) {
 279         return (ENOMEM);
 280     }
 281     my_sess->version = 0;
 282     if (sdp_add_name(my_sess, "-") != 0)
 283         goto err_ret;
 284     if (sdp_add_origin(my_sess, "Alice", 2890844526ULL, 2890842807ULL,
 285          "IN", "IP4", "10.47.16.5") != 0)
 286         goto err_ret;
 287     if (sdp_add_information(&my_sess->s_info, "A Seminar on the session"
 288                 "description protocol") != 0)
 289         goto err_ret;
 290     if (sdp_add_uri (my_sess, "http://www.example.com/seminars/sdp.pdf")
 291                 != 0)
 292         goto err_ret;
 293     if (sdp_add_email(my_sess, "alice@example.com (Alice smith)") != 0)
 294         goto err_ret;
 295     if (sdp_add_phone(my_sess, "+1 911-345-1160") != 0)
 296         goto err_ret;
 297     if (sdp_add_connection(&my_sess->s_conn, "IN", "IP4", "10.47.16.5",
 298                0, 0) != 0)
 299         goto err_ret;
 300     if (sdp_add_bandwidth(&my_sess->s_bw, "CT", 1024) != 0)
 301         goto err_ret;
 302     if (sdp_add_time(my_sess, 2854678930ULL, 2854679000ULL, &my_time)
 303                != 0)
 304         goto err_ret;
 305     if (sdp_add_repeat(my_time, 604800ULL, 3600ULL, "0 90000") != 0)
 306         goto err_ret;
 307     if (sdp_add_zone(my_sess, 2882844526ULL, "-1h") != 0)
 308         goto err_ret;
 309     if (sdp_add_zone(my_sess, 2898848070ULL, "0h") != 0)
 310         goto err_ret;
 311     if (sdp_add_attribute(&my_sess->s_attr, "sendrecv", NULL) != 0)
 312         goto err_ret;
 313     if (sdp_add_media(my_sess, "audio", 49170, 1, "RTP/AVP",
 314                       "0", &my_media) != 0)
 315         goto err_ret;
 316     if (sdp_add_information(&my_media->m_info, "audio media") != 0)
 317         goto err_ret;
 318     if (sdp_add_bandwidth(&my_media->m_bw, "CT", 1000) != 0)
 319         goto err_ret;
 320     if (sdp_add_key(&my_media->m_key, "prompt", NULL) != 0)
 321         goto err_ret;
 322     if (sdp_add_media(my_sess, "video", 51732, 1, "RTP/AVP",
 323                 "99 90", &my_media) != 0)
 324         goto err_ret;
 325     if (sdp_add_information(&my_media->m_info, "video media") != 0)
 326         goto err_ret;
 327     if (sdp_add_attribute(&my_media->m_attr, "rtpmap",
 328               "99 h232-199/90000") != 0)
 329         goto err_ret;
 330     if (sdp_add_attribute(&my_media->m_attr, "rtpmap",
 331               "90 h263-1998/90000") != 0)
 332         goto err_ret;
 333     b_sdp = sdp_session_to_str(my_sess, &error);
 334
 335     /*
 336      * b_sdp is the string representation of my_sess structure
 337      */
 338
 339     free(b_sdp);
 340     sdp_free_session(my_sess);
 341     return (0);
 342 err_ret:
 343     free(b_sdp);
 344     sdp_free_session(my_sess);
 345     return (1);
 346 }
 347 .fi
 348 .in -2
 349
 350 .SH ATTRIBUTES
 351 .sp
 352 .LP
 353 See \fBattributes\fR(5) for descriptions of the following attributes:
 354 .sp
 355
 356 .sp
 357 .TS
 358 box;
 359 c | c
 360 l | l .
 361 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 362 _
 363 Interface Stability     Committed
 364 _
 365 MT-Level        Safe
 366 .TE
 367
 368 .SH SEE ALSO
 369 .sp
 370 .LP
 371 \fBlibcommputil\fR(3LIB), \fBsdp_new_session\fR(3COMMPUTIL),
 372 \fBsdp_parse\fR(3COMMPUTIL), \fBsdp_session_to_str\fR(3COMMPUTIL),
 373 \fBattributes\fR(5)