CSTA Inside Files

                          mod_csta_socket - CSTA interface for FreeSWITCH

1. Capabilities

Module implements ECMA-269 - Services for Computer Supported Telecommunications Applications (CSTA) Phase III protocol to make possible to control FreeSWITCH switching functions from supporting applications.

As a communication & encoding interface CSTA XML over TCP without SOAP is supported yet (ECMA-323 Annex J-2).

If used alongh with mod_uacsta with compatible phones, module can use uaCSTA to augment existing B2BUA functionality to invoke features on the SIP phone not possible with standard SIP. Check readme of mod_uacsta for further details and configuration.

Module is based on CSTA Inside library and uses AsmXml for Xml decoding.

Supported device types:

1.1. internal subscribers - internal subscribers are mapped to CSTA "dialingNumber" type of devices. The dialing sequence is the phone number without any leading characters

1.2 queues Queues are able to enqueue multiple calls. To configure a CSTA queue, add the csta_trigger_queue application to a dialplan entry:

<action application="csta_trigger_queue" data="9500"/>

Data is the name of the queue. In CSTA events and requeust, the queue will be referenced as a device with type of "deviceNumber". The callNr will be concatenated with a type ID of "02" and the queue name (029500 on the above example). Queue name should be numeric to comply with CSTA standard.

To let the call wait on the queue without being interrupted, add the csta_wait application to the dialplan entry.

Example for queue calls to implement CSTA based IVR:

<include> <extension name="csta_ivr"> <condition field="destination_number" expression="^95([0-9][0-9])$"> <action application="csta_trigger_queue" data="95$1"/>
<action application="answer"/> <action application="set" data="playback_terminators=none"/> <action application="set" data="RECORD_MIN_SEC=0"/>
<action application="csta_wait" data="1800000"/>
</condition>
</extension>
</include>

1.3 network interfaces Network interfaces or trunks representing devices via calls can leave or enter the CSTA subdomain. To configure CSTA NIDs, add the csta_trigger_trunk_inbound and csta_trigger_trunk_outbound application to the corresponding dialplan entry (if a call is directed to a gateway or external call directed into FreeSWITCH):

outgoing example:

<extension name="outbound_example"> <condition field="destination_number" expression="^20(.*)$"> <action application="csta_trigger_trunk_outbound" data="20"/>
<action application="bridge" data="sofia/gateway/example_gw/$1"/> </condition> </extension>

incoming example:

<extension name="inbound_example"> <condition field="destination_number" expression="^193190$">
<action application="csta_trigger_trunk_inbound" data="20"/> <action application="set" data="domain_name=$${domain}"/>
<action application="transfer" data="9500 XML default"/> </condition> </extension>

Data is the name of the queue. In CSTA events and requeust, the NID will be referenced as a device with type of "deviceNumber". The callNr will be concatenated with a type ID of "01" and the NID name (0120 on the above example). NID name should be numeric to comply with CSTA standard.

The following CSTA messages are implemented:

requests and responses: - Monitor Start Starts monitoring of a device. Supported types: internal subscriber, queue, NID

• Monitor Stop Stops monitoring of a device.

• Make Call Originates a call to an extension Supported types: callingDevice: internal subscriber calledDirectoryNumber: any extension, used as dialing string Do Not Prompt (auto originate) option works only with devices supporting sip_auto_answer flag

• Make Predictive Call Originates a call to an extension with dialing the called device first Supported types: callingDevice: internal subscriber, queue calledDirectoryNumber: any extension, used as dialing string or sofia/xxx url

• Answer Call Answers a ringing call Supported Types: internal subscriber (device should support auto answer), queue

• Single Step Transfer Call Transfers a connection to another endpoint without hold & consultation Supported types: activeCall: internal subscriber, queue. transferredTo: any extension, used as dialing string.

• Play Message Plays a wavefile for a connected connection. Wavefile path relative to "/sounds/en/us/callie" is to specify in messageToBePlayed parameter. If positive response is returned, check Stop event for result of the service. Supported types: internal subscriber, queue

• Record Message Records a connection to a wavefile. Wavefile path relative to "/sounds/en/us/callie" can be specified in resource parameter. If not specified, filename is generated by the service and returned (with full path) in the response. Supported types: internal subscriber, queue

• Stop Stops playing or recording of a wavefile. Supported types: internal subscriber, queue

• Clear Connection Clears an active connection. Supported types: internal subscriber, queue, NID

• Snapshot Device Returns the active connections of a device. Supported types: internal subscriber, queue, NID

• Snapshot Call Returns the devices participating in an active call. Supported types: internal subscriber, queue, NID

• Deflect Call Transfers a connection to another endpoint Supported types: callToBeDiverted: internal subscriber, queue. newDestination: any extension, used as dialing string.

• Hold Call Places an active connection on hold

• Retrieve Call Retrieves a held connection

• Consult Call Places an active connection on hold and initiates consultation to an other party

• Reconnect Call Clears active connection and reconnect to held call

• Alternate Call After consultation switch between the active phone call and the call on hold

• Transfer Call Connects active and held connection after consultation and leaves the call. Requires uaCSTA.

• Conference Call Merges active and held connection after consultation to a single call. Requires uaCSTA.

• System Status Traces device and call maps. Also can be sent by FreeSWITCH to application periodically if enabled in configuration.

• Request System Status Returns actual FreeSWITCH status. It can trace device and call maps regularly if enable in configuration.

