nua.docs

Internet Phone, Chat, Conferencing

/* -*- 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 <[e-mail]>

@STATUS Core library

@LICENSE LGPL

@par Contributor(s):
- Pekka Pessi <[e-mail]>
- Pasi Rinne-Rahkola <[e-mail]>
- Kai Vehmanen <[e-mail]>
- Martti Mela <[e-mail]>

@section nua_overview Overview

The NUA API gives the high-level application programmer transparent and
full control to the SIP protocol engine燽elow it. NUA provides the call
semantics on top of existing transaction semantics found in
<a href="../nta/index.html"><b>nta</b></a> module.
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

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 utility library (<a href="../su/index.html"><b>su</b></a>) providing
unified interface to the most important 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
description of the SU services.

@subsection nua_root Event loop - root object

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
delivered messages from other task.

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
features like wait objects, timers, and messages.

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
nua_create() function.

Root object has type #su_root_t.

See documentation of <su_wait.h> and <su_root.c> for more information
of root object.

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

@subsection nua_magic Magic

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
the main event loop. The Sofia stack retains the context information between
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

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

An application using NUA services can use the memory management services
provided by the SU library but it is not mandatory.

See documentation of <su_alloc.h> for more information of memory management
services.

@subsection nua_tags Tags

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

The NUA functions can be called with a list of tagged values if they have
following parameters at the end of parameter list:

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

The last tagged value on the parameter list must be TAG_NULL()
(synonym for TAG_END()).

Every tag has two versions: \n
NUTAG_<tagname> \n
which takes a value parameter and \n
NUTAG_<tagname>_REF \n
which takes a reference parameter and is used with
tl_gets() function to retrieve tag values from tag list.

For some Sofia layers (for example SIP) there exists also additional
version of tags: \n
SIPTAG_<tagname>_STR \n
This tag version takes a C-language character string as parameter.
The corresponding tag without _STR suffix takes a parsed value structure
as parameter.

The following is an example of call to NUA function containing tagged values:
@code
nua_unregister(op->op_handle,
               TAG_IF(use_registrar, NUTAG_REGISTRAR(registrar)),
               SIPTAG_CONTACT_STR("*"),
               SIPTAG_EXPIRES_STR("0"),
               TAG_NULL());
@endcode

An application using NUA services must use tagging for the function
parameter passing.

See documentation of <su_tag.h> for more information of tags and the
module-specific documentation of each Sofia module for information of
tags specific for that module.

@subsection nua_debugandlogging Debugging and Logging

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.

Examples of useful directives/ environment variables are:
- #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

An application using NUA services can also use the debugging and
logging services provided by the Sofia stack but it is not mandatory.

See documentation of <su_log.h> for more information of debugging and
logging services.

@section nua_concepts NUA Concepts

@subsection nua_stackobject NUA Stack Object

Stack object represents an instance of SIP stack and media engine. It
contains reference to root object of that stack, user-agent-specific
settings, and reference to the SIP transaction engine, for example.

A NUA stack object is created by nua_create() function and deleted by
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

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
NUA (e.g. From and To headers).

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

The stack thread is a separate thread from application that provides the
real-time protocol stack operations so that application thread can for
example block or redraw UI as it likes.

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
the application calls su_root_run() or su_root_step() function.

@subsection nua_sipmessage SIP Message and Header Manipulation

SIP messages are manipulated with typesafe SIPTAG_ tags. There are
three versions of each SIP tag:
- SIPTAG_<tagname>() takes a parsed value as parameter.
- SIPTAG_<tagname>_STR() takes an unparsed string as parameter.
- SIPTAG_<tagname>_REF() takes a reference as parameter, is used
        with tl_gets() function to retrieve tag values from tag list.
- SIPTAG_<tagname>__STR_REF() takes a reference as parameter, is used
        with tl_gets() function to retrieve string tag values from tag list.

For example a header named "Example" would have tags names SIPTAG_EXAMPLE(),
SIPTAG_EXAMPLE_STR(), and SIPTAG_EXAMPLE_REF().

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
headers from the message.

For example:

- sending a SUBSCRIBE with @b Event: header and two @b 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

This section describes basic usage scenarios of NUA/Sofia stack using
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

The following sections will present code examples from a simple application
that uses services of NUA. The example is not complete but should present
all relevant details of the basic use of NUA.

The source distribution of Sofia stack contains in directory nua an example
application nua_cli.c that can be studied for more complete example.

@subsection nua_datastructures Data Structures & Defines

An application using services of NUA normally defines data areas that are
used to store context information (i.e., "magic"). The types of pointers to