Commit 4642c395 authored by Pekka Pessi's avatar Pekka Pessi

msg module: updated documentation.

darcs-hash:20060912115343-65a35-62633f7082be55463d0a0a2782be2f06f69c9a4d.gz
parent 0fad09ba
......@@ -5,10 +5,11 @@ INPUT = msg.docs . sofia-sip
@INCLUDE = ../docs/Doxyfile.conf
TAGFILES += ../docs/doxytags_ipt=../ipt \
../docs/doxytags_su=../su \
../docs/doxytags_sip=../sip \
../docs/doxytags_http=../http
TAGFILES += ../docs/doxytags_ipt=../ipt \
../docs/doxytags_su=../su \
../docs/doxytags_sip=../sip \
../docs/doxytags_nta=../nta \
../docs/doxytags_http=../http
GENERATE_TAGFILE = ../docs/doxytags_msg
......
......@@ -90,14 +90,14 @@ msg_t *msg_create(msg_mclass_t const *mc, int flags)
*
* @relates msg_s
*
* The function msg_ref_create() creates a reference to a message. The
* Creates a reference to a message. The
* referenced message is not freed until all the references have been
* destroyed.
*
* @param msg message of which a reference is created
*
* @return
* The function msg_ref_create() returns a reference to a message.
* A pointer to a message.
*/
msg_t *msg_ref_create(msg_t *msg)
{
......@@ -135,6 +135,10 @@ void msg_set_parent(msg_t *kid, msg_t *dad)
/** Destroy a reference to a message.
*
* @relates msg_s
*
* @param ref pointer to msg object
*
* @deprecated Use msg_destroy() instead.
*/
void msg_ref_destroy(msg_t *ref)
{
......@@ -169,7 +173,7 @@ void msg_destroy(msg_t *msg)
/**Retrieve public message structure.
*
* This function returns a pointer to the public message structure.
* Get a pointer to the public message structure.
*
* @param msg pointer to msg object
*
......@@ -188,7 +192,7 @@ msg_pub_t *msg_object(msg_t const *msg)
*
* @relates msg_s
*
* This function returns a pointer to the public message structure of the
* Get a pointer to the public message structure of the
* given protocol.
*
* @param msg pointer to msg object
......@@ -210,7 +214,7 @@ msg_pub_t *msg_public(msg_t const *msg, void *tag)
*
* @relates msg_s
*
* The function msg_mclass() returns a pointer to the message class object
* Get a pointer to the message class object
* (factory object for the message).
*
* @param msg pointer to msg object
......@@ -228,7 +232,14 @@ msg_mclass_t const *msg_mclass(msg_t const *msg)
/* Address management */
/** Zero the message address */
/** Zero the message address.
*
* @relates msg_s
*
* Zero the address and addressinfo structures associated with the message.
*
* @sa msg_addrinfo(), msg_set_address(), msg_get_address(), msg_addr_copy().
*/
void msg_addr_zero(msg_t *msg)
{
memset(&msg->m_addr, 0, sizeof(&msg->m_addr));
......@@ -239,6 +250,8 @@ void msg_addr_zero(msg_t *msg)
}
/** Get pointer to socket address structure.
*
* @relates msg_s
*
* @deprecated Use msg_get_address() or msg_set_address() instead.
*/
......@@ -247,7 +260,20 @@ su_sockaddr_t *msg_addr(msg_t *msg)
return msg ? msg->m_addr : 0;
}
/** Get message address. */
/** Get message address.
*
* @relates msg_s
*
* Copy the socket address associated with the message to the supplied
* socket address struture.
*
* @param msg pointer to msg object
* @param su pointer to socket address structure
* @param return_len return parameter value for length
* of socket address structure
*
* @sa msg_addrinfo(), msg_set_address(), msg_addr_zero(), msg_addr_copy().
*/
int msg_get_address(msg_t *msg, su_sockaddr_t *su, socklen_t *return_len)
{
if (msg && return_len && *return_len >= msg->m_addrinfo.ai_addrlen) {
......@@ -261,7 +287,19 @@ int msg_get_address(msg_t *msg, su_sockaddr_t *su, socklen_t *return_len)
return -1;
}
/** Set message address. */
/** Set message address.
*
* @relates msg_s
*
* Copy the supplied socket address to the socket address structure
* associated with the message.
*
* @param msg pointer to msg object
* @param su pointer to socket address structure
* @param sulen length of socket address structure
*
* @sa msg_addrinfo(), msg_get_address(), msg_addr_zero(), msg_addr_copy().
*/
int msg_set_address(msg_t *msg, su_sockaddr_t const *su, socklen_t sulen)
{
if (sulen < (sizeof msg->m_addr) && msg && su) {
......@@ -274,13 +312,35 @@ int msg_set_address(msg_t *msg, su_sockaddr_t const *su, socklen_t sulen)
return -1;
}
/** Get addrinfo structure. */
/** Get addrinfo structure.
*
* @relates msg_s
*
* Get pointer to the addrinfo structure associated with the message.
*
* @param msg pointer to msg object
*
* @retval pointer to addrinfo structure
* @retval NULL if msg is NULL
*
* @sa msg_get_address(), msg_set_address(), msg_addr_zero(), msg_addr_copy().
*/
su_addrinfo_t *msg_addrinfo(msg_t *msg)
{
return msg ? &msg->m_addrinfo : 0;
}
/**Copy message address.
*
* @relates msg_s
*
* Copy the addrinfo and socket address structures from @a src to the @a dst
* message object.
*
* @param dst pointer to destination message object
* @param src pointer to source message object
*
* @sa msg_addrinfo(), msg_get_address(), msg_set_address(), msg_addr_zero().
*/
void msg_addr_copy(msg_t *dst, msg_t const *src)
{
......@@ -295,20 +355,53 @@ void msg_addr_copy(msg_t *dst, msg_t const *src)
}
/** Get error classification flags */
/** Get error classification flags.
*
* @relates msg_s
*
* If the message parser fails to parse certain headers in the message, it
* sets the corresponding extract error flags. The flags corresponding to
* each header are stored in the message parser (msg_mclass_t) structure.
* They are set when the header is added to the parser table.
*
* The SIP flags are defined in <sofia-sip/sip_headers.h>. For well-known
* SIP headers, the flags for each header are listed in a separate text file
* (sip_bad_mask) read by msg_parser.awk.
*
* The flags can be used directly by NTA (the mask triggering 400 response
* is set with NTATAG_BAD_REQ_MASK(), the mask triggering response messages
* to be dropped is set with NTATAG_BAD_RESP_MASK()). Alternatively the
* application can check them based on the method or required SIP features.
*
* @sa msg_mclass_insert_with_mask(), NTATAG_BAD_REQ_MASK(),
* NTATAG_BAD_RESP_MASK().
*/
unsigned msg_extract_errors(msg_t const *msg)
{
return msg ? msg->m_extract_err : (unsigned)-1;
}
/** Get error number associated with message */
/** Get error number associated with message.
*
* @relates msg_s
*
* @param msg pointer to msg object
*
*/
int msg_errno(msg_t const *msg)
{
return msg ? msg->m_errno : EINVAL;
}
/** Set error number associated with message */
/** Set error number associated with message.
*
* @relates msg_s
*
* @param msg pointer to msg object
* @param err error value (as defined in <sofia-sip/su_errno.h>).
*
*/
void msg_set_errno(msg_t *msg, int err)
{
if (msg)
......
......@@ -50,8 +50,7 @@
/**
* Scan and compact an authentication parameter.
*
* The function msg_auth_item_scan() is used to scan an authentication
* parameter, which has syntax as follows:
* Scan an authentication parameter, which has syntax as follows:
* @code
* auth-item = auth-param | base64-string
* auth-param = token [ "=" (token | quoted-string)]
......@@ -60,9 +59,7 @@
* Parameters:
* @param s pointer to string to scan
*
* @return
* The function msg_auth_item_scan() returns number of characters scanned,
* or zero upon an error.
* @return Number of characters scanned, or zero upon an error.
*/
static int msg_auth_item_scan(char *start)
{
......
......@@ -373,6 +373,9 @@ static int msg_dup_or_copy_all(msg_t *msg,
* the copies have been destroyed.
*
* @param original message to be copied
*
* @retval pointer to newly copied message object when successful
* @retval NULL upon an error
*/
msg_t *msg_copy(msg_t *original)
{
......@@ -385,8 +388,7 @@ msg_t *msg_copy(msg_t *original)
: msg_dup_or_copy_all(copy, original, msg_header_copy_one) < 0) {
msg_destroy(copy), copy = NULL;
}
if (copy)
else
msg_set_parent(copy, original);
return copy;
......@@ -396,6 +398,11 @@ msg_t *msg_copy(msg_t *original)
return NULL;
}
/** Copy header chain.
*
* @retval 0 when successful
* @retval -1 upon an error
*/
static
int msg_copy_chain(msg_t *msg, msg_t const *original)
{
......@@ -442,6 +449,9 @@ int msg_copy_chain(msg_t *msg, msg_t const *original)
* Note that the cached representation (in h_data) is not copied.
*
* @param original message to be duplicated
*
* @retval pointer to newly duplicated message object when successful
* @retval NULL upon an error
*/
msg_t *msg_dup(msg_t const *original)
{
......@@ -458,7 +468,11 @@ msg_t *msg_dup(msg_t const *original)
return NULL;
}
/** Copy a complete message, not keeping the header chain structure. */
/** Copy a complete message, not keeping the header chain structure.
*
* @retval 0 when successful
* @retval -1 upon an error
*/
static
int msg_dup_or_copy_all(msg_t *msg,
msg_t const *original,
......
......@@ -223,7 +223,7 @@ union msg_mime_u
* msg_multipart_t *mp = NULL;
* msg_header_t *h = NULL;
* char *b;
* int len, offset;
* size_t len, offset;
*
* mp = msg_multipart_create(home, "text/html;level=3", html, strlen(html));
* mp->mp_next = msg_multipart_create(home, "image/gif", gif, giflen);
......@@ -577,18 +577,16 @@ msg_multipart_t *msg_multipart_parse(su_home_t *home,
/**Add all missing parts to the multipart.
*
* The function msg_multipart_complete() adds missing components to the
* multipart message. The missing components may include boundaries between
* body parts, separators between body-part headers and data, and
* close-delimiter after last body-part.
* Add missing components such as boundaries between body parts, separators
* 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]
*
* @return
* The function msg_multipart_complete() returns 0 when successful,
* -1 upon an error.
* @retval 0 when successful
* @retval -1 upon an error
*
* @ERRORS
* @ERROR EBADMSG
......
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