Commit 4a6d1391 authored by Pekka Pessi's avatar Pekka Pessi

nua: updated documentation. Moved documentation entries towards implementation.

darcs-hash:20061025081244-65a35-9a77e1c68163fba2f5d2a26823d502236adcfd17.gz
parent d4350e3d
......@@ -176,7 +176,7 @@ nua_t *nua_create(su_root_t *root,
*
* Ongoing calls are released, registrations unregistered, and
* subscriptions terminated. If the stack cannot terminate within
* 30 seconds, it sends the nua_r_shutdown event with status 500.
* 30 seconds, it sends the #nua_r_shutdown event with status 500.
*
* @param nua Pointer to @nua stack object
*
......@@ -290,6 +290,10 @@ nua_handle_t *nua_default(nua_t *nua)
* the handle. They include @ContentLength, @CSeq, @RSeq, @RAck, and
* @Timestamp.
*
* @par
* nua_handle() accepts all the tags accepted by nua_set_hparams(), too.
*
*
* @par Events:
* none
*
......@@ -495,8 +499,8 @@ int nua_handle_has_active_call(nua_handle_t const *nh)
*
* Please note that this status is not affected by remote end putting
* this end on hold. Remote end can put each media separately on hold
* and status is reflected on #SOATAG_ACTIVE_AUDIO, #SOATAG_ACTIVE_VIDEO
* and #SOATAG_ACTIVE_CHAT tag values in nua_i_active event.
* and status is reflected on SOATAG_ACTIVE_AUDIO(), SOATAG_ACTIVE_VIDEO()
* and SOATAG_ACTIVE_CHAT() tag values in #nua_i_state event.
*
* @param nh Pointer to operation handle
*
......@@ -674,6 +678,8 @@ void nua_options(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
* nothing
*
* @par Related Tags:
* NUTAG_URL() \n
* Tags of nua_set_hparams() \n
* Tags in <sip_tag.h>
*
* @par Events:
......@@ -687,8 +693,8 @@ void nua_message(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
/** Send a chat message.
*
* A chat channel can be established during call setup using "message" media.
* An active chat channel is indicated using nua_i_active event containing
* #SOATAG_ACTIVE_CHAT tag. Chat messages can be sent using this channel with
* An active chat channel is indicated using #nua_i_state event containing
* SOATAG_ACTIVE_CHAT() tag. Chat messages can be sent using this channel with
* nua_chat() function. Currently this is implemented using SIP MESSAGE
* requests but in future MSRP (message session protocol) will replace it.
*
......@@ -699,11 +705,11 @@ void nua_message(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
* nothing
*
* @par Related Tags:
* #SIPTAG_CONTENT_TYPE \n
* #SIPTAG_PAYLOAD \n
* #SIPTAG_FROM \n
* #SIPTAG_TO \n
* use of other SIP tags' is deprecated
* SIPTAG_CONTENT_TYPE() \n
* SIPTAG_PAYLOAD() \n
* SIPTAG_FROM() \n
* SIPTAG_TO() \n
* Use of other SIP tags is deprecated
*
* @par Events:
* #nua_r_chat
......@@ -713,52 +719,13 @@ void nua_chat(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
NUA_SIGNAL(nh, nua_r_chat, tag, value);
}
/** Subscribe a SIP event.
*
* Subscribe a SIP event using the SIP SUBSCRIBE request. If the
* SUBSCRBE is successful a subscription state is established and
* the subscription is refreshed regularly. The refresh requests will
* generate #nua_r_subscribe events.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related Tags:
* NUTAG_URL()
* Tags in <sip_tag.h>
*
* @par Events:
* #nua_r_subscribe \n
* #nua_i_notify
*/
/* Documented with nua_stack_subscribe() */
void nua_subscribe(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
NUA_SIGNAL(nh, nua_r_subscribe, tag, value);
}
/** Unsubscribe an event.
*
* Unsubscribe an active or pending subscription with SUBSCRIBE request
* containing Expires: header with value 0. The dialog associated with
* subscription will be destroyed if there is no other subscriptions or
* call using this dialog.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related Tags:
* #SIPTAG_EVENT \n
* Tags in <sip_tag.h> except #SIPTAG_EXPIRES or #SIPTAG_EXPIRES_STR
*
* @par Events:
* #nua_r_unsubscribe
*/
/* Documented with nua_stack_subscribe() */
void nua_unsubscribe(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
NUA_SIGNAL(nh, nua_r_unsubscribe, tag, value);
......@@ -788,10 +755,10 @@ void nua_notify(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
*
* @par Related Tags:
* 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
* #SIPTAG_ACCEPT or #SIPTAG_ACCEPT_STR \n
* SIPTAG_EVENT() or SIPTAG_EVENT_STR() \n
* SIPTAG_CONTENT_TYPE() or SIPTAG_CONTENT_TYPE_STR() \n
* SIPTAG_PAYLOAD() or SIPTAG_PAYLOAD_STR() \n
* SIPTAG_ACCEPT() or SIPTAG_ACCEPT_STR() \n
*
* @par Events:
* #nua_r_notify
......@@ -813,10 +780,10 @@ void nua_notifier(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
* nothing
*
* @par Related Tags:
* #SIPTAG_EVENT \n
* #SIPTAG_CONTENT_TYPE \n
* #SIPTAG_PAYLOAD \n
* #NEATAG_REASON
* SIPTAG_EVENT() \n
* SIPTAG_CONTENT_TYPE() \n
* SIPTAG_PAYLOAD() \n
* NEATAG_REASON()
*
* @par Events:
* #nua_r_terminate
......@@ -828,31 +795,7 @@ void nua_terminate(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
NUA_SIGNAL(nh, nua_r_terminate, tag, value);
}
/** Transfer a call.
*
* Send a REFER request asking the recipient to transfer the call. The REFER
* request also establishes a subscription to the "refer" event. The "refer"
* event will have an "id" parameter, which has the value of CSeq number in
* the REFER request. After initiating the REFER request, the nua engine
* sends application a nua_r_refer event with status 100 and tag
* SIPTAG_EVENT() containing a matching event header.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related Tags:
* NUTAG_URL() \n
* Tags in <sip_tag.h>
*
* @par Events:
* #nua_r_refer \n
* #nua_i_notify
*
* @sa @RFC3515
*/
/* Documented with nua_stack_refer() */
void nua_refer(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
NUA_SIGNAL(nh, nua_r_refer, tag, value);
......@@ -947,34 +890,8 @@ void nua_redirect(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
NUA_SIGNAL(nh, nua_r_redirect, tag, value);
}
/** Respond with given status.
*
* Currently, only request application is let to respond is INVITE.
*
* @param nh Pointer to operation handle
* @param status SIP response status (see RFCs of SIP)
* @param phrase free text (default response phrase used if NULL)
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related Tags:
* NUTAG_EARLY_ANSWER() \n
* #SOATAG_ADDRESS \n
* #SOATAG_AF \n
* #SOATAG_HOLD \n
* Tags in <sip_tag.h>.
*
* @par Events:
* #nua_i_state \n
* #nua_i_media_error \n
* #nua_i_error \n
* #nua_i_active \n
* #nua_i_terminated \n
*
* @sa #nua_i_invite,
*/
/* Documented with nua_stack_respond() */
void nua_respond(nua_handle_t *nh,
int status, char const *phrase,
tag_type_t tag, tag_value_t value,
......@@ -1211,7 +1128,7 @@ static int nua_stack_handle_make_replaces_call(void *arg)
* @since New in @VERSION_1_12_4.
*
* @sa nua_handle_by_replaces(), @Replaces, @RFC3891, nua_refer(),
* nua_i_refer(), @ReferTo, nta_leg_make_replaces()
* #nua_i_refer, @ReferTo, nta_leg_make_replaces()
*/
sip_replaces_t *nua_handle_make_replaces(nua_handle_t *nh,
su_home_t *home,
......@@ -1253,7 +1170,7 @@ static int nua_stack_handle_by_replaces_call(void *arg)
* done with handle.
*
* @sa nua_handle_make_replaces(), @Replaces, @RFC3891, nua_refer(),
* nua_i_refer(), @ReferTo, nta_leg_by_replaces()
* #nua_i_refer, @ReferTo, nta_leg_by_replaces()
*/
nua_handle_t *nua_handle_by_replaces(nua_t *nua, sip_replaces_t const *r)
{
......
......@@ -2044,7 +2044,7 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* @param nh operation handle associated with the original call
* @param hmagic operation magic associated with the original call
* @param sip 200 series response to INVITE
* @param tags #NUTAG_HANDLE of the new forked call
* @param tags NUTAG_HANDLE() of the new forked call
*/
/** @var nua_event_e::nua_i_media_error
......@@ -2099,16 +2099,7 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* @since Experimental in @VERSION_1_12_2.
*/
/** @var nua_event_e::nua_i_notify
*
* Incoming event.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param status statuscode of response sent automatically by stack
* @param sip incoming NOTIFY request
* @param tags #NUTAG_SUBSTATE indicating the subscription state
*/
/* nua_i_notify is documented with nua_stack_process_notify() */
/** @var nua_event_e::nua_i_options
*
......@@ -2192,8 +2183,8 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip NULL
* @param tags #SIPTAG_EVENT \n
* #SIPTAG_CONTENT_TYPE
* @param tags SIPTAG_EVENT() \n
* SIPTAG_CONTENT_TYPE()
*/
/* nua_r_notify is documented with process_response_to_notify() */
......@@ -2209,17 +2200,7 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* @param tags empty
*/
/** @var nua_event_e::nua_r_refer
*
* Answer to outgoing REFER.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip response to REFER request or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags #NUTAG_REFER_EVENT \n
* #NUTAG_SUBSTATE
*/
/* nua_r_refer is documented with process_response_to_refer() */
/** @var nua_event_e::nua_r_shutdown
*
......@@ -2237,19 +2218,7 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* @param tags empty
*/
/** @var nua_event_e::nua_r_subscribe
*
* Answer to outgoing SUBSCRIBE.
*
* The SUBSCRIBE may be sent explicitly by nua_subscribe() 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 SUBSCRIBE request or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags #NUTAG_SUBSTATE
*/
/* nua_r_subscribe is documented with process_response_to_subscribe() */
/** @var nua_event_e::nua_r_terminate
*
......@@ -2261,13 +2230,4 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* @param tags empty
*/
/** @var nua_event_e::nua_r_unsubscribe
*
* Answer to outgoing un-SUBSCRIBE.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip response to SUBSCRIBE request or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags empty
*/
/* nua_r_unsubscribe is documented with process_response_to_subscribe() */
......@@ -313,8 +313,9 @@ static int nua_stack_notify2(nua_t *, nua_handle_t *, nua_event_t,
* nothing
*
* @par Related Tags:
* NUTAG_SUBSTATE() \n
* Tags of nua_set_hparams() \n
* Tags in <sip_tag.h>
* NUTAG_SUBSTATE()
*
* @par Events:
* #nua_r_notify
......
......@@ -270,8 +270,9 @@ int nua_stack_init_instance(nua_handle_t *nh, tagi_t const *tags)
* nothing
*
* @par Related tags:
* NUTAG_ALLOW() \n
* NUTAG_ALLOW_EVENTS() \n
* NUTAG_ALLOW(), SIPTAG_ALLOW(), and SIPTAG_ALLOW_STR() \n
* NUTAG_ALLOW_EVENTS(), SIPTAG_ALLOW_EVENTS(), and
* SIPTAG_ALLOW_EVENTS_STR() \n
* NUTAG_AUTOACK() \n
* NUTAG_AUTOALERT() \n
* NUTAG_AUTOANSWER() \n
......@@ -313,27 +314,16 @@ int nua_stack_init_instance(nua_handle_t *nh, tagi_t const *tags)
* NUTAG_SMIME_SIGNATURE() \n
* NUTAG_SOA_NAME() \n
* NUTAG_SUBSTATE() \n
* NUTAG_SUPPORTED() \n
* NUTAG_SUPPORTED(), SIPTAG_SUPPORTED(), and SIPTAG_SUPPORTED_STR() \n
* NUTAG_UPDATE_REFRESH() \n
* NUTAG_USER_AGENT() \n
* SIPTAG_ALLOW() \n
* SIPTAG_ALLOW_STR() \n
* SIPTAG_ALLOW_EVENTS() \n
* SIPTAG_ALLOW_EVENTS_STR() \n
* SIPTAG_FROM() \n
* SIPTAG_FROM_STR() \n
* SIPTAG_ORGANIZATION() \n
* SIPTAG_ORGANIZATION_STR() \n
* SIPTAG_SUPPORTED() \n
* SIPTAG_SUPPORTED_STR() \n
* SIPTAG_USER_AGENT() \n
* SIPTAG_USER_AGENT_STR() \n
* NUTAG_USER_AGENT(), SIPTAG_USER_AGENT() and SIPTAG_USER_AGENT_STR() \n
* SIPTAG_ORGANIZATION() and SIPTAG_ORGANIZATION_STR() \n
*
* nua_set_params() also accepts any soa tags, defined in
* <sofia-sip/soa_tag.h>, and nta tags, defined in <sofia-sip/nta_tag.h>.
*
* @par Events:
* nua_r_set_params
* #nua_r_set_params
*
* @par SIP Header as NUA Parameters
* The @nua parameters include SIP headers @Allow, @Supported, @Organization,
......@@ -397,8 +387,9 @@ int nua_stack_init_instance(nua_handle_t *nh, tagi_t const *tags)
* nothing
*
* @par Tags Used to Set Handle-Specific Parameters:
* NUTAG_ALLOW() \n
* NUTAG_ALLOW_EVENTS() \n
* NUTAG_ALLOW(), SIPTAG_ALLOW(), and SIPTAG_ALLOW_STR() \n
* NUTAG_ALLOW_EVENTS(), SIPTAG_ALLOW_EVENTS(), and
* SIPTAG_ALLOW_EVENTS_STR() \n
* NUTAG_AUTOACK() \n
* NUTAG_AUTOALERT() \n
* NUTAG_AUTOANSWER() \n
......@@ -432,19 +423,10 @@ int nua_stack_init_instance(nua_handle_t *nh, tagi_t const *tags)
* NUTAG_SESSION_TIMER() \n
* NUTAG_SOA_NAME() \n
* NUTAG_SUBSTATE() \n
* NUTAG_SUPPORTED() \n
* NUTAG_SUPPORTED(), SIPTAG_SUPPORTED(), and SIPTAG_SUPPORTED_STR() \n
* NUTAG_UPDATE_REFRESH() \n
* NUTAG_USER_AGENT() \n
* SIPTAG_ALLOW() \n
* SIPTAG_ALLOW_STR() \n
* SIPTAG_ALLOW_EVENTS() \n
* SIPTAG_ALLOW_EVENTS_STR() \n
* SIPTAG_ORGANIZATION() \n
* SIPTAG_ORGANIZATION_STR() \n
* SIPTAG_SUPPORTED() \n
* SIPTAG_SUPPORTED_STR() \n
* SIPTAG_USER_AGENT() \n
* SIPTAG_USER_AGENT_STR() \n
* NUTAG_USER_AGENT(), SIPTAG_USER_AGENT() and SIPTAG_USER_AGENT_STR() \n
* SIPTAG_ORGANIZATION() and SIPTAG_ORGANIZATION_STR() \n
* Any soa tags are also considered as handle-specific parameters. They are
* defined in <sofia-sip/soa_tag.h>.
*
......@@ -452,7 +434,7 @@ int nua_stack_init_instance(nua_handle_t *nh, tagi_t const *tags)
* NUTAG_DETECT_NETWORK_UPDATES(), NUTAG_SMIME_* tags, and all NTA tags.
*
* @par Events:
* nua_r_set_params
* #nua_r_set_params
*/
int nua_stack_set_params(nua_t *nua, nua_handle_t *nh, nua_event_t e,
......@@ -1285,11 +1267,11 @@ int nua_stack_set_smime_params(nua_t *nua, tagi_t const *tags)
/**@fn void nua_get_hparams(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
*
* Get values of handle-specific parameters in nua_r_get_params event.
* Get values of handle-specific parameters in #nua_r_get_params event.
*
* Application will specify either expilicit list of tags it is interested
* in, or a filter (at the moment, TAG_ANY()). The values are returned as a
* list of tags in the nua_r_get_params event.
* list of tags in the #nua_r_get_params event.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
......
......@@ -145,6 +145,7 @@ static int process_response_to_publish(nua_handle_t *nh,
*
* @par Related Tags:
* NUTAG_URL() \n
* Tags of nua_set_hparams() \n
* Tags in <sip_tag.h>
*
* @par Events:
......@@ -182,6 +183,7 @@ void nua_unpublish(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);
*
* @par Related Tags:
* NUTAG_URL() \n
* Tags of nua_set_hparams() \n
* Tags in <sip_tag.h>
*
* @par Events:
......
......@@ -414,7 +414,7 @@ outbound_owner_vtable nua_stack_outbound_callbacks = {
* 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
* application using #nua_i_outbound event, and start unregistration
* procedure (unless that has been explicitly disabled).
*
* You can disable validation by inserting "no-validate" into
......
......@@ -351,30 +351,9 @@ int respond_with_retry_after(nua_handle_t *nh, nta_incoming_t *irq,
* nothing
*
* @par Related Tags:
* NUTAG_URL(),
* NUTAG_NOTIFY_REFER(),
* NUTAG_ALLOW(),
* NUTAG_AUTOACK(),
* NUTAG_AUTOALERT(),
* NUTAG_AUTOANSWER(),
* NUTAG_CALLEE_CAPS(),
* NUTAG_EARLY_MEDIA(),
* NUTAG_ENABLEINVITE(),
* NUTAG_ENABLEMESSAGE(),
* NUTAG_ENABLEMESSENGER(),
* NUTAG_INVITE_TIMER(),
* NUTAG_MEDIA_ENABLE(),
* NUTAG_MIN_SE(),
* NUTAG_ONLY183_100REL(),
* NUTAG_REFER_EXPIRES(),
* NUTAG_RETRY_COUNT(),
* NUTAG_SERVICE_ROUTE_ENABLE(),
* NUTAG_SESSION_REFRESHER(),
* NUTAG_SESSION_TIMER(),
* NUTAG_SOA_NAME(),
* NUTAG_SUPPORTED(),
* NUTAG_UPDATE_REFRESH(),
* NUTAG_USER_AGENT() \n
* NUTAG_URL() \n
* Tags of nua_set_hparams() \n
* NUTAG_INCLUDE_EXTRA_SDP() \n
* SOATAG_HOLD(), SOATAG_AF(), SOATAG_ADDRESS(),
* SOATAG_RTP_SELECT(), SOATAG_RTP_SORT(), SOATAG_RTP_MISMATCH(),
* SOATAG_AUDIO_AUX(), \n
......@@ -3222,7 +3201,7 @@ static void signal_call_state_change(nua_handle_t *nh,
* NUTAG_ANSWER_RECV(). SOATAG_ACTIVE_AUDIO() and SOATAG_ACTIVE_VIDEO() are
* informational tags used to indicate what is the status of these media.
*
* Note that nua_event_e::nua_i_state also covers call establisment events
* Note that #nua_i_state also covers call establisment events
* (#nua_i_active) and termination (#nua_i_terminated).
*
* @param status Protocol status code. \n
......
......@@ -1950,7 +1950,57 @@ int nua_default_respond(nua_server_request_t *sr,
return sr->sr_status >= 200 ? sr->sr_status : 0;
}
/** Respond to an request with given status.
*
* When nua protocol engine receives an incoming SIP request, it can either
* respond to the request automatically or let it up to application to
* respond to the request. The automatic answer is sent if the request fails
* because of method, SIP extension or, in some times, MIME content
* negotiation fails.
*
* When responding to an incoming INVITE request, the nua_respond() can be
* called without NUTAG_WITH() (or NUTAG_WITH_CURRENT() or
* NUTAG_WITH_SAVED()). Otherwise, NUTAG_WITH() will contain an indication
* of the request being responded.
*
* In order to simplify the application, most requests are responded
* automatically. The set of requests always responded by the stack include
* BYE, CANCEL and NOTIFY. The application can add methods that it likes to
* handle by itself with NUTAG_APPL_METHOD(). The default set of
* NUTAG_APPL_METHOD() include INVITE, PUBLISH, REGISTER and SUBSCRIBE. Note
* that unless the method is also added to the set of allowed methods with
* NUTAG_ALLOW(), the stack will respond to the incoming methods with <i>405
* Not Allowed</i>.
*
* Note that certain methods are rejected outside a SIP session (created
* with INVITE transaction). They include BYE, UPDATE, PRACK and INFO.
*
* @param nh Pointer to operation handle
* @param status SIP response status (see RFCs of SIP)
* @param phrase free text (default response phrase used if NULL)
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related Tags:
* NUTAG_WITH(), NUTAG_WITH_CURRENT(), NUTAG_WITH_SAVED() \n
* NUTAG_EARLY_ANSWER() \n
* SOATAG_ADDRESS() \n
* SOATAG_AF() \n
* SOATAG_HOLD() \n
* Tags in <sip_tag.h>.
*
* @par Events:
* #nua_i_state \n
* #nua_i_media_error \n
* #nua_i_error \n
* #nua_i_active \n
* #nua_i_terminated \n
*
* @sa #nua_i_invite, #nua_i_register, #nua_i_subscribe, #nua_i_publish
*/
void
nua_stack_respond(nua_t *nua, nua_handle_t *nh,
int status, char const *phrase, tagi_t const *tags)
......
......@@ -118,10 +118,58 @@ void nua_subscribe_usage_remove(nua_handle_t *nh,
/* ====================================================================== */
/* SUBSCRIBE */
/** Subscribe to a SIP event.
*
* Subscribe a SIP event using the SIP SUBSCRIBE request. If the
* SUBSCRBE is successful a subscription state is established and
* the subscription is refreshed regularly. The refresh requests will
* generate #nua_r_subscribe events.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related Tags:
* NUTAG_URL()
* Tags in <sip_tag.h>
*
* @par Events:
* #nua_r_subscribe \n
* #nua_i_notify
*
* @sa NUTAG_SUBSTATE(), @RFC3265
*/
/** Unsubscribe an event.
*
* Unsubscribe an active or pending subscription with SUBSCRIBE request
* containing Expires: header with value 0. The dialog associated with
* subscription will be destroyed if there is no other subscriptions or
* call using this dialog.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related Tags:
* SIPTAG_EVENT() or SIPTAG_EVENT_STR() \n
* Tags in <sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()
*
* @par Events:
* #nua_r_unsubscribe
*
* @sa NUTAG_SUBSTATE(), @RFC3265
*/
static int process_response_to_subscribe(nua_handle_t *nh,
nta_outgoing_t *orq,
sip_t const *sip);
int
nua_stack_subscribe(nua_t *nua, nua_handle_t *nh, nua_event_t e,
tagi_t const *tags)
......@@ -247,6 +295,35 @@ static void restart_subscribe(nua_handle_t *nh, tagi_t *tags)
nua_creq_restart(nh, nh->nh_cr, process_response_to_subscribe, tags);
}
/** @var nua_event_e::nua_r_subscribe
*
* Response to an outgoing SUBSCRIBE.
*
* The SUBSCRIBE request may have been sent explicitly by nua_subscribe() 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 SUBSCRIBE request or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags NUTAG_SUBSTATE()
*
* @sa nua_subscribe(), @RFC3265
*/
/** @var nua_event_e::nua_r_unsubscribe
*
* Response to an outgoing un-SUBSCRIBE.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip response to SUBSCRIBE request or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags NUTAG_SUBSTATE()
*
* @sa nua_unsubscribe(), @RFC3265
*/
static int process_response_to_subscribe(nua_handle_t *nh,
nta_outgoing_t *orq,
sip_t const *sip)
......@@ -472,6 +549,19 @@ static int nua_subscribe_usage_shutdown(nua_handle_t *nh,
/* ======================================================================== */
/* NOTIFY server */
/** @var nua_event_e::nua_i_notify
*
* Event for incoming NOTIFY request.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param status statuscode of response sent automatically by stack
* @param sip incoming NOTIFY request
* @param tags NUTAG_SUBSTATE() indicating the subscription state
*
* @sa nua_subscribe(), nua_unsubscribe(), @RFC3265, #nua_i_subscribe
*/
/** @internal Process incoming NOTIFY. */
int nua_stack_process_notify(nua_t *nua,
nua_handle_t *nh,
......@@ -647,6 +737,39 @@ int nua_stack_process_notify(nua_t *nua,
/* ======================================================================== */
/* REFER */
/** Transfer a call.
*
* Send a REFER request asking the recipient to transfer the call. The REFER
* request also establishes an implied subscription to the "refer" event.
* The "refer" event can have an "id" parameter, which has the value of
* CSeq number in the REFER request. After initiating the REFER request, the
* nua engine sends application a #nua_r_refer event with status 100 and tag
* NUTAG_REFER_EVENT() containing a matching event header.
*
* Note that the event header in #nua_r_refer event contains an @a id
* parameter. The recipient of the REFER request may or may not use the @a
* id parameter in the NOTIFY messages it sends to the sender of the REFER
* request. Therefore the application may not modify the state of the
* implied subscription before receiving the first NOTIFY request.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related Tags:
* NUTAG_URL() \n
* Tags of nua_set_hparams() \n
* Tags in <sip_tag.h>
*
* @par Events:
* #nua_r_refer \n
* #nua_i_notify
*
* @sa NUTAG_SUBSTATE(), @RFC3515,
*/
static int process_response_to_refer(nua_handle_t *nh,
nta_outgoing_t *orq,
sip_t const *sip);
......@@ -722,6 +845,18 @@ void restart_refer(nua_handle_t *nh, tagi_t *tags)
nua_stack_refer(nh->nh_nua, nh, nh->nh_cr->cr_event, tags);
}
/** @var nua_event_e::nua_r_refer
*
* Answer to outgoing REFER.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip response to REFER request or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags NUTAG_REFER_EVENT() \n
* NUTAG_SUBSTATE()
*/
static int process_response_to_refer(nua_handle_t *nh,
nta_outgoing_t *orq,
sip_t const *sip)
......
......@@ -409,8 +409,12 @@ SOFIAPUBVAR tag_typedef_t nutag_invite_timer_ref;
* Re-INVITE will be sent in given intervals.
*
* @par Used with
* nua_set_params() \n
* nua_get_params()
* nua_invite(), nua_update(), nua_respond() \n
* nua_set_params() or nua_set_hparams() \n
* nua_get_params() or nua_get_hparams()
*
* See nua_set_hparams() for a complete list of the the nua operations that
* accept this tag.
*
* @par Parameter type
* unsigned int
......@@ -420,6 +424,9 @@ SOFIAPUBVAR tag_typedef_t nutag_invite_timer_ref;
* @c >0 interval in seconds
*
* Corresponding tag taking reference parameter is NUTAG_SESSION_TIMER_REF()
*
* @sa NUTAG_MIN_SE(), NUTAG_SESSION_REFRESHER(),
* NUTAG_UPDATE_REFRESH(), @RFC4028, @SessionExpires, @MinSE
*/
#define NUTAG_SESSION_TIMER(x) nutag_session_timer, tag_uint_v((x))
SOFIAPUBVAR tag_typedef_t nutag_session_timer;
......@@ -429,11 +436,17 @@ SOFIAPUBVAR tag_typedef_t nutag_session_timer_ref;