Commit 542887da authored by Pekka Pessi's avatar Pekka Pessi

nua: moved documentation towards implementation.

Moved documentation of nua_options(), nua_i_options, nua_i_refer,
nua_message(), nua_i_message, nua_r_message.

Added documentation of nua_i_register, nua_i_outbound.

darcs-hash:20061027132439-65a35-c14ef4d7e99bd5f442da19d3770bd08fb4adf849.gz
parent 895516df
......@@ -414,8 +414,8 @@ int nua_handle_has_events(nua_handle_t const *nh)
/** Check if operation handle has active registrations
*
* A registrtion is active when either when a REGISTER operation going on
* when it has successfully completed so that @nua stack is expected to
* A registration is active when either when a REGISTER operation is going
* on or when it has successfully completed so that @nua stack is expected to
* refresh the registration in the future. Normally, a handle has active
* registration after nua_register() until nua_unregister() completes,
* unless the initial nua_register() had either expiration time of 0 or it
......@@ -647,44 +647,13 @@ void nua_cancel(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
NUA_SIGNAL(nh, nua_r_cancel, tag, value);
}
/** Query capabilities from server
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related Tags:
* Tags in <sip_tag.h>
*
* @par Events:
* #nua_r_options
*
*/
/* Documented with nua_stack_options() */
void nua_options(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
NUA_SIGNAL(nh, nua_r_options, tag, value);
}
/** Send an instant message.
*
* Send an instant message using SIP MESSAGE method.
*
* @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_message
*/
/* Documented with nua_stack_message() */
void nua_message(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
NUA_SIGNAL(nh, nua_r_message, tag, value);
......
......@@ -2061,17 +2061,7 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* @param tags empty
*/
/** @var nua_event_e::nua_i_message
*
* Incoming MESSAGE.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* (maybe NULL if outside session)
* @param status statuscode of response sent automatically by stack
* @param sip incoming MESSAGE request
* @param tags empty
*/
/* nua_r_message is documented with nua_stack_process_message() */
/** @var nua_event_e::nua_i_method
*
......@@ -2101,36 +2091,11 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
/* nua_i_notify is documented with nua_stack_process_notify() */
/** @var nua_event_e::nua_i_options
*
* Incoming options.
*
* @param nh operation handle associated with the call
* (default operation handle if outside session)
* @param hmagic operation magic associated with the call
* (NULL if outside session)
* @param status statuscode of response sent automatically by stack
* @param sip incoming OPTIONS request
* @param tags empty
*/
/* nua_i_options is documented with nua_stack_process_options() */
/* nua_i_publish documented with nua_stack_process_publish() */
/* nua_i_publish is documented with nua_stack_process_publish() */
/** @var nua_event_e::nua_i_refer
*
* Incoming call transfer 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 sip incoming REFER request
* @param tags NUTAG_REFER_EVENT() \n
* SIPTAG_REFERRED_BY()
*
* @sa nua_refer(), #nua_r_refer, NUTAG_NOTIFY_REFER(),
* NUTAG_REFER_WITH_ID().
*/
/* nua_i_refer is documented with nua_stack_process_refer() */
/* nua_i_subscribe is documented with nua_stack_process_subscribe() */
......@@ -2165,16 +2130,7 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* @param tags empty
*/
/** @var nua_event_e::nua_r_message
*
* Answer to outgoing MESSAGE
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip response to MESSAGE request or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags empty
*/
/* nua_r_message is documented with process_response_to_message() */
/** @var nua_event_e::nua_r_notifier
*
......
......@@ -51,6 +51,27 @@
/* ======================================================================== */
/* MESSAGE */
/** Send an instant message.
*
* Send an instant message using SIP MESSAGE method.
*
* @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_message
*
* @sa nua_i_message, @RFC3428
*/
static int process_response_to_message(nua_handle_t *nh,
nta_outgoing_t *orq,
sip_t const *sip);
......@@ -95,6 +116,19 @@ 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
*
* Response to an outgoing MESSAGE.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip response to MESSAGE request or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags empty
*
* @sa nua_message(), #nua_i_message, @RFC3428
*/
static int process_response_to_message(nua_handle_t *nh,
nta_outgoing_t *orq,
sip_t const *sip)
......@@ -104,6 +138,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
*
* Incoming MESSAGE.
*
* 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.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* (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
*/
int nua_stack_process_message(nua_t *nua,
nua_handle_t *nh,
nta_incoming_t *irq,
......
......@@ -591,6 +591,22 @@ static int nua_notify_usage_shutdown(nua_handle_t *nh,
/* REFER */
/* RFC 3515 */
/** @var nua_event_e::nua_i_refer
*
* Incoming call transfer 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 sip incoming REFER request
* @param tags NUTAG_REFER_EVENT() \n
* SIPTAG_REFERRED_BY()
*
* @sa nua_refer(), #nua_r_refer, NUTAG_NOTIFY_REFER(),
* NUTAG_REFER_WITH_ID(), @RFC3515.
*/
/** @internal Process incoming REFER. */
int nua_stack_process_refer(nua_t *nua,
nua_handle_t *nh,
......
......@@ -48,8 +48,24 @@
#include "nua_stack.h"
/* ======================================================================== */
/* OPTIONS */
/**@fn void nua_options(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);
*
* Query capabilities from server with OPTIONS request.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related Tags:
* Tags in <sip_tag.h>
*
* @par Events:
* #nua_r_options
*
* @sa #nua_i_options, @RFC3261 section 10
*/
static int process_response_to_options(nua_handle_t *nh,
nta_outgoing_t *orq,
......
......@@ -156,7 +156,7 @@ static int process_response_to_publish(nua_handle_t *nh,
/** @var nua_event_e::nua_r_publish
*
* Answer to outgoing PUBLISH.
* Response to an outgoing PUBLISH.
*
* The PUBLISH may be sent explicitly by nua_publish() or
* implicitly by NUA state machine.
......@@ -194,7 +194,7 @@ void nua_unpublish(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);
/** @var nua_event_e::nua_r_unpublish
*
* Answer to outgoing un-PUBLISH.
* Response to an outgoing un-PUBLISH.
*
* The PUBLISH may be sent explicitly by nua_publish() or
* implicitly by NUA state machine.
......@@ -426,6 +426,12 @@ int respond_to_publish(nua_server_request_t *sr, tagi_t const *tags);
* a successful response to PUBLISH @b MUST include @Expires and @SIPETag
* headers.
*
* The PUBLISH request does not create a dialog. Currently the processing
* of incoming PUBLISH 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 PUBLISH
* request.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* (NULL if outside session)
......@@ -437,6 +443,8 @@ int respond_to_publish(nua_server_request_t *sr, tagi_t const *tags);
* @Expires, @SIPETag, @SIPIfMatch, @Event,
* nua_subscribe(), #nua_i_subscribe,
* nua_notifier(), #nua_i_subscription,
*
* @since First used in @VERSION_1_12_4
*/
int nua_stack_process_publish(nua_t *nua,
......
......@@ -445,31 +445,19 @@ outbound_owner_vtable nua_stack_outbound_callbacks = {
/** @var nua_event_e::nua_r_register
*
* Answer to outgoing 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.
*
* @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 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 sip response message to REGISTER request or NULL upon an error
* (error code and message are in status and phrase parameters)
* @param tags empty
*/
......@@ -502,9 +490,12 @@ outbound_owner_vtable nua_stack_outbound_callbacks = {
*
* 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
* @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 sip response message to REGISTER request or NULL upon an error
* (error code and message are in status and phrase parameters)
* @param tags empty
*/
......@@ -1693,6 +1684,21 @@ static int nua_stack_outbound_refresh(nua_handle_t *nh,
return 0;
}
/** @var nua_event_e::nua_i_outbound
*
* Status from outbound engine.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @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
*/
/** @internal Callback from outbound_t */
static int nua_stack_outbound_status(nua_handle_t *nh, outbound_t *ob,
......
......@@ -54,6 +54,39 @@
/* ======================================================================== */
/* REGISTER */
/** @var nua_event_e::nua_i_register
*
* Incoming REGISTER request.
*
* In order to receive #nua_i_register events, the application must enable
* the REGISTER method with NUTAG_ALLOW() tag.
*
* The nua_response() call responding to a REGISTER request must have
* NUTAG_WITH() (or NUTAG_WITH_CURRENT()/NUTAG_WITH_SAVED()) tag. Note that
* a successful response to REGISTER @b MUST include the @Contact header
* bound to the the AoR URI (in @To header).
*
* The REGISTER request does not create a dialog. Currently the processing
* of incoming REGISTER 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 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 sip incoming REGISTER request
* @param tags empty
*
* @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
*/
int nua_stack_process_register(nua_t *nua,
nua_handle_t *nh,
nta_incoming_t *irq,
......
......@@ -748,11 +748,15 @@ int nua_stack_process_notify(nua_t *nua,
* 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.
* NUTAG_REFER_EVENT() containing a matching event header with id parameter.
*
* 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
* parameter. The @a id parameter contains the @CSeq number of the REFER
* request, and it get incremented if the request is retried because it gets
* challenged or redirected. In that case, the application gets a new
* @nua_r_refer event with status 100 and tag NUTAG_REFER_EVENT(). Also the
* recipient of the REFER request may or may not use the @a id parameter in
* the NOTIFY requests messages which 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.
*
......@@ -771,7 +775,7 @@ int nua_stack_process_notify(nua_t *nua,
* #nua_r_refer \n
* #nua_i_notify
*
* @sa NUTAG_SUBSTATE(), @RFC3515,
* @sa NUTAG_SUBSTATE(), @RFC3515, @ReferTo, @RFC3892, @ReferredBy
*/
static int process_response_to_refer(nua_handle_t *nh,
......
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