Commit 759272fe authored by Pekka Pessi's avatar Pekka Pessi
Browse files

Updated documentation in nua.

darcs-hash:20060329161236-65a35-93660384551dacc4abd8520948b1dc1147ee1110.gz
parent 5ddb550b
......@@ -19,4 +19,5 @@ TAGFILES += ../docs/doxytags_sdp=../sdp
GENERATE_TAGFILE = ../docs/doxytags_nua
ALIASES +=
ALIASES += CFILE="@internal @file" IFILE="@internal @file"
VERBATIM_HEADERS = NO
\ No newline at end of file
......@@ -100,13 +100,14 @@ su_log_t nua_log[] = { SU_LOG_INIT("nua", "NUA_DEBUG", SU_DEBUG) };
* @retval NULL upon an error
*
* @par Related tags:
* #NUTAG_MEDIA_ENABLE \n
* #NUTAG_PROXY \n
* #NUTAG_SIP_PARSER \n
* #NUTAG_SIPS_URL \n
* #NUTAG_UICC \n
* #NUTAG_CERTIFICATE_DIR \n
* #NUTAG_URL \n
* NUTAG_MEDIA_ENABLE() \n
* NUTAG_SOA_NAME() \n
* NUTAG_PROXY() \n
* NUTAG_URL() \n
* NUTAG_SIPS_URL() \n
* NUTAG_SIP_PARSER() \n
* NUTAG_UICC() \n
* NUTAG_CERTIFICATE_DIR() \n
* all relevant NTATAG_* are passed to NTA
*
* @note
......@@ -459,7 +460,7 @@ int nua_handle_has_active_call(nua_handle_t const *nh)
*
* @retval 0 if no call on hold in operation or operation handle is invalid
* @retval 1 if operation has call on hold, for example nua_invite() or
* nua_update() has been called with #NUTAG_HOLD with != 0 argument.
* nua_update() has been called with NUTAG_HOLD() with != 0 argument.
*
* @par Related tags:
* none
......@@ -700,57 +701,12 @@ void nua_get_hparams(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
NUA_SIGNAL(nh, nua_r_get_params, tag, value);
}
/** Send SIP REGISTER request to the registrar.
*
* Request status will be delivered to the application using #nua_r_register
* event. When successful the registration will be updated periodically. If
* the registrar includes Service-Route header in response, and service
* route is enabled using NUTAG_SERVICE_ROUTE_ENABLE(), the service route
* will be used for initial non-REGISTER requests.
*
* The handle used for registration cannot be used for any other purposes.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related tags:
* #NUTAG_REGISTRAR
*
* @par Events:
* #nua_r_register
*/
/* Documented with nua_stack_register() */
void nua_register(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
NUA_SIGNAL(nh, nua_r_register, tag, value);
}
/** Unregister.
*
* Send a REGISTER request with expiration time 0. This removes the
* registration from the registrar. If the handle was earlier used
* with nua_register() the periodic updates will be terminated.
*
* If a #SIPTAG_CONTACT_STR with argument "*" is used, the all registrations
* will be removed from the registrar otherwise only the contact address
* belonging to the NUA stack is removed.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related tags:
* #NUTAG_REGISTRAR \n
* Tags in <sip_tag.h> except #SIPTAG_EXPIRES or #SIPTAG_EXPIRES_STR
*
* @par Events:
* #nua_r_unregister
*/
void nua_unregister(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
NUA_SIGNAL(nh, nua_r_unregister, tag, value);
......@@ -766,9 +722,9 @@ void nua_unregister(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
* hung-up with nua_bye().
*
* Optionally
* - uses early media if #NUTAG_EARLY_MEDIA tag is used with non zero value
* - uses early media if NUTAG_EARLY_MEDIA() tag is used with non zero value
* - media parameters can be set by NUTAG_MEDIA_* tags
* - if #NUTAG_MEDIA_ENABLE tag is used with value zero then the soa is
* - if NUTAG_MEDIA_ENABLE() tag is used with value zero then the soa is
* not used and application must create the SDP
* - nua_invite() can be used to change call status:
* - #SOATAG_HOLD tag listing the media put on hold or with value "*" sets
......@@ -820,7 +776,7 @@ void nua_invite(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
*
* Acknowledge a successful response to INVITE request
* with SIP ACK message. This function is need only if
* #NUTAG_AUTOACK parameter has been cleared.
* NUTAG_AUTOACK() parameter has been cleared.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
......@@ -966,7 +922,7 @@ void nua_chat(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
* nothing
*
* @par Related Tags:
* #NUTAG_URL
* NUTAG_URL()
* Tags in <sip_tag.h>
*
* @par Events:
......@@ -1041,7 +997,7 @@ void nua_notify(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
* nothing
*
* @par Related Tags:
* #NUTAG_URL \n
* NUTAG_URL() \n
* #SIPTAG_EVENT or #SIPTAG_EVENT_STR \n
* #SIPTAG_CONTENT_TYPE or SIPTAG_CONTENT_TYPE_STR \n
* #SIPTAG_PAYLOAD or #SIPTAG_PAYLOAD_STR \n
......@@ -1096,7 +1052,7 @@ void nua_terminate(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
* nothing
*
* @par Related Tags:
* #NUTAG_URL \n
* NUTAG_URL() \n
* Tags in <sip_tag.h>
*
* @par Events:
......@@ -1124,7 +1080,7 @@ void nua_refer(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
* nothing
*
* @par Related Tags:
* #NUTAG_URL \n
* NUTAG_URL() \n
* Tags in <sip_tag.h>
*
* @par Events:
......@@ -1148,7 +1104,7 @@ void nua_publish(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
* nothing
*
* @par Related Tags:
* #NUTAG_URL \n
* NUTAG_URL() \n
* Tags in <sip_tag.h>
*
* @par Events:
......@@ -1236,7 +1192,7 @@ void nua_update(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
*
* - 401 / 407 response with www-authenticate header/ proxy-authenticate header
* - application should provide stack with username&password for each realm
* with #NUTAG_AUTH tag
* with NUTAG_AUTH() tag
* - restarts operation
*
* @param nh Pointer to operation handle
......@@ -1246,7 +1202,7 @@ void nua_update(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
* nothing
*
* @par Related Tags:
* #NUTAG_AUTH
* NUTAG_AUTH()
*
* @par Events:
* (any operation events)
......@@ -1262,8 +1218,8 @@ void nua_authenticate(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
* incoming subscriber launches nua_i_subscription event. Subscriber
* can be authorized in this application callback.
*
* #NUTAG_SUB tag
* #NUTAG_SUBSTATE tag
* NUTAG_SUB() tag
* NUTAG_SUBSTATE() tag
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
......@@ -1272,8 +1228,8 @@ void nua_authenticate(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
* nothing
*
* @par Related Tags:
* #NUTAG_SUB
* #NUTAG_SUBSTATE
* NUTAG_SUB()
* NUTAG_SUBSTATE()
*
* @par Events:
* (any operation events)
......
......@@ -793,7 +793,7 @@ void app_i_message(int status,
} /* app_i_message */
@endcode
@subsection nua_notifier Creating Presence Server
@subsection nua_notifier Creating a Presence Server
@code
......@@ -827,7 +827,7 @@ void app_i_message(int status,
@endcode
After the nua_notifier object -- the presence server -- is created, an
event nua_r_notifier is launched. Status and phrase values of the
event nua_r_notifier is returned. Status and phrase values of the
app_callback function indicate the success of the creation.
Authorization of an incoming subscription (to the local presence
......@@ -2386,20 +2386,6 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* #NUTAG_SUBSTATE
*/
/** @var nua_event_e::nua_r_register
*
* Answer to outgoing REGISTER.
*
* The REGISTER may be sent explicitly by nua_register() or
* implicitly by NUA state machine.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip response to REGISTER request or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags empty
*/
/** @var nua_event_e::nua_r_shutdown
*
* Answer to nua_shutdown().
......@@ -2440,17 +2426,6 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* @param tags empty
*/
/** @var nua_event_e::nua_r_unregister
*
* Answer to outgoing un-REGISTER.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip response to REGISTER request or NULL upon an error
* (error code and message are in status and phrase parameters)
* @param tags empty
*/
/** @var nua_event_e::nua_r_unsubscribe
*
* Answer to outgoing un-SUBSCRIBE.
......
......@@ -22,9 +22,8 @@
*
*/
/**
* @file nua_common.c
* @brief
/**@CFILE nua_common.c
* @brief Function common to both stack and application side.
*
* @author Pekka.Pessi@nokia.com
*
......@@ -74,7 +73,8 @@
#include "nua_stack.h"
/** Create an operation handle
/**@internal
* Create an operation handle
*
* Allocates a new operation handle and associated storage.
*
......
......@@ -61,11 +61,13 @@ static void nua_dialog_usage_remove_at(nua_owner_t*, nua_dialog_state_t*,
nua_dialog_usage_t**);
static void nua_dialog_log_usage(nua_owner_t *, nua_dialog_state_t *);
/** UAS tag and route.
/**@internal
* UAS tag and route.
*
* Update dialog tags and route on the UAS side.
*
* @param own dialog owner
* @param ds dialog state
* @param sip SIP message containing response used to update dialog
* @param rtag if true, set remote tag within the leg
*/
......@@ -89,11 +91,13 @@ void nua_dialog_uas_route(nua_owner_t *own,
nta_leg_rtag(ds->ds_leg, sip->sip_from->a_tag);
}
/** UAC tag and route.
/**@internal
* UAC tag and route.
*
* Update dialog tags and route on the UAC side.
*
* @param own dialog owner
* @param ds dialog state
* @param sip SIP message containing response used to update dialog
* @param rtag if true, set remote tag within the leg
*/
......@@ -117,7 +121,7 @@ void nua_dialog_uac_route(nua_owner_t *own,
nta_leg_rtag(ds->ds_leg, sip->sip_to->a_tag);
}
/** Store information from remote endpoint. */
/**@internal Store information from remote endpoint. */
void nua_dialog_store_peer_info(nua_owner_t *own,
nua_dialog_state_t *ds,
sip_t const *sip)
......@@ -177,7 +181,7 @@ void nua_dialog_store_peer_info(nua_owner_t *own,
}
}
/** Get dialog usage slot */
/** @internal Get dialog usage slot. */
nua_dialog_usage_t **
nua_dialog_usage_at(nua_dialog_state_t const *ds,
nua_usage_class const *kind,
......@@ -217,7 +221,7 @@ nua_dialog_usage_at(nua_dialog_state_t const *ds,
return &none;
}
/** Get a dialog usage */
/** @internal Get a dialog usage */
nua_dialog_usage_t *nua_dialog_usage_get(nua_dialog_state_t const *ds,
nua_usage_class const *kind,
sip_event_t const *event)
......@@ -225,7 +229,7 @@ nua_dialog_usage_t *nua_dialog_usage_get(nua_dialog_state_t const *ds,
return *nua_dialog_usage_at(ds, kind, event);
}
/** Get dialog usage name */
/** @internal Get dialog usage name */
char const *nua_dialog_usage_name(nua_dialog_usage_t const *du)
{
if (du == NULL)
......@@ -233,7 +237,7 @@ char const *nua_dialog_usage_name(nua_dialog_usage_t const *du)
return du->du_class->usage_name(du);
}
/** Add dialog usage */
/** @internal Add dialog usage */
nua_dialog_usage_t *nua_dialog_usage_add(nua_owner_t *own,
struct nua_dialog_state *ds,
nua_usage_class const *uclass,
......@@ -290,7 +294,7 @@ nua_dialog_usage_t *nua_dialog_usage_add(nua_owner_t *own,
return NULL;
}
/** Remove dialog usage. */
/** @internal Remove dialog usage. */
void nua_dialog_usage_remove(nua_owner_t *own,
nua_dialog_state_t *ds,
nua_dialog_usage_t *du)
......@@ -308,7 +312,7 @@ void nua_dialog_usage_remove(nua_owner_t *own,
nua_dialog_usage_remove_at(own, ds, at);
}
/** Remove dialog usage.
/** @internal Remove dialog usage.
*
* Zap dialog state (leg, tag and route) if no usages remain.
*/
......@@ -382,7 +386,7 @@ void nua_dialog_log_usage(nua_owner_t *own, nua_dialog_state_t *ds)
}
}
/** Dialog has been terminated. */
/** @internal Dialog has been terminated. */
void nua_dialog_terminated(nua_owner_t *own,
struct nua_dialog_state *ds,
int status,
......@@ -405,7 +409,8 @@ void nua_dialog_terminated(nua_owner_t *own,
}
/** Set refresh value suitably.
/**@internal
* Set refresh value suitably.
*
* The refresh time is set either at half of the @a delta interval or if @a
* delta is less than 5 minutes, 30 seconds before end of interval. $
......@@ -432,7 +437,7 @@ void nua_dialog_usage_set_refresh(nua_dialog_usage_t *du, unsigned delta)
du->du_refresh = target;
}
/** Call the owner operation function */
/** @internal Call the owner operation function. */
void nua_dialog_usage_refresh(nua_owner_t *owner,
nua_dialog_usage_t *du,
sip_time_t now)
......
......@@ -25,7 +25,7 @@
#ifndef NUA_DIALOG_H /** Defined when <nua_dialog.h> has been included. */
#define NUA_DIALOG_H
/**@file nua_dialog.h
/**@IFILE nua_dialog.h
* @brief Dialog and dialog usage handling
*
* @author Pekka Pessi <Pekka.Pessi@nokia.com>
......
......@@ -244,11 +244,12 @@ void authorize_watcher(nea_server_t *nes,
}
/* ---------------------------------------------------------------------- */
/* Authorization by application */
/* Authorization of watchers by application */
void
nua_stack_authorize(nua_t *nua, nua_handle_t *nh, nua_event_t e,
tagi_t const *tags)
void nua_stack_authorize(nua_t *nua,
nua_handle_t *nh,
nua_event_t e,
tagi_t const *tags)
{
nea_sub_t *sub = NULL;
nea_state_t state = nea_extended;
......@@ -268,13 +269,11 @@ nua_stack_authorize(nua_t *nua, nua_handle_t *nh, nua_event_t e,
return;
}
/** Shutdown notifier object */
int
nh_notifier_shutdown(nua_handle_t *nh, nea_event_t *ev,
tag_type_t t, tag_value_t v, ...)
/** @internal Shutdown notifier object */
int nh_notifier_shutdown(nua_handle_t *nh,
nea_event_t *ev,
tag_type_t t,
tag_value_t v, ...)
{
nea_server_t *nes = nh->nh_notifier;
nea_subnode_t const **subs;
......@@ -310,9 +309,11 @@ nh_notifier_shutdown(nua_handle_t *nh, nea_event_t *ev,
}
/** Terminate notifier. */
void
nua_stack_terminate(nua_t *nua, nua_handle_t *nh, nua_event_t e, tagi_t const *tags)
/** @internal Terminate notifier. */
void nua_stack_terminate(nua_t *nua,
nua_handle_t *nh,
nua_event_t e,
tagi_t const *tags)
{
sip_event_t const *event = NULL;
sip_content_type_t const *ct = NULL;
......
......@@ -22,8 +22,8 @@
*
*/
/**@CFILE nua_message.c
* @brief OPTIONS method
/**@CFILE nua_options.c
* @brief Implementation of OPTIONS method
*
* @author Pekka Pessi <Pekka.Pessi@nokia.com>
*
......
......@@ -174,15 +174,15 @@ struct outbound_connect {
unsigned oc_add_contact:1;
/* The registration state machine. */
/**< Initial REGISTER containing oc_rcontact has been sent */
/** Initial REGISTER containing oc_rcontact has been sent */
unsigned oc_registering:1;
/**< 2XX response to REGISTER containg oc_rcontact has been received */
/** 2XX response to REGISTER containg oc_rcontact has been received */
unsigned oc_registered:1;
/**< The registration has been validated:
* We have successfully sent OPTIONS to ourselves.
/**The registration has been validated:
* We have successfully sent OPTIONS to ourselves.
*/
unsigned oc_validated:1;
/**< The registration has been validated once.
/** The registration has been validated once.
* We have successfully sent OPTIONS to ourselves, so do not give
* up if OPTIONS probe fails.
*/
......@@ -247,6 +247,170 @@ outbound_owner_vtable nua_stack_register_callbacks = {
nua_stack_register_failed,
};
/**@fn void nua_register(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);
*
* Send SIP REGISTER request to the registrar.
*
* Request status will be delivered to the application using #nua_r_register
* event. When successful the registration will be updated periodically.
*
* The handle used for registration cannot be used for any other purposes.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related tags:
* NUTAG_REGISTRAR(), NUTAG_KEEPALIVE(), NUTAG_KEEPALIVE_STREAM(),
* NUTAG_OUTBOUND()
*
* @par Events:
* #nua_r_register, #nua_i_outbound
*
* @par NAT, Firewall and Outbound Support
*
* If the application did not include the Contact header in the tags,
* nua_register() will generate one and start a protocol engine for outbound
* connections used for NAT and firewall traversal and connectivity checks.
*
* First, nua_register() will first probe for NATs in between UA and
* registrar. It will send a REGISTER request as usual. Upon receiving the
* response check for the presence of "received" and "rport" parameters in
* the Via header returned by registrar. The presence of NAT is determined
* from the "received" parameter in a Via header. When a REGISTER request
* was sent, the stack inserted the source IP address in the Via header: if
* that is different from the source IP address seen by the registrar, the
* registrar inserts the source IP address it sees into the "received"
* parameter.
*
* Please note that an ALG (application-level gateway) modifying the Via
* headers in outbound requests and again in incoming responses will make
* the above-described NAT check to fail.
*
* The response to the initial REGISTER should also include feature tags
* indicating whether registrar supports various SIP extensions: @e
* outbound, @e pref, @e path, @e gruu. If the @e outbound extension is
* supported, and it is not explicitly disabled by application, the
* nua_register() will use it. Basically, @e outbound means that instead of
* registering its contact URI with a particular address-of-record URI, the
* user-agent registers a transport-level connection. Such a connection is
* identified on the Contact header field with a @ref NUTAG_INSTANCE()
* "unique string" identifying the user-agent instance and a numeric index
* identifying the transport-level connection.
*
* If @e outbound is not supported, nua_register() has to generate a URI
* that can be used to reach it from outside. It will check for public
* transport addresses detected by underlying stack with, e.g., STUN, UPnP
* or SOCKS. If there are public addresses, nua_register() will use them. If
* there is no public address, it will try to generate a Contact URI from
* the "received" and "rport" parameters found in the Via header of the
* response message.
*
* @par GRUU and Service-Route
*
* After a successful response to the REGISTER request has been received,
* nua_register() will update the information about the registration based
* on it. If there is a "gruu" parameter included in the response,
* nua_register() will save it and use the gruu URI in the Contact header
* fields of dialog-establishing messages, such as INVITE or SUBSCRIBE.
* Also, if the registrar has included a Service-Route header in the
* response, and the service route feature has not been disabled using
* NUTAG_SERVICE_ROUTE_ENABLE(), the route URIs from the Service-Route
* header will be used for initial non-REGISTER requests.
*
* The #nua_r_register message will include the contact header and route
* used in with the registration.
*
* @par Registration Keep-Alive
*
* After the registration has successfully completed the nua_register() will
* validate the registration and initiate the keepalive mechanism, too. The
* user-agent validates the registration by sending a OPTIONS requests to
* itself. If there is an error, nua_register() will indicate that to the
* application using nua_i_outbound event, and start unregistration
* procedure (unless that has been explicitly disabled).
*
* The keepalive mechanism depends on the network features detected earlier.
* If @a outbound extension is used, the STUN keepalives will be used.
* Otherwise, NUA stack will repeatedly send OPTIONS requests to itself. In
* order to save bandwidth, it will include Max-Forwards: 0 in the
* keep-alive requests, however. The keepalive interval is determined by two
* parameters: NUTAG_KEEPALIVE() and NUTAG_KEEPALIVE_STREAM(). If the
* interval is 0, no keepalive messages is sent. The value of
* NUTAG_KEEPALIVE_STREAM(), if specified, is used to indicate the desired
* transport-layer keepalive interval for stream-based transports like TLS
* and TCP.
*/
/** @var nua_event_e::nua_r_register
*
* Answer to outgoing REGISTER.
*
* The REGISTER may be sent explicitly by nua_register() or implicitly by
* NUA state machines. The @a status may be 100 even if the real response
* status returned is different if the REGISTER request has been restarted.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param status registration status
* @param sip response to REGISTER request or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags empty
*/
/** @var nua_event_e::nua_i_outbound
*
* Answer to outgoing REGISTER.
*
* The REGISTER may be sent explicitly by nua_register() or
* implicitly by NUA state machine.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip response to REGISTER request or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags empty
*/
/**@fn void nua_unregister(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);
* Unregister.
*
* Send a REGISTER request with expiration time 0. This removes the
* registration from the registrar. If the handle was earlier used
* with nua_register() the periodic updates will be terminated.
*
* If a SIPTAG_CONTACT_STR() with argument "*" is used, all the
* registrations will be removed from the registrar otherwise only the
* contact address belonging to the NUA stack is removed.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related tags:
* NUTAG_REGISTRAR() \n
* Tags in <sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()
*
* @par Events:
* #nua_r_unregister
*/