sdp.docs 2.98 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
/* -*- c -*- */

/**@mainpage SDP Module

@section sdp_meta Module Meta Information

The @b sdp module provides a simple "C" parser interface for SDP 
[<a href="ftp://ftp.funet.fi/rfc/rfc2327.txt">RFC2327</a>], <em>Session
Description Protocol</em>.

@CONTACT Pekka Pessi <Pekka.Pessi@nokia.com>

@STATUS Core library

@LICENSE LGPL

Contributor(s):
- Pekka Pessi <Pekka.Pessi@nokia.com>
- Jari Selin <Jari.Selin@nokia.com>

@section sdp_parser SDP Parser

SDP parser parses an SDP message and converts it to internally used SDP
datatypes.

Typically, the SDP parser is used as follows:

@code
 sdp_parser parser = sdp_parse(home, message, len, 0);

31
 if (!sdp_session(parser)) {
Pekka Pessi's avatar
Pekka Pessi committed
32 33 34 35 36 37 38 39 40 41
   show(sdp_parsing_error(parser));
 } else {
   sdp_session_t *sdp = sdp_session(parser);
@endcode
  Act upon session description, then free the parser:
@code
 }
 sdp_parser_free(parser);
@endcode

42 43 44 45 46 47
There are various flags indicating what kind of SDP variants parser accepts. 
The sanity check run after parsing can be disabled by including flag
#sdp_f_insane. The parser can be used to parse syntactically vague
configuration files when using flag #sdp_f_config. The parser will then
accept * for media, protocol and port, for instance.

Pekka Pessi's avatar
Pekka Pessi committed
48 49 50 51 52 53 54 55 56 57 58 59
@todo strict (parser accepts some non-conforming SDP even with strict)

@section sdp_printer SDP Printer

SDP printer converts internally used SDP datatypes to the standard SDP
format.

Typically, the SDP printer is used as follows:
@code
 char buffer[512];
 sdp_printer printer = sdp_print(home, session, buffer, sizeof(buffer), 0);

60
 if (sdp_message(printer)) {
Pekka Pessi's avatar
Pekka Pessi committed
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121
   char const *msg = sdp_message(printer);
   int  msgsize = sdp_message_size(printer);
@endcode

At this point, application can use the SDP message contents, e.g., it can
send them to network, and then free the message:
@code
 }
 else {
   show_critical_error(sdp_printing_error(printer));
 }
 sdp_printer_free(printer);
@endcode 

@section sdp_example Example

Examples on using SDP parser can be found from @b sdp_test.c and @b
nua.c. Here is an simple example, which decodes an SDP text in @a
original, increments the version number in the origin line, and encodes
the SDP description again to @a buf.

@code
int increment_sdp_version(char buf[], int bsize, 
                          char const *original, int osize)
{
  su_home_t home[1] = { SU_HOME_INIT(home) };
  sdp_parser_t *parser = sdp_parse(home, original, osize, 0);
  sdp_printer_t *printer;
  int retval = 0;

  if (sdp_session(parser)) {
    sdp_session_t *sdp = sdp_session(parser);
    
    sdp->sdp_origin->o_version++;

    printer = sdp_print(home, sdp, buf, bsize, 0);

    if (sdp_message(printer)) {
      retval = sdp_message_size(printer);
    }
    else {
      fprintf(stderr, "increment_sdp_version: %s\n", 
              sdp_printing_error(printer));
    }

    sdp_printer_free(printer);
  }
  else {
    fprintf(stderr, "increment_sdp_version: %s\n", 
            sdp_parsing_error(p));
  }

  sdp_parser_free(parser);
      
  su_home_deinit(home);

  return retval;
}
@endcode

*/