                              mod_csta_socket - CSTA interface for FreeSWITCH
                            
    
1. Capabilities
   
As a communication & encoding interface CSTA XML over TCP without SOAP is supported yet (ECMA-323 Annex J-2).
Module is based on CSTA Inside library.

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.

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

- 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
  
- Answer Call
  Answers a ringing call
  Supported Types: 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. 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.

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. 
  
                            
2. Building from source

For Win32 platform Visual Studio 2008 project file is included. Use only Release configuration. 

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: http://wiki.freeswitch.org/wiki/Installation_Guide#Download_Source_Tarball
  place to: <root>\3rdparty\freeswitch-snapshot

Both must be build before building mod_csta_socket

3. Usage

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

4. 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"/>
  </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 TCPinterface.
                    default: 3000
apply-inbound-acl:  the name of ACL entry configured in acl.conf to filter inbound connections.
                    default: empty (no ACL applied)


Copyright (C) 2009, Szentesi Krisztian <sz.krisz@freemail.hu>