CSTADLL V2.4.0 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 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.

Release Notes

This release of CSTADLL adds the following new capabilities:
Support for Siemens Initial Heartbeat in CallMan

The CallMan application will now pause for one second after the MakeACSEAssociation() call to allow for the initial System Status exchange to complete in the background if the PBX is a Siemens PBX. Siemens PBX devices want this exchange to be completed before a client application sends the first CSTA message; otherwise, the PBX will drop the connection.

Conference Call Functionality

A conference call capability has been added to the CallMan application, and ConferenceCall() methods have been introduced to all relevant DLLs.

Easier Deployment for Non-RLM Installations

In prior releases the binary DLL rlm1212.dll needed to be present regardless of whether an RLM-based license (i.e., a license with a file type of .lic) was being used. In this release this DLL is only needed if the license is RLM-based.

Newer Version of Visual Studio

The prior release of CSTADLL was built with Visual Studio 2013. This release is built with Visual Studio 2019.

Improved Efficiency

Some BER methods have been made more efficient in this release by removing a redundant decode operation.

Better Looking HTML Documentation

The HTML documentation in this release has a more polished look than the previous HTML documentation.

Better Detection of Lost Connections

This release will detect lost PBX connections better than previous releases.

Better Interfacing with Alcatel 4400 PBX Devices

This release will respond to Alcatel-specific Escape messages that might be received after an ACSE association has been completed.

SetForwarding() and ClearForwarding() Methods

SetForwarding() and ClearForwarding() methods have been added to relevant DLLs.

ConsultationCall() Changes

The BER phase 3 ConsultationCall() method has been modified so it no longer specifies transferOnly. New ConsultationCall() signatures have been added that accept a ConsultOptions object.

Note that some Panasonic PBX devices return an error message if the default consult option of "unrestricted" is used. These devices support the "transferOnly" or "conferenceOnly" options, which can be set using a ConsultOptions object (e.g., ConsultOptions.transferOnly()).

Phase 2 SetAgentState()

A SetAgentState() method has been added for phase 2.

Updates to Phase 3 MakeCall() Method wrt autoOriginate Behavior

In previous releases the BER phase 3 MakeCall() method specified the "doNotPrompt" option for the autoOriginate member of the message for all phase 3 BER PBX devices except Panasonic.

In this release the BER phase 3 MakeCall() behavior has been brought more in line with the CSTA phase 3 specification. The default behavior is now to specify the "prompt" option for autoOriginate, which is consistent with the specification.

A new MakeCall() signature for phase 3 (BER and XML) has been added that allows the caller to specify either true or false for a new autoOriginate argument. If true is passed, then "doNotPrompt" is specified as the option for the autoOriginate member of the MakeCall message. If false is passed, then "prompt" is specified as the option for the autoOriginate member of the MakeCall message. Specifying the "prompt" option is also the behavior if the MakeCall() signature that doesn't take an autoOriginate argument is used.

Note that some Panasonic PBX devices do not respond to a MakeCall message if the message contains any value for the autoOriginate member. So for Panasonic PBX devices no autoOriginate member is included in the message, even if the new signature that accepts an autoOriginate argument is used.

Phase 3 AcceptCall()

AcceptCall() methods have been added for phase 3 (BER and XML).

BER MonitorStop() Methods

The BER MonitorStop() methods that accepted an integer cross reference id have been removed. The BER phase 3 MonitorStopAtNumericDevice() method has been renamed to MonitorStop(). For phase 2 and phase 1 MonitorStop() signatures that take a long device number as an argument have been added.

New HoldCall() Methods

HoldCall() methods have been added for phase 2 and phase 1.

Logging Improvement

For BER PBX devices if the PBX returns an error message, the decoded error message will now appear in the debug log file.

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. This was sent as a file named osyslic.txt 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 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 OSLICDIR. Or
    c. The file can be copied to any folder indicated by the PATH environment variable.

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

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\asn1rtcs.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 2017.

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

<installdir>\dll\Reprise.dll

This file is the .NET DLL for the Reprise License Manager (RLM), which is used by CSTADLL for license management in some cases. This DLL will not be present in CSTADLL kits that have license checking removed. This DLL is not used in situations where the license file is named osyslic.txt instead of a file with an extension of .lic.

<installdir>\dll\rlm1212.dll

This file is the native DLL for the Reprise License Manager (RLM), which is used by CSTADLL for license management in some cases. This DLL will not be present in CSTADLL kits that have license checking removed.

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. This DLL is not used, and copying it is not necessary, in situations where the license file is named osyslic.txt instead of a file with an extension of .lic.

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

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

<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 2019 Visual BASIC project file that will allow you to work with the source code for the Visual BASIC GUI client from within Visual Studio (2019 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 2019.

<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 2019 Visual BASIC project file that will allow you to work with the source code for the call management application from within Visual Studio (2019 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.

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.

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

ClassDLLNeeded Namespace
Alcatel4400CSTABERPhase2Com.Objsys.Csta.Phase2
AlcatelOXECSTABERPhase2Com.Objsys.Csta.Phase2
AlcatelOXOCSTABERPhase1Com.Objsys.Csta.Phase1
PanasonicKXTDACSTABERPhase3Com.Objsys.Csta.Phase3
PanasonicKXTDECSTABERPhase3Com.Objsys.Csta.Phase3
PanasonicNCPCSTABERPhase3Com.Objsys.Csta.Phase3
PhilipsSophoCSTABERPhase1Com.Objsys.Csta.Phase1
SiemensCAPCSTABERPhase3Com.Objsys.Csta.Phase3
SiemensHicom300CSTABERPhase1Com.Objsys.Csta.Phase1
SiemensHipath3000p2CSTABERPhase2Com.Objsys.Csta.Phase2
SiemensHipath3000p3CSTABERPhase3Com.Objsys.Csta.Phase3
SiemensHipath4000CSTABERPhase3Com.Objsys.Csta.Phase3
SiemensRealitisCSTABERPhase1Com.Objsys.Csta.Phase1
TadiranCoralCSTABERPhase1Com.Objsys.Csta.Phase1
SiemensHicom300CSTABERPhase1Com.Objsys.Csta.Phase1
UnifyOpenscape4000BERCSTABERPhase3Com.Objsys.Csta.Phase3
UnifyOpenscapeVoiceCSTAXMLEd4Com.Objsys.Csta.Xmled4
UnifyOpenscapeX5CSTABERPhase3Com.Objsys.Csta.Phase3
VodiaSNOMOneCSTAXMLEd3Com.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.

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.