mainpage.docs

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

/* -*- text -*- */

/**@mainpage Sofia SIP User Agent Library - sofia-sip-ua

@section Introduction

This document contains automatically generated reference documentation
for Sofia-SIP components. Some introductory material and
pointers to the example code are also included.

For a list of module specific pages, see @ref subdirs 
"source tree structure" or direct links to submodules:<br>
<a href="nua/index.html">nua</a> 
<a href="su/index.html">su</a> 
<a href="features/index.html">features</a> 
<a href="soa/index.html">soa</a> 
<a href="sdp/index.html">sdp</a> 
<a href="nta/index.html">nta</a> 
<a href="tport/index.html">tport</a> 
<a href="sresolv/index.html">sresolv</a> 
<a href="sip/index.html">sip</a> 
<a href="msg/index.html">msg</a> 
<a href="url/index.html">url</a> 
<a href="stun/index.html">stun</a> 
<a href="iptsec/index.html">iptsec</a> 
<a href="nea/index.html">nea</a> 
<a href="nth/index.html">nth</a> 
<a href="http/index.html">http</a> 
<a href="bnf/index.html">bnf</a> 
<a href="ipt/index.html">ipt</a> 

@section who Contact Information

You can download latest Sofia SIP from the project 
<a href="http://sofia-sip.sf.net">home page</a> at 
<a href="sf.net">Sourceforge.net</a>.

Please contact us if you have questions regarding this software:

<ul> 
<li>Pekka Pessi <[e-mail]></li>
<li>Kai Vehmanen <[e-mail]></li>
</ul> 

Or post to the Sofia-SIP mailing list:

<ul>
<li>mailto:[e-mail]</li>
<li>http://lists.sourceforge.net/lists/listinfo/sofia-sip-devel</li>
</ul>

*/

/**@page building Source Tree Structure

@section subdirs Directory Structure

In libsofia-sip-ua, there are subdirectories for different modules listed
below.

Terminal and high-level libraries used for both signaling and media:

Common runtime library:
 - <a href="su/index.html">"su" - sockets, memory management, threads</a>
 - <a href="sresolv/index.html">"sresolv" - Asynchronous DNS resolver</a>
 - <a href="ipt/index.html">"ipt" - IPT utility library</a>

SIP Signaling:
 - <a href="nua/index.html">"nua" - SIP User Agent library</a>
 - <a href="nea/index.html">"nea" - SIP Event API</a>
 - <a href="iptsec/index.html">"iptsec" - 
    Digest authentication for HTTP and SIP</a>
 - <a href="nta/index.html">"nta" - SIP transaction engine</a>
 - <a href="tport/index.html">"tport" - Message transport</a>
 - <a href="sip/index.html">"sip" - SIP messages and headers</a>
 - <a href="msg/index.html">"msg" - Message handling </a>
 - <a href="url/index.html">"url" - URL handling</a>
 - <a href="bnf/index.html">"url" - low level parsing</a>

HTTP subsystem:
 - <a href="nth/index.html">"nth" - HTTP protocol engine</a>
 - <a href="http/index.html">"http" - HTTP messages and headers</a>

SDP processing:
 - <a href="soa/index.html">"soa" - SDP Offer/Answer engine for SIP</a>
 - <a href="sdp/index.html">"sdp" - SDP parser</a>

Other:
 - <a href="stun/index.html">"stun" - STUN library</a>

Features provided by Sofia-SIP library:
 - <a href="features/index.html">"features" - Features provided by Sofia SIP</a>

Documentation:
 - "docs" - Doxygen reference documentation

*/

/**
@page styleguide C Style Guide

This document gives general guidelines on generic C style and code
formatting within Sofia-SIP. The guidelines include identifier naming
conventions, indenting convention, and tool usage directions.

Please note that C style is always a matter of taste. 

@section naming Naming Conventions

Generally, identifiers within each module are prefixed with the name of
that module. For instance, the functions within http parser module @b http
have prefix @c http_. Identifiers composed of multiple words have an
underscore "_" between the words, the words themselves are in lower
case. For instance, http_request_create().

Macros should be in upper case. File names should be in lower case using
underscore as delimiter if needed.

Normal typedefs have suffix @c _t, however, function types have suffix @c
_f. The enum names also sometimes have @c _e, struct names have @c _s and
union names @c _u.

It is recommended that type itself is typedef'ed, not a pointer to the
type. It should be clear from variable declaration if the variable is a
pointer or not.

@code
typedef struct foo_s foo_t;
typedef int f_fun(foo_t *f, char const *s);
@endcode

Struct and union members should have common prefix. For instance,
@code
struct foo_s {
  int    f_len;
  char  *f_name;
  fun_f *f_fun;
};
@endcode

This prefix makes it easier to find where members are used.

@section formatting Indenting and Formatting code

Indentation in Sofia-SIP C code generally follows the @e K&R style with indent
of 2 characters (so you can use the default "GNU" c-style in Emacs). The
maximum line length should be 80 characters.

For example,

@code
void kluge(int foo)
{
  if (foo) {
    bar();
  }
  else {
    switch (baz()) {
    case a:
      eeny();
      break;
    case b:
      meeny();
      break;
    default:
      moe();
      break;
    }
  }
}
@endcode

The default indentation can be achieved with GNU indent with options
@code
-nbad -bap -bbo -nbc -br -brs -c33 -cd33 -ncdb -ce -ci2 -cli0 -cp33 -cs
-d0 -di1 -nfc1 -nfca -hnl -i2 -ip0 -l79 -lp -npcs -nprs -npsl -saf -sai
-saw -nsc -nsob -nss
@endcode

Loops without condition use @c for @c (;;) instead of @c while @c (1). 

@code
  for (;;) {
    foo();
    if (bar())
      break;
    baz();
  }
@endcode

There should be whitespace on both sides of infix operators, except
<code>.</code> or <code>-></code>, which require no space, or
<code>,</code> (comma) which requires space only after). There should be
whitespace between a keyword and parenthesis following it, but no
whitespace between an identifier and parenthesis following it. E.g.,

@code
  while (i++ < n)
    baz();
  for (;;) {
    x->x_foo();
    if (bar())
      break;
    z.z_baz++;
  }
  return (13 * i);
@endcode

 */

