OSIP Developer Handbook
- This manual guides developers to develop user agents using OSIP stacks
Original title: OSIP User Manual
Original author: Aymeric Moizard
Contact method: jack@atosc.org
Copyright: GNU Free Documentation License
Project website: http://osip.atosc.org
Translation Author: Shan-learning
Contact: cheshanxue@263.net
Summary
"Session Initiation Protocol-Sip is an application layer signaling control protocol. For creating, modifying, and terminating a session of one or more participants. These sessions can be Internet multimedia conference, IP phone or multimedia distribution (Eg, voicemail). Participants of the session can communicate via multicast, meicast, or mixtures of both. "
"The Session Initiation Protocol (SIP) is an application-layer control (signaling) protocol for creating, modifying and terminating sessions with one or more participants. These sessions include Internet multimedia conferences, Internet telephone calls and multimedia distribution. Members in a session can Communicate Via Multicast or via a mesh of unicast relations, or a combination of these. "
copyright
The copyright of this article belongs to Aymeric Moizard. Copy, distribute, and customization in "GNU FREE Documentation License" (version 1.1 or any version of the Free Software Fund). It should be noted that references to any chapter of this document (including this Chinese translation) need to list their titles, started text and end text, and indicate that documents are protected by "GNU Free Documentation Licence".
. Copyright (c) 2001 Aymeric MOIZARD Permission is granted to copy, distribute and / or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST . ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
Foreword
The translator revised some subtle errors in the original text. This document is completed independently of the translator, and there is no such thing as translation, so any suggestions and points are very welcome. The way in contact is via email to cheshanxue@263.net
index
Abstract. 1
Copyright. 1
Foreword. 1
Index. 2
Text. 3
Chapter 1 SIP protocol. 3
SIP independent and media. 3
SIP is independent of the transport layer. 3SIP has good scalability. 3
SIP and end user service. 3
Chapter II SIP Protocol Overview. 4
SIP syntax. 4
SIP transaction. 5
SIP session. 5
Server behavior. 7
Chapter III OSIP Development Library. 7
Goal. 7
The level of development. 7
Grammatical analyzer. 7
Finite state machine. 8
Transaction management. 8
Who will benefit from OSIP 8
Allowable platforms. 8
Chapter 4 OSIP Syntax Analyzer. 8
Document. 8
SIP-URL (SIP address). 9
The syntax structure and design goal defined by the URL. 9
URL_T structure API 9
URL_PARAM_T and URL_HEADER_T API 11 API 11
SIP Headers operation API 13
SIP Message operation API 17
Syntax Analysis Some Programs. 23
Structure information is converted into string. 26
How to improve the performance of the grammar analyzer. 27
Chapter 5 limited state machine. 27
Transaction and events (events) 27
Definition and purpose of transaction processing. 27
The definition and purpose of the event. 28
API 28 for transaction processing
Return. 31
Some useful macros (Macros) 32
Guide for a limited state machine. 33
Initialize the OSIP Stack. 33
Assign and initialize the OSIP_T structure. 33
Send Event (Events) Control Things 34
PROXY's attention. 36
Build your own architecture. 36
Postscript. 36
text
Chapter 1 SIP protocol
The SIP protocol is a signaling protocol for initiating, controlling and ending multimedia sessions. It is published by IETF (http://www.ietf.org).
SIP is an integral part of IETF to bring a telephone service into many protocols (which forms a SIP system protocol stack with many protocols such as SDP, RTP, RTCP, RTSP, RSVP, TRIP). It will become a developed IP phone - one of the standards of this vigorous telecommunications industry. Just like the email protocol, SIP will become more popular and popular ...
SIP independent and media
Traditional telephones use a media encoding member (as is the time slot and PCM concept I am known). This way will now be terminated. Our phones can connect to TV, connect the camera to communicate with different quality assurance and different coding methods. SIP has functions such as media negotiation. Any multimedia application (for example: game, remote teaching) can use SIP to establish a session.
SIP is independent of the transport layer
SIP is not closely combined with any transport layer. This concept will enable SIP to be subject to the smallest interoperability in the third generation network. The requirements of the wireless phone (eg, roaming feature) are also cared. SIP Perfect Conception makes it suitable as a signaling protocol as a new cellular phone era.
SIP has good scalability
6 types of transactions (INVITE, BYE, CANCEL ...) are defined in RFC2543. These transactions are used for media negotiation, creation, modify, and end calls. Many other services have been provided (e.g., H.323 systems), but SIP is reused with its purpose-based design and transaction model (for server being transparent, which is used to create a secondary service using new type transaction). Here is a possible service list, some of which have been implemented.
SMS for real-time information
Book or notice for conference management
Delegation, used for call transfer and other management
SIP and end user service
"SIP transparent supports name mapping and redirect services, providing ISDN and smartphone telephone services. These features make personal movements possible."
Reference reading: rfc2543.txt (chapter 1.1)
The SIP server is used to locate user positioning information for users and distribution requests. These ways make the end user agent launched a few requests and gain a variety of services.
Many scales are defined in the recommended document (query SIP-related DRAFT). We can also add personalized telephone features and keep interact with existing existing servers. Chapter 2 SIP Protocol Overview
This chapter is not for detailed description RFC (we must read the RFC acquisition protocol details), which provides quick, incomplete protocol syntax and behavioral overview.
SIP syntax
SIP is a protocol based on UTF8 text encoding format (this makes its message good readability, and easy to debug). The syntax information of the request, address (URL), a response, and a header field is described in the SIP protocol. The entire syntax information is described in the form of a Bax paradigm that can be obtained in Columbia.
These syntax definitions refer to Mail and HTTP definitions. SIP defines the type of six requests. The most basic method is:
INVITE ACK CANCEL BYE Info Options
As we see in the request BNF definition (refer to RFC2543 Chapter 3), SIP is not limited to a short method list that has been defined in the specification, and the scalability is fully considered. Not limited to the list above, any other type of request can be processed by OSIP. Of course, all of this, depending on everyone's notification and contributing new possible sample programs, etc. The current development library does not have much effort to clearly support the ability to provide development SIP phones.
INVITE SIP: Jack@atosc.org Sip / 2.0
VIA: SIP / 2.0 / udp Home.SIPWORLD.ORG
TO: SIP: JACK@atosc.org
From: Sip: cha@sipworld.org
Call-ID: 35778645354@home.sipworld.org
CSEQ: 1 Invite
Contact: Sip: cha@home.sipworld.org
Content-Type: Application / SDP
Content-Length: 267
V = 0
O = USER1 53655765 2353687637 in IP4 128.3.4.5
S = MBONE AUDIO
i = discussion of Mbone Engineering Issues
e=mbone@somewhere.com
C = in IP4 128.3.4.5
T = 0 0
M = Audio 3456 RTP / AVP 0
a = rtpmap: 0 pcmu / 8000
Sample 2-1 Invite request message content
The INVITE request is used to initialize and customize sessions. Now, Chase CHA calls from Sipword.com in Atos.org Jack. This request will be sent to the SIP proxy server managed by Atosc.org, which will be forwarded to the Jack-connected communication device, and the device has a real IP address.
SIP transaction
SIP uses things control and management sessions. Transactions (INVITE, CANCEL, BYE ...) is usually a memory of current session progressed. Some other things (Subscribe, Notify ...) are not necessary to convers a session. One thing is composed of a request and a response (some intermediate response and final response). The following headers: TO, FROM, CALL-ID and CSEQ are used to identify associated messages in a transaction.
SiP also defines the rules that retransmitted in a transaction in a transaction using an unreliable transport layer protocol (recommended using UDP in the IP network).
UAC1 UAS2
Jacks | INVITE |
Initiate A | -----------------> | BOB'S
Call | | Phone Starts
| 180 ringing | Ringing | <----------------- |
| 180 ringing |
| <----------------- |
| 200 ok |
| <----------------- |
| ACK |
| -----------------> |
Sample 2-2 Invite transaction
This is a display of the most basic point-to-point signaling call. There is only two call processes between two SIP user agent (UAC / UAS). (The situation of retransmission is not displayed)
SIP session
Transactions is used by the user agent to control sessions. A session always has an Invite message. SIP defines a series of response status codes. A proxy server can answer your very well-known "404 User Not Found" (when we use HTTP, you often encounter "HTTP 404 - Did not find file"). Error also points different levels. One thing is a call failed, but may still try new positioning and make a new transaction call. Answer 3XX is used to redirect mechanisms; 4xx, 5xx, 6xx response each is used to identify terminal errors, server errors, and global errors.
Bob Home.Net Jack (atosc.org)
UA1 Redirect UA2
| Register |.
| --------------> |.
| 200 ok |.
| <-------------- |.
.
Later ....
.
Register |
<-------------- |
200 OK |
--------------> |
.
Later ....
INVITE JACK@Home.net.
| --------------> |.
| 302 Moved Temporarily.
| <-------------- |.
| ACK |.
| --------------> |.
| Invite jack@office.atosc.org |
| AUDIO |
| ------------------------------> |
| 180 ringing |
| <------------------------------
| 180 ringing |
| <------------------------------
| 200 ok |
| <------------------------------
| ACK JACK@office.atosc.org |
------------------------------> |.
Later.
.
| Invite Bob@bob.home.net |
| AUDIO VIDEO |
| <------------------------------
| 200 ok |
| ------------------------------> |
| ACK BOB@bob.home.org |
| <------------------------------
.
Later.
.
| BYE JACK@office.atosc.org |
| ------------------------------> |
| 200 ok |
| <------------------------------
| | |
Sample 2-3 A complete session
First, all user agents are registering the registration server (in this case, the server has a registration service function. The registration server is the location server).
The session is initiated by the INVITE transaction, contacts in jack@home.net. A redirect server uses the redirection function to feed back address information of the Jack office to the initiated call end UA1. UA1 acquires information of the new target address, initiates a call to jack@atosc.org. UA2 first rings, JACK will send back the 200 OK successful response. After a few minutes, Jack and Bob use their camera to see each other's video information. The new session media parameter modified by Jack initiated INVITE to interact, and finally ended by BOB.
Server behavior
SIP defines behavioral description for the agent, redirect and registering the server (I understand it as a limited state machine), and you should also read RFC ...
Typically, a user agent initiates a request to the proxy server of the domain. For example, we don't know the specific location of the communicress between each other, we call each other in the user @ domain name format. The domain proxy server (for security considerations, where you can join the firewall function) Use the DNS query to locate the other party in which domain is in. Once the other party's domain server is looking for, it is safe (for security reasons, IPSec authentication may be used), requested to be forwarded. The other domain broker server performs specific positioning. If the other party is available (that is, the other party has already registered in his domain registration server), the other domain server is forward to the true user. In the local network, other protocol standards are used to find the final called user (such as finger ...)
Chapter 3 OSIP Development Base
In this section, I hope that you have a good knowledge foundation for the SIP system, and simple refers to the SIP RFC documentation. If you plan to use SIP, you have to read RFC2543 carefully.
aims
The OSIP project started in July 2000, the first release version was May 2001 (0.5.0).
The OSIP development library is the first free software project. In the third-generation network system, more and more telecom operators will use IP phones (Linux also become a lucky man who supports the platform). One side of development is in the near future, Linux will support more multimedia tools. OSIP, as a SIP development library, will allow interoperability registration servers, user agent (software phones), and proxy servers. All of these will add Linux that will be the opportunity of the next generation of telephone products. But OSIP's goal is not only in PC applications. OSIP has sufficient flexible and tiny to meet its specific requirements in a small operating system (such as handheld devices). Publish from version 0.7.7, support for threads as an option. As a developer, we can choose when the application is designed. OSIP will be perfect for cellular equipment and embedded systems in the future. OSIP is well known to the real-time operating system vxworks, and other support will be simple things.
Development level
Grammar analyzer
OSIP now supports UTF8 and complete SIP syntax. The 0.7.0 version contains a SIP syntax analyzer with very well-adaptive. Also, the new grammar analyzer was announced on July 25, 2001, and there may be some bugs. If discovered, be sure to report osip@atosc.org, I will fix them.
The OSIP contains a syntax analyzer that can read and write any SIP messages described in the RFC. At present, OSIP can analyze a small part of the head, such as VIA, Call-ID, To, from, Contact, CSEQ, Route, Record-Route, Mime-Version, Content-Type, and Content-Length. All other heads are stored in a string format. More heads will be increased.
Now, the SIP syntax analyzer supports multiple properties in MIME format (this part has not been tested).
Sometimes undesirable behavior may happen. The message after OSIP analysis may have some changes. OSIP cannot maintain the following reliability: (However, OSIP keeps complete adaptability)
The order of the head field
A plurality of heads appear in a row
Additional spaces in the field
LWS (internal CRLF)
Quotation marks in TO, FROM, Contact ... field
Finite State Machine
4 limited state machines have been tested. And in the eighth plus SIPIT, the interoperability test is performed with about 30 equipment, which is very stable.
Transaction management
OSIP publishes an easy-to-use user interface. This is the core of the OSIP library by using 4 limited state machines. Each thing uses a separate FIFO that is filled by an external module. Event (events) is included in the queue through the user request. A series of dynamic callback registrations, for applications to know the progress of each thing.
Built a application on OSIP requires many modules.
First, we build a module that manages transport layer characteristics. This makes OSIP independently of the transport layer.
Later, we will need to build a module for clock management (a simple, far from achieving excellent, a sample has been provided). This module will be responsible for retransmission and decide when to delete the transaction context is safe.
Finally, we need to build a multimedia application part. This part will have to maintain and update the session (the session is dependent on transaction).
Transaction management has been tested, performance is very stable. And OSIP does not require too much memory running very quickly. Since 0.7.0, the development library can be used in multi-threaded mode or not using, which is completely determined by the developer.
Who will benefit from OSIP
OSIP provides a simple interface for adding multimedia applications for SIP. Also, OSIP is not closely combined with any SIP developer and operating system. We can build end-user agents, stateless proxy servers, redirect servers and gateways. If you develop Stateful Proxy, you should read the last "PROXY development attention" and the previous transaction management. Allowable platform
The development library construction is convenient to portability, which can be quickly applied to any system of POSIX. It is already in Solaris, HP UNIX, RT OS VxWorks and Windows. GNU / Linux (2.2.16 and 2.4.7) is used for initial development.
Chapter 4 OSIP Syntax Analyzer
file
./libosip-x.x.x/parser is the source code directory of the SIP syntax analyzer.
./libosip-x.x.x is the directory of the development library.
#INLCUDE
SIP-URL (SIP address)
URL defined grammatical structure and design goals
The URL is used to describe each entity distributed in the SIP network: SIP user agent, positioning server, SIP proxy server, SIP redirect server, etc. These entities must have their complete SIP URL to identify. Use the URL_T format in the development library to define the following fields: "to", "from", "contact", "route" and "replard-route"; list_t extension defines the fixed parameters contained in the URL and unfixed heads. value.
SIP URL structure definition:
Typedef struct _sipurl_t {
Char * scheme;
Char * username;
Char * password;
Char * host;
Char * port;
List_t * URL_PARAMS;
List_t * URL_HEADERS;
URL_T
URL_T structure API
URL_INIT
[Function Description]
Allocate memory and initialize the structure. (There will be a lot of initialization functions in the API below. In general, allocation memory calls Malloc, release memory callback, because the author has changed the modified function of the call for Smalloc and SFREE, the first assignment is Some variables are assigned 0 or NULLs.
[Parameter Description]
INT URL_INIT (URL_T ** URL);
Successful returns 0, failure will automatically exit.
URL_FREE
[Function Description]
The URL_T structure completed by the release operation and the variable in the URL_T structure is empty.
[Parameter Description]
Void URL_FREE (URL_T * URL);
URL_PARSE
[Function Description]
Decompose the input string information and assign the value to the defined URL_T structure variable.
[Parameter Description]
INT URL_PARSE (URL_T * URL, CHAR * filed_value);
Successfully returned 0, failed to return -1, and the return value of the rear function is generally defined.
URL_2CHAR
[Function Description]
Conversion to the structured information in a URL_T and combine the value to a string.
[Parameter Description]
INT URL_2CHAR (URL_T * URL, Char ** Field_Value);
Successfully returned 0.
Char ** Field_Value will initialize in URL_2CHAR.
URL_CLONE
[Function Description]
Copying two URL_T structural instances (using standard functions Memcpy can also be done, but for the linked list is not necessarily, no test).
[Parameter Description]
INT URL_CLONE (URL_T * URL, URL_T ** DEST);
Successfully returned 0, failed to return -1.
URL_SETSCHEME
URL_SETUSERNAME
URL_SETPASSWORD
URL_SETHOSTURL_SETPORT
[Function Description]
Set the summary section of the URL, user name, password, host and port
[Parameter Description]
Void URL_SETSCHEME (URL_T * URL, CHAR * Scheme);
Void URL_SETUSERNAME (URL_T * URL, CHAR * Username);
Void URL_SETPASSWORD (URL_T * URL, CHAR * Password);
Void URL_SETHOTHOST (URL_T * URL, CHAR * HOST);
Void URL_SETPORT (URL_T * URL, CHAR * Port);
URL_GETSCHEME
URL_GETUSERNAME
URL_GETPASSWORD
URL_GETHOST
URL_GETPORT
[Function Description]
Get the value of some of the specific parts of the URL and return.
[Parameter Description]
Char * URL_GETSCHEME (URL_T * URL);
Char * URL_GETUSERNAME (URL_T * URL);
Char * URL_GETPASSWORD (URL_T * URL);
Char * URL_GETHOST (URL_T * URL);
Char * URL_GETPORT (URL_T * URL);
Other related useful functions API
#define url_set_transport_udp (u) URL_PARAM_ADD (U-> URL_PARAMS, "Transport", "UDP")
#define url_set_transport_tcp (u) URL_PARAM_ADD (U-> URL_PARAMS, "TRANSPORT", "TCP")
#define URL_SET_TRANSPORT_SCTP (U) URL_PARAM_ADD (U-> URL_PARAMS, "Transport", "SCTP")
#define url_set_transport_tls (u) URL_PARAM_ADD (U-> URL_PARAMS, "Transport", "TLS")
#define url_set_transport (u, t) URL_PARAM_ADD (U-> URL_PARAMS, "Transport", T)
#define url_set_user_phone (u) URL_PARAM_ADD (U-> URL_PARAMS, "User", "Phone")
#define url_set_user_ip (u) URL_PARAM_ADD (U-> URL_PARAMS, "User", "IP")
#define url_set_user (u, user) URL_PARAM_ADD (U-> URL_PARAMS, "User", USER)
#define url_set_method_invite (u) URL_PARAM_ADD (U-> URL_PARAMS, "Method", "Invite")
#define url_set_method_ack (u) URL_PARAM_ADD (U-> URL_PARAMS, "Method", "ACK")
#define URL_SET_METHOD_OPTIONS (U) URL_PARAM_ADD (U-> URL_PARAMS, "Method", "Options")
#define url_set_method_bye (u) URL_PARAM_ADD (U-> URL_PARAMS, "Method", "Bye") # define url_set_method_cancel (u) URL_PARAM_ADD (U-> URL_PARAMS, "Method", "ca Zancel")
#define url_set_method_register (u) URL_PARAM_ADD (U-> URL_PARAMS, "Method", "Register")
#define URL_SET_METHOD (U, M) URL_PARAM_ADD (U-> URL_PARAMS, "Method", M)
#define url_set_ttl (u, t) URL_PARAM_ADD (U-> URL_PARAMS, "TTL", T)
#define url_set_maddr (u, m) URL_PARAM_ADD (U-> URL_PARAMS, "MADDR", M)
These functions are necessary to understand (refer to OSIP / URLS.H)
URL_PARAM_T and URL_HEADER_T API
You can refer to the difference between the parameters and the head value of the detail. In the PARAM function below, you can complete the operation of URL_HEADER_T as long as you change the param to Header. These functions have completed the initialization, decomposition, setting, and cloning of the structure.
The structure of the parame parameter is defined as follows:
TypedEf struct _url_parm_t {
CHAR * GNAME;
Char * gvalue;
URL_PARAM_T;
The structure of the HEADER parameter is as follows:
TypedEf struct _url_parm_t {
CHAR * GNAME;
Char * gvalue;
} URL_HEADER_T
URL_PARAM_INIT
[Function Description]
Initialize the URL_PARAM_T structure.
[Parameter Description]
INT URL_PARAM_INIT (URL_PARAM_T ** URL_PARAM);
Successfully returned 0.
URL_PARAM_FREE
[Function Description]
Release the URL_PARAM_T structure instance corresponding to the URL_PARAM.
[Parameter Description]
INT URL_PARAM_FREE (URL_PARAM_T * URL_PARAM);
Successfully returned 0.
URL_PARAM_SET
[Function Description]
Assign strings PNAME (parameter name) and PVALUE (value corresponding to parameter name) to the URL_PARAM_T structure.
[Parameter Description]
Void URL_PARAM_SET (URL_PARAM_T * URL_PARAM, CHAR * PNAME, CHAR * PVALUE);
URL_PARAM_ADD
[Function Description]
Add a value to the parameter list in the URL_T structure to the URL_T.
[Parameter Description]
INT URL_PARAM_ADD (list_t * url_params, char * pname, char * pvalue);
Successfully returned 0, failed to return -1.
URL_PARAM_FREELIST
[Function Description]
Release the parameter list structure in URL_T.
[Parameter Description]
Void URL_PARAM_FREELIST (List_t * URL_PARAMS);
URL_PARAM_GETBYNAME
[Function Description]
Find URL_PARAM containing PNAME in the list_t list, and assigns this parameter to the URL_PARAM_T ** URL_PARAM. The final result is stored in URL_PARAM_T ** URL_PARAM. [Parameter Description]
Void URL_PARAM_GETBYNAME (List_t * URL_PARAMS, Char * PNAME, URL_PARAM_T ** URL_PARAM)
The following is given to two operational functions for parameters and head values:
INT URL_UPARAM_ADD (URL_T * URL, Char * PNAME, Char * PVALUE)
#define url_uparam_add (f, n, v) url_param_add (f-> URL_PARAMS, N, V)
INT URL_UPARAM_GETBYNAME (URL_T * URL, CHAR * PNAME, URL_PARAM_T ** URL_PARAM)
#define url_uparam_getbyname (f, n, uh) URL_PARAM_GETBYNAME (F-> URL_PARAMS, N, UH)
For use of PARAM, please take care of the standard RFC2543.
SIP Headers action API
About 40 fields are defined in RFC2543. SIP Message (SIP message) is made up of this series of fields. The following API definition is divided and elaborated, and the first part of the API is used to create, assign, analyze, and print the head element of the SIP; the second part shows a specific API, here I only show "to" Unique function; Part III is some extended API, which is not only suitable for "to" field, but also suitable for "from", "contact", "route", "Record-Route", and other heads, Head scalability.
The structure of TO is defined as follows:
Typedef struct_to_t {
Char * displaphname;
URL_T * URL;
List_t * gen_params;
} TO_T;
The SIP syntax analyzer is able to analyze the following heads: VIA, TO, FROM, CSEQ, Call-ID, Contact, Route, Record-Route, Content-Type, Content-Length, Mime-Version. Other heads are accessed by special APIs in string.
You can subconsciously replace "TO_" to "VIA _", "From _", "CSEQ _", "Call_ID _", "Contact _", "Route _", "Record_Route _", "Content_Type _", "Content_length_", "" MIME_VERSION_ ".
If you want to understand the structure definition of each field, read osip / smsgtypes.h; want to know the function corresponding to the field, read the OSIP / SMSG.H library file, which will be in depth for function description, parameter description and use Understanding.
Part 1: Creating, assigning, analyzing, and printing the head elements of SIP
TO_INIT
[Function Description]
Initialize the To field.
[Parameter Description]
INT to_INIT (TO_T ** TO);
Successful returns 0, do not have to make a failure judgment process.
TO_FREE
[Function Description]
Release the To field.
[Parameter Description]
Void to_free (to_t * to);
TO_2CHAR
[Function Description]
Transform the TO structure to a string.
[Parameter Description]
INT to_2CHAR (TO_T * TO, CHAR * filed_value);
Successfully returned 0, failed to return -1.
TO_CLONE
[Function Description]
Cloning to information to the target
[Parameter Description]
INT to_CLONE (TO_T * TO, TO_T ** DEST);
Part II: TO unique API
TO_SETDISPLAYNAME [Function Description]
Set Display Name inside the To field.
[Parameter Description]
Void to_setdisplayName (To_t * to, char * value);
TO_GETDISPLAYNAME
[Function Description]
Extract Display Name from the To field and return it.
[Parameter Description]
Char * to_getdisplayname (to_t * to);
TO_SETURL
[Function Description]
Set the URL value in the To field.
[Parameter Description]
Void to_SETURL (TO_T * TO, URL_T * URL);
TO_GETURL
[Function Description]
Extract the URL value from the TO field.
[Parameter Description]
URL_T * TO_GETURL (TO_T * TO);
TO_PARAM_ADD
[Function Description]
Add a Gen_PARAM in the To field
[Parameter Description]
INT to_PARAM_ADD (TO_T * TO, CHAR * NAME, CHAR * VALUE);
Successfully returned 0, failed to return -1.
note:
#define to_param_add (t, n, v) generic_param_add ((t) -> gen_params, n, v)
TO_PARAM_GET
[Function Description]
Select the contents of the POS of List_t in the TO structure.
[Parameter Description]
INT to_PARAM_GET (TO_T * TO, INT POS, Generic_PARAM_T ** GP);
Successfully returned POS, failed to return -1;
note:
#define to_param_get (t, i, gp) from_param_get ((from_t *) t, i, gp)
TO_SETTAG
[Function Description]
Set the value of TAG in the To field.
[Parameter Description]
void to_settag (to_t * to, char * tag)
note:
#define to_set_tag (t, v) generic_param_add ((t) -> Gen_Params, "Tag", V)
TO_GETTAG
[Function Description]
Return the TAG value in the TO structure to generic_param_t structure
[Parameter Description]
void to_gettag (to_t * to, generic_param_t ** DEST);
#define to_gettag (t, gp) generic_param_getbyname ((T) -> Gen_Params, SgetCopy ("tag"), GP)
TO_PARAM_GETBYNAME
[Function Description]
See the value of PNAME in the To field
[Parameter Description]
INT TO_PARAM_GETBYNAME (to_t * to, char * pname, generic_param_t ** DEST)
Success return 0
#define to_param_getbyname (t, n, gp) generic_param_getbyname ((t) -> Gen_Params, N, GP)
Part III: Extended API
The parameters of this section are components of many fields, such as "to", "from", "contact", "route", "record-route", and "Conten-Type".
TO structure and generic_param_t structure
Typedef struct _generic_param_t {
CHAR * GNAME;
Char * gvalue;
} generic_param_t
Typedef_to_t {
Char * displaphname;
URL_T * URL;
List_t * gen_params;
} TO_T;
Provide a sample:
TO: "chenshx"
[Function Description]
Initialize the generic_param_t structure.
[Parameter Description]
INT generic_param_init (generic_param_t * gen_param)
Successfully returned 0.
Generic_Param_Free
[Function Description]
Release the generic_param_t structure.
[Parameter Description]
Void generic_param_free (generic_param_t * gen_param);
Generic_Param_set
[Function Description]
Set PNAME and PVALUE to the generic_param_t structure.
[Parameter Description]
Void generic_param_set (generic_param_t * gen_param, char * pname, char * pvalue);
Generic_Param_GetName
Generic_Param-setName
Generic_Param_GetValue
Generic_Param_SetValue
[Function Description]
These four functions are mainly operated with the generic_param_t structure, and the GNAME and GVALUE in the structure are validated and assigned.
[Parameter Description]
Char * generic_param_getname (generic_param_t * gen_param)
Void generic_param-setname (generic_param_t * gen_param, char * gname)
Char * generic_param_getvalue (generic_param_t * gen_param)
void generic_param_setvalue (generic_param_t * gen_param, char * gvalue)
Successfully returns char *, otherwise returns NULL.
Generic_Param_Add
[Function Description]
Assign Name and its corresponding Value to the Gen_Params list.
[Parameter Description]
INT generic_param_add (list_t * gen_params, char * name, char * value);
Successfully returned 0.
Generic_Param_GetByname
[Function Description]
Look for the value named Name in Gen_Params in the list_t list and returns to the generic_param_t structure.
[Parameter Description]
INT generic_param_getbyname (list_t * gen_params, char * name, gener_param_t ** gen_param);
Successfully returned 0.
Generic_Param_Freelist
[Function Description]
Release Gen_Params in the List_T structure
[Parameter Description]
Void generic_param_freeelist (list_t * gen_params);
SIP Message operation API
SIP Message Structure Definition Division: The first part is a row, which is a REQUEST-URI or RESPONSE STATUS Code, which is defined separately as startline_t; the second part is some columns; the last part is other heads of some columns Ministry and accessories or companions.
At present, the SIP_T structure has not been completed, non-"from", "to", "call-id", "cseq", "via", "contact", "route", "repland-route", "mime-version", "Content-Type", "Conten-Length" is stored in a series of universal headers.
The structure is defined as follows:
Typedef struct _sip_t {
StartLine_t * startline; / * for all header flly meansMented by osip * /
From_t * from;
TO_T * TO;
CALL_ID_T * CALL_ID;
CSEQ_T * CSEQ;
List_t * vias;
List_t * Contacts;
List_t * record_routes;
List_t * routes;
Content_type_t * content_type;
Content_length_t * contentLength;
MIME_VERSION_T * MIME_VERSION;
/ * for all other headers * /
List_t * headers;
/ * for all attachments * /
List_t * bodies;
} SIP_T;
MSG_init
[Function Description]
Initialize the SIP_T structure.
[Parameter Description]
INT msg_init (SIP_T ** MSG);
Successfully returned 0.
MSG_Free
[Function Description]
Release the information of the SIP_T structure.
[Parameter Description]
Void msg_free (SIP_T * MSG);
MSG_PARSE
[Function Description]
Decompose string and assign it to instances of SIP_T structures.
[Parameter Description]
INT MSG_PARSE (SIP_T * MSG, Char * Field_Value);
Successfully returned 0, failed to return -1.
MSG_2CHAR
[Function Description]
Transform the information of the SIP_T structure into a string.
[Parameter Description]
INT MSG_2CHAR (SIP_T * MSG, Char ** Field_Value);
Successfully returned 0, failed to return -1.
MSG_clone
[Function Description]
Create a copy for an instance of the SIP_T structure, and has not been implemented.
[Parameter Description]
MSG_setheader
[Function Description]
Add a field to SIP_T.
[Parameter Description]
INT MSG_SETHEADER (SIP_T * SIP, CHAR * HNAME, CHAR * HVALUE);
Successfully returned 0, failed to return -1.
MSG_getheader
[Function Description]
Take the SIP_T structure When the POS field in the header section, and assign a value to the Header_t structure.
[Parameter Description]
INT MSG_GetHeader (SIP_T * SIP, INT POS, Header_t ** Dest);
Successfully returned 0, failed to return -1.
MSG_Header_GetByname
[Function Description]
Find the HEADER section in the SIP_T structure, take the value of the POS of the field name of the word hname, and assign this field to the Header_t structure.
[Parameter Description]
INT msg_header_getbyname (char * hname, sip_t * sip, int pos, header_t ** DEST);
Successfully returned POS, failed to return -1.
MSG_SETCALL_ID
[Function Description]
Set the value of the Call_ID in the SIP_T structure.
[Parameter Description]
INT MSG_SETCALL_ID (SIP_T * SIP, CHAR * HVALUE);
Successfully returned 0, failed to return -1.
MSG_GetCall_ID
[Function Description]
Returns the value of Call_ID in the SIP_T structure.
[Parameter Description]
Call_id_t * msg_getcall_id (SIP_T * SIP);
Successfully returns the value of the Call_ID in the SIP_T structure.
MSG_setcseq
[Function Description]
Set the value of the CSEQ in the SIP_T structure.
[Parameter Description]
INT MSG_SETCSEQ (SIP_T * SIP, CHAR * HVALUE);
Successfully returned 0, failed to return -1.
MSG_Getcseq
[Function Description]
Take the value of CSEQ in the SIP_T structure.
[Parameter Description]
CSEQ_T * MSG_GETCSEQ (SIP_T * SIP);
MSG_SETCONTACT
[Function Description]
Set the value of the Contact in the SIP_T structure.
[Parameter Description]
INT MSG_SETCONTACT (SIP_T * SIP, CHAR * HVALUE);
Successfully returned 0, failed to return -1.
MSG_GetContact
[Function Description]
Take the value of the Contact in the SIP_T structure.
[Parameter Description]
INT MSG_GETCONTACT (SIP_T * SIP, INT POS, Contact_t ** Contact);
Successfully returned 0, failed to return -1.
Msg_setfrom
[Function Description]
Set the FROM field in the SIP_T structure.
[Parameter Description]
INT MSG_SETFROM (SIP_T * SIP, CHAR * HVALUE);
Successfully returned 0, failed to return -1.
MSG_GetFrom
[Function Description]
Read the SIP_T structure in the Word forged value.
[Parameter Description]
From_t * msg_getfrom (SIP_T * SIP);
MSG_SETTO
[Function Description]
Set the value of the to field in the SIP_T structure.
[Parameter Description]
INT MSG_SETTO (SIP_T * SIP, CHAR * HVALUE);
Successfully returned 0, failed to return -1.
MSG_Getto
[Function Description]
Read the value of the To field in the SIP_T structure.
[Parameter Description]
TO_T * MSG_Getto (SIP_T * SIP);
MSG_setvia
[Function Description]
Add a VIA field at the end of the SIP_T structure.
[Parameter Description]
INT MSG_SETVIA (SIP_T * SIP, CHAR * HVALUE);
Successfully returned 0, failed to return -1.
MSG_Appendvia
[Function Description]
In the SIP_T structure, an VIA field begins.
[Parameter Description]
INT MSG_APpendvia (SIP_T * SIP, CHAR * HVALUE);
Successfully returned 0, failed to return -1.
MSG_GetVia
[Function Description]
Read the value of the POS of the VIA field in the SIP_T structure.
[Parameter Description]
INT MSG_GETVIA (SIP_T * SIP, INT POS, VIA_T ** VIA);
Successfully returned 0, failed to return -1.
MSG_SETRECORD_ROUTE
[Function Description]
Add a new Record Route field when the SIP_T structure is added.
[Parameter Description]
INT MSG_SETRECORD_ROUTE (SIP_T * SIP, CHAR * HVALUE);
Successfully returned 0, failed to return -1.
MSG_GETRECORD_ROUTE
[Function Description]
Read the value of the POS POS of the RECORD_ROUTE field in the SIP_T structure.
[Parameter Description]
INT MSG_GETRECORD_ROUTE (SIP_T SIP, INT POS, RECORD_ROUTE_T ** DEST);
Successfully returned 0, failed to return -1.
MSG_SETROUTE
[Function Description]
Add a Route field to the SIP_T structure.
[Parameter Description]
INT MSG_SETROTE (SIP_T * SIP, CHAR * HVALUE);
Successfully returned 0, failed to return -1.
MSG_Getroute
[Function Description]
Read the value of the POS of the Route field in the SIP_T structure.
[Parameter Description]
INT MSG_GETROUTE (SIP_T * SIP, INT POS, ROUTE_T ** ROUTE);
Successfully returned 0, failed to return -1.
MSG_SETCONTENT_LENGTH
[Function Description]
Set the value of the Content_length field in the SIP_T structure.
[Parameter Description]
INT MSG_SETCONTENT_LENGTH (SIP_T * SIP, CHAR * HVALUE);
Successfully returned 0, failed to return -1.
MSG_GETCONTENT_LENGTH [Function Description]
Returns the value of Content_Length in the SIP_T structure.
[Parameter Description]
Content_length_t * msg_getcontent_length; SIP_T * SIP
MSG_setContent_Type
[Function Description]
Set the value of the Content_Type field in the SIP_T structure.
[Parameter Description]
INT MSG_SETCONTENT_TYPE (SIP_T * SIP, CHAR * HVALUE);
Successfully returned 0, failed to return -1.
MSG_GetContent_Type
[Function Description]
Read the value of the Content_Type field in the SIP_T structure.
[Parameter Description]
Content_type_t * msg_getcontent_type (SIP_T * SIP);
MSG_SETMIME_VERSION
[Function Description]
Set the value of the MIME_VERSION field in the SIP_T structure.
[Parameter Description]
INT MSG_SETMIME_VERSION (SIP_T * SIP, CHAR * HVALUE);
Successfully returned 0, failed to return -1.
MSG_GETMIME_VERSION
[Function Description]
Read the value of the MIME_VERSION field in the SIP_T structure.
[Parameter Description]
MIME_VERSION_T * MSG_GETMIME_VERSION (SIP_T * SIP);
Syntax Analysis Some Programs
Some beneficially developed macro definitions, which are used to test a string with flag messages in the message, such as the type of message, the request method, and the status code of the response.
#define msg_is_response (respon) (Resp-> strtline-> statuscode! = null)
#define msg_is_request (req) (req-> strtline-> statuscode == null)
#define msg_is_invite (msg) (0 == Strncmp (msg-> strtline-> SIPMETHOD, "Invite", 6))
#define msg_is_ack (msg) (0 == Strncmp (msg-> stratline-> SIPMETHOD, "ACK", 6))
#define msg_is_bye (msg) (0 == STRNCMP (msg-> strncmp (msg-> strncmp )-> SIPMETHOD, "BYE", 6))
#define msg_is_register (msg) (0 == Strncmp (msg-> strncmp (msg-> stratline-> SIPMETHOD, "Register", 6))
#define msg_is_cancel (msg) (0 == Strncmp (msg-> strtline-> SIPMETHOD, "CANCEL", 6))
#define msg_is_options (msg) (0 == Strncmp (msg-> strncmp (msg-> strncmp "-> SIPMETHOD, "Options", 6))
#define msg_is_info (msg) (0 == Strncmp (msg-> strncmp (msg-> strncmp )-> SIPMETHOD, "INFO", 6))
#define msg_is_prack (msg) (0 == Strncmp (msg-> strncmp "-> SIPMETHOD, "PRACK", 6))
#define msg_is_status_1xx (MSG) (0 == Strncmp (msg-> strncmp (msg-> strtline-> statuscode, "1", 1)) # define msg_is_status_2xx (msg) (0 == Strncmp (msg-> strng-> statuscode, "2" ,1))
#define msg_is_status_3xx (msg) (0 == Strncmp (msg-> strnline-> statuscode, "3", 1))
#define msg_is_status_4xx (MSG) (0 == Strncmp (msg-> strnplan-> statuscode, "4", 1))
#define msg_is_status_5xx (msg) (0 == Strncmp (msg-> strnline-> statuscode, "5", 1))
#define msg_is_status_6xx (msg) (0 == Strncmp (msg-> stratline-> statuscode, "6", 1))
#define msg_test_code (resp, code) (resp -> strtline-> statuscode! = null /
&& code == (int) Satoi (Resp-> strtline-> statuscode))
#define msg_is_responsefor (resp, requestname) /
(0 == Strcmp (Resp-> CSEQ-> Method, RequestName)))
For other related APIs, be sure to refer to OSIP / SMSG.H empty content.
The syntax analysis of this library needs to do the following initialization before running, the following functions must be used, and can only be operated!
Int parse_init ();
For the process of defining the structure, you can call so-called standard functions. For example, SIP_T and FROM_T structures, you can initialize the structure using the XXX_INIT function (this includes initial assignment and memory allocation, etc.). You must call the release structure XXX_Free to prevent memory vulnerabilities relative to the release structure of the initialization function to prevent memory vulnerabilities.
SIP_T * MSG;
MSG_INIT (& MSG);
MSG_free (msg);
Sfree (msg);
URL_T * URL;
URL_INIT (& URL)
URL_FREE (URL);
Sfree (URL);
How to create a URL and Request-URI, the following process is the answer. There is a sample here, we set this value.
INVITE SIP: CHENSHX@sip.datang.com SIP / 2.0
URL_T * URL;
URL_INIT (& URL);
URL_SETSCHEME (URL, "SIP");
URL_SETUSERNAME (URL, "CHENSHX");
URL_SETHOST (URL, "SIP.DATANG.COM");
Msg_setMethod (MSG, "Invite");
MSG_SETURI (MSG, URL);
MSG_setversion (MSG, "2.0");
How to add fields in the message body?
I am provided to you two ideas, one look at the following example, and the other is to see RFC2543.
The head below is forcibly, please keep in mind.
VIA
CSEQ
Call-id
TO
From
Contact
Content-Length
Conten-Type
After that is Body
{
URL_T * URL;
TO_T * TO;
URL_INIT (& URL);
URL_SETUSERNAME (URL, SSTRDUP ("Jack");
URL_SETHOST (URL, SSTRDUP ("Atosc.org"));
TO_INIT (& to);
TO_SETURL (TO, URL);
TO_SETDISPLAYNAME (To, SSTRDUP ("Jack ...");
MSG_SETTO (MSG, TO);
}
/ * The Same API Is Available for the from_t structure * /
{
From_t * from;
/ * Allocate a URL_T * /
URL_INIT (& URL);
URL_SETUSERNAME (URL, SSTRDUP ("cha"));
URL_SETHOST (URL, SSTRDUP ("Anywhere.org");
/ * allocate a from_t * /
From_init (& from);
From_seturl (from, URL);
From_setdisplayName (from, SSTRDUP ("My Love");
From_set_tag (from, SSTRDUP ("A48A");
MSG_SETFROM (MSG, FROM);
}
{
VIA_T * VIA;
VIA_INIT (& VIA);
VIA_SETVERSION (VIA, SSTRDUP ("2.0"));
VIA_SETPROTOCOL (VIA, SSTRDUP ("UDP");
VIA_SETHOST (VIA, SSTRDUP ("137.137.137.137");
VIA_SET_BRANCH (VIA, SSTRDUP ("BRANCH"), SSTRDUP ("A7C6A8DLZE.1");
MSG_SETVIA (MSG, VIA);
}
{
CSEQ_T * CSEQ;
CSEQ_INIT (& CSEQ);
...
MSG_setcseq (MSG, CSEQ);
}
{
CallID_T * CallID;
CallID_INIT (& CallID);
Callid_setNumber (CallID, SSTRDUP ("F81D4");
Callid_sethost (CallID, SSTRDUP ("foo.atosc.org");
MSG_SETCALLID (MSG, CallID);
}
/ * This API CAN Also BE Used, But it is much more time consuming! * /
MSG_setContact (MSG, "SIP: Jack@office.atosc.org");
/ * Let's add some headers * /
MSG_setHeader (MSG, SSTRDUP ("Subject"), SSTRDUP ("NEED Support for OSIP!");
/ * Add A Body * /
Msg_setBody (MSG, "V = 0 / R / NO = USER1 53655765 2353687637 In ip4 128.3.4.5/r/ns=mbone audio / r / ni = discussion of mbone @Somewhere.com/r / NC = IP4 128.3.4.5/R/NT=0 0 / R / NM = Audio 3456 RTP / AVP 0 / R / NA = R / N "); structural information is converted into string
Transforming a defined structure into a string, which must be called after processing this action after processing information. Then it is to release the resources occupied by the structure initialization.
SIP_T * MSG;
Char * DEST;
MSG_INIT (& MSG);
The operation of MSG;
IF (MSG_2CHAR (MSG, & DEST)! = 0)
{
Printf ("/ NMSG_2CHAR call failed ./n");
CONTINUE;
}
MSG_free (msg);
Sfree (msg);
Sfree (dest);
remind:
The grammatical analyzer is too tolerant some of our mistakes, for example, in Display Name, although this is not allowed, but the analyzer is "tolerant". This allows you to be alert to everything that may happen, polish your eyes, pay attention to each problem.
How to improve grammar analyzer performance
Improve the performance of the stack, you can choose some heads to completely decode when configuring syntax analysis. (In the runtime, a small amount of work is also allowed) When you perform a proxy server, you can find that this is useful for performance improvement.
Chapter 5 limited state machine
The limited state machine is used to represent the SIP session process, and the state is used to represent the state of conversion. Each time the protocol (sender or acceptor) is always in a particular state, and its state is composed of all variable values, including the counter.
./libosip-x.x.x/fsm is a source program directory containing a limited state machine.
./libosip is the development library directory.
#include
Transaction and events (Events)
Definition and purpose of transaction processing
In RFC2543, transaction processing is used to define contextual relationships of SIP transaction processing. Use the Transaction_T structure to define transaction information, so we don't need to understand each property. The transaction model is as follows:
Incoming MSG
Timeout EVT
Msg to send
User module
Timer module
Transport Module
TRANSAC.
2
TRANSAC.
1
Context of transaction processing
Your_Instance Attribute is not used to use it, we can use it to point to the context set by the individual.
We use TransactionID as the unique identifier of each individual in the transaction linked list.
Transactionff is an event (SIPEVENT_T) that FIFO (First In First Out Advanced First) Structure to identify this transaction.
This proxy property indicates the host and port used to transmit, all requests are forced to transfer to this proxy, regardless of what the request-uri is included.
Typedef struct _transaction_t {
Void * Your_instance; / * add wherever you want here. * /
Int TransactionID; / * Simple ID Used to Identify The TR. * /
FIFO_T * Transactionff; / * Events Must Be Added in this FIFO * / from_T * from; / * call-leg definition * /
TO_T * TO;
Call_id_t * callid;
CSEQ_T * CSEQ;
SIP_T * LastRequest; / * Last Request Received or Sent * /
SIP_T * LastResponse; / * Last Response Received or Sent * /
State_t state; / * state of transaction * /
StateMachine_t * StateMachine; / * State-Machine of Transaction * /
Time_t birth_time; / * birth_date of transaction * /
Time_t completed_time; / * end date of transaction * /
Int retransmissioncounter; / * Facilities for Internal Timer * /
URL_T * proxy; / * url buy to send requests * /
Void * config; / * Transaction is managed by config * /
Transaction_t;
Event definition and purpose
The SIPEVENT target is used to control the elements in the SIP transaction process. There are three events in a finite state machine (Events):
Receive SIP messages (requests and answers)
Send SIP messages (requests and answers)
Timer event (retransmission and context delete or end)
Type always points to the type of event.
TransactionID is used inside.
When the event is caused by the SIP message, the SIP is the SIP_T structure message.
TypeDef struct_t_t
{
TYPE_T TYPE;
Int TransactionID;
SIP_T * SIP;
SIPEVENT_T;
API for transaction processing
OSIP_INIT
[Function Description]
Initialize and allocate memory for the OSIP_T structure.
[Parameter Description]
INT OSIP_INIT (OISP_T ** OSIP);
Success return 0
OSIP_FREE
[Function Description]
Release the OSIP structure.
[Parameter Description]
Void OSIP_Free (OSIP_T * OSIP);
OSIP_INIT_PROXY
[Function Description]
Set the default proxy with the OSIP structure related transaction processing.
[Parameter Description]
Void OSIP_INIT_PROXY (OSIP_T * OSIP, URL_T * URL);
OSIP_EXECUTE
[Function Description]
(Applications that are only limited to non-multi-threads) Execute events (events) in the OSIP structure.
[Parameter Description]
INT OSIP_EXECUTE (OSIP_T * OSIP);
Success return 0
OSIP_DISTRIBUTE_EVENT
[Function Description]
Distribute a SIP event (for receiving message event incoming message evt) to the FIFO in the OSIP structure
[Parameter Description]
Transaction_t * osip_distribute_event (OSIP_T * OSIP, SIPEVENT_T * SE);
OSIP_PARSE
[Function Description]
Grammar analysis of string BUF and generate SIP comes message events.
[Parameter Description]
SIPEVENT_T * OSIP_PARSE (Char * BUF);
OSIP_NEW_EVENT
[Function Description] (Timer Used) is used to create a new SIP event (Event) with type properties Type and TransactionID.
[Parameter Description]
SIPEVENT_T * OSIP_NEW_EVENT (Type_t Type, Int Transaction);
OSIP_NEW_INCOMING_EVENT
[Function Description]
Create a new SIP event for the receiving SIP message.
[Parameter Description]
SIPEVENT_T * OSIP_NEW_INCOMING_EVENT (SIP_T * SIP);
SIP_NEW_OUTGOING_EVENT
[Function Description]
Create a new SIP event for sending a SIP message.
[Parameter Description]
SIPEVENT_T * OSIP_NEW_OUTGOING_EVENT (SIP_T * SIP);
OSIP_FIND_ASINCOMINGMESSAGE
[Function Description]
Discover (or create) related to receiving SIP messages related transactions.
[Parameter Description]
Transaction_t * osip_find_adincomingmentMessage (OSIP_T * OSIP, SIPEVENT_T * SIPEVENT);
OSIP_FIND_ASOUTGOINGMESSAGE
[Function Description]
Find transactions related to sending SIP messages.
[Parameter Description]
Transaction_t * osip_find_asoutgoingmentMessage (OSIP_T * OSIP, SIPEVENT_T * SIPEVENT);
OSIP_FIND_BYID
[Function Description]
Look for transactions with the same transactionID attribute value.
[Parameter Description]
Transin_t * osip_find_byid (OSIP_T * OSIP, INT Transaction);
OSIP_REMOVE_BYID
[Function Description]
Delete transactions with the same transactionId attribute value.
[Parameter Description]
INT OSIP_REMOVE_BYID (OSIP_T * OSIP, INT TransactionID);
Transaction_init
[Function Description]
Initialize Transaction_T and allocate memory.
[Parameter Description]
Int transaction_init (transaction_t ** transaction);
Transaction_free
[Function Description]
Release the Transaction_T structure.
[Parameter Description]
Void Transaction_Free (Transaction_t * Transaction);
Transaction_execute
[Function Description]
Execute an event included in the transaction context.
[Parameter Description]
INT Transaction_execute (Transaction_t * Transaction);
Callback
OSIP uses a series of progress to declare the progress of the SIP transaction. For example, if you receive an Invite request, the developer calls the "OSIP_SETCB_RCVINVITE (..." function through the protocol stack, so that the INVITE method is registered, generates a temporary response and the action of starting construction and transmitting the final response.
The following method allows us to register, initialize the OSIP stack, which will be treated with things. Some methods are required (declared requests and final responses), while others are optional (declaration temporary corresponding and retransmission).
Void OSIP_SETCB_RCVINVITE (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_RCVACK (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_RCVBYE (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *)); Void OSIP_SETCB_RCVCANCEL (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *));
Void OSIP_SETCB_RCVINFO (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_T *));
Void OSIP_SETCB_RCVOPTIONS (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_RCVREGISTER (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *));
Void OSIP_SETCB_RCVPRACK (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_RCVUNKREQUEST (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_SNDINVITE (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_SNDACK (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_SNDBYE (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_SNDCANCEL (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_SNDINFO (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_SNDOPTIONS (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_SNDREGISTER (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_SNDPRACK (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *));
Void OSIP_SETCB_SNDUNKREQUEST (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *));
Void OSIP_SETCB_RCV1XX (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *));
Void OSIP_SETCB_RCV2XX (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *));
Void OSIP_SETCB_RCV3XX (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_RCV4XX (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_RCV5XX (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *));
Void OSIP_SETCB_RCV6XX (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *)); Void OSIP_SETCB_SND1XX (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *));
Void OSIP_SETCB_SND2XX (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_SND3XX (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *));
Void OSIP_SETCB_SND4XX (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *));
Void OSIP_SETCB_SND5XX (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *);
Void OSIP_SETCB_SND6XX (OSIP_T * CF, VOID (* CB) (SIPEVENT_T *, Transaction_t *));
Void OSIP_SETCB_RCVRESP_RETRANSMISSION (OSIP_T * CF, VOID (* CB) (Transaction_t *));
Void OSIP_SETCB_SNDREQ_RETRANSMISSION (OSIP_T * CF, VOID (* CB) (Transaction_t *));
Void OSIP_SETCB_SNDRESP_RETRANSMISSION (OSIP_T * CF, VOID (* CB) (Transaction_T *));
Void OSIP_SETCB_RCVREQ_RETRANSMISSION (OSIP_T * CF, VOID (* CB) (Transaction_t *));
Void OSIP_SETCB_KILLTRANSACTION (OSIP_T * CF, VOID (* CB) (Transaction_T *));
Void OSIP_SETCB_ENDOFTRANSACTION (OSIP_T * CF, VOID (* CB) (Transaction_T *));
Void osip_setcb_connection_refused (osip_t * cf, void (* cb) (transaction_t *));
Void OSIP_SETCB_NETWORK_ERROR (OSIP_T * CF, VOID (* CB) (Transaction_T *));
Some useful macros (Macros)
You can also use the list of the following macros. If you want your program to maintain complete compatibility on OSIP, you need to use them.
/ * For incoming transaction * /
#define evt_is_rcv_invite (Event) (Event-> Type == RCV_REQINVITE)
#define evt_is_rcv_ck (event) (event-> type == rcv_reqack)
#define evt_is_rcv_request (event-> type == RCV_REQUEST)
#define evt_is_rcv_status_1xx (Event) (Event-> Type == RCV_STATUS_1XX)
#define evt_is_rcv_status_23456xx (Event) (Event-> Type == RCV_STATUS_23456XX)
/ * For outgoing transportion * /
#define evt_is_snd_invite (event-> type == SND_REQINVITE) #define evt_is_snd_ack (event) (event-> type == SND_REQACK)
#define evt_is_snd_request (event) (event-> type == SND_REQUEST)
#define evt_is_snd_status_1xx (Event) (Event-> Type == SND_STATUS_1XX)
#define evt_is_snd_status_23456xx (Event) (Event-> Type == SND_STATUS_23456XX)
#define evt_is_incomingmsg (event) (Event-> Type> = RCV_REQINVITE /
&& Event-> Type <= rcv_status_23456xx)
#define evt_is_incomingReq (Event) (EVT_IS_RCV_INVITE (Event) /
|| evt_is_rcv_ack (event) /
|| EVT_IS_RCV_REQUEST (EVENT))
#define evt_is_incomingResp (EVT_IS_RCV_STATUS_1XX (Event) /
|| EVT_IS_RCV_STATUS_23456XX (EVENT))
#define evt_is_outgoingmsg (Event) (event-> type> = SND_REQINVITE /
&& Event-> Type <= SND_STATUS_23456XX)
#define evt_is_outgoingReq (EVT_IS_SND_INVITE (EVENT) /
|| EVT_IS_SND_ACK (EVENT) /
|| evt_is_snd_request (event))
#define evt_is_outgoingResp (Event) (EVT_IS_SND_STATUS_1XX (EVENT) /
|| EVT_IS_SND_STATUS_23456XX (EVENT))
#define evt_is_msg (Event) (event-> type> = rcv_reqinvite /
&& Event-> Type <= SND_STATUS_23456XX)
#define evt_is_kill_transaction (Event-> type == kill_transaction)
#define evt_is_unknown_evt (event) (event-> type == unknown_evt)
#define evt_is_timeout (Event) (event-> type == timeout)
Guidelines for limited state machines
SIP defines four limited state machines. SIP also defines two things. Invite transactions and other nonvite are very small. INVITE and ACK are unsuccessful and constitute an Invite transaction. Also, different rules apply to retransmission mechanisms.
A limited state machine is an ideal way to execute at the things layer. The occurrence of thread wait events (Events). The event is derived from the TU layer, the transport layer or clock management. This is done through a series of dynamic calls.
User Layer
Transaction contexts
1
N
FIFO 1
FIFO N
Initialization OSIP Stack
The OSIP stack needs to initialize before running. Before using the OSIP stack, the following function will be the first called and can only call once. Calling this letter will also initialize the syntax analysis.
INT OSIP_GLOBAL_INIT ();
Assign and initialize the OSIP_T structure
The OSIP_T structure is a container of a series of things. This element appears as an example of the SIP component, which can be used for UAS / UAC, registration server, and redirect servers.
The following code is used to build a completed OSIP_T element. First, we have to register a series of necessary or optional callback functions. We can also configure the protocol stack for all requests.
OSIP_T * OSIP;
IF (-1 == osip_global_init ())
Return -1; / * mutex is not initialized prot in * /
OSIP_INIT (& OSIP);
OSIP_INIT_PROXY (OSIP, URL_OF_PROXY);
OSIP_SETCB_RCVRESP_RETRANSMISSION (CF, & CB_RCVRESP_RETRANSMISSION);
OSIP_SETCB_SNDREQ_RETRENSMISSION (CF, & CB_SNDREQ_RETRENSMISSION);
OSIP_SETCB_SNDRESP_RETRANSMISSION (CF, & CB_SNDRESP_RETRENSMISSION);
OSIP_SETCB_RCVREQ_RETRANSMISSION (CF, & CB_RCVREQ_RETRANSMISSION);
OSIP_SETCB_KILLTRANSACTION (CF, & CB_KillTransaction);
OSIP_SETCB_ENDOFTRANSACTION (CF, & CB_ENDOFTRANSACTION);
OSIP_SETCB_CONNECTION_REFUSED (CF, & CB_CONNECTION_REFUSED);
OSIP_SETCB_NETWORK_ERROR (CF, & CB_Network_ERROR);
OSIP_SETCB_RCV1XX (CF, & CB_RCV1XX);
OSIP_SETCB_RCV2XX (CF, & CB_RCV2XX);
OSIP_SETCB_RCV3XX (CF, & CB_RCV3XX);
OSIP_SETCB_RCV4XX (CF, & CB_RCV4xx);
OSIP_SETCB_RCV5XX (CF, & CB_RCV5XX);
OSIP_SETCB_RCV6XX (CF, & CB_RCV6XX);
OSIP_SETCB_SNDINVITE (CF, & CB_SNDINVITE);
OSIP_SETCB_SNDACK (CF, & CB_SNDACK);
OSIP_SETCB_SNDBYE (CF, & CB_SNDBYE);
OSIP_SETCB_SNDCANCANCEL (CF, & CB_SNDCANCEL);
OSIP_SETCB_SNDINFO (CF, & CB_SNDINFO);
OSIP_SETCB_SNDOPTIONS (CF, & CB_SNDOPTION);
OSIP_SETCB_SNDREGISTER (CF, & CB_SNDREGISTER);
OSIP_SETCB_SNDPRACK (CF, & CB_SNDPRACK);
OSIP_SETCB_SNDUNKREQUEST (CF, & CB_SNDUNKREQUEST);
OSIP_SETCB_SND1XX (CF, & CB_SND1XX);
OSIP_SETCB_SND2XX (CF, & CB_SND2XX);
OSIP_SETCB_SND3XX (CF, & CB_SND3XX); OSIP_SETCB_SND4XX (CF, & CB_SND4XX);
OSIP_SETCB_SND5XX (CF, & CB_SND5XX);
OSIP_SETCB_SND6XX (CF, & CB_SND6XX);
OSIP_SETCB_RCVINVITE (CF, & CB_RCVINVITE);
OSIP_SETCB_RCVACK (CF, & CB_RCVACK);
OSIP_SETCB_RCVBYE (CF, & CB_RCVBYE);
OSIP_SETCB_RCVCANCANCEL (CF, & CB_RCVCANCEL);
OSIP_SETCB_RCVINFO (CF, & CB_RCVINFO);
OSIP_SETCB_RCVOPTIONS (CF, & CB_RCVOPTION);
OSIP_SETCB_RCVREGISTER (CF, & CB_RCVREGISTER);
OSIP_SETCB_RCVPRACK (CF, & CB_RCVPRACK);
OSIP_SETCB_RCVUNKREQUEST (CF, & CB_RCVunkRequest);
Send Event (Events) Controlling TRANSTY
This is a simple sample of initialization. The initial event is sent to the FIFO that includes the initial request. The creation of messages is not shown here.
int
CREATE_SESSION (OSIP_T * OSIP)
{
SIP_T * INVITE;
Transaction_t * Transaction;
/ * You Must Create Your OWN SIP Message. * /
MSG_INIT (& Invite);
Your_own_method_to_setup_messages (invite);
/ * When it is the first invite, allocate * /
/ * And Start a new Transaction (prepare the
/ * context and start a thread.) * /
TRN_INIT (& Transaction,
OSIP,
INVITE-> TO,
INVITE-> from,
INVITE-> CallID,
Invite-> CSEQ);
/ * The Thread is now Waiting on its fifo * /
/ * The folload method allocate an Event * /
/ * and send it to the transaction. * /
OSIP_SENDMSG (Transaction, INVITE);
}
int
OSIP_SENDMSG (Transaction_T * Transaction, SIP_T * MSG)
{
SIPEVENT_T * SIPEVENT;
SIPEVENT = OSIP_NEW_OUTGOING_SIPMESSAGE (MSG);
SIPEVENT-> TransactionID = Transaction-> TransactionID;
/ * Depending on your application model, you can choose * /
/ * Either to consume the Event area add it in the FIFO * /
/ * and delay the Operations * /
#ifdef osip_mt
FIFO_ADD (Transaction-> TransactionFF, SIPEVENT);
#ELSE
Transaction_execute (Transaction, Sipevent); # ENDIF
Return 0;
}
PROXY development attention
The OSIP provides the transaction layer available for user agents, registration servers, redirect servers, and some types of conference servers. A state machine of a stateful proxy server will be added in the future. The current state machine is difficult to perform Proxy functionality.
For stateless proxy servers, the state machine is simple (no status is required). However, when a state machine is executed, it is only a short time cache result.
Build your own architecture
Since the release of 0.7.0, the stack can be used without the support of the signal and threads. Whether to use these depends on our design. We have to choose a suitable design to complete the development of our app. These are what we need to carefully consider:
Select the transport layer (recommended UDP in the SIP protocol)
Make multiple transactions in a socket, or everything
Select multithreaded or non-multi-threaded
Select clock
Now, UDP is required for the SIP system. For the server, this is also true for the user agent. When performing a server, we need to face many parallel transactions. If we use a separate connection for each thing, the application may soon make the resources lack (we can't always guess whether other applications on the same machine require a lot of sockets). For the server, when designing a thread for each thing, we must also pay attention to the use of multi-threads. For high-visitive servers, we can quickly use the resources of threads (especially, similar to those such as Debian support very little thread).
If our application needs to connect to the database and IP address resolution, this will make the program in a blocking state. In this case, multi-thread will be applied, and take good performance. How to solve these problems for improved performance of our application, will be the weight of the weight.
postscript
As an OSIP translator, I hope this document will be constantly improved. This requires your attention, any suggestions and fixes are welcome, even if it is just a sentence.
