Session Initiation Protocol Library Functions
sip_stack_init(3SIP)
NAME
sip_stack_init - initializes SIP stack
SYNOPSIS
cc [ flag ... ] file ... -lsip [ library ... ]
#include
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 initialize 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 setto 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 changenotification 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 Functionssip_stack_init(3SIP)
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 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 thefunction returns. If the applica-
tion wishes to use the message beyond that, it has to hold a reference on the message usingsip_hold_msg(). Similarly, if the
application wishes to cache the dialog, it must hold a reference on the dialog usingsip_hold_msg().
sip_ulp_timeout An application can register these
sip_ulp_untimeout two routines to implement its own
routines for the stack timers. Typically, an application should allow the stack to use its ownbuilt-in timer routines. The
built-in timer routines are used
only by the stack and are not available to applications. If theSunOS 5.11 Last change: 23 Jan 2007 2
Session Initiation Protocol Library Functionssip_stack_init(3SIP)
application registers one routine, it must also register the other. These functions must be registeredfor single-threaded application.
Otherwise, the timer thread pro-
vided 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 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 notregistered the transaction is ter-
minated on such a failure. The final argument 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 dia-
log is deleted. The dialog to be deleted is passed along with theSIP message which caused the dia-
log to be deleted. The final argu-
ment is for future use. It is always set to NULL.sip_ulp_trans_state_cb If these callback routines are
sip_ulp_dlg_state_cb registered, the stack invokes
sip_ulp_trans_state_cb when a
transaction changes states andsip_ulp_dlg_state_cb when a dialog
changes states. Connection Manager Interface The connection manager interfaces must be registered by theapplication 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 Functionssip_stack_init(3SIP)
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 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 thelength information and the asso-
ciated connection object.sip_hold_conn_object The application provides a
sip_rel_conn_object mechanism for the stack to indi-
cate that a connection object is in use by the stack and must not be freed. The stack usessip_hold_conn_object to indicate
that the connection object is inuse and sip_rel_conn_object 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 Functionssip_stack_init(3SIP)
sip_conn_is_stream The stack uses this to determine
whether the connection object,passed as the argument, is byte-
stream oriented. Byte-stream pro-
tocols include TCP whilemessage-based protocols include
SCTP and UDP.sip_conn_is_reliable The stack uses this to determine
whether the connection object,passed as the argument, is reli-
able. Reliable protocols includeTCP and SCTP. Unreliable proto-
cols include UDP.sip_conn_local_address These two interfaces are used by
sip_conn_remote_address the stack to obtain endpoint
information for a connection object. Thesip_conn_local_address provides
the local address/port informa-
tion. The sip_conn_remote_address
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.sip_conn_transport 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.sip_conn_timer1 These four interfaces may be
sip_conn_timer2 registered by an application to
sip_conn_timer4 provide connection object
sip_conn_timerd specific timer information. If
these are not 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 forSunOS 5.11 Last change: 23 Jan 2007 5
Session Initiation Protocol Library Functionssip_stack_init(3SIP)
non-INVITE request and INVITE
response - default 4 secs), Timer
4 (maximum duration a messagewill remain in the network -
default 5 secs) and Timer D (wait time for response retransmitinterval - 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 withan entry for each header. If the table includes headers sup-
ported by the stack, parsing functions or otherapplication-specific table entries take precedence over lib-
sip supported headers. The header table structure is sup-
plied 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 precedence.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 valueSunOS 5.11 Last change: 23 Jan 2007 6
Session Initiation Protocol Library Functionssip_stack_init(3SIP)
of 0 indicates success.header_free The function that frees the
parsed headerheader_check_compliance An application can optionally
provide this function that will check if the header is compliantor not. The compliance for a cus-
tom header will be defined by the application.header_is_equal An application can optionally
provide this function to deter-
mine whether two input headers are equivalent. The equivalencecriteria is defined by the appli-
cation.RETURN VALUES
On success sip_stack_init() 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.ERRORS
On failure, the sip_stack_init() function returns the fol-
lowing 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 attri-
butes:SunOS 5.11 Last change: 23 Jan 2007 7
Session Initiation Protocol Library Functionssip_stack_init(3SIP)
______________________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE 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 Functionssip_stack_init(3SIP)
SunOS 5.11 Last change: 23 Jan 2007 9