usr/src/man/man3commputil/sdp_parse.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_PARSE 3COMMPUTIL "Oct 12, 2007"
   8 .SH NAME
   9 sdp_parse \- parse the SDP description
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR...] \fIfile\fR... -\fBlcommputil\fR [ \fIlibrary\fR...]
  14 #include <sdp.h>
  15
  16 \fBint\fR \fBsdp_parse\fR(\fBconst char *\fR\fIsdp_info\fR, \fBint\fR \fIlen\fR, \fBint\fR \fIflags\fR,
  17      \fBsdp_session_t **\fR\fIsession\fR, \fBuint_t *\fR\fIp_error\fR);
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 The \fBsdp_parse()\fR function parses the SDP description present in
  24 \fIsdp_info\fR and populates the \fBsdp_session_t\fR structure. The \fIlen\fR
  25 argument specifies the length of the character buffer \fIsdp_info\fR. The
  26 \fIflags\fR argument is not used, but must be set to 0, otherwise the call
  27 fails with the error value of \fBEINVAL\fR and *\fIsession\fR set to
  28 \fINULL\fR. The function allocates the memory required for the
  29 \fBsdp_session_t\fR structure and hence the caller is responsible for freeing
  30 the parsed session structure (\fBsdp_session_t\fR) using
  31 \fBsdp_free_session()\fR, described on the \fBsdp_new_session\fR(3COMMPUTIL)
  32 manual page.
  33 .sp
  34 .LP
  35 The \fIp_error\fR argument identifies any field that had a parsing error. It
  36 cannot be \fINULL\fR and can take any of the following values:
  37 .sp
  38
  39 .sp
  40 .TS
  41 l l
  42 l l .
  43 \fBSDP_VERSION_ERROR\fR 0x00000001
  44 \fBSDP_ORIGIN_ERROR\fR  0x00000002
  45 \fBSDP_NAME_ERROR\fR    0x00000004
  46 \fBSDP_INFO_ERROR\fR    0x00000008
  47 \fBSDP_URI_ERROR\fR     0x00000010
  48 \fBSDP_EMAIL_ERROR\fR   0x00000020
  49 \fBSDP_PHONE_ERROR\fR   0x00000040
  50 \fBSDP_CONNECTION_ERROR\fR      0x00000080
  51 \fBSDP_BANDWIDTH_ERROR\fR       0x00000100
  52 \fBSDP_TIME_ERROR\fR    0x00000200
  53 \fBSDP_REPEAT_TIME_ERROR\fR     0x00000400
  54 \fBSDP_ZONE_ERROR\fR    0x00000800
  55 \fBSDP_KEY_ERROR\fR     0x00001000
  56 \fBSDP_ATTRIBUTE_ERROR\fR       0x00002000
  57 \fBSDP_MEDIA_ERROR\fR   0x00004000
  58 \fBSDP_FIELDS_ORDER_ERROR\fR    0x00008000
  59 \fBSDP_MISSING_FIELDS\fR        0x00010000
  60 .TE
  61
  62 .sp
  63 .LP
  64 RFC 4566 states that the fields in the SDP description need to be in a strict
  65 order. If the fields are not in the order specified in the RFC,
  66 \fBSDP_FIELDS_ORDER_ERROR\fR will be set.
  67 .sp
  68 .LP
  69 RFC 4566 mandates certain fields to be present in SDP description. If those
  70 fields are missing then \fBSDP_MISSING_FIELDS\fR will be set.
  71 .sp
  72 .LP
  73 Applications can check for presence of parsing error using the bit-wise
  74 operators.
  75 .sp
  76 .LP
  77 If there was an error on a particular field, that field information will not be
  78 in the \fBsdp_session_t\fR structure. Also, parsing continues even if there was
  79 a field with a parsing error.
  80 .sp
  81 .LP
  82 The \fBsdp_session_t\fR structure is defined in the header file \fB<sdp.h>\fR
  83 and contains the following members:
  84 .sp
  85 .in +2
  86 .nf
  87 typedef    struct sdp_session {
  88     int              sdp_session_version;  /* SDP session verstion */
  89     int              s_version;            /* SDP version field */
  90     sdp_origin_t     *s_origin;            /* SDP origin field */
  91     char             *s_name;              /* SDP name field */
  92     char             *s_info;              /* SDP info field */
  93     char             *s_uri;               /* SDP uri field */
  94     sdp_list_t       *s_email;             /* SDP email field */
  95     sdp_list_t       *s_phone;             /* SDP phone field */
  96     sdp_conn_t       *s_conn;              /* SDP connection field */
  97     sdp_bandwidth_t  *s_bw;                /* SDP bandwidth field */
  98     sdp_time_t       *s_time;              /* SDP time field */
  99     sdp_zone_t       *s_zone;              /* SDP zone field */
 100     sdp_key_t        *s_key;               /* SDP key field */
 101     sdp_attr_t       *s_attr;              /* SDP attribute field */
 102     sdp_media_t      *s_media;             /* SDP media field */
 103 } sdp_session_t;
 104 .fi
 105 .in -2
 106
 107 .sp
 108 .LP
 109 The \fBsdp_session_version\fR member is used to track the version of the
 110 structure. Initially it is set to \fBSDP_SESSION_VERSION_1\fR (= 1).
 111 .sp
 112 .LP
 113 The \fBsdp_origin_t\fR structure contains the following members:
 114 .sp
 115 .in +2
 116 .nf
 117 typedef struct sdp_origin {
 118     char        *o_username;  /* username of the originating host */
 119     uint64_t    o_id;         /* session id */
 120     uint64_t    o_version;    /* version number of this session */
 121                               /* description */
 122     char        *o_nettype;   /* type of network */
 123     char        *o_addrtype;  /* type of the address */
 124     char        *o_address;   /* address of the machine from which */
 125                               /* session was created */
 126 } sdp_origin_t;
 127 .fi
 128 .in -2
 129
 130 .sp
 131 .LP
 132 The \fBsdp_conn_t\fR structure contains the following members:
 133 .sp
 134 .in +2
 135 .nf
 136 typedef struct sdp_conn {
 137     char            *c_nettype;  /* type of network */
 138     char            *c_addrtype; /* type of the address */
 139     char            *c_address;  /* unicast-address or multicast */
 140                                  /* address */
 141     int             c_addrcount; /* number of addresses (case of */
 142                                  /* multicast address with layered */
 143                                  /* encodings */
 144     struct sdp_conn *c_next;     /* pointer to next connection */
 145                                  /* structure; there could be several */
 146                                  /* connection fields in SDP description */
 147     uint8_t         c_ttl;       /* TTL value for IPV4 multicast address */
 148 } sdp_conn_t;
 149 .fi
 150 .in -2
 151
 152 .sp
 153 .LP
 154 The \fBsdp_bandwidth_t\fR structure contains the following members:
 155 .sp
 156 .in +2
 157 .nf
 158 typedef struct sdp_bandwidth {
 159     char                  *b_type; /* info needed to interpret b_value */
 160     uint64_t              b_value; /* bandwidth value */
 161     struct sdp_bandwidth  *b_next; /* pointer to next bandwidth structure*/
 162                                    /* (there could be several bandwidth */
 163                                    /* fields in SDP description */
 164 } sdp_bandwidth_t;
 165 .fi
 166 .in -2
 167
 168 .sp
 169 .LP
 170 The \fBsdp_list_t\fR structure is a linked list of void pointers. This
 171 structure holds SDP fields like email and phone, in which case the void
 172 pointers point to character buffers.  It to hold information in cases where the
 173 number of elements is not predefined (for example, offset (in repeat field)
 174 where void pointer holds integer values or format (in media field) where void
 175 pointers point to character buffers). The \fBsdp_list_t\fR structure is defined
 176 as:
 177 .sp
 178 .in +2
 179 .nf
 180 typedef struct sdp_list {
 181     void            *value; /* string values in case of email, phone and */
 182                             /* format (in media field) or integer values */
 183                             /* in case of offset (in repeat field) */
 184     struct sdp_list *next;  /* pointer to the next node in the list */
 185 } sdp_list_t;
 186 .fi
 187 .in -2
 188
 189 .sp
 190 .LP
 191 The \fBsdp_repeat_t\fR structure contains the following members:
 192 .sp
 193 .in +2
 194 .nf
 195 typedef struct sdp_repeat {
 196     uint64_t          r_interval; /* repeat interval, e.g. 86400 seconds */
 197                                   /* (1 day) */
 198     uint64_t          r_duration; /* duration of session, e.g. 3600 */
 199                                   /* seconds (1 hour) */
 200     sdp_list_t        *r_offset;  /* linked list of offset values; each */
 201                                   /* represents offset from start-time */
 202                                   /* in SDP time field */
 203     struct sdp_repeat *r_next;    /* pointer to next repeat structure; */
 204                                   /* there could be several repeat */
 205                                   /* fields in SDP description */
 206 .fi
 207 .in -2
 208
 209 .sp
 210 .LP
 211 The \fBsdp_repeat_t\fR structure will always be part of the time structure
 212 \fBsdp_time_t\fR, since the repeat field does not appear alone in SDP
 213 description and is always associated with the time field.
 214 .sp
 215 .LP
 216 The \fBsdp_time_t\fR structure contains the following members:
 217 .sp
 218 .in +2
 219 .nf
 220 typedef struct sdp_time {
 221     uint64_t         t_start;   /* start-time for a session */
 222     uint64_t         t_stop;    /* end-time for a session */
 223     sdp_repeat_t     *t_repeat; /* points to the SDP repeat field */
 224     struct sdp_time  *t_next;   /* pointer to next time field; there */
 225                                 /* could there could be several time */
 226                                 /* fields in SDP description */
 227 } sdp_time_t;
 228 .fi
 229 .in -2
 230
 231 .sp
 232 .LP
 233 The \fBsdp_zone_t\fR structure contains the following members:
 234 .sp
 235 .in +2
 236 .nf
 237 typedef struct sdp_zone {
 238     uint64_t        z_time;    /* base time */
 239     char            *z_offset; /* offset added to z_time to determine */
 240                                /* session time; mainly used for daylight */
 241                                /* saving time conversions */
 242     struct sdp_zone *z_next;   /* pointer to next zone field; there */
 243                                /* could be several <adjustment-time> */
 244                                /* <offset> pairs within a zone field */
 245 } sdp_zone_t;
 246 .fi
 247 .in -2
 248
 249 .sp
 250 .LP
 251 The \fBsdp_key_t\fR structure contains the following members:
 252 .sp
 253 .in +2
 254 .nf
 255 typedef struct sdp_key {
 256     char   *k_method;   /* key type */
 257     char   *k_enckey;   /* encryption key */
 258 } sdp_key_t;
 259 .fi
 260 .in -2
 261
 262 .sp
 263 .LP
 264 The \fBsdp_attr_t\fR structure contains the following members:
 265 .sp
 266 .in +2
 267 .nf
 268 typedef struct sdp_attr {
 269     char            *a_name;  /* name of the attribute */
 270     char            *a_value; /* value of the attribute */
 271     struct sdp_attr *a_next;  /* pointer to the next attribute */
 272                               /* structure; there could be several */
 273                               /* attribute fields within SDP description */
 274 } sdp_attr_t;
 275 .fi
 276 .in -2
 277
 278 .sp
 279 .LP
 280 The \fBsdp_media_t\fR structure contains the following members:
 281 .sp
 282 .in +2
 283 .nf
 284 typedef struct sdp_media {
 285     char              *m_name;     /* name of the media such as "audio", */
 286                                    /* "video", "message" */
 287     uint_t            m_port;      /* transport layer port information */
 288     int               m_portcount; /* number of ports in case of */
 289                                    /* hierarchically encoded streams */
 290     char              *m_proto;    /* transport protocol */
 291     sdp_list_t        *m_format;   /* media format description */
 292     char              *m_info;     /* media info field */
 293     sdp_conn_t        *m_conn;     /* media connection field */
 294     sdp_bandwidth_t   *m_bw;       /* media bandwidth field */
 295     sdp_key_t         *m_key;      /* media key field */
 296     sdp_attr_t        *m_attr;     /* media attribute field */
 297     struct sdp_media  *m_next;     /* pointer to next media structure; */
 298                                    /* there could be several media */
 299                                    /* sections in SDP description */
 300     sdp_session_t     *m_session;  /* pointer to the session structure */
 301 } sdp_media_t;
 302 .fi
 303 .in -2
 304
 305 .SH RETURN VALUES
 306 .sp
 307 .LP
 308 The \fBsdp_parse()\fR function returns 0 on success and the appropriate error
 309 value on failure. The value of \fBerrno\fR is not changed by these calls in the
 310 event of an error.
 311 .SH ERRORS
 312 .sp
 313 .LP
 314 The \fBsdp_parse()\fR function will fail if:
 315 .sp
 316 .ne 2
 317 .na
 318 \fB\fBEINVAL\fR\fR
 319 .ad
 320 .RS 10n
 321 Arguments to the function were invalid.
 322 .RE
 323
 324 .sp
 325 .ne 2
 326 .na
 327 \fB\fBENOMEM\fR\fR
 328 .ad
 329 .RS 10n
 330 Memory allocation failed while parsing \fIsdp_info\fR.
 331 .RE
 332
 333 .SH EXAMPLES
 334 .LP
 335 \fBExample 1 \fR\fBsdp_parse()\fR example
 336 .sp
 337 .LP
 338 If the SDP description was
 339
 340 .sp
 341 .in +2
 342 .nf
 343 v=0\er\en
 344 o=jdoe 23423423 234234234 IN IP4 192.168.1.1\er\en
 345 s=SDP seminar\er\en
 346 i=A seminar on the session description protocol\er\en
 347 e=test@host.com
 348 c=IN IP4 156.78.90.1\er\en
 349 t=2873397496 2873404696\er\en
 350 .fi
 351 .in -2
 352
 353 .sp
 354 .LP
 355 then after call to \fBsdp_parse()\fR function the \fBsdp_session_t\fR structure
 356 would be
 357
 358 .sp
 359 .in +2
 360 .nf
 361 session {
 362         sdp_session_version = 1
 363         s_version = 0
 364         s_origin {
 365                 o_username = "jdoe"
 366                 o_id = 23423423ULL
 367                 o_version = 234234234ULL
 368                 o_nettype = "IN"
 369                 o_addrtype = "IP4"
 370                 o_address = "192.168.1.1"
 371         }
 372         s_name = "SDP seminar"
 373         s_info = "A seminar on the session description protocol"
 374         s_uri =  (nil)
 375         s_email {
 376                 value = "test@host.com"
 377                 next = (nil)
 378         }
 379         s_phone = (nil)
 380         s_conn {
 381                 c_nettype = "IN"
 382                 c_addrtype = "IP4"
 383                 c_address = "156.78.90.1"
 384                 c_addrcount = 0
 385                 c_ttl = 0
 386                 c_next = (nil)
 387         }
 388         s_bw = (nil)
 389         s_time {
 390                 t_start = 2873397496ULL
 391                 t_stop = 2873404696ULL
 392                 t_repeat = (nil)
 393                 t_next = (nil)
 394         }
 395         s_zone = (nil)
 396         s_key = (nil)
 397         s_attr = (nil)
 398         s_media = (nil)
 399 }
 400 .fi
 401 .in -2
 402
 403 .SH ATTRIBUTES
 404 .sp
 405 .LP
 406 See \fBattributes\fR(5) for descriptions of the following attributes:
 407 .sp
 408
 409 .sp
 410 .TS
 411 box;
 412 c | c
 413 l | l .
 414 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 415 _
 416 Interface Stability     Committed
 417 _
 418 MT-Level        Safe
 419 .TE
 420
 421 .SH SEE ALSO
 422 .sp
 423 .LP
 424 \fBlibcommputil\fR(3LIB), \fBsdp_new_session\fR(3COMMPUTIL),
 425 \fBattributes\fR(5)