Commit 9c285045 authored by Pekka Pessi's avatar Pekka Pessi

nua: updated documentation

Updated tag documentation.

Moved doxygen doc entries from sofia-sip/nua_tag.h to nua_tag.c.

Removed internal datatypes and files from the generated documents.

darcs-hash:20070920184104-65a35-a857fbdef8abba39f299f900d3fbef8e4b88c5a8.gz
parent 3f3799c3
...@@ -32,7 +32,7 @@ ALIASES += NUA_EVENT="@var nua_event_e::" ...@@ -32,7 +32,7 @@ ALIASES += NUA_EVENT="@var nua_event_e::"
ALIASES += END_NUA_EVENT="@par  " ALIASES += END_NUA_EVENT="@par  "
ALIASES += \ ALIASES += \
NUA_HPARAM_CALLS="nua_invite(), nua_respond(), nua_ack(), nua_prack(), nua_update(), nua_info(), nua_bye(), nua_options(), nua_message(), nua_register(), nua_publish(), nua_refer(),nua_subscribe(), nua_notify(), nua_refer(), nua_notifier()" NUA_HPARAM_CALLS="nua_method(), nua_respond(), nua_invite(), nua_ack(), nua_cancel(), nua_prack(), nua_update(), nua_info(), nua_bye(), nua_options(), nua_message(), nua_register(), nua_unregister(), nua_publish(), nua_refer(), nua_subscribe(), nua_unsubscribe(), nua_notify(), nua_notifier()"
VERBATIM_HEADERS = NO VERBATIM_HEADERS = NO
......
...@@ -22,7 +22,7 @@ ...@@ -22,7 +22,7 @@
* *
*/ */
/**@file nua.c High-Level User Agent Library - "nua" Implementation. /**@internal @file nua.c High-Level User Agent Library - "nua" Implementation.
* *
* @author Pekka Pessi <Pekka.Pessi@nokia.com> * @author Pekka Pessi <Pekka.Pessi@nokia.com>
* @author Kai Vehmanen <Kai.Vehmanen@nokia.com> * @author Kai Vehmanen <Kai.Vehmanen@nokia.com>
...@@ -93,19 +93,28 @@ su_log_t nua_log[] = { SU_LOG_INIT("nua", "NUA_DEBUG", SU_DEBUG) }; ...@@ -93,19 +93,28 @@ su_log_t nua_log[] = { SU_LOG_INIT("nua", "NUA_DEBUG", SU_DEBUG) };
* @param magic Pointer to callback context * @param magic Pointer to callback context
* @param tag,value,... List of tagged parameters * @param tag,value,... List of tagged parameters
* *
* @retval !=NULL a pointer to a @nua stack object \n * @retval !=NULL a pointer to a @nua stack object
* @retval NULL upon an error * @retval NULL upon an error
* *
* @par Related tags: * @par Related tags:
* NUTAG_PROXY() \n * - NUTAG_PROXY(), giving the URI of the outbound proxy
* NUTAG_URL() \n * (but see also NUTAG_INITIAL_ROUTE()).
* NUTAG_SIPS_URL() \n * - NUTAG_URL() (and NUTAG_SIPS_URL(), listing URIs describing
* NUTAG_SIP_PARSER() \n * transports)
* NUTAG_CERTIFICATE_DIR() \n * - NUTAG_CERTIFICATE_DIR(), specifying the location of the
* all tags listed in nua_set_params(), \n * root and client/server certificate files
* all NTATAG_* are passed to NTA listed in <sofia-sip/nta_tag.h> \n * - NUTAG_SIP_PARSER(), providing customized parser used to
* all tport tags listed in <sofia-sip/tport_tag.h> \n * parse received SIP messages
* STUNTAG_DOMAIN(), STUNTAG_SERVER() \n * - All parameter tags, listed with nua_set_params()
* - All NTATAG_* are passed to NTA documented in <sofia-sip/nta_tag.h>:
* see NTATAG_EXTRA_100(),
* - All tport tags are passed to tport.
* They are documented in <sofia-sip/tport_tag.h>
* - All SOATAG_* are passed to the default SOA (media session) object which
* is created by nua_create() unless NUTAG_MEDIA_ENABLE(0) is included in
* the tag list
* - STUN tags STUNTAG_DOMAIN(), STUNTAG_SERVER().
* STUN is deprecated, however.
* *
* @note * @note
* From the @VERSION_1_12_2 all the nua_set_params() tags are processed. * From the @VERSION_1_12_2 all the nua_set_params() tags are processed.
......
...@@ -238,7 +238,7 @@ char const *nua_generate_instance_identifier(su_home_t *home) ...@@ -238,7 +238,7 @@ char const *nua_generate_instance_identifier(su_home_t *home)
* *
* @sa nua_respond(), #nua_event_e, #nua_event_t, nua_event_name() * @sa nua_respond(), #nua_event_e, #nua_event_t, nua_event_name()
* *
* @NEW_1_12_6 * @NEW_1_12_6.
*/ */
int nua_event_is_incoming_request(nua_event_t event) int nua_event_is_incoming_request(nua_event_t event)
{ {
......
...@@ -80,7 +80,7 @@ typedef struct { ...@@ -80,7 +80,7 @@ typedef struct {
} nua_server_methods_t; } nua_server_methods_t;
/** Server side transaction */ /* Server side transaction */
struct nua_server_request { struct nua_server_request {
struct nua_server_request *sr_next, **sr_prev; struct nua_server_request *sr_next, **sr_prev;
...@@ -147,7 +147,7 @@ int sr_status(nua_server_request_t *sr, int status, char const *phrase) ...@@ -147,7 +147,7 @@ int sr_status(nua_server_request_t *sr, int status, char const *phrase)
return (void)(sr->sr_phrase = phrase), (sr->sr_status = status); return (void)(sr->sr_phrase = phrase), (sr->sr_status = status);
} }
/** Methods for client request */ /* Methods for client request. @internal */
typedef struct { typedef struct {
sip_method_t crm_method; sip_method_t crm_method;
char const *crm_method_name; char const *crm_method_name;
...@@ -367,7 +367,7 @@ struct nua_dialog_state ...@@ -367,7 +367,7 @@ struct nua_dialog_state
} ds_remote_ua[1]; } ds_remote_ua[1];
}; };
/** Virtual function pointer table for dialog usage. */ /* Virtual function pointer table for dialog usage. */
typedef struct { typedef struct {
unsigned usage_size, usage_class_size; unsigned usage_size, usage_class_size;
int (*usage_add)(nua_owner_t *, int (*usage_add)(nua_owner_t *,
...@@ -387,7 +387,7 @@ typedef struct { ...@@ -387,7 +387,7 @@ typedef struct {
} nua_usage_class; } nua_usage_class;
/** Base structure for dialog usage. */ /* Base structure for dialog usage. */
struct nua_dialog_usage { struct nua_dialog_usage {
nua_dialog_usage_t *du_next; nua_dialog_usage_t *du_next;
nua_usage_class const *du_class; nua_usage_class const *du_class;
......
...@@ -35,7 +35,7 @@ ...@@ -35,7 +35,7 @@
* @date Created: Wed Mar 8 11:38:18 EET 2006 ppessi * @date Created: Wed Mar 8 11:38:18 EET 2006 ppessi
*/ */
/** NUA preferences. /**@internal @brief NUA preferences.
* *
* This structure contains values for various preferences and a separate * This structure contains values for various preferences and a separate
* bitmap (nhp_set) for each preference. Preferences are set using * bitmap (nhp_set) for each preference. Preferences are set using
......
...@@ -116,7 +116,7 @@ static int nua_register_usage_shutdown(nua_handle_t *, ...@@ -116,7 +116,7 @@ static int nua_register_usage_shutdown(nua_handle_t *,
nua_dialog_state_t *, nua_dialog_state_t *,
nua_dialog_usage_t *); nua_dialog_usage_t *);
/** REGISTER usage, aka nua_registration_t */ /** @internal @brief REGISTER usage, aka nua_registration_t. */
struct register_usage { struct register_usage {
nua_registration_t *nr_next, **nr_prev, **nr_list; /* Doubly linked list and its head */ nua_registration_t *nr_next, **nr_prev, **nr_list; /* Doubly linked list and its head */
sip_from_t *nr_aor; /**< AoR for this registration, NULL if none */ sip_from_t *nr_aor; /**< AoR for this registration, NULL if none */
...@@ -293,7 +293,7 @@ outbound_owner_vtable nua_stack_outbound_callbacks = { ...@@ -293,7 +293,7 @@ outbound_owner_vtable nua_stack_outbound_callbacks = {
* @par Related tags: * @par Related tags:
* NUTAG_REGISTRAR(), NUTAG_INSTANCE(), NUTAG_OUTBOUND(), * NUTAG_REGISTRAR(), NUTAG_INSTANCE(), NUTAG_OUTBOUND(),
* NUTAG_KEEPALIVE(), NUTAG_KEEPALIVE_STREAM(), NUTAG_M_USERNAME(), * NUTAG_KEEPALIVE(), NUTAG_KEEPALIVE_STREAM(), NUTAG_M_USERNAME(),
* NUTAG_M_DISPLAY(), NUTAG_M_PARAMS(), NUTAG_M_FEATURES(), * NUTAG_M_DISPLAY(), NUTAG_M_PARAMS(), NUTAG_M_FEATURES()
* *
* @par Events: * @par Events:
* #nua_r_register, #nua_i_outbound * #nua_r_register, #nua_i_outbound
......
...@@ -57,9 +57,15 @@ ...@@ -57,9 +57,15 @@
* Incoming REGISTER request. * Incoming REGISTER request.
* *
* In order to receive #nua_i_register events, the application must enable * In order to receive #nua_i_register events, the application must enable
* the REGISTER method with NUTAG_ALLOW() tag. * the REGISTER method with NUTAG_ALLOW() tag, e.g.,
* @verbatim
* nua_set_params(nua;
* NUTAG_APPL_METHOD("REGISTER"),
* NUTAG_ALLOW("REGISTER"),
* TAG_END());
* @endverbatim
* *
* The nua_response() call responding to a REGISTER request must have * The nua_response() call responding to a REGISTER request must include
* NUTAG_WITH() (or NUTAG_WITH_THIS()/NUTAG_WITH_SAVED()) tag. Note that * NUTAG_WITH() (or NUTAG_WITH_THIS()/NUTAG_WITH_SAVED()) tag. Note that
* a successful response to REGISTER @b MUST include the @Contact header * a successful response to REGISTER @b MUST include the @Contact header
* bound to the the AoR URI (in @To header). * bound to the the AoR URI (in @To header).
......
...@@ -137,7 +137,7 @@ sip_response_terminates_dialog(). ...@@ -137,7 +137,7 @@ sip_response_terminates_dialog().
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
/* Session event usage */ /* Session event usage */
/** Session-related state */ /** @internal @brief Session-related state. */
typedef struct nua_session_usage typedef struct nua_session_usage
{ {
enum nua_callstate ss_state; /**< Session status (enum nua_callstate) */ enum nua_callstate ss_state; /**< Session status (enum nua_callstate) */
......
...@@ -1665,7 +1665,9 @@ int nua_base_server_report(nua_server_request_t *sr, tagi_t const *tags) ...@@ -1665,7 +1665,9 @@ int nua_base_server_report(nua_server_request_t *sr, tagi_t const *tags)
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
/** @class nua_client_request /**@internal
*
* @class nua_client_request
* *
* Each handle has a queue of client-side requests; if a request is pending, * Each handle has a queue of client-side requests; if a request is pending,
* a new request from API is added to the queue. After the request is * a new request from API is added to the queue. After the request is
......
...@@ -129,7 +129,7 @@ su_inline int nua_handle_unref_by(nua_handle_t *nh, char const *by) ...@@ -129,7 +129,7 @@ su_inline int nua_handle_unref_by(nua_handle_t *nh, char const *by)
#endif #endif
/** NUA handle. /** @internal @brief NUA handle.
* *
*/ */
struct nua_handle_s struct nua_handle_s
......
...@@ -737,7 +737,10 @@ int nua_notify_server_report(nua_server_request_t *sr, tagi_t const *tags) ...@@ -737,7 +737,10 @@ int nua_notify_server_report(nua_server_request_t *sr, tagi_t const *tags)
* #nua_i_notify * #nua_i_notify
* *
* @sa #nua_r_refer, NUTAG_SUBSTATE(), NUTAG_REFER_EVENT(),#nua_i_refer, * @sa #nua_r_refer, NUTAG_SUBSTATE(), NUTAG_REFER_EVENT(),#nua_i_refer,
* @RFC3515, @ReferTo, @RFC3892, @ReferredBy * @RFC3515, @ReferTo, SIPTAG_REFER_TO(), SIPTAG_REFER_TO_STR(),
* @RFC3892, @ReferredBy, SIPTAG_REFERRED_BY(), SIPTAG_REFERRED_BY_STR(),
* @RFC3891, @Replaces, SIPTAG_REPLACES(), SIPTAG_REPLACES_STR(),
* @RFC4488, @ReferSub, SIPTAG_REFER_SUB(), SIPTAG_REFER_SUB_STR()
*/ */
/**@NUA_EVENT nua_r_refer /**@NUA_EVENT nua_r_refer
...@@ -758,7 +761,7 @@ int nua_notify_server_report(nua_server_request_t *sr, tagi_t const *tags) ...@@ -758,7 +761,7 @@ int nua_notify_server_report(nua_server_request_t *sr, tagi_t const *tags)
* NUTAG_SUBSTATE() * NUTAG_SUBSTATE()
* *
* @sa nua_refer(), NUTAG_SUBSTATE(), #nua_i_refer, * @sa nua_refer(), NUTAG_SUBSTATE(), #nua_i_refer,
* @RFC3515, @ReferTo, @RFC3892, @ReferredBy * @RFC3515, @RFC4488, @ReferSub
* *
* @END_NUA_EVENT * @END_NUA_EVENT
*/ */
......
This diff is collapsed.
This diff is collapsed.
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