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::"
ALIASES += END_NUA_EVENT="@par  "
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
......
......@@ -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 Kai Vehmanen <Kai.Vehmanen@nokia.com>
......@@ -93,19 +93,28 @@ su_log_t nua_log[] = { SU_LOG_INIT("nua", "NUA_DEBUG", SU_DEBUG) };
* @param magic Pointer to callback context
* @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
*
* @par Related tags:
* NUTAG_PROXY() \n
* NUTAG_URL() \n
* NUTAG_SIPS_URL() \n
* NUTAG_SIP_PARSER() \n
* NUTAG_CERTIFICATE_DIR() \n
* all tags listed in nua_set_params(), \n
* all NTATAG_* are passed to NTA listed in <sofia-sip/nta_tag.h> \n
* all tport tags listed in <sofia-sip/tport_tag.h> \n
* STUNTAG_DOMAIN(), STUNTAG_SERVER() \n
* - NUTAG_PROXY(), giving the URI of the outbound proxy
* (but see also NUTAG_INITIAL_ROUTE()).
* - NUTAG_URL() (and NUTAG_SIPS_URL(), listing URIs describing
* transports)
* - NUTAG_CERTIFICATE_DIR(), specifying the location of the
* root and client/server certificate files
* - NUTAG_SIP_PARSER(), providing customized parser used to
* parse received SIP messages
* - 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
* 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)
*
* @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)
{
......
......@@ -80,7 +80,7 @@ typedef struct {
} nua_server_methods_t;
/** Server side transaction */
/* Server side transaction */
struct nua_server_request {
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)
return (void)(sr->sr_phrase = phrase), (sr->sr_status = status);
}
/** Methods for client request */
/* Methods for client request. @internal */
typedef struct {
sip_method_t crm_method;
char const *crm_method_name;
......@@ -367,7 +367,7 @@ struct nua_dialog_state
} ds_remote_ua[1];
};
/** Virtual function pointer table for dialog usage. */
/* Virtual function pointer table for dialog usage. */
typedef struct {
unsigned usage_size, usage_class_size;
int (*usage_add)(nua_owner_t *,
......@@ -387,7 +387,7 @@ typedef struct {
} nua_usage_class;
/** Base structure for dialog usage. */
/* Base structure for dialog usage. */
struct nua_dialog_usage {
nua_dialog_usage_t *du_next;
nua_usage_class const *du_class;
......
......@@ -35,7 +35,7 @@
* @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
* bitmap (nhp_set) for each preference. Preferences are set using
......
......@@ -116,7 +116,7 @@ static int nua_register_usage_shutdown(nua_handle_t *,
nua_dialog_state_t *,
nua_dialog_usage_t *);
/** REGISTER usage, aka nua_registration_t */
/** @internal @brief REGISTER usage, aka nua_registration_t. */
struct register_usage {
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 */
......@@ -293,7 +293,7 @@ outbound_owner_vtable nua_stack_outbound_callbacks = {
* @par Related tags:
* NUTAG_REGISTRAR(), NUTAG_INSTANCE(), NUTAG_OUTBOUND(),
* 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:
* #nua_r_register, #nua_i_outbound
......
......@@ -57,9 +57,15 @@
* Incoming REGISTER request.
*
* 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
* a successful response to REGISTER @b MUST include the @Contact header
* bound to the the AoR URI (in @To header).
......
......@@ -137,7 +137,7 @@ sip_response_terminates_dialog().
/* ---------------------------------------------------------------------- */
/* Session event usage */
/** Session-related state */
/** @internal @brief Session-related state. */
typedef struct nua_session_usage
{
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)
/* ---------------------------------------------------------------------- */
/** @class nua_client_request
/**@internal
*
* @class nua_client_request
*
* 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
......
......@@ -129,7 +129,7 @@ su_inline int nua_handle_unref_by(nua_handle_t *nh, char const *by)
#endif
/** NUA handle.
/** @internal @brief NUA handle.
*
*/
struct nua_handle_s
......
......@@ -737,7 +737,10 @@ int nua_notify_server_report(nua_server_request_t *sr, tagi_t const *tags)
* #nua_i_notify
*
* @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
......@@ -758,7 +761,7 @@ int nua_notify_server_report(nua_server_request_t *sr, tagi_t const *tags)
* NUTAG_SUBSTATE()
*
* @sa nua_refer(), NUTAG_SUBSTATE(), #nua_i_refer,
* @RFC3515, @ReferTo, @RFC3892, @ReferredBy
* @RFC3515, @RFC4488, @ReferSub
*
* @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