Commit 777cc259 authored by Pekka Pessi's avatar Pekka Pessi
Browse files

sip/sip.docs: fixed whitespace

darcs-hash:20081127232534-db55f-715269fc1a1935df24b1212a4205a3c1772f71c8.gz
parent b9b88ed0
......@@ -44,7 +44,7 @@
* that drives the parsing process and invokes the SIP parser for each
* header. As there are no framing between SIP messages, the parser
* considers any received data, be it a UDP datagram or a TCP stream, as a
* @em message @em stream, which may consist of one or more SIP messages.
* @em message @em stream, which may consist of one or more SIP messages.
* The parser works by first separating stream into fragments, then building
* a complete message based on parsing result. After a message is completed,
* it can be given to the message stream customer (typically a protocol
......@@ -57,7 +57,7 @@
* one-by-one from the message. After the parser encounters an empty line
* separating the headers and the message body (payload), it invokes a
* function parsing the separator and payload fragment(s). When the message
* is complete, the parser can hand the message over to the protocol engine.
* is complete, the parser can hand the message over to the protocol engine.
* Then it is ready to start again with first fragment of the next message.
*
* @image html sip-parser.gif Separating byte stream to messages
......@@ -70,7 +70,7 @@
* fragment chain, and a whole other stuff is held by the generic message
* type, #msg_t, defined in <sofia-sip/msg.h>. The internal structure of #msg_t is
* known only within @b msg module and it is hidden from other modules.
*
*
* The abstract message module @b msg also drives the reverse process,
* invoking the encoding method of each fragment so that the whole outgoing
* SIP message is encoded properly.
......@@ -96,7 +96,7 @@
* For instance, the @From header has following syntax:
*
* @code
* from = ("From" | "f") ":"
* from = ("From" | "f") ":"
* ( name-addr | addr-spec ) *( ";" addr-params )
* name-addr = [ display-name ] "<" addr-spec ">"
* addr-spec = SIP-URL | URI
......@@ -134,7 +134,7 @@
* access certain headers at the SIP message level, for example, accessing
* directly the @From header instead of going through all headers and
* examining their name. The structured view to the SIP message is provided
* via a C struct with type #sip_t.
* via a C struct with type #sip_t.
*
* In other words, a single message is represented by two types, first type
* (#msg_t) is private to the msg module and inaccessable by an application
......@@ -151,7 +151,7 @@
* int sip_flags;
*
* sip_error_t *sip_error; // Erroneous headers
*
*
* sip_request_t *sip_request; // Request line
* sip_status_t *sip_status; // Status line
*
......@@ -210,11 +210,11 @@
* pointers to the headers according to their type. If there are multiple
* headers of the same type (like there are two @Via headers in the above
* message), the headers are put into a single-linked list.
*
*
* Each fragment has pointers to successing and preceding fragment. It also
* contains pointer to the corresponding data within the I/O buffer and its
* length.
*
*
* The main purpose of the fragment chain is to preserve the original order
* 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
......@@ -238,7 +238,7 @@
/**@ingroup sip_headers
* @defgroup sip_header_x SIP Header X - Conventions
*
*
* For a SIP header X, there are types, functions, macros and global data
* declared in <sofia-sip/sip_protos.h> and <sofia-sip/sip_hclass.h> as
* follows:
......@@ -247,13 +247,13 @@
* - sip_X_init() initializes a dynamic instance of #sip_X_t,
* - sip_is_X() tests if header object is instance of header X,
* - sip_X_make() creates a header X object by decoding given string,
* - sip_X_format() creates a header X object by decoding given
* - sip_X_format() creates a header X object by decoding given
* printf() list,
* - sip_X_dup() duplicates (deeply copies) the header X,
* - sip_X_dup() duplicates (deeply copies) the header X,
* - sip_X_copy() copies the header X,
* - #msg_hclass_t #sip_X_class[] contains the @em header @em class
* - #msg_hclass_t #sip_X_class[] contains the @em header @em class
* for header X.
*
*
* All header structures contain the common part, a #sip_common_t structure
* (@a X_common[]), a link to the next header in list (@a X_next), and
* various fields describing the header value (in this case, @a X_value).
......@@ -264,7 +264,7 @@
* struct msg_common_s {
* msg_header_t *h_succ; // Pointer to succeeding fragment
* msg_header_t **h_prev; // Pointer to preceeding fragment
* msg_hclass_t *h_class; // Header class
* msg_hclass_t *h_class; // Header class
* void const *h_data; // Encoded data
* usize_t h_len; // Encoding length (including CRLF)
* } X_common[1];
......@@ -295,7 +295,7 @@
* parameters. The content of parameters is not parsed, they are just
* separated from each other and then stored in an dynamically allocated
* array of string pointers. Pointer to the array is stored to @a X_params.
*
*
* For more complex header structures, see #sip_contact_t or #sip_rack_t.
*
* @{
......@@ -318,18 +318,18 @@ typedef struct sip_X_s sip_X_t;
/**@var msg_hclass_t sip_X_class[];
* @brief Header class for SIP X.
*
*
* The header class sip_X_class defines how a SIP
* X is parsed and printed. It also
* contains methods used by SIP parser and other functions
* to manipulate the sip_X_t header structure.
*
*
*/
SIP_DLL extern msg_hclass_t sip_X_class[];
enum {
enum {
/** Hash of X. @internal */
sip_X_hash = hash
sip_X_hash = hash
};
/** Parse a X. @internal */
......@@ -339,28 +339,28 @@ msg_parse_f sip_X_d;
msg_print_f sip_X_e;
/**Initializer for structure sip_X_t.
*
*
* A static sip_X_t structure must be initialized
* with the SIP_X_INIT() macro. For instance,
* @code
*
* @code
*
* sip_X_t sip_X = SIP_X_INIT;
*
*
* @endcode
* @HI
*/
#define SIP_X_INIT() SIP_HDR_INIT(X)
/**Initialize a structure sip_X_t.
*
*
* An sip_X_t structure can be initialized with the
* sip_X_init() function/macro. For instance,
* @code
*
*
* sip_X_t sip_X;
*
*
* sip_X_init(&sip_X);
*
*
* @endcode
* @HI
*/
......@@ -375,13 +375,13 @@ su_inline sip_X_t *sip_X_init(sip_X_t x[1])
#endif
/**Test if header object is instance of sip_X_t.
*
*
* The function sip_is_X() returns true (nonzero) if
* the header class is an instance of X
* object and false (zero) otherwise.
*
*
* @param header pointer to the header structure to be tested
*
*
* @return
* The function sip_is_X() returns true (nonzero) if
* the header object is an instance of header X and
......@@ -399,27 +399,27 @@ int sip_is_X(sip_header_t const *header);
#define sip_X_p(h) sip_is_X((h))
/**Duplicate (deep copy) @c sip_X_t.
*
*
* The function sip_X_dup() duplicates a header
* structure @a hdr. If the header structure @a hdr
* contains a reference (@c hdr->x_next) to a list of
* headers, all the headers in the list are duplicated, too.
*
*
* @param home memory home used to allocate new structure
* @param hdr header structure to be duplicated
*
*
* When duplicating, all parameter lists and non-constant
* strings attached to the header are copied, too. The
* function uses given memory @a home to allocate all the
* memory areas used to copy the header.
*
*
* @par Example
* @code
*
*
* X = sip_X_dup(home, sip->sip_X);
*
*
* @endcode
*
*
* @return
* The function sip_X_dup() returns a pointer to the
* newly duplicated sip_X_t header structure, or NULL
......@@ -428,29 +428,29 @@ int sip_is_X(sip_header_t const *header);
sip_X_t *sip_X_dup(su_home_t *home, sip_X_t const *hdr);
/**Copy a sip_X_t header structure.
*
*
* The function sip_X_copy() copies a header structure @a
* hdr. If the header structure @a hdr contains a reference (@c
* hdr->h_next) to a list of headers, all the headers in that
* list are copied, too. The function uses given memory @a home
* to allocate all the memory areas used to copy the header
* structure @a hdr.
*
*
* @param home memory home used to allocate new structure
* @param hdr pointer to the header structure to be duplicated
*
*
* When copying, only the header structure and parameter lists
* attached to it are duplicated. The new header structure
* retains all the references to the strings within the old @a
* header, including the encoding of the old header, if present.
*
*
* @par Example
* @code
*
*
* X = sip_X_copy(home, sip->sip_X);
*
*
* @endcode
*
*
* @return
* The function sip_X_copy() returns a pointer to
* newly copied header structure, or NULL upon an error.
......@@ -458,18 +458,18 @@ sip_X_t *sip_X_dup(su_home_t *home, sip_X_t const *hdr);
sip_X_t *sip_X_copy(su_home_t *home, sip_X_t const *hdr);
/**Make a header structure sip_X_t.
*
*
* The function sip_X_make() makes a new
* sip_X_t header structure. It allocates a new
* header structure, and decodes the string @a s as the
* value of the structure.
*
*
* @param home memory home used to allocate new header structure.
* @param s string to be decoded as value of the new header structure
*
*
* @note This function is usually implemented as a macro calling
* sip_header_make().
*
*
* @return
* The function sip_X_make() returns a pointer to
* newly maked sip_X_t header structure, or NULL upon
......@@ -485,25 +485,25 @@ sip_X_t *sip_X_make(su_home_t *home, char const *s);
#endif
/**Make a X from formatting result.
*
*
* The function sip_X_format() makes a new
* X object using formatting result as its
* value. The function first prints the arguments according to
* the format @a fmt specified. Then it allocates a new header
* structure, and uses the formatting result as the header
* value.
*
*
* @param home memory home used to allocate new header structure.
* @param fmt string used as a printf()-style format
* @param ... argument list for format
*
*
* @note This function is usually implemented as a macro calling
* msg_header_format().
*
*
* @return
* The function sip_X_format() returns a pointer to newly
* makes header structure, or NULL upon an error.
*
*
* @HIDE
*/
#if SU_HAVE_INLINE
......@@ -517,11 +517,11 @@ su_inline sip_X_t *sip_X_format(su_home_t *home, char const *fmt, ...)
{
sip_header_t *h;
va_list ap;
va_start(ap, fmt);
h = sip_header_vformat(home, sip_X_class, fmt, ap);
va_end(ap);
return h->sh_X;
}
#endif
......@@ -534,7 +534,7 @@ su_inline sip_X_t *sip_X_format(su_home_t *home, char const *fmt, ...)
* leading and trailing whitespace has been removed from the string @a s.
*
* @param home memory home used to allocate new header structure.
* @param h sip_X_t header structure
* @param h sip_X_t header structure
* @param s string to be decoded
* @param bsiz length of string @a s
*
......@@ -555,15 +555,15 @@ int sip_X_d(su_home_t *home, sip_header_t *h, char *s, int bsiz);
* @param bsiz size of the encoding buffer
* @param h header to be encoded.
* @param flags flags controlling the encoding
*
* @note
*
* @note
* The encoding buffer size @b must be @b bigger than, not equal to,
* the actual encoding result.
*
* @return
* The function sip_X_e() returns the number of characters required for the
* encoding.
*
*
*/
int sip_X_e(char buf[], int bsiz, sip_header_t const *h, int flags);
......@@ -577,7 +577,7 @@ int sip_X_e(char buf[], int bsiz, sip_header_t const *h, int flags);
/**@defgroup sip_tag SIP Tags
*
* SIP headers in tag item lists and tagged argument lists.
* SIP headers in tag item lists and tagged argument lists.
*
* The include file <sofia-sip/sip_tag.h> defines tags and tag items for including SIP
* headers in tag item lists or tagged argument lists. For each header,
......@@ -592,7 +592,7 @@ int sip_X_e(char buf[], int bsiz, sip_header_t const *h, int flags);
* @code
* sip_payload_t *payload;
* ...
* sip_add_tl(msg, sip,
* sip_add_tl(msg, sip,
* SIPTAG_CONTENT_TYPE_STR("text/plain"),
* SIPTAG_USER_AGENT(agent->user_agent),
* SIPTAG_PAYLOAD(payload),
......
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