nua.docs 73.1 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
/* -*- text -*- */

/**@mainpage Sofia User Agent Library - nua

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

@STATUS Core library

@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>
Pekka Pessi's avatar
Pekka Pessi committed
21 22 23 24 25 26

@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
27
<a href="../nta/index.html"><b>nta</b></a> module.
Pekka Pessi's avatar
Pekka Pessi committed
28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
API makes it possible to create different kind of User Agents,
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.

The application and the protocol engine within User Agent library can be
run in separate threads. Communications from the protocol engine is
conveyed through a callback function. The callback function is called
within context of the application, so the application must provide
appropriate handle to a #su_root_t object.

@section nua_concepts_user Sofia Concepts for NUA User

@subsection nua_intro Introduction

Pekka Pessi's avatar
Pekka Pessi committed
45 46
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
47 48
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
49 50 51 52 53 54 55 56

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
57 58
description of the SU services.

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

Pekka Pessi's avatar
Pekka Pessi committed
61 62 63 64 65 66 67
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
68 69
delivered messages from other task.

Pekka Pessi's avatar
Pekka Pessi committed
70 71 72 73
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
74
features like wait objects, timers, and messages.
Pekka Pessi's avatar
Pekka Pessi committed
75 76 77 78

An application using NUA services must create a root object and the
callback routine to handle 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
79 80 81 82
nua_create() function.

Root object has type #su_root_t.

Pekka Pessi's avatar
Pekka Pessi committed
83
See documentation of <su_wait.h> and <su_root.c> for more information
Pekka Pessi's avatar
Pekka Pessi committed
84 85 86 87 88 89
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
90 91 92 93
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
94
the main event loop. The Sofia stack retains the context information between
Pekka Pessi's avatar
Pekka Pessi committed
95 96 97 98 99
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
100 101 102 103 104 105
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
106 107
separately.

Pekka Pessi's avatar
Pekka Pessi committed
108 109
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
110

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

@subsection nua_tags Tags

Pekka Pessi's avatar
Pekka Pessi committed
116 117 118 119 120 121 122
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
123 124 125 126 127 128 129 130 131 132
or should it just be passed to lower layers for processing.

There are some tags with special meaning:
- TAG_NULL() end of tag list
- TAG_END()  end of tag list
- TAG_SKIP()  empty tag item
- TAG_NEXT() tag item pointing to another tag list
- 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()
Pekka Pessi's avatar
Pekka Pessi committed
143 144 145 146 147 148
(synonym for TAG_END()).

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

Pekka Pessi's avatar
Pekka Pessi committed
152
For some Sofia layers (for example SIP) 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

Pekka Pessi's avatar
Pekka Pessi committed
168
An application using NUA services must use tagging for the function
Pekka Pessi's avatar
Pekka Pessi committed
169 170
parameter passing.

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

@subsection nua_debugandlogging Debugging and Logging

Pekka Pessi's avatar
Pekka Pessi committed
177 178 179 180 181
The modules of Sofia stack contain configurable debugging and logging
functionality based on the services defined in <su_log.h>. The debugging
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
182

Pekka Pessi's avatar
Pekka Pessi committed
183
Examples of useful directives/ environment variables are:
Pekka Pessi's avatar
Pekka Pessi committed
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
- #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
200
An application using NUA services can also use the debugging and
Pekka Pessi's avatar
Pekka Pessi committed
201 202
logging services provided by the Sofia stack but it is not mandatory.

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

@section nua_concepts NUA Concepts

@subsection nua_stackobject NUA Stack Object

Pekka Pessi's avatar
Pekka Pessi committed
210 211
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
212 213
settings, and reference to the SIP transaction engine, for example.

Pekka Pessi's avatar
Pekka Pessi committed
214
A NUA stack object is created by nua_create() function and deleted by
Pekka Pessi's avatar
Pekka Pessi committed
215 216 217 218 219 220 221
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
222 223 224 225 226
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
227 228
NUA (e.g. From and To headers).

Pekka Pessi's avatar
Pekka Pessi committed
229 230 231
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
232 233 234 235 236 237 238 239
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
240 241
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
242 243
example block or redraw UI as it likes.

Pekka Pessi's avatar
Pekka Pessi committed
244 245 246 247 248
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
249 250 251 252
the application calls su_root_run() or su_root_step() function.

@subsection nua_sipmessage SIP Message and Header Manipulation

Pekka Pessi's avatar
Pekka Pessi committed
253
SIP messages are manipulated with typesafe SIPTAG_ tags. There are
Pekka Pessi's avatar
Pekka Pessi committed
254 255 256
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
257
- SIPTAG_<tagname>_REF() takes a reference as parameter, is used
Pekka Pessi's avatar
Pekka Pessi committed
258
        with tl_gets() function to retrieve tag values from tag list.
Pekka Pessi's avatar
Pekka Pessi committed
259 260
- 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
261

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

Pekka Pessi's avatar
Pekka Pessi committed
265 266 267 268 269
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
270 271
headers from the message.

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

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

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

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

@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
298
This section describes basic usage scenarios of NUA/Sofia stack using
Pekka Pessi's avatar
Pekka Pessi committed
299 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.

Pekka Pessi's avatar
Pekka Pessi committed
341
The source distribution of Sofia stack contains in directory nua an example
Pekka Pessi's avatar
Pekka Pessi committed
342 343 344 345
application nua_cli.c that can be studied for more complete example.

@subsection nua_datastructures Data Structures & Defines

Pekka Pessi's avatar
Pekka Pessi committed
346 347
An application using services of NUA normally defines data areas that are
used to store context information (i.e., "Magic"). The types of pointers
Pekka Pessi's avatar
Pekka Pessi committed
348 349 350 351 352 353 354 355 356 357 358 359
to these context information areas are passed to NUA by defines.

@code
/* application context information type */
typedef struct app_ctx_s app_ctx_t;
#define NUA_MAGIC_T   app_ctx_t

