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 4.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 or UA device and receive the responses that the PBX or UA sends back. The collection consists of DLLs, two clients (one in C# and one in VB) along with their source code that show how the DLLs can be used, several additional samples, and documentation. The DLLs contain the following: (1) classes generated by ASN1C from the ACSE and CSTA ASN.1 specifications, (2) classes generated by XBinder from the session management (ECMA-354) and CSTA XML schema specifications, and (3) 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:
- Support for the Unify OpenScape 4000
CSTADLL can now be used to do BER communication with the Unify OpenScape 4000 PBX device.
- Much More Robust CSTA XML Support
The previous release of CSTADLL had support for CSTA XML Editon 3. This release of CSTADLL has support for CSTA XML Editions 3, 4, 5, and 6.
- Multiple Small DLLs Instead of One Large DLL
The previous releases of CSTADLL had all of the functionality in one large DLL. This release of CSTADLL has the functionality divided up into multiple smaller DLLs.
For most current CSTADLL v2.2 customers the memory footprint for CSTADLL v2.3 should be anywhere from one half to one twentieth of the memory footprint for CSTADLL v2.2.
- Different Licensing Model
This release of CSTADLL can use licenses based on the Reprise License Manager (RLM) third party product. These licenses allow use of a floating license model.
- Support for uaCSTA
This release of CSTADLL supports uaCSTA, as defined in the ECMA TR/87 document. This feature has had limited testing, so we would be interested in partnering with someone to test it further.
- New Device Information Helper Methods
This release of CSTADLL has helper methods in the phase 3 classes that correspond to the Get Logical Device Information message and the Get Physical Device Information message.
- Clearer Definition of Callback Invocation Mechanisms
In previous releases of CSTADLL the PBXSession class had a boolean DebugClientCallback property. In this release that property has been replaced with a CallbackInvocationMechanism property whose value is an enum.
- CDR Support
This release of CSTADLL adds support for CSTA Phase 3 CDR (Call Detail Records) messages. This support is achieved via the new helper methods StartCDRTransmission(), SendStoredCDR(), and StopCDRTransmission(). There are also callback method properties in the PBXSession class named CDRCallback and XMLCDRCallback.
- Configurable Log File Size
In previous releases of CSTADLL the maximum size of the log file (i.e., the size the log file could grow to before a switch to a new log file was made) was fixed at 5 Mb. In this release of CSTADLL the size is configurable via the MaxLogFileSize property in the PBXSessionHelper class. The default is still 5 Mb.
- RequestSystemStatus Helper Method
In this release of CSTADLL the phase 3 classes have a RequestSystemStatus() method. This method makes implicit association with a PBX or UA easier. Implicit association is supported by some phase 3 devices.
- New DivertCall() Signature
A new phase 1 DivertCall() signature that accepts a ConnectionID as an argument has been added.
- New QueryDevice() Signature
A new phase 1 QueryDevice() signature that accepts a QueryDeviceFeature as an argument has been added.
- New Connected Property
A new boolean read-only property named Connected has been exposed via the PBXSession object. The value of this property is true if there is an active connection to the PBX and false otherwise.
- New Monitor Signatures
For BER phase 3 a new MonitorStart() method and a new MonitorStopAtNumericDevice() method that accept a longword device number have been added.
In this release of CSTADLL the Com.Objsys.Csta.Common namespace no longer exists. Instead all classes exposed by each DLL are in the namespace that corresponds to that DLL. So, for example, all classes exposed by the CSTABERPhase3 DLL are in the namespace Com.Objsys.Csta.Phase3. Hence any code that references classes in Com.Objsys.Csta.Common will need to be changed to reference the classes in the appropriate DLL namespace.
If existing customer code uses classes from two or more phases in the same source file, there may be name collisions for classes that used to be defined in Com.Objsys.Csta.Common. These collisions can be resolved by either prefacing the class name with the correct namespace (i.e., fully qualifying the class name) or by specifying a "using" directive to alias a unique class name to the right class; e.g., "using PBXSessionP3 = Com. Objsys.Csta.Phase3.PBXSession;". Some of the samples in the kit have the text MultiPBX in the sample name. These samples illustrate how classes from multiple phases can be used.
In previous releases of CSTADLL all of the functionality was in one large DLL named CSTAAllPhases.DLL. In this release of CSTADLL the functionality has been split into multiple smaller DLLs. Existing customer code that builds against CSTAAllPhases.DLL will need to be changed to build against the appropriate smaller DLL(s).
This release of CSTADLL can use licensing based on the third party product Reprise License Manager (RLM). If a customer license file has an extension of .lic, then the license is an RLM-based license. For licensed (i.e., not unlimited) CSTADLL kits that have an RLM-based .lic file, the license file itself needs to be placed either into the same folder where a .exe that uses CSTADLL sits or into a folder pointed to by the environment variable RLM_LICENSE.
Use of an osyslic.txt file is still supported, and the procedures to locate such a file are still the same as before (in a folder pointed to by the environment variable OSLICDIR, in the same folder as the .exe that uses CSTADLL, or in a folder included in the PATH environment variable).
Regardless of what licensing model is used, the files Reprise.dll and rlm1212.dll must be located in the same folder as the .exe that uses CSTADLL. Both of these DLL files are included in the CSTADLL kit. The file rlm1212.dll is a 32-bit native DLL, not a .Net DLL, so Visual Studio won't pull this DLL in automatically.
Customer code that uses a licensed CSTADLL kit must now target the x86 platform to ensure proper interfacing with the rlm1212.dll. In cases where customer code is built with a Makefile, the /target:x86 qualifier must be added to the csc or vbc command. In cases where customer code is built with a Visual Studio project, the platform that the project targets must be x86 as opposed to AnyCPU.
There is also a 64-bit version of rlm1212.dll available for customers who prefer to target the x64 platform.
Use of this release of CSTADLL on non-Windows platforms with Mono requires either an unlimited CSTADLL kit (i.e., a kit with no license checking) or a kit built specifically to use only the older osyslic.txt license files.
Previous releases of CSTADLL had a property named DebugClientCallback in the PBXSession class. This release of CSTADLL replaces this property with one named CallbackInvocationMechanism. The value for this property is an enum defined as CallbackInvocationMechanisms in the Constants class. Any existing code that references the DebugClientCallback property of the PBXSession class will need to be changed to reference one of these enum values.
In previous releases of CSTADLL the Constants.CommunicationTypes enum held symbolic names for the different PBX models that CSTADLL supported. In v2.3 this enum has a much smaller set of symbolic names that describe how messages are exchanged with a PBX or UA. A new enum named Constants.PBModels holds symbolic names for the different PBX models.
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 (1) all of the ACSE and CSTA classes generated by ASN1C from the ACSE and CSTA ASN.1 specifications, and (2) all of the session management (ECMA-354) and CSTA classes generated by XBinder from the session management and CSTA XML schema specfications.
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. If you are evaluating CSTADLL, a file with an extension of .lic (e.g., evallic.lic) 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. If you have purchased CSTADLL, either a .lic file (e.g., cstadll.lic) or an osyslic.txt file is available on your account page on our web site.
- If your license file is a .lic file, the 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 the same directory that an executable that uses CSTADLL is located in. This would include the console_csharp_client directory in the kit and the gui_vb_client directory in the kit. Or
- b. The file can be copied to a directory that is pointed to by an environment variable named RLM_LICENSE.
The software should now be operational.
- If your license file is an osyslic.txt file, the 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\CSTA*.dll
These files are the Microsoft .NET DLLs that contain generated object definitions for the ACSE, session management (ECMA-354), and CSTA objects as well as additional helper objects. Some of these DLL files are also present in the two client folders and the top-level samples folder. The DLLs are built with Visual Studio 2013.
The specific DLLs and what they contain are as follows:
- CSTABERPhase1.dll - provides functionality for exchanging BER-encoded CSTA phase 1 and ACSE messages with a PBX.
- CSTABERPhase2.dll - provides functionality for exchanging BER-encoded CSTA phase 2 and ACSE messages with a PBX.
- CSTABERPhase3.dll - provides functionality for exchanging BER-encoded CSTA phase 3 and ACSE messages with a PBX.
- CSTAXMLEd3.dll - provides functionality for exchanging XML-encoded CSTA phase 3 XML edition 3 and ECMA-354 session management messages with a PBX or UA.
- CSTAXMLEd4.dll - provides functionality for exchanging XML-encoded CSTA phase 3 XML edition 4 and ECMA-354 session management messages with a PBX or UA.
- CSTAXMLEd5.dll - provides functionality for exchanging XML-encoded CSTA phase 3 XML edition 5 and ECMA-354 session management messages with a PBX or UA.
- CSTAXMLEd6.dll - provides functionality for exchanging XML-encoded CSTA phase 3 XML edition 6 and ECMA-354 session management messages with a PBX or UA.
- <installdir>\dll\asn1rt.dll
This file is the ASN1C C# run-time DLL. The ASN1C C# run-time is used by the CSTA BER DLLs to do BER 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 2013.
- <installdir>\dll\xbrt.dll
This file is the XBinder C# run-time DLL. The XBinder C# run-time is used by the CSTA XML DLLs to do XML 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 2013.
- <installdir>\dll\Reprise.dll
This file is the .Net DLL for the Reprise License Manager (RLM), which is used by CSTADLL for license management. This DLL will not be present in unlimited CSTADLL kits.
- <installdir>\dll\rlm1212.dll
This file is the native DLL for the Reprise License Manager (RLM), which is used by CSTADLL for license management. This DLL will not be present in unlimited CSTADLL kits.
Since this DLL is a native DLL as opposed to a .Net DLL, it will not be copied automatically by Visual Studio. This DLL must sit in the same directory where a .exe that uses CSTADLL sits.
- <installdir>\doc\<dll name>\HTML
These folders contain HTML documentation that describes the helper classes contained within the specified DLL. This documentation does not describe the generated classes. Refer to the ASN1C C# Compiler User Manual for documentation about classes generated by ASN1C. Refer to the XBinder Java/C# User Manual for documentation about classes generated by XBinder.
- <installdir>\doc\<dll name>\pdf
These folders contain PDF files that describe the helper classes contained within the specified DLL. This documentation does not describe the generated classes. Refer to the ASN1C C# Compiler User Manual for documentation about classes generated by ASN1C. Refer to the XBinder Java/C# User Manual for documentation about classes generated by XBinder.
Sample Clients
- <installdir>\console_csharp_client\CSTAAllPhasesConsole.exe
This file is the executable image for a console-mode sample client that uses the DLLs and is written in C#. This image as provided initially in the kit is built with Visual Studio 2013.
- <installdir>\console_csharp_client\*.cs
The .cs files in this directory are the source files for the C# console- mode client.
- <installdir>\console_csharp_client\CSTAAllPhasesConsole.csproj
This file is a Visual Studio 2013 C# project file that will allow you to work with the source code for the C# console-mode client from within Visual Studio (2013 or higher).
- <installdir>\gui_vb_client\CSTAAllPhasesClient.exe
This file is the executable image for a GUI sample client that uses the DLLs and is written in Visual BASIC. This image as provided initially in the kit is built with Visual Studio 2013.
- <installdir>\gui_vb_client\*.vb
- <installdir>\gui_vb_client\My Project\*.vb
The .vb files in these directories are the source files for the Visual BASIC GUI client.
- <installdir>\gui_vb_client\CSTAAllPhasesClient.vbproj
This file is a Visual Studio 2013 Visual BASIC project file that will allow you to work with the source code for the Visual BASIC GUI client from within Visual Studio (2013 or higher).
Call Management Application
- <installdir>\CallMan\CallMan.exe
This file is the executable image for a call management application that uses CSTABERPhase3.DLL and is written in Visual BASIC. This image as provided initially in the kit is built with Visual Studio 2013.
- <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 2013 Visual BASIC project file that will allow you to work with the source code for the call management application from within Visual Studio (2013 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\BER
This folder contains samples written in C# that show how CSTADLL can be used for various tasks related to using a PBX device that communicates with BER CSTA.
- <installdir>\samples\csharp\XML
This folder contains samples written in C# that show how CSTADLL can be used for various tasks related to using a PBX device that communicates with XML CSTA.
- <installdir>\samples\csharp\BERAndXML
This folder contains a sample written in C# that shows how CSTADLL can be used to work with two different PBX devices, one that uses BER CSTA and one that uses XML CSTA.
- <installdir>\samples\VB\BER
This folder contains samples written in Visual BASIC that show how CSTADLL can be used for various tasks related to using a PBX device that communicates with BER CSTA.
- <installdir>\samples\VB\XML
This folder contains samples written in Visual BASIC that show how CSTADLL can be used for various tasks related to using a PBX device that communicates with XML CSTA.
- <installdir>\samples\VB\BERAndXML
This folder contains a sample written in Visual BASIC that shows how CSTADLL can be used to work with two different PBX devices, one that uses BER CSTA and one that uses XML CSTA.
Specifications and Generated Files
- <installdir>\specs
This folder contains various sub-folders that contain (1) the ACSE and CSTA ASN.1 specifications that were used to generate the relevant objects contained within the DLLs, and (2) the session management (ECMA-354) and CSTA XML schema specifications that were used to generate the relevant objects contained within the DLLs.
- <installdir>\phase1generated
- <installdir>\phase2generated
- <installdir>\phase3generated
These folders contain the generated C# source files that define the objects contained within the DLLs that correspond to ACSE and CSTA ASN.1 definitions. These files were generated using ASN1C from the ASN.1 files contained in the <installdir>\specs folder.
- <installdir>\xmled3generated
- <installdir>\xmled4generated
- <installdir>\xmled5generated
- <installdir>\xmled6generated
This folder contains the generated C# source files that define the objects contained within the DLLs that correspond to session management (ECMA-354) and CSTA XML schema definitions. These files were generated using XBinder from the XML schema 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 CSTADLL can be used. The DLLs should be consumable by any Microsoft .NET programming language. These would include C#, Visual BASIC, and C++/CLI.
CSTADLL 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 CSTADLL. The location of the log file is the folder where the executable image resides. The default behavior is that 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. That default size of 5 Mb can be modified by using the MaxLogFileSize property of the PBXSessionHelper class.
The CSTADLL kit contains a collection of DLLs. Each DLL exposes a namespace named Com.Objsys.Csta.Devices that contains classes for working with specific PBX devices. Each DLL also exposes a namespace of the form Com.Objsys.Csta.Phase<n> or Com.Objsys.Csta.Xmled<n>. These namespaces contain additional classes useful for doing CSTA work using the indicated BER phase or XML edition, including classes generated from relevant ASN.1 or XSD specifications using the Objective Systems ASN1C or XBinder products.
The table below lists the classes for working with specific PBX devices, what DLL defines them (in the Com.Objsys.Csta.Devices namespace), and what namespace besides Com.Objsys.Csta.Devices you would need to use in order to work with that PBX device.
Class DLL Needed Namespace Alcatel4400 CSTABERPhase2 Com.Objsys.Csta.Phase2 AlcatelOXE CSTABERPhase2 Com.Objsys.Csta.Phase2 AlcatelOXO CSTABERPhase1 Com.Objsys.Csta.Phase1 PanasonicKXTDA CSTABERPhase3 Com.Objsys.Csta.Phase3 PanasonicKXTDE CSTABERPhase3 Com.Objsys.Csta.Phase3 PanasonicNCP CSTABERPhase3 Com.Objsys.Csta.Phase3 PhilipsSopho CSTABERPhase1 Com.Objsys.Csta.Phase1 SiemensCAP CSTABERPhase3 Com.Objsys.Csta.Phase3 SiemensHicom300 CSTABERPhase1 Com.Objsys.Csta.Phase1 SiemensHipath3000p2 CSTABERPhase2 Com.Objsys.Csta.Phase2 SiemensHipath3000p3 CSTABERPhase3 Com.Objsys.Csta.Phase3 SiemensHipath4000 CSTABERPhase3 Com.Objsys.Csta.Phase3 SiemensRealitix CSTABERPhase1 Com.Objsys.Csta.Phase1 TadiranCoral CSTABERPhase1 Com.Objsys.Csta.Phase1 SiemensHicom300 CSTABERPhase1 Com.Objsys.Csta.Phase1 UnifyOpenscape4000BER CSTABERPhase3 Com.Objsys.Csta.Phase3 UnifyOpenscapeVoice CSTAXMLEd4 Com.Objsys.Csta.Xmled4 UnifyOpenscapeX5 CSTABERPhase3 Com.Objsys.Csta.Phase3 VodiaSNOMOne CSTAXMLEd3 Com.Objsys.Csta.Xmled3 In some cases you may need to talk to more than one PBX. There are samples in the CSTADLL kit that provide guidance for doing this. The relevant samples have "MultiPBX" in the name.
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.