Commit f36532e8 authored by Pekka Pessi's avatar Pekka Pessi

nua: updated documentation.

darcs-hash:20061115171720-65a35-3a6abb1753922d7ffb6f41ee59aa19cdae9df65a.gz
parent f754be5e
......@@ -32,4 +32,4 @@ ALIASES += END_NUA_EVENT="@par  "
VERBATIM_HEADERS = NO
@INCLUDE = ../sip/sip.doxyaliases
\ No newline at end of file
@INCLUDE = ../sip/sip.doxyaliases
......@@ -571,22 +571,32 @@ void app_r_invite(int status,
} /* app_r_invite */
@endcode
The app_i_state() function is called by callback function when call has
been successfully set up and the media has been activated.
The nua_i_state event is sent (and app_i_state() function called by callback
function) when the call state changes (see @ref nua_uac_call_model
"client-side call model").
@code
void app_i_active(int status,
char const *phrase,
nua_t *nua,
nua_magic_t *magic,
nua_handle_t *nh,
nua_hmagic_t *hmagic,
sip_t const *sip,
tagi_t tags[])
void app_i_state(int status,
char const *phrase,
nua_t *nua,
nua_magic_t *magic,
nua_handle_t *nh,
nua_hmagic_t *hmagic,
sip_t const *sip,
tagi_t tags[])
{
printf("call active\n");
nua_callstate_t state = nua_callstate_init;
} /* app_i_active */
tl_gets(tags,
NUTAG_CALLSTATE_REF(state),
NUTAG__REF(state),
state = (nua_callstate_t)t->t_value;
printf("call %s\n", nua_callstate_name(state));
} /* app_i_state */
@endcode
@subsection nua_receiveacall Receive a call
......@@ -607,12 +617,12 @@ void app_i_invite(int status,
{
printf("incoming call\n");
nua_respond(nh, 200, "OK", TAG_END());
nua_respond(nh, 200, "OK", SOA_USER_SDP(magic->sdp), TAG_END());
} /* app_i_invite */
@endcode
The app_i_active() function is called by the callback function when call has
The app_i_state() function is called by the callback function when call has
been successfully set up and the media has been activated.
@code
......
......@@ -69,7 +69,7 @@
* @par Events:
* #nua_r_message
*
* @sa nua_i_message, @RFC3428
* @sa #nua_i_message, @RFC3428
*/
static int process_response_to_message(nua_handle_t *nh,
......
......@@ -427,10 +427,11 @@ int respond_with_retry_after(nua_handle_t *nh, nta_incoming_t *irq,
* @par
* The INVITE request message created by nua_invite() operation is saved as
* a template for automatic re-INVITE requests sent by the session timer
* ("timer") feature. Please note that the template message is not used when
* ACK, PRACK, UPDATE or INFO requests are created (however, these requests
* will include dialog-specific headers like @To, @From, and @CallID as well
* as preference headers @Allow, @Supported, @UserAgent, @Organization).
* ("timer") feature (see NUTAG_SESSION_TIMER() for more details). Please
* note that the template message is not used when ACK, PRACK, UPDATE or
* INFO requests are created (however, these requests will include
* dialog-specific headers like @To, @From, and @CallID as well as
* preference headers @Allow, @Supported, @UserAgent, @Organization).
*
* @par SDP Handling
* The initial nua_invite() creates a @ref soa_session_t "soa media session"
......@@ -3285,7 +3286,7 @@ static int process_response_to_bye(nua_handle_t *nh,
* @param sip pointer to BYE request
* @param tags empty
*
* @sa @ref nua_call_model, #nua_i_state, nua_bye(), nua_r_bye(), #nua_r_cancel
* @sa @ref nua_call_model, #nua_i_state, nua_bye(), nua_bye(), #nua_r_cancel
*
* @END_NUA_EVENT
*/
......@@ -3421,16 +3422,20 @@ static void signal_call_state_change(nua_handle_t *nh,
*
* @brief Call state has changed.
*
* This event will be sent whenever the call state changes. In addition to
* basic changes of session status indicated with enum ::nua_callstate, the
* @RFC3264 SDP Offer/Answer negotiation status is also included. The
* negotiation status includes the local SDP (in SOATAG_LOCAL_SDP()) sent
* and flags indicating whether the local SDP was an offer or answer
* (NUTAG_OFFER_SENT(), NUTAG_ANSWER_SENT()). Likewise, the received remote
* SDP is included in tag SOATAG_REMOTE_SDP() and flags indicating whether
* the remote SDP was an offer or an answer in tags NUTAG_OFFER_RECV() or
* NUTAG_ANSWER_RECV(). SOATAG_ACTIVE_AUDIO() and SOATAG_ACTIVE_VIDEO() are
* informational tags used to indicate what is the status of these media.
* This event will be sent whenever the call state changes.
*
* In addition to basic changes of session status indicated with enum
* ::nua_callstate, the @RFC3264 SDP Offer/Answer negotiation status is also
* included if it is enabled (by default or with NUTAG_MEDIA_ENABLE(1)). The
* received remote SDP is included in tag SOATAG_REMOTE_SDP(). The tags
* NUTAG_OFFER_RECV() or NUTAG_ANSWER_RECV() indicate whether the remote SDP
* was an offer or an answer. The SDP negotiation result is included in the
* tags SOATAG_LOCAL_SDP() and SOATAG_LOCAL_SDP_STR() and tags
* NUTAG_OFFER_SENT() or NUTAG_ANSWER_SENT() indicate whether the local SDP
* was an offer or answer.
*
* SOATAG_ACTIVE_AUDIO() and SOATAG_ACTIVE_VIDEO() are informational tags
* used to indicate what is the status of audio or video.
*
* Note that #nua_i_state also covers call establisment events
* (#nua_i_active) and termination (#nua_i_terminated).
......@@ -3834,7 +3839,7 @@ static int respond_to_options(nua_server_request_t *sr, tagi_t const *tags);
* @param sip incoming OPTIONS request
* @param tags empty
*
* @sa nua_respond(), nua_options(), nua_r_options(), @RFC3261 section 11.2
* @sa nua_respond(), nua_options(), #nua_r_options, @RFC3261 section 11.2
*
* @END_NUA_EVENT
*/
......
......@@ -85,7 +85,7 @@ typedef enum nua_event_e {
/* Indications */
nua_i_error, /**< Error indication */
nua_i_invite, /**< Incoming call */
nua_i_invite, /**< Incoming call INVITE */
nua_i_cancel, /**< Incoming INVITE has been cancelled */
nua_i_ack, /**< Final response to INVITE has been ACKed */
nua_i_fork, /**< Outgoing call has been forked */
......@@ -95,24 +95,25 @@ typedef enum nua_event_e {
nua_i_outbound, /**< Status from outbound processing */
nua_i_bye, /**< Incoming call hangup */
nua_i_options, /**< Incoming options */
nua_i_refer, /**< Incoming call transfer */
nua_i_bye, /**< Incoming BYE call hangup */
nua_i_options, /**< Incoming OPTIONS */
nua_i_refer, /**< Incoming REFER call transfer */
nua_i_publish, /**< Incoming PUBLISH */
nua_i_prack, /**< Incoming PRACK */
nua_i_info, /**< Incoming session INFO */
nua_i_update, /**< Incoming session UPDATE */
nua_i_message, /**< Incoming MESSAGE */
nua_i_chat, /**< Incoming chat MESSAGE */
nua_i_subscribe, /**< Incoming subscription */
nua_i_subscribe, /**< Incoming SUBSCRIBE */
nua_i_subscription, /**< Incoming subscription to be authorized */
nua_i_notify, /**< Incoming event */
nua_i_notify, /**< Incoming event NOTIFY */
nua_i_method, /**< Incoming, unknown method */
nua_i_media_error, /**< Offer-answer error indication */
/* Responses */
nua_r_set_params, /**< Answer to nua_set_params() */
nua_r_set_params, /**< Answer to nua_set_params() or
* nua_get_hparams(). */
nua_r_get_params, /**< Answer to nua_get_params() or
* nua_get_hparams(). */
nua_r_shutdown, /**< Answer to nua_shutdown() */
......@@ -140,8 +141,9 @@ typedef enum nua_event_e {
nua_r_notify, /**< Answer to outgoing NOTIFY */
nua_r_method, /**< Answer to unknown outgoing method */
nua_r_authenticate, /**< Answer to nua_authenticate() */
/* Internal events: nua hides them from application */
nua_r_authenticate,
nua_r_redirect,
nua_r_destroy,
nua_r_respond,
......@@ -318,7 +320,7 @@ SOFIAPUBFUN void nua_bye(nua_handle_t *, tag_type_t, tag_value_t, ...);
/** Cancel an INVITE operation */
SOFIAPUBFUN void nua_cancel(nua_handle_t *, tag_type_t, tag_value_t, ...);
/** Authenticate an operation. */
SOFIAPUBFUN void nua_authenticate(nua_handle_t *, tag_type_t, tag_value_t, ...);
......
......@@ -201,6 +201,8 @@ SOFIAPUBVAR tag_typedef_t nutag_method_ref;
* @par Values
* @c 0 Do not allow any subscriptions \n
*
* @sa nua_notifier(), nua_authorize()
*
* Corresponding tag taking reference parameter is
* NUTAG_MAX_SUBSCRIPTIONS_REF()
*/
......@@ -430,8 +432,46 @@ SOFIAPUBVAR tag_typedef_t nutag_invite_timer_ref;
/**Default session timer in seconds.
*
* Set default session timer in seconds when using session timer extension.
* Re-INVITE will be sent in given intervals.
* Set default session timer in seconds when using session timer extension.
* The value given here is the proposed session expiration time in seconds.
* Note that the session timer extension is ponly used
*
* @par Sending INVITE and UPDATE Requests
*
* If NUTAG_SESSION_TIMER() is used with non-zero value, the value is
* used in the @SessionExpires header included in the INVITE or UPDATE
* requests. The intermediate proxies or the ultimate destination can lower
* the interval in @SessionExpires header. If the value is too low, they can
* reject the request with the status code <i>422 Session Timer Too
* Small</i>. When Re-INVITE will be sent in given intervals. In that case,
* @b nua retries the request automatically.
*
* @par Returning Response to the INVITE and UPDATE Requests
*
* The NUTAG_SESSION_TIMER() value is also used when sending the final
* response to the INVITE or UPDATE requests. If the NUTAG_SESSION_TIMER()
* value is 0 or the value in the @SessionExpires header of the requeast is
* lower than the value in NUTAG_SESSION_TIMER(), the value from the
* incoming @SessionExpires header is used. However, if the value in
* @SessionExpires is lower than the minimal acceptable session expiration
* interval specified with the tag NUTAG_MIN_SE() the request is
* automatically rejected with <i>422 Session Timer Too Small</i>.
*
* @par When to Use NUTAG_SESSION_TIMER()?
*
* The session time extension is enabled ("timer" feature tag is included in
* @Supported header) but not activated by default (no @SessionExpires
* header is included in the requests or responses by default). Using
* non-zero value with NUTAG_SESSION_TIMER() activates it. When the
* extension is activated, @nua refreshes the call state by sending periodic
* re-INVITE or UPDATE requests unless the remote end indicated that it will
* take care of refreshes.
*
* The session timer extension is mainly useful for proxies or back-to-back
* user agents that keep call state. The call state is "soft" meaning that
* if no call-related SIP messages are processed for certain time the state
* will be destroyed. An ordinary user-agent can also make use of session
* timer if it cannot get any activity feedback from RTP or other media.
*
* @par Used with
* nua_invite(), nua_update(), nua_respond() \n
......@@ -450,7 +490,9 @@ SOFIAPUBVAR tag_typedef_t nutag_invite_timer_ref;
*
* Corresponding tag taking reference parameter is NUTAG_SESSION_TIMER_REF()
*
* @sa NUTAG_MIN_SE(), NUTAG_SESSION_REFRESHER(),
* @sa NUTAG_SUPPORTED(), NUTAG_MIN_SE(), NUTAG_SESSION_REFRESHER(),
* nua_invite(), #nua_r_invite, #nua_i_invite, nua_update(), #nua_r_update,
* #nua_i_update,
* NUTAG_UPDATE_REFRESH(), @RFC4028, @SessionExpires, @MinSE
*/
#define NUTAG_SESSION_TIMER(x) nutag_session_timer, tag_uint_v((x))
......@@ -1553,7 +1595,7 @@ SOFIAPUBVAR tag_typedef_t nutag_refer_event_ref;
*
* Corresponding tag taking reference parameter is NUTAG_REFER_PAUSE_REF()
*
* @todo Not implemented.
* @deprecated Not implemented.
*/
#define NUTAG_REFER_PAUSE(x) nutag_refer_pause, tag_bool_v(x)
SOFIAPUBVAR tag_typedef_t nutag_refer_pause;
......@@ -1623,6 +1665,44 @@ SOFIAPUBVAR tag_typedef_t nutag_allow;
#define NUTAG_ALLOW_REF(x) nutag_allow_ref, tag_str_vr(&(x))
SOFIAPUBVAR tag_typedef_t nutag_allow_ref;
/** Indicate that a method (or methods) are handled by application.
*
* This tag is used to add a new method to the already existing set of
* methods handled by application, or clear the set. If you want to
* determine the set explicitly, include NUTAG_APPL_METHOD() twice,
* first with NULL and then with your supported set.
*
* The default set of application methods now include INVITE, REGISTER,
* PUBLISH and SUBSCRIBE.
*
* If the request method is in the set of methods handled by application,
* the nua stack does not automatically respond to the incoming request nor
* it will automatically send such a request. Note if the application adds
* the PRACK and UPDATE requests to the set of application methods it must
* also take care for sending the PRACK and UPDATE requests during the call
* setup when necessary.
*
* @par Used with
* nua_set_params() \n
* nua_set_hparams() \n
* any handle-specific nua call
*
* @par Parameter type
* char const *
*
* @par Values
* Valid method name, or comma-separated list of them.
*
* Corresponding tag taking reference parameter is NUTAG_APPL_METHOD_REF()
*/
#define NUTAG_APPL_METHOD(x) nutag_appl_method, tag_str_v(x)
SOFIAPUBVAR tag_typedef_t nutag_appl_method;
#define NUTAG_APPL_METHOD_REF(x) nutag_appl_method_ref, tag_str_vr(&(x))
SOFIAPUBVAR tag_typedef_t nutag_appl_method_ref;
/** Support a feature.
*
* This tag is used to add a new feature to the existing set of supported
......@@ -1897,7 +1977,10 @@ SOFIAPUBVAR tag_typedef_t nutag_service_route_enable;
nutag_service_route_enable_ref, tag_bool_vr(&(x))
SOFIAPUBVAR tag_typedef_t nutag_service_route_enable_ref;
/** Enable local media (MSS)
/** Enable built-in media session handling
*
* The built-in media session object @soa takes care of most details
* of offer-answer negotiation.
*
* @par Used with
* nua_create()
......
......@@ -78,7 +78,7 @@ int test_nua_init(struct context *ctx,
ctx->root = su_root_create(NULL);
TEST_1(ctx->root);
/* Disable threading by command line switch? */
/* Disable threading by command line switch -s */
su_root_threading(ctx->root, ctx->threading);
if (start_proxy && !o_proxy) {
......
......@@ -530,7 +530,7 @@ int test_refer0(struct context *ctx, int refer_with_id, char const *tests)
TEST(e->data->e_status, 200);
TEST_1(e = e->next); TEST_E(e->data->e_event, nua_i_state);
TEST(callstate(e->data->e_tags), nua_callstate_terminated); /* TERMINATED */
TEST_1(!e->next);
assert(!e->next); TEST_1(!e->next);
free_events_in_list(ctx, c->events);
if (print_headings)
......
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