NAME

Net::CSTAv3::Client - Perl implementation of the CSTA Phase 3 protocol as used by siemens clients

SYNOPSIS

A simple example how this module can be used:

        use Data::Dumper;       
        use Net::CSTAv3::Client;
        
        my $csta_client;
        my $cross_ref;
        
        $csta_client = Net::CSTAv3::Client->new();

        sub my_cleared_cb {
                print "CONNECTION CLEARED CALLBACK\n\n";
                print Dumper(@_);
                print "Lets close the connection now\n";
                $csta_client->csta_destroy_monitoring({'cross-ref-identifier'=>$cross_ref});
                $csta_client->csta_disconnect();
                exit(0);
        }
        
        $csta_client->csta_connect({'host'=>'siemens-pbx', 'port'=>18000});
        $cross_ref = $csta_client->csta_setup_monitoring({'dialing-number'=>'100', 'cleared_cb'=>\&my_cleared_cb});
        $csta_client->main_loop();

In this example we create a CSTA client instance and connect it to the host 'siemens-pbx' which accepts connections on port 18000. After that we instruct the PBX to monitor the (local) device which is reachable through the number '100'. In case of a connection cleared event (which is triggered when a call is torn down, for example because the caller or callee is hanging up) the function 'my_cleared_cb' is executed. It will get a reference to a hash as it's first argument. This hash contains more information about the connection cleared event because of which this function was called. After that we stop the monitoring and disconnect from the PBX.

DESCRIPTION

This module implements (a part of) the Computer Supported Telecommunications Applications (CSTA) protocol. It enables you to write perl programs which can communicate with your Private Branch eXchange device (PBX) to, for example, monitor calls to and from your own network.

Even though the CSTA protocol is defined in ECMA standards, vendors seem to implement customized versions of it. This module was developed for a Siemens HiPath PBX, most of the specification was obtained from the documentation of the "Siemens HiPath OpenOffice" unit - available at http://wiki.siemens-enterprise.com/index.php/HiPath_OpenOffice_ME_Offene_Schnittstellen.

For now this module only implements a small subset of the functionality offered by CSTA / Siemens' CSTA implementation - expect it to grow in future versions. :-)

EXPORT

None by default.

METHODS

$csta_client = Net::CSTAv3::Client->new()

Create a new Net::CSTAv3::Client instance $csta_client.

$csta_client->csta_connect({'host'=>'siemens-pbx', 'port'=>18000})

Connect the client to a PBX. This function takes a reference to a hash with parameters. The recognized hash keys are:

• host: The hostname or IP address of the PBX.

• port: The port number on which the PBX is accepting connections.

• authname: Authentication name to use when connecting to the PBX. Defaults to AMHOST".

• password: Password to use when connecting to the PBX. Defaults to 77777.

$cross_ref = $csta_client->csta_setup_monitoring({'dialing-number'=>'100'});

Start monitoring a device inside your network. This function takes a reference to a hash with parameters. The recognized hash keys are documented below. Monitoring a device means that the PBX will sent a notification to this client if the monitored device is involved in an event that is monitored. CSTA supports a wide range of events that can be monitored, but this module (up to now) only supports the following events:

• The connection cleared event, that occurs if an existing connection to/from the monitored device is torn down, for example because the peer is going on-hook.

• The delivered event, which occurs if a device receives an incoming call.

• The established event, which occurs if a call to/from a device is established.

• The transferred event, which occurs if a monitored device is involved in a transferred call. A transferred call is a call from device E that is received by device A, after that A calls another device B and after the connection between A and B is establised A can transfer it's call with E to device B.

For more information about these events please refer to the CSTA specification.

• dialing-number: Local dialing number of the device that should be monitored.

• delivered_cb: A reference to a function that will be executed in case a delivered event on the monitored device is observed. If this parameter is undefined all delivered-events from this device will be ignored.

