1sip_stack_init(3SISPe)ssion Initiation Protocol Library Functisoinps_stack_init(3SIP)
2
6 sip_stack_init - initializes SIP stack
7
9 cc [ flag ... ] file ... -lsip [ library ... ]
10 #include <sip.h>
11 int sip_stack_init(sip_stack_init_t * stack_val);
13
16 The sip_stack_init() function is used to initialize the SIP stack. The
17 stack can be initialized by a process only once. Any shared library
18 that is linked with a main program or another library that has already
19 initialized the stack will encounter a failure when trying to initial‐
20 ize the stack.
21 The initialization structure is given by:
24 typedef struct sip_stack_init_s {
26 int sip_version;
27 uint32_t sip_stack_flags;
28 sip_io_pointers_t *sip_io_pointers;
29 sip_ulp_pointers_t *sip_ulp_pointers;
30 sip_header_function_t *sip_function_table;
31 };
32 sip_version This must be set to SIP_STACK_VERSION.
35 sip_stack_flags If the application wants the SIP stack to maintain
38 dialogs, this flag must be set to SIP_STACK_DIALOGS.
39 Otherwise, it must be set to 0. If SIP_STACK_DIALOGS
40 is not set, the stack does not deal with dialogs at
41 all.
42 Upper Layer Registrations
45 These include callbacks that are invoked to deliver incoming messages
46 or error notification.
47 The callback functions should not create a thread and invoke a function
50 that could recursively invoke the callback. For example, the callback
51 function for a transition state change notification should not create a
52 thread to send a SIP message that results in a change in the state of
53 the transaction, which would again invoke the callback function.
54 The registration structure is supplied by:
57 typedef struct sip_ulp_pointers_s {
59 void (*sip_ulp_recv)(const sip_conn_object_t,
60 sip_msg_t, const sip_dialog_t);
61 uint_t (*sip_ulp_timeout)(void *,
62 void (*func)(void *),
63 struct timeval *);
64 boolean_t (*sip_ulp_untimeout)(uint_t);
65 int (*sip_ulp_trans_error)
66 (sip_transaction_t, int, void *);
67 void (*sip_ulp_dlg_del)(sip_dialog_t,
68 sip_msg_t, void *);
69 void (*sip_ulp_trans_state_cb)
70 (sip_transaction_t, sip_msg_t,
71 int, int);
72 void (*sip_ulp_dlg_state_cb)(sip_dialog_t,
73 sip_msg_t, int, int);
74 }sip_io_pointers_t;
75 sip_ulp_recv This is a mandatory routine that the applica‐
78 tion registers for the stack to deliver an
79 inbound SIP message. The SIP stack invokes
80 the function with the connection object on
81 which the message arrived, the SIP message,
82 and any associated dialog.
83 The SIP message is freed once the function
85 returns. If the application wishes to use the
86 message beyond that, it has to hold a refer‐
87 ence on the message using sip_hold_msg().
88 Similarly, if the application wishes to cache
89 the dialog, it must hold a reference on the
90 dialog using sip_hold_msg().
91 sip_ulp_timeout An application can register these two rou‐
94 sip_ulp_untimeout tines to implement its own routines for the
95 stack timers. Typically, an application
96 should allow the stack to use its own built-
97 in timer routines. The built-in timer rou‐
98 tines are used only by the stack and are not
99 available to applications. If the application
100 registers one routine, it must also register
101 the other.
102 These functions must be registered for sin‐
104 gle-threaded application. Otherwise, the
105 timer thread provided by the stack could
106 result in invoking a registered callback
107 function.
108 sip_ulp_trans_error The application can register this routine to
111 be notified of a transaction error. An error
112 can occur when the transaction layer tries to
113 send a message using a cached connection
114 object which results in a failure. If this
115 routine is not registered the transaction is
116 terminated on such a failure. The final argu‐
117 ment is for future use. It is always set to
118 NULL.
119 sip_ulp_dlg_del An application can register this routine to
122 be notified when a dialog is deleted. The
123 dialog to be deleted is passed along with the
124 SIP message which caused the dialog to be
125 deleted. The final argument is for future
126 use. It is always set to NULL.
127 sip_ulp_trans_state_cb If these callback routines are registered,
130 sip_ulp_dlg_state_cb the stack invokes sip_ulp_trans_state_cb when
131 a transaction changes states and
132 sip_ulp_dlg_state_cb when a dialog changes
133 states.
134 Connection Manager Interface
137 The connection manager interfaces must be registered by the application
138 to provide I/O related functionality to the stack. These interfaces act
139 on a connection object that is defined by the application. The applica‐
140 tion registers the interfaces for the stack to work with the connection
141 object. The connection object is application defined, but the stack
142 requires that the first member of the connection object is a void *,
143 used by the stack to store connection object specific information which
144 is private to the stack.
145 The connection manager structure is supplied by:
148 typedef struct sip_io_pointers_s {
150 int (*sip_conn_send)(const sip_conn_object_t, char *, int);
151 void (*sip_hold_conn_object)(sip_conn_object_t);
152 void (*sip_rel_conn_object)(sip_conn_object_t);
153 boolean_t (*sip_conn_is_stream)(sip_conn_object_t);
154 boolean_t (*sip_conn_is_reliable)(sip_conn_object_t);
155 int (*sip_conn_remote_address)(sip_conn_object_t, struct sockaddr *,
156 socklen_t *);
157 int (*sip_conn_local_address)(sip_conn_object_t, struct sockaddr *,
158 socklen_t *);
159 int (*sip_conn_transport)(sip_conn_object_t);
160 int (*sip_conn_timer1)(sip_conn_object_t);
161 int (*sip_conn_timer2)(sip_conn_object_t);
162 int (*sip_conn_timer4)(sip_conn_object_t);
163 int (*sip_conn_timerd)(sip_conn_object_t);
164 }sip_io_pointers_t;
165 sip_conn_send This function is invoked by the stack after
168 processing an outbound SIP message. This
169 function is responsible for sending the SIP
170 message to the peer. A return of 0 indicates
171 success. The SIP message is passed to the
172 function as a string, along with the length
173 information and the associated connection
174 object.
175 sip_hold_conn_object The application provides a mechanism for the
178 sip_rel_conn_object stack to indicate that a connection object
179 is in use by the stack and must not be
180 freed. The stack uses sip_hold_conn_object
181 to indicate that the connection object is in
182 use and sip_rel_conn_object to indicate that
183 it has been released. The connection object
184 is passed as the argument to these func‐
185 tions. The stack expects that the applica‐
186 tion will not free the connection object if
187 it is in use by the stack.
188 sip_conn_is_stream The stack uses this to determine whether the
191 connection object, passed as the argument,
192 is byte-stream oriented. Byte-stream proto‐
193 cols include TCP while message-based proto‐
194 cols include SCTP and UDP.
195 sip_conn_is_reliable The stack uses this to determine whether the
198 connection object, passed as the argument,
199 is reliable. Reliable protocols include TCP
200 and SCTP. Unreliable protocols include UDP.
201 sip_conn_local_address These two interfaces are used by the stack
204 sip_conn_remote_address to obtain endpoint information for a connec‐
205 tion object. The sip_conn_local_address pro‐
206 vides the local address/port information.
207 The sip_conn_remote_address provides the
208 address/port information of the peer. The
209 caller allocates the buffer and passes its
210 associated length along with it. On return,
211 the length is updated to reflect the actual
212 length.
213 sip_conn_transport The stack uses this to determine the trans‐
216 port used by the connection object, passed
217 as the argument. The transport could be TCP,
218 UDP, SCTP.
219 sip_conn_timer1 These four interfaces may be registered by
222 sip_conn_timer2 an application to provide connection object
223 sip_conn_timer4 specific timer information. If these are not
224 sip_conn_timerd registered the stack uses default values.
225 The interfaces provide the timer values for
227 Timer 1 (RTT estimate - default 500 msec),
228 Timer 2 (maximum retransmit interval for
229 non-INVITE request and INVITE response -
230 default 4 secs), Timer 4 (maximum duration a
231 message will remain in the network - default
232 5 secs) and Timer D (wait time for response
233 retransmit interval - default 32 secs).
234 Custom SIP headers
237 In addition to the SIP headers supported by the stack, an application
238 can optionally provide a table of custom headers and associated parsing
239 functions. The table is an array with an entry for each header. If the
240 table includes headers supported by the stack, parsing functions or
241 other application-specific table entries take precedence over libsip
242 supported headers. The header table structure is supplied by:
243 typedef struct header_function_table {
245 char *header_name;
246 char *header_short_name;
247 int (*header_parse_func)
248 (struct sip_header *,
249 struct sip_parsed_header **);
250 boolean_t (*header_check_compliance)
251 (struct sip_parsed_header *);
252 boolean_t (*header_is_equal)
253 (struct sip_parsed_header *,
254 struct sip_parsed_header *);
255 void (*header_free)
256 (struct sip_parsed_header *);
257 }
258 header_name The full name of the header. The application
261 must ensure that he name does not conflict
262 with existing headers. If it does, the one
263 registered by the application takes prece‐
264 dence.
265 header_short_name Compact name, if any, for the header.
268 header_parse_func The parsing function for the header. The
271 parser will set the second argument to the
272 resulting parsed structure. A return value
273 of 0 indicates success.
274 header_free The function that frees the parsed header
277 header_check_compliance An application can optionally provide this
280 function that will check if the header is
281 compliant or not. The compliance for a cus‐
282 tom header will be defined by the applica‐
283 tion.
284 header_is_equal An application can optionally provide this
287 function to determine whether two input
288 headers are equivalent. The equivalence cri‐
289 teria is defined by the application.
290
293 On success sip_stack_init() returns 0. Otherwise, the function returns
294 the error value.
295 The value of errno is not changed by these calls in the event of an
298 error.
299
301 On failure, the sip_stack_init() function returns the following error
302 value:
303 EINVAL If the stack version is incorrect, or if any of the mandatory
305 functions is missing.
306
309 See attributes(5) for descriptions of the following attributes:
310 ┌─────────────────────────────┬─────────────────────────────┐
315 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
316 ├─────────────────────────────┼─────────────────────────────┤
317 │Interface Stability │Committed │
318 ├─────────────────────────────┼─────────────────────────────┤
319 │MT-Level │MT-Safe │
320 └─────────────────────────────┴─────────────────────────────┘
321
323 libsip(3LIB)
324SunOS 5.11 23 Jan 2007 sip_stack_init(3SIP)