mainpage.docs

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

  - files Makefile.am \n
    See section @ref build "dealing with GNU Autotools" below.
  - (optionally) source code file(s) of the module and module tests. 
    The source code file(s) can also be located in subdirectories if necesary.
    

@section oo_with_c Writing Object-Oriented Code

While C does not provide any special object-oriented features on its own, it
is possible to program in object-oriented way using C, too. Sofia code make
use of many object-oriented features while being written entirely in C.

@subsection oo_hiding Data Hiding

Data hiding is a practice that makes separation between two modules very
clear. Outside code cannot directly access the data within a module, but it
has to use functions provided for that purpose. Data hiding also makes it
easier to define a protocol between two objects - all communication happens
using function calls.

How to implement data hiding in C? Easiest answer is to only declare data
structures in the header files, not to define them. We have a typedef #msg_t
for @link msg_s struct msg_s @endlink in <sofia-sip/msg.h>, but the actual
structure is defined in "msg_internal.h". Programs outside @b msg module
does not have access to the @link msg_s struct msg_s @endlink, but they have
to to access the #msg_t object through method functions provided in
<sofia-sip/msg.h>. The @b msg implementation is also free to change the
internal layout of the structure, only keeping the function interface
unmodified.

@subsection oo_interface Interfaces

Abstract interface is another object-oriented practice used in Sofia. Parser
headers, defined in <sofia-sip/msg_types.h>, is a good example of abstract
interface. The type for message headers, #msg_header_t, is defined using two
C structures @link msg_common_s struct msg_common_s @endlink
(#msg_common_t), and @link msg_hclass_s struct msg_hclass_s @endlink
(#msg_hclass_t).

Abstract interface is achieved using virtual function table in #msg_hclass_t
structure, bit like C++ typically implements abstract classes and virtual
functions. For implemenation of each header, the function table is
initialized with functions responsible for decoding, encoding and
manipulating the header structure. Unlike C++, the class of the object
(#msg_hclass_t) is represented by a real data structure which also contains
header-specific data, like header name.

@dontinclude sip_basic.c
@skipline msg_hclass_t sip_contact_class
@skip {{
@until }};

@subsection oo_derived Inheritance and Derived Objects

Inheritance is a object-oriented practice that has limited use in Sofia. 
Most common example of inheritance is use of #su_home_t. Many objects are
derived from #su_home_t, which means that they can use the various
home-based memory management functions from <su_alloc.h>. 

In this sence, inheritance means that a pointer to a derived object can be
casted as a pointer to a base object. In other words, the derived object
must have the base object at the beginning of its memory area:

@code
struct derived 
{
  struct base base[1];
  int         extra;
  char       *data;
};
@endcode

There are three alternatives to cast a pointer to derived to a pointer to
base:
@code
struct base *base1 = (struct base *)derived;
struct base *base2 = &derived->base;
struct base *base3 = derived->base;
@endcode
The third alternative works because base was used as a 1-element array.

@subsection oo_templates Templates

There are a few template types implemented as macros in Sofia libraries. 
They include hash table, defined in <sofia-sip/htable.h>, which can be used
to define hash tables types and accessor functions for different object, and
red-black tree, defined in <sofia-sip/rbtree.h>.

@section memory Memory Management

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.

See documentation of <sofia-sip/su_alloc.h> and @ref su_alloc "memory managment tutorial"
for more information of memory management services.

@subsection contextdata Memory management of context data

A typical example of use of a memory home is to have a memory home structure
(#su_home_t) as part of operation context information structure.

@code
  /* context info structure */
  struct context {
    su_home_t  ctx_home[1];      /* memory home */
    other_t   *ctx_other_stuff;  /* example of memory areas */
    ...
  };

  /* context pointer */
  struct context *ctx;

  /* Allocate memory for context structure and initialize memory home */
  ctx = su_home_clone(NULL, sizeof (struct context));

  /* Allocate memory and register it with memory home */
  ctx->ctx_other_stuff = su_zalloc(ctx->ctx_home, sizeof(other_t));

  ... processing and allocating more memory ...

  /* Release registered memory areas, home, and context structure */
  su_home_zap(ctx->ctx_home);

@endcode

@subsection combining Combining allocations

Another place where home-based memory management makes programmers
life easier is case where a sub-procedure makes multiple memory allocations 
and, in case the sub-procedure fails, all the allocations must be released 
and, in case the sub-procedure is succesfull, all allocations must be
controlled by upper level memory management.

@code
  /* example sub-procedure. top_home is upper-level memory home */
  int sub_procedure( su_home_t *top_home, ... )
  {
    su_home_t temphome[1] = { SU_HOME_INIT(temphome) };

    ... allocations and other processing ...

    /* was processing successfull ? */
    if (success) {
      /* ok -> move registered allocated memory to upper level memory home */
      su_home_move( top_home, temphome );
    }
    /* destroy temporary memory home (and registered allocations) */
    /* Note than in case processing was succesfull the memory     */
    /* registrations were already moved to upper level home.      */ 
    su_home_deinit(temphome);

    /* return ok/not-ok */
    return success;
  }
@endcode

@section testing Testing Your Code

See <sofia-sip/tstdef.h> for example of how to write module tests with macros provided
by Sofia.

Here are some ideas of what you should test:
- "Smoke test" \n
  See that the module compiles, links and executes.
- Module API functions should be tested with\n
  - valid args
  - not valid args
- Aim for 100% line coverage\n
  (If there is a line of code that you have not tested, you don't know 
  if its working.) \n
  For selected part of code you should also aim for 
  100% branch/path coverage.\n
  But be anyway reasonable with these because in practise complete
  coverage is next to impossible to achive (so 80% is ok in practise).
- Create test to check assumptions and/or tricks used in code.\n
  For example if you rely on some compiler feature, create a test that
  will fail with a compiler that does not have that feature.

@subsection check Running Module Tests

Automake, which is used to build Sofia SIP, has builtin
support for unit tests. To add an automatically run test to your module,
you just have to add the following few lines to your module's Makefile.am
(of course, you have to write the test programs, too):

@code
TESTS = test_foo test_bar

check_PROGRAMS = test_foo test_bar

test_foo_SOURCES = foo.c foo.h
test_foo_LDADD = -L. -lmy

test_bar_SOURCES = bar.c bar.h
test_foo_LDADD = -L. -lmy
@endcode

Each test program should either return zero for success or a non-zero
error code in its main function. Now when you run "make check",
@b my_test_foo and @b my_test_bar will be built and then run. 
Make will print a
summary of how the tests went. As these tests are run from the build 
system, the tests must be non-interactive (no questions asked) and not 
rely on any files that are not in version control system.

Sofia SIP's top-level makefile contains a recursive check target, so 
you can use "cd sofia-sip ; make check" to run all the existing tests
with a single command.

@section build Dealing with GNU Autotools

Sofia-SIP build system is based on the GNU tools automake, autoconf and
libtool. This toolset has become the de-facto way of building Linux
software. Because of this there is a lot of publicly available documentation
about these tools, and of course, lots and lots of examples.

A good introduction to these tools is available at
<a href="http://developer.gnome.org/doc/books/WGA/generating-makefiles.html">
developer.gnome.org</a>. <a href="http://sources.redhat.com/autobook">Autobook</a>
provides more detailed documentation for autoconf and automake.
The <a href="http://www.gnu.org/manual/make/">GNU make manual</a> 
is also a good source of information.

@subsection autogen_sh autogen.sh

At top-level there is a shell script called @b autogen.sh. It calls a
convenient tool called @b autoreconf which will generate configure script
for you. It also fixes the mode bits: the mode bits are not stored in
<a href="http://darcs.net">darcs</a> version control system.

@code
$ sh autogen.sh
$ ./configure ... with your configure options ...
@endcode

@subsection configure_ac configure.ac

The @b configure.ac file (older autoconf versions used also @b configure.in)
contains the primary configuration for autoconf. configure.ac contains
checks for all external libraries, non-standard language and compiler
features that are needed to build the target module.

This file is created by the developer of the module.

@subsection sofia_m4 m4 files

Sofia-SIP's own autoconf macros are stored in the top-level direcry called @b
m4. These macros, along with all other macros used by @b configure.ac, are
copied into the module-specific @b aclocal.m4 file by an utility called
aclocal.

Contact Sofia-SIP development team, if you need changes to these files.

@subsection aclocal_m4 aclocal.m4

The aclocal.m4 contains the definitions of the autoconf macros used in 
@b configure.ac.

This file is generated by aclocal command.

@subsection Makefile_am Makefile.am

Makefile.am is where you define what programs and libraries should 
be built, and also what source files are needed to create them.
When you run automake, it creates the file Makefile.in.

This file is created by the developer of the module.

@subsection configure configure

When you run configure script, it performs all the checks defined in 
@b configure.ac and then replaces all @b xxx.in files with equivalent 
@b xxx files. All @c @@FOO@@ variables in the source @b *.in files are 
replaced with values found during the configuration process. For instance
the variable @c @@srcdir@@ in @b Makefile.in is replaced in @b Makefile 
with the source directory path (useful when compiling outside the main 
source tree).

This file is generated by autoconf command.

@subsection config_status config.status

This script stores the last parameters given to configre command.
If necessary you can rerun the last given configure script (with given
parameters) by using command "./config.status -r" or 
"./config.status --recheck".

This file is generated by configure script.

@subsection config_cache config.cache

This file contains results of the various checks that configure script 
performed. In case the configure script failed, you might try to
delete this file and run the configure script again.

This file is generated by configure script.

@subsection Makefile Makefile

The @b Makefile contains the actual rules how to build the target 
libraries and program. It is used by the @c make program. @b Makefile 
is generated from @b Makefile.in when you run @c autoconf command.
Ensure that "make dist" and "make install" targets work.

This file is generated by config.status and configure scripts.

@subsection config_h config.h

This file contains C language defines of various confurable issues.

This file is generated by config.status and configure script.

@subsection sofia_sip_configure_h sofia-sip/su_configure.h

This file contains C language defines describing how the Sofia SIP UA
library is configured.

This file is generated by config.status and configure script.

*/

/**
@page debug_logs Debugging Logs

The Sofia-SIP components can output various debugging information. The
detail of the debugging output is determined by the debugging level. The
level is usually module-specific and it can be modified by module-specific
environment variable. There is also a default level for all modules,
controlled by environment variable #SOFIA_DEBUG.

The environment variables controlling the logging and other debug output are
as follows:
- #SOFIA_DEBUG	Default debug level (0..9)
- #NUA_DEBUG	User Agent engine (<a href="nua/index.html">nua</a>) debug level (0..9)
- #SOA_DEBUG	SDP Offer/Answer engine (<a href="soa/index.html">soa</a>) debug level (0..9)
- #NEA_DEBUG	Event engine (<a href="nea/index.html">nea</a>) debug level (0..9)
- #IPTSEC_DEBUG	HTTP/SIP autentication module 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
- #SU_DEBUG	<a href="nea/index.html">su</a> module debug level (0..9)

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

In addition to the macros mentioned above, there is also functions for 
printing logging messages:
- su_llog(), su_vllog()
- su_perror(), su_perror2()

The log level can be set (to a level defined in a configuration file, for
instance) with following functions
- su_log_set_level(), su_log_soft_set_level()

The log output can be redirected to, e.g., system log or loggin server, with
su_log_redirect().

*/