nua.docs 85 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2
/* -*- text -*- */

3
/**@MODULEPAGE "nua" - High-Level User Agent Module
Pekka Pessi's avatar
Pekka Pessi committed
4 5 6 7 8 9 10 11 12

@section nua_meta Module Meta Information

The @b nua module contains the user-agent library taking care of basic
SIP User Agent functions. Its functionality includes call management,
messaging and event retrieval.

@CONTACT Pekka Pessi <Pekka.Pessi@nokia.com>

13
@STATUS @SofiaSIP Core library
Pekka Pessi's avatar
Pekka Pessi committed
14 15 16

@LICENSE LGPL

Pekka Pessi's avatar
Pekka Pessi committed
17
@par Contributor(s):
Pekka Pessi's avatar
Pekka Pessi committed
18 19
- Pekka Pessi <Pekka.Pessi@nokia.com>
- Pasi Rinne-Rahkola <Pasi.Rinne-Rahkola@nokia.com>
20
- Kai Vehmanen <Kai.Vehmanen@nokia.com>
21
- Martti Mela <Martti.Mela@nokia.com>
Pekka Pessi's avatar
Pekka Pessi committed
22 23 24 25 26 27

@section nua_overview Overview

The NUA API gives the high-level application programmer transparent and
full control to the SIP protocol engine below it. NUA provides the call
semantics on top of existing transaction semantics found in
Pekka Pessi's avatar
Pekka Pessi committed
28
<a href="../nta/index.html"><b>nta</b></a> module.
29
With NUA it is possible to create different kind of SIP User Agents,
Pekka Pessi's avatar
Pekka Pessi committed
30 31 32 33 34 35
like terminals, gateways or MCUs.

The @b nua engine hides many low-level signaling and media management
aspects from the application programmer. It is possible to use different
kind of media interfaces - even remote ones - in a fully transparent way.

36 37 38 39 40
The application and the protocol engine within User Agent library can be run
in separate threads. The protocol engine communicates with the application
using @ref nua_event_e "events", delivered to the application with a a
callback function. The callback function is called within the thread context
of the application, represented with a #su_root_t object.
Pekka Pessi's avatar
Pekka Pessi committed
41 42 43 44 45

@section nua_concepts_user Sofia Concepts for NUA User

@subsection nua_intro Introduction

Pekka Pessi's avatar
Pekka Pessi committed
46 47
The Sofia software suite is based on certain basic ideas and concepts that
are used in all levels of Sofia software. Many of those are implemented in
Pekka Pessi's avatar
Pekka Pessi committed
48 49
Sofia utility library (<a href="../su/index.html"><b>su</b></a>) providing
unified interface to the most important OS services and utilities .
Pekka Pessi's avatar
Pekka Pessi committed
50 51 52 53 54 55 56 57

The following sections contain descriptions of the concepts that a user of
NUA library must understand to create a working application. The other
utilities (in the SU library and other libraries of Sofia software suite)
might also be useful for an application developer but one must be careful
when using them because they might change the behavior of the Sofia
software suite in a way that causes NUA library to work incorrectly.
See [<a href="../su/index.html"><b>su</b></a>] for more detailed
Pekka Pessi's avatar
Pekka Pessi committed
58 59
description of the SU services.

Pekka Pessi's avatar
Pekka Pessi committed
60
@subsection nua_root Event loop - root object
Pekka Pessi's avatar
Pekka Pessi committed
61

Pekka Pessi's avatar
Pekka Pessi committed
62 63 64 65 66 67 68
The NUA uses the reactor pattern (also known as dispatcher pattern and
notifier pattern) for event driven systems (see [Using Design Patterns
to Develop Reusable Object-oriented Communication Software, D.C. Schmidt,
CACM October '95, 38(10): 65-74]). Sofia uses a task as basic execution
unit for the programming model. According to the model, the program can
ask that the event loop invokes a callback function when a certain event
occurs. Such events include I/O activity, timers or a asynchronously
Pekka Pessi's avatar
Pekka Pessi committed
69 70
delivered messages from other task.

Pekka Pessi's avatar
Pekka Pessi committed
71 72 73 74
The root object is a handle representing the task in the application.
Another way of seeing the same thing is that the root object represents
the main event loop of the task. Through the root object the task code
can access its context information (magic) and thread-synchronization
Pekka Pessi's avatar
Pekka Pessi committed
75
features like wait objects, timers, and messages.
Pekka Pessi's avatar
Pekka Pessi committed
76

77 78 79
An application using NUA services must create a root object and the callback
routine to handle @ref nua_event_e "NUA events". The root object is created
with su_root_create() function and the callback routine is registered with
Pekka Pessi's avatar
Pekka Pessi committed
80 81 82 83
nua_create() function.

Root object has type #su_root_t.

84
See documentation of <sofia-sip/su_wait.h> and <su_root.c> for more information
Pekka Pessi's avatar
Pekka Pessi committed
85 86 87 88 89 90
of root object.

See section #nua_event_e for more information of the callback function.

@subsection nua_magic Magic

Pekka Pessi's avatar
Pekka Pessi committed
91 92 93 94
The magic is a term used for the context pointer that can be bound
to various objects in Sofia stack (for example root object and operation
handle) by the application code. This context pointer is passed back
to the application code when a registered callback function is called by
Pekka Pessi's avatar
Pekka Pessi committed
95
the main event loop. The Sofia stack retains the context information between
Pekka Pessi's avatar
Pekka Pessi committed
96 97 98 99 100
calls to the callback function. An application can use the context information
to store any information it needs for processing the events.

@subsection nua_memmgmt Memory Handling

Pekka Pessi's avatar
Pekka Pessi committed
101 102 103 104 105 106
The home-based memory management is useful when a lot of memory blocks are
allocated for given task. The allocations are done via the memory home,
which keeps a reference to each allocated memory block. When the memory
home is then freed, it will free all memory blocks to which it has
reference. This simplifies application logic because application code does
not need to keep track of the allocated memory and free every allocated block
Pekka Pessi's avatar
Pekka Pessi committed
107 108
separately.

Pekka Pessi's avatar
Pekka Pessi committed
109 110
An application using NUA services can use the memory management services
provided by the SU library but it is not mandatory.
Pekka Pessi's avatar
Pekka Pessi committed
111

112 113
See documentation of <sofia-sip/su_alloc.h> for more information of memory
management services.
Pekka Pessi's avatar
Pekka Pessi committed
114 115 116

@subsection nua_tags Tags

Pekka Pessi's avatar
Pekka Pessi committed
117 118 119 120 121 122 123
Tagging is the mechanism used in Sofia software for packing parameters to
functions. It enables passing a variable number of parameters having
non-fixed types. For an application programmer the tagging is visible as
macros that are used to encapsulate the passed parameters. When evaluated a
tagging macro creates a structure that contains a tag (telling what is the
type of a parameter) and a value (pointer to opaque data). By checking the
tag the layers of Sofia software check whether they can handle the parameter
Pekka Pessi's avatar
Pekka Pessi committed
124 125 126
or should it just be passed to lower layers for processing.

There are some tags with special meaning:
127
- TAG_NULL() (synonymous to TAG_END()) end of tag list
Pekka Pessi's avatar
Pekka Pessi committed
128
- TAG_SKIP()  empty tag item
129
- TAG_NEXT()  tag item pointing to another tag list, ends the current tag list
Pekka Pessi's avatar
Pekka Pessi committed
130 131 132
- TAG_ANY() filter tag accepting any tag
- TAG_IF() conditional inclusion of tag item

Pekka Pessi's avatar
Pekka Pessi committed
133
The NUA functions can be called with a list of tagged values if they have
Pekka Pessi's avatar
Pekka Pessi committed
134 135 136 137 138 139 140 141
following parameters at the end of parameter list:

@code
tag_type_t   tag,
tag_value_t  value,
...);
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
142
The last tagged value on the parameter list must be TAG_NULL()
143
(or TAG_END(), synonym for TAG_NULL()).
Pekka Pessi's avatar
Pekka Pessi committed
144 145 146 147 148

Every tag has two versions: \n
NUTAG_<tagname> \n
which takes a value parameter and \n
NUTAG_<tagname>_REF \n
149
which takes a reference parameter. The latter is used with
Pekka Pessi's avatar
Pekka Pessi committed
150 151
tl_gets() function to retrieve tag values from tag list.

152
For SIP headers there exists also additional
Pekka Pessi's avatar
Pekka Pessi committed
153 154
version of tags: \n
SIPTAG_<tagname>_STR \n
Pekka Pessi's avatar
Pekka Pessi committed
155 156
This tag version takes a C-language character string as parameter.
The corresponding tag without _STR suffix takes a parsed value structure
Pekka Pessi's avatar
Pekka Pessi committed
157 158 159 160 161
as parameter.

The following is an example of call to NUA function containing tagged values:
@code
nua_unregister(op->op_handle,
Pekka Pessi's avatar
Pekka Pessi committed
162
               TAG_IF(use_registrar, NUTAG_REGISTRAR(registrar)),
Pekka Pessi's avatar
Pekka Pessi committed
163 164 165 166 167
               SIPTAG_CONTACT_STR("*"),
               SIPTAG_EXPIRES_STR("0"),
               TAG_NULL());
@endcode

168 169 170
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.
Pekka Pessi's avatar
Pekka Pessi committed
171

172
See documentation of <sofia-sip/su_tag.h> for more information of tags and the
Pekka Pessi's avatar
Pekka Pessi committed
173
module-specific documentation of each Sofia module for information of
Pekka Pessi's avatar
Pekka Pessi committed
174 175 176 177
tags specific for that module.

@subsection nua_debugandlogging Debugging and Logging

Pekka Pessi's avatar
Pekka Pessi committed
178
The modules of Sofia stack contain configurable debugging and logging
179
functionality based on the services defined in <sofia-sip/su_log.h>. The debugging
Pekka Pessi's avatar
Pekka Pessi committed
180 181 182
and logging details (for example level of details on output and output
file name) can be configured by environment variables, directives in
configuration files and compilation directives in the source files.
Pekka Pessi's avatar
Pekka Pessi committed
183

Pekka Pessi's avatar
Pekka Pessi committed
184
Examples of useful directives/ environment variables are:
Pekka Pessi's avatar
Pekka Pessi committed
185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200
- #SOFIA_DEBUG	Default debug level (0..9)
- #NUA_DEBUG	NUA debug level (0..9)
- #NTA_DEBUG	Transaction engine debug level (0..9)
- #TPORT_DEBUG	Transport event debug level (0..9)
- #TPORT_LOG	If set, print out all parsed SIP messages on transport layer
- #TPORT_DUMP	Filename for dumping unparsed messages from transport

The defined debug output levels are:
- 0 fatal errors, panic
- 1 critical errors, minimal progress at subsystem level
- 2 non-critical errors
- 3 warnings, progress messages
- 5 signaling protocol actions (incoming packets, ...)
- 7 media protocol actions (incoming packets, ...)
- 9 entering/exiting functions, very verbatim progress

Pekka Pessi's avatar
Pekka Pessi committed
201
An application using NUA services can also use the debugging and
Pekka Pessi's avatar
Pekka Pessi committed
202 203
logging services provided by the Sofia stack but it is not mandatory.

204
See documentation of <sofia-sip/su_log.h> for more information of debugging and
Pekka Pessi's avatar
Pekka Pessi committed
205 206 207 208 209 210
logging services.

@section nua_concepts NUA Concepts

@subsection nua_stackobject NUA Stack Object

Pekka Pessi's avatar
Pekka Pessi committed
211 212
Stack object represents an instance of SIP stack and media engine. It
contains reference to root object of that stack, user-agent-specific
Pekka Pessi's avatar
Pekka Pessi committed
213 214
settings, and reference to the SIP transaction engine, for example.

Pekka Pessi's avatar
Pekka Pessi committed
215
A NUA stack object is created by nua_create() function and deleted by
Pekka Pessi's avatar
Pekka Pessi committed
216 217 218 219 220 221 222
nua_destroy() function. The nua_shutdown() function is used to gracefully
release active the sessions by @b nua engine.

NUA stack object has type nua_t.

@subsection nua_operationhandle NUA Operation Handle

Pekka Pessi's avatar
Pekka Pessi committed
223 224 225 226 227
Operation handle represents an abstract SIP call/session. It contains
information of SIP dialog and media session, and state machine that
takes care of the call, high-level SDP offer-answer protocol, registration,
subscriptions, publications and simple SIP transactions. An operation
handle may contain list of tags used when SIP messages are created by
Pekka Pessi's avatar
Pekka Pessi committed
228 229
NUA (e.g. From and To headers).

Pekka Pessi's avatar
Pekka Pessi committed
230 231 232
An operation handle is created explicitly by the application using NUA
for sending messages (function nua_handle()) and by stack for incoming
calls/sessions (starting with INVITE or MESSAGE). The handle is destroyed
Pekka Pessi's avatar
Pekka Pessi committed
233 234 235 236 237 238 239 240
by the application using NUA (function nua_handle_destroy()).

Indication and response events are associated with an operation handle.

NUA operation handle has type nua_handle_t.

@subsection nua_stacktread Stack Thread and Message Passing Concepts

Pekka Pessi's avatar
Pekka Pessi committed
241 242
The stack thread is a separate thread from application that provides the
real-time protocol stack operations so that application thread can for
Pekka Pessi's avatar
Pekka Pessi committed
243 244
example block or redraw UI as it likes.

Pekka Pessi's avatar
Pekka Pessi committed
245 246 247 248 249
The communication between stack thread and application thread is asynchronous.
Most of the NUA API functions cause a send of a message to the stack thread
for processing and similarly when something happens in the stack thread it
sends a message to the application thread. The messages to the application
thread are delivered as invokes of the application callback function when
Pekka Pessi's avatar
Pekka Pessi committed
250 251
the application calls su_root_run() or su_root_step() function.

252
@subsection nua_sip_message SIP Message and Header Manipulation
Pekka Pessi's avatar
Pekka Pessi committed
253

Pekka Pessi's avatar
Pekka Pessi committed
254
SIP messages are manipulated with typesafe SIPTAG_ tags. There are
Pekka Pessi's avatar
Pekka Pessi committed
255 256 257
three versions of each SIP tag:
- SIPTAG_<tagname>() takes a parsed value as parameter.
- SIPTAG_<tagname>_STR() takes an unparsed string as parameter.
Pekka Pessi's avatar
Pekka Pessi committed
258
- SIPTAG_<tagname>_REF() takes a reference as parameter, is used
Pekka Pessi's avatar
Pekka Pessi committed
259
        with tl_gets() function to retrieve tag values from tag list.
Pekka Pessi's avatar
Pekka Pessi committed
260 261
- SIPTAG_<tagname>__STR_REF() takes a reference as parameter, is used
        with tl_gets() function to retrieve string tag values from tag list.
Pekka Pessi's avatar
Pekka Pessi committed
262

Pekka Pessi's avatar
Pekka Pessi committed
263
For example a header named "Example" would have tags names SIPTAG_EXAMPLE(),
Pekka Pessi's avatar
Pekka Pessi committed
264 265
SIPTAG_EXAMPLE_STR(), and SIPTAG_EXAMPLE_REF().

Pekka Pessi's avatar
Pekka Pessi committed
266 267 268 269 270
When tags are used in NUA calls the corresponding headers are added to
the message. In case the header can be present only once in a message
and there already exists a value for the header the value given by
tag replaces the existing header value. Passing tag value NULL has no
effect on headers. Passing tag value (void *)-1 removes corresponding
Pekka Pessi's avatar
Pekka Pessi committed
271 272
headers from the message.

Pekka Pessi's avatar
Pekka Pessi committed
273
For example:
Pekka Pessi's avatar
Pekka Pessi committed
274

Pekka Pessi's avatar
Pekka Pessi committed
275
- sending a SUBSCRIBE with @b Event: header and two @b Accept: headers:
Pekka Pessi's avatar
Pekka Pessi committed
276 277 278 279 280 281 282 283 284

@code
	nua_subscribe(nh,
                      SIPTAG_EVENT_STR("presence"),
                      SIPTAG_ACCEPT(accept1),
                      SIPTAG_ACCEPT(accept2),
                      TAG_END());
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
285
- fetching tag values when processing nua_r_subscribe event:
Pekka Pessi's avatar
Pekka Pessi committed
286 287 288 289 290 291 292 293 294 295 296 297 298

@code
           sip_accept_t *ac = NULL;
           sip_event_t  *o  = NULL;

           tl_gets(tl,
                   SIPTAG_EVENT_REF(o),   /* _REF takes a reference! */
                   SIPTAG_ACCEPT_REF(ac),
                   TAG_END());
