Commit 9b862547 authored by Pekka Pessi's avatar Pekka Pessi

Documentation fixes.

darcs-hash:20051027164056-65a35-f9cf1fb0fa8c285ccf657ba0a4b0019a45a3536f.gz
parent 79d8f9f9
......@@ -20,7 +20,9 @@ TAGFILES += ../docs/sresolv/doxytags=../sresolv
TAGFILES += ../docs/stun/doxytags=../stun
TAGFILES += ../docs/tport/doxytags=../tport
TAGFILES += ../docs/nta/doxytags=../nta
TAGFILES += ../docs/iptsec/doxytags=../iptsec
TAGFILES += ../docs/sdp/doxytags=../sdp
TAGFILES += ../docs/nua/doxytags=../mss
ALIASES +=
TAGFILES += ../docs/soa/doxytags=../soa
TAGFILES += ../docs/nea/doxytags=../nea
TAGFILES += ../docs/nua/doxytags=../nua
TAGFILES += ../docs/features/doxytags=../features
......@@ -13,22 +13,22 @@ ALIASES = \
"CONTACT=\par Contact:\n" \
"STATUS=\par Status:\n" \
"LICENSE=\par License:\n" \
"DEF=\hideinitializer\n \def" \
"DEF=\def" \
"TAGS=\par Related Tags:\n" \
"TAG=\par \n" \
"EVENTS=\par Events:\n" \
"RESPONSES=\par Related Response Codes:\n" \
"CFILE=\file" \
"IFILE=\file" \
"HI=\hideinitializer\n" \
"HIDE=\hideinitializer\n" \
"SHOW=\showinitializer\n" \
"HI=\hideinitializer " \
"HIDE=\hideinitializer " \
"SHOW=\showinitializer " \
"LGPL2=\par Lesser GNU Public License Version 2:\n \ref lgpl2\n \if 0\n" \
"ENDLGPL2=\endif \n" \
"GPL2=\par GNU Public License Version 2:\n \ref gpl2\n \if 0\n" \
"ENDGPL2=\endif \n" \
"ERRORS=\par Errors:\n" \
"ERROR=\par \n\b " \
"ERRORS=\par Errors: " \
"ERROR=\par \n \b " \
"RFC2000=<a href="http://www.faqs.org/rfcs/rfc2000.html">RFC 2000</a>" \
"RFC2001=<a href="http://www.faqs.org/rfcs/rfc2001.html">RFC 2001</a>" \
"RFC2002=<a href="http://www.faqs.org/rfcs/rfc2002.html">RFC 2002</a>" \
......@@ -2229,4 +2229,3 @@ ALIASES = \
"RFC4197=<a href="http://www.faqs.org/rfcs/rfc4197.html">RFC 4197</a>" \
"RFC4198=<a href="http://www.faqs.org/rfcs/rfc4198.html">RFC 4198</a>" \
"RFC4199=<a href="http://www.faqs.org/rfcs/rfc4199.html">RFC 4199</a>"
......@@ -32,23 +32,28 @@ Or post to the Sofia-SIP mailing list:
@section subdirs Directory Structure
Terminal and high-level libraries utilizing for both signaling and media:
- <a href=nua/index.html>"nua" - SIP User Agent library</a>
- <a href="nua/index.html">"nua" - SIP User Agent library</a>
Common runtime library:
- <a href=su/index.html>"su" - sockets, memory management, threads</a>
Signaling subsystem:
- <a href=nea/index.html>"nea" - Event API</a>
- <a href=nta/index.html>"nta" - SIP transaction engine</a>
- <a href=sresolv/index.html>"sresolv" - Asynchronous DNS resolver</a>
- <a href=tport/index.html>"tport" - Message transport</a>
- <a href=sip/index.html>"sip" - SIP messages and headers</a>
- <a href=msg/index.html>"msg" - Message handling </a>
- <a href=ipt/index.html>"ipt" - IPT utility library</a>
- <a href=nth/index.html>"nth" - HTTP protocol engine</a>
- <a href=http/index.html>"http" - HTTP messages and headers</a>
- <a href=sdp/index.html>"sdp" - SDP parser</a>
- <a href=soa/index.html>"soa" - SIP Offer/answer engine</a>
- <a href="su/index.html">"su" - sockets, memory management, threads</a>
SIP Signaling:
- <a href="nea/index.html">"nea" - SIP Event API</a>
- <a href="iptsec/index.html">"nta" - SIP transaction engine</a>
- <a href="nta/index.html">"nta" - SIP transaction engine</a>
- <a href="sresolv/index.html">"sresolv" - Asynchronous DNS resolver</a>
- <a href="tport/index.html">"tport" - Message transport</a>
- <a href="sip/index.html">"sip" - SIP messages and headers</a>
- <a href="msg/index.html">"msg" - Message handling </a>
- <a href="ipt/index.html">"ipt" - IPT utility library</a>
HTTP subsystem:
- <a href="nth/index.html">"nth" - HTTP protocol engine</a>
- <a href="http/index.html">"http" - HTTP messages and headers</a>
SDP processing:
- <a href="soa/index.html">"soa" - SDP Offer/Answer engine for SIP</a>
- <a href="sdp/index.html">"sdp" - SDP parser</a>
Documentation:
- "docs" - Documentation generated by Doxygen
......@@ -192,7 +197,7 @@ The following ANSI C 99 features are to be used in Sofia-SIP software:
The following ANSI C 99 features shall not be used in Sofia-SIP software:
- definition of a variable in the middle of function code.
(So always define your variables in the beginning of the function)
(so always define your variables in the beginning of the block)
@subsection port_ints Integer Types
......@@ -296,7 +301,7 @@ structure. Seems handy but beware: initialization of this structure fails
on some ARM gcc compilers. (Ask Kai Vehmanen for details).
A way to force packing of a structure is to use preprocessor
directive @c #pragma(pack). This directive is compiler specific, so if
directive @c @#pragma(pack). This directive is compiler specific, so if
you plan to write truly portable code, you cannot use it. We have
used it in some parts of the Sofia-SIP though. Only alternative is to
write functions that fetch the desired bits from a 32 bit field
......
......@@ -1756,6 +1756,19 @@ MSG_HEADER_CLASS_G(content_md5, "Content-MD5", "", single);
* @endcode
*/
/**@ingroup msg_content_id
* @typedef msg_generic_t msg_content_id_t;
* Content-ID Header Structure.
* @code
* typedef struct
* {
* msg_common_t g_common[1]; // Common fragment info
* msg_content_id_t *g_next; // Link to next header
* char const *g_string; // Header value
* }
* @endcode
*/
#define msg_content_id_d msg_generic_d
#define msg_content_id_e msg_generic_e
msg_hclass_t msg_content_id_class[] =
......@@ -1907,7 +1920,6 @@ int msg_mime_version_e(char b[], int bsiz, msg_header_t const *h, int f)
msg_hclass_t msg_content_location_class[] =
MSG_HEADER_CLASS_G(content_location, "Content-Location", "", single);
/* ====================================================================== */
/* ====================================================================== */
#if 0
......
......@@ -25,6 +25,36 @@
/*
*/
/*
* This file is part of the Sofia-SIP package
*
* Copyright (C) 2005 Nokia Corporation.
*
* Contact: Pekka Pessi <pekka.pessi@nokia.com>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* as published by the Free Software Foundation; either version 2.1 of
* the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA
*
*/
/**@CFILE nea_debug.c Debug Log for Nokia Event Client API
*
* @author Pekka Pessi <Pekka.Pessi@nokia.com>
*
*/
#include <stddef.h>
#include <nea_debug.h>
......
Description of Adding a Standard SIP Header
===========================================
Description of Adding a SIP Header to Sofia SIP
===============================================
by Pekka Pessi (2002-08-16, updated 2005-08-03)
by Pekka Pessi (2002-08-16, updated 2005-10-05)
In the text below, we use "Example" header as our example with following
ABNF:
sip-example = "Example" COLON 1*DIGIT
There are two ways to extend your parser.
In the text below, we use "Example" header as our example.
* Write parsing tests for your new headers in torture_sip.c...
- Add all relevant parsing/processing cases you can think of
at the end of function sip_header_test() or add a testing
function of your own.
* In <sip.h>, add:
IF YOUR HEADER IS A STANDARD ONE:
* In <sip.h>, add:
- Add typedefs to the header structures.
......@@ -23,12 +32,87 @@ In the text below, we use "Example" header as our example.
Note that the typedefs are documented together with the
implementation in the .c file.
- Add field to the sip_t structure (struct sip_s)
- remember to add a comment after field for AWK script:
sip_example_t *sip_example; /**< Example */
- NOTE: the AWK script msg_parser.awk automatically creates the default
prototypes and tags for the newly created header, when the entry in
sip_t structure is formatted like to the example above
- Add field to the sip_t structure (struct sip_s)
- remember to add a comment after field for AWK script:
sip_example_t *sip_example; /**< Example */
- NOTE: the AWK script msg_parser.awk automatically creates the default
prototypes and tags for the newly created header, when the entry in
sip_t structure is formatted like to the example above
IF YOUR HEADERS ARE NON-STANDARD:
- Create a header template for your header just like sip_rfc2543.h.in,
e.g, sip_example.h.in:
---8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<---
/**@file sip_example.h.in
*
* Template for <sip_example.h>.
*/
#ifndef SIP_EXAMPLE_H
/** Defined when <sip_example.h> has been included. */
#define SIP_EXAMPLE_H
/**@file sip_example.h
*
* @brief Example header.
*
* #AUTO#
*
* @author Pekka Pessi <Pekka.Pessi@nokia.com>.
*
* @date Created: Fri May 27 18:40:38 EEST 2005 ppessi
*/
#ifndef SIP_H
#include <sip.h>
#endif
/**@ingroup sip_also
* @brief Structure for @b Also header.
*/
struct sip_also_s
{
sip_common_t also_common[1]; /**< Common fragment info */
sip_also_t *also_next; /**< Link to next Also header */
char const *also_display; /**< Display name */
url_t also_url[1]; /**< URL */
};
typedef struct sip_also_s sip_also_t;
typedef sip_generic_t sip_hide_t;
typedef sip_auth_t sip_encryption_t;
typedef sip_auth_t sip_response_key_t;
struct sip_example_dummy_structure {
/* === Headers start here */
sip_also_t *sip_also; /**< Also */
sip_hide_t *sip_hide; /**< Hide */
sip_encryption_t *sip_encryption; /**< Encryption */
sip_response_key_t *sip_response_key; /**< Response-Key */
/* === Headers end here */
};
#endif /** !defined(SIP_EXAMPLE_H) */
--->8---->8---->8---->8---->8---->8---->8---->8---->8---->8---->8---->8---
- Add a makefile rule
$s/sip_example.h: $s/sip_example.h.in
${AWK} -f ${sofiaexecdir}/msg_parser.awk module=sip PR=$@ \
NO_FIRST=1 NO_LAST=1 \
TEMPLATE1=$i/sip_hclasses.h.in \
TEMPLATE2=$i/sip_protos.h.in \
TEMPLATE3=$i/sip_tag.h.in \
$s/sip_example.h.in
$s/sip_example_tag.c: $s/sip_example_tag.c.in $s/sip_example.h.in
${AWK} -f ${sofiaexecdir}/msg_parser.awk module=sip PR=$@ \
NO_FIRST=1 NO_LAST=1 \
$s/sip_example.h.in
- Add the actual header structure:
......@@ -50,22 +134,6 @@ In the text below, we use "Example" header as our example.
unsigned long ex_value; /**< Value of example. */
};
[HISTORIC STEP; adding new things to sip_header_t union deprecated]
- Add the header typedefs to the sip_header_t (also known as union
sip_header_u):
...
sip_warning_t sh_warning[1];
sip_example_t sh_example[1];
...
The sip_header_t is pointer to any SIP header; it can be converted to
any specific header type by referencing the union, for example:
sip_header_t *h = ...;
sip_example_t *ex = h->sh_example;
* Add implementation in a suitable ".c" file
- For an simple example, see implementation of Date header in sip_basic.c
......
......@@ -228,12 +228,15 @@
* of the headers. If there were an third Via header after CSeq in the
* message, the fragment representing it would be after the CSeq header in
* the fragment chain but after second Via in the header list.
*
* @}
*/
/**@{*/
/**@}*/
/**@addtogroup sip_headers
/**@ingroup sip
* @defgroup sip_headers SIP Headers
*
* SIP headers and other SIP message elements.
*
* @{
*/
......@@ -574,10 +577,7 @@ int sip_X_e(char buf[], int bsiz, sip_header_t const *h, int flags);
* In the above fragment, the function sip_add_tl() will add @b Content-Type
* and @b User-Agent headers along with message payload to the SIP message.
* The @b Content-Type header is made with value "text/plain".
*/
/**@ingroup sip
* @defgroup sip_headers SIP Headers
*
* SIP headers and other SIP message elements.
* @}
*/
/* -*- c -*- */
/*REMOVED_RCS_ID*/
/**@ingroup sip
* @defgroup sip_parser SIP Parser
/**@page sip_parser SIP Parser
*
* This part of the Sofia documentation describes the internal working of
* SIP parser. It documents the internal functions and macros used when a
......@@ -28,7 +25,67 @@
* for @ref sip_unknown "unknown headers" and
* @ref sip_error "headers that contained parsing errors".
*
* @{
*
* @section sip_add_headers Adding Headers to Parser
*
* Sofia SIP Parser can be extended easily, either by application or by
* internally extending the sofia-sip library itself.
*
* Create a header template for your header just like sip_rfc2543.h.in,
* e.g, sip_example.h.in:
*
*@code
/**@file sip_example.h.in
*
* Template for <sip_example.h>.
*/
#ifndef SIP_EXAMPLE_H
/** Defined when <sip_example.h> has been included. */
#define SIP_EXAMPLE_H
/**@}*/
/**@file sip_example.h
*
* @brief Example header.
*
* #AUTO#
*
* @author Pekka Pessi <Pekka.Pessi@nokia.com>.
*
* @date Created: Fri May 27 18:40:38 EEST 2005 ppessi
*/
#ifndef SIP_H
#include <sip.h>
#endif
/**@ingroup sip_also
* @brief Structure for @b Also header.
*/
struct sip_also_s
{
sip_common_t also_common[1]; /**< Common fragment info */
sip_also_t *also_next; /**< Link to next Also header */
char const *also_display; /**< Display name */
url_t also_url[1]; /**< URL */
};
typedef struct sip_also_s sip_also_t;
typedef sip_generic_t sip_hide_t;
typedef sip_auth_t sip_encryption_t;
typedef sip_auth_t sip_response_key_t;
struct sip_example_dummy_structure {
/* === Headers start here */
sip_also_t *sip_also; /**< Also */
sip_hide_t *sip_hide; /**< Hide */
sip_encryption_t *sip_encryption; /**< Encryption */
sip_response_key_t *sip_response_key; /**< Response-Key */
/* === Headers end here */
};
#endif /** !defined(SIP_EXAMPLE_H) */
--->8---->8---->8---->8---->8---->8---->8---->8---->8---->8---->8---->8---
* @endcode
*/
......@@ -211,7 +211,7 @@ tag_typedef_t soatag_user_sdp_str = STRTAG_TYPEDEF(user_sdp_str);
tag_typedef_t soatag_af = INTTAG_TYPEDEF(af);
/**@def SOATAG_AF_REF(x)
/**@def SOATAG_ADDRESS(x)
*
* Pass media address.
*
......
......@@ -1441,10 +1441,6 @@ sres_query_report_error(sres_resolver_t *res, sres_query_t *q,
* The function sresolver_timer() should be called in regular intervals. We
* recommend calling it in 500 ms intervals.
*
* Every time it is called it goes through all query structures, and
* retransmits all the query messages, which have not been answered yet.
*
* Every 30 seconds it goes through the cache and removes outdated entries.
*/
void sres_resolver_timer(sres_resolver_t *res, int socket)
{
......@@ -1461,7 +1457,9 @@ void sres_resolver_timer(sres_resolver_t *res, int socket)
now = time(&res->res_now);
if (res->res_queries->qt_used) {
/** Resend unanswered queries */
/** Every time it is called it goes through all query structures, and
* retransmits all the query messages, which have not been answered yet.
*/
for (i = 0; i < res->res_queries->qt_size; i++) {
q = res->res_queries->qt_table[i];
......@@ -1480,6 +1478,7 @@ void sres_resolver_timer(sres_resolver_t *res, int socket)
}
}
/** Every 30 seconds it goes through the cache and removes outdated entries. */
if (res->res_now > res->res_cache_cleaned + SRES_CACHE_TIMER_INTERVAL) {
/* Clean cache from old entries */
res->res_cache_cleaned = res->res_now;
......
......@@ -41,7 +41,7 @@
*
* @par SU Debug Log
*
* The debugging output from @b su module is controlled by #su_global_log
* The debugging output from @b su module is controlled by #su_log_global
* log object. The environment variable #SU_DEBUG sets the default log
* level.
*/
......
......@@ -229,7 +229,7 @@ void su_task_move(su_task_r dst, su_task_r src)
}
/**
* Compare two tasks with each other..
* Compare two tasks with each other.
*
* @param a First task
* @param b Second task
......@@ -246,7 +246,7 @@ int su_task_cmp(su_task_r const a, su_task_r const b)
}
/**
* Tests if a task is running..
* Tests if a task is running.
*
* @param task task handle
*
......
......@@ -86,7 +86,7 @@ long su_time_cmp(su_time_t const t1, su_time_t const t2)
return retval;
}
/**@DEF SU_TIME_CMP(t1, t2)
/**@def SU_TIME_CMP(t1, t2)
*
* Compare two timestamps.
*
......@@ -98,6 +98,8 @@ long su_time_cmp(su_time_t const t1, su_time_t const t2)
* @retval negative, if t1 is before t2,
* @retval zero, if t1 is same as t2, or
* @retval positive, if t1 is after t2.
*
* @hideinitializer
*/
/** Difference between two timestamps.
......
......@@ -52,29 +52,28 @@
/* ---------------------------------------------------------------------- */
/* Constants */
/** @DEF SU_WAIT_IN Incoming data is available on socket. @HI */
/** @DEF SU_WAIT_OUT Data can be sent on socket. @HI */
/** @DEF SU_WAIT_ERR An error occurred on socket. @HI */
/** @DEF SU_WAIT_HUP The socket connection was closed. @HI */
/** @DEF SU_WAIT_ACCEPT A listening socket accepted a new connection. @HI */
/** @DEF SU_WAIT_FOREVER No timeout for su_wait(). */
/** @DEF SU_WAIT_TIMEOUT The return value of su_wait() if timeout occurred. */
/** @DEF SU_WAIT_INIT Initializer for a wait object. */
#if SU_HAVE_POLL
#if SU_HAVE_POLL || DOCUMENTATION_ONLY
/** Compare wait object */
#define SU_WAIT_CMP(x, y) \
(((x).fd - (y).fd) ? ((x).fd - (y).fd) : ((x).events - (y).events))
/** Incoming data is available on socket. @HI */
#define SU_WAIT_IN (POLLIN)
/** Data can be sent on socket. @HI */
#define SU_WAIT_OUT (POLLOUT)
/** An error occurred on socket. @HI */
#define SU_WAIT_ERR (POLLERR)
/** The socket connection was closed. @HI */
#define SU_WAIT_HUP (POLLHUP)
/** A listening socket accepted a new connection. @HI */
#define SU_WAIT_ACCEPT (POLLIN)
/** No timeout for su_wait(). */
#define SU_WAIT_FOREVER (-1)
/** The return value of su_wait() if timeout occurred. */
#define SU_WAIT_TIMEOUT (-2)
/** Initializer for a wait object. @HI */
#define SU_WAIT_INIT { INVALID_SOCKET, 0, 0 }
#elif SU_HAVE_WINSOCK
......
......@@ -135,9 +135,9 @@ enum {
#define BEGIN() BEGIN_(TSTFLAGS); { extern int tstdef_dummy
/** End a test function. @HIDE */
#define END() (void) tstdef_dummy; } END_(TSTFLAGS)
/**Test that @a suite returns a nonzero value. @HIDE
/**Test that @a suite returns a nonzero value.
* @deprecated Use TEST_1()
*/
* @HIDE */
#define TEST0(suite) TEST_1_(TSTFLAGS, suite)
/** Test that @a suite returns a nonzero value. @HIDE */
#define TEST_1(suite) TEST_1_(TSTFLAGS, suite)
......
......@@ -894,8 +894,9 @@ int url_len(url_t const * url)
return rv;
}
/**@DEF URL_E(buf, end, url)
/**@def URL_E(buf, end, url)
* Encode an URL: use @a buf up to @a end.
* @hideinitializer
*/
/**
......
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