sdp.docs 2.96 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
/* -*- 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
Pekka Pessi's avatar
Pekka Pessi committed
24
structure #sdp_session_t.
Pekka Pessi's avatar
Pekka Pessi committed
25 26 27 28

Typically, the SDP parser is used as follows:

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

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

Pekka Pessi's avatar
Pekka Pessi committed
42 43 44
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
45 46 47
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
@section sdp_printer SDP Printer

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

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

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

Pekka Pessi's avatar
Pekka Pessi committed
75 76 77 78
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
79 80

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

  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

*/