1a634d05ec3764a116bc0c29402f8dacbccf5f2f
[sip-router] / README
1
2 sca Module
3
4 Andrew Mortensen
5
6    University of Pennsylvania
7
8    Copyright © 2012 Andrew Mortensen, admorten@isc.upenn.edu
9      _________________________________________________________________
10
11    Table of Contents
12
13    1. Admin Guide
14
15         1. Overview
16         2. Dependencies
17
18               2.1. Modules
19
20         3. Parameters
21
22               3.1. domain (str)
23               3.2. hash_table_size (integer)
24               3.3. call_info_max_expires (integer)
25               3.4. line_seize_max_expires (integer)
26               3.5. purge_expired_interval (integer)
27               3.6. db_url (str)
28               3.7. subs_table (str)
29               3.8. db_update_interval (integer)
30
31         4. Functions
32
33               4.1. sca_handle_subscribe() 
34               4.2. sca_call_info_update() 
35
36         5. Exported RPC Commands
37
38               5.1. sca.all_subscriptions
39               5.2. sca.all_appearances
40               5.3. sca.release_appearance
41
42    List of Examples
43
44    1.1. Set domain parameter:
45    1.2. Set hash_table_size:
46    1.3. Set call_info_max_expires:
47    1.4. Set line_seize_max_expires:
48    1.5. Set purge_expired_interval:
49    1.6. Set db_url parameter:
50    1.7. Set subs_table parameter:
51    1.8. Set db_update_interval:
52    1.9. sca_handle_subscribe usage:
53    1.10. sca_call_info_update usage:
54
55 Chapter 1. Admin Guide
56
57    Table of Contents
58
59    1. Overview
60    2. Dependencies
61
62         2.1. Modules
63
64    3. Parameters
65
66         3.1. domain (str)
67         3.2. hash_table_size (integer)
68         3.3. call_info_max_expires (integer)
69         3.4. line_seize_max_expires (integer)
70         3.5. purge_expired_interval (integer)
71         3.6. db_url (str)
72         3.7. subs_table (str)
73         3.8. db_update_interval (integer)
74
75    4. Functions
76
77         4.1. sca_handle_subscribe() 
78         4.2. sca_call_info_update() 
79
80    5. Exported RPC Commands
81
82         5.1. sca.all_subscriptions
83         5.2. sca.all_appearances
84         5.3. sca.release_appearance
85
86 1. Overview
87
88    The sca module implements Shared Call Appearances. It handles SUBSCRIBE
89    messages for call-info and line-seize events, and sends call-info NOTIFYs to
90    line subscribers to implement line bridging. The module implements SCA as
91    defined in Broadworks SIP Access Side Extensions Interface Specifications,
92    Release 13.0, version 1, sections 2, 3 and 4.
93
94    SCA group members are receive call state notifications when other group
95    members participate in calls. An SCA caller can place a call on hold, and
96    the call may be retrieved from hold by another member of the group.
97
98    Subscribers to SCA call-info events SUBSCRIBE to their address-of-record
99    (AoR), asking the application server to send call-info NOTIFYs with line
100    state information as lines in the subscriber group are used.
101
102    For example, when an SCA subscriber takes the phone off hook, if sends a
103    line-seize SUBSCRIBE to the application server. The application server
104    acknowledges the request, and sends to the subscriber a line-seize NOTIFY
105    with  the appearance index of the line claimed for the subscriber. The
106    application also sends call-info NOTIFYs to the other SCA subscribers to the
107    AoR, letting them know that an appearance within the group has gone off
108    hook. Subscribers update their display appropriately.
109
110    Subscribers to an SCA address-of-record will receive call-info NOTIFYs when
111    a  member  of the group seizes a line (seized); receives a 180 ringing
112    response  from  the remote party (ringing); receives a 183 progressing
113    response from the remote party (progressing); when the remote party answers
114    the call (active); when either party in the call places the call on hold
115    (held); and when an SCA line goes back on hook (idle).
116
117    The call-info subscriber information is stored in memory and is periodically
118    written to the database. Call state information is stored in memory. A
119    future release may periodically write call state to the database, as well.
120    The database is purely for restoring subscriptions after a restart of the
121    application server. Subscriber information is also flushed to the database
122    when the service is stopped.
123
124    The  module  implements  SCA  as defined in Broadworks SIP Access Side
125    Extensions Interface Specifications, Release 13.0, version 1, sections 2, 3
126    and 4. At the time of this writing, Polycom and Cisco handsets are known to
127    implement  the  call-info and line-seize event packages defined in the
128    document, which may be found freely on the web.
129
130    To date, this module has only been tested with Polycom Soundpoint 550s and
131    650s running Polycom SIP 3.3.4.
132
133 2. Dependencies
134
135    2.1. Modules
136
137 2.1. Modules
138
139    The following modules must be loaded before this module:
140      * a database module
141      * sl
142      * tm
143
144 3. Parameters
145
146    3.1. domain (str)
147    3.2. hash_table_size (integer)
148    3.3. call_info_max_expires (integer)
149    3.4. line_seize_max_expires (integer)
150    3.5. purge_expired_interval (integer)
151    3.6. db_url (str)
152    3.7. subs_table (str)
153    3.8. db_update_interval (integer)
154
155 3.1. domain (str)
156
157    SIP domain to use in SCA NOTIFY Call-Info headers.
158
159    The module uses this value as the SIP domain in Call-Info headers sent with
160    call-info and line-seize NOTIFYs. The domain must match the domain in the
161    SCA line's address-of-record.
162
163    This parameter is required. A future update of the module may extract this
164    value from client SUBSCRIBEs.
165
166    Example 1.1. Set domain parameter:
167 ...
168 modparam( "sca", "domain", "voice.example.org" )
169 ...
170
171 3.2. hash_table_size (integer)
172
173    Size, as a power of two, of the shared memory hash table containing the
174    call-info subscriptions and the appearance state. A larger power of two
175    means better performance (fewer collisions, making for fewer subscriber URI
176    comparisons) at the expense of increased shared memory use.
177
178    Default value is 9 (2 ^ 9 == 512). 
179
180    Example 1.2. Set hash_table_size:
181 ...
182 # create shared memory hash table with 2^8 (256) slots
183 modparam( "sca", "hash_table_size", 8 )
184 ...
185
186 3.3. call_info_max_expires (integer)
187
188    The maximum allowed call-info subscription time in seconds.
189
190    Default value is 3600 (1 hour). 
191
192    Example 1.3. Set call_info_max_expires:
193 ...
194 modparam( "sca", "call_info_max_expires", 1800 )
195 ...
196
197 3.4. line_seize_max_expires (integer)
198
199    The maximum allowed line-seize subscription time in seconds.
200
201    Default value is 15 (15 seconds). 
202
203    A maximum line-seize subscription time of 15 seconds is recommended in the
204    SIP Access Side Extensions document. This interval is purposely short to
205    prevent  a client from seizing an appearance without making a call for
206    extended periods of time.
207
208    Example 1.4. Set line_seize_max_expires:
209 ...
210 modparam( "sca", "line_seize_max_expires", 30 )
211 ...
212
213 3.5. purge_expired_interval (integer)
214
215    The  period of time in seconds between purges of expired call-info and
216    line-seize subscriptions.
217
218    Default value is 120 (2 minutes). 
219
220    On finding an expired subscription, the module removes the subscription from
221    the shared memory hash table, and sends a NOTIFY with Subscription-State
222    "terminated;expired" header value to the subscriber. It also NOTIFYs other
223    members of the group, in the event that the expired subscription was a
224    line-seize.
225
226    Example 1.5. Set purge_expired_interval:
227 ...
228 modparam( "sca", "purge_expired_interval", 60 )
229 ...
230
231 3.6. db_url (str)
232
233    URL of database to which subscribers will be written.
234
235    Default value is mysql://openser:openserrw@localhost/openser
236
237    Example 1.6. Set db_url parameter:
238 ...
239 modparam( "sca", "db_url", "mysql://openser:openserrw@localhost/openser" )
240 ...
241
242 3.7. subs_table (str)
243
244    Name of the database table where call-info subscriptions are written.
245
246    Default value is “sca_subscriptions”. 
247
248    Example 1.7. Set subs_table parameter:
249 ...
250 modparam( "sca", "subs_table", "call_info_subscriptions" )
251 ...
252
253 3.8. db_update_interval (integer)
254
255    Period in seconds between writes of call-info subscriber information to the
256    database.
257
258    Default value is 300 (5 minutes). 
259
260    Example 1.8. Set db_update_interval:
261 ...
262 modparam( "sca", "db_update_interval", 120 )
263 ...
264
265 4. Functions
266
267    4.1. sca_handle_subscribe() 
268    4.2. sca_call_info_update() 
269
270 4.1.  sca_handle_subscribe()
271
272    The function handling call-info and line-seize SUBSCRIBE requests. It stores
273    or updates the subscriptions in shared memory, and sends NOTIFYs to the
274    subscriber and other members of the group as needed.
275
276    For example, a line-seize SUBSCRIBE will cause the module to reserve an
277    appearance  index  for the subscriber; send a line-seize NOTIFY to the
278    subscriber indicating which appearance index it must use; and send call-info
279    NOTIFYs to other subscribers to the address-of-record letting them know the
280    appearance is off hook.
281
282    This function can be used from the REQUEST_ROUTE.
283
284    Return code:
285      * 1 - successful
286      * -1 - failed, error logged
287
288    Example 1.9. sca_handle_subscribe usage:
289 ...
290 if ( method == "SUBSCRIBE" &&
291         ( @hf_value.event == "call-info" || @hf_value.event == "line_seize" ))
292 {
293     sca_handle_subscribe();
294 }
295 ...
296
297 4.2.  sca_call_info_update()
298
299    The sca_call_info_update function updates call state for SCA appearances. If
300    a request or response packet contains a Call-Info header, the function
301    extracts call state from the header and sends NOTIFYs to subscribers if
302    needed. If no Call-Info header is included in the packet, the module looks
303    up the To and From URIs to see if either are SCA addresses-of-record. If
304    either  the  To  or  From URI are SCA, AoRs, the function looks up the
305    appearance by dialog, and updates call state as needed, sending NOTIFYs to
306    members of the group if the call state has changed.
307
308    The sca_call_info_update function updates call state for INVITE, CANCEL,
309    BYE, PRACK and REFER requests and responses.
310
311    This  function  can  be  used from the REQUEST_ROUTE, REPLY_ROUTE, and
312    FAILURE_ROUTE.
313
314    Return code:
315      * 1 - successful
316      * -1 - failed, error logged
317
318    Example 1.10. sca_call_info_update usage:
319 ...
320 route
321 {
322     ...
323     if ( $fu.sca == "y" ) {
324         sca_call_info_update();
325     }
326     ...
327 }
328
329 onreply_route[REPLY_ROUTE]
330 {
331 ...
332     if ( status =~ "[456][0-9][0-9]" ) {
333         # don't update SCA state here, since there may be
334         # failure route processing (e.g., call forwarding).
335         # update state in failure route instead.
336         break;
337     }
338
339     sca_call_info_update();
340 ...
341 }
342
343 failure_route[FAILURE_ROUTE]
344 {
345 ...
346     sca_call_info_update();
347 ...
348 }
349 ...
350
351 5. Exported RPC Commands
352
353    5.1. sca.all_subscriptions
354    5.2. sca.all_appearances
355    5.3. sca.release_appearance
356
357 5.1. sca.all_subscriptions
358
359    List all current call-info and line-seize subscriptions.
360
361    Name: sca.all_subscriptions
362
363    Parameters: none
364
365    Example:
366             sercmd sca.all_subscriptions
367
368 5.2. sca.all_appearances
369
370    List all SCA appearances with non-idle state.
371
372    Name: sca.all_appearances
373
374    Parameters: none
375
376    Example:
377             sercmd sca.all_appearances
378
379 5.3. sca.release_appearance
380
381    Set a non-idle appearance index to idle and NOTIFY members of the group.
382
383    Name: sca.release_appearance
384
385    Parameters: 2
386      * SCA Address-of-Record
387      * Appearance Index
388
389    Example:
390             # release appearance of sip:215@voice.example.com with
391             # appearance index 3
392             sercmd sca.release_appearance sip:215@voice.example.com 3