nua.docs

this is simple sip stack.

	|<-----ACK (answer)-----|			|
	|			|     			|
	|			|----------ACK--------->|
	|			|			|
@endcode

The modifications to the call model affect mainly offer-answer model.
The detailed description of state transitions for 3pcc on the server side is as
follows:

<table>
<tr><th>#</th>
    <th>Previous state</th>
    <th>Input</th>
    <th>Output</th>
    <th>Next state</th>
    <th>Offer/ Answer</th>
    <th align="left">Description</th>
</tr>
<tr><td>S1'</td>			<!-- transition -->
    <td>init</td>			<!-- previous state -->
    <td>INVITE</td>			<!-- input -->
    <td>100 Trying</td>			<!-- output -->
    <td>received</td>			<!-- next state -->
    <td>-</td>				<!-- offer/answer -->
    <td>
    There is no SDP to save.
</td></tr>
<tr><td>S2b'</td>			<!-- transition -->
    <td>init</td>			<!-- previous state -->
    <td>INVITE and			<!-- input -->
        @ref NUTAG_AUTOALERT() "auto-alert"</td>
    <td>180 Ringing</td>		<!-- output -->
    <td>early</td>			<!-- next state -->
    <td>-</td>				<!-- offer/answer -->
    <td>
    There is no SDP to save.
</td></tr>
<tr><td>S3a</td>			<!-- transition -->
    <td>early</td>			<!-- previous state -->
    <td rowspan=2>nua_respond()</td>	<!-- input -->
    <td rowspan=2>2XX</td>		<!-- output -->
    <td rowspan=3>completed</td>	<!-- next state -->
    <td rowspan=3>Generate offer</td>	<!-- offer/answer -->
    <td rowspan=3>
    The offer is sent in 200 OK.
</td></tr>
<tr><td>S3b'</td>			<!-- transition -->
    <td>received</td>			<!-- previous state -->
</td></tr>
<tr><td>S3c'</td>			<!-- transition -->
    <td>init</td>			<!-- previous state -->
    <td>INVITE and			<!-- input -->
        @ref NUTAG_AUTOANSWER() "auto-answer"</td>
    <td>200 OK</td>			<!-- output -->
</td></tr>
<tr><td>S4'</td>			<!-- transition -->
    <td>completed</td>			<!-- previous state -->
    <td>ACK</td>			<!-- input -->
    <td>-</td>				<!-- output -->
    <td>ready</td>			<!-- next state -->
    <td>Save and process answer</td>	<!-- offer/answer -->
    <td>
    The answer is processed and media activated after receiving @b ACK.
</td></tr>
<tr><td>S9b'</td>			<!-- transition -->
    <td>completed</td>			<!-- previous state -->
    <td>ACK and O/A error</td>		<!-- input -->
    <td>BYE</td>			<!-- output -->
    <td>terminating</td>		<!-- next state -->
    <td>Save and process answer</td>	<!-- offer/answer -->
    <td>
    If the offer/answer negotiation ends in error after the server receives
    answer in @b ACK request, the server will have to terminate call by
    sending a @b BYE request.
</td></tr>
</table>


@par Model for Modifying and Terminating Call

After the SIP session has been established, it can be further modified by @b
INVITE transactions, initiated by either the original client or the original
server. These so-called re-INVITE transactions can be used to upgrade
session (add new media to it), put the session on hold or resume a held
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.


@code
    +-------------------------------------------------------------+
    |                            READY                            |
    +-------------------------------------------------------------+
      |           |                |		    |
      |           |                |		    |
     (1) BYE/200 (2) nua_bye/BYE  (4) graceful/BYE (5) final/BYE
      |           |		   |     	    |
      |           V		   V     	    |
      |     +-----------------------------+         |
      |     |         TERMINATING         |         |
      |     +-----------------------------+	    |
      |                    |			    |
      |                   (3) [23456]XX/-	    |
      |                    |			    |
      V                    V			    V
    +-------------------------------------------------------------+
    |                         TERMINATED                          |
    +-------------------------------------------------------------+
@endcode

The detailed description of state transitions while call is terminated is as
follows:
<table>
<tr><th>#</th>
    <th>Previous state</th>
    <th>Input</th>
    <th>Output</th>
    <th>Next state</th>
    <th align="left">Description</th>
</tr>
<tr><td>T1</td>				<!-- transition -->
    <td>ready</td>			<!-- previous state -->
    <td>BYE</td>			<!-- input -->
    <td>200 OK</td>			<!-- output -->
    <td>terminated</td>			<!-- next state -->
    <td>
    	When the @b BYE request is received, the recipient terminates the
    	currently ongoing @b INVITE transaction, the session and its dialog
    	usage (if there is another dialog usage active, e.g., a subscription
    	creted by @b REFER.)
