| blob | b2daf54386349cfb8df5de3d5dd388572d1026e1 |
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH SIP_STACK_INIT 3SIP "Jan 23, 2007"
7 .SH NAME
8 sip_stack_init \- initializes SIP stack
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... -lsip [ \fIlibrary\fR ... ]
13 #include <sip.h>
15 \fBint\fR \fIsip_stack_init\fR(\fBsip_stack_init_t *\fR \fIstack_val\fR);
16 .fi
18 .SH DESCRIPTION
19 .LP
20 The \fBsip_stack_init()\fR function is used to initialize the \fBSIP\fR stack.
21 The stack can be initialized by a process only once. Any shared library that is
22 linked with a main program or another library that has already initialized the
23 stack will encounter a failure when trying to initialize the stack.
24 .sp
25 .LP
26 The initialization structure is given by:
27 .sp
28 .in +2
29 .nf
30 typedef struct sip_stack_init_s {
31 int sip_version;
32 uint32_t sip_stack_flags;
33 sip_io_pointers_t *sip_io_pointers;
34 sip_ulp_pointers_t *sip_ulp_pointers;
35 sip_header_function_t *sip_function_table;
36 };
37 .fi
38 .in -2
40 .sp
41 .ne 2
42 .na
43 \fBsip_version\fR
44 .ad
45 .RS 19n
46 This must be set to \fBSIP_STACK_VERSION\fR.
47 .RE
49 .sp
50 .ne 2
51 .na
52 \fBsip_stack_flags\fR
53 .ad
54 .RS 19n
55 If the application wants the \fBSIP\fR stack to maintain dialogs, this flag
56 must be set to \fBSIP_STACK_DIALOGS\fR. Otherwise, it must be set to \fB0\fR.
57 If \fBSIP_STACK_DIALOGS\fR is not set, the stack does not deal with dialogs at
58 all.
59 .RE
61 .SS "Upper Layer Registrations"
62 .LP
63 These include callbacks that are invoked to deliver incoming messages or error
64 notification.
65 .sp
66 .LP
67 The callback functions should not create a thread and invoke a function that
68 could recursively invoke the callback. For example, the callback function for a
69 transition state change notification should not create a thread to send a
70 \fBSIP\fR message that results in a change in the state of the transaction,
71 which would again invoke the callback function.
72 .sp
73 .LP
74 The registration structure is supplied by:
75 .sp
76 .in +2
77 .nf
78 typedef struct sip_ulp_pointers_s {
79 void (*sip_ulp_recv)(const sip_conn_object_t,
80 sip_msg_t, const sip_dialog_t);
81 uint_t (*sip_ulp_timeout)(void *,
82 void (*func)(void *),
83 struct timeval *);
84 boolean_t (*sip_ulp_untimeout)(uint_t);
85 int (*sip_ulp_trans_error)
86 (sip_transaction_t, int, void *);
87 void (*sip_ulp_dlg_del)(sip_dialog_t,
88 sip_msg_t, void *);
89 void (*sip_ulp_trans_state_cb)
90 (sip_transaction_t, sip_msg_t,
91 int, int);
92 void (*sip_ulp_dlg_state_cb)(sip_dialog_t,
93 sip_msg_t, int, int);
94 }sip_io_pointers_t;
95 .fi
96 .in -2
98 .sp
99 .ne 2
100 .na
101 \fBsip_ulp_recv\fR
102 .ad
103 .RS 26n
104 This is a mandatory routine that the application registers for the stack to
105 deliver an inbound \fBSIP\fR message. The \fBSIP\fR stack invokes the function
106 with the connection object on which the message arrived, the \fBSIP\fR message,
107 and any associated dialog.
108 .sp
109 The \fBSIP\fR message is freed once the function returns. If the application
110 wishes to use the message beyond that, it has to hold a reference on the
111 message using \fBsip_hold_msg()\fR. Similarly, if the application wishes to
112 cache the dialog, it must hold a reference on the dialog using
113 \fBsip_hold_msg()\fR.
114 .RE
116 .sp
117 .ne 2
118 .na
119 \fBsip_ulp_timeout\fR
120 .ad
121 .br
122 .na
123 \fBsip_ulp_untimeout\fR
124 .ad
125 .RS 26n
126 An application can register these two routines to implement its own routines
127 for the stack timers. Typically, an application should allow the stack to use
128 its own built-in timer routines. The built-in timer routines are used only by
129 the stack and are not available to applications. If the application registers
130 one routine, it must also register the other.
131 .sp
132 These functions must be registered for single-threaded application. Otherwise,
133 the timer thread provided by the stack could result in invoking a registered
134 callback function.
135 .RE
137 .sp
138 .ne 2
139 .na
140 \fBsip_ulp_trans_error\fR
141 .ad
142 .RS 26n
143 The application can register this routine to be notified of a transaction
144 error. An error can occur when the transaction layer tries to send a message
145 using a cached connection object which results in a failure. If this routine is
146 not registered the transaction is terminated on such a failure. The final
147 argument is for future use. It is always set to \fBNULL\fR.
148 .RE
150 .sp
151 .ne 2
152 .na
153 \fBsip_ulp_dlg_del\fR
154 .ad
155 .RS 26n
156 An application can register this routine to be notified when a dialog is
157 deleted. The dialog to be deleted is passed along with the \fBSIP\fR message
158 which caused the dialog to be deleted. The final argument is for future use. It
159 is always set to \fBNULL\fR.
160 .RE
162 .sp
163 .ne 2
164 .na
165 \fBsip_ulp_trans_state_cb\fR
166 .ad
167 .br
168 .na
169 \fBsip_ulp_dlg_state_cb\fR
170 .ad
171 .RS 26n
172 If these callback routines are registered, the stack invokes
173 \fBsip_ulp_trans_state_cb\fR when a transaction changes states and
174 \fBsip_ulp_dlg_state_cb\fR when a dialog changes states.
175 .RE
177 .SS "Connection Manager Interface"
178 .LP
179 The connection manager interfaces must be registered by the application to
180 provide I/O related functionality to the stack. These interfaces act on a
181 connection object that is defined by the application. The application registers
182 the interfaces for the stack to work with the connection object. The connection
183 object is application defined, but the stack requires that the first member of
184 the connection object is a void *, used by the stack to store connection object
185 specific information which is private to the stack.
186 .sp
187 .LP
188 The connection manager structure is supplied by:
189 .sp
190 .in +2
191 .nf
192 typedef struct sip_io_pointers_s {
193 int (*sip_conn_send)(const sip_conn_object_t, char *, int);
194 void (*sip_hold_conn_object)(sip_conn_object_t);
195 void (*sip_rel_conn_object)(sip_conn_object_t);
196 boolean_t (*sip_conn_is_stream)(sip_conn_object_t);
197 boolean_t (*sip_conn_is_reliable)(sip_conn_object_t);
198 int (*sip_conn_remote_address)(sip_conn_object_t, struct sockaddr *,
199 socklen_t *);
200 int (*sip_conn_local_address)(sip_conn_object_t, struct sockaddr *,
201 socklen_t *);
202 int (*sip_conn_transport)(sip_conn_object_t);
203 int (*sip_conn_timer1)(sip_conn_object_t);
204 int (*sip_conn_timer2)(sip_conn_object_t);
205 int (*sip_conn_timer4)(sip_conn_object_t);
206 int (*sip_conn_timerd)(sip_conn_object_t);
207 }sip_io_pointers_t;
208 .fi
209 .in -2
211 .sp
212 .ne 2
213 .na
214 \fBsip_conn_send\fR
215 .ad
216 .RS 27n
217 This function is invoked by the stack after processing an outbound \fBSIP\fR
218 message. This function is responsible for sending the \fBSIP\fR message to the
219 peer. A return of \fB0\fR indicates success. The \fBSIP\fR message is passed to
220 the function as a string, along with the length information and the associated
221 connection object.
222 .RE
224 .sp
225 .ne 2
226 .na
227 \fBsip_hold_conn_object\fR
228 .ad
229 .br
230 .na
231 \fBsip_rel_conn_object\fR
232 .ad
233 .RS 27n
234 The application provides a mechanism for the stack to indicate that a
235 connection object is in use by the stack and must not be freed. The stack uses
236 \fBsip_hold_conn_object\fR to indicate that the connection object is in use and
237 \fBsip_rel_conn_object\fR to indicate that it has been released. The connection
238 object is passed as the argument to these functions. The stack expects that the
239 application will not free the connection object if it is in use by the stack.
240 .RE
242 .sp
243 .ne 2
244 .na
245 \fBsip_conn_is_stream\fR
246 .ad
247 .RS 27n
248 The stack uses this to determine whether the connection object, passed as the
249 argument, is byte-stream oriented. Byte-stream protocols include \fBTCP\fR
250 while message-based protocols include \fBSCTP\fR and \fBUDP\fR.
251 .RE
253 .sp
254 .ne 2
255 .na
256 \fBsip_conn_is_reliable\fR
257 .ad
258 .RS 27n
259 The stack uses this to determine whether the connection object, passed as the
260 argument, is reliable. Reliable protocols include \fBTCP\fR and \fBSCTP\fR.
261 Unreliable protocols include \fBUDP\fR.
262 .RE
264 .sp
265 .ne 2
266 .na
267 \fBsip_conn_local_address\fR
268 .ad
269 .br
270 .na
271 \fBsip_conn_remote_address\fR
272 .ad
273 .RS 27n
274 These two interfaces are used by the stack to obtain endpoint information for a
275 connection object. The \fBsip_conn_local_address\fR provides the local
276 address/port information. The \fBsip_conn_remote_address\fR provides the
277 address/port information of the peer. The caller allocates the buffer and
278 passes its associated length along with it. On return, the length is updated to
279 reflect the actual length.
280 .RE
282 .sp
283 .ne 2
284 .na
285 \fBsip_conn_transport\fR
286 .ad
287 .RS 27n
288 The stack uses this to determine the transport used by the connection object,
289 passed as the argument. The transport could be \fBTCP\fR, \fBUDP\fR,
290 \fBSCTP\fR.
291 .RE
293 .sp
294 .ne 2
295 .na
296 \fBsip_conn_timer1\fR
297 .ad
298 .br
299 .na
300 \fBsip_conn_timer2\fR
301 .ad
302 .br
303 .na
304 \fBsip_conn_timer4\fR
305 .ad
306 .br
307 .na
308 \fBsip_conn_timerd\fR
309 .ad
310 .RS 27n
311 These four interfaces may be registered by an application to provide connection
312 object specific timer information. If these are not registered the stack uses
313 default values.
314 .sp
315 The interfaces provide the timer values for \fBTimer 1\fR (\fBRTT\fR estimate -
316 default \fB500\fR \fBmsec\fR), \fBTimer 2\fR (maximum retransmit interval for
317 non-\fBINVITE\fR request and \fBINVITE\fR response - default \fB4\fR
318 \fBsecs\fR), \fBTimer 4\fR (maximum duration a message will remain in the
319 network - default \fB5\fR \fBsecs\fR) and \fBTimer D\fR (wait time for response
320 retransmit interval - default \fB32\fR \fBsecs\fR).
321 .RE
323 .SS "Custom \fBSIP\fR headers"
324 .LP
325 In addition to the \fBSIP\fR headers supported by the stack, an application can
326 optionally provide a table of custom headers and associated parsing functions.
327 The table is an array with an entry for each header. If the table includes
328 headers supported by the stack, parsing functions or other application-specific
329 table entries take precedence over \fBlibsip\fR supported headers. The header
330 table structure is supplied by:
331 .sp
332 .in +2
333 .nf
334 typedef struct header_function_table {
335 char *header_name;
336 char *header_short_name;
337 int (*header_parse_func)
338 (struct sip_header *,
339 struct sip_parsed_header **);
340 boolean_t (*header_check_compliance)
341 (struct sip_parsed_header *);
342 boolean_t (*header_is_equal)
343 (struct sip_parsed_header *,
344 struct sip_parsed_header *);
345 void (*header_free)
346 (struct sip_parsed_header *);
347 }
348 .fi
349 .in -2
351 .sp
352 .ne 2
353 .na
354 \fBheader_name\fR
355 .ad
356 .RS 27n
357 The full name of the header. The application must ensure that he name does not
358 conflict with existing headers. If it does, the one registered by the
359 application takes precedence.
360 .RE
362 .sp
363 .ne 2
364 .na
365 \fBheader_short_name\fR
366 .ad
367 .RS 27n
368 Compact name, if any, for the header.
369 .RE
371 .sp
372 .ne 2
373 .na
374 \fBheader_parse_func\fR
375 .ad
376 .RS 27n
377 The parsing function for the header. The parser will set the second argument to
378 the resulting parsed structure. A return value of \fB0\fR indicates success.
379 .RE
381 .sp
382 .ne 2
383 .na
384 \fBheader_free\fR
385 .ad
386 .RS 27n
387 The function that frees the parsed header
388 .RE
390 .sp
391 .ne 2
392 .na
393 \fBheader_check_compliance\fR
394 .ad
395 .RS 27n
396 An application can optionally provide this function that will check if the
397 header is compliant or not. The compliance for a custom header will be defined
398 by the application.
399 .RE
401 .sp
402 .ne 2
403 .na
404 \fBheader_is_equal\fR
405 .ad
406 .RS 27n
407 An application can optionally provide this function to determine whether two
408 input headers are equivalent. The equivalence criteria is defined by the
409 application.
410 .RE
412 .SH RETURN VALUES
413 .LP
414 On success \fBsip_stack_init()\fR returns \fB0\fR. Otherwise, the function
415 returns the error value.
416 .sp
417 .LP
418 The value of \fBerrno\fR is not changed by these calls in the event of an
419 error.
420 .SH ERRORS
421 .LP
422 On failure, the \fBsip_stack_init()\fR function returns the following error
423 value:
424 .sp
425 .ne 2
426 .na
427 \fB\fBEINVAL\fR\fR
428 .ad
429 .RS 10n
430 If the stack version is incorrect, or if any of the mandatory functions is
431 missing.
432 .RE
434 .SH ATTRIBUTES
435 .LP
436 See \fBattributes\fR(5) for descriptions of the following attributes:
437 .sp
439 .sp
440 .TS
441 box;
442 c | c
443 l | l .
444 ATTRIBUTE TYPE ATTRIBUTE VALUE
445 _
446 Interface Stability Committed
447 _
448 MT-Level MT-Safe
449 .TE
451 .SH SEE ALSO
452 .LP
453 \fBlibsip\fR(3LIB), \fBsockaddr\fR(3SOCKET)