@endcode

@section nua_tutorial SIP/NUA tutorial

Pekka Pessi's avatar
Pekka Pessi committed
299
This section describes basic usage scenarios of NUA/Sofia stack using
Pekka Pessi's avatar
Pekka Pessi committed
300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336
message sequence charts.

@subsection nua_outgoingcall Outgoing Call

@image latex SIP_outgoing_call.eps

@image html SIP_outgoing_call.gif


@subsection nua_incomingcall Incoming Call

@image latex SIP_incoming_call.eps

@image html SIP_incoming_call.gif

@subsection nua_basicoutgoingoperation Basic Outgoing Operation

@image latex SIP_basic_outgoing_operation.eps

@image html SIP_basic_outgoing_operation.gif


@subsection nua_basicincomingoperation Basic Incoming Operation

@image latex SIP_basic_incoming_operation.eps

@image html SIP_basic_incoming_operation.gif


@subsection nua_outgoingoperationwithauth Outgoing Operation with Authentication

@image latex SIP_outgoing_operation_with_auth.eps

@image html SIP_outgoing_operation_with_auth.gif

@section nua_simpleapplication Simple Application

Pekka Pessi's avatar
Pekka Pessi committed
337 338
The following sections will present code examples from a simple application
that uses services of NUA. The example is not complete but should present
Pekka Pessi's avatar
Pekka Pessi committed
339 340
all relevant details of the basic use of NUA.

