sdp.docs 3.1 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2
/* -*- c -*- */

3
/**@MODULEPAGE "sdp" - SDP Module
Pekka Pessi's avatar
Pekka Pessi committed
4 5 6

@section sdp_meta Module Meta Information

7 8 9 10
The @b sdp module provides a simple "C" parser interface for SDP [@RFC2327],
<em>Session Description Protocol</em>. The parser also implements support
for IPv6 addresses as per @RFC3266. The @RFC4566 should be supported, but we
have not checked since draft-eitf-mmusic-sdp-new-17 or so.
Pekka Pessi's avatar
Pekka Pessi committed
11 12 13

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

14
@STATUS @SofiaSIP Core library
Pekka Pessi's avatar
Pekka Pessi committed
15 16 17 18 19 20 21 22 23 24

@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
25
structure #sdp_session_t.
Pekka Pessi's avatar
Pekka Pessi committed
26 27 28 29

Typically, the SDP parser is used as follows:

@code
30
 sdp_parser_t *parser = sdp_parse(home, message, len, 0);
Pekka Pessi's avatar
Pekka Pessi committed
31

32
 if (!sdp_session(parser)) {
Pekka Pessi's avatar
Pekka Pessi committed
33 34 35 36 37 38 39 40 41 42
   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

43 44 45
There are various flags indicating what kind of SDP variants the sdp_parse()
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
46 47 48
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
49 50
@section sdp_printer SDP Printer

51 52
SDP printer converts internally used SDP structure #sdp_session_t to the
standard SDP format.
Pekka Pessi's avatar
Pekka Pessi committed
53 54 55 56

Typically, the SDP printer is used as follows:
@code
 char buffer[512];
57
 sdp_printer_t *printer = sdp_print(home, session, buffer, sizeof(buffer), 0);
Pekka Pessi's avatar
Pekka Pessi committed
58

59
 if (sdp_message(printer)) {
Pekka Pessi's avatar
Pekka Pessi committed
60
   char const *msg = sdp_message(printer);
61
   size_t msgsize = sdp_message_size(printer);
Pekka Pessi's avatar
Pekka Pessi committed
62 63 64 65 66 67 68 69 70 71 72 73 74 75
@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

76 77 78 79
Examples on using SDP parser can be found from test_sdp.c and soa.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.
Pekka Pessi's avatar
Pekka Pessi committed
80 81

@code
82 83
size_t increment_sdp_version(char buf[], size_t bsize, 
                             char const *original, size_t osize)
Pekka Pessi's avatar
Pekka Pessi committed
84 85 86 87
{
  su_home_t home[1] = { SU_HOME_INIT(home) };
  sdp_parser_t *parser = sdp_parse(home, original, osize, 0);
  sdp_printer_t *printer;
88
  size_t retval = 0;
Pekka Pessi's avatar
Pekka Pessi committed
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

  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

*/