Project: oSIP is an implementation of SIP - rfc2543. 
Last update: 0.6.2
Email  : jack@atosc.org
License: LGPL

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.


HISTORY:
--------
Aug 2001    : 0.6.2
	finite state machine has been optimized. Note
	that it may not be free of bug as it has not been
	tested heavily. This release also include many
	improvements.

Aug 2001    : 0.6.1
        move some prototypes, correct BUGs, and began
        the declaration of the accessor API.

Aug 2001    : 0.6.0
	This release has a completely NEW PARSER which is
	a lot more compliant with draft-sip-rfc2543-03.txt.
	The API for the parser is completely new and
	ready for a better error management. The support
	of multiple attachments (MIME) has been added.

May/June 2001: 0.5.1 to 0.5.4
	Those versions include some bug fixes but no major
	improvements.

April 2001   : first release of oSIP 0.5.0
	This is the first release and is not complete but
	yet usable to implement SIP agents.

FEATURES: (version 0.6.0)
---------

The oSIP library consists of 2 parts: a PARSER and
an minimal architecture for SIP agents (IP phones,
redirect servers, registrar...)

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).
  *  SIP udp transport layer. (ready for any protocol)
  *  user controls the application with events.
  *  events managed by the oSIP stack are announced through callbacks.
  *  2 timers manager for unreliable protocol. (UDP)

EXTRA:
  *  The application handles transport and timers management alone.
  *  Porting the library is done through the "port_" files.
  *  The application design is only optional! (new ones
	will be added)

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

Yet available:
  *  this README file.
  *  A user manual. (NOT *very* up to date in 0.6.0)

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)
  *  VxWorks(??).

NOTES: For VxWorks, you will have to compile with
your own Makefile (contact me for help) and must also
define -D__VXWORKS_OS__

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

      +-------------------+-----------------------+
      |    configure      |          GCC          |
      |     OPTIONS       |        OPTIONS        |
      +-------------------+-----------------------+
      |  --enable-debug   |  "-g -DENABLE_DEBUG"  |
      |  --enable-trace   |  "-DENABLE_TRACE"     |
      |  --enable-mleak   |  "-DENABLE_MLEAK"     |
      +-------------------+-----------------------+

List of executables:
  *  ./example/ua :
	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.

  *  vxworks:
	Your must use your own Makefile and add
	-D__VXWORKS_OS__ as a defined MACRO.


KNOWN BUGS AND LIMITATION:
--------------------------

  *  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. (see the TODO
	list for more information)
  *  Only main headers are entirely defined:
	To, From, Call-Id, CSeq, Contact, Content-Type,
	Content-Length, mime-version. 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.

But this utility mainly tests the finite state machine
of INVITE transactions as a 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.


How to start the './example/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 3 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>"

UA2: mode 0/1/2 to initiate some transactions

   $> ./example/ua -m 0 -f conf/siprc2 -d 2 -t "<sip:jack@127.0.0.1>"
   $> ./example/ua -m 1 -f conf/siprc2 -d 2 -t "<sip:jack@127.0.0.1>"
   $> ./example/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)


How to use the 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 (not tested since long)
	r: new register transaction (not tested since long)

    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