Commit 96dd1df0 authored by Pekka Pessi's avatar Pekka Pessi

nua: updated documentation of nua events

darcs-hash:20061110073313-65a35-45150fe2bd0ab9b6fb8d48d42c56efdf71d366db.gz
parent e2099ea6
......@@ -27,6 +27,9 @@ ALIASES += nua="@ref index \"nua\""
# When GENERATE_TAGFILE=YES, we should use \ref main
#ALIASES += nua="@ref main \"nua\""
ALIASES += NUA_EVENT="@var nua_event_e::"
ALIASES += END_NUA_EVENT="@par  "
VERBATIM_HEADERS = NO
@INCLUDE = ../sip/sip.doxyaliases
\ No newline at end of file
......@@ -117,6 +117,8 @@ su_log_t nua_log[] = { SU_LOG_INIT("nua", "NUA_DEBUG", SU_DEBUG) };
*
* @par Events:
* none
*
* @sa nua_shutdown(), nua_destroy(), nua_handle()
*/
nua_t *nua_create(su_root_t *root,
nua_callback_f callback,
......@@ -172,23 +174,8 @@ nua_t *nua_create(su_root_t *root,
return nua;
}
/**Shutdown a @nua stack.
*
* 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.
*
* @param nua Pointer to @nua stack object
*
* @return
* nothing
*
* @par Related tags:
* none
*
* @par Events:
* #nua_r_shutdown
*/
/* nua_shutdown() is documented with nua_stack_shutdown() */
void nua_shutdown(nua_t *nua)
{
enter;
......@@ -215,6 +202,8 @@ void nua_shutdown(nua_t *nua)
*
* @par Events:
* none
*
* @sa nua_shutdown(), nua_create(), nua_handle_destroy(), nua_handle_unref()
*/
void nua_destroy(nua_t *nua)
{
......@@ -903,7 +892,8 @@ void nua_respond(nua_handle_t *nh,
* @par Events:
* none
*
* @sa nua_handle(), nua_handle_bind(), nua_handle_ref(), nua_handle_unref().
* @sa nua_handle(), nua_handle_bind(), nua_handle_ref(), nua_handle_unref(),
* nua_unregister(), nua_unpublish(), nua_unsubscribe(), nua_bye().
*/
void nua_handle_destroy(nua_handle_t *nh)
{
......
This diff is collapsed.
......@@ -116,17 +116,25 @@ void restart_message(nua_handle_t *nh, tagi_t *tags)
nua_creq_restart(nh, nh->nh_ds->ds_cr, process_response_to_message, tags);
}
/** @var nua_event_e::nua_r_message
/** @NUA_EVENT nua_r_message
*
* Response to an outgoing MESSAGE.
* Response to an outgoing @b MESSAGE request.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param status response status code
* (if the request is retried, @a status is 100, the @a
* sip->sip_status->st_status contain the real status code
* from the response message, e.g., 302, 401, or 407)
* @param phrase a short textual description of @a status code
* @param nh operation handle associated with the message
* @param hmagic application context associated with the handle
* @param sip response to MESSAGE request or NULL upon an error
* (error code and message are in status an phrase parameters)
* (status code is in @a status and
* descriptive message in @a phrase parameters)
* @param tags empty
*
* @sa nua_message(), #nua_i_message, @RFC3428
*
* @END_NUA_EVENT
*/
static int process_response_to_message(nua_handle_t *nh,
......@@ -138,24 +146,26 @@ static int process_response_to_message(nua_handle_t *nh,
return nua_stack_process_response(nh, nh->nh_ds->ds_cr, orq, sip, TAG_END());
}
/** @var nua_event_e::nua_i_message
/** @NUA_EVENT nua_i_message
*
* Incoming MESSAGE.
* @brief Incoming @b MESSAGE request.
*
* The MESSAGE request does not create a dialog. Currently the processing
* of incoming MESSAGE creates a new handle for each incoming request which
* is not assiciated with an existing dialog. If the handle @a nh is not
* bound, you should probably destroy it after responding to the MESSAGE
* request.
* The @b MESSAGE request does not create a dialog. If the incoming @b
* MESSAGE request is not assiciated with an existing dialog the stack
* creates a new handle for it. If the handle @a nh is not bound, you should
* probably destroy it after responding to the MESSAGE request.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param status status code of response sent automatically by stack
* @param phrase a short textual description of @a status code
* @param nh operation handle associated with the message
* @param hmagic application context associated with the handle
* (maybe NULL if outside session)
* @param status statuscode of response sent automatically by stack
* @param sip incoming MESSAGE request
* @param tags empty
*
* @sa nua_message(), #nua_r_message, @RFC3428
* @sa nua_message(), #nua_r_message, @RFC3428, @RFC3862
*
* @END_NUA_EVENT
*/
int nua_stack_process_message(nua_t *nua,
......
......@@ -117,9 +117,12 @@ void nua_notify_usage_remove(nua_handle_t *nh,
static int respond_to_subscribe(nua_server_request_t *sr, tagi_t const *tags);
/** @var nua_event_e::nua_i_subscribe
/** @NUA_EVENT nua_i_subscribe
*
* Incoming subscription request.
* Incoming @b SUBSCRIBE request.
*
* @b SUBSCRIBE request is used to query SIP event state or establish a SIP
* event subscription.
*
* Initial SUBSCRIBE requests are dropped with <i>489 Bad Event</i>
* response, unless the application has explicitly included the @Event in
......@@ -143,12 +146,18 @@ static int respond_to_subscribe(nua_server_request_t *sr, tagi_t const *tags);
* implicitly by REFER request. See #nua_i_refer how the application must
* handle the REFER requests.
*
* @param nh
* @param hmagic
* @param status status code of response sent automatically by stack
* @param phrase response phrase sent automatically by stack
* @param nh operation handle associated with the incoming request
* @param hmagic application context associated with the handle
* (NULL when handle is created by the stack)
* @param sip SUBSCRIBE request headers
* @param tags NUTAG_SUBSTATE()
*
* @sa @RFC3265, nua_notify(), NUTAG_SUBSTATE(), @SubscriptionState,
* @Event, nua_subscribe(), #nua_r_subscribe, #nua_i_refer, nua_refer()
*
* @END_NUA_EVENT
*/
......@@ -492,22 +501,30 @@ void restart_notify(nua_handle_t *nh, tagi_t *tags)
nua_creq_restart(nh, nh->nh_ds->ds_cr, process_response_to_notify, tags);
}
/** @var nua_event_e::nua_r_notify
/** @NUA_EVENT nua_r_notify
*
* Response to an outgoing NOTIFY request.
* Response to an outgoing @b NOTIFY request.
*
* The NOTIFY may be sent explicitly by nua_notify() or implicitly by NUA
* state machine. Implicit NOTIFY is sent when an established dialog is
* The @b NOTIFY may be sent explicitly by nua_notify() or implicitly by NUA
* state machine. Implicit @b NOTIFY is sent when an established dialog is
* refreshed by client or it is terminated (either by client or because of a
* timeout)
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip response to NOTIFY request or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags NUTAG_SUBSTATE() indicating subscription state
* @param status response status code
* (if the request is retried, @a status is 100, the @a
* sip->sip_status->st_status contain the real status code
* from the response message, e.g., 302, 401, or 407)
* @param phrase a short textual description of @a status code
* @param nh operation handle associated with the subscription
* @param hmagic application context associated with the handle
* @param sip response to @b NOTIFY request or NULL upon an error
* (status code is in @a status and
* descriptive message in @a phrase parameters)
* @param tags NUTAG_SUBSTATE() indicating subscription state
*
* @sa @RFC3265, #nua_i_subscribe, #nua_i_refer
* @sa nua_notify(), @RFC3265, #nua_i_subscribe, #nua_i_refer
*
* @END_NUA_EVENT
*/
static int process_response_to_notify(nua_handle_t *nh,
......@@ -591,20 +608,24 @@ static int nua_notify_usage_shutdown(nua_handle_t *nh,
/* REFER */
/* RFC 3515 */
/** @var nua_event_e::nua_i_refer
/** @NUA_EVENT nua_i_refer
*
* Incoming call transfer request.
* Incoming @b REFER request used to transfer calls.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* (NULL if outside session)
* @param status statuscode of response sent automatically by stack
* @param status status code of response sent automatically by stack
* @param phrase a short textual description of @a status code
* @param nh operation handle associated with the incoming request
* @param hmagic application context associated with the handle
* (NULL if outside of an already established session)
* @param sip incoming REFER request
* @param tags NUTAG_REFER_EVENT() \n
* SIPTAG_REFERRED_BY()
*
* @sa nua_refer(), #nua_r_refer, NUTAG_NOTIFY_REFER(),
*
* @sa nua_refer(), #nua_r_refer, @ReferTo, NUTAG_REFER_EVENT(),
* SIPTAG_REFERRED_BY(), @ReferredBy, NUTAG_NOTIFY_REFER(),
* NUTAG_REFER_WITH_ID(), @RFC3515.
*
* @END_NUA_EVENT
*/
/** @internal Process incoming REFER. */
......
......@@ -109,6 +109,27 @@ void restart_options(nua_handle_t *nh, tagi_t *tags)
nua_creq_restart(nh, nh->nh_ds->ds_cr, process_response_to_options, tags);
}
/** @NUA_EVENT nua_r_options
*
* Answer to outgoing OPTIONS.
*
* @param status response status code
* (if the request is retried the @a status is 100 and the @a
* sip->sip_status->st_status contain the real status code
* from the response message, e.g., 302, 401, or 407)
* @param phrase a short textual description of @a status code
* @param nh operation handle associated with the incoming OPTIONS request
* @param hmagic application context associated with the handle
* @param sip response to OPTIONS request or NULL upon an error
* (status code is in @a status and
* descriptive message in @a phrase parameters)
* @param tags empty
*
* @sa nua_options(), @RFC3261 section 11, #nua_i_options
*
* @END_NUA_EVENT
*/
static int process_response_to_options(nua_handle_t *nh,
nta_outgoing_t *orq,
sip_t const *sip)
......
......@@ -437,6 +437,26 @@ int nua_stack_init_instance(nua_handle_t *nh, tagi_t const *tags)
* #nua_r_set_params
*/
/** @NUA_EVENT nua_r_set_params
*
* Response to nua_set_params() or nua_set_hparams().
*
* @param status 200 when successful, error code otherwise
* @param phrase a short textual description of @a status code
* @param nh NULL when responding to nua_set_params(),
* operation handle when responding to nua_set_hparams()
* @param hmagic NULL when responding to nua_set_params(),
* application contact associated with the operation handle
* when responding to nua_set_hparams()
* @param sip NULL
* @param tags None
*
* @sa nua_set_params(), nua_set_hparams(),
* #nua_r_get_params, nua_get_params(), nua_get_hparams()
*
* @END_NUA_EVENT
*/
int nua_stack_set_params(nua_t *nua, nua_handle_t *nh, nua_event_t e,
tagi_t const *tags)
{
......@@ -1296,12 +1316,17 @@ int nua_stack_set_smime_params(nua_t *nua, tagi_t const *tags)
* #nua_r_get_params
*/
/** @var nua_event_e::nua_r_get_params
/** @NUA_EVENT nua_r_get_params
*
* Answer to nua_get_params() or nua_get_hparams().
*
* @param nh NULL
* @param hmagic NULL
* @param status 200 when succesful, error code otherwise
* @param phrase a short textual description of @a status code
* @param nh NULL when responding to nua_get_params(),
* operation handle when responding to nua_get_hparams()
* @param hmagic NULL when responding to nua_get_params(),
* application contact associated with the operation handle
* when responding to nua_get_hparams()
* @param sip NULL
* @param tags
* NUTAG_AUTOACK() \n
......@@ -1359,7 +1384,11 @@ int nua_stack_set_smime_params(nua_t *nua, tagi_t const *tags)
* SIPTAG_SUPPORTED_STR() \n
* SIPTAG_USER_AGENT() \n
* SIPTAG_USER_AGENT_STR() \n
*
*
* @sa nua_get_params(), nua_get_hparams(),
* nua_set_params(), nua_set_hparams(), #nua_r_set_params
*
* @END_NUA_EVENT
*/
/**@internal
......
......@@ -133,9 +133,9 @@ static int process_response_to_publish(nua_handle_t *nh,
* event. When successful the publication will be updated periodically until
* nua_unpublish() is called or handle is destroyed. Note that the periodic
* updates and unpublish do not include the original message body nor the @b
* Content-Type header. Instead, the periodic update will include the @b
* SIP-If-Match header, which was generated from the latest @b SIP-ETag
* header received in response to PUBLISH request.
* Content-Type header. Instead, the periodic update will include the
* @SIPIfMatch header, which was generated from the latest @SIPETag
* header received in response to @b PUBLISH request.
*
* The handle used for publication cannot be used for any other purposes.
*
......@@ -152,30 +152,48 @@ static int process_response_to_publish(nua_handle_t *nh,
*
* @par Events:
* #nua_r_publish
*
* @sa #nua_r_publish, @RFC3903, @SIPIfMatch,
* nua_unpublish(), #nua_r_unpublish, #nua_i_publish
*/
/** @var nua_event_e::nua_r_publish
/** @NUA_EVENT nua_r_publish
*
* Response to an outgoing PUBLISH.
*
* The PUBLISH may be sent explicitly by nua_publish() or
* implicitly by NUA state machine.
* The PUBLISH request may be sent explicitly by nua_publish() or implicitly
* by NUA state machine.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param status status code of PUBLISH request
* (if the request is retried, @a status is 100, the @a
* sip->sip_status->st_status contain the real status code
* from the response message, e.g., 302, 401, or 407)
* @param phrase a short textual description of @a status code
* @param nh operation handle associated with the publication
* @param hmagic application context associated with the handle
* @param sip response to PUBLISH request or NULL upon an error
* (error code and message are in status an phrase parameters)
* (status code is in @a status and
* descriptive message in @a phrase parameters)
* @param tags empty
*
* @sa nua_publish(), @RFC3903, @SIPETag, @Expires,
* nua_unpublish(), #nua_r_unpublish, #nua_i_publish
*
* @END_NUA_EVENT
*/
/**@fn \
void nua_unpublish(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);
*
* Send un-PUBLISH request to publication server.
* Send un-PUBLISH request to publication server. Un-PUBLISH request is just
* a PUBLISH request with @Expires set to 0. It is possible to un-publish a
* publication not associated with the handle by providing correct ETag in
* SIPTAG_IF_MATCH() or SIPTAG_IF_MATCH_STR() tags.
*
* Request status will be delivered to the application using
* #nua_r_unpublish event. The handle used for un-publication
* cannot be used for any other purposes.
* Response to the un-PUBLISH request will be delivered to the application
* using #nua_r_unpublish event.
*
* The handle used for publication cannot be used for any other purposes.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
......@@ -185,25 +203,38 @@ void nua_unpublish(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);
*
* @par Related Tags:
* NUTAG_URL() \n
* 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>
*
* @par Events:
* #nua_r_publish
* #nua_r_unpublish
*
* @sa #nua_r_unpublish, @RFC3903, @SIPIfMatch,
* #nua_i_publish, nua_publish(), #nua_r_publish
*/
/** @var nua_event_e::nua_r_unpublish
/** @NUA_EVENT nua_r_unpublish
*
* Response to an outgoing un-PUBLISH.
*
* The PUBLISH may be sent explicitly by nua_publish() or
* implicitly by NUA state machine.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param status response status code
* (if the request is retried, @a status is 100, the @a
* sip->sip_status->st_status contain the real status code
* from the response message, e.g., 302, 401, or 407)
* @param phrase a short textual description of @a status code
* @param nh operation handle associated with the publication
* @param hmagic application context associated with the handle
* @param sip response to PUBLISH request or NULL upon an error
* (error code and message are in status an phrase parameters)
* (status code is in @a status and
* descriptive message in @a phrase parameters)
* @param tags empty
*
* @sa nua_unpublish(), @RFC3903, @SIPETag, @Expires,
* nua_publish(), #nua_r_publish, #nua_i_publish
*
* @END_NUA_EVENT
*/
int nua_stack_publish(nua_t *nua, nua_handle_t *nh, nua_event_t e,
......@@ -413,7 +444,7 @@ static int nua_publish_usage_shutdown(nua_handle_t *nh,
static
int respond_to_publish(nua_server_request_t *sr, tagi_t const *tags);
/** @var nua_event_e::nua_i_publish
/** @NUA_EVENT nua_i_publish
*
* Incoming PUBLISH request.
*
......@@ -432,10 +463,11 @@ int respond_to_publish(nua_server_request_t *sr, tagi_t const *tags);
* bound, you should probably destroy it after responding to the PUBLISH
* request.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* (NULL if outside session)
* @param status statuscode of response sent automatically by stack
* @param status status code of response sent automatically by stack
* @param phrase a short textual description of @a status code
* @param nh operation handle associated with the incoming request
* @param hmagic application context associated with the call
* (usually NULL)
* @param sip incoming PUBLISH request
* @param tags empty
*
......@@ -445,6 +477,8 @@ int respond_to_publish(nua_server_request_t *sr, tagi_t const *tags);
* nua_notifier(), #nua_i_subscription,
*
* @since First used in @VERSION_1_12_4
*
* @END_NUA_EVENT
*/
int nua_stack_process_publish(nua_t *nua,
......
......@@ -282,7 +282,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_PARAMS(), NUTAG_M_FEATURES()
* NUTAG_M_DISPLAY(), NUTAG_M_PARAMS(), NUTAG_M_FEATURES(),
*
* @par Events:
* #nua_r_register, #nua_i_outbound
......@@ -440,25 +440,44 @@ outbound_owner_vtable nua_stack_outbound_callbacks = {
* the desired transport-layer keepalive interval for stream-based
* transports like TLS and TCP.
*
* @sa NUTAG_OUTBOUND() and tags.
* @sa #nua_r_register, nua_unregister(), #nua_r_unregister,
* #nua_i_register,
* @RFC3261 section 10,
* @Expires, @Contact, @CallID, @CSeq,
* @Path, @RFC3327, @ServiceRoute, @RFC3608, @RFC3680,
* NUTAG_REGISTRAR(), NUTAG_INSTANCE(), NUTAG_OUTBOUND(),
* NUTAG_KEEPALIVE(), NUTAG_KEEPALIVE_STREAM(),
* SIPTAG_CONTACT(), SIPTAG_CONTACT_STR(), NUTAG_M_USERNAME(),
* NUTAG_M_DISPLAY(), NUTAG_M_PARAMS(), NUTAG_M_FEATURES(),
*/
/** @var nua_event_e::nua_r_register
/** @NUA_EVENT nua_r_register
*
* Response to an 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.
* NUA state machines.
*
* When REGISTER request has been restarted the @a status may be 100 even
* while the real response status returned is different.
*
* @param status response status code
* (if the request is retried, @a status is 100, the @a
* sip->sip_status->st_status contain the real status code
* from the response message, e.g., 302, 401, or 407)
* @param phrase a short textual description of @a status code
* @param nh operation handle associated with the registration
* @param hmagic operation magic associated with the registration
* @param status status code
* (from the response message or internally generated)
* @param phrase response phrase
* @param hmagic application context associated with the registration
* @param sip response message to REGISTER request or NULL upon an error
* (error code and message are in status and phrase parameters)
* (status code is in @a status and
* descriptive message in @a phrase parameters)
* @param tags empty
*
* @sa nua_register(), nua_unregister(), #nua_r_unregister,
* @Contact, @CallID, @CSeq, @RFC3261 section 10,
* @Path, @RFC3327, @ServiceRoute, @RFC3608, @RFC3680
*
* @END_NUA_EVENT
*/
/**@fn void nua_unregister(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);
......@@ -484,20 +503,38 @@ outbound_owner_vtable nua_stack_outbound_callbacks = {
*
* @par Events:
* #nua_r_unregister
*
* @sa nua_register(), #nua_r_register, nua_handle_destroy(), nua_shutdown(),
* #nua_i_register,
* @Expires, @Contact, @CallID, @CSeq, @RFC3261 section 10,
* @Path, @RFC3327, @ServiceRoute, @RFC3608, @RFC3680,
* NUTAG_REGISTRAR(), NUTAG_INSTANCE(), NUTAG_OUTBOUND(),
* NUTAG_KEEPALIVE(), NUTAG_KEEPALIVE_STREAM(),
* SIPTAG_CONTACT(), SIPTAG_CONTACT_STR(), NUTAG_M_USERNAME(),
* NUTAG_M_DISPLAY(), NUTAG_M_PARAMS(), NUTAG_M_FEATURES(),
*/
/** @var nua_event_e::nua_r_unregister
/** @NUA_EVENT nua_r_unregister
*
* Answer to outgoing un-REGISTER.
*
* @param status response status code
* (if the request is retried, @a status is 100, the @a
* sip->sip_status->st_status contain the real status code
* from the response message, e.g., 302, 401, or 407)
* @param phrase a short textual description of @a status code
* @param nh operation handle associated with the registration
* @param hmagic operation magic associated with the registration
* @param status status code
* (from the response message or internally generated)
* @param phrase response phrase
* @param hmagic application context associated with the registration
* @param sip response message to REGISTER request or NULL upon an error
* (error code and message are in status and phrase parameters)
* (status code is in @a status and
* descriptive message in @a phrase parameters)
* @param tags empty
*
* @sa nua_unregister(), nua_register(), #nua_r_register,
* @Contact, @CallID, @CSeq, @RFC3261 section 10,
* @Path, @RFC3327, @ServiceRoute, @RFC3608, @RFC3680
*
* @END_NUA_EVENT
*/
int
......@@ -1684,22 +1721,26 @@ static int nua_stack_outbound_refresh(nua_handle_t *nh,
return 0;
}
/** @var nua_event_e::nua_i_outbound
/** @NUA_EVENT nua_i_outbound
*
* Status from outbound engine.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param status SIP status code or NUA status code (>= 900)
* describing the outbound state
* @param phrase a short textual description of @a status code
* @param nh operation handle associated with the outbound engine
* @param hmagic application context associated with the handle
* @param sip NULL or response message to an keepalive message or
* registration probe
* (error code and message are in status an phrase parameters)
* @param tags empty
*
* @sa nua_register(), #nua_r_register, nua_unregister(), #nua_r_unregister,
* @RFC3261 section 10
* @sa NUTAG_OUTBOUND(), NUTAG_KEEPALIVE(), NUTAG_KEEPALIVE_STREAM(),
* nua_register(), #nua_r_register, nua_unregister(), #nua_r_unregister
*
* @END_NUA_EVENT
*/
/** @internal Callback from outbound_t */
static int nua_stack_outbound_status(nua_handle_t *nh, outbound_t *ob,
int status, char const *phrase,
......
......@@ -54,7 +54,7 @@
/* ======================================================================== */
/* REGISTER */
/** @var nua_event_e::nua_i_register
/** @NUA_EVENT nua_i_register
*
* Incoming REGISTER request.
*
......@@ -72,19 +72,21 @@
* bound, you should probably destroy it after responding to the REGISTER
* request.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* (NULL if outside session)
* @param status status code of response sent automatically by stack
* @param phrase a short textual description of @a status code
* @param nh operation handle associated with the request
* @param hmagic application context associated with the handle
* (usually NULL)
* @param sip incoming REGISTER request
* @param tags empty
*
* @sa nua_respond(), @RFC3261 section 10.3,
* @sa nua_respond(), @RFC3261 section 10.3,
* @Expires, @Contact, @CallID, @CSeq,
* @Path, @RFC3327, @ServiceRoute, @RFC3608, @RFC3680,
* nua_register(), #nua_i_register, nua_unregister(), #nua_i_unregister
*
* @since New in @VERSION_1_12_4
* @END_NUA_EVENT
*/
int nua_stack_process_register(nua_t *nua,
......
This diff is collapsed.
......@@ -514,6 +514,50 @@ int nh_call_pending(nua_handle_t *nh, sip_time_t now)
/* ====================================================================== */
/**Shutdown a @nua stack.
*
* When the @nua stack is shutdown, ongoing calls are released,
* registrations unregistered, publications un-PUBLISHed and subscriptions
* terminated. If the stack cannot terminate everything within 30 seconds,
* it sends the #nua_r_shutdown event with status 500.
*
* @param nua Pointer to @nua stack object
*
* @return
* nothing
*
* @par Related tags:
* none
*
* @par Events:
* #nua_r_shutdown
*
* @sa #nua_r_shutdown, nua_destroy(), nua_create(), nua_bye(),
* nua_unregister(), nua_unpublish(), nua_unsubscribe(), nua_notify(),
* nua_handle_destroy(), nua_handle_unref()
*/
/** @NUA_EVENT nua_r_shutdown
*
* Answer to nua_shutdown().
*
* Status codes
* - 100 shutdown started
* - 101 shutdown in progress (sent when shutdown has been progressed)
* - 200 shutdown was successful
* - 500 shutdown timeout after 30 sec
*
* @param status shutdown status code
* @param nh NULL
* @param hmagic NULL
* @param sip NULL
* @param tags empty
*
* @sa nua_shutdown(), nua_destroy()
*
* @END_NUA_EVENT
*/
/** @internal Shut down stack. */
void nua_stack_shutdown(nua_t *nua)
{
......@@ -1599,6 +1643,35 @@ int nua_creq_restart(nua_handle_t *nh,
/* ======================================================================== */
/* Authentication */
/** @NUA_EVENT nua_r_authenticate
*
* Response to nua_authenticate(). Under normal operation, this event is
* never sent but rather the unauthenticated operation is completed.
* However, if there is no operation to authentication or if there is an
* authentication error the #nua_r_authenticate event is sent to the
* application with the status code as follows:
* - <i>202 No operation to restart</i>:\n
* The authenticator associated with the handle was updated, but there was
* no operation to retry with the new credentials.
* - <i>900 Cannot add credentials</i>:\n
* There was internal problem updating authenticator.
* - <i>904 No matching challenge</i>:\n
* There was no challenge matching with the credentials provided by
* nua_authenticate(), e.g., their realm did not match with the one
* received with the challenge.
*
* @param status status code from authentication
* @param phrase a short textual description of @a status code
* @param nh operation handle authenticated
* @param hmagic application context associated with the handle
* @param sip NULL
* @param tags empty
*
* @sa nua_terminate(), nua_handle_destroy()
*
* @END_NUA_EVENT
*/
void
nua_stack_authenticate(nua_t *nua, nua_handle_t *nh, nua_event_t e,
tagi_t const *tags)
......
......@@ -297,33 +297,49 @@ static void restart_subscribe(nua_handle_t *nh, tagi_t *tags)
nua_creq_restart(nh, nh->nh_ds->ds_cr, process_response_to_subscribe, tags);
}
/** @var nua_event_e::nua_r_subscribe
/** @NUA_EVENT nua_r_subscribe
*
* Response to an outgoing SUBSCRIBE.
* Response to an outgoing SUBSCRIBE request.
*