Skip to content

Commit

Permalink
- updated docs for the module
Browse files Browse the repository at this point in the history
  • Loading branch information
@bogdan-iancu
bogdan-iancu committed Jul 31, 2013
1 parent 346510b commit 7643f6e
Show file tree
Hide file tree
Showing 3 changed files with 512 additions and 161 deletions.
207 changes: 183 additions & 24 deletions modules/presence_callinfo/README
View file
Expand Up @@ -4,50 +4,115 @@ Ovidiu Sas

<osas@voipembedded.com>

Bogdan-Andrei Iancu

<bogdan@opensips.org>

Edited by

Ovidiu Sas

<osas@voipembedded.com>

Copyright © 2010 VoIP Embedded, Inc.
Edited by

Bogdan-Andrei Iancu

<bogdan@opensips.org>

Copyright © 2010-2013 VoIP Embedded, Inc. ,
www.opensips-solutions.com
Revision History
Revision $Revision: 7754 $ $Date: 2011-02-23 20:57:21 +0200
(Wed, 23 Feb 2011) $
Revision $Revision: 7754 $ $Date$
__________________________________________________________

Table of Contents

1. Admin Guide

1.1. Overview
1.2. Dependencies
1.2. Usage modes

1.2.1. OpenSIPS Modules
1.2.2. External Libraries or Applications
1.2.1. External publishing
1.2.2. Internal publishing

1.3. Exported Parameters
1.3. Dependencies

1.3.1. call_info_timeout_notification (int)
1.3.2. line_seize_timeout_notification (int)
1.3.1. OpenSIPS Modules
1.3.2. External Libraries or Applications

1.4. Exported Functions
1.4. Exported Parameters

1.4.1. call_info_timeout_notification (int)
1.4.2. line_seize_timeout_notification (int)
1.4.3. disable_dialog_support_for_sca (int)
1.4.4. line_hash_size (int)

1.5. Exported Functions

1.5.1. sca_set_calling_line([line])
1.5.2. sca_set_called_line([line])

List of Examples

1.1. Set call_info_timeout_notification parameter
1.2. Set line_seize_timeout_notification parameter
1.3. Set disable_dialog_support_for_sca parameter
1.4. Set line_hash_size parameter
1.5. sca_set_calling_line() usage
1.6. sca_set_called_line() usage

Chapter 1. Admin Guide

1.1. Overview

This module provides OpenSIPS support for shared call
appearances (SCA) as defined by BroadWorks SIP Access Side
Extensions Interface specifications. The SCA mechanism is a
fundamental building block for a variety of enhanced telephony
services. Features like attendant console, line extensions, and
key system emulation cannot be delivered without some mechanism
for sharing call appearances across access devices. Although
SIP (RFC 3261) by itself offers no inherent semantics for
supporting SCA features, when coupled with an appropriate
instantiation of the “SIP Specific Event Notification”
framework (RFC 3265), these services can be deployed quite
easily in a distributed network.

A shared line is an address of record managed by central
controlling element, such as an application server. The
application server allows multiple endpoints to register
locations against the address of record. The application server
is responsible for policing who can register and who cannot
register against the shared line.

The module enables the handling of "call-info" and "line-seize"
events inside the presence module. It is used with the general
event handling module: presence and it constructs and adds
"Call-Info" headers to notification events. To send "call-info"
notification to watchers, a third-party application must
publish "call-info" events to the presence server.
"Call-Info" headers to notification events.

1.2. Usage modes