</td></tr>
<tr><td>T2</td>				<!-- transition -->
    <td>ready</td>			<!-- previous state -->
    <td>nua_bye</td>			<!-- input -->
    <td>BYE</td>			<!-- output -->
    <td>terminating</td>		<!-- next state -->
    <td>
        The application terminates the session by calling nua_bye(). All the
    	call-related requests on the dialog are rejected while in
    	terminating state (XXX - with what?).
</td></tr>
<tr><td>T3</td>				<!-- transition -->
    <td>terminating</td>		<!-- previous state -->
    <td>2XX 3XX 4XX 5XX 6XX</td>	<!-- input -->
    <td>-</td>				<!-- output -->
    <td>terminated</td>			<!-- next state -->
    <td>
        The session is finally terminated when a final response to @b BYE is
    	received. Note that nua stack does retry @b BYE requests.
</td></tr>
<tr><td>T4</td>				<!-- transition -->
    <td>ready</td>			<!-- previous state -->
    <td>"graceful" response</td>	<!-- input -->
    <td>BYE</td>			<!-- output -->
    <td>terminating</td>		<!-- next state -->
    <td>
        A call-related request (@b re-INVITE, @b UPDATE, @b INFO, @b PRACK,
    	@b REFER) fails with a response code indicating that the client
    	should gracefully terminate the call.
</td></tr>
<tr><td>T5</td>				<!-- transition -->
    <td>ready</td>			<!-- previous state -->
    <td>"fatal" response</td>		<!-- input -->
    <td>-</td>				<!-- output -->
    <td>terminated</td>			<!-- next state -->
    <td>
        A call-related request (@b re-INVITE, @b UPDATE, @b INFO, @b PRACK,
    	@b REFER) fails with a response code indicating that the call has
    	been terminated.
</td></tr>
</table>

@sa http://www.ietf.org/internet-drafts/draft-sparks-sipping-dialogusage-01.txt
@sa sip_response_terminates_dialog()

*/

/*
For reference:

                    +---------------+
             +-(1)--|     INIT      |-----+
    INVITE/- |      +---------------+    (A) INVITE/100
             V                            |
       +------------+               +------------+
  +----|  CALLING   |           +---|  RECEIVED  |--+
  |    +------------+           |   +------------+  |
  |          |                  |         |         |
  |         (2) 18X/-           |        (B) -/18X  |
  |          V                  |         V         |
  |    +------------+           |   +------------+  |
  |<---| PROCEEDING |--+        |   |   EARLY    |->|
  |    +------------+  |        |   +------------+ (F) -/[3456]XX
  |          :         |        |         |         |
  |         (4) 2XX/-  |       (E) -/2XX (C) -/2XX  |    or
  |          V         |        |         V         |
  |    + - - - - - -+  |        |   +------------+ (G) CANCEL/200,487
  |    : COMPLETING :  |        +-->|  COMPLETE  |  |
  |    + - - - - - -+  |            +------------+  |
  |          :         |                  |    :    |
  |         (5)-/ACK  (3) 2XX/ACK   ACK/-(D)   :    |
  |          :         |                  |    :    |
  |          :         V                  |    :    |
  |          :      +---------------+     |    :    |
  |          + - - >|     READY     |<----+    :    |
  |                 +---------------+          :    |
  |                   |     |                  :    |
  |          BYE/200 (i)  (ii) -/BYE  timeout/ :    |
  |                   |     |             BYE (H)   |
  |                   |     V                  :    |
  |                   |   +--------------+     :    |
 (6) [3456]XX/ACK     |   | TERMINATING  |<- - +    |
  |                   |   +--------------+          |
  |                   |           |                 |
  |                   |         (iii) [23456]XX/-   |
  |                   V           V                 |
  |                 +---------------+               |
  +---------------->|  TERMINATED   |<--------------+
                    +---------------+
                            |
                            V
                           INIT

*/

