Commit c667a9ac authored by Pekka Pessi's avatar Pekka Pessi

nua: updated documentation. Fixed references to headers.

darcs-hash:20070627094612-65a35-a40398f0eff6b6f258dd074f8d88d0c355b26203.gz
parent 5e2c4d82
......@@ -1040,19 +1040,30 @@ void nua_event(nua_t *root_magic, su_msg_r sumsg, event_t *e)
su_msg_destroy(nua->nua_current);
}
/** Get current request message. @NEW_1_12_4. */
/** Get current request message. @NEW_1_12_4.
*
* @note A response message is returned when processing response message.
*
* @sa #nua_event_e, nua_respond(), NUTAG_WITH_CURRENT()
*/
msg_t *nua_current_request(nua_t const *nua)
{
return nua && nua->nua_current ? su_msg_data(nua->nua_current)->e_msg : NULL;
}
/** Get request message from saved nua event. @NEW_1_12_4. */
/** Get request message from saved nua event. @NEW_1_12_4.
*
* @sa nua_save_event(), nua_respond(), NUTAG_WITH_SAVED(),
*/
msg_t *nua_saved_event_request(nua_saved_event_t const *saved)
{
return saved && saved[0] ? su_msg_data(saved)->e_msg : NULL;
}
/** Save nua event and its arguments */
/** Save nua event and its arguments.
*
* @sa #nua_event_e, nua_event_data() nua_saved_event_request(), nua_destroy_event()
*/
int nua_save_event(nua_t *nua, nua_saved_event_t return_saved[1])
{
if (nua && return_saved) {
......@@ -1066,13 +1077,19 @@ int nua_save_event(nua_t *nua, nua_saved_event_t return_saved[1])
return 0;
}
/** Get event data */
/** Get event data.
*
* @sa #nua_event_e, nua_event_save(), nua_saved_event_request(), nua_destroy_event().
*/
nua_event_data_t const *nua_event_data(nua_saved_event_t const saved[1])
{
return saved ? su_msg_data(saved) : NULL;
}
/** Destroy saved event */
/** Destroy saved event.
*
* @sa #nua_event_e, nua_event_save(), nua_event_data(), nua_saved_event_request().
*/
void nua_destroy_event(nua_saved_event_t saved[1])
{
if (su_msg_is_non_null(saved)) {
......
......@@ -26,18 +26,18 @@ The NUA API gives the high-level application programmer transparent and
full control to the SIP protocol engine below it. NUA provides the call
semantics on top of existing transaction semantics found in
<a href="../nta/index.html"><b>nta</b></a> module.
API makes it possible to create different kind of User Agents,
With NUA it is possible to create different kind of SIP User Agents,
like terminals, gateways or MCUs.
The @b nua engine hides many low-level signaling and media management
aspects from the application programmer. It is possible to use different
kind of media interfaces - even remote ones - in a fully transparent way.
The application and the protocol engine within User Agent library can be
run in separate threads. Communications from the protocol engine is
conveyed through a callback function. The callback function is called
within context of the application, so the application must provide
appropriate handle to a #su_root_t object.
The application and the protocol engine within User Agent library can be run
in separate threads. The protocol engine communicates with the application
using @ref nua_event_e "events", delivered to the application with a a
callback function. The callback function is called within the thread context
of the application, represented with a #su_root_t object.
@section nua_concepts_user Sofia Concepts for NUA User
......@@ -74,14 +74,14 @@ the main event loop of the task. Through the root object the task code
can access its context information (magic) and thread-synchronization
features like wait objects, timers, and messages.
An application using NUA services must create a root object and the
callback routine to handle events. The root object is created with
su_root_create() function and the callback routine is registered with
An application using NUA services must create a root object and the callback
routine to handle @ref nua_event_e "NUA events". The root object is created
with su_root_create() function and the callback routine is registered with
nua_create() function.
Root object has type #su_root_t.
See documentation of <su_wait.h> and <su_root.c> for more information
See documentation of <sofia-sip/su_wait.h> and <su_root.c> for more information
of root object.
See section #nua_event_e for more information of the callback function.
......@@ -109,8 +109,8 @@ separately.
An application using NUA services can use the memory management services
provided by the SU library but it is not mandatory.
See documentation of <su_alloc.h> for more information of memory management
services.
See documentation of <sofia-sip/su_alloc.h> for more information of memory
management services.
@subsection nua_tags Tags
......@@ -169,14 +169,14 @@ An application using NUA services must use tagged arguments for passing the
parameters to functions. See nua_invite() for discussion on how a SIP
message is constructed from the tags.
See documentation of <su_tag.h> for more information of tags and the
See documentation of <sofia-sip/su_tag.h> for more information of tags and the
module-specific documentation of each Sofia module for information of
tags specific for that module.
@subsection nua_debugandlogging Debugging and Logging
The modules of Sofia stack contain configurable debugging and logging
functionality based on the services defined in <su_log.h>. The debugging
functionality based on the services defined in <sofia-sip/su_log.h>. The debugging
and logging details (for example level of details on output and output
file name) can be configured by environment variables, directives in
configuration files and compilation directives in the source files.
......@@ -201,7 +201,7 @@ The defined debug output levels are:
An application using NUA services can also use the debugging and
logging services provided by the Sofia stack but it is not mandatory.
See documentation of <su_log.h> for more information of debugging and
See documentation of <sofia-sip/su_log.h> for more information of debugging and
logging services.
@section nua_concepts NUA Concepts
......@@ -2089,6 +2089,8 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* #nua_r_unregister \n
* #nua_r_unsubscribe \n
* #nua_r_update
*
* @sa nua_event_is_incoming_request(), nua_event_name()
*/
/** @NUA_EVENT nua_i_chat
......
......@@ -235,7 +235,7 @@ char const *nua_generate_instance_identifier(su_home_t *home)
* ...
* @endcode
*
* @sa #nua_event_t, nua_respond()
* @sa nua_respond(), #nua_event_e, #nua_event_t, nua_event_name()
*
* @NEW_1_12_6
*/
......@@ -260,7 +260,10 @@ int nua_event_is_incoming_request(nua_event_t event)
}
}
/** Get name for a NUA event. */
/** Get name for a NUA event.
*
* @sa #nua_event_e, #nua_event_t, nua_callstate_name(), nua_substate_name()
*/
char const *nua_event_name(nua_event_t event)
{
switch (event) {
......@@ -329,7 +332,10 @@ char const *nua_event_name(nua_event_t event)
}
}
/** Return name of call state */
/** Return name of call state.
*
* @sa enum #nua_callstate, nua_event_name(), nua_substate_name()
*/
char const *nua_callstate_name(enum nua_callstate state)
{
switch (state) {
......@@ -348,7 +354,10 @@ char const *nua_callstate_name(enum nua_callstate state)
}
}
/** Return name of subscription state. @NEW_1_12_5. */
/** Return name of subscription state. @NEW_1_12_5.
*
* @sa enum #nua_substate, nua_event_name(), nua_callstate_name()
*/
char const *nua_substate_name(enum nua_substate substate)
{
switch (substate) {
......
......@@ -63,7 +63,7 @@
* NUTAG_METHOD() \n
* NUTAG_URL() \n
* Tags of nua_set_hparams() \n
* Tags in <sip_tag.h>
* Header tags defined in <sofia-sip/sip_tag.h>
*
* @par Events:
* #nua_r_method
......
......@@ -64,7 +64,7 @@
* @par Related Tags:
* NUTAG_URL() \n
* Tags of nua_set_hparams() \n
* Tags in <sip_tag.h>
* Header tags defined in <sofia-sip/sip_tag.h>
*
* @par Events:
* #nua_r_message
......
......@@ -366,7 +366,7 @@ int nua_subscribe_server_report(nua_server_request_t *sr, tagi_t const *tags)
* @par Related Tags:
* NUTAG_SUBSTATE() \n
* Tags of nua_set_hparams() \n
* Tags in <sip_tag.h>
* Header tags defined in <sofia-sip/sip_tag.h>
*
* @par Events:
* #nua_r_notify
......
......@@ -58,7 +58,7 @@
* nothing
*
* @par Related Tags:
* Tags in <sip_tag.h>
* Header tags defined in <sofia-sip/sip_tag.h>
*
* @par Events:
* #nua_r_options
......
......@@ -138,7 +138,7 @@ void nua_publish_usage_remove(nua_handle_t *nh,
* @par Related Tags:
* NUTAG_URL() \n
* Tags of nua_set_hparams() \n
* Tags in <sip_tag.h>
* Header tags defined in <sofia-sip/sip_tag.h>
*
* @par Events:
* #nua_r_publish
......@@ -196,7 +196,7 @@ void nua_unpublish(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);
* SIPTAG_IF_MATCH(), SIPTAG_IF_MATCH_STR() \n
* SIPTAG_EVENT(), SIPTAG_EVENT_STR() \n
* Tags of nua_set_hparams() \n
* Tags in <sip_tag.h>
* Other header tags defined in <sofia-sip/sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()
*
* @par Events:
* #nua_r_unpublish
......
......@@ -516,7 +516,7 @@ outbound_owner_vtable nua_stack_outbound_callbacks = {
*
* @par Related tags:
* NUTAG_REGISTRAR() \n
* Tags in <sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()
* Header tags defined in <sofia-sip/sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()
*
* @par Events:
* #nua_r_unregister
......
......@@ -999,7 +999,7 @@ static int nua_invite_client_report(nua_client_request_t *cr,
* nothing
*
* @par Related Tags:
* Tags in <sip_tag.h>
* Header tags defined in <sofia-sip/sip_tag.h>
*
* @par Events:
* #nua_i_media_error \n
......@@ -1217,7 +1217,7 @@ static int nua_invite_client_deinit(nua_client_request_t *cr)
* nothing
*
* @par Related Tags:
* Tags in <sip_tag.h>
* Header tags defined in <sofia-sip/sip_tag.h>
*
* @par Events:
* #nua_r_cancel, #nua_i_state (#nua_i_active, #nua_i_terminated)
......@@ -2714,7 +2714,7 @@ nh_referral_respond(nua_handle_t *nh, int status, char const *phrase)
* nothing
*
* @par Related Tags:
* Tags in <sip_tag.h>.
* Header tags defined in <sofia-sip/sip_tag.h>.
*
* @par Events:
* #nua_r_info
......
......@@ -1336,7 +1336,7 @@ void nua_server_request_destroy(nua_server_request_t *sr)
* SOATAG_AF() \n
* SOATAG_HOLD() \n
* Tags used with nua_set_hparams() \n
* Tags in <sip_tag.h>.
* Header tags defined in <sofia-sip/sip_tag.h>.
*
* @par Events:
* #nua_i_state \n
......
......@@ -138,7 +138,7 @@ void nua_subscribe_usage_remove(nua_handle_t *nh,
*
* @par Related Tags:
* NUTAG_URL()
* Tags in <sip_tag.h>
* Header tags defined in <sofia-sip/sip_tag.h>
*
* @par Events:
* #nua_r_subscribe \n
......@@ -164,7 +164,7 @@ void nua_subscribe_usage_remove(nua_handle_t *nh,
*
* @par Related Tags:
* SIPTAG_EVENT() or SIPTAG_EVENT_STR() \n
* Tags in <sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()
* Header tags defined in <sofia-sip/sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()
*
* @par Events:
* #nua_r_unsubscribe
......@@ -727,7 +727,7 @@ int nua_notify_server_report(nua_server_request_t *sr, tagi_t const *tags)
* @par Related Tags:
* NUTAG_URL() \n
* Tags of nua_set_hparams() \n
* Tags in <sip_tag.h>
* Header tags defined in <sofia-sip/sip_tag.h>
*
* @par Events:
* #nua_r_refer \n
......
......@@ -172,6 +172,7 @@ typedef struct event_s {
/** NUA module version */
SOFIAPUBVAR char const nua_version[];
/** Typedef of NUA event callback. */
typedef void (*nua_callback_f)(nua_event_t event,
int status, char const *phrase,
nua_t *nua, nua_magic_t *magic,
......@@ -349,9 +350,10 @@ SOFIAPUBFUN void nua_respond(nua_handle_t *nh,
/** Check if event can be responded with nua_respond() */
SOFIAPUBFUN int nua_event_is_incoming_request(nua_event_t e);
/** Cast a #nua_handle_t pointer to a #su_home_t. */
#define nua_handle_home(nh) ((su_home_t *)(nh))
/** Generate an instance identifier */
/** Generate an instance identifier. */
SOFIAPUBFUN char const *nua_generate_instance_identifier(su_home_t *);
#ifndef NUA_SAVED_EVENT_T
......
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