Timo Schneider > Net-CSTAv3-Client > Net::CSTAv3::Client

Download:
Net-CSTAv3-Client-0.06.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.06   Source  

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:

$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:

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

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.

syntax highlighting: