Skip to content

GitLab

Commit ddb12ded authored by Pekka Pessi's avatar Pekka Pessi
Browse files

msg: updated documentation. Making use of new doxygen features. 

darcs-hash:20060914130348-65a35-6c6b9628b556bc605e8a7b2aa8a93355dfe439a1.gz
parent f94086d8
Hide whitespace changes
Inline Side-by-side
Showing with 173 additions and 137 deletions
libsofia-sip-ua/msg/Doxyfile
View file @ ddb12ded
......@@ -13,6 +13,4 @@ TAGFILES += ../docs/ipt.doxytags=../ipt \
GENERATE_TAGFILE = ../docs/msg.doxytags
PREDEFINED += "MSG_HDR_T=union msg_header_u"
IMAGE_PATH += ../sip/images
libsofia-sip-ua/msg/msg.docs
View file @ ddb12ded
......@@ -242,8 +242,9 @@ typedef struct sip_s {
msg_common_t sip_common[1]; // Used with recursive inclusion
msg_pub_t *sip_next; // Ditto
void *sip_user; // Application data
unsigned sip_size;
int sip_flags;
unsigned sip_size; // Size of the structure with
// extension headers
int sip_flags; // Parser flags
sip_error_t *sip_error; // Erroneous headers
......@@ -450,7 +451,16 @@ encountered.
* Message object.
*
* The @a msg_t is the type of a message object used by Sofia signaling
* protocols and parsers.
* protocols and parsers. Its contents are not directly accessible.
*/
/**@typedef typedef struct msg_common_s msg_common_t;
*
* Common part of header.
*
* The @a msg_common_t is the base type of a message headers used by
* protocol parsers. Instead of #msg_common_t, most interfaces use
* #msg_header_t, which is supposed to be a union of all possible headers.
*/
......
libsofia-sip-ua/msg/msg_date.c
View file @ ddb12ded
......@@ -150,30 +150,33 @@ int time_d(char const **ss,
/**Decode RFC1123-date, RFC822-date or asctime-date.
*
* The function msg_date_d() decodes @e HTTP-date, which may have
* The function msg_date_d() decodes <HTTP-date>, which may have
* different formats.
*
* @verbatim
* HTTP-date = rfc1123-date | rfc850-date | asctime-date
* @code
* HTTP-date = rfc1123-date / rfc850-date / asctime-date
*
* rfc1123-date = wkday "," SP date1 SP time SP "GMT"
* rfc850-date = weekday "," SP date2 SP time SP "GMT"
* asctime-date = wkday SP date3 SP time SP 4DIGIT
* date1 = 2DIGIT SP month SP 4DIGIT
* ; day month year (e.g., 02 Jun 1982)
*
* rfc850-date = weekday "," SP date2 SP time SP "GMT"
* date2 = 2DIGIT "-" month "-" 2DIGIT
* ; day-month-year (e.g., 02-Jun-82)
* date3 = month SP ( 2DIGIT | ( SP 1DIGIT ))
*
* asctime-date = wkday SP date3 SP time SP 4DIGIT
* date3 = month SP ( 2DIGIT / ( SP 1DIGIT ))
* ; month day (e.g., Jun 2)
*
* time = 2DIGIT ":" 2DIGIT ":" 2DIGIT
* ; 00:00:00 - 23:59:59
* wkday = "Mon" | "Tue" | "Wed"
* | "Thu" | "Fri" | "Sat" | "Sun"
* weekday = "Monday" | "Tuesday" | "Wednesday"
* | "Thursday" | "Friday" | "Saturday" | "Sunday"
* month = "Jan" | "Feb" | "Mar" | "Apr"
* | "May" | "Jun" | "Jul" | "Aug"
* | "Sep" | "Oct" | "Nov" | "Dec"
* @endverbatim
*
* wkday = "Mon" / "Tue" / "Wed" / "Thu" / "Fri" / "Sat" / "Sun"
* weekday = "Monday" / "Tuesday" / "Wednesday"
* / "Thursday" / "Friday" / "Saturday" / "Sunday"
* month = "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun"
* / "Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec"
* @endcode
*/
issize_t msg_date_d(char const **ss, msg_time_t *date)
{
......@@ -299,21 +302,21 @@ issize_t msg_date_d(char const **ss, msg_time_t *date)
/**Encode RFC1123-date.
*
* The function msg_date_e() prints @e http-date in the @e rfc1123-date
* The function msg_date_e() prints @e http-date in the <rfc1123-date>
* format. The format is as follows:
*
* @verbatim
* rfc1123-date = wkday "," SP date SP time SP "GMT"
* wkday = "Mon" | "Tue" | "Wed"
* | "Thu" | "Fri" | "Sat" | "Sun"
* date = 2DIGIT SP month SP 4DIGIT
* ; day month year (e.g., 02 Jun 1982)
* month = "Jan" | "Feb" | "Mar" | "Apr"
* | "May" | "Jun" | "Jul" | "Aug"
* | "Sep" | "Oct" | "Nov" | "Dec"
* time = 2DIGIT ":" 2DIGIT ":" 2DIGIT
* ; 00:00:00 - 23:59:59
* @endverbatim
* @code
* rfc1123-date = wkday "," SP date SP time SP "GMT"
* wkday = "Mon" | "Tue" | "Wed"
* | "Thu" | "Fri" | "Sat" | "Sun"
* date = 2DIGIT SP month SP 4DIGIT
* ; day month year (e.g., 02 Jun 1982)
* month = "Jan" | "Feb" | "Mar" | "Apr"
* | "May" | "Jun" | "Jul" | "Aug"
* | "Sep" | "Oct" | "Nov" | "Dec"
* time = 2DIGIT ":" 2DIGIT ":" 2DIGIT
* ; 00:00:00 - 23:59:59
* @endcode
*
* @param b buffer to print the date
* @param bsiz size of the buffer
......@@ -359,9 +362,16 @@ issize_t msg_date_e(char b[], isize_t bsiz, msg_time_t http_date)
}
/**Decode a http-delta.
/**Decode a delta-seconds.
*
* The function msg_delta_d() decodes a http-delta field.
* The function msg_delta_d() decodes a <delta-seconds> field.
*
* The <delta-seconds> is defined as follows:
* @code
* delta-seconds = 1*DIGIT
* @endcode
*
* Note, however, that <delta-seconds> may not be larger than #MSG_TIME_MAX.
*/
issize_t msg_delta_d(char const **ss, msg_time_t *delta)
{
......@@ -376,20 +386,21 @@ issize_t msg_delta_d(char const **ss, msg_time_t *delta)
return *ss - s;
}
/**Encode http-delta
/**Encode @ref msg_delta_d() "<delta-seconds>" field.
*/
issize_t msg_delta_e(char b[], isize_t bsiz, msg_time_t delta)
{
return snprintf(b, bsiz, "%lu", (unsigned long)delta);
}
/** Decode a date or delta
/** Decode a HTTP date or delta
*
* The function msg_date_delta_d() decodes a http-date or http-delta field.
* Decode a @ref msg_date_d() "<http-date>" or
* @ref msg_delta_d() "<delta-seconds>" field.
*/
issize_t msg_date_delta_d(char const **ss,
msg_time_t *date,
msg_time_t *delta)
msg_time_t *date,
msg_time_t *delta)
{
if (delta && is_digit(**ss)) {
return msg_delta_d(ss, delta);
......
libsofia-sip-ua/msg/msg_generic.c
View file @ ddb12ded
......@@ -54,10 +54,10 @@
*
* The function msg_generic_d() parses a generic header structure.
*
* @param home memory home [IN]
* @param h header structure [IN/OUT]
* @param s string to be parsed [IN]
* @param slen length of the string [IN]
* @param[in] home memory home
* @param[in,out] h header structure
* @param[in] s string to be parsed
* @param[in] slen length of the string
*
* @retval 0 when successful,
* @retval -1 upon an error.
......
libsofia-sip-ua/msg/msg_mclass.c
View file @ ddb12ded
......@@ -64,9 +64,9 @@
* headers. This is useful if more fine-grained control of parsing process
* is required, for instance.
*
* @param old pointer to the message class object to be copied [IN]
* @param newsize size of hash table in the copied object [IN]
* @param empty if true, resulting copy does not contain any headers [IN]
* @param[in] old pointer to the message class object to be copied
* @param[in] newsize size of hash table in the copied object
* @param[in] empty if true, resulting copy does not contain any headers
*
* @return
* The function msg_mclass_clone() returns a pointer to a newly
......@@ -148,17 +148,17 @@ msg_mclass_t *msg_mclass_clone(msg_mclass_t const *old, int newsize, int empty)
* structure" is zero, the function extends the public message structure in
* order to store newly inserted header there.
*
* @param mc pointer to a message class object [IN/OUT]
* @param hc pointer to a header class object [IN]
* @param offset offset of the header in
* @ref msg_pub_t "public message structure" [IN]
* @param[in,out] mc pointer to a message class object
* @param[in] hc pointer to a header class object
* @param[in] offset offset of the header in
* @ref msg_pub_t "public message structure"
*
* If the @a offset is 0, the msg_mclass_insert_header() increases size of
* the public message structure and places the header at the end of message.
*
* @return Number of collisions in hash table, or -1 upon an error.
*
* @deprecated Use msg_mclass_insert_header_flags() instead.
* @deprecated Use msg_mclass_insert_with_mask() instead.
*/
int msg_mclass_insert_header(msg_mclass_t *mc,
msg_hclass_t *hc,
......@@ -186,19 +186,16 @@ int msg_mclass_insert_header(msg_mclass_t *mc,
*
* @relates msg_mclass_s
*
* Insert a header class @a hc to the message class object @a mc. If the
* given @a offset of the header in @ref msg_pub_t "public message
* structure" is zero, the function extends the public message structure in
* order to store headers.
* Insert a header class @a hc to the message class @a mc. If the given @a
* offset of the header in @ref msg_pub_t "public message structure" is
* zero, extend the size of the public message structure in order to store
* headers at the end of structure.
*
* @param mc pointer to a message class object [IN/OUT]
* @param hc pointer to a header class object [IN]
* @param offset offset of the header in
* @ref msg_pub_t "public message structure" [IN]
* @param flags classification flags for the header [IN]
*
* If the @a offset is 0, the msg_mclass_insert_header() increases size of
* the public message structure and places the header at the end of message.
* @param[in,out] mc pointer to a message class
* @param[in] hc pointer to a header class
* @param[in] offset offset of the header in
* @ref msg_pub_t "public message structure"
* @param[in] flags classification flags for the header
*
* @return Number of collisions in hash table, or -1 upon an error.
*/
......@@ -230,8 +227,8 @@ int msg_mclass_insert_with_mask(msg_mclass_t *mc,
*
* @relates msg_mclass_s
*
* @param mc pointer to a message class object [IN/OUT]
* @param hr header reference object [IN]
* @param[in,out] mc pointer to a message class object
* @param[in] hr header reference object
*
* @return Number of collisions in hash table, or -1 upon an error.
*/
......@@ -294,10 +291,9 @@ int msg_mclass_insert(msg_mclass_t *mc, msg_href_t const *hr)
* class based on the contents of the header to be parsed. The buffer @a s
* should point to the first character in the header name.
*
* @param mc message class object [IN]
* @param s header contents [IN]
* @param return_start_of_content start of header content [OUT]
* (may be NULL)
* @param[in] mc message class object
* @param[in] s header contents
* @param[out] return_start_of_content start of header content (may be NULL)
*
* @return The function msg_find_hclass() returns a pointer to a header
* reference structure. A pointer to a header reference for unknown headers
......
libsofia-sip-ua/msg/msg_mime.c
View file @ ddb12ded
......@@ -392,9 +392,9 @@ msg_multipart_search_boundary(su_home_t *home, char const *p, size_t len)
* The function msg_multipart_parse() parses a MIME multipart message. The
* 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]
* @param pl payload structure for multipart [IN]
* @param[in,out] home home for allocating structures
* @param[in] c content-type header for multipart
* @param[in] pl payload structure for multipart
*
* After parsing, the @a pl will contain the plain-text preamble (if any).
*
......@@ -581,9 +581,9 @@ msg_multipart_t *msg_multipart_parse(su_home_t *home,
* between body-part headers and data, and close-delimiter after last
* body-part to the multipart message.
*
* @param home home for allocating structures [IN/OUT]
* @param c content-type header for multipart [IN/OUT]
* @param mp pointer to first multipart structure [IN/OUT]
* @param[in,out] home home for allocating structures
* @param[in,out] c content-type header for multipart
* @param[in,out] mp pointer to first multipart structure
*
* @retval 0 when successful
* @retval -1 upon an error
......@@ -1002,8 +1002,8 @@ unsigned msg_q_value(char const *q)
*
* The function msg_mediatype_d() parses a mediatype string.
*
* @param ss string to be parsed [IN/OUT]
* @param type value result for media type [OUT]
* @param[in,out] ss string to be parsed
* @param[out] type value result for media type
*
* @retval 0 when successful,
* @retval -1 upon an error.
......
libsofia-sip-ua/msg/msg_parser.c
View file @ ddb12ded
......@@ -324,11 +324,11 @@ void *msg_buf_move(msg_t *dst, msg_t const *src)
* so the caller should allocate at least two elements for the I/O vector @a
* vec.
*
* @param msg message object [IN]
* @param vec I/O vector [OUT]
* @param veclen available length of @a vec [IN]
* @param n number of available bytes[IN]
* @param exact true if data ends at message boundary [IN]
* @param[in] msg message object
* @param[out] vec I/O vector
* @param[in] veclen available length of @a vec
* @param[in] n number of available bytes
* @param[in] exact true if data ends at message boundary
*
* @return
* The function msg_recv_iovec() returns the length of I/O vector to
......@@ -1939,8 +1939,8 @@ isize_t msg_iovec(msg_t *msg, msg_iovec_t vec[], isize_t veclen)
* Headers are either inserted just before the payload, or after the first
* line, depending on their type.
*
* @param msg message object [IN]
* @param pub public message structure [IN/OUT]
* @param[in] msg message object
* @param[in,out] pub public message structure
* @param prepend if true, add before same type of headers (instead after them)
* @param head head of chain
* @param h header to insert
......
libsofia-sip-ua/msg/msg_parser_util.c
View file @ ddb12ded
......@@ -163,29 +163,31 @@ issize_t msg_uint32_d(char **ss, uint32_t *return_value)
* character after the list. The function modifies the string as it parses
* it.
*
* A pointer to the resulting list is returned in the return-value parameter
* @a return_list. If there already is a list in @a return_list, new items
* are appended. Empty list items are ignored, and are not included in the
* The parsed items are appended to the list @a *append_list. If there the
* list in @a *append_list is NULL, allocate a new list and return it in @a
* *append_list. Empty list items are ignored, and are not appended to the
* list.
*
* The function must be passed a scanning function @a scanner. The scanning
* function scans for a legitimate list item, for example, a token. It
* should also compact the list item, for instance, if the item consists of
* @c name=value parameter definitions. The scanning function returns the
* length of the scanned item, including any linear whitespace after it.
*
* @param home memory home used to allocate memory for list pointers [IN]
* @param ss pointer to pointer to string to be parsed [IN/OUT]
* @param return_list return-value parameter for parsed list [IN/OUT]
* @param sep separator character [IN]
* @param scanner pointer to function scanning a single item (optional) [IN]
* The function @b must be passed a scanning function @a scanner. The
* scanning function scans for a legitimate list item, for example, a token.
* It should also compact the list item, for instance, if the item consists
* of @c name=value parameter definitions it should remove whitespace around
* "=" sign. The scanning function returns the length of the scanned item,
* including any linear whitespace after it.
*
* @param[in] home memory home for allocating list pointers
* @param[in,out] ss pointer to pointer to string to be parsed
* @param[in,out] append_list pointer to list
* where parsed list items are appended
* @param[in] sep separator character
* @param[in] scanner pointer to function for scanning a single item
*
* @retval 0 if successful.
* @retval -1 upon an error.
*/
issize_t msg_any_list_d(su_home_t *home,
char **ss,
msg_param_t **return_list,
msg_param_t **append_list,
issize_t (*scanner)(char *s),
int sep)
{
......@@ -199,8 +201,8 @@ issize_t msg_any_list_d(su_home_t *home,
if (!scanner)
return -1;
if (*return_list) {
list = *return_list;
if (*append_list) {
list = *append_list;
while (list[n])
n++;
N = MSG_PARAMS_NUM(n + 1);
......@@ -219,7 +221,7 @@ issize_t msg_any_list_d(su_home_t *home,
if (tlen > 0) {
if (n + 1 == N) { /* Reallocate list? */
N = MSG_PARAMS_NUM(N + 1);
if (list == auto_list || list == *return_list) {
if (list == auto_list || list == *append_list) {
re_list = su_alloc(home, N * sizeof(*list));
if (re_list)
memcpy(re_list, list, n * sizeof(*list));
......@@ -256,17 +258,32 @@ issize_t msg_any_list_d(su_home_t *home,
if (n == 0)
list = NULL;
*return_list = list;
*append_list = list;
return 0;
error:
*start = NULL;
if (list != auto_list && list != *return_list)
if (list != auto_list && list != *append_list)
su_free(home, list);
return -1;
}
/** Scan an attribute [= value] pair */
/** Scan an attribute (name [= value]) pair.
*
* The attribute consists of name (a token) and optional value, separated by
* equal sign. The value can be a token or quoted string.
*
* This function compacts the scanned value. It removes the
* whitespace around equal sign "=" by moving the equal sign character and
* value towards name.
*
* If there is whitespace within the scanned value or after it,
* NUL-terminates the scanned attribute.
*
* @retval > 0 number of characters scanned,
* including the whitespace within the value
* @retval -1 upon an error
*/
issize_t msg_attribute_value_scanner(char *s)
{
char *p = s;
......@@ -320,16 +337,17 @@ issize_t msg_attribute_value_scanner(char *s)
* av-pair = token ["=" ( value / quoted-string) ] ; optional value
* @endcode
*
* @param home pointer to a memory home [IN]
* @param ss pointer to string at the start of parameter list [IN/OUT]
* @param return_list return-value parameter for parsed list [IN/OUT]
* @param[in] home pointer to a memory home
* @param[in,out] ss pointer to string at the start of parameter list
* @param[in,out] append_list pointer to list
* where parsed list items are appended
*
* @retval >= 0 if successful
* @retval -1 upon an error
*/
issize_t msg_avlist_d(su_home_t *home,
char **ss,
msg_param_t const **return_list)
msg_param_t const **append_list)
{
char const *stack[MSG_N_PARAMS];
char const **params;
......@@ -339,8 +357,8 @@ issize_t msg_avlist_d(su_home_t *home,
if (!*s)
return -1;
if (*return_list) {
params = (char const **)*return_list;
if (*append_list) {
params = (char const **)*append_list;
for (n = 0; params[n]; n++)
;
N = MSG_PARAMS_NUM(n + 1);
......@@ -429,7 +447,7 @@ issize_t msg_avlist_d(su_home_t *home,
params[n] = NULL;
*return_list = params;
*append_list = params;
return 0;
......@@ -446,9 +464,10 @@ issize_t msg_avlist_d(su_home_t *home,
* *(";" token [ "=" (token | quoted-string)]).
* @endcode
*
* @param home pointer to a memory home [IN]
* @param ss pointer to string at the start of parameter list [IN/OUT]
* @param return_list return-value parameter for the parsed list [IN/OUT]
* @param[in] home pointer to a memory home
* @param[in,out] ss pointer to string at the start of parameter list
* @param[in,out] append_list pointer to list
* where parsed list items are appended
*
* @retval >= 0 if successful
* @retval -1 upon an error
......@@ -457,12 +476,12 @@ issize_t msg_avlist_d(su_home_t *home,
*/
issize_t msg_params_d(su_home_t *home,
char **ss,
msg_param_t const **return_list)
msg_param_t const **append_list)
{
if (**ss == ';') {
*(*ss)++ = '\0';
*return_list = NULL;
return msg_avlist_d(home, ss, return_list);
*append_list = NULL;
return msg_avlist_d(home, ss, append_list);
}
if (IS_LWS(**ss)) {
......@@ -543,21 +562,23 @@ char *msg_params_dup(msg_param_t const **d, msg_param_t const s[],
* By default, the scanning function accepts tokens, quoted strings or
* separators (except comma, of course).
*
* @param home memory home used to allocate memory for list pointers [in]
* @param ss pointer to pointer to string to be parsed [in/out]
* @param return_list return-value parameter for parsed list [in/out]
* @param scanner pointer to function scanning a single item (optional) [in]
* @param[in] home memory home for allocating list pointers
* @param[in,out] ss pointer to pointer to string to be parsed
* @param[in,out] append_list pointer to list
* where parsed list items are appended
* @param[in] scanner pointer to function scanning a single item
* (optional)
*
* @retval 0 if successful.
* @retval -1 upon an error.
*/
issize_t msg_commalist_d(su_home_t *home,
char **ss,
msg_param_t **return_list,
msg_param_t **append_list,
issize_t (*scanner)(char *s))
{
scanner = scanner ? scanner : msg_comma_scanner;
return msg_any_list_d(home, ss, return_list, scanner, ',');
return msg_any_list_d(home, ss, append_list, scanner, ',');
}
/** Token scanner for msg_commalist_d() accepting also empty entries. */
......
libsofia-sip-ua/msg/sofia-sip/msg_parser.h
View file @ ddb12ded
......@@ -202,14 +202,15 @@ SOFIAPUBFUN issize_t msg_unquoted_e(char *b, isize_t bsiz, char const *s);
#define MSG_STRING_SIZE(s) ((s) ? (strlen(s) + 1) : 0)
SOFIAPUBFUN issize_t msg_commalist_d(su_home_t *, char **ss,
msg_param_t **return_list,
msg_param_t **append_list,
issize_t (*scanner)(char *s));
SOFIAPUBFUN issize_t msg_token_scan(char *start);
SOFIAPUBFUN issize_t msg_attribute_value_scanner(char *s);
SOFIAPUBFUN issize_t msg_any_list_d(su_home_t *, char **ss,
msg_param_t **retval,
issize_t (*scanner)(char *s), int sep);
msg_param_t **append_list,
issize_t (*scanner)(char *s),
int sep);
/** Encode a comma-separated parameter list */
#define MSG_COMMALIST_E(b, end, params, compact) do { \
......
libsofia-sip-ua/msg/sofia-sip/msg_types.h
View file @ ddb12ded
......@@ -275,8 +275,7 @@ struct msg_hclass_s
char hc_short[2];/**< Short name, if any. */
unsigned char hc_size; /**< Size of header structure. */
unsigned char hc_params; /**< Offset of parameters */
unsigned /* msg_header_kind_t */
hc_kind:3; /**< Kind of header:
unsigned hc_kind:3; /**< Kind of header (#msg_header_kind_t):
* single, append, list, apndlist, prepend. */
unsigned hc_critical:1; /**< True if header is critical */
unsigned /*pad*/:0;
......
libsofia-sip-ua/msg/test_class.c
View file @ ddb12ded
......@@ -195,15 +195,15 @@ char *msg_status_dup_one(msg_header_t *dst, msg_header_t const *src,
/** Extract the message body, including separator line.
*
* @param msg message object [IN]
* @param pub public message structure [IN/OUT]
* @param b buffer containing unparsed data [IN]
* @param bsiz buffer size [IN]
* @param eos true if buffer contains whole message [IN]
* @param[in,out] msg message object
* @param[in,out] pub public message structure
* @param[in] b buffer containing unparsed data
* @param[in] bsiz buffer size
* @param[in] eos true if buffer contains whole message
*
* @retval -1 error
* @retval 0 message is incomplete
* @retval other number of bytes extracted
* @retval -1 error
* @retval 0 message is incomplete
* @retval other number of bytes extracted
*/
issize_t msg_test_extract_body(msg_t *msg, msg_pub_t *pub,
char b[], isize_t bsiz, int eos)
......
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