341
On sourceforge.net there is available an example application
342 343
<a href="http://sourceforge.net/project/showfiles.php?group_id=143636&package_id=179933">
sofisip_cli.c</a> that can be studied for more complete example.
Pekka Pessi's avatar
Pekka Pessi committed
344 345 346

@subsection nua_datastructures Data Structures & Defines

Pekka Pessi's avatar
Pekka Pessi committed
347
An application using services of NUA normally defines data areas that are
348 349
used to store context information (i.e., "magic"). The types of pointers to
these context information areas are passed to NUA by defines.
Pekka Pessi's avatar
Pekka Pessi committed
350 351

@code
352 353 354
/* type for application context data */
typedef struct application application;
#define NUA_MAGIC_T   application
Pekka Pessi's avatar
Pekka Pessi committed
355

356
/* type for operation context data */
Pekka Pessi's avatar
Pekka Pessi committed
357 358 359 360
typedef union oper_ctx_u oper_ctx_t;
#define NUA_HMAGIC_T  oper_ctx_t
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
361
The information area contents themselves can be defined as
Pekka Pessi's avatar
Pekka Pessi committed
362 363 364 365
C structures or unions:

@code
/* example of application context information structure */
366
typedef struct application
Pekka Pessi's avatar
Pekka Pessi committed
367 368 369 370 371 372
{
  su_home_t       home[1];  /* memory home */
  su_root_t      *root;     /* root object */
  nua_t          *nua;      /* NUA stack object */

  /* other data as needed ... */
373
} application;
Pekka Pessi's avatar
Pekka Pessi committed
374 375

/* Example of operation handle context information structure */
376
typedef union operation
Pekka Pessi's avatar
Pekka Pessi committed
377 378 379
{
  nua_handle_t    *handle;  /* operation handle /

Pekka Pessi's avatar
Pekka Pessi committed
380
  struct
Pekka Pessi's avatar
Pekka Pessi committed
381 382 383 384 385
  {
    nua_handle_t  *handle;  /* operation handle /
    ...                     /* call-related information */
  } call;

386
  struct
387 388 389 390 391
  {
    nua_handle_t  *handle;  /* operation handle /
    ...                     /* subscription-related information */
  } subscription;

Pekka Pessi's avatar
Pekka Pessi committed
392
  /* other data as needed ... */
393 394

} operation;
Pekka Pessi's avatar
Pekka Pessi committed
395 396
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
397 398 399 400 401 402
NUA stack object and handle are opaque to the application programmer.
Likewise, the application context is completely opaque to the NUA stack
module. NUA functions are passed a pointer, and that pointer is then
given back to the application within the callback parameters. In this
case the application context information structure is also used to
store a root object and memory home for memory handling. The application
Pekka Pessi's avatar
Pekka Pessi committed
403 404 405 406
context information also contains the NUA stack object information.

@subsection nua_initanddeinit Initialization and deinitialization

Pekka Pessi's avatar
Pekka Pessi committed
407 408 409
The following code is an example of application function that initializes
the system, enters the main loop for processing the messages, and, after
message processing is ended, deinitalizes the system.
Pekka Pessi's avatar
Pekka Pessi committed
410

Pekka Pessi's avatar
Pekka Pessi committed
411 412 413 414
If the application is not just responding to incoming SIP messages there must
also be means to send messages to NUA. This can be handled for example by
having a separate thread that calls NUA functions to send messages or by
having a socket connection to the application for sending commands to the
Pekka Pessi's avatar
Pekka Pessi committed
415 416 417
application (see documentation of su_wait_create() and su_root_register()).

@code
418 419
/* Application context structure */
application appl[1] = {{{{(sizeof appl)}}}};
Pekka Pessi's avatar
Pekka Pessi committed
420 421 422 423 424

/* initialize system utilities */
su_init();

/* initialize memory handling */
425
su_home_init(appl->home);
Pekka Pessi's avatar
Pekka Pessi committed
426 427

/* initialize root object */
428
appl->root = su_root_create(appl);
Pekka Pessi's avatar
Pekka Pessi committed
429

430
if (appl->root != NULL) {
Pekka Pessi's avatar
Pekka Pessi committed
431
  /* create NUA stack */
432
  appl->nua = nua_create(appl->root,
Pekka Pessi's avatar
Pekka Pessi committed
433
                             app_callback,
434
                             appl,
Pekka Pessi's avatar
Pekka Pessi committed
435 436 437
                             /* tags as necessary ...*/
                             TAG_NULL());

438
  if (appl->nua != NULL) {
Pekka Pessi's avatar
Pekka Pessi committed
439
    /* set necessary parameters */
440
    nua_set_params(appl->nua,
Pekka Pessi's avatar
Pekka Pessi committed
441 442 443
                    /* tags as necessary ... */
                    TAG_NULL());

Pekka Pessi's avatar
Pekka Pessi committed
444
    /* enter main loop for processing of messages */
445
    su_root_run(appl->root);
Pekka Pessi's avatar
Pekka Pessi committed
446 447

    /* destroy NUA stack */
448
    nua_destroy(appl->nua);
Pekka Pessi's avatar
Pekka Pessi committed
449 450 451
  }

  /* deinit root object */
452 453
  su_root_destroy(appl->root);
  appl->root = NULL;
Pekka Pessi's avatar
Pekka Pessi committed
454 455 456
}

/* deinitialize memory handling */
457
su_home_deinit(appl->home);
Pekka Pessi's avatar
Pekka Pessi committed
458 459 460 461 462 463 464

/* deinitialize system utilities */
su_deinit();
@endcode

@subsection nua_handlingevents Handling events

Pekka Pessi's avatar
Pekka Pessi committed
465 466 467 468
Handling of the events coming from NUA stack is done in the callback
function that is registered for NUA stack with the nua_create() function
when the application is initialized. The content of callback function is
in its simplest form just a switch/case statement that dispatches the
Pekka Pessi's avatar
Pekka Pessi committed
469 470 471 472
incoming events for processing to separate functions.

@code
void app_callback(nua_event_t   event,
Pekka Pessi's avatar
Pekka Pessi committed
473
                  int           status,
Pekka Pessi's avatar
Pekka Pessi committed
474
                  char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
475
                  nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
476
                  nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
477
                  nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495
                  nua_hmagic_t *hmagic,
                  sip_t const  *sip,
                  tagi_t        tags[])
{
  switch (event) {
  case nua_i_invite:
    app_i_invite(status, phrase, nua, magic, nh, hmagic, sip, tags);
    break;

  case nua_r_invite:
    app_r_invite(status, phrase, nua, magic, nh, hmagic, sip, tags);
    break;

  /* and so on ... */

  default:
    /* unknown event -> print out error message */
    if (status > 100) {
Pekka Pessi's avatar
Pekka Pessi committed
496 497 498
      printf("unknown event %d: %03d %s\n",
             event,
             status,
Pekka Pessi's avatar
Pekka Pessi committed
499 500 501 502 503 504 505 506 507 508 509 510 511
             phrase);
    }
    else {
      printf("unknown event %d\n", event);
    }
    tl_print(stdout, "", tags);
    break;
  }
} /* app_callback */
@endcode

