From b78287fec5eda36db3031e82295e8aed1ea59666 Mon Sep 17 00:00:00 2001 From: Pekka Pessi Date: Thu, 27 Oct 2005 21:51:06 +0300 Subject: [PATCH] Documentation fixes in msg module. darcs-hash:20051027185106-65a35-3071ae5d78d640ac71d2decf3a0b3824b8cd34cc.gz --- libsofia-sip-ua/msg/msg.docs | 27 ++-- libsofia-sip-ua/msg/msg_addr.h | 3 + libsofia-sip-ua/msg/msg_date.c | 2 +- libsofia-sip-ua/msg/msg_mime.c | 168 ++++++++++++++++++++--- libsofia-sip-ua/msg/msg_mime_protos.h.in | 2 +- libsofia-sip-ua/msg/msg_parser.c | 9 +- 6 files changed, 170 insertions(+), 41 deletions(-) diff --git a/libsofia-sip-ua/msg/msg.docs b/libsofia-sip-ua/msg/msg.docs index 1eb73294..ba918cdc 100644 --- a/libsofia-sip-ua/msg/msg.docs +++ b/libsofia-sip-ua/msg/msg.docs @@ -473,22 +473,21 @@ encountered. * @defgroup msg_mime MIME Headers * * This submodule contains the header classes, functions and types for - * handling MIME headers (RFC 2045) and MIME multipart (RFC 2046) processing. + * handling MIME headers (@RFC2045) and MIME multipart (@RFC2046) processing. * * The MIME headers implemented are as follows: - * - #msg_accept_t - @b Accept header - * - #msg_accept_charset_t - @b Accept-Charser header - * - #msg_accept_encoding_t - @b Accept-Encoding header - * - #msg_accept_language_t - @b Accept-Language header - * - #msg_content_disposition_t - @b Content-Disposition header - * - #msg_content_encoding_t - @b Content-Encoding header - * - #msg_content_base_t - @b Content-Base header - * - #msg_content_id_t - @b Content-ID header - * - #msg_content_location_t - @b Content-Location header - * - #msg_content_language_t - @b Content-Language header - * - #msg_content_md5_t - @b Content-MD5 header - * - #msg_content_transfer_encoding_t - @b Content-Transfer-Encoding header - * - #msg_mime_version_t - @b MIME-Version header + * - @ref msg_accept "@b Accept header" + * - @ref msg_accept_charset "@b Accept-Charser header" + * - @ref msg_accept_encoding "@b Accept-Encoding header" + * - @ref msg_accept_language "@b Accept-Language header" + * - @ref msg_content_disposition "@b Content-Disposition header" + * - @ref msg_content_encoding "@b Content-Encoding header" + * - @ref msg_content_id "@b Content-ID header" + * - @ref msg_content_location "@b Content-Location header" + * - @ref msg_content_language "@b Content-Language header" + * - @ref msg_content_md5 "@b Content-MD5 header" + * - @ref msg_content_transfer_encoding "@b Content-Transfer-Encoding header" + * - @ref msg_mime_version "@b MIME-Version header" */ /** diff --git a/libsofia-sip-ua/msg/msg_addr.h b/libsofia-sip-ua/msg/msg_addr.h index 71352bbc..9602fa4a 100644 --- a/libsofia-sip-ua/msg/msg_addr.h +++ b/libsofia-sip-ua/msg/msg_addr.h @@ -53,8 +53,11 @@ int msg_errno(msg_t const *msg); void msg_set_errno(msg_t *msg, int err); enum { + /** Minimum size of a message buffer */ msg_min_size = 512, + /** Minimum size of external buffer */ msg_min_block = 8192, + /** Number of external buffers */ msg_n_fragments = 8 }; diff --git a/libsofia-sip-ua/msg/msg_date.c b/libsofia-sip-ua/msg/msg_date.c index 1c010120..a890b784 100644 --- a/libsofia-sip-ua/msg/msg_date.c +++ b/libsofia-sip-ua/msg/msg_date.c @@ -26,7 +26,7 @@ * @CFILE msg_date.c * @brief Parser for HTTP-Date and HTTP-Delta. * - * Parsing functions for RFC 1123 (GMT) date. + * Parsing functions for @RFC1123 (GMT) date. * * @author Pekka Pessi * diff --git a/libsofia-sip-ua/msg/msg_mime.c b/libsofia-sip-ua/msg/msg_mime.c index 300505b7..24ff16a1 100644 --- a/libsofia-sip-ua/msg/msg_mime.c +++ b/libsofia-sip-ua/msg/msg_mime.c @@ -124,7 +124,7 @@ union msg_mime_u * * The #msg_multipart_t is an object for storing MIME multipart message * bodies. It includes message components used for framing and identifying - * message parts. Its syntax is defined in RFC 2046 as follows: + * message parts. Its syntax is defined in @RFC2046 as follows: * * @code * @@ -156,7 +156,7 @@ union msg_mime_u * ; transport padding, but receivers MUST be able to * ; handle padding added by message transports. * - * body-part := <"message" as defined in RFC 822, with all header fields + * body-part := <"message" as defined in @RFC822, with all header fields * optional, not starting with the specified dash-boundary, * and with the delimiter not occurring anywhere in the body * part. Note that the semantics of a part differ from the @@ -389,7 +389,7 @@ msg_multipart_search_boundary(su_home_t *home, char const *p, size_t len) /** Parse a MIME multipart. * * The function msg_multipart_parse() parses a MIME multipart message. The - * common syntax of multiparts is described in RFC 2046 (section 7). + * common syntax of multiparts is described in @RFC2046 (section 7). * * @param home home for allocating structures [IN/OUT] * @param c content-type header for multipart [IN] @@ -1350,7 +1350,7 @@ int msg_accept_charset_e(char b[], int bsiz, msg_header_t const *h, int f) * * The Accept-Encoding header is similar to Accept, but restricts the * content-codings that are acceptable in the response. Its syntax is - * defined in [H14.3, S10.7] (bis-04) as follows: + * defined in [H14.3, S20.2] as follows: * * @code * Accept-Encoding = "Accept-Encoding" ":" @@ -1400,7 +1400,7 @@ int msg_accept_encoding_e(char b[], int bsiz, msg_header_t const *h, int f) * The Accept-Language header allows the client to indicate to the server in * which language it would prefer to receive reason phrases, session * descriptions or status responses carried as message bodies. Its syntax is - * defined in [H14.4, S10.8] (bis-04) as follows: + * defined in [H14.4, S20.3] as follows: * * @code * Accept-Language = "Accept-Language" ":" @@ -1451,8 +1451,8 @@ int msg_accept_language_e(char b[], int bsiz, msg_header_t const *h, int f) * * The Content-Disposition header field describes how the message body or, * in the case of multipart messages, a message body part is to be - * interpreted by the UAC or UAS. Its syntax is defined in [S10.15] - * (bis-04) as follows: + * interpreted by the UAC or UAS. Its syntax is defined in [S20.11] + * as follows: * * @code * Content-Disposition = "Content-Disposition" ":" @@ -1472,10 +1472,9 @@ int msg_accept_language_e(char b[], int bsiz, msg_header_t const *h, int f) * @code * Content-Disposition = "Content-Disposition" ":" * disposition-type *( ";" disposition-param ) - * disposition-type = "script" | "sip-cgi" | token - * disposition-param = action-param - * | modification-date-param - * | generic-param + * disposition-type /= "script" | "sip-cgi" | token + * disposition-param /= action-param + * / modification-date-param * action-param = "action" "=" action-value * action-value = "store" | "remove" | token * modification-date-param = "modification-date" "=" quoted-date-time @@ -1483,6 +1482,27 @@ int msg_accept_language_e(char b[], int bsiz, msg_header_t const *h, int f) * @endcode */ +/**@ingroup msg_content_disposition + * @typedef struct msg_content_disposition_s msg_content_disposition_t; + * + * The structure msg_content_disposition_t contains representation of an @b + * Content-Disposition header. + * + * The msg_content_disposition_t is defined as follows: + * @code + * typedef struct msg_content_disposition_s + * { + * msg_common_t cd_common[1]; // Common fragment info + * msg_error_t *cd_next; // Link to next (dummy) + * char const *cd_type; // Disposition type + * msg_param_t const *cd_params; // List of parameters + * msg_param_t cd_handling; // Value of @b handling parameter + * unsigned cd_required:1; // True if handling=required + * unsigned cd_optional:1; // True if handling=optional + * } msg_content_disposition_t; + * @endcode + */ + msg_hclass_t msg_content_disposition_class[] = MSG_HEADER_CLASS(msg_, content_disposition, "Content-Disposition", "", cd_params, single, msg_content_disposition); @@ -1573,15 +1593,32 @@ static void msg_content_disposition_update(msg_content_disposition_t *cd) * @defgroup msg_content_encoding Content-Encoding Header * * The Content-Encoding header indicates what additional content codings - * have been applied to the entity-body. Its syntax is defined in [S10.16] - * (bis-04) as follows: + * have been applied to the entity-body. Its syntax is defined in [H14.11] + * and [S20.12] as follows: * * @code - * Content-Encoding = ( "Content-Encoding" | "e" ) ":" 1#content-coding + * Content-Encoding = ( "Content-Encoding" / "e" ) ":" 1#content-coding * content-coding = token * @endcode */ +/**@ingroup msg_content_encoding + * @typedef struct msg_list_s msg_content_encoding_t; + * + * The structure msg_content_encoding_t contains representation of an @b + * Content-Encoding header. + * + * The msg_content_encoding_t is defined as follows: + * @code + * typedef struct msg_list_s + * { + * msg_common_t k_common[1]; // Common fragment info + * msg_list_t *k_next; // Link to next header + * msg_param_t *k_items; // List of items + * } msg_content_encoding_t; + * @endcode + */ + msg_hclass_t msg_content_encoding_class[] = MSG_HEADER_CLASS_LIST(content_encoding, "Content-Encoding", "e", list); @@ -1724,11 +1761,28 @@ msg_content_length_t *msg_content_length_create(su_home_t *home, uint32_t n) * * The Content-MD5 header is an MD5 digest of the entity-body for the * purpose of providing an end-to-end message integrity check (MIC) of the - * message-body. Its syntax is defined in [RFC1864, H14.15] as follows: + * message-body. Its syntax is defined in [@RFC1864, H14.15] as follows: * * @code * Content-MD5 = "Content-MD5" ":" md5-digest - * md5-digest = + * md5-digest = + * @endcode + */ + +/**@ingroup msg_content_md5 + * @typedef struct msg_generic_s msg_content_md5_t; + * + * The structure msg_content_md5_t contains representation of an @b + * Content-MD5 header. + * + * The msg_content_md5_t is defined as follows: + * @code + * typedef struct msg_generic_s + * { + * msg_common_t g_common[1]; // Common fragment info + * msg_generic_t *g_next; // Link to next header + * char const *g_string; // Header value + * } msg_content_md5_t; * @endcode */ @@ -1780,7 +1834,7 @@ MSG_HEADER_CLASS_G(content_id, "Content-ID", "", single); * @defgroup msg_content_type Content-Type Header * * The @b Content-Type header indicates the media type of the message-body - * sent to the recipient. Its syntax is defined in [H3.7, S10.19] (bis-04) + * sent to the recipient. Its syntax is defined in [H3.7, S20.15] * as follows: * * @code @@ -1885,14 +1939,31 @@ char *msg_content_type_dup_one(msg_header_t *dst, msg_header_t const *src, * @defgroup msg_mime_version MIME-Version Header * * MIME-Version header indicates what version of the protocol was used - * to construct the message. Its syntax is defined in [H19.4.1, S10.28] - * (bis-04) as follows: + * to construct the message. Its syntax is defined in [H19.4.1, S20.24] + * as follows: * * @code * MIME-Version = "MIME-Version" ":" 1*DIGIT "." 1*DIGIT * @endcode */ +/**@ingroup msg_mime_version + * @typedef struct msg_generic_s msg_mime_version_t; + * + * The structure msg_mime_version_t contains representation of an @b + * MIME-Version header. + * + * The msg_mime_version_t is defined as follows: + * @code + * typedef struct msg_generic_s + * { + * msg_common_t g_common[1]; // Common fragment info + * msg_generic_t *g_next; // Link to next header + * char const *g_string; // Header value + * } msg_mime_version_t; + * @endcode + */ + msg_hclass_t msg_mime_version_class[] = MSG_HEADER_CLASS_G(mime_version, "MIME-Version", "", single); @@ -1915,6 +1986,23 @@ int msg_mime_version_e(char b[], int bsiz, msg_header_t const *h, int f) * */ +/**@ingroup msg_content_location + * @typedef struct msg_generic_s msg_content_location_t; + * + * The structure msg_content_location_t contains representation of an @b + * Content-Location header. + * + * The msg_content_location_t is defined as follows: + * @code + * typedef struct msg_generic_s + * { + * msg_common_t g_common[1]; // Common fragment info + * msg_generic_t *g_next; // Link to next header + * char const *g_string; // Header value + * } msg_content_location_t; + * @endcode + */ + #define msg_content_location_d msg_generic_d #define msg_content_location_e msg_generic_e msg_hclass_t msg_content_location_class[] = @@ -1926,7 +2014,7 @@ MSG_HEADER_CLASS_G(content_location, "Content-Location", "", single); /**@ingroup msg_mime * @defgroup msg_content_base Content-Base Header * - * RFC2617: + * @RFC2617: * Content-Base was deleted from the specification: it was not * implemented widely, and there is no simple, safe way to introduce it * without a robust extension mechanism. In addition, it is used in a @@ -1963,6 +2051,24 @@ MSG_HEADER_CLASS_G(content_base, "Content-Base", "", single); * */ +/**@ingroup msg_content_transfer_encoding + * @typedef struct msg_generic_s msg_content_transfer_encoding_t; + * + * The structure msg_content_transfer_encoding_t contains representation of + * an @b Content-Transfer-Encoding header. + * + * The msg_content_transfer_encoding_t is defined as follows: + * @code + * typedef struct msg_generic_s + * { + * msg_common_t g_common[1]; // Common fragment info + * msg_generic_t *g_next; // Link to next header + * char const *g_string; // Header value + * } msg_content_transfer_encoding_t; + * @endcode + */ + + #define msg_content_transfer_encoding_d msg_generic_d #define msg_content_transfer_encoding_e msg_generic_e msg_hclass_t msg_content_transfer_encoding_class[] = @@ -1975,7 +2081,7 @@ MSG_HEADER_CLASS_G(content_transfer_encoding, "Content-Transfer-Encoding", * @defgroup msg_warning Warning Header * * The Warning response-header field is used to carry additional information - * about the status of a response. Its syntax is defined in [RFC 3265 10.47] + * about the status of a response. Its syntax is defined in [S20.43] * as follows: * * @code @@ -1990,6 +2096,26 @@ MSG_HEADER_CLASS_G(content_transfer_encoding, "Content-Transfer-Encoding", * @endcode */ +/**@ingroup msg_warning + * @typedef struct msg_warning_s msg_warning_t; + * + * The structure msg_warning_t contains representation of an @b + * Warning header. + * + * The msg_warning_t is defined as follows: + * @code + * typedef struct msg_warning_s + * { + * msg_common_t w_common[1]; // Common fragment info + * msg_warning_t *w_next; // Link to next Warning header + * unsigned w_code; // Warning code + * char const *w_host; // Hostname or pseudonym + * char const *w_port; // Port number + * char const *w_text; // Warning text + * } msg_warning_t; + * @endcode + */ + int msg_warning_d(su_home_t *home, msg_header_t *h, char *s, int slen) { msg_warning_t *w = h->sh_warning; diff --git a/libsofia-sip-ua/msg/msg_mime_protos.h.in b/libsofia-sip-ua/msg/msg_mime_protos.h.in index e3974f4c..fc7a94b1 100644 --- a/libsofia-sip-ua/msg/msg_mime_protos.h.in +++ b/libsofia-sip-ua/msg/msg_mime_protos.h.in @@ -34,7 +34,7 @@ /**@ingroup msg_mime * @file msg_mime_protos.h * - * Prototypes for MIME headers (RFC 2045). + * Prototypes for MIME headers (@RFC2045). * * #AUTO# * diff --git a/libsofia-sip-ua/msg/msg_parser.c b/libsofia-sip-ua/msg/msg_parser.c index 1982bd25..60868717 100644 --- a/libsofia-sip-ua/msg/msg_parser.c +++ b/libsofia-sip-ua/msg/msg_parser.c @@ -1482,14 +1482,15 @@ static int msg_header_prepare(msg_mclass_t const *, int flags, * @relates msg_s * * The function msg_prepare() prepares a message for sending. It encodes all - * serialized fragments in the message. The #h_data field will point to the - * encoding result of size #h_len bytes. + * serialized fragments in the message. In each fragment, the + * msg_common_s::h_data field will point to the encoding result of size + * msg_common_s::h_len bytes. * * When multiple header fields are represented as a comma-separated list * within a single header line, the first fragment in the header will * contain all the text belonging to the header. The rest of the header - * fields will have zero-length encoding with #h_data that points to the end - * of the line. + * fields will have zero-length encoding with msg_common_s::h_data that + * points to the end of the line. * * @return Total size of the encoded message in bytes, or -1 upon an error. */ -- 2.21.0