Description: =========== The GNU oSIP library is an implementation of SIP - rfc3261. Email : firstname.lastname@example.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 <email@example.com>. A Mailing list is available for support: <firstname.lastname@example.org>. You can subscribe by writing to: <email@example.com> 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 <firstname.lastname@example.org> (subscribe first!) or directly to me <email@example.com>. 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.