@subsection nua_placeacall Place a call

Pekka Pessi's avatar
Pekka Pessi committed
512
The following three functions show an example of how a basic SIP
Pekka Pessi's avatar
Pekka Pessi committed
513 514
call is created.

Pekka Pessi's avatar
Pekka Pessi committed
515
The place_a_call() function creates an operation handle and invokes the
Pekka Pessi's avatar
Pekka Pessi committed
516 517 518
SIP INVITE method.

@code
519
operation *place_a_call(char const *name, url_t const *url)
Pekka Pessi's avatar
Pekka Pessi committed
520
{
521 522
  operation *op;
  sip_to_t *to;
Pekka Pessi's avatar
Pekka Pessi committed
523 524

  /* create operation context information */
525 526 527
  op = su_zalloc(appl->home, (sizeof *op));
  if (!op)
     return NULL;
Pekka Pessi's avatar
Pekka Pessi committed
528

529 530 531 532 533 534
  /* Destination address */
  to = sip_to_create(NULL, url);
  if (!to)
     return NULL;

  to->a_display = name;
Pekka Pessi's avatar
Pekka Pessi committed
535 536

  /* create operation handle */
537
  op->handle = nua_handle(appl->nua, op, SIPTAG_TO(to), TAG_END());
Pekka Pessi's avatar
Pekka Pessi committed
538

539
  if (op->handle == NULL) {
Pekka Pessi's avatar
Pekka Pessi committed
540
    printf("cannot create operation handle\n");
541
    return NULL;
Pekka Pessi's avatar
Pekka Pessi committed
542 543
  }

544
  nua_invite(op->handle,
Pekka Pessi's avatar
Pekka Pessi committed
545 546 547 548 549 550
              /* other tags as needed ... */
              TAG_END());

} /* place_a_call */
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
551 552
The app_r_invite() function is called by callback function when response to
INVITE message is received. Here it is assumed that automatic acknowledge
Pekka Pessi's avatar
Pekka Pessi committed
553 554 555
is not enabled so ACK response must be sent explicitly.

@code
Pekka Pessi's avatar
Pekka Pessi committed
556
void app_r_invite(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
557
                  char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
558
                  nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
559
                  nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
560
                  nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
561 562 563 564 565 566 567 568 569 570 571 572 573
                  nua_hmagic_t *hmagic,
                  sip_t const  *sip,
                  tagi_t        tags[])
{
  if (status == 200) {
    nua_ack(nh, TAG_END());
  }
  else {
    printf("response to INVITE: %03d %s\n", status, phrase);
  }
} /* app_r_invite */
@endcode

574 575 576
The nua_i_state event is sent (and app_i_state() function called by callback
function) when the call state changes (see @ref nua_uac_call_model
"client-side call model").
Pekka Pessi's avatar
Pekka Pessi committed
577 578

@code
579 580 581 582 583 584 585 586
void app_i_state(int           status,
		 char const   *phrase,
		 nua_t        *nua,
		 nua_magic_t  *magic,
		 nua_handle_t *nh,
		 nua_hmagic_t *hmagic,
		 sip_t const  *sip,
		 tagi_t        tags[])
