CSTADLL V2.2.3 README

This file contains introductory information about the CSTADLL software and release notes about the current release.

Contents

Introduction

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 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 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.

Release Notes

This release of CSTADLL adds the following new capabilities:
XML CSTA Support

CSTADLL can now be used to communicate with PBX devices that use edition 3 (ed3) of XML CSTA messaging, as defined in ECMA-323. There is a new GenericXML class that corresponds functionally to the GenericCSTAp3 class. There are also two new device-specific classes: UnifyOpenscapeVoice and VodiaSNOMOne.

Easier Extensibility

It has always been possible to extend CSTADLL to support a specific PBX by overriding helper methods (e.g., MakeCall()). But in most cases the differences that need to be accommodated for an unfamiliar PBX lie in the format of specific messages.

This release of CSTADLL exposes numerous protected methods whose names start with "Encode". These methods can be overridden in a derived class for a new PBX. These "Encode" methods simply format the message, and this formatting is where much of the work to support an unfamiliar PBX lies.

The helper methods call these "Encode" methods; so if such a method is overridden in a derived class, the override method will be invoked. The mechanics of sending the message to the PBX and receiving the response stays encapsulated in the helper method.

Overriding a helper method is still possible, but unless such an override is absolutely necessary, overriding just the "Encode" method should be done instead. The NewPBX sample that's provided with CSTADLL illustrates how this overriding can be done.

Visual Studio 2013 DLL

The main DLL and the provided sample .exe files are built with Visual Studio 2013 in this release of CSTADLL.

New SiemensCap MakeACSEAssociation() Signatures

Three new MakeACSEAssociation() signatures have been added to the SiemensCap class so the caller can pass items such as a login name, a password, an application id, a native flag, and a CSTA version.

New MonitorStart() Signature

A new MonitorStart() signature that accepts a ConnectionID object instead of a device has been added for all three phases. This new signature enables monitoring a call.

Updated Panasonic-specific Definitions

The Panasonic-specific ASN.1 definitions have been updated from v6.5 to v8.0.

New SetAgentState() Methods

New SetAgentState() methods have been added for phase 3 and XML.

Exception Callback

A new ExceptionCallback property has been added to the PBXSession class. With this property it's possible to define a callback method that will be invoked if the asynchronous I/O handling code encounters an exception condition. If the callback is not defined, the asynchronous I/O handling code will throw an exception, which was always the behavior before.

Easier Unlimited Deployment

Prior to this release any customers who bought unlimited deployment rights still needed to deploy a special license file with the CSTADLL software that would unlock the software for unlimited use. With this release deploying that license file with unlimited distributions is no longer necessary.

New AlternateCall() Method

A new AlternateCall() method has been added for phase 3 that encodes and sends an Alternate Call message.

New ConferenceCall() Method

A new ConferenceCall() method has been added for phase 3 that encodes and sends a Conference Call message.

New GetLogicalDevInfo() and GetPhysicalDevInfo() Methods

These new methods have been added for BER phase 3. They encode and send Get Logical Device Information and Get Physical Device Information messages.

System Status Callback

The PBXSession class now has SystemStatusCallback and XMLSystemStatusCallback properties. These properties allow a callback method to be set that will be invoked if an asynchronous System Status message is received from the PBX. The client application should NOT send a System Status Response message, since that is done by CSTADLL itself.

Compatibility

Documentation

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.

Windows Installation

The steps to install CSTADLL on a Windows system are as follows:

  1. 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.
  2. After installation is complete, the license file must be installed to allow the product to operate. The name of the license file is osyslic.txt. If you are evaluating CSTADLL, an evaluation license 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, the license file is available on your account page on our web site.
  3. 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.

Contents of the Release

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, session management (ECMA-354), 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 2013.

<installdir>\dll\asn1rt.dll

This file is the ASN1C C# runtime DLL. The ASN1C C# runtime is used by CSTAAllPhases.dll 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 2010.

<installdir>\dll\xbrt.dll

This file is the XBinder C# runtime DLL. The XBinder C# runtime is used by CSTAAllPhases.dll 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 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 classes generated by ASN1C. Refer to the XBinder Java/C# User Manual for documentation about classes generated by XBinder.

<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 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 DLL 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 DLL 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 the 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 DLL, and (2) the session management (ECMA-354) and CSTA XML schema specifications that were used to generate the relevant objects contained within the DLL.

<installdir>\phase1generated
<installdir>\phase2generated
<installdir>\phase3generated

These folders contain the generated C# source files that define the objects contained within the DLL 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>\xmlgenerated

This folder contains the generated C# source files that define the objects contained within the DLL 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.

Getting Started

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.

Reporting Problems

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.