sdp.docs 3.09 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
@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);
72
@endcode
Pekka Pessi's avatar
Pekka Pessi committed
73 74 75

@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
size_t increment_sdp_version(char buf[], size_t bsize,
83
                             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

  if (sdp_session(parser)) {
    sdp_session_t *sdp = sdp_session(parser);
92

Pekka Pessi's avatar
Pekka Pessi committed
93 94 95 96 97 98 99 100
    sdp->sdp_origin->o_version++;

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

    if (sdp_message(printer)) {
      retval = sdp_message_size(printer);
    }
    else {
101
      fprintf(stderr, "increment_sdp_version: %s\n",
Pekka Pessi's avatar
Pekka Pessi committed
102 103 104 105 106 107
              sdp_printing_error(printer));
    }

    sdp_printer_free(printer);
  }
  else {
108
    fprintf(stderr, "increment_sdp_version: %s\n",
109
            sdp_parsing_error(parser));
Pekka Pessi's avatar
Pekka Pessi committed
110 111 112
  }

  sdp_parser_free(parser);
113

Pekka Pessi's avatar
Pekka Pessi committed
114 115 116 117 118 119 120
  su_home_deinit(home);

  return retval;
}
@endcode

*/