nua.docs 59.7 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 47 48 49 50 51 52 53 54 55 56
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
Sofia system utility library (<a href="../su/index.html"><b>su</b></a>)
providing unified interface to certain OS services and utilities.

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 59 60
description of the SU services.

@subsection nua_root Root object

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 94
The magic is a term used for the context information that can be connected
to various entities in Sofia stack (for example root object and operation
handle) by the application code. This context information is passed back
to the application code when the registered callback function is called by
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 162 163 164 165 166 167
as parameter.

The following is an example of call to NUA function containing tagged values:
@code
nua_unregister(op->op_handle,
               TAG_IF(registrar, NUTAG_REGISTRAR(registrar)),
               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 259
        with tl_gets() function to retrieve tag values from tag list.

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

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

Pekka Pessi's avatar
Pekka Pessi committed
270
For example:
Pekka Pessi's avatar
Pekka Pessi committed
271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295

sending a SUBSCRIBE with Event: header and two Accept: headers:

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

fetching tag values when processing nua_r_subscribe event:

@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
296
This section describes basic usage scenarios of NUA/Sofia stack using
Pekka Pessi's avatar
Pekka Pessi committed
297 298 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
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
335 336
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
337 338
all relevant details of the basic use of NUA.

Pekka Pessi's avatar
Pekka Pessi committed
339
The source distribution of Sofia stack contains in directory nua an example
Pekka Pessi's avatar
Pekka Pessi committed
340 341 342 343
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
344 345
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
346 347 348 349 350 351 352 353 354 355 356 357
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
358
The information area contents themselves can be defined as
Pekka Pessi's avatar
Pekka Pessi committed
359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376
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
377
  struct
Pekka Pessi's avatar
Pekka Pessi committed
378 379 380 381 382 383 384 385 386
  {
    nua_handle_t  *handle;  /* operation handle /
    ...                     /* call-related information */
  } call;

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

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

@subsection nua_initanddeinit Initialization and deinitialization

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

Pekka Pessi's avatar
Pekka Pessi committed
401 402 403 404
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
405 406 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
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
434
    /* enter main loop for processing of messages */
Pekka Pessi's avatar
Pekka Pessi committed
435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454
    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
455 456 457 458
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
459 460 461 462
incoming events for processing to separate functions.

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

Pekka Pessi's avatar
Pekka Pessi committed
505
The place_a_call() function creates an operation handle and invokes the
Pekka Pessi's avatar
Pekka Pessi committed
506 507 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
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
540 541
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
542 543 544
is not enabled so ACK response must be sent explicitly.

@code
Pekka Pessi's avatar
Pekka Pessi committed
545
void app_r_invite(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
546
                  char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
547
                  nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
548
                  nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
549
                  nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
550 551 552 553 554 555 556 557 558 559 560 561 562
                  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
563
The app_i_active() function is called by callback function when call has
Pekka Pessi's avatar
Pekka Pessi committed
564 565 566
been successfully set up and the media has been activated.

@code
Pekka Pessi's avatar
Pekka Pessi committed
567
void app_i_active(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
568
                  char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
569
                  nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
570
                  nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
571
                  nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
572 573 574 575 576 577 578 579 580 581 582
                  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
583 584
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
585 586 587
not enabled so the response must be sent explicitly.

@code
Pekka Pessi's avatar
Pekka Pessi committed
588
void app_i_invite(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
589
                  char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
590
                  nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
591
                  nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
592
                  nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
593 594 595 596 597 598 599 600 601 602 603
                  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
604
The app_i_active() function is called by the callback function when call has
Pekka Pessi's avatar
Pekka Pessi committed
605 606 607
been successfully set up and the media has been activated.

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

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

  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
666 667
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
668 669 670
the memory allocated to operation context information.

@code
Pekka Pessi's avatar
Pekka Pessi committed
671
void app_i_bye(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
672
               char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
673
               nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
674
               nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
675
               nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
676 677 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
               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
733
The app_r_message() function is called by the callback function when
Pekka Pessi's avatar
Pekka Pessi committed
734 735 736
answer to the MESSAGE is received.

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

@code
Pekka Pessi's avatar
Pekka Pessi committed
758
void app_i_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
                   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
769 770
  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
771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786
         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
787
The following functions show an example of how application terminates
Pekka Pessi's avatar
Pekka Pessi committed
788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803
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
804
void app_r_shutdown(int           status,
Pekka Pessi's avatar
Pekka Pessi committed
805
                    char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
806
                    nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
807
                    nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
808
                    nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827
                    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

*/

828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 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 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182
/** @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.

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>).

@code
                    +---------------+
             +------|     INIT      |-----+
    INVITE/- |      +---------------+     | INVITE/100
             V                            |
       +------------+               +------------+
  +----|  CALLING   |           +---|  RECEIVED  |--+
  |    +------------+           |   +------------+  |
  |          |                  |         |         |
  |          | 18X/-            |         | -/18X   |
  |          V                  |         V         |
  |    +------------+           |   +------------+  |
  |<---| PROCEEDING |--+        |   |   EARLY    |->|
  |    +------------+  |        |   +------------+  |  -/[3456]XX
  |          :         |        |         |         |
  |          |  2XX/-  |        |  -/2XX  |  -/2XX  |    or
  |          V         |        |         V         |
  |    + - - - - - -+  |        |   +------------+  |  CANCEL/200,487
  |    : COMPLETING :  |        +-->|  COMPLETE  |  |
  |    + - - - - - -+  |            +------------+  |
  |          :         |                  |         |
  |          | -/ACK   |  2XX/ACK   ACK/- |         |
  |          :         |                  |         |
  |          :         V                  |         |
  |          :      +---------------+     |         |
  |          + - - >|     READY     |<----+         |
  |                 +---------------+               |
  |                   |           |                 |
  |          BYE/200  |           | -/BYE           |
  |                   |           |                 |
  |                   |           V                 |
  |                   |   +--------------+          |
  | [3456]XX/ACK      |   | TERMINATING  |          |
  |                   |   +--------------+          |
  |                   |           |                 |
  |                   |           | [23456]XX/-     |
  |                   V           V                 |
  |                 +---------------+               |
  +---------------->|  TERMINATED   |<--------------+
                    +---------------+
@endcode

@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
                        +------------+
                        |    INIT    |
                        +------------+
                              |
                             (1) nua_invite/INVITE
                              |
                              V
                        +------------+
                        |            |- - +
    +-------------------|  CALLING   |   (8) nua_cancel/CANCEL
    |                   |            |<- -+
    |                   +------------+
    |                         |
    |                        (2) 18X/-
    |                         |
    |                         V
    |                   +------------+
    |                   |            |- - +
    |                   |            |   (8) nua_cancel/CANCEL
    |<------------------| PROCEEDING |<- -+
    |                   |            |
    |                   |            |- - - - - -+
    |                   +------------+           :
    |                    :          |            :
   (7) [3456]XX/ACK     (5) 2XX/-  (3) 2XX/ACK  (9) nua_bye/BYE
    |                    :          |            :
    |                    V          |            :
    |              + - - - - - -+   |            :
    |     + - - - -: COMPLETING :  (X) - +       :
    |     :        + - - - - - -+   |    :       :
    |     :              :          |    :       :
    |     : nua_ack      : nua_ack  |    :       :
    |    (9) /ACK+BYE   (6) /ACK    |    :       :
    |     :              :          |    :       :
    |     :             (X)- - - - -|- - +       :
    |     :              :          |    :       :
    |     :              V          V    :       :
    |     :             +------------+   :       :
    |     :             |            |   :       :
    |     :             |   READY    |  (4)-/BYE :
    |     :             |            |   :       :
    |     :             +------------+   :       :
    |     :          		         :       :
    |     :          		         :       :
    |     :          		         :       :
    |     :          		         V       V
    |     :          		      +-------------+
    |     + - - - - - - - - - - - - ->| TERMINATING |
    |                		      +-------------+
    |                		             |
    |                		             | [23456]XX/-
    |                		             |
    |                		             |
    |                   +------------+       |
    +------------------>| TERMINATED |<------+
                        +------------+
@endcode

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

-# Entering @b calling state: \n
   Client application invokes nua_invite(). By default, stack runs
   the initial offer/answer step and sends @b INVITE request with the SDP
   offer.
-# Entering @b proceeding state: \n
   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.
-# Entering @b ready state: \n
   Client receives a 2XX response (usually <i>200 OK</i>) and sends an
   ACK request. If the initial offer was sent with INVITE, the answer must
   be included with 2XX response at latest. If the client has not received
   the SDP answer, it sends immediately a BYE request after sending the ACK
   request and enters the @b terminating state.
-# Error entering @b ready state: \n
   If there is an failure entering the @b ready state (because of SDP
   negotiation or media failure), the stack will automatically terminate the
   call by sending the BYE request towards the server.
-# Entering @b completing state: \n
   Client receives 2XX series response (usually <i>200 OK</i>) and forwards
   it to the application. This state transition happens only when the
   @ref NUTAG_AUTOACK() "auto-ack"
   mode is explicitly turned off by application.
-# Entering @b ready state: \n
   Client completes offer/answer exchange and sends the ACK request to the
   server.
-# Entering @b terminated state: \n
   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.
-# Canceling call in @b calling or @b proceeding state: \n
   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.
-# Entering @b terminated state: \n
   Call can be terminated by sending a @b BYE request after entering
   proceeding state. If the stack is in @b completing state (it has already
   received 2XX response), it will have to @b ACK the final response, too.

@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

                     +--------------------------------+
                     |              INIT              |
                     +--------------------------------+
                       |              :             :
                       |              :             :
                      (1) INVITE/100  :             :
                       |              :             :
                       |              :             :
                       V              :             :
                    +------------+    :             :
                    |            |    :             :
     +--------------|  RECEIVED  |    :             :
     |              |            |    :             :
     |              +------------+    :             :
     |                          |     :             :
     |         nua_respond/18X (2)  (2b) INVITE/18X :
     |                          |     :             :
     |                          V     V             :
     |                         +------------+       :
     |<------------------------|            |       :
     |                         |    EARLY   |       :
     |              +----------|            |       :
     |              |          +------------+       :
     | nua_respond/ |                      |        :
    (5) /[3456]XX   |     nua_respond/2XX (3)     (3b) INVITE/2XX
     |              |                      |        :
     |              |                      V        V
     |              |                   +-------------+
     |              |                   |             |
     |              |             +-----|   COMPLETE  |- - +
     |              |             |     |             |    :
     |              |             |     +-------------+    :
     |              |             |            |           :
    (6) CANCEL/487 (7) BYE/487    |           (4) ACK/-    :
     |              |             |            |           :
     |              |             |            V           :
     |              |             |     +-------------+    :
     |              |             |     |             |    :
     |              |             |     |    READY    |    :
     |              |             |     |             |    :
     |              |             |     +-------------+    :
     |              |             |                        :
     |              |            (8) BYE/200              (9) timeout/BYE
     |              |             |                        :
     |              |             |     +-------------+    :
     |              |             |     | TERMINATING |<- -+
     |              |             |     +-------------+
     |              |             |            |
     |              |             |            | [23456]XX/-
     |              |             |            |
     |              |             |            V
     |              V             V     +-------------+
     +--------------------------------->| TERMINATED  |
                                        +-------------+
@endcode

The detailed description of state transitions on the server side is as
follows:
-# Entering @b received state: \n
   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
   offer included in @b INVITE and passes it to the application. (Optionally,
   the stack can return with 18X or 2XX response immediately and enter)
-# Entering @b early state: \n
   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.
-# Entering @b complete state: \n
   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.
-# Entering @b ready state: \n
   The ready state is entered at server side after receiving ACK request
   from client, indicating that the client have received server's 2XX
   response. The call is ready, the @b INVITE transaction is confirmed.
-# Entering @b terminating state: \n
   The server rejects the call by sending a 3XX, 4XX, 5XX, or 6XX response
   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.
-# Entering @b terminating state after receiving @b CANCEL: \n
   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.
-# Entering @b terminated state after receiving @b BYE: \n
   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.
-# Entering @b terminated state by receiving @b BYE before @b ACK: \n
   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.
-# Entering @b terminating state after a timeout: \n
   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.

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


*/

/*
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
1183 1184 1185 1186
 *
 * @brief Events
 *
 * The NUA event loop calls an event callback function when an application
Pekka Pessi's avatar
Pekka Pessi committed
1187 1188
 * 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
1189 1190 1191 1192 1193
 * 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
1194
 *                     int           status,
Pekka Pessi's avatar
Pekka Pessi committed
1195
 *                     char const   *phrase,
Pekka Pessi's avatar
Pekka Pessi committed
1196
 *                     nua_t        *nua,
Pekka Pessi's avatar
Pekka Pessi committed
1197
 *                     nua_magic_t  *magic,
Pekka Pessi's avatar
Pekka Pessi committed
1198
 *                     nua_handle_t *nh,
Pekka Pessi's avatar
Pekka Pessi committed
1199 1200 1201 1202
 *                     nua_hmagic_t *hmagic,
 *                     sip_t const  *sip,
 *                     tagi_t        tags[]);
 * @endcode
Pekka Pessi's avatar
Pekka Pessi committed
1203
 *
Pekka Pessi's avatar
Pekka Pessi committed
1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218
 * @param event  Callback event identification. \n
 *               Always present
 * @param status Protocol status code. \n
 *               Always present
 * @param phrase Text corresponding to status code. \n
 *               Always present
 * @param nua    Pointer to NUA stack object. \n
 *               Always present
 * @param magic  Pointer to callback context from nua_create(). \n
 *               Always present
 * @param nh     Pointer to operation handle.
 * @param hmagic Pointer to callback context from nua_handle().
 * @param sip    Parsed incoming message.
 * @param tags   Tag list containing more information about the state of NUA.
 *
Pekka Pessi's avatar
Pekka Pessi committed
1219 1220
 * Note that the contents of the last four parameters vary depending on
 * the event. The descriptions can be found from the description of the
Pekka Pessi's avatar
Pekka Pessi committed
1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240
 * individual event.
 *
 * The events can be divided into the following categories: \n
 * @par Indications:
 * #nua_i_active           \n
 * #nua_i_bye              \n
 * #nua_i_cancel           \n
 * #nua_i_chat             \n
 * #nua_i_error            \n
 * #nua_i_fork             \n
 * #nua_i_info             \n
 * #nua_i_invite           \n
 * #nua_i_media_error      \n
 * #nua_i_message          \n
 * #nua_i_method           \n
 * #nua_i_notify           \n
 * #nua_i_options          \n
 * #nua_i_publish          \n
 * #nua_i_refer            \n
 * #nua_i_subscribe        \n
1241
 * #nua_i_state            \n
Pekka Pessi's avatar
Pekka Pessi committed
1242 1243 1244 1245 1246 1247 1248
 * #nua_i_terminated       \n
 * #nua_i_update
 *
 * @par Responses:
 * #nua_r_get_params       \n
 * #nua_r_notifier         \n
 * #nua_r_shutdown         \n
Pekka Pessi's avatar
Pekka Pessi committed
1249
 * #nua_r_terminate
Pekka Pessi's avatar
Pekka Pessi committed
1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294
 *
 * @par SIP responses:
 * #nua_r_bye         \n
 * #nua_r_chat        \n
 * #nua_r_info        \n
 * #nua_r_invite      \n
 * #nua_r_message     \n
 * #nua_r_notify      \n
 * #nua_r_options     \n
 * #nua_r_publish     \n
 * #nua_r_refer       \n
 * #nua_r_register    \n
 * #nua_r_subscribe   \n
 * #nua_r_unregister  \n
 * #nua_r_unsubscribe \n
 * #nua_r_update
 */

/** @var nua_event_e::nua_i_active
 *
 * A call has been activated.
 *
 * This event will be sent after succesful response to the initial
 * INVITE has been received and the media has been activated.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
 * @param sip    NULL
 * @param tags   NUTAG_ACTIVE_* tags
 */

/** @var nua_event_e::nua_i_bye
 *
 * Incoming call hangup.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
 * @param sip    pointer to BYE request
 * @param tags   empty
 */

/** @var nua_event_e::nua_i_cancel
 *
 * Incoming INVITE has been cancelled
 *
Pekka Pessi's avatar
Pekka Pessi committed
1295
 * Incoming INVITE has been cancelled or
Pekka Pessi's avatar
Pekka Pessi committed
1296 1297 1298 1299 1300 1301 1302 1303 1304 1305
 * no ACK has been received for an accepted call.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
 * @param sip    incoming CANCEL request or NULL if time-out occured
 * @param tags   empty
 */

/** @var nua_event_e::nua_i_chat
 *
Pekka Pessi's avatar
Pekka Pessi committed
1306
 * Incoming chat MESSAGE
Pekka Pessi's avatar
Pekka Pessi committed
1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
 * @param sip    incoming char MESSAGE
 * @param tags   empty
 */

/** @var nua_event_e::nua_i_error
 *
 * Error indication.
 *
Pekka Pessi's avatar
Pekka Pessi committed
1318
 * Will be sent when an internal error happened or
Pekka Pessi's avatar
Pekka Pessi committed
1319 1320 1321 1322 1323 1324 1325 1326 1327 1328
 * an error occurred while responding a request.
 *
 * @param nh     NULL or operation handle associated with the call
 * @param hmagic NULL or operation magic associated with the call
 * @param sip    NULL
 * @param tags   empty or error specific information
 */

/** @var nua_event_e::nua_i_fork
 *
Pekka Pessi's avatar
Pekka Pessi committed
1329
 * Outgoing call has been forked.
Pekka Pessi's avatar
Pekka Pessi committed
1330 1331 1332 1333 1334 1335
 *
 * This is sent when an INVITE request is answered with multiple 200 responses.
 *
 * @param nh     operation handle associated with the original call
 * @param hmagic operation magic associated with the original call
 * @param sip    200 series response to INVITE
Pekka Pessi's avatar
Pekka Pessi committed
1336
 * @param tags   #NUTAG_HANDLE of the new forked call
Pekka Pessi's avatar
Pekka Pessi committed
1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352
 */

/** @var nua_event_e::nua_i_info
 *
 * Incoming session INFO
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
 * @param sip    incoming INFO request
 * @param tags   empty
 */

/** @var nua_event_e::nua_i_invite
 *
 * Incoming call
 *
Pekka Pessi's avatar
Pekka Pessi committed
1353
 * @param nh     operation handle associated with this call
Pekka Pessi's avatar
Pekka Pessi committed
1354
 *               (maybe created for this call)
Pekka Pessi's avatar
Pekka Pessi committed
1355
 * @param hmagic operation magic associated with this call
Pekka Pessi's avatar
Pekka Pessi committed
1356 1357 1358 1359 1360 1361 1362 1363 1364
 *               (maybe NULL if call handle was created for this call)
 * @param sip    incoming INVITE request
 * @param tags   NUTAG_ACTIVE_*
 */

/** @var nua_event_e::nua_i_media_error
 *
 * Media error indication.
 *
Pekka Pessi's avatar
Pekka Pessi committed
1365
 * This may be sent after an implicit
Pekka Pessi's avatar
Pekka Pessi committed
1366 1367 1368
 * media operation has failed while processing incoming or outgoing call.
 *
 * @param nh     operation handle associated with the call
Pekka Pessi's avatar
Pekka Pessi committed
1369
 * @param hmagic operation magic associated with this call
Pekka Pessi's avatar
Pekka Pessi committed
1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389
 *               (maybe NULL if call handle was created for this call)
 * @param sip    NULL
 * @param tags   #NUTAG_MEDIA_SESSION (optionally)
 */

/** @var nua_event_e::nua_i_message
 *
 * Incoming MESSAGE
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
 *               (maybe NULL if outside session)
 * @param sip    incoming MESSAGE request
 * @param tags   empty
 */

/** @var nua_event_e::nua_i_method
 *
 * Unknown incoming method.
 *
Pekka Pessi's avatar
Pekka Pessi committed
1390
 * The extension method must be listed using #SIPTAG_ALLOW
Pekka Pessi's avatar
Pekka Pessi committed
1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 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
 * tag in nua_set_options().
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
 * @param sip    incoming request with unknown method
 * @param tags   empty
 */

/** @var nua_event_e::nua_i_notify
 *
 * Incoming event.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
 * @param sip    incoming NOTIFY request
 * @param tags   #NUTAG_SUBSTATE indicating the subscription state
 */

/** @var nua_event_e::nua_i_options
 *
 * Incoming options.
 *
 * @param nh     operation handle associated with the call
 *               (default operation handle if outside session)
 * @param hmagic operation magic associated with the call
 *               (NULL if outside session)
 * @param sip    incoming OPTIONS request
 * @param tags   empty
 */


/** @var nua_event_e::nua_i_publish
 *
 * Incoming PUBLISH.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
 *               (NULL if outside session)
 * @param sip    incoming PUBLISH request
 * @param tags   empty
 */

/** @var nua_event_e::nua_i_refer
 *
 * Incoming call transfer.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
 *               (NULL if outside session)
 * @param sip    incoming REFER request
 * @param tags   #NUTAG_REFER_EVENT \n
 *               #SIPTAG_REFERRED_BY
 */

1445
/** @var nua_event_e::nua_i_state
Pekka Pessi's avatar
Pekka Pessi committed
1446
 *
1447
 * Call state has changed.
Pekka Pessi's avatar
Pekka Pessi committed
1448
 *
Pekka Pessi's avatar
Pekka Pessi committed
1449 1450
 * This event will be sent whenever the call state changes.
 * In addition to basic changes of session status, also
1451 1452 1453 1454 1455
 * SDP O/A negotiation status is included.
 *
 * Note that nua_event_e::nua_i_state also covers call
 * establisment (@see nua_event_e::nua_i_active ) and
 * termination (@see nua_event_e::nua_i_terminated ).
Pekka Pessi's avatar
Pekka Pessi committed
1456
 *
1457 1458 1459 1460 1461 1462
 * @param status Protocol status code. \n
 *               Always present
 * @param phrase Text corresponding to status code. \n
 *               Always present
 * @param nh     Operation handle associated with the call
 * @param hmagic Operation magic associated with the call
Pekka Pessi's avatar
Pekka Pessi committed
1463
 * @param sip    NULL
1464 1465
 * @param tags   NUTAG_ACTIVE_* \n
 *               NUTAG_SOA_SESSION
Pekka Pessi's avatar
Pekka Pessi committed
1466 1467 1468 1469 1470 1471 1472 1473
 */

/** @var nua_event_e::nua_i_subscribe
 *
 * Incoming subscription.
 *
 * Not implemented.
 *
Pekka Pessi's avatar
Pekka Pessi committed
1474 1475 1476 1477
 * @param nh
 * @param hmagic
 * @param sip
 * @param tags
Pekka Pessi's avatar
Pekka Pessi committed
1478 1479
 */

1480 1481 1482 1483 1484
/** @var nua_event_e::nua_i_terminated
 *
 * A call has been terminated.
 *
 * This event will be sent after a call has been terminated. A call is
Pekka Pessi's avatar
Pekka Pessi committed
1485
 * terminated, when
1486
 * 1) an error response (300..599) is sent to an incoming initial INVITE
Pekka Pessi's avatar
Pekka Pessi committed
1487
 * 2) a reliable response (200..299 or reliable preliminary response) to
1488 1489
 *    an incoming initial INVITE is not acknowledged with ACK or PRACK
 * 3) BYE is received or sent
Pekka Pessi's avatar
Pekka Pessi committed
1490
 *
1491 1492 1493 1494 1495 1496
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
 * @param sip    NULL
 * @param tags   empty
 */

Pekka Pessi's avatar
Pekka Pessi committed
1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510
/** @var nua_event_e::nua_i_update
 *
 * Incoming session UPDATE.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
 * @param sip    incoming UPDATE request
 * @param tags   empty
 */

/** @var nua_event_e::nua_r_bye
 *
 * Answer to outgoing BYE.
 *
Pekka Pessi's avatar
Pekka Pessi committed
1511
 * The BYE may be sent explicitly by nua_bye() or
Pekka Pessi's avatar
Pekka Pessi committed
1512 1513 1514 1515
 * implicitly by NUA state machine.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
Pekka Pessi's avatar
Pekka Pessi committed
1516
 * @param sip    response to BYE request or NULL upon an error
Pekka Pessi's avatar
Pekka Pessi committed
1517 1518 1519 1520 1521 1522 1523 1524 1525 1526
 *               (error code and message are in status an phrase parameters)
 * @param tags   empty
 */

/** @var nua_event_e::nua_r_chat
 *
 * Answer to outgoing chat MESSAGE.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
Pekka Pessi's avatar
Pekka Pessi committed
1527
 * @param sip    response to MESSAGE request or NULL upon an error
Pekka Pessi's avatar
Pekka Pessi committed
1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549
 *               (error code and message are in status an phrase parameters)
 * @param tags   empty
 */

/** @var nua_event_e::nua_r_get_params
 *
 * Answer to nua_get_params().
 *
 * @param nh     NULL
 * @param hmagic NULL
 * @param sip    NULL
 * @param tags   NUTAG_* \n
 *               SIPTAG_* \n
 *               NTATAG_*
 */

/** @var nua_event_e::nua_r_info
 *
 * Answer to outgoing INFO.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
Pekka Pessi's avatar
Pekka Pessi committed
1550
 * @param sip    response to INFO or NULL upon an error
Pekka Pessi's avatar
Pekka Pessi committed
1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563
 *               (error code and message are in status an phrase parameters)
 * @param tags   empty
 */

/** @var nua_event_e::nua_r_invite
 *
 * Answer to outgoing INVITE.
 *
 * The INVITE may be sent explicitly by nua_invite() or
 * implicitly by NUA state machine.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
Pekka Pessi's avatar
Pekka Pessi committed
1564
 * @param sip    response to INFO or NULL upon an error
Pekka Pessi's avatar
Pekka Pessi committed
1565 1566 1567 1568 1569 1570 1571 1572 1573 1574
 *               (error code and message are in status an phrase parameters)
 * @param tags   empty
 */

/** @var nua_event_e::nua_r_message
 *
 * Answer to outgoing MESSAGE
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
Pekka Pessi's avatar
Pekka Pessi committed
1575
 * @param sip    response to MESSAGE request or NULL upon an error
Pekka Pessi's avatar
Pekka Pessi committed
1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592
 *               (error code and message are in status an phrase parameters)
 * @param tags   empty
 */

/** @var nua_event_e::nua_r_notifier
 *
 * Answer to nua_notitier()
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
 * @param sip    NULL
 * @param tags   #SIPTAG_EVENT \n
 *               #SIPTAG_CONTENT_TYPE
 */

/** @var nua_event_e::nua_r_notify
 *
Pekka Pessi's avatar
Pekka Pessi committed
1593
 * Answer to outgoing NOTIFY.
Pekka Pessi's avatar
Pekka Pessi committed
1594
 *
Pekka Pessi's avatar
Pekka Pessi committed
1595
 * The NOTIFY may be sent explicitly by nua_notify() or
Pekka Pessi's avatar
Pekka Pessi committed
1596 1597 1598 1599
 * implicitly by NUA state machine.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
Pekka Pessi's avatar
Pekka Pessi committed
1600
 * @param sip    response to NOTIFY request or NULL upon an error
Pekka Pessi's avatar
Pekka Pessi committed
1601 1602 1603 1604 1605 1606
 *               (error code and message are in status an phrase parameters)
 * @param tags   empty
 */

/** @var nua_event_e::nua_r_options
 *
Pekka Pessi's avatar
Pekka Pessi committed
1607
 * Answer to outgoing OPTIONS.
Pekka Pessi's avatar
Pekka Pessi committed
1608 1609 1610
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
Pekka Pessi's avatar
Pekka Pessi committed
1611
 * @param sip    response to OPTIONS request or NULL upon an error
Pekka Pessi's avatar
Pekka Pessi committed
1612 1613 1614 1615 1616 1617
 *               (error code and message are in status an phrase parameters)
 * @param tags   empty
 */

/** @var nua_event_e::nua_r_publish
 *
Pekka Pessi's avatar
Pekka Pessi committed
1618
 * Answer to outgoing PUBLISH.
Pekka Pessi's avatar
Pekka Pessi committed
1619
 *
Pekka Pessi's avatar
Pekka Pessi committed
1620
 * The PUBLISH may be sent explicitly by nua_publish() or
Pekka Pessi's avatar
Pekka Pessi committed
1621 1622 1623 1624
 * implicitly by NUA state machine.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
Pekka Pessi's avatar
Pekka Pessi committed
1625
 * @param sip    response to PUBLISH request or NULL upon an error
Pekka Pessi's avatar
Pekka Pessi committed
1626 1627 1628 1629 1630 1631
 *               (error code and message are in status an phrase parameters)
 * @param tags   empty
 */

/** @var nua_event_e::nua_r_refer
 *
Pekka Pessi's avatar
Pekka Pessi committed
1632
 * Answer to outgoing REFER.
Pekka Pessi's avatar
Pekka Pessi committed
1633 1634 1635
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
Pekka Pessi's avatar
Pekka Pessi committed
1636
 * @param sip    response to REFER request or NULL upon an error
Pekka Pessi's avatar
Pekka Pessi committed
1637 1638 1639 1640 1641 1642 1643
 *               (error code and message are in status an phrase parameters)
 * @param tags   #NUTAG_REFER_EVENT \n
 *               #NUTAG_SUBSTATE
 */

/** @var nua_event_e::nua_r_register
 *
Pekka Pessi's avatar
Pekka Pessi committed
1644
 * Answer to outgoing REGISTER.
Pekka Pessi's avatar
Pekka Pessi committed
1645
 *
Pekka Pessi's avatar
Pekka Pessi committed
1646
 * The REGISTER may be sent explicitly by nua_register() or
Pekka Pessi's avatar
Pekka Pessi committed
1647 1648 1649 1650
 * implicitly by NUA state machine.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
Pekka Pessi's avatar
Pekka Pessi committed
1651
 * @param sip    response to REGISTER request or NULL upon an error
Pekka Pessi's avatar
Pekka Pessi committed
1652 1653 1654 1655 1656 1657
 *               (error code and message are in status an phrase parameters)
 * @param tags   empty
 */

/** @var nua_event_e::nua_r_shutdown
 *
Pekka Pessi's avatar
Pekka Pessi committed
1658
 * Answer to nua_shutdown().
Pekka Pessi's avatar
Pekka Pessi committed
1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673
 *
 * Status codes
 * 100 shutdown started \n
 * 101 shutdown in progress (sent when shutdown has been progressed) \n
 * 200 shutdown was successful \n
 * 500 shutdown timeout after 30 sec \n
 *
 * @param nh     NULL
 * @param hmagic NULL
 * @param sip    NULL
 * @param tags   empty
 */

/** @var nua_event_e::nua_r_subscribe
 *
Pekka Pessi's avatar
Pekka Pessi committed
1674
 * Answer to outgoing SUBSCRIBE.
Pekka Pessi's avatar
Pekka Pessi committed
1675
 *
Pekka Pessi's avatar
Pekka Pessi committed
1676
 * The SUBSCRIBE may be sent explicitly by nua_subscribe() or
Pekka Pessi's avatar
Pekka Pessi committed
1677 1678 1679 1680
 * implicitly by NUA state machine.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
Pekka Pessi's avatar
Pekka Pessi committed
1681
 * @param sip    response to SUBSCRIBE request or NULL upon an error
Pekka Pessi's avatar
Pekka Pessi committed
1682 1683 1684 1685 1686 1687
 *               (error code and message are in status an phrase parameters)
 * @param tags   #NUTAG_SUBSTATE
 */

/** @var nua_event_e::nua_r_terminate
 *
Pekka Pessi's avatar
Pekka Pessi committed
1688
 * Answer to nua_terminate().
Pekka Pessi's avatar
Pekka Pessi committed
1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
 * @param sip    NULL
 * @param tags   empty
 */

/** @var nua_event_e::nua_r_unregister
 *
 * Answer to outgoing un-REGISTER.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
 * @param sip    response to REGISTER request or NULL upon an error
 *               (error code and message are in status and phrase parameters)
 * @param tags   empty
 */

/** @var nua_event_e::nua_r_unsubscribe
 *
 * Answer to outgoing un-SUBSCRIBE.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
Pekka Pessi's avatar
Pekka Pessi committed
1713
 * @param sip    response to SUBSCRIBE request or NULL upon an error
Pekka Pessi's avatar
Pekka Pessi committed
1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726
 *               (error code and message are in status an phrase parameters)
 * @param tags   empty
 */

/** @var nua_event_e::nua_r_update
 *
 * Answer to outgoing UPDATE.
 *
 * The UPDATE may be sent explicitly by nua_update() or
 * implicitly by NUA state machine.
 *
 * @param nh     operation handle associated with the call
 * @param hmagic operation magic associated with the call
Pekka Pessi's avatar
Pekka Pessi committed
1727
 * @param sip    response to UPDATE request or NULL upon an error
Pekka Pessi's avatar
Pekka Pessi committed
1728 1729 1730
 *               (error code and message are in status an phrase parameters)
 * @param tags   empty
 */