Project: oSIP is an implementation of SIP - rfc2543. 
Last update: 0.7.0
Email  : jack@atosc.org
License: LGPL (http://www.gnu.org)

This is the oSIP library (for Open SIP). It has been
designed to provide the Internet Community a simple
way to support the Session Initiation Protocol.
SIP is described in the RFC2543 which is available at
http://www.ietf.org/rfc/rfc2543.txt.


FEATURES: (version 0.7.0)
---------

The oSIP library consists of 2 parts:

PARSER:
  *  SIP URL parser.
  *  SIP message parser.
  *  MIME support for message with multiple attachments.
  *  *very minimal* SDP message parser. (no negotiation!)

TRANSACTION MANAGER:
  *  2 states machines for UAC (INVITE and other).
  *  2 states machines for UAS (INVITE and other).
  *  user controls the application with events.
  *  events managed by the oSIP stack are announced through callbacks.
  *  2 timers manager for unreliable protocol such as UDP.

EXTRA:
  *  Porting the library is done through the "port_" files.
  *  osip is not tight to any design! You can use the library
     either in a multi-thread environment or not, use your
     own interuption's mechanism for timer, or use your own
     transport protocol...

Documentation:
--------------

Yet available:
  *  this README file.

Coming:
  *  The API reference for parser.
  *  The API reference for oSIP maintainers. (lowest priority)

Installation procedure:
-----------------------

The library is known to compile on various platform:
  *  Solaris (2.5)
  *  GNU/Linux (2.2.16, 2.4.7)
  *  VxWorks(5.4?).

For VxWorks:

First, you have to correct the makedef.vxw file.
Then, just type the following:

	$> make -f makefile.mai

Solaris and Linux:

	$>configure

If you need to disable any thread support,
you can use the folowing command:

	$>configure --disable-mt

Rq: If you use this option, the binaries
samples created in example_mt and example
will be identical to each other (without
multithread support)

If you need to use the GNU Portable thread
library, you can add the following option:

	$>configure --enable-pth  (never tested yet!!!!!!)

miscaleneous options:

	$>configure --disable-debug
	$>configure --disable-debug --disable-trace
	$>configure --enable_mleak
	$>make

      +-------------------+-----------------------+
      |    configure      |          GCC          |
      |     OPTIONS       |        OPTIONS        |
      +-------------------+-----------------------+
      |  --disable-mt     |  "-DOSIP_MT"          |
      |  --disable-debug  |  "-UENABLE_DEBUG"     |
      |  --disable-trace  |  "-UENABLE_TRACE"     |
      |  --enable-mleak   |  "-DENABLE_MLEAK"     |
      +-------------------+-----------------------+

List of executables:
  *  ./example/ua    : mono-processed sample
  *  ./example_mt/ua : multi-threaded sample
	simple app handling transaction. This is to
	test oSIP. (no sessions is stored in context)

  *  ./test/torture_test: test the SIP messages.
  *  ./test/turl      : test the sip-urls parser.
  *  ./test/tto       : test some 'to' fields
  *  ./test/tfrom     : test some 'from' fields
  *  ./test/tcontact  : test some 'contact' fields
  *  ./test/tvia      : test some 'via' fields
  *  ./test/tcallid   : test some 'call-id' fields
  *  ./test/tcontentt : test some 'content-type' fields

How to use the test programs:

  examples: messages are in conf/torture_msgs file

	./test/torture_test conf/torture_msgs 0
	./test/torture_test conf/torture_msgs 1
	./test/torture_test conf/torture_msgs 3

	./test/tcallid conf/callids.txt
	./test/tfrom  conf/froms.txt
	./test/tto conf/tos.txt
	./test/tvia conf/vias.txt
	./test/tcontact conf/contacts.txt
	./test/turl conf/urls.txt


Compilation issues:
-------------------

  *  hp unix:
	The oSIP library is known to compile but the -lrt
	is missing at link time.

Known issues:
-------------

  *  Lack of thread resources: (especially on Debian?)
	The actual architecture makes use of an impressing
	number of threads. The maximal number of thread may
	not be the same on all platforms. On Debian
	distribution, the applications cannot launch as
	many threads as on other systems. Once the kernel
	re-compiled, the issue dissapeared.

Known Limitation:
-----------------

  *  Only main headers are entirely defined:
	Via, To, From, Call-Id, CSeq, Contact,
	Content-Type, Content-Length, mime-version,
	route, record-route.
	All other headers are considered to be
	strings. (but there are all fully usable
	by the application layer)

EXAMPLE:
--------

The directory './example' contains a test application
of the library. Code is not clean, but it's a good start.

This utility mainly tests the finite state machines
of INVITE transactions for UAS and UAC. A few tests are
also available for REGISTER and BYE transactions.

During the test, transactions are always closed properly
even if one application is killed. It seems there is no
left memory leaks. (This has been tested with
-DMEMORY_LEAK in port_malloc.c!)

Warning: This is a test application so:
 *  some undefined behaviours may happen. For example,
    if you start 2 BYE transactions at the same time.
 *  the SDP answer or body attachment is totally dummy.
 *  wrong parameter will make the application crash...
    not the library...


1.How to start the './example/ua' test:
2.How to start the './example_mt/ua' test:
-------------------------------------

You must always launch two SIP agents. One will
act as a server (User Agent Server or UAS) and another
as a client (User Agent Client or UAC).

There are many ways to do it!

UA1: mode 0/1/2/3 (you should use 0 or 3 for at least one User Agent)
===
   $> ./example/ua -m 0 -f conf/siprc -d 2  -t "<sip:jack@127.0.0.1:5070>"
   $> ./example_mt/ua -m 0 -f conf/siprc -d 2  -t "<sip:jack@127.0.0.1:5070>"

UA2: mode 0/1/2 to initiate some transactions
===  Note that only the multithreaded sample can initiate
     transaction by the time of writing those lines.

   $> ./example_mt/ua -m 0 -f conf/siprc2 -d 2 -t "<sip:jack@127.0.0.1>"
   $> ./example_mt/ua -m 1 -f conf/siprc2 -d 2 -t "<sip:jack@127.0.0.1>"
   $> ./example_mt/ua -m 2 -f conf/siprc2 -d 2 -t "<sip:jack@127.0.0.1>"


command line OPTIONS:
	-m : this is a facility to select a behavior for the UA.
	     Modes are explained below.

	-d : This is the debug options. You should give a number
	     between 0 and 5.
		Example: -d 3 -> enable trace_level:0,1,2

	-t : this is where you can put the address of the callee
		(where you want to send the request)
		This will be the url used in the request-URI and
		the to field.

	-f : You MUST provide a configuration. The config file
	     MUST provide the
		* UDP port where the application is listening
		* username
		* localip
		* contact field
		* ... some other fields (NOT all are currently used)
	     If the config file contains the 'sipproxy' attribute,
	     its url will be used to send all messages.

How to use the multi-threaded test application:
----------------------------------------------

    in mode 0 (command line) you can type:
	i: new invite transaction.
	t: specify number of concurrent new invite transactions.
	b: new bye transaction 
	r: new register transaction

    in mode 1 and 2, you can stop and restart the application:
	s: stop test
	r: restart test

    in all modes, you can change on the fly the trace level
	0,1,2,3,4,5: to enable a special trace level.
	d: disable all levels.

    in all modes, you can also change the code for SIP answers.
	c: new static return code wanted

The following Use Cases are executed:
-------------------------------------

INVITE TRANSACTION
       UA1                    UA2
        |   INVITE->           |
        |   +retransmissions-> |
        |                      |
        | <- 180 Ringing       |
        |                      |
        | <- 200 Ok            |
        | <-retransmissions+   |
        |                      |
        |   ACK   ->           |
        |                      |

BYE TRANSACTION

       UA1                    UA2
        |   BYE->              |
        |   +retransmissions-> |
        |                      |
        | <- 200 Ok            |
        | <-retransmissions+   |
        |                      |

Contact information:
--------------------

For more information on the SIP stack, or any contributions,
you can contact the author at <jack@atosc.org>.

Latest version is available at
http://osip.atosc.org