/**
@page programming Programming Guide

@section porting Writing Portable Code

Most of Sofia-SIP software is written as portable. All core modules are
(or at least should be) written in ANSI C 89 with some ANSI C 99
features. If there are platform specific parts, they are collected to
separate C files and isolated from the rest of the software with a
wrapper interface.

SU module handles abstraction to OS specific functionality such as
memory management, sockets, threads and time functions. 

@subsection ansi_99 ANSI C 99 features

The following ANSI C 99 features are to be used in Sofia-SIP software:
- Integer types
- functions va_copy() and snprintf()

The following ANSI C 99 features shall not be used in Sofia-SIP software:
- definition of a variable in the middle of function code.
  (so always define your variables in the beginning of the block)

@subsection port_ints Integer Types

As you should know, the length of native storage size depends on hardware,
OS and compiler. This means in practice that the length of int or long is
not necessarily 32 bits. As a consequence, you need to make sure that the
value you intend to store in the int, can actually fit in int on different
platforms. As a rule of thumb, if the integer value can exceed 8 bits, you
should use types that have a defined length.

Nevertheless its OK to use native integer types if you bear in mind
what was said above. The original reason for having only native
data type was performance. The int type is always stored in the
fastest (and usually biggest size) possible.

Never assume anything on the length of the type. Alway use sizeof()
operator to find out the length.

C 99 standard defines the following fixed length data types:

- int64_t
- uint64_t
- int32_t
- uint32_t
- int16_t
- uint16_t
- int8_t
- uint8_t

To use these data types you must include the <sofia-sip/su_types.h> header, which
takes care of including correct file. If @b su includes are not available,
you must include the following code segment to each file where you plan to
use them:

@code
#if HAVE_STDINT_H
#include <stdint.h>
#elif HAVE_INTTYPES_H
#include <inttypes.h>
#else
#error Define HAVE_STDINT_H as 1 if you have <stdint.h>, \
 or HAVE_INTTYPES_H if you have <inttypes.h>
#endif
@endcode

@subsection port_byte_sex Byte order

The host byte order on different platforms vary. When you do only
local processing, need not to worry about the byte order. But as
soon as you start writing code that send or receives anything to
the network, you need to start worrying.

If you wish to convert the byte order, it is simply done by calling
one the following functions:

The htonl() function converts the unsigned integer hostlong from
host byte order to network byte order.

The htons() function converts the unsigned short integer hostshort
from host byte order to network byte order.

The ntohl() function converts the unsigned integer netlong from
network byte order to host byte order.

The ntohs() function converts the unsigned short integer netshort
from network byte order to host byte order.

You need to include <netinet/in.h> or <sofia-sip/su.h> to use these functions.

@subsection port_struct Packing structures

By default, compilers usually arrange structures so that they are
quick to access. This means that most fields in the structure start
at the 32 bit boundary. If you need to conserve memory, you may use
structure packing.

To tell the compiler that you only need certain amount of bits to
store a variable, you can use bit-fields. Compiler may or may not
pack the bit-fields.

@code
struct foo {
  unsigned bar:5;
  unsigned foo:2;
  unsigned :0;
  int      something;
}
@endcode

If compiler decides to pack this structure, this code generates a
structure that has @a bar and @a foo in the first seven bits, and then
@a something beginning from the next 32 bit boundary. 

One problem arises when using packed bit-fields: on ARM it is
generally not possible to access a 32 bit field that does not start from
the 32-bit boundary. Hence the example has the :0 padding member in the
structure. Seems handy but beware: initialization of this structure fails
on some ARM gcc compilers. (Ask Kai Vehmanen for details).

A way to force packing of a structure is to use preprocessor
directive @c @#pragma(pack). This directive is compiler specific, so if
you plan to write truly portable code, you cannot use it. We have
used it in some parts of the Sofia-SIP though. Only alternative is to
write functions that fetch the desired bits from a 32 bit field
with bit operations; not very handy and error prone.

The same aligment problem also arises if you cast for example char
buffer to a int32_t. You can only read int32_t from the 32bit boundary
on ARM platform. So be careful.

As a conclusion, when using bit-fields and stucture packing, beware
of the pitfalls. If you don't really need to use them (as in parsing
binary protocols), don't use them.

@section file_organization File and Directory Structure

A Sofia-SIP library module can be defined as a subdirectory under the
libsofia-sip-ua directory hierarchy that contains a file \<modulename\>.docs 
(where the \<modulename\> of course referes to the actual name of 
the module). 

In case you like to start developing a new module, please
contact Sofia-SIP development team so that they can help you to set up
the basic module for you.

An overview of the contents of a module directory:
  - file \<modulename\>.docs \n
    Main documentation file for the module. See @ref module_docs
    for more information
  - subdirectory pictures \n
    Contains any pictures/images
    that are needed by the module documentation. The
    file formats to use are GIF (for html pages) and
    EPS (for latex). If some program (e.g. MS Visio) is 
    used to create the pictures, also the original
    files must be stored here.\n
    (Note that old modules may have "images" subdirectory instead of
    "pictures")