Commit 900ad089 authored by Pekka Pessi's avatar Pekka Pessi

sdp: updated documentation.

darcs-hash:20060914131342-65a35-470b7e8a934b647912a3639fc7355c4d042e4a64.gz
parent ddb12ded
......@@ -1537,7 +1537,7 @@ sdp_mode_t sdp_attribute_mode(sdp_attribute_t const *a, sdp_mode_t defmode)
return defmode;
}
/** Get session mode from attribute list. */
/** Convert session mode as #sdp_attribute_t structure. */
sdp_attribute_t *sdp_attribute_by_mode(su_home_t *home, sdp_mode_t mode)
{
sdp_attribute_t *a;
......@@ -1563,12 +1563,20 @@ sdp_attribute_t *sdp_attribute_by_mode(su_home_t *home, sdp_mode_t mode)
/** Find a mapped attribute.
*
* A mapped attribute has form 'a=<name>:<pt> <value>' where pt is a RTP payload type,
* integer in range 0..127.
* A mapped attribute has form 'a=<name>:<pt> <value>' where pt is a RTP
* payload type, integer in range 0..127. For example, "a=atmmap" [@RFC3108]
* is a mapped attribute. Note that common mapped attributes, "a=rtpmap" and
* "a=fmtp" are already parsed as list of #sdp_rtpmap_t in #sdp_media_t.
*
* @param a pointer to first attribute in the list
* @param name name of the attribute
* @param pt payload type number (must be 0..127)
* @param return_result return value parameter for mapped attribute value
*
* @return Pointer to a matching attribute structure, or NULL.
*
* @return Pointer to a matching attribute structure, or NULL. If a matching
* attribute is found, @a return_result will point to part of the attribute
* after the payload type and whitespace.
* If a matching attribute is found, @a return_result will point to part of
* the attribute after the payload type and whitespace.
*/
sdp_attribute_t *sdp_attribute_mapped_find(sdp_attribute_t const *a,
char const *name,
......
......@@ -21,12 +21,12 @@ Contributor(s):
@section sdp_parser SDP Parser
SDP parser parses an SDP message and converts it to internally used SDP
datatypes.
structure #sdp_session_t.
Typically, the SDP parser is used as follows:
@code
sdp_parser parser = sdp_parse(home, message, len, 0);
sdp_parser_t *parser = sdp_parse(home, message, len, 0);
if (!sdp_session(parser)) {
show(sdp_parsing_error(parser));
......@@ -39,27 +39,25 @@ Typically, the SDP parser is used as follows:
sdp_parser_free(parser);
@endcode
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
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
configuration files when using flag #sdp_f_config. The parser will then
accept * for media, protocol and port, for instance.
@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.
SDP printer converts internally used SDP structure #sdp_session_t 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);
sdp_printer_t *printer = sdp_print(home, session, buffer, sizeof(buffer), 0);
if (sdp_message(printer)) {
char const *msg = sdp_message(printer);
int msgsize = sdp_message_size(printer);
size_t msgsize = sdp_message_size(printer);
@endcode
At this point, application can use the SDP message contents, e.g., it can
......@@ -74,19 +72,19 @@ send them to network, and then free the message:
@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.
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.
@code
int increment_sdp_version(char buf[], int bsize,
char const *original, int osize)
size_t increment_sdp_version(char buf[], size_t bsize,
char const *original, size_t 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;
size_t retval = 0;
if (sdp_session(parser)) {
sdp_session_t *sdp = sdp_session(parser);
......
......@@ -45,6 +45,18 @@
#include "sofia-sip/sdp.h"
/** @typedef struct sdp_parser_s sdp_parser_t;
*
* SDP parser handle.
*
* The SDP parser handle is returned by sdp_parse(). It contains either
* successfully parse SDP session #sdp_session_t or an error message.
* If sdp_session() returns non-NULL, parsing was successful.
*
* @sa #sdp_session_t, sdp_parse(), sdp_session(), sdp_parsing_error(),
* sdp_sanity_check(), sdp_parser_home(), sdp_parser_free().
*/
struct sdp_parser_s {
su_home_t pr_home[1];
union {
......@@ -91,23 +103,31 @@ static void parsing_error(sdp_parser_t *p, char const *fmt, ...);
*
* The function sdp_parse() parses an SDP message @a msg of size @a
* msgsize. Parsing is done according to the given @a flags. The SDP message
* may not contain a @c NUL.
* may not contain a NUL.
*
* The parsing result is stored to an @c sdp_session_t structure.
* The parsing result is stored to an #sdp_session_t structure.
*
* @param home memory home
* @param msg pointer to message
* @param msgsize size of the message (excluding final NUL, if any)
* @param flags flags affecting the parsing.
*
* The following flags are defined:
* The following flags are used by parser:
*
* @li @c sdp_f_strict Parser should accept only messages conforming strictly
* to the specification.
* @li @c sdp_f_anynet Parser accepts unknown network or address types.
* @li #sdp_f_strict Parser should accept only messages conforming strictly
* to the specification.
* @li #sdp_f_anynet Parser accepts unknown network or address types.
* @li #sdp_f_insane Do not run sanity check.
* @li #sdp_f_c_missing Sanity check does not require c= for each m= line
* @li #sdp_f_mode_0000 Parser regards "c=IN IP4 0.0.0.0" as "a=inactive"
* (likewise with c=IN IP6 ::)
* @li #sdp_f_mode_manual Do not generate or parse SDP mode
* @li #sdp_f_config Parse config files (any line can be missing)
*
* @return
* The function sdp_parse() returns always a valid parser handle.
* Always a valid parser handle.
*
* @todo Parser accepts some non-conforming SDP even with #sdp_f_strict.
*/
sdp_parser_t *
sdp_parse(su_home_t *home, char const msg[], int msgsize, int flags)
......@@ -169,13 +189,13 @@ su_home_t *sdp_parser_home(sdp_parser_t *parser)
*
* The function sdp_session() returns a pointer to the SDP session
* structure associated with the SDP parser @a p. The pointer and all the
* data in the structure are valid until @c sdp_parser_free() is called.
* data in the structure are valid until sdp_parser_free() is called.
*
* @param p SDP parser
*
* @return
* The function sdp_session() returns a pointer to an parsed SDP message
* or @c NULL, if an error has occurred. */
* or NULL, if an error has occurred. */
sdp_session_t *
sdp_session(sdp_parser_t *p)
{
......@@ -191,7 +211,7 @@ sdp_session(sdp_parser_t *p)
*
* @return
* The function sdp_parsing_error() returns a C string describing parsing
* error, or @c NULL if no error occurred.
* error, or NULL if no error occurred.
*/
char const *sdp_parsing_error(sdp_parser_t *p)
{
......@@ -508,7 +528,7 @@ static void post_session(sdp_parser_t *p, sdp_session_t *sdp)
/** Validates that all mandatory fields exist
*
* Checks that all necessary fields (v=, o=) exists in the given sdp. If
* Checks that all necessary fields (v=, o=) exists in the parsed sdp. If
* strict, check that all mandatory fields (c=, o=, s=, t=) are present.
* This function also goes through all media, marks rejected media as such,
* and updates the mode accordingly.
......@@ -1024,8 +1044,6 @@ static void parse_repeat(sdp_parser_t *p, char *d, sdp_repeat_t **result)
* r - pointer to record data
* result - pointer to which parsed record is assigned
*
* Note:
* This is unimplemented!
*/
static void parse_zone(sdp_parser_t *p, char *r, sdp_zone_t **result)
{
......@@ -1100,8 +1118,6 @@ static void parse_zone(sdp_parser_t *p, char *r, sdp_zone_t **result)
* r - pointer to record data
* result - pointer to which parsed record is assigned
*
* Note:
* This function is unimplemented!
*/
static void parse_key(sdp_parser_t *p, char *r, sdp_key_t **result)
{
......@@ -1402,6 +1418,8 @@ static sdp_rtpmap_t const
*
* The table of reserved payload numbers is constructed from @RFC3551
* and @RFC1890. Note the clock rate of G722.
*
* Use sdp_rtpmap_dup() to copy these structures.
*/
sdp_rtpmap_t const * const sdp_rtpmap_well_known[128] =
{
......
......@@ -54,6 +54,14 @@
typedef unsigned longlong ull;
/** @typedef struct sdp_printer_s sdp_printer_t
*
* SDP printer handle.
*
* @sa #sdp_session_t, sdp_print(), sdp_printing_error(),
* sdp_message(), sdp_message_size(), sdp_printer_free()
*/
struct sdp_printer_s {
int pr_size;
su_home_t *pr_home;
......@@ -82,8 +90,8 @@ static void print_session(sdp_printer_t *p, sdp_session_t const *session);
/** Print a SDP description.
*
* The function sdp_print() encodes the contents of the SDP session
* structure to the @a msgbuf. The @a msgbuf has size @a msgsize
* Encode the contents of the SDP session structure #sdp_session_t
* to the @a msgbuf. The @a msgbuf has size @a msgsize
* bytes. If @a msgbuf is @c NULL, the sdp_print() function allocates the
* required buffer from the @a home heap.
*
......@@ -102,16 +110,19 @@ static void print_session(sdp_printer_t *p, sdp_session_t const *session);
* small for the resulting SDP message, @c sdp_print() may allocate a new
* buffer for it from the heap.
*
* @li #sdp_f_prefix - The buffer provided by caller already contains valid
* data. The function sdp_print() will concatenate its result to the buffer.
* @li #sdp_f_print_prefix - The buffer provided by caller already contains
* valid data. The result will concatenated to the string in the buffer.
*
* @li #sdp_f_mode_always - Always add mode attributes to media
*
* @li #sdp_f_mode_manual - Do not generate mode attributes
*
* @return
* The function sdp_print() always returns a handle to an sdp_printer_t
* object.
* Always return a handle to an #sdp_printer_t object.
*
* @sa #sdp_printer_t, #sdp_session_t, sdp_printing_error(),
* sdp_message(), sdp_message_size(), sdp_printer_free(),
* sdp_parse().
*/
sdp_printer_t *sdp_print(su_home_t *home,
sdp_session_t const *session,
......@@ -153,15 +164,14 @@ sdp_printer_t *sdp_print(su_home_t *home,
/** @brief Get encoding error.
*
* The function sdp_printing_error() returns a message describing
* encoding error.
* Return a message describing the encoding error.
*
* @param p Pointer to an @c sdp_printer_t object.
* @param p Pointer to an #sdp_printer_t object.
*
* @return
* The function sdp_printing_error() returns a pointer to C string
* descibing printing errors, or @c NULL if no error were
* encountered. */
* Return a pointer to C string describing printing errors, or NULL if no
* error was encountered.
*/
char const *sdp_printing_error(sdp_printer_t *p)
{
if (p)
......@@ -175,14 +185,13 @@ char const *sdp_printing_error(sdp_printer_t *p)
/** @brief Get encoded SDP message.
*
* The function sdp_message() returns a pointer to a C string containing
* the SDP message
* Return a pointer to a C string containing the SDP message.
*
* @param p Pointer to an @c sdp_printer_t object.
* @param p Pointer to an #sdp_printer_t object.
*
* @return
* The function sdp_message() returns a pointer to a C string
* containing the emitted SDP message, or @c NULL upon an error.
* Return a pointer to a C string containing the encoded SDP message, or
* NULL upon an error.
*/
char const *sdp_message(sdp_printer_t *p)
{
......@@ -194,14 +203,12 @@ char const *sdp_message(sdp_printer_t *p)
/** @brief Get size of encoded SDP message.
*
* The function sdp_message_size() returns the size of the emitted SDP
* message.
* Return the size of the encoded SDP message.
*
* @param p Pointer to an @c sdp_printer_t object.
* @param p Pointer to an #sdp_printer_t object.
*
* @return
* The function sdp_message_size() returns number of bytes in SDP
* message or @c 0 upon an error.
* Number of bytes in SDP message excluding final NUL or 0 upon an error.
*/
isize_t sdp_message_size(sdp_printer_t *p)
{
......@@ -213,10 +220,10 @@ isize_t sdp_message_size(sdp_printer_t *p)
/** Free a SDP printer.
*
* The function sdp_printer_free() frees the printer object @a p and the
* message buffer possibly associated with it.
* Free the printer object @a p and the message buffer possibly associated
* with it.
*
* @param p Pointer to an @c sdp_printer_t object.
* @param p Pointer to an #sdp_printer_t object.
*/
void sdp_printer_free(sdp_printer_t *p)
{
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment