Commit cd9b3d9c authored by Pekka Pessi's avatar Pekka Pessi

nua_session.c, nua.docs, sofia-sip/nua_tag.h: updated enum nua_callstate dox.

darcs-hash:20060821161609-65a35-73e53f586cd78f9453473abe3de6d6ac1d5a5596.gz
parent bfcfb9aa
......@@ -2183,13 +2183,12 @@ 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, also
* 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 (@see nua_event_e::nua_i_active ) and
* termination (@see nua_event_e::nua_i_terminated ).
* Note that nua_event_e::nua_i_state also covers call establisment
* (#nua_i_active) and termination (#nua_i_terminated).
*
* @param status Protocol status code. \n
* Always present
......@@ -2200,6 +2199,8 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
* @param sip NULL
* @param tags NUTAG_ACTIVE_* \n
* NUTAG_SOA_SESSION
*
* @sa #nua_i_active, #nua_i_terminated
*/
/** @var nua_event_e::nua_i_subscribe
......
......@@ -60,6 +60,82 @@
typedef struct sdp_session_s sdp_session_t;
#endif
/* ---------------------------------------------------------------------- */
/* */
/** @enum nua_callstate
The states for SIP session established with INVITE.
Initially the call states follow the state of the INVITE transaction. If the
initial INVITE transaction fails, the call is terminated. The status codes
401 and 407 are an exception: if the client (on the left side in the diagram
below) receives them, it enters in #nua_callstate_authenticating state.
If a re-INVITE transaction fails, the result depends on the status code in
failure. The call can return to the ready state, be terminated immediately,
or be terminated gracefully. The proper action to take is determined with
sip_response_terminates_dialog().
@par Session State Diagram
@code
+----------+
| |---------------------+
| Init | |
| |----------+ |
+----------+ | |
| | | |
--/INVITE| |INVITE/100 | |
V V | |
+----------+ +----------+ | |
+--------| | | | | |
| 18X +-| Calling | | Received | |INVITE/ |
| /- | | | | | | /18X |
| V +----------+ +----------+ V |
| +----------+ | | | +----------+ |
|---| | |2XX -/ | -/ | | | |
| | Proceed- | | /- 2XX| 18X| | Early | |INVITE/
| | ing | | | +->| | | /200
| +----------+ V V +----------+ |
| | +----------+ +----------+ | -/ |
| 2XX| | | | |<--+ 2XX |
| /-| | Complet- | | Complete |<-----------+
| +->| ing | | |------+
| +----------+ +----------+ |
| | | | |
|401,407/ -/ACK| |ACK/- |timeout/ |
| /ACK V V | /BYE |
| +----------+ | |
| | | | |
| +--| Ready | | |
| | | | | |
| | +----------+ | |
| | | | |
| BYE/ | |-/BYE | |BYE/
V /200 | V | |/200
+----------+ | +----------+ | |
| | | | | | |
|Authentic-| | | Terminat-|<----+ |
| ating | | | ing | |
+----------+ | +----------+ |
| | |
| |[23456]XX/- |
| V |
| +----------+ |
| | | |
+->|Terminated|<--------------+
| |
+----------+
|
V
+----------+
| |
| Init |
| |
@endcode +----------+
*/
/* ---------------------------------------------------------------------- */
/* Session event usage */
......
......@@ -1293,15 +1293,17 @@ SOFIAPUBVAR tag_typedef_t nutag_allow_ref;
* int
*
* @par Values
* - @c nua_callstate_init - Initial state
* - @c nua_callstate_authenticating - 401/407 received
* - @c nua_callstate_calling - INVITE sent
* - @c nua_callstate_proceeding - 18X received
* - @c nua_callstate_received - INVITE received
* - @c nua_callstate_early - 18X sent (w/SDP)
* - @c nua_callstate_ready - 2XX received or sent
* - @c nua_callstate_terminating - BYE sent
* - @c nua_callstate_terminated - BYE complete
* - #nua_callstate_init - Initial state
* - #nua_callstate_authenticating - 401/407 received
* - #nua_callstate_calling - INVITE sent
* - #nua_callstate_proceeding - 18X received
* - #nua_callstate_completing - 2XX received
* - #nua_callstate_received - INVITE received (and 100 Trying sent)
* - #nua_callstate_early - 18X sent
* - #nua_callstate_completed - 2XX sent
* - #nua_callstate_ready - 2XX and ACK received/sent
* - #nua_callstate_terminating - BYE sent
* - #nua_callstate_terminated - BYE complete
*
* Corresponding tag taking reference parameter is NUTAG_CALLSTATE_REF()
*/
......
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