/* operation handle context information type */
typedef union oper_ctx_u oper_ctx_t;
#define NUA_HMAGIC_T  oper_ctx_t
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
360
The information area contents themselves can be defined as
Pekka Pessi's avatar
Pekka Pessi committed
361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378
C structures or unions:

@code
/* example of application context information structure */
struct app_ctx_s
{
  su_home_t       home[1];  /* memory home */
  su_root_t      *root;     /* root object */
  nua_t          *nua;      /* NUA stack object */

  /* other data as needed ... */
};

/* Example of operation handle context information structure */
union oper_ctx_u
{
  nua_handle_t    *handle;  /* operation handle /

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

  /* other data as needed ... */
};
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
389 390 391 392 393 394
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
395 396 397 398
context information also contains the NUA stack object information.

@subsection nua_initanddeinit Initialization and deinitialization

Pekka Pessi's avatar
Pekka Pessi committed
399 400 401
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
402

Pekka Pessi's avatar
Pekka Pessi committed
403 404 405 406
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
407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435
application (see documentation of su_wait_create() and su_root_register()).

@code
/* initialize application context area */
app_ctx_t app_ctx[1] = {{{{sizeof(app_ctx_t)}}}};

/* initialize system utilities */
su_init();

/* initialize memory handling */
su_home_init(app_ctx->home);

/* initialize root object */
app_ctx->root = su_root_create(app_ctx);

if (app_ctx->root != NULL) {
  /* create NUA stack */
  app_ctx->nua = nua_create(app_ctx->root,
                             app_callback,
                             app_ctx,
                             /* tags as necessary ...*/
                             TAG_NULL());

  if (app_ctx->nua != NULL) {
    /* set necessary parameters */
    nua_set_params(app_ctx->nua,
                    /* tags as necessary ... */
                    TAG_NULL());

Pekka Pessi's avatar
Pekka Pessi committed
436
    /* enter main loop for processing of messages */
Pekka Pessi's avatar
Pekka Pessi committed
437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456
    su_root_run(app_ctx->nua);

    /* destroy NUA stack */
    nua_destroy(app_ctx->nua);
  }

  /* deinit root object */
  su_root_destroy(app_ctx->root);
  app_ctx->root = NULL;
}

/* deinitialize memory handling */
su_home_deinit(app_ctx->home);

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

@subsection nua_handlingevents Handling events

Pekka Pessi's avatar
Pekka Pessi committed
457 458 459 460
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
461 462 463 464
incoming events for processing to separate functions.

