Commit d4bb5ce1 authored by Pekka Pessi's avatar Pekka Pessi

sip: updated doxygen docs. Using aliased links to header groups like @Contact.

darcs-hash:20060914123747-65a35-2e517433f61e69013efdd56beac69abc71f72272.gz
parent e667cc38
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
......@@ -25,9 +25,8 @@
/**@CFILE sip_event.c
* @brief Event SIP headers.
*
* The file @b sip_event.c contains implementation of header classes for
* event-related SIP headers @b Event, @b Allow-Events, and
* @b Subscription-State.
* Implementation of header classes for event-related SIP headers @Event,
* @AllowEvents, and @SubscriptionState.
*
* @author Pekka Pessi <Pekka.Pessi@nokia.com>.
*
......@@ -65,14 +64,16 @@
* / "_" / "+" / "`" / "'" / "~" )
* event-param = generic-param / ( "id" EQUAL token )
* @endcode
*
* The parsed Event header is stored in #sip_event_t structure.
*/
/**@ingroup sip_event
* @typedef struct sip_event_s sip_event_t;
*
* The structure sip_event_t contains representation of an @b Event header.
* The structure #sip_event_t contains representation of an @Event header.
*
* The sip_event_t is defined as follows:
* The #sip_event_t is defined as follows:
* @code
* typedef struct sip_event_s
* {
......@@ -80,7 +81,7 @@
* sip_error_t *o_next; // Link to next (dummy)
* char const * o_type; // Event type
* msg_param_t const *o_params; // List of parameters
* msg_param_t o_id; // Event ID
* char const *o_id; // Event ID
* } sip_event_t;
* @endcode
*/
......@@ -130,7 +131,7 @@ isize_t sip_event_dup_xtra(sip_header_t const *h, isize_t offset)
return offset;
}
/** Duplicate one sip_event_t object */
/** Duplicate one #sip_event_t object */
char *sip_event_dup_one(sip_header_t *dst, sip_header_t const *src,
char *b, isize_t xtra)
{
......@@ -145,7 +146,7 @@ char *sip_event_dup_one(sip_header_t *dst, sip_header_t const *src,
return b;
}
/** Update parameters in Event header. */
/** Update parameters in @Event header. */
static int sip_event_update(msg_common_t *h,
char const *name, isize_t namelen,
char const *value)
......@@ -164,9 +165,9 @@ static int sip_event_update(msg_common_t *h,
/* ====================================================================== */
/**@SIP_HEADER sip_allow_events Allow-Event Header
/**@SIP_HEADER sip_allow_events Allow-Events Header
*
* The Allow-Event header is used to indicate which events or classes of
* The Allow-Events header is used to indicate which events or classes of
* events the notifier supports. Its syntax is defined in @RFC3265 as
* follows:
*
......@@ -174,15 +175,17 @@ static int sip_event_update(msg_common_t *h,
* Allow-Events = ( "Allow-Events" | "u" ) ":" 1#event-type
* @endcode
*
*
* The parsed Allow-Events header is stored in #sip_allow_events_t structure.
*/
/**@ingroup sip_allow_events
* @typedef struct msg_list_s sip_allow_events_t;
*
* The structure sip_allow_events_t contains representation of an @b
* Allow-Events header.
* The structure #sip_allow_events_t contains representation of an
* @AllowEvents header.
*
* The sip_allow_events_t is defined as follows:
* The #sip_allow_events_t is defined as follows:
* @code
* typedef struct msg_list_s
* {
......@@ -207,7 +210,7 @@ issize_t sip_allow_events_e(char b[], isize_t bsiz, sip_header_t const *h, int f
return msg_list_e(b, bsiz, h, f);
}
/** Append an event to a Allow-Events header.
/** Append an event to a @AllowEvents header.
*
* @note This function @b does @b duplicate @p event.
*
......@@ -250,15 +253,18 @@ int sip_allow_events_add(su_home_t *home,
* / event-reason-extension
* event-reason-extension = token
* @endcode
*
* The parsed Subscription-State header
* is stored in #sip_subscription_state_t structure.
*/
/**@ingroup sip_subscription_state
* @typedef struct sip_subscription_state_s sip_subscription_state_t;
*
* The structure sip_subscription_state_t contains representation of an @b
* Subscription-State header.
* The structure #sip_subscription_state_t contains representation of an
* @SubscriptionState header.
*
* The sip_subscription_state_t is defined as follows:
* The #sip_subscription_state_t is defined as follows:
* @code
* typedef struct sip_subscription_state_s
* {
......@@ -267,9 +273,9 @@ int sip_allow_events_add(su_home_t *home,
* // Subscription state: "pending", "active" or "terminated"
* char const *ss_substate;
* msg_param_t const *ss_params; // List of parameters
* msg_param_t ss_reason; // Reason of terminating
* msg_param_t ss_expires; // Subscription lifetime in seconds
* msg_param_t ss_retry_after; // Value of retry-after parameter
* char const *ss_reason; // Reason of terminating
* char const *ss_expires; // Subscription lifetime in seconds
* char const *ss_retry_after; // Value of retry-after parameter
* } sip_subscription_state_t;
* @endcode
*/
......@@ -331,7 +337,7 @@ isize_t sip_subscription_state_dup_xtra(sip_header_t const *h, isize_t offset)
return offset;
}
/** Duplicate one sip_subscription_state_t object */
/** Duplicate one #sip_subscription_state_t object */
char *sip_subscription_state_dup_one(sip_header_t *dst, sip_header_t const *src,
char *b, isize_t xtra)
{
......@@ -395,6 +401,8 @@ static int sip_subscription_state_update(msg_common_t *h,
* ptype = "type" EQUAL token
* @endcode
*
*
* The parsed Publication header is stored in #sip_publication_t structure.
*/
/**@ingroup sip_publication
......@@ -457,7 +465,7 @@ isize_t sip_publication_dup_xtra(sip_header_t const *h, isize_t offset)
return offset;
}
/** Duplicate one sip_publication_t object */
/** Duplicate one #sip_publication_t object */
char *sip_publication_dup_one(sip_header_t *dst, sip_header_t const *src,
char *b, isize_t xtra)
{
......@@ -500,6 +508,9 @@ static inline void sip_publication_update(sip_publication_t *pub)
* * ( COMMA publish-type )
* @endcode
*
*
* The parsed Allow-Publication Header
* is stored in #sip_allow_publications_t structure.
*/
msg_hclass_t sip_allow_publications_class[] =
......
This diff is collapsed.
......@@ -49,21 +49,22 @@
/**@SIP_HEADER sip_allow Allow Header
*
* The Allow header lists the set of methods supported by the user agent
* generating the message. Its syntax is defined in [S10.10] as
* generating the message. Its syntax is defined in @RFC3261 as
* follows:
*
* @code
* Allow = "Allow" HCOLON [Method *(COMMA Method)]
* @endcode
*
* The parsed Allow header is stored in #sip_allow_t structure.
*/
/**@ingroup sip_allow
* @typedef struct msg_list_s sip_allow_t;
*
* The structure sip_allow_t contains representation of an @b Allow header.
* The structure #sip_allow_t contains representation of an @Allow header.
*
* The sip_allow_t is defined as follows:
* The #sip_allow_t is defined as follows:
* @code
* typedef struct msg_list_s
* {
......@@ -94,27 +95,29 @@ issize_t sip_allow_e(char b[], isize_t bsiz, sip_header_t const *h, int f)
/**@SIP_HEADER sip_proxy_require Proxy-Require Header
*
* The Proxy-Require header is used to indicate proxy-sensitive features
* that @b MUST be supported by the proxy. Its syntax is defined in [S10.33]
* that @b MUST be supported by the proxy. Its syntax is defined in @RFC3261
* as follows:
*
* @code
* Proxy-Require = "Proxy-Require" HCOLON option-tag *(COMMA option-tag)
* @endcode
*
*
* The parsed Proxy-Require header is stored in #sip_proxy_require_t structure.
*/
/**@ingroup sip_proxy_require
* @typedef struct msg_list_s sip_proxy_require_t;
*
* The structure sip_proxy_require_t contains representation of an @b
* Proxy-Require header.
* The structure #sip_proxy_require_t contains representation of an
* @ProxyRequire header.
*
* The sip_proxy_require_t is defined as follows:
* The #sip_proxy_require_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_list_t *k_next; // Dummy link
* msg_param_t *k_items; // List of items
* } sip_proxy_require_t;
* @endcode
......@@ -141,22 +144,23 @@ issize_t sip_proxy_require_e(char b[], isize_t bsiz, sip_header_t const *h, int
*
* The Require header is used by clients to tell user agent servers about
* options that the client expects the server to support in order to
* properly process the request. Its syntax is defined in [S10.35]
* properly process the request. Its syntax is defined in @RFC3261
* as follows:
*
* @code
* Require = "Require" HCOLON option-tag *(COMMA option-tag)
* @endcode
*
* The parsed Require header is stored in #sip_require_t structure.
*/
/**@ingroup sip_require
* @typedef struct msg_list_s sip_require_t;
*
* The structure sip_require_t contains representation of an @b
* Require header.
* The structure #sip_require_t contains representation of an
* @Require header.
*
* The sip_require_t is defined as follows:
* The #sip_require_t is defined as follows:
* @code
* typedef struct msg_list_s
* {
......@@ -187,22 +191,24 @@ issize_t sip_require_e(char b[], isize_t bsiz, sip_header_t const *h, int f)
/**@SIP_HEADER sip_supported Supported Header
*
* The Supported header enumerates all the capabilities of the client or
* server. Its syntax is defined in [S10.41] as follows:
* server. Its syntax is defined in @RFC3261 as follows:
*
* @code
* Supported = ( "Supported" / "k" ) HCOLON
* [option-tag *(COMMA option-tag)]
* @endcode
*
* The parsed option-tags of Supported header
* are stored in #sip_supported_t structure.
*/
/**@ingroup sip_supported
* @typedef struct msg_list_s sip_supported_t;
*
* The structure sip_supported_t contains representation of an @b
* Supported header.
* The structure #sip_supported_t contains representation of an
* @Supported header.
*
* The sip_supported_t is defined as follows:
* The #sip_supported_t is defined as follows:
* @code
* typedef struct msg_list_s
* {
......@@ -234,21 +240,23 @@ issize_t sip_supported_e(char b[], isize_t bsiz, sip_header_t const *h, int f)
/**@SIP_HEADER sip_unsupported Unsupported Header
*
* The Unsupported header lists the features not supported by the server.
* Its syntax is defined in [S20.40] as follows:
* Its syntax is defined in @RFC3261 as follows:
*
* @code
* Unsupported = "Unsupported" HCOLON [option-tag *(COMMA option-tag)]
* @endcode
*
*
* The parsed Unsupported header is stored in #sip_unsupported_t structure.
*/
/**@ingroup sip_unsupported
* @typedef struct msg_list_s sip_unsupported_t;
*
* The structure sip_unsupported_t contains representation of an @b
* Unsupported header.
* The structure #sip_unsupported_t contains representation of an
* @Unsupported header.
*
* The sip_unsupported_t is defined as follows:
* The #sip_unsupported_t is defined as follows:
* @code
* typedef struct msg_list_s
* {
......@@ -277,7 +285,7 @@ issize_t sip_unsupported_e(char b[], isize_t bsiz, sip_header_t const *h, int f)
/** Check if required feature is supported.
*
* @retval NULL if all the required features are supported
* @retval pointer to a @b Unsupported header or
* @retval pointer to a @Unsupported header or
* #SIP_NONE if @a home is NULL
*/
sip_unsupported_t *sip_has_unsupported(su_home_t *home,
......@@ -292,7 +300,7 @@ sip_unsupported_t *sip_has_unsupported(su_home_t *home,
/** Check if required feature is supported.
*
* @retval NULL if all the required features are supported
* @retval pointer to a @b Unsupported header or
* @retval pointer to a @Unsupported header or
* #SIP_NONE if @a home is NULL
*/
sip_unsupported_t *
......@@ -310,23 +318,23 @@ sip_has_unsupported2(su_home_t *home,
/** Ensure that required features are supported.
*
* The supported features can be listed in @b Supported, @b Require or @b
* Proxy-Require headers (in @a supported, @a by_require, or @a
* The supported features can be listed in @Supported, @Require or
* @ProxyRequire headers (in @a supported, @a by_require, or @a
* by_proxy_require parameters, respectively)
*
* @param home (optional) home pointer for allocating @b Unsupported header
* @param supported @b Supported features (may be NULL) [IN]
* @param home (optional) home pointer for allocating @Unsupported header
* @param supported @Supported features (may be NULL) [IN]
* @param by_require supported features listed by
* @b Require (may be NULL) [IN]
* @Require (may be NULL) [IN]
* @param by_proxy_require supported features listed
* by @b Proxy-Require (may be NULL) [IN]
* by @ProxyRequire (may be NULL) [IN]
*
* @param require list of required features (may be NULL) [IN]
* @param require2 2nd list of required features (may be NULL) [IN]
* @param require3 3rd list of required features (may be NULL) [IN]
*
* @retval NULL if all the required features are supported
* @retval pointer to a @b Unsupported header or
* @retval pointer to a @Unsupported header or
* #SIP_NONE if @a home is NULL
*/
sip_unsupported_t *
......@@ -432,7 +440,7 @@ int sip_has_supported(sip_supported_t const *supported, char const *feature)
/**@SIP_HEADER sip_path Path Header
*
* The Path header field is a SIP extension header field (@RFC3327) with
* syntax very similar to the Record-Route header field. It is used in
* syntax very similar to the @RecordRoute header field. It is used in
* conjunction with SIP REGISTER requests and with 200 class messages in
* response to REGISTER (REGISTER responses).
*
......@@ -441,20 +449,22 @@ int sip_has_supported(sip_supported_t const *supported, char const *feature)
* path-value = name-addr *( SEMI rr-param )
* @endcode
*
*
* The parsed Path header is stored in #sip_path_t structure.
*/
/**@ingroup sip_path
* @typedef typedef struct sip_route_s sip_path_t;
*
* The structure #sip_path_t contains representation of SIP @b Path header.
* The structure #sip_path_t contains representation of SIP @Path header.
*
* The #sip_path_t is defined as follows:
* @code
* typedef struct sip_route_s {
* sip_common_t r_common[1]; // Common fragment info
* sip_path_t *r_next; // Link to next Path
* sip_path_t *r_next; // Link to next @Path
* char const *r_display; // Display name
* url_t r_url[1]; // Path URL
* url_t r_url[1]; // @Path URL
* msg_param_t const *r_params; // List of parameters
* } sip_path_t;
* @endcode
......@@ -492,19 +502,22 @@ issize_t sip_path_e(char b[], isize_t bsiz, sip_header_t const *h, int flags)
* sr-value = name-addr *( SEMI rr-param )
* @endcode
*
* The parsed Service-Route header is stored in #sip_service_route_t structure.
*
* @sa @RFC3608, @Path, @Route, @RecordRoute
*/
/**@ingroup sip_service_route
* @typedef typedef struct sip_route_s sip_service_route_t;
*
* The structure #sip_service_route_t contains representation of SIP
* @b Service-Route header.
* @ServiceRoute header.
*
* The #sip_service_route_t is defined as follows:
* @code
* typedef struct sip_route_s {
* sip_common_t r_common[1]; // Common fragment info
* sip_service_route_t*r_next; // Link to next Service-Route
* sip_service_route_t*r_next; // Link to next @ServiceRoute
* char const *r_display; // Display name
* url_t r_url[1]; // Service-Route URL
* msg_param_t const *r_params; // List of parameters
......
This diff is collapsed.
......@@ -127,7 +127,7 @@ issize_t sip_extract_body(msg_t *msg, sip_t *sip, char b[], isize_t bsiz, int eo
/** Parse SIP version.
*
* The function sip_version_d() parses a SIP version string. It updates the
* Parse a SIP version string. Update the
* pointer at @a ss to first non-LWS character after the version string.
*
* @param ss string to be parsed [IN/OUT]
......@@ -255,24 +255,24 @@ char const *sip_method_name(sip_method_t method, char const *name)
/**Parse a SIP method name.
*
* The function sip_method_d() parses a SIP method, and returns a code
* corresponding to the method. It stores the address of the first non-LWS
* character after method name in @a *ss.
* Parse a SIP method name and return a code corresponding to the method.
* The address of the first non-LWS character after method name is stored in
* @a *ss.
*
* @param ss pointer to pointer to string to be parsed
* @param return_name value-result parameter for method name
*
* @note
* If there is no whitespace after method name, the value in @a *nname
* If there is no whitespace after method name, the value in @a *return_name
* may not be NUL-terminated. The calling function @b must NUL terminate
* the value by setting the @a **ss to NUL after first examining its value.
*
* @return The function sip_method_d returns the method code if method
* @return The method code if method
* was identified, 0 (sip_method_unknown()) if method is not known, or @c -1
* (sip_method_invalid()) if an error occurred.
*
* If the value-result argument @a nname is not @c NULL, sip_method_d()
* stores a pointer to the method name to it.
* If the value-result argument @a return_name is not @c NULL,
* a pointer to the method name is stored to it.
*/
sip_method_t sip_method_d(char **ss, char const **return_name)
{
......@@ -494,8 +494,8 @@ char *sip_word_at_word_d(char **ss)
/**Add message separator, then test if message is complete.
*
* Add sip_content_length and sip_separator if they are missing.
* The test that all necessary message components (@b From, @b To, @b
* CSeq, @b Call-ID, @b Content-Length and message separator are present.
* The test that all necessary message components ( @From, @To,
* @CSeq, @CallID, @ContentLength and message separator are present.
*
* @retval 0 when successful
* @retval -1 upon an error: headers are missing and they could not be added
......
......@@ -26,7 +26,7 @@
* @brief SIP headers for Prack.
*
* The file @b sip_prack.c contains implementation of header classes for
* PRACK-related SIP headers @b RAck and @b RSeq.
* PRACK-related SIP headers @RAck and @RSeq.
*
* @author Pekka Pessi <Pekka.Pessi@nokia.com>.
*
......@@ -53,14 +53,37 @@
*
* The RAck header indicates the sequence number of the provisional response
* which is being acknowledged. Its syntax is defined in
* draft-ietf-sip-100rel-04.txt section 5 as follows:
* @RFC3262 section 10 as follows:
*
* @code
* RAck = "RAck" ":" response-num CSeq-num Method
* RAck = "RAck" HCOLON response-num LWS CSeq-num LWS Method
* response-num = 1*DIGIT
* CSeq-num = 1*DIGIT
* @endcode
*
* @sa @RFC3262, nta_outgoing_prack(), nta_reliable_treply(),
* nta_reliable_mreply().
*
* The parsed RAck header is stored in #sip_rack_t structure.
*/
/**@ingroup sip_rack
* @typedef struct sip_rack_s sip_rack_t;
*
* The structure #sip_rack_t contains representation of an @RAck header.
*
* The #sip_rack_t is defined as follows:
* @code
* typedef struct sip_rack_s
* {
* sip_common_t ra_common; // Common fragment info
* sip_error_t *ra_next; // Dummy link to next
* uint32_t ra_response; // Sequence number of response
* uint32_t ra_cseq; // Sequence number of request
* sip_method_t ra_method; // Original request method
* char const *ra_method_name; // Original request method name
* } sip_rack_t;
* @endcode
*/
static msg_xtra_f sip_rack_dup_xtra;
......@@ -111,7 +134,7 @@ isize_t sip_rack_dup_xtra(sip_header_t const *h, isize_t offset)
return offset;
}
/** Duplicate one sip_rack_t object */
/** Duplicate one #sip_rack_t object */
char *sip_rack_dup_one(sip_header_t *dst, sip_header_t const *src,
char *b, isize_t xtra)
{
......@@ -138,17 +161,32 @@ char *sip_rack_dup_one(sip_header_t *dst, sip_header_t const *src,
/**@SIP_HEADER sip_rseq RSeq Header
*
* The RSeq header identifies provisional responses within a transaction.
* Its syntax is defined in draft-ietf-sip-100rel-04.txt section 5 as
* follows:
* The RSeq header identifies provisional responses within a transaction.
* Its syntax is defined in @RFC3262 section 10 as follows:
*
* @code
* RSeq = "RSeq" ":" response-num
* RSeq = "RSeq" HCOLON response-num
* response-num = 1*DIGIT
* @endcode
*
* The parsed RSeq header is stored in #sip_rseq_t structure.
*/
/**@ingroup sip_rseq
* @typedef struct sip_rseq_s sip_rseq_t;
*
* The structure #sip_rseq_t contains representation of an @RSeq header.
*
* The #sip_rseq_t is defined as follows:
* @code
* typedef struct sip_rseq_s
* {
* sip_common_t rs_common; // Common fragment info
* sip_error_t *rs_next; // Dummy link to next
* uint32_t rs_response; // Sequence number of response
* } sip_rseq_t;
* @endcode
*/
msg_hclass_t sip_rseq_class[] =
SIP_HEADER_CLASS(rseq, "RSeq", "", rs_common, single, any);
......
......@@ -186,20 +186,19 @@ int sip_prefs_match(union sip_pref const *a,
/**Find a matching parameter-value pair from a parameter list.
*
* The function sip_prefs_matching() checks if the given feature values match
* with each other.
* Check if the given feature values match with each other.
*
* @param pvalue first feature parameter
* @param nvalue second feature parameter
* @param return_parse_error return-value parameter for error (may be NULL)
*
* @return
* The function sip_prefs_match() returns 1, if given feature parameters
* match. The function sip_prefs_match() returns 0, if there is no match or
* a parse or type error occurred.
* @retval 1 if given feature parameters match
* @retval 0 if there is no match or a parse or type error occurred.
*
* If there is a parsing or type error, 0 is returned and @a
* return_parse_error is set to -1.
* *return_parse_error is set to -1.
*
* @sa sip_prefs_parse(), sip_prefs_match(), union #sip_pref.
*/
int sip_prefs_matching(char const *pvalue,
char const *nvalue,
......@@ -249,7 +248,19 @@ int sip_prefs_matching(char const *pvalue,
return 0;
}
/** Check if the parameter is a valid feature tag. */
/** Check if the parameter is a valid feature tag.
*
* A feature tag is a parameter starting with a single plus, or a well-known
* feature tag listed in @RFC3841: "audio", "automata", "application",
* "class", "control", "duplex", "data", "description", "events", "isfocus",
* "language", "mobility", "methods", "priority", "schemes", "type", or
* "video". However, well-known feature tag can not start with plus. So,
* "+alarm" or "audio" is a feature tag, "alarm", "++alarm", or "+audio" are
* not.
*
* @retval 1 if string is a feature tag parameter
* @retval 0 otherwise
*/
int sip_is_callerpref(char const *param)
{
#define MATCH(s) \
......@@ -308,7 +319,7 @@ int sip_is_callerpref(char const *param)
return base ^ xor;
}
/** Check if @b Contact is immune to callerprefs. */
/** Check if @Contact is immune to callerprefs. */
int sip_contact_is_immune(sip_contact_t const *m)
{
unsigned i;
......@@ -322,12 +333,57 @@ int sip_contact_is_immune(sip_contact_t const *m)
return 1;
}
/** Check if @b Contact matches by @b Accept-Contact.
*
/**Check if @Contact matches by @AcceptContact.
*
* Matching @AcceptContact and @Contact headers is done as explained in
* @RFC3841 section 7.2.4. The caller score can be calculated from the
* returned S and N values.
*
* @par Matching
* The @AcceptContact header contains number of feature tag parameters. The
* count of feature tags is returned in @a return_N. For each feature tag in
* @AcceptContact, the feature tag with same name is searched from the
* @Contact header. If both headers contain the feature tag with same name,
* their values are compared. If the value in @AcceptContact does not match
* with the value in @Contact, there is mismatch and 0 is returned. If they
* match, S is increased by 1.
*
* @retval 1 if successful
* @retval 0 if an error occurs
* @param m pointer to @Contact header structure
* @param cp pointer to @AcceptContact header structure
* @param return_N return-value parameter for number of
* feature tags in @AcceptContact
* @param return_S return-value parameter for number of
* matching feature tags
* @param return_error return-value parameter for parsing error
*
* For example,
* @code
* if (sip_contact_accept(contact, accept_contact, &S, &N, &error)) {
* if (N == 0)
* score == 1.0;
* else
* score = (double)S / (double)N;
* if (accept_contact->cp_explicit) {
* if (accept_contact->cp_require)
* goto drop;
* else
* score = 0.0;
* }
* }
* else if (!error) {
* score = 0.0;
* }
* @endcode
*
* @retval 1 if @Contact matches
* @return @a return_S contains number of matching feature tags
* @return @a return_N contains number of feature tags in @AcceptContact
* @retval 0 if @Contact does not match
* @return @a return_error contains -1 if feature tag value was malformed
*
* @sa @RFC3841 section 7.2.4, sip_contact_score(), sip_contact_reject(),
* sip_contact_is_immune(), sip_contact_immunize(), sip_is_callerpref(),
* sip_prefs_matching().
*/
int sip_contact_accept(sip_contact_t const *m,
sip_accept_contact_t const *cp,
......@@ -368,13 +424,23 @@ int sip_contact_accept(sip_contact_t const *m,
}
*return_S = S; /* Matched feature tags */
*return_N = N; /* Number of feature tags in Accept-Contact */
*return_N = N; /* Number of feature tags in @AcceptContact */
return 1;
}
/** Check if Contact can be rejected by Reject-Contact. */
/** Check if @Contact is rejected by @RejectContact.
*
* @param m pointer to @Contact header
* @param reject pointer to @RejectContact header
*
* @retval 1 when rejecting
* @retval 0 when @Contact does not match with @RejectContact
*
* @sa sip_contact_score(), sip_contact_accept(), sip_contact_immunize(),
* sip_contact_is_immune(), @RFC3841, @RejectContact, @Contact
*/
int sip_contact_reject(sip_contact_t const *m,
sip_reject_contact_t const *reject)
{
......@@ -387,7 +453,20 @@ int sip_contact_reject(sip_contact_t const *m,
return sip_contact_accept(m, reject, &S, &N, &error) && S == N && N > 0;
}
/** Immunize Contact is to callerprefs. */
/**Immunize @Contact to callerprefs.
*
* Make a copy of @Contact header @a m and remove all parameters which
* affect caller preferences.
*
* @param home home object used when allocating copy
* @param m pointer to @Contact header structure to immunize
*
* @retval pointer to immunized copy if successful
* @retval NULL upon an error
*
* @sa @RFC3841, sip_is_callerpref(), sip_contact_score(),
* sip_contact_accept(), sip_contact_reject(), @Contact
*/
sip_contact_t *sip_contact_immunize(su_home_t *home, sip_contact_t const *m)
{
unsigned i, j;
......@@ -416,7 +495,19 @@ sip_contact_t *sip_contact_immunize(su_home_t *home, sip_contact_t const *m)
return m1;
}
/** Calculate score for contact */
/** Calculate score for contact.
*
* The caller preference score is an integer in range of 0 to 1000.
*
* @retval -1 if the contact is rejected
* @retval 1000 if contact is immune to caller preferences
* @retval 0..1000 reflecting @RFC3481 score in 0.000 - 1.000.
*
* @sa sip_q_value(),
* sip_contact_accept(), sip_contact_reject(), sip_contact_is_immune(),
* sip_contact_immunize(), sip_is_callerpref(), sip_prefs_matching(),
* @RFC3481, @AcceptContact, @RejectContact, @Contact
*/
int sip_contact_score(sip_contact_t const *m,
sip_accept_contact_t const *ac,
sip_reject_contact_t const *rc)
......
......@@ -23,10 +23,10 @@
*/
/**@CFILE sip_reason.c
* @brief Reason header.