Commit 2b1f9a67 authored by Pekka Pessi's avatar Pekka Pessi

nua: moved documentation from nua.c/nua.docs towards the implementation.

darcs-hash:20061003100047-65a35-d7181675520c4255c08df388ed9b53ca42c6c609.gz
parent b384a05e
......@@ -596,67 +596,19 @@ void nua_invite(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
NUA_SIGNAL(nh, nua_r_invite, tag, value);
}
/** Acknowledge a succesfull response to INVITE request.
*
* Acknowledge a successful response to INVITE request
* with SIP ACK message. This function is need only if
* NUTAG_AUTOACK() parameter has been cleared.
*
* @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_i_media_error \n
* #nua_i_active
*/
/* Documented with nua_stack_ack() */
void nua_ack(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
NUA_SIGNAL(nh, nua_r_ack, tag, value);
}
/** Hangdown a call.
*
* Hangdown a call using SIP BYE method. Also the media session
* associated with the call is terminated.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related Tags:
* none
*
* @par Events:
* #nua_r_bye \n
* #nua_i_media_error
*/
/* Documented with nua_stack_bye() */
void nua_bye(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
NUA_SIGNAL(nh, nua_r_bye, tag, value);
}
/** Cancel an INVITE operation
*
* @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_cancel
*/
/* Documented with nua_stack_cancel() */
void nua_cancel(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
NUA_SIGNAL(nh, nua_r_cancel, tag, value);
......@@ -904,74 +856,19 @@ void nua_unpublish(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
NUA_SIGNAL(nh, nua_r_unpublish, tag, value);
}
/** Send an INFO request.
*
* INFO is used to send call related information like DTMF
* digit input events. See @RFC2976.
*
* @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_info
*/
/* Documented with nua_stack_info() */
void nua_info(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
NUA_SIGNAL(nh, nua_r_info, tag, value);
}
/** Send a PRACK request.
*
* PRACK is used to acknowledge receipt of 100rel responses. See @RFC3262.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related Tags:
* Tags in <sofia-sip/soa_tag.h>, <sofia-sip/sip_tag.h>.
*
* @par Events:
* #nua_r_prack
*/
/* Documented with nua_stack_prack() */
void nua_prack(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
NUA_SIGNAL(nh, nua_r_prack, tag, value);
}
/** Update a session.
*
* Update a session using SIP UPDATE method. See @RFC3311.
*
* Update method can be used when the session has been established with
* INVITE. It's mainly used during the session establishment when
* preconditions are used (@RFC3312). It can be also used during the call if
* no user input is needed for offer/answer negotiation.
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related Tags:
* same as nua_invite()
*
* @par Events:
* #nua_r_update \n
* #nua_i_state \n
* #nua_i_media_error \n
*/
/* Documented with nua_stack_update() */
void nua_update(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
NUA_SIGNAL(nh, nua_r_update, tag, value);
......
......@@ -2010,48 +2010,6 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* #nua_r_update
*/
/** @var nua_event_e::nua_i_active
*
* A call has been activated.
*
* This event will be sent after a succesful response to the initial
* INVITE has been received and the media has been activated.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip NULL
* @param tags SOATAG_ACTIVE_AUDIO(), SOATAG_ACTIVE_VIDEO(),
* SOATAG_ACTIVE_IMAGE(), SOATAG_ACTIVE_CHAT().
*
* @deprecated Use #nua_i_state instead.
*
* @sa @ref nua_call_model, #nua_i_state, #nua_i_terminated,
* #nua_i_invite
*/
/** @var nua_event_e::nua_i_bye
*
* Incoming call hangup.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip pointer to BYE request
* @param tags empty
*/
/** @var nua_event_e::nua_i_cancel
*
* Incoming INVITE has been cancelled
*
* Incoming INVITE has been cancelled or
* no ACK has been received for an accepted call.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip incoming CANCEL request or NULL if time-out occured
* @param tags empty
*/
/** @var nua_event_e::nua_i_chat
*
* Incoming chat MESSAGE
......@@ -2087,28 +2045,6 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* @param tags #NUTAG_HANDLE of the new forked call
*/
/** @var nua_event_e::nua_i_info
*
* Incoming session INFO
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip incoming INFO request
* @param tags empty
*/
/** @var nua_event_e::nua_i_invite
*
* Incoming call
*
* @param nh operation handle associated with this call
* (maybe created for this call)
* @param hmagic operation magic associated with this call
* (maybe NULL if call handle was created for this call)
* @param sip incoming INVITE request
* @param tags NUTAG_ACTIVE_*
*/
/** @var nua_event_e::nua_i_media_error
*
* Media error indication.
......@@ -2208,43 +2144,6 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* NUTAG_REFER_WITH_ID().
*/
/** @var nua_event_e::nua_i_state
*
* 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.
*
* Note that nua_event_e::nua_i_state also covers call establisment events
* (#nua_i_active) and termination (#nua_i_terminated).
*
* @param status Protocol status code. \n
* Always present
* @param phrase Text corresponding to status code. \n
* Always present
* @param nh Operation handle associated with the call
* @param hmagic Operation magic associated with the call
* @param sip NULL
* @param tags NUTAG_CALLSTATE(),
* SOATAG_LOCAL_SDP(), SOATAG_LOCAL_SDP_STR(),
* NUTAG_OFFER_SENT(), NUTAG_ANSWER_SENT(),
* SOATAG_REMOTE_SDP(), SOATAG_REMOTE_SDP_STR(),
* NUTAG_OFFER_RECV(), NUTAG_ANSWER_RECV(),
* SOATAG_ACTIVE_AUDIO(), SOATAG_ACTIVE_VIDEO(),
* SOATAG_ACTIVE_IMAGE(), SOATAG_ACTIVE_CHAT().
*
* @sa @ref nua_call_model, nua_invite(), #nua_i_active, #nua_i_terminated,
* #nua_r_invite
*/
/** @var nua_event_e::nua_i_subscribe
*
* Incoming subscription request.
......@@ -2278,54 +2177,6 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* @sa nua_notifier(), #nua_i_subscribe, nua_authorize(), nua_terminate()
*/
/** @var nua_event_e::nua_i_terminated
*
* A call has been terminated.
*
* This event will be sent after a call has been terminated. A call is
* terminated, when
* 1) an error response (300..599) is sent to an incoming initial INVITE
* 2) a reliable response (200..299 or reliable preliminary response) to
* an incoming initial INVITE is not acknowledged with ACK or PRACK
* 3) BYE is received or sent
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip NULL
* @param tags empty
*
* @deprecated Use #nua_i_state instead.
*
* @sa @ref nua_call_model, #nua_i_state, #nua_i_active, #nua_i_bye,
* #nua_i_invite
*/
/** @var nua_event_e::nua_i_update
*
* Incoming session UPDATE request.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip incoming UPDATE request
* @param tags empty
*
* @sa nua_update(), #nua_r_update, #nua_i_state
*/
/** @var nua_event_e::nua_r_bye
*
* Answer to outgoing BYE.
*
* The BYE may be sent explicitly by nua_bye() 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 BYE request or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags empty
*/
/** @var nua_event_e::nua_r_chat
*
* Answer to outgoing chat MESSAGE.
......@@ -2337,43 +2188,6 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* @param tags empty
*/
/** @var nua_event_e::nua_r_get_params
*
* Answer to nua_get_params().
*
* @param nh NULL
* @param hmagic NULL
* @param sip NULL
* @param tags NUTAG_* \n
* SIPTAG_* \n
* NTATAG_*
*/
/** @var nua_event_e::nua_r_info
*
* Answer to outgoing INFO.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
* @param sip response to INFO or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags empty
*/
/** @var nua_event_e::nua_r_invite
*
* Answer to outgoing INVITE.
*
* The INVITE may be sent explicitly by nua_invite() 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 INFO or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags empty
*/
/** @var nua_event_e::nua_r_message
*
* Answer to outgoing MESSAGE
......@@ -2483,17 +2297,3 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* (error code and message are in status an phrase parameters)
* @param tags empty
*/
/** @var nua_event_e::nua_r_update
*
* Answer to outgoing UPDATE.
*
* The UPDATE may be sent explicitly by nua_update() 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 UPDATE request or NULL upon an error
* (error code and message are in status an phrase parameters)
* @param tags empty
*/
......@@ -1275,6 +1275,72 @@ 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
*
* Answer to nua_get_params() or nua_get_hparams().
*
* @param nh NULL
* @param hmagic NULL
* @param sip NULL
* @param tags
* NUTAG_ALLOW() \n
* NUTAG_AUTOACK() \n
* NUTAG_AUTOALERT() \n
* NUTAG_AUTOANSWER() \n
* NUTAG_CALLEE_CAPS() \n
* NUTAG_DETECT_NETWORK_UPDATES() \n
* NUTAG_EARLY_ANSWER() \n
* NUTAG_EARLY_MEDIA() \n
* NUTAG_ENABLEINVITE() \n
* NUTAG_ENABLEMESSAGE() \n
* NUTAG_ENABLEMESSENGER() \n
* NUTAG_INSTANCE() \n
* NUTAG_INVITE_TIMER() \n
* NUTAG_KEEPALIVE() \n
* NUTAG_KEEPALIVE_STREAM() \n
* NUTAG_MAX_SUBSCRIPTIONS() \n
* NUTAG_MEDIA_ENABLE() \n
* NUTAG_MEDIA_FEATURES() \n
* NUTAG_MIN_SE() \n
* NUTAG_M_DISPLAY() \n
* NUTAG_M_FEATURES() \n
* NUTAG_M_PARAMS() \n
* NUTAG_M_USERNAME() \n
* NUTAG_ONLY183_100REL() \n
* NUTAG_OUTBOUND() \n
* NUTAG_PATH_ENABLE() \n
* NUTAG_REFER_EXPIRES() \n
* NUTAG_REFER_WITH_ID() \n
* NUTAG_REGISTRAR() \n
* NUTAG_RETRY_COUNT() \n
* NUTAG_SERVICE_ROUTE_ENABLE() \n
* NUTAG_SESSION_REFRESHER() \n
* NUTAG_SESSION_TIMER() \n
* NUTAG_SMIME_ENABLE() \n
* NUTAG_SMIME_KEY_ENCRYPTION() \n
* NUTAG_SMIME_MESSAGE_DIGEST() \n
* NUTAG_SMIME_MESSAGE_ENCRYPTION() \n
* NUTAG_SMIME_OPT() \n
* NUTAG_SMIME_PROTECTION_MODE() \n
* NUTAG_SMIME_SIGNATURE() \n
* NUTAG_SOA_NAME() \n
* NUTAG_SUBSTATE() \n
* NUTAG_SUPPORTED() \n
* NUTAG_UPDATE_REFRESH() \n
* NUTAG_USER_AGENT() \n
* SIPTAG_ALLOW() \n
* SIPTAG_ALLOW_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
*
*/
/**@internal
* Send a list of NUA parameters to the application.
*
......
This diff is collapsed.
......@@ -87,7 +87,7 @@ typedef enum nua_event_e {
nua_i_invite, /**< Incoming call */
nua_i_cancel, /**< Incoming INVITE has been cancelled */
nua_i_ack, /**< Response to INVITE has been ACKed */
nua_i_ack, /**< Final response to INVITE has been ACKed */
nua_i_fork, /**< Outgoing call has been forked */
nua_i_active, /**< A call has been activated */
nua_i_terminated, /**< A call has been terminated */
......
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