@code
void app_callback(nua_event_t   event,
Pekka Pessi's avatar
Pekka Pessi committed
465
                  int           status,
Pekka Pessi's avatar
Pekka Pessi committed
466
                  char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
467
                  nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
468
                  nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
469
                  nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487
                  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
488 489 490
      printf("unknown event %d: %03d %s\n",
             event,
             status,
Pekka Pessi's avatar
Pekka Pessi committed
491 492 493 494 495 496 497 498 499 500 501 502 503
             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
504
The following three functions show an example of how a basic SIP
Pekka Pessi's avatar
Pekka Pessi committed
505 506
call is created.

Pekka Pessi's avatar
Pekka Pessi committed
507
The place_a_call() function creates an operation handle and invokes the
Pekka Pessi's avatar
Pekka Pessi committed
508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541
SIP INVITE method.

@code
void place_a_call(void)
{
  oper_ctx_t *oper_ctx;

  /* create operation context information */
  oper_ctx = su_zalloc(app_ctx->home, sizeof(oper_ctx_t));
  if (oper_ctx = NULL) {
    printf("cannot create operation context information\n");
    return;
  }

  /* how we create destination_address? */

  /* create operation handle */
  oper_ctx->handle = nua_handle(app_ctx->nua,
                                oper_ctx,
                                NUTAG_URL(destination_address),
                                TAG_END());

  if (oper_ctx->handle == NULL) {
    printf("cannot create operation handle\n");
    return;
  }

  nua_invite(oper_ctx->handle,
              /* other tags as needed ... */
              TAG_END());

} /* place_a_call */
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
542 543
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
544 545 546
is not enabled so ACK response must be sent explicitly.

@code
Pekka Pessi's avatar
Pekka Pessi committed
547
void app_r_invite(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
548
                  char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
549
                  nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
550
                  nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
551
                  nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
552 553 554 555 556 557 558 559 560 561 562 563 564
                  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

Pekka Pessi's avatar
Pekka Pessi committed
565
The app_i_active() function is called by callback function when call has
Pekka Pessi's avatar
Pekka Pessi committed
566 567 568
been successfully set up and the media has been activated.

@code
Pekka Pessi's avatar
Pekka Pessi committed
569
void app_i_active(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
570
                  char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
571
                  nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
572
                  nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
573
                  nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
574 575 576 577 578 579 580 581 582 583 584
                  nua_hmagic_t *hmagic,
                  sip_t const  *sip,
                  tagi_t        tags[])
{
  printf("call active\n");

} /* app_i_active */
@endcode

@subsection nua_receiveacall Receive a call

Pekka Pessi's avatar
Pekka Pessi committed
585 586
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
587 588 589
not enabled so the response must be sent explicitly.

@code
Pekka Pessi's avatar
Pekka Pessi committed
590
void app_i_invite(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
591
                  char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
592
                  nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
593
                  nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
594
                  nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
595 596 597 598 599 600 601 602 603 604 605
                  nua_hmagic_t *hmagic,
                  sip_t const  *sip,
                  tagi_t        tags[])
{
  printf("incoming call\n");

  nua_respond(nh, 200, "OK", TAG_END());

} /* app_i_invite */
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
606
The app_i_active() function is called by the callback function when call has
Pekka Pessi's avatar
Pekka Pessi committed
607 608 609
been successfully set up and the media has been activated.

@code
Pekka Pessi's avatar
Pekka Pessi committed
610
void app_i_active(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
611
                   char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
612
                   nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
613
                   nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
614
                   nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
615 616 617 618 619 620 621 622 623 624 625
                   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
626
The following three functions show an example of how a basic SIP
Pekka Pessi's avatar
Pekka Pessi committed
627 628 629 630 631 632 633 634 635 636 637 638
call is terminated.

The terminate_call() function sends the SIP BYE message.

@code
void terminate_call(void)
{
  nua_bye(oper_ctx->handle, TAG_END());

} /* terminate call */
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
639 640
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
641 642 643
releases the memory allocated to operation context information.

@code
Pekka Pessi's avatar
Pekka Pessi committed
644
void app_r_bye(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
645
               char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
646
               nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
647
               nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
648
               nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
649 650 651 652 653
               nua_hmagic_t *hmagic,
               sip_t const  *sip,
               tagi_t        tags[])
{
  if (status < 200)
Pekka Pessi's avatar
Pekka Pessi committed
654
     return;
Pekka Pessi's avatar
Pekka Pessi committed
655 656 657 658 659 660 661 662 663 664 665 666 667

  printf("call released\n");

  /* release operation handle */
  nua_handle_destroy(hmagic->handle);
  oper_ctx->handle = NULL;

  /* release operation context information */
  su_free(app_ctx->home, hmagic);

} /* app_r_bye */
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
668 669
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
670 671 672
the memory allocated to operation context information.

@code
Pekka Pessi's avatar
Pekka Pessi committed
673
void app_i_bye(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
674
               char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
675
               nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
676
               nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
677
               nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734
               nua_hmagic_t *hmagic,
               sip_t const  *sip,
               tagi_t        tags[])
{
  printf("call released\n");

  /* release operation handle */
  nua_handle_destroy(hmagic->handle);
  oper_ctx->handle = NULL;

  /* release operation context information */
  su_free(app_ctx->home, hmagic);

} /* 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)
{
  oper_ctx_t *oper_ctx;

  /* create operation context information */
  oper_ctx = su_zalloc(app_ctx->home, sizeof(oper_ctx_t));
  if (oper_ctx = NULL) {
    printf("cannot create operation context information\n");
    return;
  }

  /* how we create destination_address? */

  /* create operation handle */
  oper_ctx->handle = nua_handle(app_ctx->nua,
                                oper_ctx,
                                NUTAG_URL(destination_address),
                                TAG_END());

  if (oper_ctx->handle == NULL) {
    printf("cannot create operation handle\n");
    return;
  }

  /* send MESSAGE */
  nua_message(oper_ctx->handle,
               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
735
The app_r_message() function is called by the callback function when
Pekka Pessi's avatar
Pekka Pessi committed
736 737 738
answer to the MESSAGE is received.

@code
Pekka Pessi's avatar
Pekka Pessi committed
739
void app_r_message(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
740
                    char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
741
                    nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
742
                    nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
743
                    nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
744 745 746 747 748 749 750 751 752 753 754 755
                    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
756
The app_i_message() function is called by the callback function when
Pekka Pessi's avatar
Pekka Pessi committed
757 758 759
a SIP MESSAGE is received.

@code
Pekka Pessi's avatar
Pekka Pessi committed
760
void app_i_message(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
761
                   char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
762
                   nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
763
                   nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
764
                   nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
765 766 767 768 769 770
                   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
771 772
  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
773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788
         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

@subsection nua_shutting_down Shutdown

Pekka Pessi's avatar
Pekka Pessi committed
789
The following functions show an example of how application terminates
Pekka Pessi's avatar
Pekka Pessi committed
790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805
the NUA stack.

The shutdown() function starts the termination.

@code
void shutdown(void)
{
  nua_shutdown(app_ctx->nua);

} /* 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
806
void app_r_shutdown(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
807
                    char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
808
                    nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
809
                    nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
810
                    nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829
                    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

*/

Pekka Pessi's avatar
Pekka Pessi committed
830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852
/** @page nua_call_model NUA Call Model

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

In the figure below, a simplified state diagram for a SIP call is
presented. The application will receive an #nua_i_state event indicating
change in call state after it has occurred. The states in NUA call model are
represented by @e enum #nua_callstate, and the current value of state is
included in tag NUTAG_CALLSTATE() with the #nua_i_state event.

The SDP Offer/Answer negotiation status is also included in the event. The
#nua_i_state event is not sent, however, if the change is invoked by by
application calling API functions like nua_bye(), and there is no change in
SDP offer/answer status.

@code
                    +---------------+
             +------|     INIT      |-----+
    INVITE/- |      +---------------+     | INVITE/100
             V                            |
       +------------+               +------------+
853 854 855 856 857 858 859
  +----|  CALLING   |--+        +---|  RECEIVED  |--+
  |    +------------+  |        |   +------------+  |
  |          |         |        |         |         |
  |          | 18X/-   |        |         | -/18X   |
  |          V         |        |         V         |
  |    +------------+  |        |   +------------+  |
  |<---| PROCEEDING |  |        |   |   EARLY    |->|
Pekka Pessi's avatar
Pekka Pessi committed
860
  |    +------------+  |        |   +------------+  |  -/[3456]XX
861 862
  |          |         |        |         |         |
  |          | 2XX/-   | 2XX/-  | -/2XX   | -/2XX   |    or
Pekka Pessi's avatar
Pekka Pessi committed
863 864
  |          V         |        |         V         |
  |    + - - - - - -+  |        |   +------------+  |  CANCEL/200,487
865 866 867 868 869 870 871 872
  |    : COMPLETING :<-+        +-->|  COMPLETE  |  |
  |    + - - - - - -+               +------------+  |
  |          |                            |         |
  |          | -/ACK                ACK/- |         |
  |          |                            |         |
  |          |                            |         |
  |          |      +---------------+     |         |
  |          +----->|     READY     |<----+         |
Pekka Pessi's avatar
Pekka Pessi committed
873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888
  |                 +---------------+               |
  |                   |           |                 |
  |          BYE/200  |           | -/BYE           |
  |                   |           |                 |
  |                   |           V                 |
  |                   |   +--------------+          |
  | [3456]XX/ACK      |   | TERMINATING  |          |
  |                   |   +--------------+          |
  |                   |           |                 |
  |                   |           | [23456]XX/-     |
  |                   V           V                 |
  |                 +---------------+               |
  +---------------->|  TERMINATED   |<--------------+
                    +---------------+
@endcode

Pekka Pessi's avatar
Pekka Pessi committed
889 890 891 892 893 894 895 896 897
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>).

Pekka Pessi's avatar
Pekka Pessi committed
898 899 900 901 902 903
@par Detailed Client Call Model

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

@code
904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962
            +------------+
            |    INIT    |
            +------------+
                  |
                 (1) nua_invite/INVITE
                  |
                  V
            +------------+
            |            |---------------------------------------+
            |            |----+                                  |
     +------|  CALLING   |  (7a) nua_cancel/CANCEL               |
     |      |            |<---+                                  |
     |      |            |                                       |
     |      +------------+                                       |
     |            |                                              |
     |           (2) 18X/-                                       |
     |            |                                              |
     |            V                                              |
     |      +------------+                                       |
     |      |            |-------------------------------------->|
     |      |            |----+                                  |
     |      | PROCEEDING |  (7b) nua_cancel/CANCEL               |
     |      |            |<---+                                  |
     |      |            |----------------------+                |
     |      +------------+                      |                |
     |            |                             |                |
   (3b) 2XX/-   (3a) 2XX/-                      |               (6) [3456]XX/ACK
     |            |                             |                |
     |            V                             |                |
     |      + - - - - - -+                      |                |
     +----->:            :                      |                |
            : COMPLETING :-------+              |                |
     + - - -:            :       |              |                |
     :      + - - - - - -+       |              |                |
     :     	  |         	 |              |                |
     :<auto_ack>  |         	 |              |                |
     :or nua_ack  | <auto_ack>   |              |                |
     :and media   | or nua_ack   | nua_bye      |                |
    (5) error 	 (4) /ACK   	(9) /ACK+BYE   (8) nua_bye/BYE   |
     : /ACK+BYE	  |         	 |              |                |
     :     	  V         	 |              |                |
     :      +------------+       |              |                |
     :      |            |       |              |                |
     :      |   READY    |       |              |                |
     :      |            |       |              |                |
     :      +------------+       |              |                |
     :                           |              |                |
     |                           |              |                |
     :                           |              |                |
     :      +-------------+      |              |                |
     + - - >| TERMINATING |<-----+<-------------+                |
            +-------------+                                      |
                  |                                              |
                  | [23456]XX/-                                  |
                  |                                              |
                  V                                              |
            +------------+                                       |
            | TERMINATED |<--------------------------------------+
            +------------+
Pekka Pessi's avatar
Pekka Pessi committed
963 964 965 966 967
@endcode

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

968 969
<table>
<tr><th>#</th>
Pekka Pessi's avatar
Pekka Pessi committed
970 971 972 973
    <th>Previous state</th>
    <th>Input</th>
    <th>Output</th>
    <th>Next state</th>
974 975 976
    <th>Offer/ Answer</th>
    <th align="left">Description</th>
</tr>
977
<tr><td>C1</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
978 979 980 981 982 983
    <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>
984
   Client application starts call be invoking nua_invite(). By default, stack runs
Pekka Pessi's avatar
Pekka Pessi committed
985 986
   the initial offer/answer step and sends @b INVITE request with the SDP
   offer.
987
</td></tr>
988
<tr><td>C2</td>
989 990 991
    <td>calling</td><td>18X</td><td>-</td><td>proceeding</td>
    <td>(Save answer)</td>
  <td>
Pekka Pessi's avatar
Pekka Pessi committed
992 993 994 995 996
   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.
997
</td></tr>
998
<tr><td>C3a</td>
999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010
    <td>proceeding</td><td rowspan="2">2XX</td>
    <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>
1011
<tr><td>C3b</td>
1012
    <td>calling</td></tr>
1013
<tr><td>C4</td>
1014 1015 1016 1017 1018 1019 1020 1021 1022 1023
    <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>
1024
<tr><td>C5</td>
1025 1026 1027 1028 1029 1030 1031 1032 1033 1034
    <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>
   If there was an failure in SDP negotiation or other failure with media,
   the stack will automatically terminate the call. The BYE follows
   immediatelhy after the ACK.
</td></tr>
1035
<tr><td>C6a</td>
1036 1037 1038 1039 1040 1041
    <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>
Pekka Pessi's avatar
Pekka Pessi committed
1042 1043 1044 1045
   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.
1046
</td></tr>
1047 1048 1049 1050
<tr><td>C6b</td>
    <td>proceeding</td>
</tr>
<tr><td>C7a</td>
1051 1052 1053 1054 1055 1056
    <td>calling</td>
    <td rowspan=2>nua_cancel()</td>
    <td rowspan=2>CANCEL</td>
    <td>calling</td>
    <td rowspan=2>-</td>
    <td rowspan=2>
Pekka Pessi's avatar
Pekka Pessi committed
1057 1058 1059 1060 1061
   Client can ask server to cancel the call attempt while in in @b calling
   or @b proceeding state. There is no direct call state transition caused
   by nua_cancel(). However, the server will return a <i>487 Request
   Terminated</i> response when receiving CANCEL and call is terminated as in
   previous item.
1062
</td></tr>
1063
<tr><td>C7b</td>
1064 1065
    <td>proceeding</td>
    <td>proceeding</td></tr>
1066
<tr><td>C8</td>
1067 1068 1069 1070 1071 1072 1073 1074 1075 1076
    <td>proceeding</td>
    <td>nua_bye()</td>
    <td>BYE</td>
    <td>terminating</td>
    <td>-</td>
    <td>
   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.
</td></tr>
1077
<tr><td>C9</td>
1078 1079 1080 1081
    <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
Pekka Pessi's avatar
Pekka Pessi committed
1082
   received 2XX response), it will have to @b ACK the final response, too.
1083 1084
</td></tr>
</table>
Pekka Pessi's avatar
Pekka Pessi committed
1085 1086 1087 1088 1089 1090 1091 1092

@par Detailed Server-Side Call Model

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

@code

Pekka Pessi's avatar
Pekka Pessi committed
1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116
                           +----------------------------------+
                           |                INIT              |
                           +----------------------------------+
                             |              :               :
                             |              :               :
                            (1) INVITE/100 (2b) INVITE/18X (3c) INVITE/2XX
                             |              :               :
                             |              :               :
                             V              :               :
                          +------------+    :               :
     +--------------------|            |    :               :
     |                    |  RECEIVED  |--------------+     :
     |    +---------------|            |    :         |     :
     |    |               +------------+    :         |     :
     |    |                           |     :         |     :
     |    |          nua_respond/18X (2)    :         |     :
     |    |                           |     :         |     :
     |    |                           V     V         |     :
     |    |                          +------------+   |     :
     |<------------------------------|            |   |     :
     |    |<-------------------------|    EARLY   |   |     :
     |    |               +----------|            |   |     :
     |    |               |          +------------+   |     :
     | nua_respond/       |                     |     |     :
1117
    (6) /[3456]XX         |    nua_respond/2XX (3a)  (3b)   :
Pekka Pessi's avatar
Pekka Pessi committed
1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134
     |    |               |                     |     |     :
     |    |               |                     V     V     V
     |    |               |                    +-------------+
     |    |               |                    |             |
     |    |               |              +-----|  COMPLETED  |- - +
     |    |               |              |     |             |    :
     |    |               |              |     +-------------+    :
     |    |               |              |            |           :
     |    |               |              |           (4) ACK/-    :
     |    |               |              |            |           :
     |    |               |              |            V           :
     |    |               |              |     +-------------+    :
     |    |               |              |     |             |    :
     |    |               |              |     |    READY    |    :
     |    |               |              |     |             |    :
     |    |               |              |     +-------------+    :
     |    |               |              |                        :
1135
     |   (7) CANCEL/487  (8) BYE/487    (9) BYE/200              (5) timeout/BYE
Pekka Pessi's avatar
Pekka Pessi committed
1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146
     |    |               |              |                        :
     |    |               |              |     +-------------+    :
     |    |               |              |     | TERMINATING |<- -+
     |    |               |              |     +-------------+
     |    |               |              |            |
     |    |               |              |            | [23456]XX/-
     |    |               |              |            |
     |    |               |              |            V
     |    V               V              V     +-------------+
     +---------------------------------------->| TERMINATED  |
                                               +-------------+
Pekka Pessi's avatar
Pekka Pessi committed
1147 1148 1149 1150
@endcode

The detailed description of state transitions on the server side is as
follows:
Pekka Pessi's avatar
Pekka Pessi committed
1151 1152 1153 1154 1155 1156 1157 1158 1159
<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>
1160 1161 1162 1163 1164 1165
<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
1166
    <td>
Pekka Pessi's avatar
Pekka Pessi committed
1167 1168 1169
   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
1170 1171
   offer included in @b INVITE and passes it to the application.
</td></tr>
1172
<tr><td>S2a</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1173 1174 1175 1176
    <td>received</td>			<!-- previous state -->
    <td>nua_respond()</td>		<!-- input -->
    <td>18X</td>			<!-- output -->
    <td rowspan=2>early</td>		<!-- next state -->
1177
    <td>(Generate early answer)</td>	<!-- offer/answer -->
Pekka Pessi's avatar
Pekka Pessi committed
1178
    <td>
Pekka Pessi's avatar
Pekka Pessi committed
1179 1180 1181 1182 1183
   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
1184
</td></tr>
1185 1186 1187
<tr><td>S2b</td>			<!-- transition -->
    <td>init</td>			<!-- previous state -->
    <td>INVITE and			<!-- input -->
Pekka Pessi's avatar
Pekka Pessi committed
1188
        @ref NUTAG_AUTOALERT() "auto-alert"</td>
1189
    <td>180 Ringing</td>		<!-- output -->
Pekka Pessi's avatar
Pekka Pessi committed
1190 1191 1192
    <td>Save offer (and
        generate early answer)</td>	<!-- offer/answer -->
    <td>
1193
    When @ref NUTAG_AUTOALERT() "auto-alert" option is enabled, stack sends
Pekka Pessi's avatar
Pekka Pessi committed
1194 1195
    180 Ringing immediately after receiving INVITE and enters @b early state.
</td></tr>
1196
<tr><td>S3a</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1197 1198 1199 1200 1201 1202
    <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=2>Generate answer</td>	<!-- offer/answer -->
    <td rowspan=2>
Pekka Pessi's avatar
Pekka Pessi committed
1203 1204 1205 1206
   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
1207
</td></tr>
1208
<tr><td>S3b</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1209 1210
    <td>received</td>			<!-- previous state -->
</td></tr>
1211 1212
<tr><td>S3c</td>			<!-- transition -->
    <td>init</td>			<!-- previous state -->
Pekka Pessi's avatar
Pekka Pessi committed
1213
    <td>INVITE and @ref NUTAG_AUTOANSWER() "auto-answer"
1214 1215
    </td>				<!-- input -->
    <td>200 OK</td>			<!-- output -->
Pekka Pessi's avatar
Pekka Pessi committed
1216
    <td>Save offer and
1217
    <br>generate answer</td>		<!-- offer/answer -->
Pekka Pessi's avatar
Pekka Pessi committed
1218 1219 1220 1221 1222
    <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>
1223 1224 1225 1226 1227 1228
<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
1229 1230
    <td>
   The ready state is entered at server side after receiving @b ACK request
Pekka Pessi's avatar
Pekka Pessi committed
1231 1232
   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
1233
</td></tr>
1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244
<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
1245 1246 1247 1248 1249 1250 1251
    <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
Pekka Pessi's avatar
Pekka Pessi committed
1252 1253 1254
   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
1255
</td></tr>
1256
<tr><td>S6b</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1257 1258
    <td>early</td>			<!-- previous state -->
</td></tr>
1259
<tr><td>S7a</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1260 1261 1262 1263 1264 1265
    <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>
Pekka Pessi's avatar
Pekka Pessi committed
1266 1267 1268 1269
   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
1270
</td></tr>
1271
<tr><td>S7b</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1272 1273
    <td>early</td>			<!-- previous state -->
</td></tr>
1274
<tr><td>S8</td>				<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1275 1276 1277 1278 1279 1280 1281
    <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>
Pekka Pessi's avatar
Pekka Pessi committed
1282 1283 1284 1285
   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
1286
</td></tr>
1287
<tr><td>S9</td>				<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1288 1289 1290 1291 1292 1293
    <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>
Pekka Pessi's avatar
Pekka Pessi committed
1294 1295 1296 1297
   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
1298 1299 1300 1301 1302 1303 1304 1305
</td></tr>
</table>

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.

1306
@code
Pekka Pessi's avatar
Pekka Pessi committed
1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320
	A		        C		        B
	|			|			|
	|<-------INVITE---------|			|
	|			|			|
	|			|			|
	|------200 (offer)----->|  	  		|
	|			|----INVITE (offer)---->|
	|			|			|
	|			|			|
	|			|<-----200 (answer)-----|
	|<-----ACK (answer)-----|			|
	|			|     			|
	|			|----------ACK--------->|
	|			|			|
1321
@endcode
Pekka Pessi's avatar
Pekka Pessi committed
1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335

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>
1336 1337 1338 1339 1340 1341
<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
1342 1343 1344
    <td>
    There is no SDP to save.
</td></tr>
1345 1346 1347
<tr><td>S2b'</td>			<!-- transition -->
    <td>init</td>			<!-- previous state -->
    <td>INVITE and			<!-- input -->
Pekka Pessi's avatar
Pekka Pessi committed
1348
        @ref NUTAG_AUTOALERT() "auto-alert"</td>
1349 1350 1351
    <td>180 Ringing</td>		<!-- output -->
    <td>early</td>			<!-- next state -->
    <td>-</td>				<!-- offer/answer -->
Pekka Pessi's avatar
Pekka Pessi committed
1352 1353 1354
    <td>
    There is no SDP to save.
</td></tr>
1355
<tr><td>S3a</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1356 1357 1358 1359 1360 1361 1362 1363
    <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>
1364
<tr><td>S3b'</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1365 1366
    <td>received</td>			<!-- previous state -->
</td></tr>
1367 1368 1369
<tr><td>S3c'</td>			<!-- transition -->
    <td>init</td>			<!-- previous state -->
    <td>INVITE and			<!-- input -->
Pekka Pessi's avatar
Pekka Pessi committed
1370
        @ref NUTAG_AUTOANSWER() "auto-answer"</td>
1371
    <td>200 OK</td>			<!-- output -->
Pekka Pessi's avatar
Pekka Pessi committed
1372
</td></tr>
1373 1374 1375 1376 1377
<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
1378 1379 1380 1381
    <td>Save and process answer</td>	<!-- offer/answer -->
    <td>
    The answer is processed and media activated after receiving @b ACK.
</td></tr>
1382
<tr><td>S9b'</td>			<!-- transition -->
Pekka Pessi's avatar
Pekka Pessi committed
1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394
    <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>

Pekka Pessi's avatar
Pekka Pessi committed
1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411

@par Model for Modifying and Terminating Call

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

A session can be terminated with a @b BYE request at any time.

If any in-dialog request fail with certain response codes, the session can
be considered terminated, too. These response codes are documented with
sip_response_terminates_dialog(). In some cases, the session should be
terminated gracefully by sending a @b BYE request.


1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497
@code
    +-------------------------------------------------------------+
    |                            READY                            |
    +-------------------------------------------------------------+
      |           |                |		    |
      |           |                |		    |
     (1) BYE/200 (2) nua_bye/BYE  (4) graceful/BYE (5) final/BYE
      |           |		   |     	    |
      |           V		   V     	    |
      |     +-----------------------------+         |
      |     |         TERMINATING         |         |
      |     +-----------------------------+	    |
      |                    |			    |
      |                   (3) [23456]XX/-	    |
      |                    |			    |
      V                    V			    V
    +-------------------------------------------------------------+
    |                         TERMINATED                          |
    +-------------------------------------------------------------+
@endcode

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

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

Pekka Pessi's avatar
Pekka Pessi committed
1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547
*/

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

*/
/**@var nua_event_e
Pekka Pessi's avatar
Pekka Pessi committed
1548 1549 1550 1551
 *
 * @brief Events
 *
 * The NUA event loop calls an event callback function when an application
Pekka Pessi's avatar
Pekka Pessi committed
1552 1553
 * needs to act on something that happened in the Sofia stack. The callback
 * function is registered when nua_create() function call is used to create
Pekka Pessi's avatar
Pekka Pessi committed
1554 1555 1556 1557 1558
 * the NUA stack object.
 *
 * The prototype of the event callback function is:
 * @code
 * void nua_callback_f(nua_event_t   event,
Pekka Pessi's avatar
Pekka Pessi committed
1559
 *                     int           status,
Pekka Pessi's avatar
Pekka Pessi committed