• cleared_cb: A reference to a function that will be executed in case a connection-cleared-event on the monitored device is observed. If this parameter is undefined all connection-cleared-events from this device will be ignored.

• established_cb: A reference to a function that will be executed in case a established-event on the monitored device is observed. If this parameter is undefined all established-events from this device will be ignored.

• transferred_cb: A reference to a function that will be executed in case a transferred-event on the monitored device is observed. If this parameter is undefined all transferred-events from this device will be ignored.

The callback functions will receive a reference to a hash with event parameters. In case of a delivered-event the most interesting parameters / hash keys are:

alerting-device: The dialing number of the device which is ringing

calling-device: The dialing number of the calling device

called-device: The dialing number of the called device

cross-ref-identifier: The cross reference identifier for the monitor instance. This is the same identifier which was returned by the csta_setup_monitoring function for the device that caused this event

In case of a delivered-event the most interesting parameters / hash keys are:

releasing-device: The dialing number of the device that closed the connection

dialing-number: The dialing number of the device that generated this event

cross-ref-identifier: The cross reference identifier for the monitor instance. This is the same identifier which was returned by the csta_setup_monitoring function for the device that caused this event

In case of a delivered-event the most interesting parameters / hash keys are:

answering-device: The dialing number of the device that answered the call

calling-device: The dialing number of the device which initiated the call

called-device: The dialing number of the device which was called by calling-device

cross-ref-identifier: The cross reference identifier for the monitor instance. This is the same identifier which was returned by the csta_setup_monitoring function for the device that caused this event

In case of a delivered-event the most interesting parameters / hash keys are:

transferring-device: The dialing number of the device that is responsible for the call transfer

transferred-to-device: The dialing number of the device which became the new internal endpoint for the transferred call

endpoint: The dialing number of the device which initially called

cross-ref-identifier: The cross reference identifier for the monitor instance. This is the same identifier which was returned by the csta_setup_monitoring function for the device that caused this event

Note that you have to call the main_loop() function to receive incoming events as soon as possible.

$csta_client->csta_destroy_monitoring({'cross-ref-identifier'=>$cross_ref})

Disable monitoring for the given cross-ref-identifier. These identifiers are returned for each call of csta_setup_monitoring().

$csta_client->main_loop()

This is the "event loop" that indefinitely waits for incoming events. Call this function after you set up all your monitorings. Note that this function can only be left through callbacks invoked by incoming events.

$csta_client->debug_on()

If debugging is turned on this module emits *a lot* of debugging information on STDOUT. All debugging information printed by this module is prefixed with "[DEBUG] ". By default debugging is turned off.

$csta_client->debug_off()

Turn of debugging infos. Note that debugging is turned off by default anyway, this function is only usefull after you turned it on via the debug_on() function.

BUGS

This module only implements a small subset of the CSTA protocol so far

It was developed for a Siemens HiPath PBX. It might not work with other PBXs. I tried to isolate the Siemens specific stuff in Net::CSTAv3::Client::HiPath.pm, so support for other devices can be added later.

I am not fully satisfied with the event handling as it is now (users have to call the 'black hole function' main-loop() manually), so the interface might change in later versions.

Error handling and logging are poorly implemented in this module as of now.

SEE ALSO

The CSTA protocol is defined by ECMA International, see: http://www.ecma-international.org/activities/Communications/TG11/cstaIII.htm

Documentation on Siemens CSTA implementation for their HiPath PBXs can be found at http://wiki.siemens-enterprise.com/index.php/HiPath_OpenOffice_ME_Offene_Schnittstellen

Siemens offers two usefull programs to test/develop CSTA applications, CSTASwitchSimulator and CSTABrowser.

AUTHOR

Timo Schneider, <timos@informatik.tu-chemnitz.de>

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Timo Schneider

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.

cpanm Net::CSTAv3::Client

perl -MCPAN -e shell
install Net::CSTAv3::Client