|
@@ -1,12 +1,11 @@
|
|
|
-
|
|
|
sca Module
|
|
|
|
|
|
Andrew Mortensen
|
|
|
|
|
|
University of Pennsylvania
|
|
|
|
|
|
- Copyright © 2012 Andrew Mortensen, [email protected]
|
|
|
- _________________________________________________________________
|
|
|
+ Copyright © 2012 Andrew Mortensen, [email protected]
|
|
|
+ __________________________________________________________________
|
|
|
|
|
|
Table of Contents
|
|
|
|
|
@@ -29,8 +28,8 @@ Andrew Mortensen
|
|
|
|
|
|
4. Functions
|
|
|
|
|
|
- 4.1. sca_handle_subscribe()
|
|
|
- 4.2. sca_call_info_update()
|
|
|
+ 4.1. sca_handle_subscribe()
|
|
|
+ 4.2. sca_call_info_update()
|
|
|
|
|
|
5. Exported RPC Commands
|
|
|
|
|
@@ -76,8 +75,8 @@ Chapter 1. Admin Guide
|
|
|
|
|
|
4. Functions
|
|
|
|
|
|
- 4.1. sca_handle_subscribe()
|
|
|
- 4.2. sca_call_info_update()
|
|
|
+ 4.1. sca_handle_subscribe()
|
|
|
+ 4.2. sca_call_info_update()
|
|
|
|
|
|
5. Exported RPC Commands
|
|
|
|
|
@@ -92,47 +91,50 @@ Chapter 1. Admin Guide
|
|
|
1. Overview
|
|
|
|
|
|
The sca module implements Shared Call Appearances. It handles SUBSCRIBE
|
|
|
- messages for call-info and line-seize events, and sends call-info NOTIFYs to
|
|
|
- line subscribers to implement line bridging. The module implements SCA as
|
|
|
- defined in Broadworks SIP Access Side Extensions Interface Specifications,
|
|
|
- Release 13.0, version 1, sections 2, 3 and 4.
|
|
|
-
|
|
|
- SCA group members receive call state notifications when other group members
|
|
|
- participate in calls. An SCA caller can place a call on hold, and the call
|
|
|
- may be retrieved from hold by another member of the group.
|
|
|
-
|
|
|
- Subscribers to SCA call-info events SUBSCRIBE to their address-of-record
|
|
|
- (AoR), asking the application server to send call-info NOTIFYs with line
|
|
|
- state information as lines in the subscriber group are used.
|
|
|
-
|
|
|
- For example, when an SCA subscriber takes the phone off hook, it sends a
|
|
|
- line-seize SUBSCRIBE to the application server. The application server
|
|
|
- acknowledges the request, and sends to the subscriber a line-seize NOTIFY
|
|
|
- with the appearance index of the line claimed for the subscriber. The
|
|
|
- application also sends call-info NOTIFYs to the other SCA subscribers to the
|
|
|
- AoR, letting them know that an appearance within the group has gone off
|
|
|
- hook. Subscribers update their display appropriately.
|
|
|
-
|
|
|
- Subscribers to an SCA address-of-record will receive call-info NOTIFYs when
|
|
|
- a member of the group seizes a line (seized); receives a 180 ringing
|
|
|
- response from the remote party (ringing); receives a 183 progressing
|
|
|
- response from the remote party (progressing); when the remote party answers
|
|
|
- the call (active); when either party in the call places the call on hold
|
|
|
- (held); and when an SCA line goes back on hook (idle).
|
|
|
-
|
|
|
- The call-info subscriber information is stored in memory and is periodically
|
|
|
- written to the database. Call state information is stored in memory. A
|
|
|
- future release may periodically write call state to the database, as well.
|
|
|
- The database is purely for restoring subscriptions after a restart of the
|
|
|
- application server. Subscriber information is also flushed to the database
|
|
|
- when the service is stopped.
|
|
|
-
|
|
|
- At the time of this writing, Polycom and Cisco handsets are known to
|
|
|
- implement the call-info and line-seize event packages defined in the
|
|
|
+ messages for call-info and line-seize events, and sends call-info
|
|
|
+ NOTIFYs to line subscribers to implement line bridging. The module
|
|
|
+ implements SCA as defined in Broadworks SIP Access Side Extensions
|
|
|
+ Interface Specifications, Release 13.0, version 1, sections 2, 3 and 4.
|
|
|
+
|
|
|
+ SCA group members receive call state notifications when other group
|
|
|
+ members participate in calls. An SCA caller can place a call on hold,
|
|
|
+ and the call may be retrieved from hold by another member of the group.
|
|
|
+
|
|
|
+ Subscribers to SCA call-info events SUBSCRIBE to their
|
|
|
+ address-of-record (AoR), asking the application server to send
|
|
|
+ call-info NOTIFYs with line state information as lines in the
|
|
|
+ subscriber group are used.
|
|
|
+
|
|
|
+ For example, when an SCA subscriber takes the phone off hook, it sends
|
|
|
+ a line-seize SUBSCRIBE to the application server. The application
|
|
|
+ server acknowledges the request, and sends to the subscriber a
|
|
|
+ line-seize NOTIFY with the appearance index of the line claimed for the
|
|
|
+ subscriber. The application also sends call-info NOTIFYs to the other
|
|
|
+ SCA subscribers to the AoR, letting them know that an appearance within
|
|
|
+ the group has gone off hook. Subscribers update their display
|
|
|
+ appropriately.
|
|
|
+
|
|
|
+ Subscribers to an SCA address-of-record will receive call-info NOTIFYs
|
|
|
+ when a member of the group seizes a line (seized); receives a 180
|
|
|
+ ringing response from the remote party (ringing); receives a 183
|
|
|
+ progressing response from the remote party (progressing); when the
|
|
|
+ remote party answers the call (active); when either party in the call
|
|
|
+ places the call on hold (held); and when an SCA line goes back on hook
|
|
|
+ (idle).
|
|
|
+
|
|
|
+ The call-info subscriber information is stored in memory and is
|
|
|
+ periodically written to the database. Call state information is stored
|
|
|
+ in memory. A future release may periodically write call state to the
|
|
|
+ database, as well. The database is purely for restoring subscriptions
|
|
|
+ after a restart of the application server. Subscriber information is
|
|
|
+ also flushed to the database when the service is stopped.
|
|
|
+
|
|
|
+ At the time of this writing, Polycom and Cisco handsets are known to
|
|
|
+ implement the call-info and line-seize event packages defined in the
|
|
|
document, which may be found freely on the web.
|
|
|
|
|
|
- To date, this module has only been tested with Polycom Soundpoint 550s and
|
|
|
- 650s running Polycom SIP 3.3.4.
|
|
|
+ To date, this module has only been tested with Polycom Soundpoint 550s
|
|
|
+ and 650s running Polycom SIP 3.3.4.
|
|
|
|
|
|
2. Dependencies
|
|
|
|
|
@@ -159,10 +161,10 @@ Chapter 1. Admin Guide
|
|
|
|
|
|
Size, as a power of two, of the shared memory hash table containing the
|
|
|
call-info subscriptions and the appearance state. A larger power of two
|
|
|
- means better performance (fewer collisions, making for fewer subscriber URI
|
|
|
- comparisons) at the expense of increased shared memory use.
|
|
|
+ means better performance (fewer collisions, making for fewer subscriber
|
|
|
+ URI comparisons) at the expense of increased shared memory use.
|
|
|
|
|
|
- Default value is 9 (2 ^ 9 == 512).
|
|
|
+ Default value is 9 (2 ^ 9 == 512).
|
|
|
|
|
|
Example 1.1. Set hash_table_size:
|
|
|
...
|
|
@@ -174,7 +176,7 @@ modparam( "sca", "hash_table_size", 8 )
|
|
|
|
|
|
The maximum allowed call-info subscription time in seconds.
|
|
|
|
|
|
- Default value is 3600 (1 hour).
|
|
|
+ Default value is 3600 (1 hour).
|
|
|
|
|
|
Example 1.2. Set call_info_max_expires:
|
|
|
...
|
|
@@ -185,12 +187,12 @@ modparam( "sca", "call_info_max_expires", 1800 )
|
|
|
|
|
|
The maximum allowed line-seize subscription time in seconds.
|
|
|
|
|
|
- Default value is 15 (15 seconds).
|
|
|
+ Default value is 15 (15 seconds).
|
|
|
|
|
|
- A maximum line-seize subscription time of 15 seconds is recommended in the
|
|
|
- SIP Access Side Extensions document. This interval is purposely short to
|
|
|
- prevent a client from seizing an appearance without making a call for
|
|
|
- extended periods of time.
|
|
|
+ A maximum line-seize subscription time of 15 seconds is recommended in
|
|
|
+ the SIP Access Side Extensions document. This interval is purposely
|
|
|
+ short to prevent a client from seizing an appearance without making a
|
|
|
+ call for extended periods of time.
|
|
|
|
|
|
Example 1.3. Set line_seize_max_expires:
|
|
|
...
|
|
@@ -199,16 +201,16 @@ modparam( "sca", "line_seize_max_expires", 30 )
|
|
|
|
|
|
3.4. purge_expired_interval (integer)
|
|
|
|
|
|
- The period of time in seconds between purges of expired call-info and
|
|
|
+ The period of time in seconds between purges of expired call-info and
|
|
|
line-seize subscriptions.
|
|
|
|
|
|
- Default value is 120 (2 minutes).
|
|
|
+ Default value is 120 (2 minutes).
|
|
|
|
|
|
- On finding an expired subscription, the module removes the subscription from
|
|
|
- the shared memory hash table, and sends a NOTIFY with Subscription-State
|
|
|
- "terminated;expired" header value to the subscriber. It also NOTIFYs other
|
|
|
- members of the group, in the event that the expired subscription was a
|
|
|
- line-seize.
|
|
|
+ On finding an expired subscription, the module removes the subscription
|
|
|
+ from the shared memory hash table, and sends a NOTIFY with
|
|
|
+ Subscription-State "terminated;expired" header value to the subscriber.
|
|
|
+ It also NOTIFYs other members of the group, in the event that the
|
|
|
+ expired subscription was a line-seize.
|
|
|
|
|
|
Example 1.4. Set purge_expired_interval:
|
|
|
...
|
|
@@ -230,7 +232,7 @@ modparam( "sca", "db_url", "mysql://kamailio:kamailiorw@localhost/kamailio" )
|
|
|
|
|
|
Name of the database table where call-info subscriptions are written.
|
|
|
|
|
|
- Default value is “sca_subscriptions�.
|
|
|
+ Default value is "sca_subscriptions".
|
|
|
|
|
|
Example 1.6. Set subs_table parameter:
|
|
|
...
|
|
@@ -239,10 +241,10 @@ modparam( "sca", "subs_table", "call_info_subscriptions" )
|
|
|
|
|
|
3.7. db_update_interval (integer)
|
|
|
|
|
|
- Period in seconds between writes of call-info subscriber information to the
|
|
|
- database.
|
|
|
+ Period in seconds between writes of call-info subscriber information to
|
|
|
+ the database.
|
|
|
|
|
|
- Default value is 300 (5 minutes).
|
|
|
+ Default value is 300 (5 minutes).
|
|
|
|
|
|
Example 1.7. Set db_update_interval:
|
|
|
...
|
|
@@ -251,20 +253,20 @@ modparam( "sca", "db_update_interval", 120 )
|
|
|
|
|
|
4. Functions
|
|
|
|
|
|
- 4.1. sca_handle_subscribe()
|
|
|
- 4.2. sca_call_info_update()
|
|
|
+ 4.1. sca_handle_subscribe()
|
|
|
+ 4.2. sca_call_info_update()
|
|
|
|
|
|
4.1. sca_handle_subscribe()
|
|
|
|
|
|
- The function handling call-info and line-seize SUBSCRIBE requests. It stores
|
|
|
- or updates the subscriptions in shared memory, and sends NOTIFYs to the
|
|
|
- subscriber and other members of the group as needed.
|
|
|
+ The function handling call-info and line-seize SUBSCRIBE requests. It
|
|
|
+ stores or updates the subscriptions in shared memory, and sends NOTIFYs
|
|
|
+ to the subscriber and other members of the group as needed.
|
|
|
|
|
|
For example, a line-seize SUBSCRIBE will cause the module to reserve an
|
|
|
- appearance index for the subscriber; send a line-seize NOTIFY to the
|
|
|
- subscriber indicating which appearance index it must use; and send call-info
|
|
|
- NOTIFYs to other subscribers to the address-of-record letting them know the
|
|
|
- appearance is off hook.
|
|
|
+ appearance index for the subscriber; send a line-seize NOTIFY to the
|
|
|
+ subscriber indicating which appearance index it must use; and send
|
|
|
+ call-info NOTIFYs to other subscribers to the address-of-record letting
|
|
|
+ them know the appearance is off hook.
|
|
|
|
|
|
This function can be used from the REQUEST_ROUTE.
|
|
|
|
|
@@ -284,19 +286,20 @@ if ( is_method( "SUBSCRIBE" )) {
|
|
|
|
|
|
4.2. sca_call_info_update()
|
|
|
|
|
|
- The sca_call_info_update function updates call state for SCA appearances. If
|
|
|
- a request or response packet contains a Call-Info header, the function
|
|
|
- extracts call state from the header and sends NOTIFYs to subscribers if
|
|
|
- needed. If no Call-Info header is included in the packet, the module looks
|
|
|
- up the To and From URIs to see if either are SCA addresses-of-record. If
|
|
|
- either the To or From URI are SCA AoRs, the function looks up the appearance
|
|
|
- by dialog and updates call state as needed, sending NOTIFYs to members of
|
|
|
- the group if the call state has changed.
|
|
|
+ The sca_call_info_update function updates call state for SCA
|
|
|
+ appearances. If a request or response packet contains a Call-Info
|
|
|
+ header, the function extracts call state from the header and sends
|
|
|
+ NOTIFYs to subscribers if needed. If no Call-Info header is included in
|
|
|
+ the packet, the module looks up the To and From URIs to see if either
|
|
|
+ are SCA addresses-of-record. If either the To or From URI are SCA AoRs,
|
|
|
+ the function looks up the appearance by dialog and updates call state
|
|
|
+ as needed, sending NOTIFYs to members of the group if the call state
|
|
|
+ has changed.
|
|
|
|
|
|
- The sca_call_info_update function updates call state for INVITE, CANCEL,
|
|
|
- BYE, PRACK and REFER requests and responses.
|
|
|
+ The sca_call_info_update function updates call state for INVITE,
|
|
|
+ CANCEL, BYE, PRACK and REFER requests and responses.
|
|
|
|
|
|
- This function can be used from the REQUEST_ROUTE, REPLY_ROUTE, and
|
|
|
+ This function can be used from the REQUEST_ROUTE, REPLY_ROUTE, and
|
|
|
FAILURE_ROUTE.
|
|
|
|
|
|
Return code:
|
|
@@ -351,7 +354,7 @@ failure_route[FAILURE_ROUTE]
|
|
|
Parameters: none
|
|
|
|
|
|
Example:
|
|
|
- sercmd sca.all_subscriptions
|
|
|
+ kamcmd sca.all_subscriptions
|
|
|
|
|
|
5.2. sca.all_appearances
|
|
|
|
|
@@ -362,13 +365,13 @@ failure_route[FAILURE_ROUTE]
|
|
|
Parameters: none
|
|
|
|
|
|
Example:
|
|
|
- sercmd sca.all_appearances
|
|
|
+ kamcmd sca.all_appearances
|
|
|
|
|
|
5.3. sca.seize_appearance
|
|
|
|
|
|
- Seize an appearance index for a specific contact within an SCA group, and
|
|
|
- notify other members of the group that the appearance is off hook. Useful
|
|
|
- for testing SCA signaling.
|
|
|
+ Seize an appearance index for a specific contact within an SCA group,
|
|
|
+ and notify other members of the group that the appearance is off hook.
|
|
|
+ Useful for testing SCA signaling.
|
|
|
|
|
|
Name: sca.seize_appearance
|
|
|
|
|
@@ -379,31 +382,32 @@ failure_route[FAILURE_ROUTE]
|
|
|
Example:
|
|
|
# seize next available appearance of sip:[email protected]
|
|
|
# for contact sip:[email protected]
|
|
|
- sercmd sca.seize_appearance sip:[email protected] sip:[email protected].
|
|
|
-1.2
|
|
|
+ kamcmd sca.seize_appearance sip:[email protected] sip:[email protected].1
|
|
|
+.2
|
|
|
|
|
|
5.4. sca.update_appearance
|
|
|
|
|
|
- Update the state of an in-use appearance index, and notify other members of
|
|
|
- the group. Useful for testing SCA signaling.
|
|
|
+ Update the state of an in-use appearance index, and notify other
|
|
|
+ members of the group. Useful for testing SCA signaling.
|
|
|
|
|
|
Name: sca.update_appearance
|
|
|
|
|
|
Parameters: 3 or 4
|
|
|
* SCA Address-of-Record
|
|
|
* Index of In-Use Appearance
|
|
|
- * Appearance State (seized, ringing, progressing, active, held,
|
|
|
+ * Appearance State (seized, ringing, progressing, active, held,
|
|
|
held-private)
|
|
|
* Appearance Display Info (Optional)
|
|
|
|
|
|
Example:
|
|
|
# update in-use appearance index 3 of sip:[email protected]
|
|
|
# state held.
|
|
|
- sercmd sca.update_appearance sip:[email protected] 3 held
|
|
|
+ kamcmd sca.update_appearance sip:[email protected] 3 held
|
|
|
|
|
|
5.5. sca.release_appearance
|
|
|
|
|
|
- Set a non-idle appearance index to idle and NOTIFY members of the group.
|
|
|
+ Set a non-idle appearance index to idle and NOTIFY members of the
|
|
|
+ group.
|
|
|
|
|
|
Name: sca.release_appearance
|
|
|
|
|
@@ -414,12 +418,12 @@ failure_route[FAILURE_ROUTE]
|
|
|
Example:
|
|
|
# release appearance of sip:[email protected] with
|
|
|
# appearance index 3
|
|
|
- sercmd sca.release_appearance sip:[email protected] 3
|
|
|
+ kamcmd sca.release_appearance sip:[email protected] 3
|
|
|
|
|
|
6. Sample kamailio.cfg with SCA
|
|
|
|
|
|
- The following is a basic kamailio.cfg providing Shared Call Appearances to
|
|
|
- local subscribers. It has been tested with Polycom handsets.
|
|
|
+ The following is a basic kamailio.cfg providing Shared Call Appearances
|
|
|
+ to local subscribers. It has been tested with Polycom handsets.
|
|
|
|
|
|
Example 1.10. kamailio.cfg
|
|
|
##
|
|
@@ -468,8 +472,8 @@ port=5060
|
|
|
#!ifdef WITH_SRCPATH
|
|
|
mpath="modules_k:modules"
|
|
|
#!else
|
|
|
-mpath="/usr/local/kamailio/lib64/kamailio/modules_k/:/usr/local/kamailio/lib64/
|
|
|
-kamailio/modules/"
|
|
|
+mpath="/usr/local/kamailio/lib64/kamailio/modules_k/:/usr/local/kamailio/lib64/k
|
|
|
+amailio/modules/"
|
|
|
#!endif
|
|
|
|
|
|
#!ifdef WITH_MYSQL
|
|
@@ -581,7 +585,7 @@ request_route {
|
|
|
if (t_check_trans()) {
|
|
|
route(SCA);
|
|
|
t_relay();
|
|
|
- }
|
|
|
+ }
|
|
|
exit;
|
|
|
}
|
|
|
|
|
@@ -660,8 +664,8 @@ route[WITHINDLG] {
|
|
|
# take the path determined by record-routing
|
|
|
if (loose_route()) {
|
|
|
if ( is_method("NOTIFY") ) {
|
|
|
- # Add Record-Route for in-dialog NOTIFY as per
|
|
|
-RFC 6665.
|
|
|
+ # Add Record-Route for in-dialog NOTIFY as per R
|
|
|
+FC 6665.
|
|
|
record_route();
|
|
|
}
|
|
|
route(RELAY);
|
|
@@ -679,8 +683,8 @@ RFC 6665.
|
|
|
t_relay();
|
|
|
exit;
|
|
|
} else {
|
|
|
- # ACK without matching transaction ...
|
|
|
-ignore and discard
|
|
|
+ # ACK without matching transaction ... i
|
|
|
+gnore and discard
|
|
|
exit;
|
|
|
}
|
|
|
}
|
|
@@ -758,8 +762,7 @@ route[AUTH] {
|
|
|
route[SCA] {
|
|
|
#!ifdef WITH_SCA
|
|
|
if(is_method("SUBSCRIBE")) {
|
|
|
- if ($hdr(Event) == "call-info" || $hdr(Event) == "line-seize")
|
|
|
-{
|
|
|
+ if ($hdr(Event) == "call-info" || $hdr(Event) == "line-seize") {
|
|
|
xdbg("SCA: $hdr(Event) SUBSCRIBE $ru from $si:$sp");
|
|
|
sca_handle_subscribe();
|
|
|
exit;
|
|
@@ -795,10 +798,9 @@ route[XMLRPC] {
|
|
|
# allow XMLRPC from localhost
|
|
|
if ((method=="POST" || method=="GET")
|
|
|
&& (src_ip==127.0.0.1)) {
|
|
|
- # close connection only for xmlrpclib user agents (there is a b
|
|
|
-ug in
|
|
|
- # xmlrpclib: it waits for EOF before interpreting the response)
|
|
|
-.
|
|
|
+ # close connection only for xmlrpclib user agents (there is a bu
|
|
|
+g in
|
|
|
+ # xmlrpclib: it waits for EOF before interpreting the response).
|
|
|
if ($hdr(User-Agent) =~ "xmlrpclib")
|
|
|
set_reply_close();
|
|
|
set_reply_no_connect();
|