Commit 5c1f5e87 authored by Pekka Pessi's avatar Pekka Pessi

nua.c, nua.docs, nua_session.c: updated documentation. Added links.

darcs-hash:20060925184146-65a35-cb47623184a1c91b082c918522a6601394f4c069.gz
parent 3854c9b7
......@@ -63,10 +63,10 @@
/* From AM_INIT/AC_INIT in our "config.h" */
char const nua_version[] = VERSION;
/**Environment variable determining the debug log level for @b nua module.
/**Environment variable determining the debug log level for @nua module.
*
* The NUA_DEBUG environment variable is used to determine the debug logging
* level for @b nua module. The default level is 3.
* level for @nua module. The default level is 3.
*
* @sa <sofia-sip/su_debug.h>, nua_log, SOFIA_DEBUG
*/
......@@ -76,16 +76,16 @@ extern char const NUA_DEBUG[];
#define SU_DEBUG 3
#endif
/**Debug log for @b nua module.
/**Debug log for @nua module.
*
* The nua_log is the log object used by @b nua module. The level of
* The nua_log is the log object used by @nua module. The level of
* #nua_log is set using #NUA_DEBUG environment variable.
*/
su_log_t nua_log[] = { SU_LOG_INIT("nua", "NUA_DEBUG", SU_DEBUG) };
/**Create a NUA agent.
/**Create a @nua agent.
*
* This function creates a Sofia-SIP User Agent stack object (nua) and
* This function creates a Sofia-SIP User Agent stack object (@nua) and
* initializes its parameters by given tagged values.
*
* @param root Pointer to a root object
......@@ -93,22 +93,26 @@ su_log_t nua_log[] = { SU_LOG_INIT("nua", "NUA_DEBUG", SU_DEBUG) };
* @param magic Pointer to callback context
* @param tag,value,... List of tagged parameters
*
* @retval !=NULL a pointer to a NUA stack object \n
* @retval !=NULL a pointer to a @nua stack object \n
* @retval NULL upon an error
*
* @par Related tags:
* NUTAG_MEDIA_ENABLE() \n
* NUTAG_SOA_NAME() \n
* NUTAG_PROXY() \n
* NUTAG_URL() \n
* NUTAG_SIPS_URL() \n
* NUTAG_SIP_PARSER() \n
* NUTAG_UICC() \n
* NUTAG_CERTIFICATE_DIR() \n
* all relevant NTATAG_* are passed to NTA
* and all tags listed in nua_set_params(), \n
* and all relevant NTATAG_* are passed to NTA.
*
* @note
* Both the NUTAG_URL and NUTAG_SIPS_URL() are used to pass arguments to
* From the @VERSION_1_12_2 all the nua_set_params() tags are processed.
* Previously all nutags except NUTAG_SOA_NAME() and NUTAG_MEDIA_ENABLE()
* were ignored.
*
* @note
* Both the NUTAG_URL() and NUTAG_SIPS_URL() are used to pass arguments to
* nta_agent_add_tport().
*
* @par Events:
......@@ -168,13 +172,13 @@ nua_t *nua_create(su_root_t *root,
return nua;
}
/**Shutdown a NUA stack.
/**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
* @param nua Pointer to @nua stack object
*
* @return
* nothing
......@@ -194,14 +198,14 @@ void nua_shutdown(nua_t *nua)
nua_signal(nua, NULL, NULL, 1, nua_r_shutdown, 0, NULL, TAG_END());
}
/** Destroy the NUA stack.
/** Destroy the @nua stack.
*
* Before calling nua_destroy() the application
* should call nua_shutdown and wait for successful #nua_r_shutdown event.
* Shuts down and destroys the NUA stack. Ongoing calls, registrations,
* Shuts down and destroys the @nua stack. Ongoing calls, registrations,
* and subscriptions are left as they are.
*
* @param nua Pointer to NUA stack object
* @param nua Pointer to @nua stack object
*
* @return
* nothing
......@@ -234,14 +238,14 @@ void nua_destroy(nua_t *nua)
}
}
/** Obtain default operation handle of the NUA stack object.
/** Obtain default operation handle of the @nua stack object.
*
* A default operation can be used for operations where the
* ultimate result is not important or can be discarded.
*
* @param nua Pointer to NUA stack object
* @param nua Pointer to @nua stack object
*
* @retval !=NULL Pointer to NUA operation handle
* @retval !=NULL Pointer to @nua operation handle
* @retval NULL No default operation exists
*
* @par Related tags:
......@@ -260,7 +264,7 @@ nua_handle_t *nua_default(nua_t *nua)
*
* Allocates a new operation handle and associated storage.
*
* @param nua Pointer to NUA stack object
* @param nua Pointer to @nua stack object
* @param hmagic Pointer to callback context
* @param tag, value, ... List of tagged parameters
*
......@@ -268,8 +272,12 @@ nua_handle_t *nua_default(nua_t *nua)
* @retval NULL Creation failed
*
* @par Related tags:
* Creates a copy of provided tags and they will
* be used with every operation.
* Duplicates the provided tags for use with every operation. Note that
* NUTAG_URL() is converted to SIPTAG_TO() if there is no SIPTAG_TO().
* And also vice versa, request-URI is taken from SIPTAG_TO() if there
* is no NUTAG_URL(). Note that certain SIP headers cannot be saved with
* the handle. They include @ContentLength, @CSeq, @RSeq, @RAck, and
* @Timestamp.
*
* @par Events:
* none
......@@ -345,8 +353,8 @@ int nua_handle_has_invite(nua_handle_t const *nh)
/**Check if operation handle has active event subscriptions.
*
* Active subscription can be established either by nua_subscribe
* or nua_refer() calls.
* Active subscription can be established either by nua_subscribe() or
* nua_refer() calls.
*
* @param nh Pointer to operation handle
*
......@@ -367,8 +375,12 @@ int nua_handle_has_events(nua_handle_t const *nh)
/** Check if operation handle has active registrations
*
* Either REGISTER operation is ongoing or NUA stack is expected to
* refresh in the future.
* A registrtion is active when either when a REGISTER operation going on
* 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
* had SIPTAG_CONTACT(NULL) as an argument.
*
* @param nh Pointer to operation handle
*
......@@ -381,6 +393,8 @@ int nua_handle_has_events(nua_handle_t const *nh)
*
* @par Events:
* none
*
* @sa nua_register(), nua_unregister(), #nua_r_register, #nua_r_unregister
*/
int nua_handle_has_registrations(nua_handle_t const *nh)
{
......@@ -576,58 +590,7 @@ void nua_unregister(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
NUA_SIGNAL(nh, nua_r_unregister, tag, value);
}
/** Place a call using SIP INVITE method.
*
* By default creates a SOA session, includes its description as SDP and
* sends the request to the recipient. Upon receiving the response nua will
* activate the media session and establish the call.
*
* Incomplete call can be hung-up with nua_cancel(). Complete or incomplete
* calls can be hung-up with nua_bye().
*
* Optionally
* - uses early media if NUTAG_EARLY_MEDIA() tag is used with non zero value
* - media parameters can be set by SOA tags
* - nua_invite() can be used to change status of an existing call:
* - #SOATAG_HOLD tag listing the media put on hold or with value "*" sets
* the call on hold
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related Tags:
* NUTAG_URL() \n
* NUTAG_HOLD() \n
* NUTAG_NOTIFY_REFER() \n
* NUTAG_REFER_PAUSE() \n
* NUTAG_INVITE_TIMER() \n
* NUTAG_MEDIA_FEATURES() \n
* SOATAG_HOLD() \n
* SOATAG_AF() \n
* SOATAG_ADDRESS() \n
* SOATAG_USER_SDP() or SOATAG_USER_SDP_STR() \n
* tags in <sip_tag.h>
*
* @par Events:
* #nua_r_invite \n
* #nua_i_state \n
* #nua_i_active \n
* #nua_i_media_error \n
* #nua_i_terminated \n
* #nua_i_fork \n
*
* \sa nua_handle_has_active_call() \n
* nua_handle_has_call_on_hold()\n
* nua_handle_has_invite() \n
* nua_prack() \n
* nua_update() \n
* nua_info() \n
* nua_cancel() \n
* nua_bye()
*/
/* Documented with nua_stack_invite() */
void nua_invite(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
NUA_SIGNAL(nh, nua_r_invite, tag, value);
......@@ -860,7 +823,7 @@ 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_CONTENT_TYPE or #SIPTAG_CONTENT_TYPE_STR \n
* #SIPTAG_PAYLOAD or #SIPTAG_PAYLOAD_STR \n
* #SIPTAG_ACCEPT or #SIPTAG_ACCEPT_STR \n
*
......@@ -891,6 +854,8 @@ void nua_notifier(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
*
* @par Events:
* #nua_r_terminate
*
* @sa nua_notifier(), nua_authorize().
*/
void nua_terminate(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
......@@ -1016,7 +981,7 @@ void nua_update(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
*
* - 401 / 407 response with www-authenticate header/ proxy-authenticate header
* - application should provide stack with username&password for each realm
* with NUTAG_AUTH() tag
* with NUTAG_AUTH() tag
* - restarts operation
*
* @param nh Pointer to operation handle
......@@ -1038,12 +1003,12 @@ void nua_authenticate(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
/** Authorize a subscriber.
*
* After creating a local presence server by nua_notifier(), an
* incoming subscriber launches nua_i_subscription event. Subscriber
* can be authorized in this application callback.
*
* NUTAG_SUB() tag
* NUTAG_SUBSTATE() tag
* After creating a local presence server by nua_notifier(), an incoming
* SUBSCRIBE request causes #nua_i_subscription event. Each subscriber is
* identified with NEATAG_SUB() tag in the #nua_i_subscription event.
* Application can either authorize the subscriber with
* NUTAG_SUBSTATE(#nua_substate_active) or terminate the subscription with
* NUTAG_SUBSTATE(#nua_substate_terminated).
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
......@@ -1052,11 +1017,13 @@ void nua_authenticate(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
* nothing
*
* @par Related Tags:
* NUTAG_SUB()
* NEATAG_SUB() \n
* NUTAG_SUBSTATE()
*
* @par Events:
* (any operation events)
* #nua_i_subscription
*
* @sa nua_notifier(), nua_terminate()
*/
void nua_authorize(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
......@@ -1071,7 +1038,7 @@ void nua_redirect(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
/** Respond with given status.
*
* Currently, only requests application is let to respond is INVITE.
* 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)
......@@ -1082,15 +1049,20 @@ void nua_redirect(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
* 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_active \n
* #nua_i_state \n
* #nua_i_media_error \n
* #nua_i_error
* #nua_i_error \n
* #nua_i_active \n
* #nua_i_terminated \n
*
* @sa #nua_i_invite,
*/
void nua_respond(nua_handle_t *nh,
int status, char const *phrase,
......@@ -1146,7 +1118,6 @@ void nua_handle_destroy(nua_handle_t *nh)
}
}
/*# Send a request to the protocol thread */
void nua_signal(nua_t *nua, nua_handle_t *nh, msg_t *msg, int always,
nua_event_t event,
......
......@@ -124,10 +124,9 @@ tag the layers of Sofia software check whether they can handle the parameter
or should it just be passed to lower layers for processing.
There are some tags with special meaning:
- TAG_NULL() end of tag list
- TAG_END() end of tag list
- TAG_NULL() (synonymous to TAG_END()) end of tag list
- TAG_SKIP() empty tag item
- TAG_NEXT() tag item pointing to another tag list
- TAG_NEXT() tag item pointing to another tag list, ends the current tag list
- TAG_ANY() filter tag accepting any tag
- TAG_IF() conditional inclusion of tag item
......@@ -141,16 +140,16 @@ tag_value_t value,
@endcode
The last tagged value on the parameter list must be TAG_NULL()
(synonym for TAG_END()).
(or TAG_END(), synonym for TAG_NULL()).
Every tag has two versions: \n
NUTAG_<tagname> \n
which takes a value parameter and \n
NUTAG_<tagname>_REF \n
which takes a reference parameter and is used with
which takes a reference parameter. The latter is used with
tl_gets() function to retrieve tag values from tag list.
For some Sofia layers (for example SIP) there exists also additional
For SIP headers there exists also additional
version of tags: \n
SIPTAG_<tagname>_STR \n
This tag version takes a C-language character string as parameter.
......@@ -166,8 +165,9 @@ nua_unregister(op->op_handle,
TAG_NULL());
@endcode
An application using NUA services must use tagging for the function
parameter passing.
An application using NUA services must use tagged arguments for passing the
parameters to functions. See nua_invite() for discussion on how a SIP
message is constructed from the tags.
See documentation of <su_tag.h> for more information of tags and the
module-specific documentation of each Sofia module for information of
......@@ -905,19 +905,28 @@ void app_r_shutdown(int status,
/** @page nua_call_model NUA Call Model
The NUA call follows a relative simple state model presented below. The call
The NUA call follows a relatively simple state model presented below. The call
model is used to present changes in call: when media starts to flow, when
call is considered established, when call is terminated.
In the figure below, a simplified state diagram for a SIP call is
presented. The application will receive an #nua_i_state event indicating
change in call state after it has occurred. The states in NUA call model are
In the figure below, a simplified state diagram for a SIP call is presented.
After the call state has changes the application will receive an
#nua_i_state event indicating the change. The states in NUA call model are
represented by @e enum #nua_callstate, and the current value of state is
included in tag NUTAG_CALLSTATE() with the #nua_i_state event.
The SDP Offer/Answer negotiation status is also included in the event. The
#nua_i_state event is not sent, however, if the change is invoked by by
application calling API functions like nua_bye(), and there is no change in
included as the tag NUTAG_CALLSTATE() with the #nua_i_state event.
The @RFC3264 SDP Offer/Answer negotiation status is also included in the
#nua_i_state event. 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.
The #nua_i_state event is not sent, however, if the change is invoked by by
application calling API functions like nua_bye() and there is no change in
SDP offer/answer status.
@code
......@@ -1208,8 +1217,8 @@ not include the extensions like @b 100rel or @b UPDATE.
| | | | | | :
| | | | +-------------+ :
| | | | :
| (7) CANCEL/487 (8) BYE/487 (9) BYE/200 (5) timeout/BYE
| | | | :
| (7) CANCEL/487 (8) BYE/487 (9) BYE/200 (5) timeout
| | | | : /BYE
| | | | +-------------+ :
| | | | | TERMINATING |<- -+
| | | | +-------------+
......@@ -1479,11 +1488,10 @@ call.
A session can be terminated with a @b BYE request at any time.
If any in-dialog request fail with certain response codes, the session can
be considered terminated, too. These response codes are documented with
sip_response_terminates_dialog(). In some cases, the session should be
terminated gracefully by sending a @b BYE request.
If any in-dialog request (including re-INVITE) fails with certain response
code, the session can be considered terminated, too. These response codes
are documented with sip_response_terminates_dialog(). In some cases, the
session should be terminated gracefully by sending a @b BYE request.
@code
+-------------------------------------------------------------+
......@@ -1491,7 +1499,7 @@ terminated gracefully by sending a @b BYE request.
+-------------------------------------------------------------+
| | | |
| | | |
(1) BYE/200 (2) nua_bye/BYE (4) graceful/BYE (5) final/BYE
(1) BYE/200 (2) nua_bye/BYE (4) graceful/BYE (5) fatal/-
| | | |
| V V |
| +-----------------------------+ |
......@@ -2006,13 +2014,19 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
*
* A call has been activated.
*
* This event will be sent after succesful response to the initial
* 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 NUTAG_ACTIVE_* tags
* @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
......@@ -2099,9 +2113,8 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
*
* Media error indication.
*
* This may be sent after an SOA
* operation has failed while processing incoming or outgoing call.
* Currently, it is not used.
* This may be sent after an SOA operation has failed while processing
* incoming or outgoing call.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with this call
......@@ -2112,7 +2125,7 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
/** @var nua_event_e::nua_i_message
*
* Incoming MESSAGE
* Incoming MESSAGE.
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
......@@ -2125,8 +2138,8 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
*
* Unknown incoming method.
*
* The extension method must be listed using #SIPTAG_ALLOW
* tag in nua_set_options().
* The extension method must be listed using NUTAG_ALLOW() or SIPTAG_ALLOW()
* tag in nua_set_params().
*
* @param nh operation handle associated with the call
* @param hmagic operation magic associated with the call
......@@ -2143,7 +2156,7 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* @param sip NULL
* @param tags empty
*
* @since New in @VERSION_1_12_2.
* @since Experimental in @VERSION_1_12_2.
*/
/** @var nua_event_e::nua_i_notify
......@@ -2182,14 +2195,17 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
/** @var nua_event_e::nua_i_refer
*
* Incoming call transfer.
* 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 sip incoming REFER request
* @param tags #NUTAG_REFER_EVENT \n
* #SIPTAG_REFERRED_BY
* @param tags NUTAG_REFER_EVENT() \n
* SIPTAG_REFERRED_BY()
*
* @sa nua_refer(), #nua_r_refer, NUTAG_NOTIFY_REFER(),
* NUTAG_REFER_WITH_ID().
*/
/** @var nua_event_e::nua_i_state
......@@ -2197,10 +2213,17 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* 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, also
* SDP O/A negotiation status is included.
*
* Note that nua_event_e::nua_i_state also covers call establisment
* 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
......@@ -2210,17 +2233,25 @@ 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 NUTAG_ACTIVE_* \n
* NUTAG_SOA_SESSION
*
* @sa #nua_i_active, #nua_i_terminated
* @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.
* Incoming subscription request.
*
* Not implemented.
* Currently implemented only for refer events created by incoming REFER
* requests. The referrer can modify the subscription lifetime or terminate
* it with SUBSCRIBE requests.
*
* @param nh
* @param hmagic
......@@ -2232,13 +2263,19 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
*
* Incoming subscription to be authorized.
*
* This event is launched by nua_notifier to inform application of the
* current state of the subscriber and to authorize the subscriber.
* This event is launched by nua_notifier() to inform application of the
* current state of the subscriber. The subscriber state is included in the
* NUTAG_SUBSTATE() tag. If the state is #nua_substate_pending or
* #nua_substate_embryonic, application should to authorize the subscriber
* with nua_authorize().
*
* @param nh operation handle associated with the nua_notifier
* @param hmagic operation magic
* @param sip incoming SUBSRIBE request
* @param tags empty
* @param sip incoming SUBSCRIBE request
* @param tags NEATAG_SUB(),
* NUTAG_SUBSTATE()
*
* @sa nua_notifier(), #nua_i_subscribe, nua_authorize(), nua_terminate()
*/
/** @var nua_event_e::nua_i_terminated
......@@ -2256,16 +2293,23 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* @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.
* 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
......
......@@ -255,6 +255,142 @@ int session_process_response(nua_handle_t *nh,
sip_t const *sip,
char const **return_received);
/**@fun void nua_invite(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);
*
* Place a call using SIP INVITE method.
*
* Incomplete call can be hung-up with nua_cancel(). Complete or incomplete
* calls can be hung-up with nua_bye().
*
* Optionally
* - uses early media if NUTAG_EARLY_MEDIA() tag is used with non zero value
* - media parameters can be set by SOA tags
* - nua_invite() can be used to change status of an existing call:
* - #SOATAG_HOLD tag can be used to list the media that will be put on hold,
* the value "*" sets all the media beloginging to the session on hold
*
* @param nh Pointer to operation handle
* @param tag, value, ... List of tagged parameters
*
* @return
* nothing
*
* @par Related Tags: