stream/freesdp/parser.h

   1 /*
   2   This file is part of FreeSDP
   3   Copyright (C) 2001,2002,2003 Federico Montesino Pouzols <fedemp@altern.org>
   4
   5   FreeSDP is free software; you can redistribute it and/or modify it
   6   under the terms of the GNU General Public License as published by
   7   the Free Software Foundation; either version 2 of the License, or
   8   (at your option) any later version.
   9
  10   This program is distributed in the hope that it will be useful,
  11   but WITHOUT ANY WARRANTY; without even the implied warranty of
  12   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13   GNU General Public License for more details.
  14
  15   You should have received a copy of the GNU General Public License
  16   along with this program; if not, write to the Free Software
  17   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18
  19   Benjamin Zores, (C) 2006
  20     added support in parser for the a=control: lines.
  21     added support in parser for the a=range: lines.
  22 */
  23
  24 /**
  25  * @file parser.h
  26  * @ingroup parser
  27  * @short Specific public header for parsing module.
  28  **/
  29
  30 #ifndef FSDP_PARSER_H
  31 #define FSDP_PARSER_H
  32
  33 #include "common.h"
  34
  35 BEGIN_C_DECLS
  36 /**
  37  * @defgroup parser FreeSDP Parsing Module
  38  *
  39  * SDP descriptions parsing routines.
  40  * @{
  41  **/
  42 /**
  43  * Parse a SDP description in <code>description</code>, extracting the
  44  * session properties into <code>dsc</code>. These properties can be
  45  * obtained individually later using the <code>fsdp_get_xxxx<code>
  46  * functions.
  47  *
  48  * @param description a multimedia session description formatted in
  49  * SDP.
  50  * @param dsc pointer that is updated to point to a fsdp_description_t
  51  * object. This fsdp_description_t object should have been previously
  52  * allocated using <code>fsdp_description_new()</code>; to free it,
  53  * <code>fsdp_description_delete()</code> should be used.
  54  *
  55  * @return FSDPE_OK when parsing completes successfully. Otherwise,
  56  * another error code is returned.
  57  **/
  58 fsdp_error_t fsdp_parse (const char *description, fsdp_description_t * dsc);
  59
  60 /**
  61  * Get the SDP protocol version of the description.
  62  *
  63  * @return SDP protocol version number.
  64  **/
  65 unsigned int fsdp_get_version (const fsdp_description_t * dsc);
  66
  67 /**
  68  * Get the username provided by the originator of the session.
  69  *
  70  * @param dsc SDP description object.
  71  * @return username of the session owner
  72  **/
  73 const char *fsdp_get_owner_username (const fsdp_description_t * dsc);
  74
  75 /**
  76  * Get the id for the session described in <code>dsc</code>.
  77  *
  78  * @param dsc SDP description object.
  79  * @return id string for this session.
  80  **/
  81 const char *fsdp_get_session_id (const fsdp_description_t * dsc);
  82
  83 /**
  84  * Get the announcement version for the session description in
  85  * <code>dsc</code>.
  86  *
  87  * @param dsc SDP description object.
  88  * @return announcement version string for this description.
  89  **/
  90 const char *fsdp_get_announcement_version (const fsdp_description_t * dsc);
  91
  92 /**
  93  * Get the the type of network the owner of the session described in
  94  * <code>dsc</code> is based on.
  95  *
  96  * @param dsc SDP description object.
  97  * @return network type for the owner of this session.
  98  **/
  99 fsdp_network_type_t
 100 fsdp_get_owner_network_type (const fsdp_description_t * dsc);
 101
 102 /**
 103  * Get the the type of address the owner of the session described in
 104  * <code>dsc</code> is based on.
 105  *
 106  * @param dsc SDP description object.
 107  * @return network address type for the owner of this session.
 108  **/
 109 fsdp_address_type_t
 110 fsdp_get_owner_address_type (const fsdp_description_t * dsc);
 111
 112 /**
 113  * Get the network address of the owner of the session described in
 114  * <code>dsc</code>.
 115  *
 116  * @param dsc SDP description object.
 117  * @return network address for the owner this session.
 118  **/
 119 const char *fsdp_get_owner_address (const fsdp_description_t * dsc);
 120
 121 /**
 122  * Get the name of the session described in <code>dsc</code>.
 123  *
 124  * @param dsc SDP description object.
 125  * @return name of this session.
 126  **/
 127 const char *fsdp_get_name (const fsdp_description_t * dsc);
 128
 129 /**
 130  * Get the information about the session provided in the description
 131  * <code>dsc</code>.
 132  *
 133  * @param dsc SDP description object.
 134  * @return information of this session.
 135  **/
 136 const char *fsdp_get_information (const fsdp_description_t * dsc);
 137
 138 /**
 139  * Get an URI about the session provided in the description
 140  * <code>dsc</code>.
 141  *
 142  * @param dsc SDP description object.
 143  * @return string containing an URI about the session. NULL if the
 144  * session uri is missing.
 145  **/
 146 const char *fsdp_get_uri (const fsdp_description_t * dsc);
 147
 148 /**
 149  * Get the number of emails specified for the session in the description
 150  * <code>dsc</code>.
 151  *
 152  * @param dsc SDP description object.
 153  * @return number of emails.
 154  **/
 155 unsigned int fsdp_get_emails_count (const fsdp_description_t * dsc);
 156
 157 /**
 158  * Get the n-th email specified for the session in the description
 159  * <code>dsc</code>.
 160  *
 161  * @param dsc SDP description object.
 162  * @param index number of URI. Note that this index follows the
 163  * traditional C convention: from 0 to fsdp_get_emails_count() - 1.
 164  * @return string containing an email about the session. NULL if there
 165  * is no such index.
 166  **/
 167 const char *fsdp_get_email (const fsdp_description_t * dsc,
 168                             unsigned int index);
 169
 170 /**
 171  * Get the number of phones specified for the session in the description
 172  * <code>dsc</code>.
 173  *
 174  * @param dsc SDP description object.
 175  * @return number of emails.
 176  **/
 177 unsigned int fsdp_get_phones_count (const fsdp_description_t * dsc);
 178
 179 /**
 180  * Get the n-th phone specified for the session in the description
 181  * <code>dsc</code>.
 182  *
 183  * @param dsc SDP description object.
 184  * @param index number of URI. Note that this index follows the
 185  * traditional C convention: from 0 to fsdp_get_phones_count() - 1.
 186  * @return string containing a phone about the session. NULL if there
 187  * is no such index.
 188  **/
 189 const char *fsdp_get_phone (const fsdp_description_t * dsc,
 190                             unsigned int index);
 191
 192 /**
 193  * Get the the global type of network of the multimedia session
 194  * connection.
 195  *
 196  * @param dsc SDP description object.
 197  * @return global network type for this
 198  * connection. FSDP_NETWORK_TYPE_UNDEFINED if no global network
 199  * address type is included in the description.
 200  **/
 201 fsdp_network_type_t
 202 fsdp_get_global_conn_network_type (const fsdp_description_t * dsc);
 203
 204 /**
 205  * Get the the global type of network address of the multimedia
 206  * session connection.
 207  *
 208  * @param dsc SDP description object.
 209  * @return global network address type for this connection.
 210  * FSDP_ADDRESS_TYPE_UNDEFINED if no global network address type is
 211  * included in the description.
 212  **/
 213 fsdp_address_type_t
 214 fsdp_get_global_conn_address_type (const fsdp_description_t * dsc);
 215
 216 /**
 217  * Get the the global address of the multimedia session connection.
 218  *
 219  * @param dsc SDP description object.
 220  * @return global address for this connection.
 221  **/
 222 const char *fsdp_get_global_conn_address (const fsdp_description_t * dsc);
 223
 224 unsigned int
 225 fsdp_get_global_conn_address_ttl (const fsdp_description_t * dsc);
 226
 227 unsigned int
 228 fsdp_get_global_conn_address_count (const fsdp_description_t * dsc);
 229
 230 /**
 231  * Get the number of bandwidth modifiers specified for this session.
 232  *
 233  * @param dsc SDP description object.
 234  * @return number of bandwidth modifiers.
 235  **/
 236 unsigned int fsdp_get_bw_modifier_count (const fsdp_description_t * dsc);
 237
 238 /**
 239  * Get the bandwidth modifier type for the session.
 240  *
 241  * @param dsc SDP description object.
 242  * @param index number of bandwidth modifier.
 243  *
 244  * @return global bandwidth modifier type.
 245  * @retval FSDP_BW_MOD_TYPE_UNDEFINED if no global bandwith modifier
 246  * type is defined or invalid index.
 247  * @retval FSDP_BW_MOD_TYPE_UNKNOWN if an unknown bandwith modifier is
 248  * specified or an invalid index is provided. In this case
 249  * fsdp_get_bw_modifer_type_unknown() can be called to get the
 250  * modifier as a character string.
 251  **/
 252 fsdp_bw_modifier_type_t
 253 fsdp_get_bw_modifier_type (const fsdp_description_t * dsc,
 254                            unsigned int index);
 255
 256 /**
 257  * Get the textual bandwidth modifier type when it is unknown.
 258  *
 259  * @param dsc SDP description object.
 260  * @param index number of bandwidth modifier.
 261  *
 262  * @return global bandwidth modifier type.
 263  * @retval empty string if the provided bandwidth type is not unknown,
 264  * the provided index is invalid or or there was a parse error.
 265  **/
 266 const char *fsdp_get_bw_modifier_type_unknown (const fsdp_description_t * dsc,
 267                                                unsigned int index);
 268
 269 /**
 270  * Get the value for the bandwidth modifier.
 271  *
 272  * @param dsc SDP description object.
 273  * @param index number of bandwidth modifier.
 274  * @return global bandwidth value.
 275  * @retval 0 if no bandwidth is specified for this session or an
 276  * invalid index has been provided.
 277  **/
 278 unsigned long int
 279 fsdp_get_bw_value (const fsdp_description_t * dsc, unsigned int index);
 280
 281 /**
 282  * Get the number of time periods specified for this session
 283  *
 284  * @param dsc SDP description object.
 285  * @return number of time periods
 286  **/
 287 unsigned long int fsdp_get_period_count (const fsdp_description_t * dsc);
 288
 289 /**
 290  * Get the start time for the period selected by index.
 291  *
 292  * @param dsc SDP description object.
 293  * @param index number of time period. Note that this index follows the
 294  * traditional C convention: from 0 to fsdp_get_period_count() - 1.
 295  * @return start time
 296  * @retval 0 if an invalid index is provided.
 297  **/
 298 time_t
 299 fsdp_get_period_start (const fsdp_description_t * dsc, unsigned int index);
 300
 301 /**
 302  * Get the stop time for the period selected by index.
 303  *
 304  * @param dsc SDP description object.
 305  * @param index number of time period. Note that this index follows the
 306  * traditional C convention: from 0 to fsdp_get_period_count() - 1.
 307  * @return stop time
 308  * @retval 0 if an invalid index is provided.
 309  **/
 310 time_t
 311 fsdp_get_period_stop (const fsdp_description_t * dsc, unsigned int index);
 312
 313 /**
 314  * Get the number of repeats for the period selected by index.
 315  *
 316  * @param dsc SDP description object.
 317  * @param index number of the period. Note that this index follows the
 318  * traditional C convention: from 0 to fsdp_get_period_count() - 1.
 319  * @return number of repeats
 320  * @retval 0 if an invalid index is provided.
 321  **/
 322 unsigned int
 323 fsdp_get_period_repeats_count (const fsdp_description_t * dsc,
 324                                unsigned int index);
 325
 326 /**
 327  * Get the interval time of the repeat selected by rindex for the
 328  * period selected by index.
 329  *
 330  * @param dsc SDP description object.
 331  * @param index number of time period. Note that this index follows the
 332  * traditional C convention: from 0 to fsdp_get_period_count() - 1.
 333  * @param rindex number of repeat
 334  * @return interval time
 335  * @retval 0 if an invalid index is provided.
 336  **/
 337 unsigned long int
 338 fsdp_get_period_repeat_interval (const fsdp_description_t * dsc,
 339                                  unsigned int index, unsigned int rindex);
 340
 341 /**
 342  * Get the duration of the repeat selected by rindex for the period
 343  * selected by index.
 344  *
 345  * @param dsc SDP description object.
 346  * @param index number of time period. Note that this index follows the
 347  * traditional C convention: from 0 to fsdp_get_period_count() - 1.
 348  * @param rindex number of repeat
 349  * @return duration
 350  * @retval 0 if an invalid index is provided.
 351  **/
 352 unsigned long int
 353 fsdp_get_period_repeat_duration (const fsdp_description_t * dsc,
 354                                  unsigned int index, unsigned int rindex);
 355
 356 /**
 357  * Get the offsets of the repeat selected by rindex for the period
 358  * selected by index.
 359  *
 360  * @param dsc SDP description object.
 361  * @param index number of time period. Note that this index follows the
 362  * traditional C convention: from 0 to fsdp_get_period_count() - 1.
 363  * @param rindex number of repeat
 364  * @return array of offsets
 365  * @retval NULL if an invalid index is provided.
 366  **/
 367 const unsigned long int *fsdp_get_period_repeat_offsets (const
 368                                                          fsdp_description_t *
 369                                                          dsc,
 370                                                          unsigned int index,
 371                                                          unsigned int rindex);
 372
 373 /**
 374  * Get the encryption method defined for this session.
 375  *
 376  * @param dsc SDP description object.
 377  * @return encryption method. FSDP_ENCRYPTION_METHOD_UNDEFINED if no
 378  * encryption method is specified.
 379  **/
 380 fsdp_encryption_method_t
 381 fsdp_get_encryption_method (const fsdp_description_t * dsc);
 382
 383 /**
 384  * Get the encryption key or a URI pointing to the encryption key for
 385  * this session.
 386  *
 387  * @param dsc SDP description object.
 388  * @return encryption key unless FSDP_ENCRYPTION_METHOD_URI is
 389  * specified, in which case a URI pointing to the key is returned. If
 390  * the global encryption method is undefined, NULL is returned.
 391  **/
 392 const char *fsdp_get_encryption_content (const fsdp_description_t * dsc);
 393
 394 /**
 395  * Get timezone adjustments.
 396  *
 397  * @param dsc SDP description object.
 398  * @return string with list of timezone adjustments
 399  * @retval NULL if no timezone adjustment list was specified or there
 400  * was a parse error.
 401  **/
 402 const char *fsdp_get_timezone_adj (const fsdp_description_t * dsc);
 403
 404 /**
 405  *
 406  **/
 407 unsigned int
 408 fsdp_get_unidentified_attribute_count (const fsdp_description_t * dsc);
 409
 410 /**
 411  *
 412  **/
 413 const char *fsdp_get_unidentified_attribute (const fsdp_description_t * dsc,
 414                                              unsigned int index);
 415
 416 /**
 417  *
 418  **/
 419 unsigned int
 420 fsdp_get_media_rtpmap_count (const fsdp_media_description_t * mdsc);
 421
 422 /**
 423  *
 424  **/
 425 const char *fsdp_get_media_rtpmap_payload_type (const fsdp_media_description_t
 426                                                 * mdsc, unsigned int index);
 427
 428 /**
 429  *
 430  **/
 431 const char *fsdp_get_media_rtpmap_encoding_name (const
 432                                                  fsdp_media_description_t *
 433                                                  mdsc, unsigned int index);
 434
 435 /**
 436  *
 437  **/
 438 unsigned int
 439 fsdp_get_media_rtpmap_clock_rate (const fsdp_media_description_t * mdsc,
 440                                   unsigned int index);
 441
 442 /**
 443  *
 444  **/
 445 const char *fsdp_get_media_rtpmap_encoding_parameters (const
 446                                                        fsdp_description_t *
 447                                                        mdsc,
 448                                                        unsigned int index);
 449
 450 /**
 451  * Get the value of the session attribute specified in
 452  * <code>att</code>. This function works for all the session
 453  * attributes whose value is a character string. These attributes are
 454  * defined in the session_string_attribute_t enumerated type.
 455  *
 456  * @param dsc SDP description object.
 457  * @param att attribute to get.
 458  *
 459  * @return value of the attribute <code>att</code>.
 460  * @retval NULL if the attribute was not specified or there was a
 461  * parse error or an invalid att is given.
 462  **/
 463 const char *fsdp_get_str_att (const fsdp_description_t * dsc,
 464                               fsdp_session_str_att_t att);
 465
 466 /**
 467  *
 468  **/
 469 unsigned int fsdp_get_sdplang_count (const fsdp_description_t * dsc);
 470
 471 /**
 472  *
 473  **/
 474 const char *fsdp_get_sdplang (const fsdp_description_t * dsc,
 475                               unsigned int index);
 476
 477 /**
 478  * Get the mode of the conference, specified with attributes sendrecv,
 479  * sendonly, recvonly and inactive.
 480  *
 481  * @param dsc SDP description object.
 482  * @return send/rec conference mode.
 483  * @retval FSDP_SENDRECV_UNDEFINED if conference mode not provided.
 484  **/
 485 fsdp_sendrecv_mode_t fsdp_get_sendrecv_mode (const fsdp_description_t * dsc);
 486
 487 /**
 488  * Get the type of conference, such as broadcast, meeting, moderated,
 489  * test or H332.
 490  *
 491  * @param dsc SDP description object.
 492  * @return conference type.
 493  * @retval FSDP_SESSION_TYPE_UNDEFINED if conference type not provided.
 494  **/
 495 fsdp_session_type_t fsdp_get_session_type (const fsdp_description_t * dsc);
 496
 497 /**
 498  *
 499  **/
 500 unsigned int fsdp_get_media_count (const fsdp_description_t * dsc);
 501
 502 /**
 503  *
 504  **/
 505 const fsdp_media_description_t *fsdp_get_media (const fsdp_description_t *
 506                                                 dsc, unsigned int index);
 507
 508 /**
 509  *
 510  **/
 511 fsdp_media_t fsdp_get_media_type (const fsdp_media_description_t * dsc);
 512
 513 /**
 514  *
 515  **/
 516 unsigned int fsdp_get_media_port (const fsdp_media_description_t * dsc);
 517
 518 unsigned int fsdp_get_media_port_count (const fsdp_media_description_t * dsc);
 519
 520 /**
 521  *
 522  **/
 523 fsdp_transport_protocol_t
 524 fsdp_get_media_transport_protocol (const fsdp_media_description_t * dsc);
 525
 526 /**
 527  *
 528  **/
 529 const char *fsdp_get_media_formats (const fsdp_media_description_t * dsc);
 530
 531 /**
 532  *
 533  **/
 534 unsigned int
 535 fsdp_get_media_formats_count (const fsdp_media_description_t * dsc);
 536
 537 /**
 538  *
 539  **/
 540 const char *fsdp_get_media_format (const fsdp_media_description_t * dsc,
 541                                    unsigned int index);
 542
 543 /**
 544  *
 545  **/
 546 const char *fsdp_get_media_title (const fsdp_media_description_t * dsc);
 547
 548 /**
 549  *
 550  **/
 551 fsdp_network_type_t
 552 fsdp_get_media_network_type (const fsdp_media_description_t * dsc);
 553
 554 /**
 555  *
 556  **/
 557 fsdp_address_type_t
 558 fsdp_get_media_address_type (const fsdp_media_description_t * dsc);
 559
 560 /**
 561  *
 562  **/
 563 const char *fsdp_get_media_address (const fsdp_media_description_t * dsc);
 564
 565 unsigned int
 566 fsdp_get_media_address_ttl (const fsdp_media_description_t * mdsc);
 567
 568 unsigned int
 569 fsdp_get_media_address_count (const fsdp_media_description_t * mdsc);
 570
 571 /**
 572  *
 573  **/
 574 fsdp_bw_modifier_type_t
 575 fsdp_get_media_bw_modifier_type (const fsdp_media_description_t * dsc,
 576                                  unsigned int index);
 577
 578 /**
 579  *
 580  **/
 581 const char *fsdp_get_media_bw_modifier_type_unknown (const
 582                                                      fsdp_media_description_t
 583                                                      * dsc,
 584                                                      unsigned int index);
 585
 586 /**
 587  *
 588  **/
 589 unsigned long int
 590 fsdp_get_media_bw_value (const fsdp_media_description_t * dsc,
 591                          unsigned int index);
 592
 593 /**
 594  *
 595  **/
 596 fsdp_encryption_method_t
 597 fsdp_get_media_encryption_method (const fsdp_media_description_t * dsc);
 598
 599 /**
 600  *
 601  **/
 602 const char *fsdp_get_media_encryption_content (const fsdp_media_description_t
 603                                                * dsc);
 604
 605 /**
 606  *
 607  **/
 608 unsigned int fsdp_get_media_ptime (const fsdp_media_description_t * dsc);
 609
 610 /**
 611  *
 612  **/
 613 unsigned int fsdp_get_media_maxptime (const fsdp_media_description_t * dsc);
 614
 615 /**
 616  *
 617  **/
 618 unsigned int
 619 fsdp_get_media_fmtp_count (const fsdp_media_description_t * mdsc);
 620
 621 /**
 622  *
 623  **/
 624 const char *fsdp_get_media_fmtp (const fsdp_media_description_t * mdsc,
 625                                  unsigned int index);
 626
 627 /**
 628  *
 629  **/
 630 unsigned int
 631 fsdp_get_media_sdplang_count (const fsdp_media_description_t * dsc);
 632
 633 /**
 634  *
 635  **/
 636 const char *fsdp_get_media_sdplang (const fsdp_media_description_t * dsc,
 637                                     unsigned int index);
 638
 639 /**
 640  *
 641  **/
 642 unsigned int fsdp_get_media_lang_count (const fsdp_media_description_t * dsc);
 643
 644 /**
 645  *
 646  **/
 647 const char *fsdp_get_media_lang (const fsdp_media_description_t * dsc,
 648                                  unsigned int index);
 649
 650
 651 unsigned int fsdp_get_control_count (const fsdp_description_t * dsc);
 652
 653 const char *fsdp_get_control (const fsdp_description_t * dsc,
 654                               unsigned int index);
 655
 656 const char *fsdp_get_range (const fsdp_description_t * dsc);
 657
 658 unsigned int
 659 fsdp_get_media_control_count (const fsdp_media_description_t * mdsc);
 660
 661 char *fsdp_get_media_control (const fsdp_media_description_t * mdsc,
 662                               unsigned int index);
 663
 664 char *fsdp_get_media_range (const fsdp_media_description_t * mdsc);
 665
 666 /**
 667  *
 668  **/
 669 fsdp_orient_t fsdp_get_media_orient (const fsdp_media_description_t * dsc);
 670
 671 /**
 672  *
 673  **/
 674 fsdp_sendrecv_mode_t
 675 fsdp_get_media_sendrecv (const fsdp_media_description_t * dsc);
 676
 677 /**
 678  *
 679  **/
 680 float fsdp_get_media_framerate (const fsdp_media_description_t * dsc);
 681
 682 /**
 683  *
 684  **/
 685 unsigned int fsdp_get_media_quality (const fsdp_media_description_t * dsc);
 686
 687 /**
 688  *
 689  **/
 690 unsigned int fsdp_get_media_rtcp_port (const fsdp_media_description_t * dsc);
 691
 692 /**
 693  *
 694  **/
 695 fsdp_network_type_t
 696 fsdp_get_media_rtcp_network_type (const fsdp_media_description_t * dsc);
 697
 698 /**
 699  *
 700  **/
 701 fsdp_address_type_t
 702 fsdp_get_media_rtcp_address_type (const fsdp_media_description_t * dsc);
 703
 704 /**
 705  *
 706  **/
 707 const char *fsdp_get_media_rtcp_address (const fsdp_media_description_t *
 708                                          dsc);
 709
 710 /**
 711  *
 712  **/
 713 unsigned int
 714 fsdp_get_media_unidentified_attribute_count (const fsdp_media_description_t
 715                                              * mdsc);
 716
 717 /**
 718  *
 719  **/
 720 const char *fsdp_get_media_unidentified_attribute (const
 721                                                    fsdp_media_description_t *
 722                                                    mdsc, unsigned int index);
 723
 724
 725           /** @} *//* closes parser group */
 726
 727 END_C_DECLS
 728 #endif /* FSDP_PARSER_H */