nua.docs

Sofia SIP is an open-source SIP User-Agent library, compliant with the IETF RFC3261 specification.

<tr><td>S6b</td>			<!-- transition -->
    <td>early</td>			<!-- previous state -->
</td></tr>
<tr><td>S7a</td>			<!-- transition -->
    <td>received</td>			<!-- previous state -->
    <td rowspan=2>CANCEL</td>		<!-- input -->
    <td rowspan=2>487 Request terminated</td><!-- output -->
    <td rowspan=2>terminated</td>	<!-- next state -->
    <td rowspan=2>-</td>		<!-- offer/answer -->
    <td rowspan=2>
   The client can cancel the call attempt before it is completed with a @b
   CANCEL request. Server returns a <i>200 OK</i> response to @b CANCEL and
   a <i>487 Request Terminated</i> response to the @b INVITE transaction and
   the call is terminated.
</td></tr>
<tr><td>S7b</td>			<!-- transition -->
    <td>early</td>			<!-- previous state -->
</td></tr>
<tr><td>S8</td>				<!-- transition -->
    <td>early</td>			<!-- previous state -->
    <td>BYE</td>			<!-- input -->
    <td>487 to INVITE<br>
        200 to BYE</td>			<!-- output -->
    <td>terminated</td>			<!-- next state -->
    <td>-</td>				<!-- offer/answer -->
    <td>
   The client can terminate an early session with a @b BYE request, too. Like
   in the @b CANCEL case above, the server will terminate call immediately,
   return a <i>200 OK</i> response to @b BYE and a <i>487 Request
   Terminated</i> response to the @b INVITE transaction.
</td></tr>
<tr><td>S9</td>				<!-- transition -->
    <td>completed</td>			<!-- previous state -->
    <td>BYE</td>			<!-- input -->
    <td>200 to BYE</td>			<!-- output -->
    <td>terminated</td>			<!-- next state -->
    <td>-</td>				<!-- offer/answer -->
    <td>
   The client can terminate a completed dialog with a @b BYE request. Server
   terminates call immediately, returns a <i>200 OK</i> response to @b BYE
   and lets the underlying transaction engine to take care of consuming @b
   ACK.
</td></tr>
</table>

@section nua_3pcc_call_model Third Party Call Control

There is an alternative offer-answer model for third party call control
(3pcc).  The call setup involves a 3rd party, client C, which sends initial
INVITE to server A without SDP. The call setup looks perfectly ordinary to
server B, however.

@code
	A		        C		        B
	|			|			|
	|<-------INVITE---------|			|
	|			|			|
	|			|			|
	|------200 (offer)----->|  	  		|
	|			|----INVITE (offer)---->|
	|			|			|
	|			|			|
	|			|<-----200 (answer)-----|
	|<-----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>


@section nua_terminate_call_model 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 (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 after
the failed requests.

@code
    +-------------------------------------------------------------+
    |                            READY                            |
    +-------------------------------------------------------------+
      |           |                |		    |
      |           |                |		    |
     (1) BYE/200 (2) nua_bye/BYE  (4) graceful/BYE (5) fatal/-
      |           |		   |     	    |
      |           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 with <i>487 No Such Call</i> response.
</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