Pekka Pessi's avatar
Pekka Pessi committed
587
{
588
  nua_callstate_t state = nua_callstate_init;
Pekka Pessi's avatar
Pekka Pessi committed
589

590 591 592 593
  tl_gets(tags,
          NUTAG_CALLSTATE_REF(state),
          NUTAG__REF(state),

594

595 596 597 598 599
    state = (nua_callstate_t)t->t_value;

  printf("call %s\n", nua_callstate_name(state));

} /* app_i_state */
Pekka Pessi's avatar
Pekka Pessi committed
600 601 602 603
@endcode

@subsection nua_receiveacall Receive a call

Pekka Pessi's avatar
Pekka Pessi committed
604 605
The app_i_invite() function is called by callback function when incoming
INVITE message is received. This example assumes that autoanswer is
Pekka Pessi's avatar
Pekka Pessi committed
606 607 608
not enabled so the response must be sent explicitly.

@code
Pekka Pessi's avatar
Pekka Pessi committed
609
void app_i_invite(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
610
                  char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
611
                  nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
612
                  nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
613
                  nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
614 615 616 617 618 619
                  nua_hmagic_t *hmagic,
                  sip_t const  *sip,
                  tagi_t        tags[])
{
  printf("incoming call\n");

620
  nua_respond(nh, 200, "OK", SOA_USER_SDP(magic->sdp), TAG_END());
Pekka Pessi's avatar
Pekka Pessi committed
621 622 623 624

} /* app_i_invite */
@endcode

625
The app_i_state() function is called by the callback function when call has
Pekka Pessi's avatar
Pekka Pessi committed
626 627 628
been successfully set up and the media has been activated.

@code
Pekka Pessi's avatar
Pekka Pessi committed
629
void app_i_active(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
630
                   char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
631
                   nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
632
                   nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
633
                   nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
634 635 636 637 638 639 640 641 642 643 644
                   nua_hmagic_t *hmagic,
                   sip_t const  *sip,
                   tagi_t        tags[])
{
  printf("call active\n");

} /* app_i_active */
@endcode

@subsection nua_terminatingcall Terminating a call

Pekka Pessi's avatar
Pekka Pessi committed
645
The following three functions show an example of how a basic SIP
Pekka Pessi's avatar
Pekka Pessi committed
646 647 648 649 650 651 652
call is terminated.

The terminate_call() function sends the SIP BYE message.

@code
void terminate_call(void)
{
653
  nua_bye(op->handle, TAG_END());
Pekka Pessi's avatar
Pekka Pessi committed
654 655 656 657

} /* terminate call */
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
658 659
The app_r_bye() function is called by the callback function when answer to
the BYE message is received. The function destroys the call handle and
Pekka Pessi's avatar
Pekka Pessi committed
660 661 662
releases the memory allocated to operation context information.

@code
Pekka Pessi's avatar
Pekka Pessi committed
663
void app_r_bye(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
664
               char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
665
               nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
666
               nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
667
               nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
668 669 670 671 672
               nua_hmagic_t *hmagic,
               sip_t const  *sip,
               tagi_t        tags[])
{
  if (status < 200)
Pekka Pessi's avatar
Pekka Pessi committed
673
     return;
Pekka Pessi's avatar
Pekka Pessi committed
674 675 676 677 678

  printf("call released\n");

  /* release operation handle */
  nua_handle_destroy(hmagic->handle);
679
  op->handle = NULL;
Pekka Pessi's avatar
Pekka Pessi committed
680 681

  /* release operation context information */
682
  su_free(appl->home, hmagic);
Pekka Pessi's avatar
Pekka Pessi committed
683 684 685 686

} /* app_r_bye */
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
687 688
The app_i_bye() function is called by the callback function when an incoming
BYE message is received. The function destroys the call handle and releases
Pekka Pessi's avatar
Pekka Pessi committed
689 690 691
the memory allocated to operation context information.

@code
Pekka Pessi's avatar
Pekka Pessi committed
692
void app_i_bye(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
693
               char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
694
               nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
695
               nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
696
               nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
697 698 699 700 701 702 703 704
               nua_hmagic_t *hmagic,
               sip_t const  *sip,
               tagi_t        tags[])
{
  printf("call released\n");

  /* release operation handle */
  nua_handle_destroy(hmagic->handle);
705
  op->handle = NULL;
Pekka Pessi's avatar
Pekka Pessi committed
706 707

  /* release operation context information */
708
  su_free(appl->home, hmagic);
Pekka Pessi's avatar
Pekka Pessi committed
709 710 711 712 713 714 715 716 717 718 719 720 721

} /* app_i_bye */
@endcode

@subsection nua_sendamessage Sending a message

The following functions show an example of how a SIP MESSAGE is sent.

The send_message() function sends the SIP MESSAGE.

@code
void send_message(void)
{
722
  op_t *op;
Pekka Pessi's avatar
Pekka Pessi committed
723 724

  /* create operation context information */
725 726
  op = su_zalloc(appl->home, sizeof(op_t));
  if (op = NULL) {
Pekka Pessi's avatar
Pekka Pessi committed
727 728 729 730 731 732 733
    printf("cannot create operation context information\n");
    return;
  }

  /* how we create destination_address? */

  /* create operation handle */
734 735
  op->handle = nua_handle(appl->nua,
                                op,
Pekka Pessi's avatar
Pekka Pessi committed
736 737 738
                                NUTAG_URL(destination_address),
                                TAG_END());

739
  if (op->handle == NULL) {
Pekka Pessi's avatar
Pekka Pessi committed
740 741 742 743 744
    printf("cannot create operation handle\n");
    return;
  }

  /* send MESSAGE */
745
  nua_message(op->handle,
Pekka Pessi's avatar
Pekka Pessi committed
746 747 748 749 750 751 752 753
               SIPTAG_CONTENT_TYPE_STR("text/plain"),
               SIPTAG_PAYLOAD_STR("Hello, world!"),
               /* other tags as needed ... */
               TAG_END());

} /* send_message */
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
754
The app_r_message() function is called by the callback function when
Pekka Pessi's avatar
Pekka Pessi committed
755 756 757
answer to the MESSAGE is received.

@code
Pekka Pessi's avatar
Pekka Pessi committed
758
void app_r_message(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
759
                    char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
760
                    nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
761
                    nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
762
                    nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
763 764 765 766 767 768 769 770 771 772 773 774
                    nua_hmagic_t *hmagic,
                    sip_t const  *sip,
                    tagi_t        tags[])
{
  printf("response to MESSAGE: %03d %s\n", status, phrase);
} /* app_r_message */
@endcode

@subsection nua_receivemessage Receiving a message

The following function shows an example of how a SIP MESSAGE is received.

Pekka Pessi's avatar
Pekka Pessi committed
775
The app_i_message() function is called by the callback function when
Pekka Pessi's avatar
Pekka Pessi committed
776 777 778
a SIP MESSAGE is received.

@code
Pekka Pessi's avatar
Pekka Pessi committed
779
void app_i_message(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
780
                   char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
781
                   nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
782
                   nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
783
                   nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
784 785 786 787 788 789
                   nua_hmagic_t *hmagic,
                   sip_t const  *sip,
                   tagi_t        tags[])
{
  printf("received MESSAGE: %03d %s\n", status, phrase);

Pekka Pessi's avatar
Pekka Pessi committed
790 791
  printf("From: %s%s" URL_PRINT_FORMAT "\n",
         sip->sip_from->a_display ? sip->sip_from->a_display : "",
Pekka Pessi's avatar
Pekka Pessi committed
792 793 794 795 796 797 798 799 800 801 802 803 804 805
         sip->sip_from->a_display ? " " : "",
         URL_PRINT_ARGS(sip->sip_from->a_url));

  if (sip->sip_subject) {
    printf("Subject: %s\n", sip->sip_subject->g_value);
  }

  if (sip->sip_payload) {
    fwrite(sip->sip_payload->pl_data, sip->sip_payload->pl_len, 1, stdout);
    fputs("\n", stdout);
  }
} /* app_i_message */
@endcode

806
@subsection nua_notifier Creating a Presence Server
807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824

@code

...
  application_t *app;
  operation_t   *oper;

...

  oper->app = app;


  app->nua = nua_create(ssip->s_root,
                        app_callback,
                        app,
                        TAG_NULL());
...

825 826
  oper->handle = nua_handle(app->nua, app,
                            NUTAG_URL(to->a_url),
827 828 829 830 831 832 833 834 835 836 837 838 839
                            SIPTAG_TO(to),
                            ta_tags(ta));
...

    nua_notifier(oper->handle,
		 SIPTAG_EXPIRES_STR("3600"),
		 SIPTAG_EVENT_STR("presence"),
		 SIPTAG_CONTENT_TYPE_STR("application/pidf-partial+xml"),
		 NUTAG_SUBSTATE(nua_substate_pending),
		 TAG_END());
@endcode

After the nua_notifier object -- the presence server -- is created, an
840
event nua_r_notifier is returned. Status and phrase values of the
841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856
app_callback function indicate the success of the creation.

Authorization of an incoming subscription (to the local presence
server) can be handled in the callback function.

@code
void app_callback(nua_event_t event,
                  int status, char const *phrase,
                  nua_t *nua, application_t *app,
                  nua_handle_t *nh, oper_t *op,
                  sip_t const *sip, tagi_t tags[])
{
  nea_sub_t *subscriber = NULL;

  switch (event) {
  case nua_i_subscription:
857
    tl_gets(tags,
858 859
	    NEATAG_SUB_REF(subscriber),
	    TAG_END());
860 861


862
    nua_authorize(nua_substate_active);
863

864 865 866 867 868 869 870 871 872

  default:
    break;
}


@endcode


Pekka Pessi's avatar
Pekka Pessi committed
873 874
@subsection nua_shutting_down Shutdown

Pekka Pessi's avatar
Pekka Pessi committed
875
The following functions show an example of how application terminates
Pekka Pessi's avatar
Pekka Pessi committed
876 877 878 879 880 881 882
the NUA stack.

The shutdown() function starts the termination.

@code
void shutdown(void)
{
883
  nua_shutdown(appl->nua);
Pekka Pessi's avatar
Pekka Pessi committed
884 885 886 887 888 889 890 891

} /* shutdown */
@endcode

The app_r_shutdown() function is called by the callback function when NUA
stack termination is either finished or failed.

@code
Pekka Pessi's avatar
Pekka Pessi committed
892
void app_r_shutdown(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
893
                    char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
894
                    nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
895
                    nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
896
                    nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915
                    nua_hmagic_t *hmagic,
                    sip_t const  *sip,
                    tagi_t        tags[])
{
  printf("shutdown: %d %s\n", status, phrase);

  if (status < 200) {
    /* shutdown in progress -> return */
    return;
  }

  /* end the event loop. su_root_run() will return */
  su_root_break(magic->root);

} /* app_r_shutdown */
@endcode

*/

916 917
/** @page nua_call_model NUA Call Model

918
The NUA call follows a relatively simple state model presented below. The call
919 920 921
model is used to present changes in call: when media starts to flow, when
call is considered established, when call is terminated.

922
In the figure below, a simplified state diagram for a SIP call is presented.
923 924
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
925
represented by @e enum #nua_callstate, and the current value of state is
926 927 928 929 930 931 932 933 934 935 936 937
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.

938
The #nua_i_state event is not sent, however, if the change is invoked by
939
application calling API functions like nua_bye() and there is no change in
940 941 942 943 944 945 946 947
SDP offer/answer status.

@code
                    +---------------+
             +------|     INIT      |-----+
    INVITE/- |      +---------------+     | INVITE/100
             V                            |
       +------------+               +------------+
948 949 950 951 952 953 954
  +----|  CALLING   |--+        +---|  RECEIVED  |--+
  |    +------------+  |        |   +------------+  |
  |          |         |        |         |         |
  |          | 18X/-   |        |         | -/18X   |
  |          V         |        |         V         |
  |    +------------+  |        |   +------------+  |
  |<---| PROCEEDING |  |        |   |   EARLY    |->|
955
  |    +------------+  |        |   +------------+  |  -/[3456]XX
956 957
  |          |         |        |         |         |
  |          | 2XX/-   | 2XX/-  | -/2XX   | -/2XX   |    or
958 959
  |          V         |        |         V         |
  |    + - - - - - -+  |        |   +------------+  |  CANCEL/200,487
960 961 962 963 964 965 966 967
  |    : COMPLETING :<-+        +-->|  COMPLETE  |  |
  |    + - - - - - -+               +------------+  |
  |          |                            |         |
  |          | -/ACK                ACK/- |         |
  |          |                            |         |
  |          |                            |         |
  |          |      +---------------+     |         |
  |          +----->|     READY     |<----+         |
968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983
  |                 +---------------+               |
  |                   |           |                 |
  |          BYE/200  |           | -/BYE           |
  |                   |           |                 |
  |                   |           V                 |
  |                   |   +--------------+          |
  | [3456]XX/ACK      |   | TERMINATING  |          |
  |                   |   +--------------+          |
  |                   |           |                 |
  |                   |           | [23456]XX/-     |
  |                   V           V                 |
  |                 +---------------+               |
  +---------------->|  TERMINATED   |<--------------+
                    +---------------+
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
984 985 986 987 988 989 990 991 992
The labels "input/output" along each transition indicates SIP messages
received from and sent to network, for instance, state transition
"INVITE/100" occurs when a SIP @b INVITE request is received, and it is
immediately returned a 100 (<i>Trying</i>) response. Label "2XX" means any
200-series response, e.g., <i>200 OK</i> or <i>202 Accepted</i>). Notation
"[3456]XX" means any final error response in 300, 400, 500, or 600
series. Label "18X" means any provisional response from 101 to 199, most
typically 180 (<i>Ringing</i>) or 183 (<i>Session Progress</i>).

993
@section nua_uac_call_model Detailed Client Call Model
994 995 996 997 998

The detailed call model at client side is presented below. This model does
not include the extensions like @b 100rel or @b UPDATE.

@code
999 1000 1001 1002 1003 1004 1005 1006
            +------------+
            |    INIT    |
            +------------+
                  |
                 (1) nua_invite/INVITE
                  |
                  V
            +------------+
1007
            |            |-----------------------------(6a)-----+
1008 1009
            |            |----+  nua_cancel                     |
     +------|  CALLING   |  (7a)  /CANCEL                       |
1010
     |      |            |<---+                                 |
1011 1012 1013 1014 1015 1016 1017
     |      |            |----------------------+               |
     |      +------------+                      |               |
     |            |                           (8a) nua_bye      |
     |           (2) 18X/-                      |   /CANCEL     |
     |            |                             |               |
     |            V                             |               |
     |      +------------+                      |               |
1018
     |      |            |-----------------------------(6b)---->|
1019 1020 1021
     |      |            |----+  nua_cancel     |               |
     |      | PROCEEDING |  (7b)  /CANCEL       |               |
     |      |            |<---+                 |               |
1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036
     |      |            |----------------------+               |
     |      +------------+                      |               |
     |            |                             |               |
   (3a) 2XX/-   (3b) 2XX/-                      |              (6) [3456]XX/ACK
     |            |                             |               |
     |            V                             |               |
     |      + - - - - - -+                      |               |
     +----->:            :                      |               |
            : COMPLETING :-------+              |               |
     + - - -:            :       |              |               |
     :      + - - - - - -+       |              |               |
     :     	  |         	 |              |               |
     :<auto_ack>  |         	 |              |               |
     :or nua_ack  | <auto_ack>   |              |               |
     :and media   | or nua_ack   | nua_bye      |               |
1037
    (5) error 	 (4) /ACK   	(9) /ACK+BYE  (8b) nua_bye/BYE  |
1038
     : /ACK+BYE	  |         	 |              |               |
1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056
     :     	  V         	 |              V               |
     :      +------------+       |       +-------------+        |
     :      |            |       |       |             |        |
     :      |   READY    |       |       | TERMINATING*|        |
     :      |            |       |       |             |        |
     :      +------------+       |       +-------------+        |
     :                           |        |	     |		|
     :                           |      (10) 2XX   (11) 3XX 4XX |
     :      +-------------+      |        |   /BYE   |	5XX 6XX |
     :      |             |      V        V          |   /-     |
     + - - >| TERMINATING |<-------------------------+	        |
            |             |                                     |
            +-------------+			      	        |
                  |        			      		|
                (12) [23456]XX to BYE/-		      		|
                  |             		      		|
                  V             		      		|
            +------------+             		      		|
1057
            | TERMINATED |<-------------------------------------+
1058
            +------------+
1059 1060 1061 1062 1063
@endcode

The detailed description of state transitions on the client side is as
follows:

1064 1065
<table>
<tr><th>#</th>
Pekka Pessi's avatar
Pekka Pessi committed
1066 1067 1068 1069
    <th>Previous state</th>
    <th>Input</th>
    <th>Output</th>
    <th>Next state</th>
1070 1071 1072
    <th>Offer/ Answer</th>
    <th align="left">Description</th>
</tr>
1073
<tr><td>C1</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1074 1075 1076 1077 1078 1079
    <td>init</td>		<!-- previous state -->
    <td>nua_invite()</td>	<!-- input -->
    <td>INVITE</td>		<!-- output -->
    <td>calling</td>		<!-- next state -->
    <td>Generate offer</td>	<!-- offer/answer -->
    <td>
1080
   Client application starts call be invoking nua_invite(). By default, stack runs
1081 1082
   the initial offer/answer step and sends @b INVITE request with the SDP
   offer.
1083
</td></tr>
1084
<tr><td>C2</td>
1085 1086 1087
    <td>calling</td><td>18X</td><td>-</td><td>proceeding</td>
    <td>(Save answer)</td>
  <td>
1088 1089 1090 1091 1092
   Stack receives a 18X response (a provisional response between 101
   and 199). It establishes an early dialog with server.  If the provisional
   response contains an SDP answer, a session with early media is
   established. The caller can be listen to, for instance, ring tone or
   announcements about call progress using the early media session.
1093
</td></tr>
1094
<tr><td>C3a</td>
1095
    <td>calling</td><td rowspan="2">2XX</td>
1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106
    <td rowspan="2">-</td><td rowspan="2">completing</td>
    <td rowspan="2">Save answer</td>
  <td rowspan="2">
   Client receives a 2XX response (usually <i>200 OK</i>) indicating that
   call has been accepted by the server. If there is an SDP session
   description included with response, it is stored.

   Unless the @ref NUTAG_AUTOACK() "auto-ack" mode is explicitly turned off
   by application the client does not stay in @b completing state, but
   proceeds immediately to next state transition.
</td></tr>
1107
<tr><td>C3b</td>
1108
    <td>proceeding</td></tr>
1109
<tr><td>C4</td>
1110 1111 1112 1113 1114 1115 1116 1117 1118 1119
    <td>completing</td>
    <td>nua_ack() or<br>@ref NUTAG_AUTOACK() "auto-ack" </td>
    <td>ACK</td><td>ready</td>
    <td>Process answer</td>
    <td>
   Client sends an ACK request in this state transition. If the initial
   offer was sent with INVITE, the answer must have been received by this
   time, usually in the 2XX response. Client now completes the SDP
   offer-answer exchange and activates the media.
</td></tr>
1120
<tr><td>C5</td>
1121 1122 1123 1124 1125 1126
    <td>completing</td>
    <td>nua_ack() or<br>@ref NUTAG_AUTOACK() "auto-ack" and<br> media error</td>
    <td>ACK<br>BYE</td>
    <td>terminating</td>
    <td>Process answer</td>
    <td>
1127
   If there was a failure in SDP negotiation or other failure with media,
1128
   the stack will automatically terminate the call. The BYE follows
1129
   immediately after the ACK.
1130
</td></tr>
1131
<tr><td>C6a</td>
1132 1133 1134 1135 1136 1137
    <td>calling</td>
    <td rowspan=2>3XX 4XX <br> 5XX 6XX</td>
    <td rowspan=2>ACK*</td>
    <td rowspan=2>terminated</td>
    <td rowspan=2>-</td>
    <td rowspan=2>
1138 1139 1140 1141
   Call is terminated when client receives a final error response (from 300
   to 699) to its INVITE request. In this case, the underlying transaction
   engine takes care of sending ACK even when application-driven-ack mode is
   requested by application.
1142
</td></tr>
1143 1144 1145
<tr><td>C6b</td>
    <td>proceeding</td>
</tr>
1146

1147
<tr><td>C7a</td>
1148 1149 1150 1151 1152 1153
    <td>calling</td>
    <td rowspan=2>nua_cancel()</td>
    <td rowspan=2>CANCEL</td>
    <td>calling</td>
    <td rowspan=2>-</td>
    <td rowspan=2>
1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164
   Client can ask server to cancel the call attempt while in @b calling or
   @b proceeding state. There is no direct call state transition caused by
   nua_cancel(). The call state changes when the server returns a response.
   After receiving a CANCEL request the server will usually return a <i>487
   Request Terminated</i> response and call is terminated as in previous
   item.

   However, there is a race condition and the server can respond with a
   succesful 2XX response before receiving CANCEL. In that case, the call is
   established as usual. It is up to application to terminate the call with
   nua_bye().
1165
</td></tr>
1166
<tr><td>C7b</td>
1167
    <td>proceeding</td>
1168 1169 1170
    <td>proceeding</td>
</tr>
<tr><td>C8a</td>
1171 1172
    <td>proceeding</td>
    <td>nua_bye()</td>
1173 1174 1175
    <td>CANCEL</td>
    <td rowspan=2>terminating*</td>
    <td rowspan=2>-</td>
1176
    <td>
1177 1178 1179
   The call cannot be terminated with BYE before the dialog is established
   with a non-100 preliminary response. So, instead of a @b BYE, stack sends
   a @b CANCEL request, and enters terminating state.
1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190

   However, there is a race condition and the server can respond with a
   succesful 2XX response before receiving CANCEL. If the server responds with
   a 2XX response, the nua will automatically send a BYE request asking server
   to terminate the call.
</td></tr>
<tr><td>C8b</td>
    <td>proceeding</td>
    <td>nua_bye()</td>
    <td>BYE</td>
<td>
1191 1192 1193
   Even an early session can be terminated after entering @b proceeding
   state with nua_bye(). Stack sends a @b BYE request, and enters
   terminating state. Unlike @b CANCEL, @b BYE affects only one fork.
1194 1195 1196 1197 1198

   However, there is a race condition and the server can respond with a
   succesful 2XX response before receiving BYE. If the server responds with
   a 2XX response, the nua will automatically send a BYE request asking server
   to terminate the call.
1199
</td></tr>
1200
<tr><td>C9</td>
1201 1202 1203 1204
    <td>completing</td><td>nua_bye()</td><td>ACK<br>BYE</td><td>terminating</td>
    <td>-</td>
    <td>
   If the stack is in @b completing state (it has already
1205
   received 2XX response), it will have to @b ACK the final response, too.
1206
</td></tr>
1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240

<tr><td>C10</td>
    <td>terminating*</td>
    <td>2XX<br>to INVITE</td>
    <td>BYE</td>
    <td>terminating</td>
    <td>-</td>
    <td>
   There is a race condition between @b BYE and @b INVITE. The call may have
   been re-established with @b INVITE after @b BYE was processed. @b BYE is
   re-sent and call state transitions to normal terminating state.
</td></tr>

<tr><td>C11</td>
    <td>terminating*</td>
    <td>3XX 4XX<br>5XX 6XX<br>to INVITE</td>
    <td>BYE</td>
    <td>terminating</td>
    <td>-</td>
    <td>
   The @b INVITE transaction is completed without a call being created. The
   call state transitions to normal terminating state.
</td></tr>

<tr><td>C12</td>
    <td>terminating</td>
    <td>3XX 4XX<br>5XX 6XX<br>to BYE</td>
    <td>-</td>
    <td>terminated</td>
    <td>-</td>
    <td>
   Call is terminated when the final response to the BYE is received.
</td></tr>

1241
</table>
1242

1243
@section nua_uas_call_model Detailed Server-Side Call Model
1244

1245 1246
The detailed call model at server side (UAS) is presented below. This model
does not include the extensions like @b 100rel or @b UPDATE.
1247 1248 1249

@code

Pekka Pessi's avatar
Pekka Pessi committed
1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264
                           +----------------------------------+
                           |                INIT              |
                           +----------------------------------+
                             |              :               :
                             |              :               :
                            (1) INVITE/100 (2b) INVITE/18X (3c) INVITE/2XX
                             |              :               :
                             |              :               :
                             V              :               :
                          +------------+    :               :
     +--------------------|            |    :               :
     |                    |  RECEIVED  |--------------+     :
     |    +---------------|            |    :         |     :
     |    |               +------------+    :         |     :
     |    |                           |     :         |     :
1265
     |    |          nua_respond/18X (2a)   :         |     :
Pekka Pessi's avatar
Pekka Pessi committed
1266 1267 1268 1269 1270 1271 1272 1273
     |    |                           |     :         |     :
     |    |                           V     V         |     :
     |    |                          +------------+   |     :
     |<------------------------------|            |   |     :
     |    |<-------------------------|    EARLY   |   |     :
     |    |               +----------|            |   |     :
     |    |               |          +------------+   |     :
     | nua_respond/       |                     |     |     :
1274
    (6) /[3456]XX         |    nua_respond/2XX (3b)  (3a)   :
Pekka Pessi's avatar
Pekka Pessi committed
1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291
     |    |               |                     |     |     :
     |    |               |                     V     V     V
     |    |               |                    +-------------+
     |    |               |                    |             |
     |    |               |              +-----|  COMPLETED  |- - +
     |    |               |              |     |             |    :
     |    |               |              |     +-------------+    :
     |    |               |              |            |           :
     |    |               |              |           (4) ACK/-    :
     |    |               |              |            |           :
     |    |               |              |            V           :
     |    |               |              |     +-------------+    :
     |    |               |              |     |             |    :
     |    |               |              |     |    READY    |    :
     |    |               |              |     |             |    :
     |    |               |              |     +-------------+    :
     |    |               |              |                        :
1292 1293
     |   (7) CANCEL/487  (8) BYE/487    (9) BYE/200              (5) timeout
     |    |               |              |                        :     /BYE
Pekka Pessi's avatar
Pekka Pessi committed
1294 1295 1296 1297 1298 1299 1300 1301 1302 1303
     |    |               |              |     +-------------+    :
     |    |               |              |     | TERMINATING |<- -+
     |    |               |              |     +-------------+
     |    |               |              |            |
     |    |               |              |            | [23456]XX/-
     |    |               |              |            |
     |    |               |              |            V
     |    V               V              V     +-------------+
     +---------------------------------------->| TERMINATED  |
                                               +-------------+
1304 1305 1306 1307
@endcode

The detailed description of state transitions on the server side is as
follows:
Pekka Pessi's avatar
Pekka Pessi committed
1308 1309 1310 1311 1312 1313 1314 1315 1316
<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>
1317 1318 1319 1320 1321 1322
<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>Save offer</td>			<!-- offer/answer -->
Pekka Pessi's avatar
Pekka Pessi committed
1323
    <td>
1324 1325 1326
   When a @b INVITE request for a new call is received, the server creates a
   fresh call handle for it, responds to the client with <i>100 Trying</i>
   and enters in the @b received state by default. It saves the possible SDP
Pekka Pessi's avatar
Pekka Pessi committed
1327 1328
   offer included in @b INVITE and passes it to the application.
</td></tr>
1329
<tr><td>S2a</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1330 1331 1332 1333
    <td>received</td>			<!-- previous state -->
    <td>nua_respond()</td>		<!-- input -->
    <td>18X</td>			<!-- output -->
    <td rowspan=2>early</td>		<!-- next state -->
1334
    <td>(Generate early answer)</td>	<!-- offer/answer -->
Pekka Pessi's avatar
Pekka Pessi committed
1335
    <td>
1336 1337 1338 1339 1340
   When server returns a preliminary response for the initial @b INVITE request,
   a early dialog is created. The server can also send an SDP answer with
   the preliminary answer and establish an early session, too. It can use
   the early session to send early media, e.g., ringing tone and
   announcements towards the client.
Pekka Pessi's avatar
Pekka Pessi committed
1341
</td></tr>
1342 1343 1344
<tr><td>S2b</td>			<!-- transition -->
    <td>init</td>			<!-- previous state -->
    <td>INVITE and			<!-- input -->
Pekka Pessi's avatar
Pekka Pessi committed
1345
        @ref NUTAG_AUTOALERT() "auto-alert"</td>
1346
    <td>180 Ringing</td>		<!-- output -->
Pekka Pessi's avatar
Pekka Pessi committed
1347 1348 1349
    <td>Save offer (and
        generate early answer)</td>	<!-- offer/answer -->
    <td>
1350
    When @ref NUTAG_AUTOALERT() "auto-alert" option is enabled, stack sends
Pekka Pessi's avatar
Pekka Pessi committed
1351 1352
    180 Ringing immediately after receiving INVITE and enters @b early state.
</td></tr>
1353
<tr><td>S3a</td>			<!-- transition -->
1354
    <td>received</td>			<!-- previous state -->
Pekka Pessi's avatar
Pekka Pessi committed
1355 1356 1357 1358 1359
    <td rowspan=2>nua_respond()</td>	<!-- input -->
    <td rowspan=2>2XX</td>		<!-- output -->
    <td rowspan=3>completed</td>	<!-- next state -->
    <td rowspan=2>Generate answer</td>	<!-- offer/answer -->
    <td rowspan=2>
1360 1361 1362 1363
   When the server sends a 2XX response towards the client, it accepts the
   call. The @b INVITE transaction is now considered complete but unconfirmed
   at the server side. If the offer was sent in @b INVITE request, the answer
   should be included in the 2XX response.
Pekka Pessi's avatar
Pekka Pessi committed
1364
</td></tr>
1365
<tr><td>S3b</td>			<!-- transition -->
1366
    <td>early</td>			<!-- previous state -->
Pekka Pessi's avatar
Pekka Pessi committed
1367
</td></tr>
1368 1369
<tr><td>S3c</td>			<!-- transition -->
    <td>init</td>			<!-- previous state -->
Pekka Pessi's avatar
Pekka Pessi committed
1370
    <td>INVITE and @ref NUTAG_AUTOANSWER() "auto-answer"
1371 1372
    </td>				<!-- input -->
    <td>200 OK</td>			<!-- output -->
Pekka Pessi's avatar
Pekka Pessi committed
1373
    <td>Save offer and
1374
    <br>generate answer</td>		<!-- offer/answer -->
Pekka Pessi's avatar
Pekka Pessi committed
1375 1376 1377 1378 1379
    <td>
    When @ref NUTAG_AUTOANSWER() "auto-answer" option is enabled, stack send
    200 OK immediately after receiving INVITE and enters @b completed state.
</td></tr>
</td></tr>
1380 1381 1382 1383 1384 1385
<tr><td>S4</td>				<!-- transition -->
    <td>completed</td>			<!-- previous state -->
    <td>ACK</td>			<!-- input -->
    <td>-</td>				<!-- output -->
    <td>ready</td>			<!-- next state -->
    <td>-</td>				<!-- offer/answer -->
Pekka Pessi's avatar
Pekka Pessi committed
1386 1387
    <td>
   The ready state is entered at server side after receiving @b ACK request
1388 1389
   from client, indicating that the client have received server's 2XX
   response. The call is ready, the @b INVITE transaction is confirmed.
Pekka Pessi's avatar
Pekka Pessi committed
1390
</td></tr>
1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401
<tr><td>S5td>				<!-- transition -->
    <td>completed</td>			<!-- previous state -->
    <td>timeout</td>			<!-- input -->
    <td>BYE</td>			<!-- output -->
    <td>terminating</td>		<!-- next state -->
    <td>-</td>				<!-- offer/answer -->
    <td>
   If the server does not receive an @b ACK request in timely fashion, it will
   terminate the call by sending a @b BYE request to client.
</td></tr>
<tr><td>S6a</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1402 1403 1404 1405 1406 1407 1408
    <td>received</td>			<!-- previous state -->
    <td rowspan=2>nua_respond()</td>	<!-- input -->
    <td rowspan=2>3XX 4XX<br>5XX 6XX</td><!-- output -->
    <td rowspan=2>terminated</td>	<!-- next state -->
    <td rowspan=2>-</td>		<!-- offer/answer -->
    <td rowspan=2>
   The server can reject the call by sending a 3XX, 4XX, 5XX, or 6XX response
1409 1410 1411
   towards the client. The underlying transaction engine takes care of
   retransmitting the response when needed. It consumes the ACK response
   sent by the client, too.
Pekka Pessi's avatar
Pekka Pessi committed
1412
</td></tr>
1413
<tr><td>S6b</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1414 1415
    <td>early</td>			<!-- previous state -->
</td></tr>
1416
<tr><td>S7a</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1417 1418 1419 1420 1421 1422
    <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>
1423 1424 1425 1426
   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.
Pekka Pessi's avatar
Pekka Pessi committed
1427
</td></tr>
1428
<tr><td>S7b</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1429 1430
    <td>early</td>			<!-- previous state -->
</td></tr>
1431
<tr><td>S8</td>				<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1432 1433 1434 1435 1436 1437 1438
    <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>
1439 1440 1441 1442
   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.
Pekka Pessi's avatar
Pekka Pessi committed
1443
</td></tr>
1444
<tr><td>S9</td>				<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1445 1446 1447 1448 1449 1450
    <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>
1451 1452 1453 1454
   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.
Pekka Pessi's avatar
Pekka Pessi committed
1455 1456 1457
</td></tr>
</table>

1458 1459
@section nua_3pcc_call_model Third Party Call Control

Pekka Pessi's avatar
Pekka Pessi committed
1460 1461 1462 1463 1464
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.

1465
@code
Pekka Pessi's avatar
Pekka Pessi committed
1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479
	A		        C		        B
	|			|			|
	|<-------INVITE---------|			|
	|			|			|
	|			|			|
	|------200 (offer)----->|  	  		|
	|			|----INVITE (offer)---->|
	|			|			|
	|			|			|
	|			|<-----200 (answer)-----|
	|<-----ACK (answer)-----|			|
	|			|     			|
	|			|----------ACK--------->|
	|			|			|
1480
@endcode
Pekka Pessi's avatar
Pekka Pessi committed
1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494

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>
1495 1496 1497 1498 1499 1500
<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 -->
Pekka Pessi's avatar
Pekka Pessi committed
1501 1502 1503
    <td>
    There is no SDP to save.
</td></tr>
1504 1505 1506
<tr><td>S2b'</td>			<!-- transition -->
    <td>init</td>			<!-- previous state -->
    <td>INVITE and			<!-- input -->
Pekka Pessi's avatar
Pekka Pessi committed
1507
        @ref NUTAG_AUTOALERT() "auto-alert"</td>
1508 1509 1510
    <td>180 Ringing</td>		<!-- output -->
    <td>early</td>			<!-- next state -->
    <td>-</td>				<!-- offer/answer -->
Pekka Pessi's avatar
Pekka Pessi committed
1511 1512 1513
    <td>
    There is no SDP to save.
</td></tr>
1514
<tr><td>S3a'</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1515 1516 1517 1518 1519 1520 1521 1522
    <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>
1523
<tr><td>S3b'</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1524 1525
    <td>received</td>			<!-- previous state -->
</td></tr>
1526 1527 1528
<tr><td>S3c'</td>			<!-- transition -->
    <td>init</td>			<!-- previous state -->
    <td>INVITE and			<!-- input -->
Pekka Pessi's avatar
Pekka Pessi committed
1529
        @ref NUTAG_AUTOANSWER() "auto-answer"</td>
1530
    <td>200 OK</td>			<!-- output -->
Pekka Pessi's avatar
Pekka Pessi committed
1531
</td></tr>
1532 1533 1534 1535 1536
<tr><td>S4'</td>			<!-- transition -->
    <td>completed</td>			<!-- previous state -->
    <td>ACK</td>			<!-- input -->
    <td>-</td>				<!-- output -->
    <td>ready</td>			<!-- next state -->
Pekka Pessi's avatar
Pekka Pessi committed
1537 1538 1539 1540
    <td>Save and process answer</td>	<!-- offer/answer -->
    <td>
    The answer is processed and media activated after receiving @b ACK.
</td></tr>
1541
<tr><td>S9b'</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553
    <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>

1554

1555
@section nua_terminate_call_model Model for Modifying and Terminating Call
1556 1557 1558 1559 1560 1561 1562 1563 1564

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.

1565 1566 1567
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
1568 1569
session should be terminated gracefully by sending a @b BYE request after
the failed requests.
1570

1571 1572 1573 1574 1575 1576
@code
    +-------------------------------------------------------------+
    |                            READY                            |
    +-------------------------------------------------------------+
      |           |                |		    |
      |           |                |		    |
1577
     (1) BYE/200 (2) nua_bye/BYE  (4) graceful/BYE (5) fatal/-
1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620
      |           |		   |     	    |
      |           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
1621
    	terminating state with <i>487 No Such Call</i> response.
1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656
</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()

1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705
*/

/*
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

*/
1706 1707 1708 1709 1710 1711 1712 1713

/**@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

1714
The SIP following event diagram shows a pretty simple, succesful call case.
1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731
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                  |                |                |
1732
 8                  |                |                |
1733 1734
 9                  |                |<--180 Ringing--| <- nua_respond(180)
10  nua_i_invite <- |<--180 Ringing--|                | -> nua_i_state
1735
11   nua_i_state <- |                |                |
1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765
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
1766
hold.
1767

1768
A re-INVITE is sent by calling nua_invite() on handle with existing call.
1769 1770 1771 1772 1773 1774
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.)