This file contains introductory information about the CSTADLL software and release notes about the current release.
Thank you for your interest in this release of the CSTADLL software. CSTADLL is a collection of software that allows a developer using the Microsoft .NET platform (version 3.5 or higher) to work with CSTA messages in any of the three phases. The CSTADLL software allows you to send CSTA messages to a PBX device and receive the responses that the PBX sends back. The collection consists of a DLL, two clients (one in C# and one in VB) along with their source code that show how the DLL can be used, several additional samples, and documentation. The DLL contains all of the classes generated by ASN1C from the ACSE and CSTA ASN.1 specifications plus several additional classes that act as helper classes in working with CSTA messages. Also included in the kit is a small office call management application named CallMan, along with its source code. This application can be used as is or modified as needed.
This release of CSTADLL adds the following new capabilities:
- Use on Linux
The basic DLL functionality of CSTADLL v2.1 has been tested on Linux with the Mono tool. The version of Mono was 2.10.8.1. Version 4.0.0.0 of the System.Windows.Forms namespace is also needed. For Ubuntu Linux the name of the Mono package that contains this version of System.Windows.Forms is libmono-system-windows-forms4.0-cil, but Mono package names are not consistent across different flavors of Linux.
- Call Management Application
A small office call management application named CallMan is now included with the CSTADLL kit. This application can be used out of the box or can be modified as needed (the source code is included).
- Multiple PBX Sessions Now Supported
CSTADLL v2.1 supports sessions to more than one PBX. Previously only one PBX session was supported.
- Visual Studio 2010 DLL Version
The DLL provided in the dll folder of the kit is now built with Visual Studio 2010. Previously this DLL was built with Visual Studio 2008. A version of the DLL built with Visual Studio 2008 is provided in the dll_vs2008 folder. The use of Visual Studio 2010 as the main build tool makes this version of CSTADLL consistent with most of Objective Systems' other Windows products.
The Visual Studio projects for the sample VB client, the sample C# client, and the samples that are in the samples folder hierarchy are also now Visual Studio 2010 projects. Similarly, the Visual Studio project for the new CallMan application is a Visual Studio 2010 project.
- New AlcatelOXE Class
A new AlcatelOXE class is provided for working with the Alcatel OXE PBX device.
- New GetDeviceData() Method for Panasonic
The classes that work with Panasonic PBXes now have a GetDeviceData() method that retrieves information about a specified device.
- New RetrieveCall() Method for All Three Phases
A RetrieveCall() method to retrieve a held call is now available for all three phases.
- New DoNotDisturb Methods
There are now SetDoNotDisturb() and ClearDoNotDisturb() methods available for all three phases. In addition phase 3 also now has a GetDoNotDisturb() method.
- New MessageWaiting Methods
There are now SetMessageWaiting() and ClearMessageWaiting() methods available for phases 1 and 2. Phase 3 already had these methods.
- AlcatelOXO Now a Phase 1 Class
The AlcatelOXO class is now (correctly) a phase 1 class. The AlcatelOXOp1 class that was in previous versions has been removed.
- Clear Button in Sample GUI Client
The sample GUI client that's provided with CSTADLL now has a Clear button to clear the contents of the asynchronous message window.
- New DebugClientCallback Property
The PBXSession class has a new DebugClientCallback property. If set to true, this property will enable easier debugging of client callback methods by delaying the read for the next message from the PBX until after the client callback method has finished. The default value is false, meaning the read for the next message from the PBX is posted before the client callback method is invoked.
- New MaxReceiveTimeout Property
The PBXSession class has a new MaxReceiveTimeout property. This property specifies in milliseconds the amount of time to wait for a response to arrive from the PBX. The default value is 5,000 milliseconds (5 seconds).
- New GetAgentState() Method
A new GetAgentState() method has been added for phase 3.
- New MakeACSEAssociation() Signature
A new MakeACSEAssociation() signature that accepts a user name and a password has been added to the SiemensHipath3000p3 and UnifyOpenscapeX5 classes.
- New SnapshotCall() Signature
A new SnapshotCall() signature has been added for phase 3.
- Support for the Philips Sopho
The Philips Sopho PBX device is now supported.
Prior versions of CSTADLL exposed an Init() method in the PBXSessionHelper class. Client applications would call this method and then create a worker object using an argument-less constructor.
In version 2.1 the Init() method is no longer available in the PBXSessionHelper class, and the worker classes no longer have argumentless constructors. Instead an instantiable PBXSession class is provided.
So where before a client application might have a sequence like this:
PBXSessionHelper.Init("10.0.0.75", 33333);
PanasonicNCP workerObject = new PanasonicNCP();Now the sequence will look like this:
PBXSession sessionObject = new PBXSession("10.0.0.75", 33333);
PanasonicNCP workerObject = new PanasonicNCP(sessionObject);Or like this:
PanasonicNCP workerObject = new PanasonicNCP("10.0.0.75", 33333);Prior versions of CSTADLL exposed a ClientCallback property in the PBXSessionHelper class for defining a monitor callback method. In version 2.1 this property is now exposed in the instantiable PBXSession class.
So where before a client application might have a line like this:
PBXSessionHelper.ClientCallback = ReceiveMonitorMessages;Now the line will look like this:
sessionObject.ClientCallback = ReceiveMonitorMessages;In prior versions of CSTADLL the monitor callback method took one argument: a byte array containing the bytes of the asynchronous message received from the PBX. In version 2.1 this method now takes two arguments: a PBXSession object indicating which PBX the message is from, and the byte array containing the message.
So where before a monitor callback method might have had a signature like this:
static void ReceiveMonitorMessages(byte[] receivedMessage);Now the line will look like this:
static void ReceiveMonitorMessages(PBXSession sessionObject, byte[] receivedMessage);Starting with CSTADLL v2.0.3 a ConnectionLostCallback property was exposed in the PBXSessionHelper class for handling lost PBX connections. In version 2.1 this property is now exposed in the instantiable PBXSession class.
So where before a client application might have a line like this:
PBXSessionHelper.ConnectionLostCallback = HandleLostConnection;Now the line will look like this:
sessionObject.ConnectionLostCallback = HandleLostConnection;In prior versions of CSTADLL the connection lost callback method took no arguments. In version 2.1 this method now takes one argument: a PBXSession object indicating the PBX whose connection was lost.
So where before a connection lost callback method might have had a signature like this:
static void HandleLostConnection();Now the line will look like this:
static void HandleLostConnection(PBXSession sessionObject);
The CSTADLL kit includes both HTML and PDF documentation that describes the classes that the kit contains. In addition to the classes described in the documentation, the kit also contains all of the ACSE and CSTA classes generated by ASN1C from the ACSE and CSTA ASN.1 specifications.
The steps to install CSTADLL on a Windows system are as follows:
- The software is packaged into a zip archive that can be expanded anywhere on your system. There is no dependency on any particular folder hierarchy.
- After installation is complete, the license file must be installed to allow the product to operate. This was sent in the osyslic.txt file that was attached to the E-mail message that was sent at the time the product was downloaded. If you did not receive a license file, please contact us.
- The osyslic.txt file must be copied to a location where the software can find it. This can be done in one of the following ways:
- a. The file can be copied to a directory that is pointed to by an environment variable named OSLICDIR, or
- b. The file can be copied into any of the directories specified within your PATH environment variable (copying to the c:\windows directory works on most systems), or
- c. The file can be copied to the same directory that an executable that uses the DLL is located in. This would include the csharpclient directory in the kit and the vbclient directory in the kit.
The software should now be operational.
The following subdirectories contain the following files (note: <installdir> refers to the installation directory that was specified during the installation process):Binaries and Documentation
- <installdir>\dll\CSTAAllPhases.dll
This file is the Microsoft .NET DLL that contains generated object definitions for the ACSE and CSTA objects as well as additional helper objects. This DLL file is also present in the two client folders and the top-level samples folder. The DLL is built with Visual Studio 2010.
- <installdir>\dll\asn1rt.dll
This file is the ASN1C C# runtime DLL. The ASN1C C# runtime is used by CSTAAllPhasesDLL.dll to do encoding and decoding operations. This DLL file is also present in the two client folders and the top-level samples folder. The DLL is built with Visual Studio 2010.
- <installdir>\dll_vs2008\CSTAAllPhases.dll
This file is the same as the DLL with the same name in the dll folder, except that the DLL in this folder is built with Visual Studio 2008.
- <installdir>\dll_vs2008\asn1rt.dll
This file is the same as the DLL with the same name in the dll folder, except that the DLL in this folder is built with Visual Studio 2008.
- <installdir>\doc\HTML
This folder contains HTML documentation that describes the helper classes contained within the all-phases DLL. This documentation does not describe the generated classes. Refer to the ASN1C C# Compiler User Manual for documentation about the generated classes.
- <installdir>\doc\pdf
This folder contains a PDF file that describes the helper classes contained within the all-phases DLL. This documentation does not describe the generated classes. Refer to the ASN1C C# Compiler User Manual for documentation about the generated classes.
Sample Clients
- <installdir>\csharpclient\CSTAAllPhasesConsole.exe
This file is the executable image for a console-mode sample client that uses the DLL and is written in C#. This image as provided initially in the kit is built with Visual Studio 2010.
- <installdir>\csharpclient\*.cs
The .cs files in this directory are the source files for the C# console- mode client.
- <installdir>\csharpclient\CSTAAllPhasesConsole.csproj
This file is a Visual Studio 2010 C# project file that will allow you to work with the source code for the C# console-mode client from within Visual Studio (2010 or higher).
- <installdir>\vbclient\CSTAAllPhasesClient.exe
This file is the executable image for a GUI sample client that uses the DLL and is written in Visual BASIC. This image as provided initially in the kit is built with Visual Studio 2010.
- <installdir>\vbclient\*.vb
- <installdir>\vbclient\My Project\*.vb
The .vb files in these directories are the source files for the Visual BASIC GUI client.
- <installdir>\vbclient\CSTAAllPhasesClient.vbproj
This file is a Visual Studio 2010 Visual BASIC project file that will allow you to work with the source code for the Visual BASIC GUI client from within Visual Studio (2010 or higher).
Call Management Application
- <installdir>\CallMan\CallMan.exe
This file is the executable image for a call management application that uses the DLL and is written in Visual BASIC. This image as provided initially in the kit is built with Visual Studio 2010.
- <installdir>\CallMan\*.vb
- <installdir>\CallMan\My Project\*.vb
The .vb files in these directories are the source files for the call management application.
- <installdir>\CallMan\CallMan.vbproj
This file is a Visual Studio 2010 Visual BASIC project file that will allow you to work with the source code for the call management application from within Visual Studio (2010 or higher).
- <installdir>\CallMan\phone.ico
This file is the icon file that's assigned to the CallMan executable image.
Other Samples
- <installdir>\samples\csharp\CSTACsButtonPress
This folder contains a C# sample that illustrates how the DLL can be used to work with a CSTA message for which the DLL doesn't expose any explicit helper methods.
- <installdir>\samples\csharp\DLLCs*
These folders contain C# samples that show how the DLL's exposed helper methods can be used for various operations.
Specifications and Generated Files
- <installdir>\specs
This folder contains the ACSE and CSTA ASN.1 specifications that were used to generate most of the objects contained within the DLL.
- <installdir>\phase1Generated
- <installdir>\phase2Generated
- <installdir>\phase3Generated
These folders contain the generated C# source files that define most of the objects contained within the DLL. These files were generated using ASN1C from the ASN.1 files contained in the <installdir>\specs folder.
If you're not familiar with CSTA in general, there is some helpful information at this location.You may first want to spend some time with with either the C# console-mode client program or the Visual BASIC GUI client program to familiarize yourself with the types of operations involved with CSTA. Note that these clients only do a small subset of the total number of CSTA operations.
To use one of the clients you will need the IP address (or well-known name) of the PBX device with which you wish to work and the port number that the PBX uses for CSTA communication.
If you wish to use the Visual BASIC GUI client, the README.txt file in that client's folder explains how.
Both clients have their source code included in the kit. You may also want to investigate some of the additional samples or the CallMan application to get more ideas about how the all-phases DLL can be used. The DLL should be consumable by any Microsoft .NET programming language. These would include C#, Visual BASIC, and C++/CLI.
The all-phases DLL can log message traffic between a client program and the PBX device if so desired. The logging is controlled by the LoggingEnabled property within the PBXSessionHelper class. The logging is off by default. Both of the provided sample clients enable the logging. The log file used is named cstadll_<program>.log, where <program> is the name of the executable image that is using the DLL. The location of the log file is the folder where the executable image resides. If the log file grows to more than 5 Mb, it is copied to cstadll_<program>.backup.log, and a new log file is opened. If there is already a file with the backup file name, it is overwritten.
Report problems you encounter by sending E-mail to support@obj-sys.com. Please provide sample code and indicate where in the code the problem occurs.
If you have any further questions or comments on what you would like to see in the product or what is difficult to use or understand, please communicate them to us. Your feedback is important to us. Please let us know how it works out for you - either good or bad.