events: - Service Initiated Generated if an outbound channel is created from a device Supported types: internal subscriber, network interface

• Originated Generated from the caller if call is delivered Supported types: internal subscriber

• Delivered Generated if call is delivered to called party Supported types: internal subscriber

• Established Generated if channel is answered Supported types: internal subscriber, queue, network interface

• Connection Cleared Generated if a device leaves a call Supported types: internal subscriber, queue, network interface

• Queued Generated if a call enters a queue Supported types: internal subscriber, queue, network interface

• DTMF Detected Generated if a DTMF tone is detected on a connected connection Supported types: internal subscriber, queue (if a device connected to a queue generates a tone), network interface Note: On queues FreeSWITCH only detects DTMF if acoustic conection is on. Workaround: add <action application="playback" data="silence_stream://1800000"/> after queue is answered to queue dialplan.

• Play Generated if playback application is started. The "message" field contains the soundfile relative path.

• Record Generated if record application is started. The "message" field contains the soundfile relative path.

• Stop
  Generated if playback or record application is stopped. The "message" field contains the soundfile relative path. The "cause" field is set to "endOfMessageDetected" if file played successfully or stop service is invoked, "resourcesNotAvailable" if file not found, and "blocked" if playback failed from any other reason. For recording "messageDurationExceeded" cause is used if record stopped after recording length reached maxDuration or stop service is invoked. If recording stopped because of hangup, no Stop event will be generated, only Connection Cleared.

• Diverted Generated if ringing call is moved to other destination after DeflectCall service.

• Transferred Indicates the connection has been moved to other device. ("TransferedEvent" due to ECMA-323)

• Held Indicates that a call has been placed on hold.

• Retrieved Indicates that a previously held call has been retrieved.

• Conferenced The Conferenced event indicates that the conferencing device has conferenced itself or another device with an existing call and that no devices have been removed from the resulting call.

• Network Reached Indicates connection reaches an outgoing network interface

• Out of Service Indicates that the device has become unavailable (i.e. unsubscribed, disconnected)

• Back in Service Indicates that the device has been returned to service and is operating normally (subscriber registered).

• Building from source

For Win32 platform Visual Studio 2017 project file is included. Use only Release configuration. x64 is not supported yet.

Requirements: - CSTA Inside Core - Multi-purpose C++ CSTA-XML library download from: http://cstainside.sourceforge.net/ place to: <root>\CSTAInsideCore (project file expects ..\CSTAInsideCore directory) - FreeSWITCH download from: https://files.freeswitch.org/freeswitch-releases/ Set the environmental variable FREESWITCH_SRC_LOCATION to the freeswitch build directory (Hint: after compiling FREESWITCH_SRC_LOCATION\Win32 or FREESWITCH_SRC_LOCATION\x64 should exist)

Both must be build before building mod_csta_socket

1. Usage

mod_csta_socket.dll is placed to <root>\3rdparty\freeswitch-src\win32\Release\mod directory. To load use load mod_csta_socket FreeSWITCH command or set automatic load in modules.conf.xml

1. Configuration

module reads configuration data from csta_socket.conf.xml file under <freeswitch>\conf\autoload_configs directory.

Example: <configuration name="csta_socket.conf" description="CSTA Interface"> <settings>
<param name="listen-ip" value="127.0.0.1"/> <param name="xml-listen-port" value="3000"/>
<param name="apply-inbound-acl" value="csta"/> <param name="system-status-timer" value="30"/> <param name="minimum-dump-interval" value="-1"/> <param name="loopback-originate-params" value="ignore_early_media=true,loopback_initial_codec=PCMA"/> <param name="use-multi-threading" value="0"/> <param name="use-uacsta" value="0"/> <param name="uacsta-after-monitor" value="0"/> </settings> </configuration>

listen-ip: the IP address of interface to listen on. 0.0.0.0 specifies to listen on all interfaces. default: 127.0.0.1 xml-listen-port: the listening port for CSTA-XML over TCP without SOAP interface. default: none (no listening for this type) apply-inbound-acl: the name of ACL entry configured in acl.conf to filter inbound connections. default: empty (no ACL applied) system-status-timer: specifies a timer value in seconds indicating how often the switching function sends periodic system status requests to the computing function (i.e. heartbeats). default: 0 means that the switching function does not send periodic System Status service requests. minimum-dump-interval: specifies minimum interval time between dumping call/device maps on Request System Status Request messages to reduce logging overhead. default: -1, dumping to logs is disabled. loopback-originate-params: list of FreeSWITCH channel variables used when call originated with loopback interface This is takes in effect when Make Call Request invoked with non dialable type of calling device or Make Predictive Call invoked with called device specified as dialing string use-multi-threading: enables parallel processing of CSTA requests (0/1, default: 0). use-uacsta: if enabled, module uses uaCSTA via mod_uacsta to control compatible phones (0/1, default: 0). uaCSTA support should also be configured for FreeSWITCH user in /conf/directory/... uacsta-after-monitor: if set to 1, uacsta will be activated only on monitored devices. If set to 0, uacsta session will be established for all configured devices immediatelly after register (0/1, default: 0). check-device-state-in-db: if set to 1, module checks device registation state in FreeSWITCH database to set operational state, othervise device state will be set only at register (0/1, default: 1).

Copyright (C) 2009-2024, Szentesi Krisztian sz.krisz@freemail.hu