/**@page nua_event_diagrams NUA Event Diagrams

The example diagrams below try to present how to use NUA API with different
SIP use cases.

@section nua_event_diagram_call Basic Call

The SIP following event diagram shows a pretty simple, succesful call case.
The nua events and nua function calls are show in the diagram below as well
as the SIP messages.

The call setup above assumes parameters NUTAG_AUTOALERT(0),
NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.

@code

                   Alice           Proxy            Bob
 0                  |                |                |
 1  nua_handle()    |                |                |
 2  nua_invite() -> |-----INVITE---->|                |
 3   nua_i_state <- |                |                |
 4                  |                |-----INVITE---->| -> nua_i_invite
 5                  |<--100 Trying---|                | -> nua_i_state
 6                  |                |                |
 7                  |                |                |
 8                  |                |                |
 9                  |                |<--180 Ringing--| <- nua_respond(180)
10  nua_i_invite <- |<--180 Ringing--|                | -> nua_i_state
11   nua_i_state <- |                |                |
12                  |                |<--200 OK-------| <- nua_respond(200)
13  nua_i_invite <- |<---200 OK------|                | -> nua_i_state
14   nua_i_state <- |                |                |
15     nua_ack() -> |-----ACK------->|                |
16   nua_i_state <- |                |-----ACK------->| -> nua_i_ack
17                  |                |                | -> nua_i_state
18                  |                |                |
19               <<====== SIP Session Established =======>>
20                  |                |                |
21                  |                |                |
22     nua_bye() -> |-----BYE------->|                |
23                  |                |-----BYE------->| -> nua_i_bye
24                  |                |<----200 OK-----| -> nua_i_state
25     nua_r_bye <- |<---200 OK------|                |
26   nua_i_state <- |                |                |
                    |                |                |
@endcode

@section nua_event_diagram_call_hold Holding Call

The media (audio, video) can be put on hold. In SIP system this means that
application can indicate to the remote end that it is engaged in other
activity (another call, for instance) and does not wish to receive media
from the remove end.

The call hold is usully implemented using re-INVITE. Re-INVITE is an INVITE
request sent on existing SIP session. Both original caller and callee can
send re-INVITEs. The main use of re-INVITE is modifying sessions: adding
media lines to the session, changing codecs on existing media, and, as you
might expect, putting existing media on hold as well as resuming media from
hold.

A re-INVITE is sent by calling nua_invite() on handle with existing call.
When putting call on hold, the application can include SOATAG_HOLD("audio")
or SOATAG_HOLD("video") or SOATAG_HOLD("audio, video") or SOATAG_HOLD("*")
as parameters to re-INVITE nua_invite(). (Note that last SOATAG_HOLD() in
the tag list will override the SOATAG_HOLD() tags before it.)

Another feature where nua tries to be helpful is autoanswer and auto-ACK on
existing sessions: the re-INVITE is automatically responded with <i>200 OK</i>
and ACK is automatically sent. (If the application wants to respond and ACK
by itself, it should explicitly set NUTAG_AUTOANSWER(0) and/or
NUTAG_AUTOACK(0) in the handle; either include them in nua_invite() or
nua_respond() parameters or call nua_set_hparams() explicitly.

@code
                   Alice           Proxy            Bob
 0     nua_handle() |                |                |
 1                  |                |                |
 2  nua_invite() -> |-----INVITE---->|                |
 3   nua_i_state <- |                |                |
 4                  |                |-----INVITE---->| -> nua_i_invite
 5                  |<--100 Trying---|                | -> nua_i_state
 6                  |                |                |
 7                  |                |                |
 8                  |                |                |
 9                  |                |<--180 Ringing--| <- nua_respond(180)
10  nua_i_invite <- |<--180 Ringing--|                | -> nua_i_state
11   nua_i_state <- |                |                |
12                  |                |<--200 OK-------| <- nua_respond(200)
13  nua_i_invite <- |<---200 OK------|                | -> nua_i_state
14   nua_i_state <- |                |                |
15     nua_ack() -> |-----ACK------->|                |
16   nua_i_state <- |                |-----ACK------->| -> nua_i_ack
17                  |                |                | -> nua_i_state
18                  |                |                |
19               <<== Bi-Directional RTP Established ==>>
20                  |                |                |
21                  |                |                |
22                  |                |<--INVITE(hold)-| <- nua_invite(..
21                  |                |                |       NUTAG_HOLD("*")..)
23  nua_i_invite <- |<-INVITE(hold)--|                | -> nua_i_state
25   nua_i_state <- |----200 OK----->|    	      |
26                  |                |----200 OK----->| -> nua_i_invite
28                  |                |<-----ACK-------| -> nua_i_state
29     nua_i_ack <- |<----ACK--------|                |
24                  |                |                |
30               <<== Uni-Directional RTP Established ==>>
24                  |                |                |
31                  |                |                |
32                  |                |<--INVITE-------| <- nua_invite(..
21                  |                |                |      NUTAG_HOLD(NULL)..)
33  nua_i_invite <- |<--INVITE-------|                | -> nua_i_state
35