Session Initiation Protocol Library Functions
sipstackinit(3SIP)
NAME
sipstackinit - initializes SIP stack
SYNOPSIS
cc [ flag ... ] file ... -lsip [ library ... ]
#include
int sipstackinit(sipstackinitt * stackval);
DESCRIPTION
The sipstackinit() function is used to initialize the SIP
stack. The stack can be initialized by a process only once.
Any shared library that is linked with a main program or
another library that has already initialized the stack will
encounter a failure when trying to initialize the stack.
The initialization structure is given by:
typedef struct sipstackinits {
int sipversion;
uint32t sipstackflags;
sipiopointerst *sipiopointers;
sipulppointerst *sipulppointers;
sipheaderfunctiont *sipfunctiontable;
};
sipversion This must be set to SIPSTACKVERSION.
sipstackflags If the application wants the SIP stack to
maintain dialogs, this flag must be set
to SIPSTACKDIALOGS. Otherwise, it must
be set to 0. If SIPSTACKDIALOGS is not
set, the stack does not deal with dialogs
at all.
Upper Layer Registrations
These include callbacks that are invoked to deliver incoming
messages or error notification.
The callback functions should not create a thread and invoke
a function that could recursively invoke the callback. For
example, the callback function for a transition state change
notification should not create a thread to send a SIP mes-
sage that results in a change in the state of the transac-
tion, which would again invoke the callback function.
SunOS 5.11 Last change: 23 Jan 2007 1
Session Initiation Protocol Library Functions
sipstackinit(3SIP)
The registration structure is supplied by:
typedef struct sipulppointerss {
void (*sipulprecv)(const sipconnobjectt,
sipmsgt, const sipdialogt);
uintt (*sipulptimeout)(void *,
void (*func)(void *),
struct timeval *);
booleant (*sipulpuntimeout)(uintt);
int (*sipulptranserror)
(siptransactiont, int, void *);
void (*sipulpdlgdel)(sipdialogt,
sipmsgt, void *);
void (*sipulptransstatecb)
(siptransactiont, sipmsgt,
int, int);
void (*sipulpdlgstatecb)(sipdialogt,
sipmsgt, int, int);
}sipiopointerst;
sipulprecv This is a mandatory routine that
the application registers for the
stack to deliver an inbound SIP
message. The SIP stack invokes the
function with the connection
object on which the message
arrived, the SIP message, and any
associated dialog.
The SIP message is freed once the
function returns. If the applica-
tion wishes to use the message
beyond that, it has to hold a
reference on the message using
sipholdmsg(). Similarly, if the
application wishes to cache the
dialog, it must hold a reference
on the dialog using
sipholdmsg().
sipulptimeout An application can register these
sipulpuntimeout two routines to implement its own
routines for the stack timers.
Typically, an application should
allow the stack to use its own
built-in timer routines. The
built-in timer routines are used
only by the stack and are not
available to applications. If the
SunOS 5.11 Last change: 23 Jan 2007 2
Session Initiation Protocol Library Functions
sipstackinit(3SIP)
application registers one routine,
it must also register the other.
These functions must be registered
for single-threaded application.
Otherwise, the timer thread pro-
vided by the stack could result in
invoking a registered callback
function.
sipulptranserror The application can register this
routine to be notified of a tran-
saction error. An error can occur
when the transaction layer tries
to send a message using a cached
connection object which results in
a failure. If this routine is not
registered the transaction is ter-
minated on such a failure. The
final argument is for future use.
It is always set to NUL.
sipulpdlgdel An application can register this
routine to be notified when a dia-
log is deleted. The dialog to be
deleted is passed along with the
SIP message which caused the dia-
log to be deleted. The final argu-
ment is for future use. It is
always set to NUL.
sipulptransstatecb If these callback routines are
sipulpdlgstatecb registered, the stack invokes
sipulptransstatecb when a
transaction changes states and
sipulpdlgstatecb when a dialog
changes states.
Connection Manager Interface
The connection manager interfaces must be registered by the
application to provide I/O related functionality to the
stack. These interfaces act on a connection object that is
defined by the application. The application registers the
interfaces for the stack to work with the connection object.
The connection object is application defined, but the stack
requires that the first member of the connection object is a
void *, used by the stack to store connection object
SunOS 5.11 Last change: 23 Jan 2007 3
Session Initiation Protocol Library Functions
sipstackinit(3SIP)
specific information which is private to the stack.
The connection manager structure is supplied by:
typedef struct sipiopointerss {
int (*sipconnsend)(const sipconnobjectt, char *, int);
void (*sipholdconnobject)(sipconnobjectt);
void (*siprelconnobject)(sipconnobjectt);
booleant (*sipconnisstream)(sipconnobjectt);
booleant (*sipconnisreliable)(sipconnobjectt);
int (*sipconnremoteaddress)(sipconnobjectt, struct sockaddr *,
socklent *);
int (*sipconnlocaladdress)(sipconnobjectt, struct sockaddr *,
socklent *);
int (*sipconntransport)(sipconnobjectt);
int (*sipconntimer1)(sipconnobjectt);
int (*sipconntimer2)(sipconnobjectt);
int (*sipconntimer4)(sipconnobjectt);
int (*sipconntimerd)(sipconnobjectt);
}sipiopointerst;
sipconnsend This function is invoked by the
stack after processing an out-
bound SIP message. This function
is responsible for sending the
SIP message to the peer. A return
of 0 indicates success. The SIP
message is passed to the function
as a string, along with the
length information and the asso-
ciated connection object.
sipholdconnobject The application provides a
siprelconnobject mechanism for the stack to indi-
cate that a connection object is
in use by the stack and must not
be freed. The stack uses
sipholdconnobject to indicate
that the connection object is in
use and siprelconnobject to
indicate that it has been
released. The connection object
is passed as the argument to
these functions. The stack
expects that the application will
not free the connection object if
it is in use by the stack.
SunOS 5.11 Last change: 23 Jan 2007 4
Session Initiation Protocol Library Functions
sipstackinit(3SIP)
sipconnisstream The stack uses this to determine
whether the connection object,
passed as the argument, is byte-
stream oriented. Byte-stream pro-
tocols include TCP while
message-based protocols include
SCTP and UDP.
sipconnisreliable The stack uses this to determine
whether the connection object,
passed as the argument, is reli-
able. Reliable protocols include
TCP and SCTP. Unreliable proto-
cols include UDP.
sipconnlocaladdress These two interfaces are used by
sipconnremoteaddress the stack to obtain endpoint
information for a connection
object. The
sipconnlocaladdress provides
the local address/port informa-
tion. The sipconnremoteaddress
provides the address/port infor-
mation of the peer. The caller
allocates the buffer and passes
its associated length along with
it. On return, the length is
updated to reflect the actual
length.
sipconntransport The stack uses this to determine
the transport used by the connec-
tion object, passed as the argu-
ment. The transport could be TCP,
UDP, SCTP.
sipconntimer1 These four interfaces may be
sipconntimer2 registered by an application to
sipconntimer4 provide connection object
sipconntimerd specific timer information. If
these are not registered the
stack uses default values.
The interfaces provide the timer
values for Timer 1 (RT estimate
- default 500 msec), Timer 2
(maximum retransmit interval for
SunOS 5.11 Last change: 23 Jan 2007 5
Session Initiation Protocol Library Functions
sipstackinit(3SIP)
non-INVITE request and INVITE
response - default 4 secs), Timer
4 (maximum duration a message
will remain in the network -
default 5 secs) and Timer D (wait
time for response retransmit
interval - default 32 secs).
Custom SIP headers
In addition to the SIP headers supported by the stack, an
application can optionally provide a table of custom headers
and associated parsing functions. The table is an array with
an entry for each header. If the table includes headers sup-
ported by the stack, parsing functions or other
application-specific table entries take precedence over lib-
sip supported headers. The header table structure is sup-
plied by:
typedef struct headerfunctiontable {
char *headername;
char *headershortname;
int (*headerparsefunc)
(struct sipheader *,
struct sipparsedheader **);
booleant (*headercheckcompliance)
(struct sipparsedheader *);
booleant (*headerisequal)
(struct sipparsedheader *,
struct sipparsedheader *);
void (*headerfree)
(struct sipparsedheader *);
}
headername The full name of the header. The
application must ensure that he
name does not conflict with
existing headers. If it does, the
one registered by the application
takes precedence.
headershortname Compact name, if any, for the
header.
headerparsefunc The parsing function for the
header. The parser will set the
second argument to the resulting
parsed structure. A return value
SunOS 5.11 Last change: 23 Jan 2007 6
Session Initiation Protocol Library Functions
sipstackinit(3SIP)
of 0 indicates success.
headerfree The function that frees the
parsed header
headercheckcompliance An application can optionally
provide this function that will
check if the header is compliant
or not. The compliance for a cus-
tom header will be defined by the
application.
headerisequal An application can optionally
provide this function to deter-
mine whether two input headers
are equivalent. The equivalence
criteria is defined by the appli-
cation.
RETURN VALUES
On success sipstackinit() returns 0. Otherwise, the func-
tion returns the error value.
The value of errno is not changed by these calls in the
event of an error.
ERORS
On failure, the sipstackinit() function returns the fol-
lowing error value:
EINVAL If the stack version is incorrect, or if any of
the mandatory functions is missing.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 23 Jan 2007 7
Session Initiation Protocol Library Functions
sipstackinit(3SIP)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level MT-Safe
SEE ALSO
libsip(3LIB)
SunOS 5.11 Last change: 23 Jan 2007 8
Session Initiation Protocol Library Functions
sipstackinit(3SIP)
SunOS 5.11 Last change: 23 Jan 2007 9
|