The module can be used in two ways (depending on who is doing
the publishing of the "call-info" data:
* external publishing - the "call-info" data is received from
a third party via SIP PUBLISH requests. In this mode, the
modules simply distributes the SCA info, it is not
producing any of it - a third-party application must
publish "call-info" events to the presence server.
* internal publishing - the "call-info" data is internally
generated by the module, based on the information received
from the dialog module - what calls are using what
line/index, what is the state of the call, etc. There is no
SIP PUBLISH in this case and there is no need for a
third-party - the module is self-sufficient and stand alone
as functionality.

The used mode can be controlled via the module parameter
"disable_dialog_support_for_sca" - see below in the parameter's
section.

1.2.1. External publishing

The module does not currently implement any authorization
rules. It assumes that publish requests are only issued by a
Expand All @@ -56,9 +121,6 @@ Chapter 1. Admin Guide
can thus be easily done by OpenSIPS configuration file before
calling handle_publish() and handle_subscribe() functions.

The module implements a simple check for the presence of
Call-Info headers in received PUBLISH requests.

To get better understanding on how the module works please take
a look at the follwing figure:

Expand Down Expand Up @@ -106,20 +168,49 @@ alice@example presence bob@example watcher@example
checks for active watchers of the presentity. The active
watcher is notified via a NOTIFY SIP request.

1.2. Dependencies
1.2.2. Internal publishing

1.2.1. OpenSIPS Modules
In this mode, the module requires the "dialog" module to be
loaded into OpenSIPS. All the publishing will be automatically
done (the modules will exchange data directly via C API).

From presence perspective, the OpenSIPS script must be
configured to handle the SUBSCRIBE requests only (there is no
need for PUBLISH handling as there is no SIP publishing in this
mode). So be sure to use the "handle_subscribe()" function
(from presence module) in the script.

To trigger the internal publishing (from the dialog module) for
a certain call, use the "sca_set_calling_line()" or
"sca_set_called_line()" functions from the script when handling
a new call. These functions will do all the work (creating
dialog, setting the internal publishing, etc) - you just need
to use them and eventually specify the name of the line (if
other then the one from the SIP INVITE) - see the below
documentation.

LIMITATIONS : in this mode, the module does not really check if
the line exists or not (like defined) - it blindly trust the
traffic; also there is no check on how many indexes are for
each line. Such information (lines and indexes) are not
provisioned into the module, but the module will dynamically
accept and handle any line and index based on the SIP traffic.

1.3. Dependencies

1.3.1. OpenSIPS Modules

The following modules must be loaded before this module:
* presence.
* dialog.

1.2.2. External Libraries or Applications
1.3.2. External Libraries or Applications

None.

1.3. Exported Parameters
1.4. Exported Parameters

1.3.1. call_info_timeout_notification (int)
1.4.1. call_info_timeout_notification (int)

Enables or disables call_info event timeout notifications.

Expand All @@ -130,7 +221,7 @@ alice@example presence bob@example watcher@example
modparam("presence_callinfo", "call_info_timeout_notification", 0)
...

1.3.2. line_seize_timeout_notification (int)
1.4.2. line_seize_timeout_notification (int)

Enables or disables line_seize event timeout notifications.

Expand All @@ -141,6 +232,74 @@ modparam("presence_callinfo", "call_info_timeout_notification", 0)
modparam("presence_callinfo", "line_seize_timeout_notification", 1)
...

1.4. Exported Functions
1.4.3. disable_dialog_support_for_sca (int)

Disables the internal publishing of the "call-info" events
(generated by the dialog module). The publishing is expected to
be done via SIP PUBLISH from a third-party. See the wroking
mode described in the beginning of this document.

Default value is “0” (not disabled).

Example 1.3. Set disable_dialog_support_for_sca parameter
...
modparam("presence_callinfo", "disable_dialog_support_for_sca", 1)
...

1.4.4. line_hash_size (int)

Allows you to controll the size of the internal hash table used
for storing the information about the lines and indexes (in the
internal publishing mode).

The value must be a power of 2. You may consider increasing the
value if using a large set of lines (>1000).

Default value is “64”.

Example 1.4. Set line_hash_size parameter
...
modparam("presence_callinfo", "line_hash_size", 128)
...

1.5. Exported Functions

1.5.1. sca_set_calling_line([line])

The function (to be used only in internal publishing mode) is
setting for the current new call (initinal INVITE) the outbound
line - the line used for calling out.

If no parameter is provided, the name of the line is taken from
the SIP FROM header of the INVITE. You can override that by
providing the name of the line a parameter - be careful as the
value must be a SIP URI ! Variables are accepted.

None to be used in configuration file.
This function can be used from REQUEST_ROUTE.

Example 1.5. sca_set_calling_line() usage
...
if (is_method("INVITE") and !has_totag()) {
sca_set_calling_line();
}
...

1.5.2. sca_set_called_line([line])

The function (to be used only in internal publishing mode) is
setting for the current new call (initinal INVITE) the inbound
line - the line the call was received on.

If no parameter is provided, the name of the line is taken from
the SIP RURI of the INVITE. You can override that by providing
the name of the line a parameter - be careful as the value must
be a SIP URI ! Variables are accepted.

This function can be used from REQUEST_ROUTE.

Example 1.6. sca_set_called_line() usage
...
if (is_method("INVITE") and !has_totag()) {
sca_set_called_line();
}
...
77 changes: 44 additions & 33 deletions modules/presence_callinfo/doc/presence_callinfo.xml
View file
Expand Up @@ -13,39 +13,50 @@
]>

<book>
<bookinfo>
<title>Presence_CallInfo Module</title>
<productname class="trade">&osipsname;</productname>
<authorgroup>
<author>
<firstname>Ovidiu</firstname>
<surname>Sas</surname>
<email>osas@voipembedded.com</email>
</author>
<editor>
<firstname>Ovidiu</firstname>
<surname>Sas</surname>
<email>osas@voipembedded.com</email>
</editor>
</authorgroup>
<copyright>
<year>2010</year>
<holder>
<ulink url="http://www.voipembedded.com">VoIP Embedded, Inc.</ulink>
</holder>
</copyright>
<revhistory>
<revision>
<revnumber>$Revision: 7754 $</revnumber>
<date>$Date$</date>
</revision>
</revhistory>
</bookinfo>
<toc></toc>

&admin;
&faq;

<bookinfo>
<title>Presence_CallInfo Module</title>
<productname class="trade">&osipsname;</productname>
<authorgroup>
<author>
<firstname>Ovidiu</firstname>
<surname>Sas</surname>
<email>osas@voipembedded.com</email>
</author>
<author>
<firstname>Bogdan-Andrei</firstname>
<surname>Iancu</surname>
<email>bogdan@opensips.org</email>
</author>
<editor>
<firstname>Ovidiu</firstname>
<surname>Sas</surname>
<email>osas@voipembedded.com</email>
</editor>
<editor>
<firstname>Bogdan-Andrei</firstname>
<surname>Iancu</surname>
<email>bogdan@opensips.org</email>
</editor>
</authorgroup>
<copyright>
<year>2010-2013</year>
<holder>
<ulink url="http://www.voipembedded.com">VoIP Embedded, Inc.</ulink>
</holder>
<holder>&osipssol;</holder>
</copyright>
<revhistory>
<revision>
<revnumber>$Revision: 7754 $</revnumber>
<date>$Date$</date>
</revision>
</revhistory>
</bookinfo>
<toc></toc>

&admin;
&faq;

</book>


0 comments on commit 7643f6e

Please sign in to comment.