CSTADLL V2.0.4 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 2.0 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.

Release Notes

This release of CSTADLL adds the following new capabilities:
Support for Multi-threaded Applications

This version of CSTADLL fully supports multi-threaded client applications; i.e., client applications in which multiple threads exchange messages with the PBX. Previously, multi-threaded client applications had to synchronize their access to the PBX. With this release of CSTADLL, the synchronization is no longer necessary.

CSTA Phase 3 Edition 4 Definitions

The classes for the CSTA messages in this release are generated from the CSTA Phase 3 Edition 4 message definitions, which are the most recent definitions. Prior to this release the classes were generated from the CSTA Phase 3 Edition 2 message definitions.

Consistent Consultation Call and Transfer Call Mechanisms

In this release all three phases have a ConsultationCall() method that sends a Consultation Call message to the PBX.

Also in this release all three phases have a TransferCall() signature that requires a ConsultationCall() be done first and accepts two connection ids: one obtained from the ConsultationCall() and one from the original call (perhaps done with MakeCall()). This approach is more consistent with the descriptions of the Transfer Call message in the CSTA documentation from Ecma.

Also in this release the sample clients present a Consultation Call option in all three phases. The Transfer Call option in all three phases first sends a Consultation Call message and then a Transfer Call message.

Visual Studio 2008 DLL Version

The DLL provided in the dll folder of the kit is now built with Visual Studio 2008. Previously this DLL was built with Visual Studio 2005. A version of the DLL built with Visual Studio 2005 is provided in the dll_vs2005 folder. The use of Visual Studio 2008 as the main build tool makes this version of CSTADLL consistent with 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 2008 projects.

Renamed Main DLL

In this release the main DLL is named CSTAAllPhases.dll. In prior releases the DLL was named CSTAAllPhasesDLL.dll, which was a bit awkward.

Renamed Top-level Folder

The top-level folder in the distribution kits in this release is CSTADLLv. In prior releases the top-level folder was named CSTAAllPhasesDLLv.

Less Cluttered Output in Sample Clients

The VB and C# sample clients that are provided no longer display the individual bytes of messages that come in from the PBX. A byte by byte listing of the message contents can be seen by making use of the log file feature.

New Phase 1 and Phase 2 AnswerCall() Signature

New AnswerCall() signatures for phase 1 and phase 2 have been added. These new signatures accept a connection id (the connection id of the call to answer) and a device to use to answer the call. Phase 3 already has a similar signature.

Consistent Answer Call and Monitor Stop Operation in Sample Clients

The Answer Call functionality in the VB and C# sample clients now works against the most recently made call (made with the Make Call option) regardless of what phase is being used. Also, the Monitor Stop functionality now works against the most recently started monitor operation (started with the Monitor Start option) regardless of what phase is being used.

Consistent Transfer Call Operation in Sample Clients.

The sample clients now follow the same pattern for transferring calls regardless of what phase is being used: A Consultation Call message is sent first, and then a Transfer Call message.

New PDFStart() and PDFStop() Methods for Panasonic

The Panasonic classes now have PDFStart() and PDFStop() methods. The PDFStart() method sends the Panasonic-specific PDF (Physical Device Features) Start message to the PBX, and the PDFStop() method sends the Panasonic-specific PDF Stop message. These are convenience methods that do exactly the same things as the AcquireControlRight() and ReleaseControlRight() methods.

Revised Location for Proprietary Specifications

Vendor-specific ASN.1 specifications are now located in folders named "proprietary" within the CSTADLL kit folder hierarchy.

New SingleStepTransfer() Signature

A new signature for the phase 3 SingleStepTransfer() method has been added. This new signature accepts two arguments: a ConnectionID for the call to transfer, and a string specifying the device to which the call is to be transferred. The ConnectionID can be obtained from the response to the MakeCall() method or from an event report message.

Makefiles for Samples

The samples that are provided in the kit, including the VB and C# sample clients, now have Makefiles for building the sample code in addition to the Visual Studio project files.

New MonitorStop() Signature

A new MonitorStop() signature that takes a string device name has been added. This method will stop all monitors started with MonitorStart() against the indicated device, regardless of what thread started the monitor. Monitors started by mechanisms other than the MonitorStart() method will not be stopped by this method.

New ResetDisplay() Method for Panasonic

A new ResetDisplay() method has been added to the classes for Panasonic PBX devices. This method will reset a telephony device's display back to its default contents. The method can be used after a SetDisplay() call is done to display text.

New ClearConnection() Method

A new ClearConnection() method has been added for all three phases. Along with this change, the CSTACsClearConnection sample has been changed to a CSTACsButtonPress sample. The provided sample applications have been updated to offer options that use the new ClearConnection() method.

New SnapshotDevice() Method

A new SnapshotDevice() method has been added for all three phases. Along with this change, a new DLLCsPhase3SnapshotDevice sample has been added.

New GetGroupMembers() Method

A new GetGroupMembers() method has been added for Panasonic PBX devices. This method can be used, for example, to get the extensions associated with an incoming call distribution group device. A new sample named DLLCsPanasonicGetGroupMembers has been added to show how this method might be used.

New SendKmeMessage() Method

A new SendKmeMessage() method has been added for Panasonic PBX devices. This method can be used to send any KMESpecificPrivateData message to a Panasonic PBX.

New ConnectionLostCallback

A new ConnectionLostCallback property has been added to the PBXSessionHelper class. This callback works similarly to the ClientCallback property, except that the method designated by this property will be invoked if the connection to the PBX is lost. The method can then do whatever might be needed to re-establish communication with the PBX, such as re-invoke the MakeACSEAssociation() method.

New AnswerCall() Method

A new AnswerCall() method that takes just a ConnectionID as an argument has been added.

New UnifyOpenscapeX5 Class

A new UnifyOpenscapeX5 class has been added for the Unify Openscape Business X5 PBX device.

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 all of the ACSE and CSTA classes generated by ASN1C from the ACSE and CSTA ASN.1 specifications.

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

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

<installdir>\dll_vs2005\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 2005.

<installdir>\dll_vs2005\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 2005.

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

<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 2005 C# project file that will allow you to work with the source code for the C# console-mode client from within Visual Studio (2005 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 2008.

<installdir>\vbclient\*.vb

The .vb files in this directory are the source files for the Visual BASIC GUI client.

<installdir>\vbclient\CSTAAllPhasesClient.vbproj

This file is a Visual Studio 2005 Visual BASIC project file that will allow you to work with the source code for the Visual BASIC GUI client from within Visual Studio (2005 or higher).

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.

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