Description:
===========
The GNU oSIP library is an implementation of SIP - rfc3261.
Email : jack@atosc.org
License : LGPL (http://www.gnu.org)
Home Page : http://www.gnu.org/software/osip/osip.html
Download : ftp://ftp.gnu.org/gnu/osip
"The GNU oSIP library" is part of the "GNU project".
You can check www.gnu.org for more information about
being part of the "GNU project".
For information, look at:
INSTALL
HISTORY
FEATURES
Links:
=====
Latest version: ftp://ftp.gnu.org/gnu/osip
Home page: http://www.gnu.org/software/osip/osip.html
Online Documentation: http://www.gnu.org/software/osip/
Supported Platforms:
===================
The library is known to compile on various platform:
* GNU/Linux
* MacOSX (Darwin)
* OpenBsd 3.1/3.2 // (FreeBSD&NetBSD should also work)
* Windows NT/95/2000 (VC++6.0 or cygwin)
* Solaris
* HP-Unix.
* VxWorks.
* Some embedded systems with linux.
* WinCE (report to be possible)
For more informations about compilation, please look in
the ./help directory.
Test Programs:
=============
The library contains some built-in test for the parser. To quickly test
the parser, type: (Note that some tests MUST fail!)
$> make check
Watch out the ./src/test/CHECK file for more informations.
Contact Informations:
====================
For more information on the SIP stack, or any contributions,
you can contact the author at <jack@atosc.org>.
A Mailing list is available for support: <osip@atosc.org>.
You can subscribe by writing to: <osip-request@atosc.org>
with a subject set to "subscribe".
History:
=======
The oSIP stack project has been started in September 2000
since the early days of the SIP protocol.
The initial version was quite close to the actual one in
terms of features. The SIP parser and the SIP state machines
were already provided. At this point and till version 0.9.7,
the API was not very clean but osip was already stable,
portable, flexible and compliant with SIP.
After rfc2543 were released, a lot of developments were made
to follow the drafts that were produced prior to the final
release of rfc3261. (around version 0.8.X).
A lot of users were requesting help on the API and were
reporting their difficulties to use it. I have decided
to refine osip into a new osip2 version which would offer
a simpler and nicer API. With a very few exception, only
the API has been changed between 0.9.7 and 2.0.0. From
this version, osip has been much readable.
However, oSIP is still complex to use. There are reasons
for that. oSIP was made to be flexible (which make the API
quite large). oSIP is architecture free (but you need to
understand how it works to use it correctly). oSIP is
implementing only low layers of SIP (so you still can
build malformed messages, or uncompliant ones). oSIP will
not warn you about most errors that you can make.
Be aware, that if you use osip, you still have to read
carefully the rfc. oSIP is not easy to use, but I'm
convinced there are benefits in terms of flexibility.
If you find osip too complex to use, please look for
another adequate solution.
Features:
========
oSIP is a not a complete SIP stack and will never implements
all the specifications. Instead, the goal is to provide
a limited set of features common to any kind of SIP Agents.
Thus oSIP is not oriented towards any particular implementations
and can be used for implementing SIP End-Point, Proxy
or any kind of more specific SIP Agent such as B2BUA.
The minimal common required features for any SIP Agent
provided by osip are describe below.
However, some extra facilities oriented towards SIP End-Points
are provided. Some are considered usefull and stable such as the
dialog management API. One features is particularly not flexible
such as the SDP negotiation facility and you should consider
implementing your own. If you still want
SIP parser:
==========
The initial feature implemented in osip is a SIP parser. There
is not much to say about it: it is capable of parsing and
reformating SIP requests and answers.
The details of the parsing tools available are listed below:
1 SIP request/answer
2 SIP uri
3 specific headers
4 Via
5 CSeq
6 Call-ID
7 To, From, Route, Record-Route...
8 Authentication related headers
9 Content related headers
10 Accept related headers
11 ...
12 Generic header
13 Attachement parser (should support mime)
14 SDP parser
SIP transaction state machines:
==============================
The interesting and somewhat complex feature implemented
by osip is the 4 states machines that applied to the different
transactions defined by the SIP rfc.
SIP defines the following 4 state machines, abreviations
used in osip are provided below:
* ICT : Invite Client Transaction (Section 17.1.1)
* NICT: Non Invite Client Transaction (Section 17.1.2)
* IST : Invite Server Transaction (Section 17.2.1)
* NIST: Non Invite Server Transaction (Section 17.2.2)
As you can notice if you have read the rfc (do it!), those
4 state machines are provided as drawings within the SIP
rfc3261.txt (section 17.1 and 17.2)
As an exemple of what you'll find in the rfc3261, here is the
drawing that apply to the "Invite Client Transaction" (page 127)
|INVITE from TU
Timer A fires |INVITE sent
Reset A, V Timer B fires
INVITE sent +-----------+ or Transport Err.
+---------| |---------------+inform TU
| | Calling | |
+-------->| |-------------->|
+-----------+ 2xx |
| | 2xx to TU |
| |1xx |
300-699 +---------------+ |1xx to TU |
ACK sent | | |
resp. to TU | 1xx V |
| 1xx to TU -----------+ |
| +---------| | |
| | |Proceeding |-------------->|
| +-------->| | 2xx |
| +-----------+ 2xx to TU |
| 300-699 | |
| ACK sent, | |
| resp. to TU| |
| | | NOTE:
| 300-699 V |
| ACK sent +-----------+Transport Err. | transitions
| +---------| |Inform TU | labeled with
| | | Completed |-------------->| the event
| +-------->| | | over the action
| +-----------+ | to take
| ^ | |
| | | Timer D fires |
+--------------+ | - |
| |
V |
+-----------+ |
| | |
| Terminated|<--------------+
| |
+-----------+
Figure 5: INVITE client transaction
As you can expect, with osip an Invite Client Transaction may be
in the CALLING, PROCEEDING, COMPLETED or TERMINATED state. To
"execute" the state machine, you will build events, provide them
to the correct transaction context and the the state of the
transaction will be updated if the event is allowed in the current
state.
Events are divided in three categories:
* SIP messages
* Timers
* transport errors
Other features:
==============
To ease development of SIP portable application, osip
provide abstractions methods for threads, semaphore,
and mutex.
You still have the choice to compile osip without thread
support which you may be required on some embedded platforms.
Please report any porting issue to the mailing list <osip@atosc.org>
(subscribe first!) or directly to me <jack@atosc.org>.
If you are building a new port, I'll certainly think about merging
it.
Other Facilities:
================
oSIP also give small facilities which are completly optional.
Among them, the dialog facility(osip_dialog.h), mainly to
be used by SIP End-Points, is a stable extra feature. It will
allow you to build a structure described in the rfc3261 (Section
12: Dialogs). Once built, you can reuse this information to match
received requests with a particular SIP call or to build a new
request within a particular SIP call.
An old feature has been implemented in osip: a SDP negotiator.
I advise you to not use this old facility which is not powerfull
often uncompliant and not flexible enough. It's also quite
unreadable and poorly written (by me!). I'll delete it anyway in
future version of osip. I have warned you...
However, I'm building a new SDP negotiator (osip_rfc3264.h).
While not being fully ready, I hope to get it completed by the
end of year 2004. It's promising work and I hope it will be
enough flexible to fit any applications. Time will tell.
oSIP finaly contains a MD5 implementation (osip_md5.h) which
you'll find usefull when implementing SIP Digest authentication.
