sip_stack_init(3SSession Initiation Protocol Library Functsip_stack_init(3SIP)NAMEsip_stack_init - initializes SIP stack
SYNOPSIS
cc [ flag ... ] file ... -lsip [ library ... ]
#include <sip.h>
int sip_stack_init(sip_stack_init_t * stack_val);
DESCRIPTION
The sip_stack_init() 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 initial‐
ize the stack.
The initialization structure is given by:
typedef struct sip_stack_init_s {
int sip_version;
uint32_t sip_stack_flags;
sip_io_pointers_t *sip_io_pointers;
sip_ulp_pointers_t *sip_ulp_pointers;
sip_header_function_t *sip_function_table;
};
sip_version This must be set to SIP_STACK_VERSION.
sip_stack_flags If the application wants the SIP stack to maintain
dialogs, this flag must be set to SIP_STACK_DIALOGS.
Otherwise, it must be set to 0. If SIP_STACK_DIALOGS
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 message that results in a change in the state of
the transaction, which would again invoke the callback function.
The registration structure is supplied by:
typedef struct sip_ulp_pointers_s {
void (*sip_ulp_recv)(const sip_conn_object_t,
sip_msg_t, const sip_dialog_t);
uint_t (*sip_ulp_timeout)(void *,
void (*func)(void *),
struct timeval *);
boolean_t (*sip_ulp_untimeout)(uint_t);
int (*sip_ulp_trans_error)
(sip_transaction_t, int, void *);
void (*sip_ulp_dlg_del)(sip_dialog_t,
sip_msg_t, void *);
void (*sip_ulp_trans_state_cb)
(sip_transaction_t, sip_msg_t,
int, int);
void (*sip_ulp_dlg_state_cb)(sip_dialog_t,
sip_msg_t, int, int);
}sip_io_pointers_t;
sip_ulp_recv This is a mandatory routine that the applica‐
tion 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 application wishes to use the
message beyond that, it has to hold a refer‐
ence on the message using sip_hold_msg().
Similarly, if the application wishes to cache
the dialog, it must hold a reference on the
dialog using sip_hold_msg().
sip_ulp_timeout An application can register these two rou‐
sip_ulp_untimeout tines 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 rou‐
tines are used only by the stack and are not
available to applications. If the applica‐
tion registers one routine, it must also reg‐
ister the other.
These functions must be registered for sin‐
gle-threaded application. Otherwise, the
timer thread provided by the stack could
result in invoking a registered callback
function.
sip_ulp_trans_error The application can register this routine to
be notified of a transaction 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
terminated on such a failure. The final argu‐
ment is for future use. It is always set to
NULL.
sip_ulp_dlg_del An application can register this routine to
be notified when a dialog is deleted. The
dialog to be deleted is passed along with the
SIP message which caused the dialog to be
deleted. The final argument is for future
use. It is always set to NULL.
sip_ulp_trans_state_cb If these callback routines are registered,
sip_ulp_dlg_state_cb the stack invokes sip_ulp_trans_state_cb when
a transaction changes states and
sip_ulp_dlg_state_cb 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 applica‐
tion 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 specific information which
is private to the stack.
The connection manager structure is supplied by:
typedef struct sip_io_pointers_s {
int (*sip_conn_send)(const sip_conn_object_t, char *, int);
void (*sip_hold_conn_object)(sip_conn_object_t);
void (*sip_rel_conn_object)(sip_conn_object_t);
boolean_t (*sip_conn_is_stream)(sip_conn_object_t);
boolean_t (*sip_conn_is_reliable)(sip_conn_object_t);
int (*sip_conn_remote_address)(sip_conn_object_t, struct sockaddr *,
socklen_t *);
int (*sip_conn_local_address)(sip_conn_object_t, struct sockaddr *,
socklen_t *);
int (*sip_conn_transport)(sip_conn_object_t);
int (*sip_conn_timer1)(sip_conn_object_t);
int (*sip_conn_timer2)(sip_conn_object_t);
int (*sip_conn_timer4)(sip_conn_object_t);
int (*sip_conn_timerd)(sip_conn_object_t);
}sip_io_pointers_t;
sip_conn_send This function is invoked by the stack after
processing an outbound 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 associated connection
object.
sip_hold_conn_object The application provides a mechanism for the
sip_rel_conn_object stack to indicate that a connection object
is in use by the stack and must not be
freed. The stack uses sip_hold_conn_object
to indicate that the connection object is in
use and sip_rel_conn_object to indicate that
it has been released. The connection object
is passed as the argument to these func‐
tions. The stack expects that the applica‐
tion will not free the connection object if
it is in use by the stack.
sip_conn_is_stream The stack uses this to determine whether the
connection object, passed as the argument,
is byte-stream oriented. Byte-stream proto‐
cols include TCP while message-based proto‐
cols include SCTP and UDP.
sip_conn_is_reliable The stack uses this to determine whether the
connection object, passed as the argument,
is reliable. Reliable protocols include TCP
and SCTP. Unreliable protocols include UDP.
sip_conn_local_address These two interfaces are used by the stack
sip_conn_remote_address to obtain endpoint information for a connec‐
tion object. The sip_conn_local_address pro‐
vides the local address/port information.
The sip_conn_remote_address provides the
address/port information 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.
sip_conn_transport The stack uses this to determine the trans‐
port used by the connection object, passed
as the argument. The transport could be TCP,
UDP, SCTP.
sip_conn_timer1 These four interfaces may be registered by
sip_conn_timer2 an application to provide connection object
sip_conn_timer4 specific timer information. If these are not
sip_conn_timerd registered the stack uses default values.
The interfaces provide the timer values for
Timer 1 (RTT estimate - default 500 msec),
Timer 2 (maximum retransmit interval for
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 supported by the stack, parsing functions or
other application-specific table entries take precedence over libsip
supported headers. The header table structure is supplied by:
typedef struct header_function_table {
char *header_name;
char *header_short_name;
int (*header_parse_func)
(struct sip_header *,
struct sip_parsed_header **);
boolean_t (*header_check_compliance)
(struct sip_parsed_header *);
boolean_t (*header_is_equal)
(struct sip_parsed_header *,
struct sip_parsed_header *);
void (*header_free)
(struct sip_parsed_header *);
}
header_name 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 prece‐
dence.
header_short_name Compact name, if any, for the header.
header_parse_func The parsing function for the header. The
parser will set the second argument to the
resulting parsed structure. A return value
of 0 indicates success.
header_free The function that frees the parsed header
header_check_compliance 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 applica‐
tion.
header_is_equal An application can optionally provide this
function to determine whether two input
headers are equivalent. The equivalence cri‐
teria is defined by the application.
RETURN VALUES
On success sip_stack_init() returns 0. Otherwise, the function returns
the error value.
The value of errno is not changed by these calls in the event of an
error.
ERRORS
On failure, the sip_stack_init() function returns the following error
value:
EINVAL If the stack version is incorrect, or if any of the mandatory
functions is missing.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Stable │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │MT-Safe │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOlibsip(3SIP)SunOS 5.10 20 Mar 2007 sip_stack_init(3SIP)
