Avaya Aura® Application Enablement Services

Device, Media and Call Control

.NET API Programmer’s Guide

Release 7.0.0
1 02-602658
Issue 1
© 2014 Avaya Inc. accessed by multiple users. “Software” means the computer programs
All Rights Reserved. in object code, originally licensed by Avaya and ultimately utilized by
Notices End User, whether as stand-alone products or pre-installed on
While reasonable efforts have been made to ensure that the Hardware. “Hardware” means the standard hardware originally sold by
information in this document is complete and accurate at the time of Avaya and ultimately utilized by End User.
printing, Avaya assumes no liability for any errors. Avaya reserves the License types
right to make changes and corrections to the information in this Designated System(s) License (DS). End User may install and use
document without the obligation to notify any person or organization of each copy of the Software on only one Designated Processor, unless
such changes. a different number of Designated Processors is indicated in the
Documentation disclaimer Documentation or other materials available to End User. Avaya may
Avaya shall not be responsible for any modifications, additions, or require the Designated Processor(s) to be identified by type, serial
deletions to the original published version of this documentation unless number, feature key, location or other specific designation, or to be
such modifications, additions, or deletions were performed by Avaya. provided by End User to Avaya through electronic means established
End User agree to indemnify and hold harmless Avaya, Avaya's agents, by Avaya specifically for this purpose.
servants and employees against all claims, lawsuits, demands and Concurrent User License (CU). End User may install and use the
judgments arising out of, or in connection with, subsequent Software on multiple Designated Processors or one or more Servers,
modifications, additions or deletions to this documentation, to the so long as only the licensed number of Units are accessing and using
extent made by End User. the Software at any given time. A “Unit” means the unit on which Avaya,
Link disclaimer at its sole discretion, bases the pricing of its licenses and can be,
Avaya is not responsible for the contents or reliability of any linked Web without limitation, an agent, port or user, an e-mail or voice mail account
sites referenced within this site or documentation(s) provided by Avaya. in the name of a person or corporate function (e.g., webmaster or
Avaya is not responsible for the accuracy of any information, statement helpdesk), or a directory entry in the administrative database utilized
or content provided on these sites and does not necessarily endorse by the Software that permits one user to interface with the Software.
the products, services, or information described or offered within them. Units may be linked to a specific, identified Server.
Avaya does not guarantee that these links will work all the time and has Database License (DL). End User may install and use each copy of the
no control over the availability of the linked pages. Software on one Server or on multiple Servers provided that each of
Warranty the Servers on which the Software is installed communicate with no
Avaya provides a limited warranty on this product. Refer to your sales more than a single instance of the same database.
agreement to establish the terms of the limited warranty. In addition, CPU License (CP). End User may install and use each copy of the
Avaya’s standard warranty language, as well as information regarding Software on a number of Servers up to the number indicated by Avaya
support for this product, while under warranty, is available to Avaya provided that the performance capacity of the Server(s) does not
customers and other parties through the Avaya Support Web site: exceed the performance capacity specified for the Software. End User
http://www.avaya.com/support. Please note that if you acquired the may not re-install or operate the Software on Server(s) with a larger
product from an authorized Avaya reseller outside of the United States performance capacity without Avaya's prior consent and payment of an
and Canada, the warranty is provided to you by said Avaya reseller and upgrade fee
not by Avaya. Named User License (NU). End User may: (i) install and use the
Licenses Software on a single Designated Processor or Server per authorized
THE SOFTWARE LICENSE TERMS AVAILABLE ON THE AVAYA Named User (defined below); or (ii) install and use the Software on a
WEBSITE, HTTP://SUPPORT.AVAYA.COM/LICENSEINFO/ ARE Server so long as only authorized Named Users access and use the
APPLICABLE TO ANYONE WHO DOWNLOADS, USES AND/OR Software. “Named User,” means a user or device that has been
INSTALLS AVAYA SOFTWARE, PURCHASED FROM AVAYA INC., expressly authorized by Avaya to access and use the Software. At
ANY AVAYA AFFILIATE, OR AN AUTHORIZED AVAYA RESELLER Avaya's sole discretion, a “Named User” may be, without limitation,
(AS APPLICABLE) UNDER A COMMERCIAL AGREEMENT WITH designated by name, corporate function (e.g., webmaster or helpdesk),
AVAYA OR AN AUTHORIZED AVAYA RESELLER. UNLESS an e-mail or voice mail account in the name of a person or corporate
OTHERWISE AGREED TO BY AVAYA IN WRITING, AVAYA DOES function, or a directory entry in the administrative database utilized by
NOT EXTEND THIS LICENSE IF THE SOFTWARE WAS OBTAINED the Software that permits one user to interface with the Software.
FROM ANYONE OTHER THAN AVAYA, AN AVAYA AFFILIATE OR Shrinkwrap License (SR). With respect to Software that contains
AN elements provided by third party suppliers, End User may install and
AVAYA AUTHORIZED RESELLER, AND AVAYA RESERVES THE use the Software in accordance with the terms and conditions of the
RIGHT TO TAKE LEGAL ACTION AGAINST YOU AND ANYONE applicable license agreements, such as “shrinkwrap” or “clickwrap”
ELSE USING OR SELLING THE SOFTWARE WITHOUT A LICENSE. license accompanying or applicable to the Software (“Shrinkwrap
BY INSTALLING, DOWNLOADING OR USING THE SOFTWARE, OR License”). The text of the Shrinkwrap License will be available from
AUTHORIZING OTHERS TO DO SO, YOU, ON BEHALF OF Avaya upon End User’s request (see “Third-party Components” for
YOURSELF AND THE ENTITY FOR WHOM YOU ARE INSTALLING, more information).
DOWNLOADING OR USING THE SOFTWARE (HEREINAFTER Copyright
REFERRED TO INTERCHANGEABLY AS “YOU” AND “END USER”), Except where expressly stated otherwise, no use should be made of
AGREE TO THESE TERMS AND CONDITIONS AND CREATE A materials on this site, the Documentation(s) and Product(s) provided
BINDING CONTRACT BETWEEN YOU AND AVAYA INC. OR THE by Avaya. All content on this site, the documentation(s) and the
APPLICABLE AVAYA AFFILIATE (“AVAYA”). product(s) provided by Avaya including the selection, arrangement and
Avaya grants End User a license within the scope of the license types design of the content is owned either by Avaya or its licensors and is
described below. The applicable number of licenses and units of protected by copyright and other intellectual property laws including the
capacity for which the license is granted will be one (1), unless a sui generis rights relating to the protection of databases. You may not
different number of licenses or units of capacity is specified in the modify, copy, reproduce, republish, upload, post, transmit or distribute
Documentation or other materials available to End User. “Designated in any way any content, in whole or in part, including any code and
Processor” means a single stand-alone computing device. “Server” software. Unauthorized reproduction, transmission, dissemination,
means a Designated Processor that hosts a software application to be storage, and or use without the express written consent of Avaya can
be a criminal, as well as a civil, offense under the applicable law.

Release 7.0.0
2 02-602658
Issue 1
Third-party components
Certain software programs or portions thereof included in the Product
may contain software distributed under third party agreements (“Third
Party Components”), which may contain terms that expand or limit
rights to use certain portions of the Product (“Third Party Terms”).
Information regarding distributed Linux OS source code (for those
Products that have distributed the Linux OS source code), and
identifying the copyright holders of the Third Party Components and the
Third Party Terms that apply to them is available on the Avaya Support
Web site: http://www.avaya.com/support/Copyright/.
Preventing toll fraud
“Toll fraud” is the unauthorized use of your telecommunications system
by an unauthorized party (for example, a person who is not a corporate
employee, agent, subcontractor, or is not working on your company's
behalf). Be aware that there can be a risk of toll fraud associated with
your system and that, if toll fraud occurs, it can result in substantial
additional charges for your telecommunications services.
Avaya fraud intervention
If you suspect that you are being victimized by toll fraud and you need
technical assistance or support, call Technical Service Center Toll
Fraud Intervention Hotline at +1-800-643-2353 for the United States
and Canada. For additional support telephone numbers, see the Avaya
Support Web site: http://www.avaya.com/support/. Suspected security
vulnerabilities with Avaya products should be reported to Avaya by
sending mail to: [email protected].
Trademarks
Avaya Aura is a registered trademark of Avaya.
All non-Avaya trademarks are the property of their respective owners.
PuTTY is copyright 1997-2009 Simon Tatham.
Downloading documents
For the most current versions of documentation, see the Avaya Support
Web site: http://www.avaya.com/support
Contact Avaya Support
Avaya provides a telephone number for you to use to report problems
or to ask questions about your product. The support telephone number
is 1-800-242-2121 in the United States. For additional support
telephone numbers, see the Avaya Web site: http://www.avaya.com/
support

Release 7.0.0
3 02-602658
Issue 1
 Contents
About this document ....................................................................................................................................... 9
Scope of this document .............................................................................................................................. 9
Intended Audience ....................................................................................................................................10
Conventions used in this document ..........................................................................................................10
Related documents ...................................................................................................................................11
Application Enablement Services documents.......................................................................................11
Communication Manager documents ...................................................................................................12
ECMA documents.................................................................................................................................12
Providing documentation feedback ...........................................................................................................13
New Features and Capabilities ......................................................................................................................14
Chapter 1: API Services .................................................................................................................................15
Service Provider Class ..............................................................................................................................18
Device Class .............................................................................................................................................22
Phone Class ..............................................................................................................................................22
Media Class ..............................................................................................................................................25
Call Information Link Class........................................................................................................................28
Third Party Call Controller Class ...............................................................................................................29
XML Processor Class ................................................................................................................................35
Constant Classes ......................................................................................................................................36
Call Associated Class................................................................................................................................37
Chapter 2: Getting started ..............................................................................................................................38
Setting up the development environment ..................................................................................................38
Downloading the Application Enablement Services Device, Media and Call Control .NET API SDK ...38
Setting up Visual Studio .......................................................................................................................39
Setting up your test environment ..........................................................................................................39
Understanding basic CSTA concepts ........................................................................................................39
First Party vs Third Party (Device and Media Control vs Call Control) .................................................40
Devices.................................................................................................................................................41
Physical Elements ................................................................................................................................41
Logical Elements ..................................................................................................................................41
Calls .....................................................................................................................................................41
Service Requests .................................................................................................................................41
Service Responses...............................................................................................................................42
Events ..................................................................................................................................................42
Negative acknowledgements................................................................................................................43
Call Recording...........................................................................................................................................43
Recording warning tone........................................................................................................................44
Signaling Encryption .................................................................................................................................44

Release 7.0.0
4 02-602658
Issue 1
 Media Encryption ......................................................................................................................................45
Accessing the client API reference documentation ...................................................................................46
Using the Device, Media and Call Control Dashboard ..............................................................................46
Learning from sample code .......................................................................................................................46
Chapter 3: Writing a client application ............................................................................................................48
The Dashboard tool ...................................................................................................................................48
Receiving Negative Responses ................................................................................................................49
Session Management................................................................................................................................50
Start Application Session......................................................................................................................50
Reset Application Session Timer ..........................................................................................................52
Exercise: Starting the Application Session ...........................................................................................53
SessionCharacteristics ..............................................................................................................................54
DeviceID Type ......................................................................................................................................54
Event Filter Mode .................................................................................................................................55
Device Identifiers (DeviceID) .....................................................................................................................56
Getting Device Identifiers .....................................................................................................................57
Comparing Device Identifiers ...............................................................................................................58
Populating the Device ID Switch Name and Switch IP Interface fields .................................................58
Multiple DeviceIDs ................................................................................................................................60
Controllable By Other Sessions ............................................................................................................60
Device ID Instances..............................................................................................................................61
Getting Device State Information ..........................................................................................................61
Exercise: Getting A Device ID ..............................................................................................................62
Notification of Events ................................................................................................................................63
Register for Events ...............................................................................................................................64
Unregister for Events ............................................................................................................................65
Exercise: Registering for Events ..........................................................................................................65
Registering Devices ..................................................................................................................................66
Endpoint Registration Events ...............................................................................................................68
Endpoint Registration Information ........................................................................................................70
Controllable telephone types ................................................................................................................70
Registration Modes...............................................................................................................................71
Dependency Modes .........................................................................................................................71
Media Modes ...................................................................................................................................73
Choosing a media mode.......................................................................................................................74
Choosing a codec .................................................................................................................................77
Choosing the media encryption ............................................................................................................78
Redirecting Media ................................................................................................................................78
The "share-talk" button .........................................................................................................................79
Interpretation of the ’share-talk’ button lamp state ................................................................................79
Release 7.0.0
5 02-602658
Issue 1
 Using E.164 Conversion Services ........................................................................................................80
Exercise: Performing a Device Registration .........................................................................................82
Exercise: Performing Operations on a Registered Device....................................................................85
Expanded help feature ..............................................................................................................................87
Writing Code .............................................................................................................................................89
Writing applications that run in a browser................................................................................................100
Telephony Logic ......................................................................................................................................101
Device and Media Control ..................................................................................................................101
Monitoring and Controlling Physical Elements ...............................................................................102
Knowing what buttons are administered ........................................................................................102
Detecting an incoming call .............................................................................................................103
Determining that far end has ended the call ..................................................................................104
Making a call ..................................................................................................................................104
Call Control.........................................................................................................................................106
Monitoring and Controlling Calls ....................................................................................................106
Making a call ..................................................................................................................................107
Answering a call.............................................................................................................................107
Ending a call ..................................................................................................................................107
Getting ANI information for a call ........................................................................................................108
Recording and playing voice media ....................................................................................................108
Media Operations ..........................................................................................................................110
Recording ......................................................................................................................................110
Playing a Recording Warning Tone ...............................................................................................111
Playing a recording warning tone - single step conference method ...............................................112
Playing a recording warning tone - multiple registration method ...................................................112
Dubbing .........................................................................................................................................113
Playing ...........................................................................................................................................113
Monitoring Media Events ...............................................................................................................114
Detecting and collecting DTMF tones .................................................................................................114
Detecting individual tones ..............................................................................................................116
Collecting multiple tones ................................................................................................................116
Determining when far-end RTP media parameters change................................................................118
Chapter 4: Recovery ....................................................................................................................................119
Session Recovery...............................................................................................................................120
Transfer Monitor Objects ....................................................................................................................122
Chapter 5: Cleanup ......................................................................................................................................124
Chapter 6: High Availability ..........................................................................................................................126
AE Services Geo-Redundant High Availability (GRHA) ..........................................................................126
DMCC Service Recovery ........................................................................................................................129
DMCC Support of Communication Manager High Availability Using ESS and LSP Servers ..................133
Release 7.0.0
6 02-602658
Issue 1
 Programming Considerations for High Availability ..................................................................................135
Chapter 7: Media Encryption........................................................................................................................136
The AES Encryption Scheme ..................................................................................................................136
Specifying the Devices’ Encryption Capability.........................................................................................140
MediaStartEvent Handling.......................................................................................................................140
Media Encryption Information .............................................................................................................141
Encrypting and Decrypting the RTP Stream............................................................................................141
Roll Over Counter (ROC) ...................................................................................................................141
Creating the Encryption Keys Using the Pseudo Random Function ...................................................142
Creating the Initialization Vectors (IV) ................................................................................................143
Decrypting the Media Payload............................................................................................................144
Test Data ............................................................................................................................................145
Chapter 8: Security Considerations .............................................................................................................146
Advanced authentication and authorization policies ................................................................................147
User Authentication Policies....................................................................................................................148
User Authorization Policies .....................................................................................................................148
SDB ....................................................................................................................................................148
Enterprise Directory ............................................................................................................................149
Unrestricted Access............................................................................................................................149
AA Policy Use Cases ..............................................................................................................................150
Server based applications without enterprise user identities ..............................................................150
Enterprise user based applications where user controls only their own telephone.............................150
Chapter 9: Debugging ..................................................................................................................................152
Error Messages .......................................................................................................................................152
Possible race conditions..........................................................................................................................153
Improving performance ...........................................................................................................................153
Getting support........................................................................................................................................154
Appendix A: The J-Scripts Library................................................................................................................155
J-Script ....................................................................................................................................................155
ActiveX Service Provider .........................................................................................................................156
Static event handlers ...............................................................................................................................157
Requests, response events, and events .................................................................................................157
J-Script object .........................................................................................................................................159
Service Provider Methods and Events................................................................................................160
Phone Methods and Events ...............................................................................................................160
Media Methods and Events ................................................................................................................161
Third Party Call Controller Methods and Events.................................................................................162
Call Information Methods and Events .................................................................................................163
J-Script library configuration ....................................................................................................................163
Server-side Instructions...........................................................................................................................163
Release 7.0.0
7 02-602658
Issue 1
 Client-side Instructions ............................................................................................................................164
Appendix B: Communication Manager Features..........................................................................................165
Appendix C: Constant Values ......................................................................................................................167
Phone Object Enumerations and Constants ...........................................................................................167
Media Enumerations ...............................................................................................................................176
Service Provider Enumeration.................................................................................................................177
Third Party Call Control Enumerations ....................................................................................................177
Appendix D: Unicode Mapping Table ...........................................................................................................179
Appendix E: DMCC Server Logging............................................................................................................180
Appendix F: TSAPI Error Code Definitions ..................................................................................................184
CSTA Universal Failures .........................................................................................................................184
ACS Universal Failures ...........................................................................................................................186
Appendix G: Routeing Services ...................................................................................................................188
Routeing Services Sequence Diagram....................................................................................................188
Requests to end a routeing registration session:................................................................................189
RouteRegister .........................................................................................................................................190
RouteRequest .........................................................................................................................................191
RouteSelect.............................................................................................................................................192
RouteUsed Event ....................................................................................................................................193
RouteEnd Request ..................................................................................................................................194
RouteEnd Event: .....................................................................................................................................194
RouteRegisterAbort.................................................................................................................................197
RouteRegisterCancel ..............................................................................................................................198
Appendix H: IPv6 Support ............................................................................................................................199
Usage of IPv6 addresses in AE Services ................................................................................................200
Mixed IPv4 and IPv6 networks ................................................................................................................201
Appendix I: ACS Universal Error Codes ......................................................................................................202
Glossary .......................................................................................................................................................204

Release 7.0.0
8 02-602658
Issue 1
About this document
This chapter describes the:

• Scope of this document

• Intended Audience
• Conventions used in this document
• Related documents
• Providing documentation feedback

Scope of this document

This document shows you how to use the Avaya Aura Application Enablement (AE)
Services Device, Media and Call Control (DMCC) API to develop, debug, and deploy
.NET applications that require first party or third party device, media and call control.

• Chapter 1: API Services provides background information about the AE Services

Device, Media and Call Control API and CSTA.
• Chapter 2: Getting started gets you ready to program to this API.
• Chapter 3: Writing a client application guides you in developing an application.
• Chapter 4: Recovery dicusses the available ways to recover a failed application
session.
• Chapter 5: Cleanup discusses the scenarios when to perform cleanup.
• Chapter 6: High Availability provides information on what you can expect from
the AE Services High Availability feature. It discusses the various strategies used
by AE Services to ensure that applications have reliable access to the server and
its components.
• Chapter 7: Media Encryption discusses the necessary steps to secure the RTP
data
• Chapter 8: Security Considerations discusses the security features available with
the AE Services server.
• Chapter 9: Debugging guides you in debugging an application.
• Appendix A: The J-Scripts Library discusses the ability to use the .NET API with
IE.
• Appendix B: Communication Manager Features lists the Communication
Manager features that your application can use.
• Appendix C: Constatnt Values lists the values for the XML messages parameters
which take a constant value and that are switch specific.
• Appendix D: Unicode Mapping Table specifies the appropriate bit shift for a
specific Unicode character set.
• Appendix E: Server Logging gives instructions on increasing the detail of AE
Services server logging for applications using the DMCC Service.
• Appendix F: TSAPI Error Code Definitions lists all of the values for the TSAPI
error codes that may be present in the DMCC/TSAPI logfiles, when employing
DMCC Call Control Servces.
• Appendix G: Routeing Services discusses the ability to allow applications to
request and receive routing instructions for a call.
Release 7.0.0
9 02-602658
Issue 1
 • Appendix H: IPv6 Support discusses the ability to use IPv6.
• Appendix I: ACS Universal Error Codes lists the private error codes returned in a
CSTAError response.
• Glossary defines the terminology and acronyms used in this document.

Intended Audience
This document is written for application developers. The .NET Client Library has been
tested with applications written in the following languages:
• C#
• Visual Basic

A developer should be familiar with:

• Microsoft .NET Framework
• Microsoft Visual Studio
• Telephony Concepts

You do not need to understand CSTA concepts or the Avaya Communication Manager
features and concepts, but they both might be helpful.

If you are new to CSTA, you may wish to start by reading ECMA-269, section 6.1,
“CSTA Operational Model: Switching Sub-Domain Model”. Also become familiar with the
table of contents so that you know the kinds of information available there. All of the
descriptions of the services implemented by this API are also found in the Avaya Aura®
Application Enablement Services Device, Media and Call Control .NET Programmers
Reference, found online on the Avaya DevConnect Web site
(http://www.avaya.com/devconnect ) and on the Avaya Support Web site
(http://www.avaya.com/support ).

For those new to Avaya Communication Manager, you may wish to take a course from
Avaya University (http://www.avaya.com/learning ) to learn more about Communication
Manager and its features. It is recommended that you start with the Avaya
Communication Manager Overview course (course ID AVA00383WEN). You may also
wish to peruse Appendix B: Communication Manager Features in this guide to get some
ideas of how applications can take advantage of Communication Manager’s abilities.

Conventions used in this document

The following fonts are used in this document:
To represent... This font is used...

Release 7.0.0
10 02-602658
Issue 1
Code and Linux commands request = new GetDeviceId();

.NET class, method and field the getDeviceID method

names

Window names The buttons are assigned on the Station form.

Browser selections Select Member Login

Hypertext links Go to the http://www.avaya.com/support website.

The term connector can be found in the glossary.

For details, see The Dashboard tool on page 48.

Related documents
While planning, developing, deploying, or troubleshooting your application, you may
need to reference other Avaya Aura® Application Enablement Services documents,
Avaya Communication Manager documents or CSTA documents listed below.

Application Enablement Services documents

You can find all these documents online on the Avaya Support Center Web Site
(http://support.avaya.com).

For developers, another important source of .NET API information can be found in the
following documents:

• Avaya Aura® Application Enablement Services Device, Media and Call Control
.NET Programmer’s Reference
• Dashboard User’s Guide (see the SDK .exe file)
• ReadMe.txt (see the SDK .exe file)

In the above items, you can find details about each package, interface, class, method,
and field in the .NET API.

Other Application Enablement Services documents include:

• Avaya Aura® Application Enablement Services Overview and Specification (02-

300360)
• Deploying Avaya Aura® Application Enablement Services in a Software Only
Environment (02-300355)
Release 7.0.0
11 02-602658
Issue 1
 • Deploying Avaya Aura® Application Enablement Services in Virtualized
Environment
• Administering and Maintaining Avaya Aura® Application Enablement Services
(02-300357)
• Avaya Aura® Application Enablement Services Device, Media and Call Control
API XML Programmer Guide (02-300358)
• Avaya Aura® Application Enablement Services Device, Media and Call Control
XML Programmer Reference (XMLdoc)
• Avaya Aura® Application Enablement Services Device, Media and Call Control
API Web Services Programmer Guide (02-300362)
• Avaya Aura® Application Enablement Services OAM Help (HTML)
• Avaya Aura® Application Enablement Services TSAPI and CVLAN Client and
SDK Installation Guide (02-300543)
• Avaya Aura® Application Enablement Services TSAPI for Avaya
Communication Manager Programmer Reference (02-300544)
• Avaya Aura® Application Enablement Services TSAPI Programmer’s Reference
(02-300545)
• Avaya Aura® Application Enablement Services Java Telephony API (JTAPI)
Programmer’s Reference (JTAPI v1.2 Specification) (02-300547)
• Avaya Aura® Application Enablement Services Java Telephony API (JTAPI)
Programmer's Guide (02-603488)
• Avaya Aura® Application Enablement Services ASAI Technical Reference (02-
300549)
• Avaya Aura® Application Enablement Services ASAI Protocol Reference (02-
300550)

Communication Manager documents

Since this API gives you programmable access to the Avaya Communication Manager
features, you may wish to reference the documents related to Communication Manager.

The following documents from the Communication Manager documentation set provide
additional information about administering Communication Manager for Device, Media
and Call Control API. They are on the Avaya Support Centre Web Site
(http://www.avaya.com/support ).

• Administrator’s Guide for Avaya Communication Manager (03-300509)

• Administration for Network Connectivity for Avaya Communication Manager
(555-233-504_10)

ECMA documents
The .NET Programmers Reference contains much of what you need to know about
CSTA services. For CSTA details not found in this document, please refer to the

Release 7.0.0
12 02-602658
Issue 1
following documents. They are found in the Publications section of the ECMA web site
(http://www.ecma-international.org/ ):

• ECMA-269: Services for Computer Supported Telecommunications Applications

(CSTA) Phase III
• ECMA-323: XML Protocol for Computer Supported Telecommunications
Applications (CSTA) Phase III
• ECMA-354: Application Session Services
• ECMA Technical Report TR/72: Glossary of Definitions and Terminology for
Computer Supported Telecommunications Applications (CSTA) Phase III

Providing documentation feedback

Let us know what you like or do not like about this document. Although we cannot
respond personally to all your feedback, we promise we read each response we receive.

Please email feedback to [email protected]

Thank you.

Release 7.0.0
13 02-602658
Issue 1
New Features and Capabilities
New features and capabilities in AE Services 7.0 are:
• Enhancements to the Application Enablement Service services

Increased the maximum number of DMCC station registrations from 4K
to 8K

Shared memory implementation for Transport Service to increase
reliability and performance.
• Enhancements to the Application Enablement Service DMCC .NET SDK

.NET SDK updated to support .NET Framework 4.5.2
• Enhancements to Application Enablement Services Geo-Redundancy High
Availability

The use of virtual IP addresses on all active interfaces.

Support for features similar to those used by the Fast-Reboot High
Availability (FRHA).
• Enhancements to the Application Enablement Services server

AE Services 7.0 runs on Red Hat Enterprise Linux version 6 update 5
(RHEL 6U5), with appropriate security patches from Red Hat.

Support for Out-of-Band Management (OOBM)

Support for the Avaya Aura Solution Deployment Manager

Support for the TLSv1.2 protocol

Use of a new 1year self-signed server certificate for the AE Services
server as the default server certificate‡
• Changes to the Application Enablement Services offer

Dropped support for the AE Services on Bundled offer

Dropped support for the AE Services on System Platform offer, including
the FRHA and MPHA features.

Removed support for the SSLv3 protocol

‡
WARNING: Since the default certificate used by earlier releases of AE Services has been replaced, any
applications that rely on this certificate for SSL/TLS will fail SSL negotiation with an AE Services 7.0 server.
To overcome this in your test environment, you will need to export the server certificate from the AE
Services and import into your application’s trust-store. Note that, for a production environment, you are
strongly advised to create your own server certificates and install them on the AE Services server (and
include the CA in your application’s trust-store). Please refer to the “certificates” section of the AE Services
Administration and Maintenance Guide for more details

Release 7.0.0
14 02-602658
Issue 1
Chapter 1: API Services
This chapter provides an overview of what CSTA services this API supports.

This API supports the following telephony services:

• Device Control
• Media Control (including call recording, message playing and dubbing)
• Call Control
• Tone Collection and Detection
• Routeing Services

These services are provided through an XML protocol which is wrapped by the .NET
API. Some of the interfaces of the XML protocol conform to the CSTA III standard
(ECMA-269) and some are Avaya extensions to the CSTA standard.
In CSTA, each service is defined to be a request that either comes from the application
to a switch or from a switch to the application. This API, however, is based on a
client/server model where the application is the client and the AE Services server
software and Communication Manager together act as the server. Thus, this API allows
an application:
• to request services of Communication Manager
• to request notification of asynchronous events on Communication Manager

CSTA specifies that for any given service some parameters are mandatory and some
parameters are optional. To determine which of the optional parameters Avaya supports
or which of the field values Avaya supports, refer to the requests and responses detailed
in the XML Programmer’s Reference on the Avaya Support site. The Dashborad tool is
also another good source to determine which parameters are optional.

The .NET API, which follows the event based asynchronous pattern, abstracts the XML
protocol requests and responses into a set of reusable service classes. The exposed
.NET classes will model all requests and responses (or exceptions) asynchronously and
will model all events and handlers using standard .NET conventions.

This API exposes the following .NET classes:

• Service Provider Class

• Device Class
• Phone Class
• Media Class
• Call Information Link Class
• Third Party Call Controller Class
• XML Processor Class
• Constant Classes
• Call Associated Class

Release 7.0.0
15 02-602658
Issue 1
The following table provides a correlation between the supported CSTA services and
the .NET exposed service classes.

Table 1: Correlate Supported CSTA Services to the .NET API

.NET API Supported CSTA CSTA AE Services
Classes CSTA specifications XML License Consumed
Services protocol
Service Application ECMA-354 ECMA- None
Provider Session Ch.4 354,
Services Ch.5
Service Capability ECMA-269, ECMA- None
Provider Exchange sec. 13 323, sec.
Services 11
Service System ECMA-269, ECMA- TSAPI
Provider Services sec 14 323, sec
12
Phone Physical ECMA-269, ECMA- None2
Device sec. 21 323, sec.
Services and 19
Events
Media Voice Unit ECMA-269, ECMA- None 2
Services and sec. 26 323, sec.
Events 24
Third Party Call Control ECMA-269, ECMA- TSAPI or Advanced
Call Control Services sec. 17 323, sec. TSAPI
15
Third Party Logical Device ECMA-269, ECMA- TSAPI
Call Control Services sec. 22 323, sec.
20
Third Party Snapshot ECMA-269, ECMA- TSAPI
Call Control Services sec. 16 323, sec.
14
All Monitoring ECMA-269, ECMA- Depends on Service
Services1 sec. 15 323, sec. being monitored
13
Third Party Routeing ECMA-269, ECMA- Advanced TSAPI
Call Control Services sec. 20 323, sec.
18
Call Call ECMA-269, ECMA- None
Associated Associated sec. 18 323, sec
Services 16

1
This API implements the intent of CSTA’s Monitoring Services using .NET Event Handlers
2
This API does not consume a license. However, it is necessary to register a DMCC endpoint in
order to use this service, and this registration will consume a DMCC or IP_API_A license.
Release 7.0.0
16 02-602658
Issue 1
The XML API provide extensions to the CSTA Service Set referred to as Avaya
Extensions that are meant to enhance the capabilities of CSTA and provide higher-level
services and useful events that make development of telephony applications easier.

The following table provides a correlation between the XML API Avaya Extensions and
the .NET exposed service classes.

Table 2: Correlate Avaya Extensions to the .NET API

.NET API Avaya Extends Purpose AE
Classes Extensions which CSTA Services
Service Set License
Consumed
Call Call None Provides the ability to None
Information Information obtain detailed call
Link Services and information and to
Events determine the status
of the call information
link.
Device Device None Provides an identifier None
Services for a given dial string
on Communication
Manager
Media Extended Voice Unit Provides dubbing of None
Voice Unit Services recorded messages
Services and other extensions
to playing and
recording of files
Media Media Control None Provides the ability to None
Events be notified when the
far-end RTP and
RTCP parameters for
a media stream
change.
Phone Registration None Provides ability to DMCC or
Services gain main, dependent IP_API_A
or independent
control over
Communication
Manager endpoints -
also referred to as
device registration
Service E164 None Allows an application None
Provider Conversion to convert from an
Services E.164 to a
Communication
Manager dial string
and vice versa.
Media Tone None Detects DTMF tones None

Release 7.0.0
17 02-602658
Issue 1
 Collection and buffers them as
Services and requested before
Events reporting them to the
application
Media Tone Replaces Detects DTMF tones None
Detection Data and reports each
Events Collection tone as it is detected
Services

The remaining sections of this chapter will provide additional details about the .NET
API classess. If you are interested in additional information about the supported CSTA
Services, please see the CSTA specifications listed in Table 1. For a general overview
of the CSTA Services and additional information about the Avaya Extensions please
see Chapter 1 of the Avaya Aura® Application Enablement Services Device, Media and
Call Control API XML Programmer Guide.

Service Provider Class

The Service Provider Class is used to establish and maintain a relationship between an
application and a server for the purpose of exchanging application messages.

This class act as a bootstrap class for connecting to the server, performing session
management, retrieving other objects and disconnecting from the server. In addition to
these features, this class also provides support for the CSTA System Service to allow an
application to obtain the status of the TLink connections between the AE Services server
and Communication Manager. To learn how to use the Service Provider Class, see The
Dashboard tool on page 48.

The Service Provider Class provides the following asynchronous operations:

Table 3: Service Provider Class Requests

Method Name Description

ChangeSystemStatusFilter Changes the System Status monitor events for a

current System Registration.
ConvertDialStringToE164 Convert one or more dial strings to E164 format.

ConvertE164ToDialString Convert one or strings which are in E164 format

to dial strings.
Get Auto Keep Alive Enabled Lets the application know if auto keep alive is
enabled.

Release 7.0.0
18 02-602658
Issue 1
Get Device Given a device name (Id), returns a reference to
the associated Device.
Get Device ID List Get all the Device IDs that are active on the
DMCC server.

Get Monitor List Get a list of all the monitors which are active on
this DMCC server.
Get New Device Creates a new Device object and returns a
reference to it.

As of Release 5.2 you can specify the Device

Instance (0, 1, 2) when getting a new Device.
This will allow you to get up to three devices for
a particular station on a single AE Services.
Before Release 5.2 you would need three
separate AE Services servers to do this.
Requesting the Device Instance is optional so
your existing application will work the same if
you do not need or desire this capability.
Get Physical Device Information Gets device information for the specified device.
Provides the class (voice, data, image or other)
and type (station, ACD, ACD Group or other) of
the device
Get Physical Device Name Gets the device name for the specified device in
Communication Manager’s (CM) Integrated
Directory database.
Get Session ID List Retrieve all the active sessions that are running
in a DMCC server.
Reconnect Sends a StartApplicationSession
message to the server. If sessionId is not null
then the server will try to reconnect a session
that has timed out or become inactive.
Request System Status Allows the application to get a snapshot of the
current status of one or all administered TLinks
between the AE Services and Communication
Manager.
Reset Application Session Sends a ResetApplicationSession XML
message to the server.
Session Management Start Start the monitor for session management.
Monitor
Session Management Stop Stop a session management monitor.
Monitor

Release 7.0.0
19 02-602658
Issue 1
SetSessionCharacteristics Configures the session characteristics
(specifically, Device ID Type, and Event Filter
Mode) for the session.

Starting with the 5.2 release of AE Services,

DMCC applications will be able to specify
several “Session Characteristics” that will alter
the way their application interfaces with DMCC.
The following are the session characteristics that
can be specified. These characteristics are
optional and if not specified the previous
behavior will be preserved.
See the “Writing a client Application” section for
more information.
Shut Down Allows the application to tell the Service Provider
to shutdown. The Service Provider will in turn
notify ThirdPartyCallControl,
CallInformationLink, and all the Devices
that have been created to also shut down. The
Devices in turn will notify their Phone objects.
The Phone Objects will in turn notify their Media
Objects. Calling this method will also force the
socket to the server to be closed. Therefore,
once this method returns control to the
application the application should not invoke any
methods which will result in a message being
sent to the server. If the application does do this
then exceptions will be thrown back to the
application. Note: The API provides a callback
(OnObjectDeactivatedEvent) for all publicly
exposed objects. This will allow the application
the ability to easily be notified when an object
has bee shutdown (deactivated).
Start Application Session Initiates an application session between an
application and a server
Start Auto Keep Alive Tells the API to start automatically sending the
ResetApplicationSession messages every
intervalInMs milliseconds. 1,000 milliseconds is
1 second.
Stop Application Session Terminates an existing application session.
Stop Auto Keep Alive Stops the ResetApplicationSession
messages from automatically being sent to the
server.
System Register Allows the application to register for System
Status notification (linkup/linkDown) of any
change in status for one or all administered
TLinks (TSAPI CTI Link).

Release 7.0.0
20 02-602658
Issue 1
System Register Cancel Allows the application to cancel a previously
initiated System Register request.

Transfer Monitor Objects Transfer all the devices and monitors from one
session to another session. The session which
the monitors are being transferred from will be
closed by the DMCC server.
Get Actual Protocol Version Retrieves the API version for the server.
Get Call Information Link Returns a reference to the CallInformationLink
object.
Get Last Incoming Xml Message Retireves the last XML message received.

Get Session ID Returns the session name (id) as a string.

Get Third Party Call Controller Returns a reference to the ThirdPartyCallControl

object.
Get Xml Processor Returns a reference to the XML Processor
object.
Get Time of Day Allows the application to get the current time of
day for a specified switch
Get Call Associated Returns a reference to the Call Associated
object

The Service Provider Class raises the following events:

Table 4: Service Provider Events

Event Name Description

Missed At Least One Keep Alive Occurs if the server has missed at least one
Event keepalive
Server Connection Down Occurs if the socket to the AE Services server
has gone down for some reason
Server Connection Not Active Occurs if a message was received by the AE
Services server but the session has timed out
and been placed in the inactive state
System Register Abort Occurs when an active System Registration has
been cancelled (e.g. if the TSAPI Service is
stopped)
System Status Occurs for changes in the TLink status of one or
all administered TSAPI CTI links. Once an
application is registered, notifications are sent
when the TLink status changes (e.g.
linkup/linkDown).
Release 7.0.0
21 02-602658
Issue 1
Device Class
The Device Class is used to communicate to the server in order to get a new DeviceID
for a particular extension. The device object contains the phone object. There will be one
Device Object for every device that is being used in the application. To learn how to use
the Device Class, see The Dashboard tool .

Note:
Care must be taken when creating a Device ID to ensure that the switch name is
properly set in the Device ID. Please see “Populating the Device ID Switch Name
and Switch IP Interface fields” for more information.

The Device Class provides the following asynchronous operations:

Table 5: Device Class Requests

Method Name Description

Get Device ID As String Gets the device identifier that represents the
device described by its extension number and
the Communication Manager upon which it
resides, as a string
Get Extension Returns the extension associated with this
device.
Get Phone Returns the reference to the phone object for
this Device.
Get Service Provider Returns an instance of a Service Provider
object.
Get Device ID Gets the device identifier that represents the
device described by its extension number and
the Communication Manager upon which it
resides. Release 5.2 and later supports the
ability to also send the Device Instance (0, 1, or
2) which is to be created.
Release Device ID Sends a ReleaseDeviceId XML message to
the server.

Phone Class
The Phone Class provides physical device control which allows an application the ability
to manipulate and monitor the physical aspects of a device, which includes buttons,
lamps, the display, and the ringer. The services simulate manual action on a device as
Release 7.0.0
22 02-602658
Issue 1
well as provide the ability to request status of physical elements. The events provide
notification of changes to the physical elements of the device.

All services that operate on a particular device use a device identifier to specify the
device. This class will also provide a device identifier for a given extension on
Communication Manager.

The Phone Class will also provide the ability to gain Main, Dependent or Independent
control over a device and to specify the desired media mode for that device.

Main, Dependent and Independent control is described in the "Device and media
control" section of the "Capabilities of the API" chapter of the Avaya Aura® Application
Enablement Services Overview. For a list of device types that can be controlled with this
API and for further distinction between the registration modes, see the "Controllable
telephone types" section of the "Capabilities of the API" chapter of the Avaya Aura®
Application Enablement Services Overview.

The desired media parameters are also specified using the Phone Class. The options for
the Media parameters are described in the "Media control modes" section of the
"Capabilities of the API" chapter of the Avaya Aura® Application Enablement Services
Overview.

To learn how to use the Phone Class, see The Dashboard tool.

Note:
Care must be taken when creating a Device ID to ensure that the switch name is
properly set in the Device ID. Please see “Populating the Device ID Switch Name
and Switch IP Interface fields” for more information.

The Phone Class provides the following asynchronous operations:

Table 6: Phone Class Requests

Method Name Description

Change Device Security Code Allows a DMCC client to change the security
code of an extension on Communication
Manager.
Change Monitor Allows a DMCC client the ability to change the
attributes of an existing monitor.

Validate Device Security Code Allows a DMCC client to validate the security
code of an extension on Communication
Manager.
Get Device Returns the device that this phone object is in.

Get Media Mode Returns the current media mode that the phone
is in.

Release 7.0.0
23 02-602658
Issue 1
Get Media Returns the media object which will perform all
media operations on this phone.
Get Registered Returns true if the phone is currently in the
registered state.
Get Button Info Gets the button information for either a specified
button or all buttons on a device, including the
button identifier, button function, associated
extension (if applicable), and associated lamp
identifier (if applicable)
Get Display Gets a snapshot of the contents of the physical
device's display
Get Hookswitch Status Gets the hookswitch status of a specified device,
either on hook or off hook
Get Lamp Mode Gets the lamp mode status for either a specified
button or all buttons on a device, including how
the lamp is lit (flutter, off, steady, etc.), color and
associated button
Get Message Waiting Indicator Gets the message waiting status at a specified
device, either on or off
Get Registration State Get the current registration state for the phone.
If the state is “REGISTERED”, it also returns the
H.323 gatekeeper IP address.
Get Ringer Status Gets the ringer status of the ringer associated
with a device, including ring mode (ringing/not
ringing) and the ring pattern such as normal ring
or priority ring
Press Button Simulates the depression of a specified button
on a device
Redirect Media Instruct Communication Manager to direct the
media to a different IP Address
Register Terminal Registers a specific device with Communication
Manager in order to gain main, dependent or
independent control over the phone or extension
and specifies the desired media mode.
Applications can specify whether media
encryption is desired while registering.

Release 5.2 and later supports the ability to

specify the Unicode Script. The Unicode Script
specifies the character set on Communication
Manager that is configured for that station.

See Appendix D for more information.

Set Hookswitch Status Sets the hookswitch status of a specified device
to either onhook or offhook

Release 7.0.0
24 02-602658
Issue 1
Start Monitor Informs the API of what type of phone events
the application wishes to be notified of. Phone
events are events like lamp updates, display
updates, ringer updates, etc
Stop Monitor Cancels a previously initiated Start Monitor
request
Unregister Terminal Unregisters the specified device from
Communication Manager in order to give up
control of the device

The Phone Class raises the following events:

Table 7: Phone Class Events

Event Name Description

Display Updated Occurs if the contents of a device's display has

changed
Hookswitch Updated Occurs if Communication Manager has changed
the device's hookswitch status
Lamp Updated Occurs if the lamp mode status of a particular
lamp has changed
Ringer Status Updated Occurs if the ringer attribute associated with a
device has changed status
Terminal Reregistered Occurs when the Communication Manager, to
which the device is registered, fails-over to an
ESS or LSP. This causes the device to be
unregistered from the Main switch and re-
registered with the ESS/LSP. Similarly, another
Reregistered event will be sent when the
ESS/LSP switches back to the Main CM.

Note that the CM fail-over (and consequent re-

registration) may negate any temporary changes
(on the switch) that have been set up for the
device.

Terminal Unregistered Occurs if the specified device has been

unregistered from Communication Manager

Media Class
The Media Class provides an interface to allow media processing to be performed
including play, record and tone collection.

Release 7.0.0
25 02-602658
Issue 1
This class will allow an application to record voice stream data coming into a device and
to play messages to the device’s outgoing voice stream.

This class will also allow your application to collect DTMF tones coming into a device,
store them in a buffer, and report the tones based on application-specified retrieval
criteria. The retrieval criteria can be one or more of the following:

• The specified number of tones has been detected

• The specified tone has been detected
• The specified amount of time has passed

If multiple criteria are specified, then the first condition that occurs terminates the
retrieval and reports the string of DTMF tones collected. Both in-band and out-of-band
tone collection are supported. Out-of-band tone collection is recommended.

When tones are retrieved and reported to the application, they are removed from the
buffer. If the buffer fills up, the oldest tones are overwritten with the new detected tones.

The Tone Detection Events notifies an application whenever a DTMF tone has been
detected coming into a device. Both in-band and out-of-band tone detection is
supported. Out-of-band tone detection is recommended.

To learn how to use the Media Class, see “The Dashboard tool” and “Recording and
playing voice media” and “Detecting and collecting DTMF tones”.

The Media Class provides the following asynchronous operations:

Table 8: Media Class Requests

Method Name Description

Change Monitor Allows a DMCC client to change the attributes of

an existing monitor.
Delete Message Deletes a specified file from the AE Services
server
Flush tone Collection Buffer Reports the DTMF tones received since the last
time the buffer was flushed and flushes the
buffer
Get Device Returns the parent Device object that the media
object is a part of.
Resume Playing Resume only playing, not recording
Resume Recording Resumes only recording, not playing.

Release 7.0.0
26 02-602658
Issue 1
Start Monitor Informs the API of what type of media events the
application wishes to be notified of. Media
events are events like media started, media
stopped, recording starting/playing, recording
stopped, tone detected, etc
Stop Monitor Cancels a previously initiated Monitor Start
request
Start Playing Sends a Start Playing XML message to the
server.
Stop Playing Stops only the player, not the recorder.
Suspend Playing Suspends only the player, not the recorder.
Start Recording Sends a Start Recording XML message to the
server.
Stop Recording Sends a Stop Recording XML message to the
server.
Suspend Recording Suspends only the recorder, not the player.
Start Dubbing Starts replacing an existing recording session
with the specified file
Stop Dubbing Stops replacement of an existing recording
session
Set Tone Retrieval Criteria Specifies the retrieval criteria
Start Tone Collection Used to start collecting DTMF tones sent to a
device and specifies the termination criteria.
Stop Tone Collection Used to stop collecting DTMF tones sent to a
device and report the tones that have been
buffered. This flushes the buffer.

The Media Class raises the following events:

Table 9: Media Class Events

Event Name Description

Playing Indicates that a message is being played

Playing Suspended Indicates that a message is suspended in play
Playing Stopped Indicates that a play (or record) operation of a
message on a device has been stopped or has
completed.
Recording Indicates that a message is being recorded
Recording Suspended Indicates that a message is suspended during
recording

Release 7.0.0
27 02-602658
Issue 1
Tones Retrieved Occurs when DTMF tones are retrieved from the
buffer. This event reports the retrieved tones to
the application.
Tone Detected Occurs when a DTMF tone has been sent to the
device
Media Started Indicates when the far-end RTP parameters
have changed and an RTP session has been
established. Also provides the media encryption
keys if media encryption is enabled for the
device.
Media Stopped Indicates when the far-end RTP parameters
have changed to null and the RTP session has
been disconnected

Call Information Link Class

The Call Information Link Class provides an interface to allow call information and Call
Information Link (DAPI link) monitoring to occur.

This class allows applications to get detailed call information and to determine the status
of the call information link. The call information link must be operational to get the call
information. The call information link is one of the communication links between
Communication Manager and the AE Services server.

The Call Information Link Class provides the following asynchronous operations:

Table 10: Call Information Link Class Requests

Method Name Description

Get Call Information Used to get detailed call information.

Get Link Status Used to get the status of the call information
link to the AE Services server.
Start Monitor Informs the API of what type of call information
events the application wishes to be notified of.
There are two Call information events: link-up
and link-down.
Stop Monitor Cancels a previously initiated Monitor Start
request

The Call Information Link Class raises the following events:

Table 11: Call Information Link Class Events

Event Name Description

Release 7.0.0
28 02-602658
Issue 1
Link Up Occurs when a link has come up and is now
active. Occurs the first time the link is brought
up, as well as every time the link is brought up
after being down.
Link Down Occurs when a link has gone down and is now
inactive. Occurs when it is determined that
Communication Manager is not responding or
Communication Manager and Device, Media
and Call Control API are out of sync.
Response will indicate which link is down and
whether the AE Services server will attempt to
reconnect automatically.

Third Party Call Controller Class

The Third Party Call Controller Class provides an interface to allow basic 3rd Party Call
Control to be performed.

This class will provide single step conferencing capabilities to allow an application to add
a device into an existing call.

This class will allow an application to obtain 3rd party information about the devices
participating in a specified call. The information returned includes device identifiers, their
connections in the call, and local connection states of the devices in the call as well as
call related information.

This class provides information about calls associated with a given device. The
information provided identifies each call the device is participating in and the local
connection state of the device in that call.

The Call Control Services utilizes the TSAPI Service on the AE Services server. The use
of the Call Control Services requires the setup of the connection and cti-link between the
AE Services server and Communication Manager as well as a basic TSAPI license.
The use of the Snapshot Services requires the setup of the connection and cti-link
between the AE Services server and Communication Manager as well as a basic TSAPI
license

Note:
Care must be taken when creating a Device ID to ensure that the switch name is
properly set in the Device ID. Please see “Populating the Device ID Switch Name
and Switch IP Interface fields” for more information.

The Third Party Call Controller Class provides the following asynchronous operations:

Table 12: Third Party Call Controller Class Requests

Method Name Description

Release 7.0.0
29 02-602658
Issue 1
Alternate Call Performs a third party Alternate Call
operation (put active call on hold and unhold
held call).
Answer Call Performs a third party Answer Call operation
(answers an incoming call).
Change Monitor Allows a DMCC client to change the
attributes of an existing monitor.
Clear Call Perform a third party Clear Call operation
(drops all parties on a call).
Clear Connection Performs a third party Clear Call operation
(drops all parties on a connection).

Conference Call Performs a third party Conference Call

operation (merges the held call into the
active call).

Consultation Call Performs a third party Consultation Call

operation (puts the active call on hold and
calls another device). Provides support for a
Direct Agent or Supervisor Assist Call.

Deflect Call Performs a third party Deflect Call operation

(directs an incoming call to another
destination).
Directed Pick Up Performs a third party Directed Pick Up
operation (moves a specified call and
connects it at a new specified destination).
Endpoint Registration Information Retrieves the current registration information
for the specified device. Registration data for
each registered deviceID instance (up to 3
H.323 endpoints and 1 SIP endpoint) may be
included in the response.
Note that the device does not have to be
registered through DMCC, but it must be
registered to Communication Manager using
the H.323 or SIP protocol.

The EndpointRegistrationInfo query is meant

to be used for queries to physical stations,
not for extensions associated with agent IDs.
It will return an error if a logical agent
extension number is used as the deviceId for
the query

Release 7.0.0
30 02-602658
Issue 1
Generate Digits Performs a third party Generate Digits
operation (inject touch tone digits into an
active call).

Get ACD Split Performs a Third Party Get ACD Split

information request. Provides the number of
ACD agents available to receive calls
through the split, the number of calls in
queue, and the number of agents logged in.

Get Agent Login Provides the extension of each ACD agent

logged into the specified ACD split.

Get Agent State Provides the agent state at a specified

device.

Get Call Linkage Data Retrieve the Call Linkage Data for a normal
callID. (Avaya Universal Call ID - UCID).

Get Do Not Disturb Performs a third party Get Do Not Disturb

operation (determines if Do Not Disturb, AKA
Send All Calls, is active).
Get Third Party Device ID Gets a third party device identifier
information for the selected DeviceId. This
information is necessary in order to perform
other third party call functions.
Get Forwarding Performs a third party Get Forwarding
operation (determines if call forwarding is
active, if so the call forwarding destination is
provided).
Get Message Waiting Indicator Get the message waiting indicator status at a
specified device (either on or off)

Hold Call Performs a third party Hold Call operation

(puts an active call on hold).
Make Call Performs a third party Make Call operation
(originates a call for the specified third party
Device ID). With the addition of Private Data
support, originates a call between two
devices for a user station and an ACD agent
logged into a specified split (aka Agent Call)
or an ACD agent’s extension and another
station extension (typically a supervisor)
device (aka Supervisor Assist Call).

Release 7.0.0
31 02-602658
Issue 1
Make Predictive Call Performs a third party Make Predictive Call
operation (originates a call between two
devices by first creating a connection to the
called device).

Reconnect Call Performs a third party Reconnect Call

operation (drops the active call and unhold a
call that is held).
Retrieve Call Performs a third party Retrieve Call
operation (takes a call off of hold and makes
it active).
Route Register The RouteRegister request is used to tell AE
Services that the client application is
interested in routing calls that are going to
the VDN which is specified in the deviceId
parameter.

When a call is routed to a VDN and the step

in the associated vector is an "Adjunt Route"
then a "RouteRequest" event will be sent
from AE Services to the client application.

When the client application receives the

"RouteRequest" event from AE Services the
client application then decides how to route
the call and instructs AE Services via the
"RouteSelect" method.

Route Register Cancel The RouteRegisterCancel request is used to

tell AE Services that the client application is
no longer interested in receiving
RouteRequests for the specified Route
Register Requester Id.

Route Select The RouteSelect request is used to tell AE

Services how the call should be routed.

Route End The RouteEnd request is used to tell AE

Services that the client application is done
routing the call.

Selective Listening Hold The SelectiveListingHold request is not a

ECMA-269 specified request, but rather a
private request supported by TSAPI. The
Selective Listening Hold Service allows a
client application to prevent a specific party
on a call from hearing anything said by
Release 7.0.0
32 02-602658
Issue 1
 another specific party or all other parties on
the call. It allows a client application to put a
party’s (subjectConnection) listening path to
a selected party (selectedParty) on listen-
hold, or all parties on an active call on listen-
hold. The selected party or all parties may be
stations or trunks. A party that has been
listen-held may continue to talk and be heard
by other connected parties on the call since
this service does not affect the talking or
listening path of any other party. A party will
be able to hear parties on the call from which
it has not been listen-held, but will not be
able to hear any party from which it has been
listen-held. This service will also allow the
listen-held party to be retrieved (i.e., to again
hear the other party or parties on the call).

Selective Listening Retrieve Allows the client application to allow a party,

which was in a listen hold state, to resume
listening to a call.

Set Agent State Allows the client application to change the

agent’s state at a specified device (including
work mode and reason code).

Set Do Not Disturb Performs a third party Set Do Not Disturb

operation (allows you to enable/disable Do
Not Disturb AKA Send All Calls).
Set Forwarding Performs a third party Set Forwarding
operation (allows you to enable/disable Call
Forwarding for the specified Device ID).
Set Message Waiting Indicator Set the message waiting indicator status at a
specified device (either on or off)

Single Step Conference Call Adds a device to an existing call.

Single Step Transfer Call Performs a third party Single Step Transfer
Call operation (transfers an active call to
another device).
Snapshot Call Provides information about the devices
participating in a specified call.
Snapshot Device Provides information on the status of calls at
a specific device.

Release 7.0.0
33 02-602658
Issue 1
Start Monitor Informs the API of what type of Third Party
Call Control events the application wishes to
be notified of.

Stop Monitor Turn a monitor off.

Transfer Call Performs a third party Transfer Call

operation (transfers the call on hold to the
active call and drops the party doing the
transfer).

The Third Party Call Controller Class raises the following events for a device type
monitor or a call type monitor (Per Call or CallsViaDevice):

Table 13: Third Party Call Control Class Events

Event Name Description

Agent Logged Off Occurs when an agent has logged off an ACD
device or an ACD group.

Agent Logged On Occurs when an agent has logged on an ACD

device or an ACD group.

Agent Login Extension A private event that is sent after a

GetAgentLogin Request/Response.

Call Cleared Indicates that a call has been cleared and no

longer exists within the switching sub-domain.
Conferenced Indicates that the conferencing device has
conferenced itself or another device with an
existing call.
Connection Cleared Indicates that a device in a call has
disconnected or dropped out from a call.
Delivered Indicates that a call is being presented to a
device in either the Ringing or Entering
Distribution modes of the alerting state.
Diverted Indicates that a call has been diverted from a
device.
Do No Disturb Indicates that the do not disturb status has
changed.
Endpoint Registered Event Occurs when a H.323 or SIP endpoint
registers against the device’s extension
number.
Note that the endpoint does not have to be
registered via DMCC, but the Communication
Manager must be CM 6.3 or later for H.323
endpoints and CM 6.3.2 or later for SIP
endpoints.

Release 7.0.0
34 02-602658
Issue 1
Endpoint Unregistered Event Occurs when a H.323 or SIP endpoint
unregisters from the device’s extension
number.
Note that the endpoint does not have to be
registered via DMCC, but the Communication
Manager must be CM 6.3 or later for H.323
endpoints and CM 6.3.2 or later for SIP
endpoints.

Established Indicates that a device has answered or has

been connected to a call.
Failed Indicates that a call cannot be completed
and/or a connection has entered the Fail state.
Forwarding Indicates that the forwarding status has
changed.
Held Indicates that an existing call has been put on
hold.
Message Waiting Indicates the message waiting indicator status
changed (either from off to on or vice versa)
Network Reached Indicates that a call has cut through the
switching sub-domain boundary to another
network; that is, has reached and engaged a
Network Interface Device (e.g., trunk, CO
Line).

Originated Indicates that a call is being attempted from a

device.
Queued Indicates that a call has been queued.

Retrieved Indicates that a previously held call has been

retrieved.
Service Initiated Indicates that a telephony service has been
initiated at a monitored device.

Transferred Indicates that an existing call has been

transferred to another device and that the
device transferring the call has been dropped
from the call.

XML Processor Class

The XML Processor Class provides 2 key features:

• It provides a method to allow a client to send their own XML messages to the
server and a response handle to then process the XML response. It also
provides an event handler to process any unhandled events coming from the
Release 7.0.0
35 02-602658
Issue 1
 server. This allows an application to take advantage of new server features
without having to wait for a client with the support for that new feature.
• It provides the ability for the application to register two event handlers. One
handler is called when any request is sent to the server. The event includes the
XML message sent to the server. The 2nd handler is called when any request,
exception or event is received from the server. This can be useful for debug
purposes or for application developers working at the XML level who want to see
what these "raw" message look like.

The XML Processor Class provides the following asynchronous operations:

Table 14: XML Processor Class Requests

Method Name Description

Inject XML Send XML directly to server. No verification on

XML is done before it is sent.

The XML Processor Class raises the following events:

Table 15: XML Processor Class Events

Event Name Description

Unhandled XML Message Event registration for getting notified when

XML messages are not processed by the API.
XML Data Inject XML Response Event registration for responses to InjectXml
request.
XML Message Sent Event registration for getting notified when
XML messages are sent to the server.
XML Message Received Event registration for getting notified when
XML messages have been received from the
server.

Constant Classes
Constant classes are provided for the following:

• Button Function Constants

• Button ID Constants
• Lamp Mode Constants
• Ringer Pattern Constants
• Media Constants
• Registration Constants
• API Version Constants
• Service Name Constants
Release 7.0.0
36 02-602658
Issue 1
Please see Appendix C: Constant Values for more information on these constant
classes.

Call Associated Class

The Call Associated Class allows applications to request the Communication Manager
to generate a recording telephony tone on behalf of a specific device that has been
registered using DMCC. The client application can also cancel the recording telephony
tone for the device. This service requires AE Services 6.3 or later and Communication
Manager 6.3 or later.
The Call Associated Class provides the following asynchronous operations:

Table 16: Call Associated Class Requests

Method Name Description

Generate Allows the application to request a warning

Telephony Tone tone be played every few seconds, whenever
the specified device is on a call. If the device is
active on a call when the warning tone request
is generated, the change is effective after the
active call ends. The device must be
registered via the DMCC service.
Cancel Allows the application to cancel a previous
Telephony Tone warning telephony tone. If the device is active
on a call when the warning tone is cancelled,
the change is effective after the active call
ends.
Start Monitor Requests the application be notified when the
Communication Manager fails to generate a
warning tone during recovery
Stop Monitor Cancels a previously initiated Call Associated
monitor.

The Call Associated Class raises the following events:

Table 17: Call Associated Class Events

Event Name Description

Telephony Tone An event that indicates that the

Aborted Communication Manager failed to regenerate
the warning telephony tone for the specified
device, following a fail-over recovery. The
application must send a new
GenerateTelephonyTones request in order to
re-establish the warning tone.

Release 7.0.0
37 02-602658
Issue 1
Chapter 2: Getting started
This section describes what you need to do and what you need to know before you
begin programming to this API, including:

• Setting the development environment

• Understanding basic CSTA concepts
• Call Recording
• Signaling Encryption
• Media Encryption
• Accessing the client API reference documentation
• Using the Device, Media, and Call Control Dashboard
• Learning from sample code

Setting up the development environment

Applications will be developed using the Microsoft Visual Studio tool. To develop your
.NET application using Visual Studio, you must make a reference to the
ServiceProvider.dll file.

Downloading the Application Enablement Services Device, Media and

Call Control .NET API SDK
To download the Application Enablement Services Device, Media and Call Control .NET
API SDK from the Avaya DevConnect Web site:

1. Go to www.avaya.com/devconnect
2. Select Member Login.
3. Log in with your email address and password.
4. Download the SDK (dmcc-dotnet-sdk-x.exe) from the DevConnect website
by navigating to the Application Enablement Services page and selecting the
appropriate SDK from the Technical Resources section. The download location
defaults to the desktop, but it does not matter where you download the files in
your directory system. The SDK file is dmcc-dotnet-sdk-x.exe, where x is the
load number.
Note:
The Application Enablement Services page can be located
through the Avaya Product Information/Documentation/SDKs link
under the left-hand Do Your Research menu options.

5. Invoke the file, dmcc-dotnet-sdk-x.exe, to execute the self-extracting WinZip file.

Release 7.0.0
38 02-602658
Issue 1
 6. Follow the instructions to accept the End-User License Agreement (EULA) and
install the SDK. All of the SDK files are placed into a directory named dmcc-
dotnet-sdk.

Setting up Visual Studio

In Visual Studio:
1. Right click on References in the Solution Explorer window
2. Select Add Reference
3. Select the Browse tab
4. Browse to the folder where the ServiceProvider.dll file resides in the unzipped
.NET SDK
5. Select the file and hit OK

Setting up your test environment

Before running an application you will need to have an AE Services server machine
setup. For instructions see the appropriate Avaya Aura® Application Enablement
Services Implementation Guide for the offer you have purchased (Software Only or
VMware).

Understanding basic CSTA concepts

CSTA stands for Computer-Supported Telecommunications Applications. It is a standard
produced by ECMA, an international standards body (http://www.ecma-international.org
). CSTA provides a standard for Computer-Telephony Integration (CTI). When fully
implemented, CSTA allows an application to:
• monitor calls on dial strings, lines or trunks
• modify the behavior of calls
• make a call between two parties

The Avaya Application Enablement Services Device, Media and Call Control API,
implements a subset of the CSTA standard including some Avaya specific extentions to
the CSTA framework. The API supports monitoring and making calls at the physical
device level. Applications using this API have first party device control, first party media
control and third-party call control.

The following sections describe what you need to know about the following CSTA
concepts

• First Party vs Third Party (Device and Media Control vs Call Control)
• Devices
• Physical Elements
• Logical Elements
Release 7.0.0
39 02-602658
Issue 1
 • Calls
• Service Requests
• Service Responses
• Events
• Negative Acknowledgements

First Party vs Third Party (Device and Media Control vs Call Control)
Basically, the differences between Device and Media Control and Call Control are the
differences between first-party and third-party call control.

AE Services’ Device and Media Control uses first-party call control, where an application
interacts with an endpoint using the model of a person physically manipulating a phone.
For example, to make a call a person picks up a handset and presses each digit, one
after the other. Similarly, to make a call an application invokes a method to cause the
endpoint to go off hook and invokes a PressButton method once for each digit. This
gives an application fine-grained control of and information about an endpoint’s state.

In contrast, AE Services’ Call Control uses third-party call control, where an application
issues higher level instructions. To make a call using third-party call control, an
application only has to invoke a single MakeCall method, which causes one endpoint to
call another. It is somewhat inexact, but you can think of the model of third-party call
control as a graph in which endpoints are nodes and calls are edges. The methods of
the API reconfigure the graph by adding, deleting, or moving edges.

Applications using Device and Media Control require the end-point used in the
application to be registered through AE Services. Registration of an end-point
associated with the Device, Media and Call Control API requires either a DMCC_DMC
license from WebLM (preferred) or an IP_API_A license from Communication Manager.

Applications using Call Control Services do not need to register devices, and thus do not
consume DMCC_DMC nor IP_API_A licenses; however, they do need a TSAPI or
UNIFIED_CC_DESKTOP license in order to use the Call Control service.

Note:
It is important to consider license consumption when deciding which style
of call control to use. If your application uses Device and Media control for
other reasons than controlling calls (for example, to record media or to
push feature buttons on a telephone) then you may want to consider
using first-party call control in order to not consume an additional license.
If, on the other hand, your application is primarily concerned with call
control, consider using Call Control Services as its higher level operations
and events are often easier to use.

Release 7.0.0
40 02-602658
Issue 1
Devices
In the context of this API, a device refers to a software instantiation of a phone or dial
string that is registered on Communication Manager. Such a device is also referred to as
a softphone. A device has physical and logical elements.

Physical Elements
The physical element of a device encompasses the set of attributes, features, and
services that have any association with physical components of the device that make up
the user interface of the device. Physical elements can be manipulated, such as pushing
buttons or going offhook, or they can be observed, such as observing the ringer or
whether a lamp is lit. The physical elements of a device include:
• Buttons
• Hookswitch
• Display
• Lamps
• Message waiting indicator
• Ringer

This API supports all of these physical elements.

Logical Elements
A logical element is the part of a device that is used to manage and interact with calls at
a device. This element represents the media stream channels and associated call
handling facilities that are used by the device when involved in a call. The logical
elements that this API supports are:
• DTMF tones coming into the device
• Media stream coming into and out of the device
• Do Not Disturb
• Call Forwarding

Calls
Calls are made from and received by a device. CSTA performs most telephony services
against a connection that identifies a particular call.

Service Requests
In this API an application requests services of the AE Services server. Examples of a
request are “give me a device identifier”, “press a button”, “give me information about a
lamp’s status”, or “notify me when a tone comes into the device”.
Release 7.0.0
41 02-602658
Issue 1
Each request is processed by the AE Services server. The server may complete a
request synchronously in one logical step or it may take additional steps to pass the
request to Communication Manager and handle the response(s) before responding
asynchronously to the application with the request’s results in an event or negative
acknowledgement.

To make a request, the application must invoke the appropriate .NET class method.
Once the method is invoked, the .NET API will construct the required message and send
the request to the AE Services server.

Every time you request the API to do something (for example, push a button) and that
request results in a message being sent to the server, you will immediately get an
InvokeID back. The InvokeID is the message number that is sent to the server as
part of the request and returned as part of the response which may be useful in
debugging over on the server side.

Service Responses
Each service request is acknowledged with a service response (positive
acknowledgement). Some service requests, particularly those that request information,
are completed in a single logical step, thus the results of the request are reported in the
service response (single-step requests follow CSTA’s atomic model). Other service
requests, particularly those that require the AE Services server to pass on a request to
Communication Manager, take multiple steps to complete. (These follow CSTA’s multi-
step model.) Responses to multi-step requests merely indicate that the request was
received and is being processed. In some cases, response data values may indicate an
error in the request or in the processing of a single-step request.

When the request has been acted upon, the application will receive an asynchronous
message from the .NET API informing the application of the results of the request. In
order to get this message your application must have a registered Response Handler
(delegate) associated with the service request. You will see how to do this under
Learning from sample code on page 46.

Events
Events are asynchronous occurrences on a device that an application can choose to
listen for and respond to. Examples of events are the DisplayUpdatedEvent, which
indicates that the device’s display has changed, or TerminalUnregisteredEvent,
which indicates that the device has been unregistered by Communication Manager.

An application indicates its desire to be notified of events by using the Monitor Start
method on the various .NET API service classes. Once a monitor is established, the AE
Services server notifies the application of relevant activity by sending messages called
event reports, or simply events.

Note:

Release 7.0.0
42 02-602658
Issue 1
 Once you receive an event, release the event thread immediately and
continue to do event processing on a different thread.

Negative acknowledgements
The AE Services server may respond to a service request with a negative
acknowledgement. A negative acknowledgement indicates that the service request has
failed. CSTA error categories are used to categorize errors into a hierarchy of error
return values. If an error is encountered, the details of the error will be in the "error"
string attribute of the appropriate response event.

Call Recording
Call recording provides the ability to record phone calls by employing the DMCC
Registration Services (see the “Registering Devices” and optionally see the “Recording
and Playing Voice Media” section in Chapter 3). If the client recording application
chooses not to employ the DMCC Voice Unit Services, then the application is
responsible for directing the RTP stream to a suitable recording application capable of
handling the media.
Note:
The Call Recording feature is supported for calls that are handled by DCP, H.323
and SIP endpoints, or by a mobile device.
The available methods for recording phone calls, via AE Services, include the following:
• Service observing method
A DMCC service client recording application registers as a Communication
Manager Service Observing extension in independent (or dependent) mode.
When a call is accepted by the user the Service Observer is added to the call.
• Single step conference method
A DMCC service client recording application registers as a standard
Communication Manager extension in independent (or dependent) mode. A
JTAPI, TSAPI or DMCC client application can monitor the user’s extension and,
when a call is accepted by the user, it conferences the recording client extension
into the call.
• Multiple registrations method
A DMCC service client recording application registers as the same extension
(either in dependent or independent mode) as that of the user who is taking the
calls. Since the incoming media in all of the extension’s RTP streams is the same
as for the main registrant (i.e. the user), the client application receives the same
RTP as the user, and can record the RTP. The DMCC service call recording
client is also able to register and connect after the user is already on the call.
Note:
Communication Manger does not play any warning tones into the call
while recording is in progress. It is up to the customer to warn the calling
parties via an announcement.
Release 7.0.0
43 02-602658
Issue 1
 Note:
When the extension of the user taking the call is associated with a SIP
endpoint, the DMCC service client application must register in
Independent mode.
• Cell phone recording
AE Services 6.2 introduced the ability to record calls originating or terminating at
a cell phone. This feature combines the AE Services Multiple Registrations
method with the Avaya EC500 or the Avaya One-X Mobile (OPTIM) applications.
The DMCC service client application is able to connect to, and record, calls:
o answered either at the desk set or at the mobile device
o answered at the desk set and then extended to the mobile device
o answered at the mobile device and then retrieved at the desk set
Note:
For mobile calls and SIP endpoint calls, the Cell Phone Recording feature
does not use the call control aspect of the Multiple Registration feature.
Also, the Cell Phone Recording feature does not increase the number of
parties on a call.

Recording warning tone

Beginning with AE Services 6.3 and Communication Manager 6.3, the DMCC client
application has the ability to request Communication Manager to insert a tone into the
audio stream of the parties in a call. This tone can be used to indicate that the audio
stream is being recorded using either the Single Step Conferencing method or the
Multiple Registrations method. The tone that is played is inserted by Communication
Manager and is identical to that already used by the Service Observing feature. See
“Chapter 3 - Playing a recording warning tone” for more information.

Signaling Encryption
AE Services offers the ability to encrypt the signaling channel between the AE Services
server and Communication Manager. However, the option to encrypt this link is not
under the direct control of your application. Instead, it is an option that is provisioned on
Communication Manager, via the “set network-region” page. See the "Setting up a
network region for Device and Media Control" subsection of the "Administering
Communication Manager for AE Services" chapter of the Avaya Aura® Application
Enablement Services Administration and Maintenance Guide.

The encryption of the signaling link is automatically negotiated between the AE Services
server and Communication Manager during the device registration, and the resultant
encryption used is dependent on the options set for the network region. The following
encryption types are supported:
• Challenge
• Pin-Eke
• H323TLS
Release 7.0.0
44 02-602658
Issue 1
 Note:
The H323TLS security profile option is only available for use with
Communication Manager 6.3.6, or later, running in Secure Mode with
FIPS. In this case, the AE Services Management Console screen,
“Communication Manager Interface” > “Switch Connections” > “Add/Edit
Connection”, must have the options “Secure H323 Connection” and
“Provide AE Services certificate to switch” check-boxes checked

When registering the device, the negotiated signaling encryption type is included as a
parameter in the RegisterTerminalResponse message.

Media Encryption
You have the ability to encrypt the RTP (media) stream between the application and the
other endpoint of the call.

The option to encrypt the RTP stream is provisioned on the Communication Manager via
the “change ip-codec-set” page. See the "Creating the Device and Media Control codec
set" subsection of the "Administering Communication Manager for AE Services" chapter
of the Avaya Aura® Application Enablement Services Administration and Maintenance
Guide. However, in this case, the application does have some (albeit limited) control
over the type of encryption used. The media encryption will be one of the following
types:
• Advanced Encryption Scheme (AES)
• SRTP encryption schemes (multiple options)
• no media encryption

When registering the device, the application may specify which media encryption
schemes that it supports. For more details see Choosing the media encryption on page
78.

The list of application-supported media encryption schemes will be matched to the list of
encryption schemes provisioned on Communication Manager’s “change ip-codec-set”
page for the device’s codec set. Communication Manager will pick an encryption
scheme that is common to both lists, if possible.

Note:
The encryption scheme and encryption keys (if any) chosen by
Communication Manager will be indicated in the MediaStartEvent
message. See MediaStartEvent Handling on page 140.

Release 7.0.0
45 02-602658
Issue 1
Accessing the client API reference documentation
You may need to reference the .NET Programmer’s Reference provided with this API. It
is available on the Avaya Support site (www.avaya.com/support ) as both a viewable
HTML document and a downloadable zip file.

This html documentation will also ship with the SDK. This documentation describes all of
the interfaces and their parameters. In addition, Visual Studio will provide help with the
parameters as you are writing the code.

Using the Device, Media and Call Control Dashboard

The Device, Media and Call Control .NET SDK ships with a "Dashboard" tool, that is
very useful for developers who are just learning about the API and its capabilities. The
Dashboard tool documents all of the capabilities of the API and provides the ability to get
detailed help about every interface. The Dashboard tool can greatly reduce the learning
curve by allowing you the ability to easily try out all of the capabilities of the .NET SDK
without having to write any code.

For information on getting started with using the Dashboard tool, see The Dashboard
tool on page 48.

Learning from sample code

The SDK ships with many code snippets which can be imported directly into Visual
Studio. These code snippets are available to provide sample code for virtually every
interface into the SDK and also provide an example of handling all of the events.

To import the code snippets into Visual Studio:

1. click on Tools
2. click on Code Snippets Manager
3. select you language (Visual C# or Visual basic)
4. select Add
5. Browse to the Method and Events Folder (provided by the SDK)
6. select Open
7. select Ok

These code snippets are now available for use in your applications. To utilize these in
your code, right click in your source code and select Insert Snippet. You may then
specify which snippet to insert into your code.

Another key learning tool is the set of sample applications that are provided with this
API. These sample applications are located in the SDK in the following directories:

Release 7.0.0
46 02-602658
Issue 1
dmcc-dotnet-sdk/Examples and dmcc-dotnet-sdk/JScript. Additional
information pertaining to setup and configuration of the sample applications can be
obtained from the ReadMe.txt file in the SDK under the directory dmcc-dotnet-sdk.

Table 18: Sample code

Application Language written File path names under Description
or Class in dmcc-dotnet-sdk/

Simple C# Examples/C# Simple This application provides a

Record Record simple recording capability.
It allows you to record
conversation for a given
extension. You may record
the calls either on the
server or on your PC.
Simple Visual Basic Examples/VB Simple This application is identical
RecordVB Record to Simple Record except it
is written in Visual Basic.
Soft phone in HTML and JScript Sample web page is in: This is an HTML page
a browser JScript/softphone which demonstrates a
The html document name simple softphone which
is: runs in a browser. The
IeSoftphone.html softphone can run in
telecommuter mode or in
no media mode.
Dashboard in HTML and JScript JScript\dashboard This is an HTML page
a Browser which provides basic
dashboard capabilities.

Release 7.0.0
47 02-602658
Issue 1
Chapter 3: Writing a client application
This chapter describes how to write an application using the Application Enablement
Services.

You will need to understand:

• what features of Device, Media and Call Control you will need for your application
• what capabilities Device, Media and Call Control provides.

The .NET SDK ships with a tool that will assist you in both aspects.

The Dashboard tool

The 7.0 SDK ships with an updated version of the Dashboard. All the new 7.0
capabilities are supported in the Dashboard. The Dashboard has a checkbox which will
highlight all the new and modified features in 7.0. This will make it very easy to see what
has been added for this release.

The name of this tool is Dashboard.exe and it is located in the dmcc-dotnet-sdk

folder. The Dashboard tool allows you to easily try out all the capabilities of the .NET
SDK without having to write any code. Once you have determined what you need out of
Device, Media and Call Control it will not be difficult to implement in the code (assuming
you have a working knowledge of Visual Studio).

Note:
The Dashboard is a tool that is constantly evolving and being improved.
The following screenshots may not match the Dashboard exactly but
should be close enough to give you an idea of its capabilities.

The information in this chapter assumes a developer has zero knowledge of Device,
Media and Call Control.

We will outline the steps necessary to write a simple application. In general, most, if not
all, applications will need to do the following:
• Start a session with the AE Services server
• Get one or more devices that you are interested in monitoring.
• Register those Devices to the Communication Manager.
• Listen for events that you are interested in (e.g., lamp updates).
• Process those events.

For our sample application, we will assume the developer wants to do the following:
• monitor all incoming calls for extension 5382834
• log the duration of the calls

The first thing you must do is start up the Dashboard application.

Release 7.0.0
48 02-602658
Issue 1
The system displays following:

Notice that most of the buttons are inactive. The only buttons that are active are the
ones that are valid given the current state of the Dashboard. In this case, the only button
that is active is the Start Application Session button.

Receiving Negative Responses

Each service request initiated by the client application may generate a negative
response from the AE Services server. Therefore your application must be prepared to
handle these negative resposes.

It is recommended that the application, log all negative responses since this will be an
important source of information for debugging the application. Look at the server side
logs for more information about what happened. The logs will contain helpful information
that you may need to provide to DevConnect.

For more information on negative acknowledgements please see section 9.2.2 and 9.3
in the ECMA-269: Services for Computer Supported Telecommunications Applications
(CSTA) Phase III found in the Publications section of the ECMA web site
(http://www.ecma-international.org/).

Release 7.0.0
49 02-602658
Issue 1
The CSTA specification provides a long list of standard error messages that a request
could return. This list of standard CSTA errors is somewhat limiting in that it does not
cover all the possible errors. The latest version of the CSTA specification extended the
error message capability by allowing the creation of vendor specific errors. To utilize this
new capability an XSD, avaya-error.xsd, was created. This XSD specifies an
enumeration of all the extended error codes. Private error codes were added to convert
TSAPI ACS Universal errors. These errors will be sent to the application instead of the
generic CSTAErrorCode ‘unspecified’ when applicable. Appendix I: ACS Universal Error
Codes contains a table of the errors that were added and their meaning. The use of an
XSD will make it easy for any client (Java, C#, etc.) to have a programmatic way of
knowing what AE Services extended error codes are possible.

Session Management
An application session must be established between your application and the AE
Services server for the purpose of exchanging application messages. It is required that
an application session be established before application messages can be exchanged.
This allows you to recover and reestablish an existing session on a new connection. The
application session is established by the ServiceProvider class.

The ServiceProvider class is the starting point for all applications to:
• indicate which AE Services server to connect to
• identify the application
• establish an application session
• gain access to all API services

Start Application Session

If you hold the mouse over the Start Application Session button several of the input fields
will turn a light blue color.

Release 7.0.0
50 02-602658
Issue 1
The input fields that turned light blue in this case are the parameters that are required by
the Start Application Session method.

Note:
We also see a tool tip that comes up when the mouse is held over a
button or an input field. The tool tip provides additional information about
that button or the input field.

We now know exactly what information is needed to start an Application Session. The
required information is:
• The IP Address (or DNS name) to the AE Services server
• The port that you want to connect to, typically 4721 or 4722 (4722 is the default
port for encrypted information)
Note:
If you want to use the non-secure port, first you must enable the
unencrypted port (4721) on the AE Services server. Using a browser, go
to the AE Services Management Console web-pages and click on
“Networking”, then “Ports”. On the “Ports” web-page, click to enable the
“Unencrypted Port”, then click “Apply Changes”. Also, note the directive to
restart the AE Services server.
• You need to indicate if this port is a secure socket (usually checked if port 4722
is used)
• You need to indicate if you want to allow a certificate name mismatch (only
necessary if a secure socket is used)
• You need to have a valid login name and password on the DMCC server
Release 7.0.0
51 02-602658
Issue 1
 • You need to specify a name for the session
• You need to specify what protocol version you want to communicate to the
DMCC server on.
Note:
The .NET Service Provider class provides a set of constants that can be
used to set the Protocol Version. In the .NET Reference Documentation,
see ServiceProvider.DmccProtocolVersion.
Note:
Each release adds functionality to the previous releases. If you wish to
use an older specific release version protocol rather than the default
version for the SDK, you can specify the appropriate protocol version per
the release value. AE Services 3.x, 4.x and 5.x applications are expected
to run against the current release of AE Services as long as the protocol
version associated with the SDK is specified correctly. Appendix A in the
Avaya Aura® Application Enablement Services Overview document
contains more information on API and client compatibility.
• You need to specify how long the session (in seconds) should last if no keep
alives are returned. We recommend that you do not override the default of 180
seconds. The minimum value is 30 seconds, and the maximum value is 7200
seconds (2 hours).
• You need to specify (in seconds) how long the session is to be kept active in the
server AFTER the server tears the connection down due to no keep alives being
sent. This will allow you to attempt to reconnect the session if you are notified
that the session was terminated by the server. (60 is a reasonable value for this
field) The minimum value is 0 seconds, and the maximum value is 7200 seconds
(2 hours).

Reset Application Session Timer

The API will send a StartApplicationSession request to the server containing the
Cleanup Delay, and the Application Session Duration. The Application Session Duration
is the maximum amount of time that the server will wait for a timer reset, before moving
the session to the inactive state. This timer is reset when the server receives a
ResetApplicationSessionTimer message from the application. The .NET API
automatically handles sending these keepalive messages to the server on the behalf of
the application at intervals that are approximately 1/3 the session duration. This allows
for up to 2 messages to be lost or delayed before the application session is put into an
inactive mode.

Note:
The AE Services server only allows session durations between 30
seconds and 2 hours. If you request a duration shorter than 30 seconds
or longer than 2 hours, the duration will automatically be set to the
negotationed value specified in the ResetApplicationSessionTimerPos
response message of either 30 seconds or 2 hours.

If the server session duration timer expires due to not having received the
ResetApplicationSessionTimer message, it will:
Release 7.0.0
52 02-602658
Issue 1
 1. Close the socket
2. Mark the session as inactive
3. Start the cleanup timer using the time specified in the Cleanup Delay.

If the application then attempts to send any messages, it will receive a Negative
Acknowledgement response. If this happens, the application should then take recovery
actions as specified in the recovery section (Chapter 4: Recovery).

Exercise: Starting the Application Session

Input the information into the Dashboard and push the Start Application Session
button.

The following screen shot shows the result:

A session has been created producing the following:

• The Session Id is in the Session Id textbox area

• All of the outgoing and incoming XML messages which are sent/received to the
AE Services server are displayed
• The results of your request are in the Events box
• If an error has occurred you will see the details in the Events area or possibly in
the Exceptions, Errors, and Automated Testing Comments textbox.

Release 7.0.0
53 02-602658
Issue 1
You now have a valid session established. The server may respond with a
StartApplicationSessionNegResponse with an error code to define why the server failed
to start the session. Your application may also receive a special negative response
message that is associated with a failure while attempting to recover a session. Please
see the Chapter 4: Recovery for details.

The next thing you need to do is to specify the session characteristics and obtain a
Device ID.

SessionCharacteristics
Since the 5.2 release of AE Services, DMCC applications are able to specify several
“Session Characteristics” that will alter the way their application interfaces with DMCC.
The SessionCharacteristics are optional and when they are not specified, previous
behaviors are preserved.

At present, there are no restrictions on the number of times that the Session
Characteristics may be changed for a given session. However, changing the
characteristics in the middle of a session may have unforeseen issues involving possible
Call Control services or events and their delivery to the client. Thus, it is recommended
that the Session Characteristics are set up immediately after the session has been
established. Thereafter, the application should exercise caution in setting new
characteristics for the session.

The following are the session characteristics that can be specified.

DeviceID Type
The two Device ID Types that can be specified are “DMCC” and “Tel URI”.

The DMCC Device ID type is the type that has been supported in previous releases of
DMCC and is the default if no DeviceID type is specified.

The “Tel URI” type allows an application to interact with DMCC using E.164 numbers
rather than switch-specific extensions and dial strings. DMCC leverages the Dial Plan
provisioning of the AE Services Management Console pages in order to work in this
mode.

There are several benefits to using Tel URI mode as follows:

• Applications can look up telephone numbers in an enterprise directory and

provide those telephone numbers to DMCC without knowledge or concern of the
Communication Manager dial plan.
• The above benefit is extended to numbers external to Communication Manager.
The application would not have to be aware of the ARS code to denote an
external number, nor would it have to be aware of the international dialing code.
Release 7.0.0
54 02-602658
Issue 1
 • The application does not have to be aware of a switchname for the given device.
Instead, DMCC will attempt to discover the appropriate Communication Manager
instance on receipt of a Monitor Start or Snapshot Device request.

While this mode can be extremely useful there are several important limitations to be
considered prior to using Tel URI mode.

• Only Monitoring Services, Call Control Services, Snapshot Services and Logical
Device Feature Services may be used when working in this mode.
• If Monitoring Services is used in Tel URI mode, the application must take care to
only subscribe to Call Control, Logical Device Feature and Endpoint Registration
events.
• The first request issued by the application must be a Monitor Start or Snapshot
Device request as those requests are used to associate the Tel URI with a
particular administered Switch.
• The Dial Plan must have been provisioned in the AE Services Management
Console pages for the Communication Manager(s) of interest.
• A given AE Services instance may only serve users in a single country, even if
the Communication Manager is a multi-national deployment. This is because the
dial plan rules do not take the calling number into account when determining how
to convert a called number.

For more details on how to provision Dial Plan rules, please see the section on DialPlan
Administration in the “Avaya Aura® Application Enablement Services Implementation
Guide for Microsoft Office Live Communications Server 2005 or Microsoft Office
Communications Server 2007”

Event Filter Mode

An Event Filtering Mode of “None” corresponds to the “regular” DMCC behavior
applications are used to receiving and it is the default if no Event Filter mode is
specified.
Note:
Filters specified in a Monitor Start request will continue to be applied
even if the default Event Filtering Mode of “None” is requested.

“Desktop Call Control” event filtering may be leveraged by applications that are directly
representing call state to end-users. In this mode, DMCC will filter out events that would
otherwise lead to confusing call states for the user. The following events filtering is
applied in this mode:

• Delivered and Established events that would reveal the presence of a silent
observer. When Single Step Conference is used to add a participant to a call, an
application can optionally specify that the participant be added in “listen-only”
mode. This is generally used to add automata such as virtual call recording
extensions. A participant that has been added using the Communication
Manager Service Observing feature would also be a silent participant. It is

Release 7.0.0
55 02-602658
Issue 1
 generally beneficial to hide the presence of such silent observers from an end-
user application that otherwise shows all parties on the call.
• Established events that indicate that a call has been answered at a different
device than the one being monitored. This generally occurs in a situation where
one user has a bridged appearance of another. In that scenario, both devices
alert and the call can be answered at either device. In general, an end-user
application showing call state on the device that did not answer would then want
to show that the call has been cleared. Consequently, DMCC will convert such
an Established event to a Connection Cleared event prior to sending the event to
the application.
• Bridged Appearance Alert provisioning is applied. This provisioning allows the
administrator to specify whether applications monitoring a station with bridged
appearances of another station should receive Delivered events that would
indicate that a bridged appearance is alerting. For example, consider a case
where an assistant has bridged appearances of several executives. In some
deployments, it may not be desirable for that assistant’s call control application to
indicate that there is an incoming call for one of these bridged appearances. In
other deployments, it may be desirable for the application to alert in this scenario.
The Bridged Appearance Alert provisioning allows the administrator to specify
which behavior is desired for their particular deployment, and even allows per-
user provisioning.

Device Identifiers (DeviceID)

AE Services support two forms of device identifiers, first party device identifiers and
third party device identifiers. First party device identifiers are associated with the Phone
and Media Services. Third party device identifiers are associated with the Third Party
Call Call Control and Call Information services. Third party device identifiers have been
supported since the 3.1 release of AE Services.
Note:
A Device ID is required for each Communication Manager phone or dial string
that your application needs to control.
A Device ID can be controlled by more than one session based on either of the
following:
• Device ID Instances
AE Services allows you to create up to three instances of a device identifier. For
more information, see “Multiple DeviceIDs” and “Device ID Instances”.
• Controllable By Other Sessions
AE Services allows each DeviceID to be controlled by multiple client sessions
that belong to the same user. Each session will then invoke the same requests.
For more information, see “Controllable By Other Sessions”.
In the case of an application failure, one session can then takeover all of the devices on
another session, preserving the device registrations and monitor states. The new
Release 7.0.0
56 02-602658
Issue 1
session will receive information enabling them to process events without starting new
monitors. See Transfer Monitor Objects for more information.
First party device identifiers have the following properties:
• Are not exclusive to a session
• Can only be obtained from Device Services
• Can be used to register a virtual softphone and perform device and media
control
• Can also be used for third party call control operations, but only if they
contain a Communication Manager connection name
• Must be released to be cleaned up
Third party device identifiers have the following properties:
• Are not exclusive to session
• Can be obtained from Device Services or may be returned by Call Control
Services or Snapshot Services
• Can only be used with Call Control Services and Snapshot Services
• Need not be released

Getting Device Identifiers

There are several valid ways to get a first party device ID. It is recommended that the
application take advantage of the H.323 Gatekeeper List feature so that both first party
device IDs and third party device IDs are acquired in the same way by giving a switch
name and an extension number. This feature requires the administrator to administer
through the AE Services Management Console web pages a list of IP addresses that
can be used for H.323 registrations. See the "Administering Switch Connections"
section of the "AE Services OAM Administration and CTI OAM Admin" chapter of the
Avaya Aura® Application Enablement Services Administration and Maintenance Guide.

If an application is not using Call Information Services or the Third Party Call Control
Services, it is also valid to include only a switchIPInterface and dial string in the
getDeviceID request, and thereby not administer the H.323 Gatekeeper list.

Note:
The DeviceID format is subject to change in future releases. Your application
should not be parsing these ID’s, but rather should be using them as keys in their
requests.

Release 7.0.0
57 02-602658
Issue 1
Comparing Device Identifiers
Depending on how you obtained the DeviceIDs, there may be small formatting
differences between two DeviceIDs that you might think should be equal. A DeviceID
comprises of four main parts:
1. the phone extension – normally consists of 4-13 digits .
2. the name of the switch associated with the extension – this should match one of
the “Switch Connections” provisioned via the AE Services Management Console
web pages.
3. the IP address of the CLAN or Processor Ethernet interface used to connect the
phone to the switch (optional)
4. the instance of the phone extension – ranges from 0 -2 (default = 0)

Parts 1, 3 & 4 are comprised of numeric digits and normally pose no comparison
problems. However, part 2 (switchname) consists of alphanumeric characters and can
contain either upper-case or lower-case alphabetic letters. Thus, for example, it is
possible to obtain the DeviceIDs:

deviceId1 = “12345:myswitch:192.168.1.1:0”;
deviceId2 = “12345:MYSWITCH:192.168.1.1:0”;

where the first DeviceID may have been obtained from a “getDeviceID()” request, while
the second DeviceID may have been obtained from an event. Always perform case-
insensistive string comparisons when comparing DeviceIDs that contain a switchName.

As a way to assist the developer, the Device class contains two helper methods,
• DeviceIDComparer(String,String)
Performs a case insensitive string comparison of 2 DeviceIDs.
• ExtensionComparer(String,String)
Performs a case insensitive string comparison of the extension and switch name
portion of 2 DeviceIDs.

Populating the Device ID Switch Name and Switch IP Interface fields

For first-party device ID’s there are several ways to populate the switchName and/or
switch IP interface fields:

• Your application can specify a switchName, a switchIPInterface, and a dial

string when getting a device ID. In this case, administration of the H.323
Gatekeeper list for the switch connection (transport link) is not required.
• Your application can get a switchName by using the Gatekeeper List feature of
the AE Services server. Your application would specify just an extension and
switchIPInterface as in previous releases of the API. If this is done, it is required
that you administer an H.323 Gatekeeper list for the Switch Connection. The AE
Services server, upon receiving the GetDeviceID request, will go to its

Release 7.0.0
58 02-602658
Issue 1
 administration database, and will resolve the given switchIPInterface to a
switchName, then populate this value in the DeviceID.
• The AE Services server also offers a feature which will use a round-robin
algorithm to distribute softphones to a list of H.323 Gatekeepers (i.e. to
automatically populate the switchIPInterface). If using this feature, the
application need only know a symbolic name for the switch (i.e. switchName),
rather than maintaining a list of Gatekeepers with which it wishes to register. To
take advantage of this feature, the list of H.323 Gatekeepers must be
administered in the AE Services Management Console for the given Switch
Connection.
o Prior to AE Services 6.1, when getting a DeviceID, the application would
specify only a switchName and extension. Upon receiving the
“GetDeviceID” request, the switch would pick the next H.323
Gatekeeper from the list, and return it, as part of the DeviceID. Later,
when the application attempts to register the device, it would register
with that gatekeeper. Unfortunately, if the gatekeeper was out-of-service
when the device registration occurred, it was necessary for the
application to release the DeviceID and get another one before the
registration could be re-attempted.
o For AE Services 6.1 and later, if only the switchName and extension
are specified in the “GetDeviceID” request, the choice of H.323
Gatekeeper is delayed until the device is actually being registered. In
this case, the DeviceID that is returned to the application (in response to
GetDeviceID) will have “0.0.0.0” as the switchIPInterface portion of
the DeviceID. This designation is merely meant to indicate that the
H.323 Gatekeeper for registration has not yet been chosen. Delaying the
choice of gatekeeper until the device needs to be registered allows
greater flexibility for the application. Thus, if a gatekeeper is down or
out-of-service at the time of registration, then it will not be picked from
the list of gatekeepers. Instead, the out-of-service gatekeeper will be
skipped, and the next available in-service gatekeeper will be allocated
for the device registration. In this way, the need for the application to
invoke “ReleaseDeviceID” and re-invoke “GetDeviceID” (in order to pick
another gatekeeper) is avoided. Furthermore, the probability of picking
an out-of-service gatekeeper IP address is much reduced.

Note:
The H.323 gatekeeper being used for a given DeviceID can
actually change during the life of the registration. The most
common cause for this is a failover of the Communication
Manager to/from an ESS or LSP. If you need to know which
H.323 gatekeeper is currently being used for a given device
registration, then you can do one of the following:

• On the AE Services Management Console (OAM),

navigate to “Status” -> “Status and Control” -> “DMCC
Service Summary” and click on “Device Summary”. If the
DeviceID is registered, then the current H.323 gatekeeper
IP address is listed on the form.

Release 7.0.0
59 02-602658
Issue 1
 • From your application program, issue a
“GetRegistrationState” request for the device. If the
device is registered, then the response will include the
current H.323 gatekeeper IP address.

For third-party device ID’s:

• Your application must always specify a switchName, and an extension when

getting a device ID.
• There is no switchIPInterface for third-party device ID’s.

Note:
The switchName field is only required for Call Information Services, Third
Party Call Control Services, and Phone Registration Services. If an
application is not using one of these services, it is not required to
administer a Switch Connection and an H.323 Gatekeeper List, nor to
specify a switchName in the GetDeviceID request. In this case, any calls
with this DeviceID to Call Information Services or Third Party Call Control
Services will fail. Calls to Phone Registration Services may succeed, but
will require an IP_API_A license from Communication Manager.

Multiple DeviceIDs
In AE Services 4.1, the ability to register up to three instances of the same deviceID was
introduced. This ability allowed the client application to implement a rudimentary, client-
side, high-availability setup, which allowed the client to “control” the extension from a
secondary or tertiary DeviceID, if control of the primary DeviceID failed. The deviceID
was identified by the extension number and the Communication Manager to which it was
being registered (either by switch-name and/or by IP address of the CLAN).

Communication Manager allows up to three registrations against the same extension,

providing that only one registers in Main Dependency mode; the other two should
register in either Independent or Dependent Dependency modes (see Registration
modes, Dependency modes and Media modes).

Unfortunately, each instance of the deviceID needed to be registered from a different IP

endpoint, as determined by Communication Manager. In practice, this meant that each
instance of the deviceID needed to be registered through a different AE Services server.

Controllable By Other Sessions

For first-party device ID’s:

There are two ways to populate the controllableByOtherSessions field:

Release 7.0.0
60 02-602658
Issue 1
 • Your application can specify Boolean.FALSE which means that only one session
can control the DeviceID. The effect is the same as not setting the
controllableByOtherSessions parameter. This is for backward compatibility
with applications that use an earlier version of the Java SDK.
• Your application can specify Boolean.TRUE which means that more than one
session can control the DeviceID. It is recommended that user authorization be
enabled for device(s) that can be controlled by multiple sessions. There are
three different authorization policies offered and that are explained in the “User
Authorization Policies” section

Device ID Instances
Starting with Communication Manager 5.2 and AE Services 5.2, the need for multiple AE
Services servers in order to register multiple instances of the same device with the same
switch has been eliminated.

The deviceID has been expanded to include the device instance, as well as the
extension, switchname and Gatekeeper IP address. Thus, you can obtain up to three
instances of the same deviceID through just one AE Services server.

When you obtain a deviceID (using Device services getDeviceID()), if you do not specify
which device instance you require, the instance will automatically default to instance ‘0’;
otherwise, you may specify which of the three possible instances of the deviceID that
you require.

The three instances of deviceID that may be specified are:

• DeviceInstance.VALUE_0
• DeviceInstance.VALUE_1
• DeviceInstance.VALUE_2

Note:
The device instances can be used in any order – i.e. it is not necessary to get
instance ‘0’ before instance ‘1’, nor to get instance ‘1’ before instance ‘2’.

Getting Device State Information

The DMCC .NET request GetDeviceIdList is used by an application to obtain all the
DeviceIDs associated with a user’s session. The request can be based on a particular
session ID or all the sessions owned by the user making the request against the AE
Service server which receives the request. The available requests are
GetDeviceIdList(Object) and GetDeviceIdList(String, Object), see the .NET
Programmer’s Reference for additional information on these requests.

Release 7.0.0
61 02-602658
Issue 1
Since a user could have multiple DeviceID’s associated with a session, the results will
be returned to the application in a series of events. The application will need to register
for the appropriate SessionManagementEvents using the
SessionManagementStartMonitor request. In addition, the application will need to add
an OnGetDeviceIdListEvent delegate to allow the application to receive and process
the events. The event(s) the application will receive is the GetDeviceIdListEvent.

Note:
The specified requests, events, and delegates are defined in the ServiceProvider
class.

Exercise: Getting A Device ID

The Get Dev Id button is now available. If we hold the mouse over the Get Dev. Id
button we see what information we need to fill in.

Note:
This exercise is a continuation of the previous exercise.

Specifically we need:

• Extension
• Switch Name (or IP Address)
Release 7.0.0
62 02-602658
Issue 1
 • Do we want other sessions to also control this station
Fill in the required information and push the Get Dev. Id button:

We now have a Device ID:

1. The Device Id is in the Device ID textbox area
2. The results are in the Events box

Now that we have a Device ID, the next thing we need to do is detect that a user is on a
call. We have decided we want to monitor all phone events to see what is coming in. To
accomplish this we need to create a monitor for phone events.

Notification of Events
Your application can choose to be notified of asynchronous events that occur on a
device by implementing and registering a service delegate. Asynchronous events
include:

• Telephony events.
Examples of telephony events are when the lamp state has changed or a DTMF
tone has been detected.
• Asynchronous responses to service requests.

Release 7.0.0
63 02-602658
Issue 1
 For example, after requesting to register a device an event is received from the
AE Services server indicating whether the request succeeded or failed.
The .NET API uses what the .NET Framework call delegates to be notified of events.
Each of the .NET API classes contains a set of deletegates called EventHandlers and
ResponseHandlers that an application can implement and register with the API.

• EventHandlers are used to inform an application about unsolicited events that

are published by the AE Services server.
• ResponseHandlers are used to inform the application of soliciated events
(responses) to a request originally issued by the application to the AE Services
server.

For a complete list of the available handlers exposed by the .NET API, please see the
Avaya Aura® Application Enablement Services Device, Media and Call Control .NET
Programmer’s Reference.

Note:
The .NET Programmer’s Refeence is also available in the .NET SDK at
“dmcc-dotnet-sdk/Docs/html/index.htm”

In order to guarantee that events are not missed the event should be registered before
the device is registered. Your application should unregister all event monitors once they
are no longer needed.

This API will not block an application from registering multiple event monitors of the
same type (i.e. RegisterTerminalResponseHandler). In this scenario each registered
handler could perform a unique set of tasks.

Note:
It is a common mistake to inadvertently add the same handler
implementation multiple times. This is allowed, but may not be what your
application intends. Check your logic to be sure your code adds only the
number of handlers it intends. Programmatically, a list of monitors can be
retrieved from the server using the GetMonitorList request. Alternatively,
the event CrossRefID can be tested to verify that many identifiers do not
map to the same listener.

Register for Events

Each of the .NET API services contains a method called Start Monitor which is used to
register a monitor. A monitor id will be returned from the AE Services server which can
be used to modify or stop the associated monitor.

This will be performed from the Dashborad tool in the Registering for Events section.

Release 7.0.0
64 02-602658
Issue 1
Unregister for Events
Each of the .NET API services contains a method called Stop Monitor which is used to
unregister a monitor based on its monitor id.

For the Dashboard, select the appropriate monitor listedin the Monitor ID listbox and
click the Stop Monitor button.

Exercise: Registering for Events

You do this with the Event Registration area of the Dashboard. This is where you
register for the events you are interested in. The Event Registration area is divided into
logical tabs.

To monitor phone events, we will select the Phone tab.

Note:
This exercise is a continuation of the previous exercise.

We now see that we can monitor display updates, hookswitch updates, lamp mode
updates, ringer status updates, and get notified if the terminal is unregistered.

Since we are not sure which ones we want, we will monitor all phone events.
Release 7.0.0
65 02-602658
Issue 1
So we push the Start Phone Monitor button.

We have started a Phone Monitor and:

• the Phone Monitor is in the Monitor IDs area
• the results are in the Events box

Now that we have the monitor started, we need to register the terminal.

Registering Devices
The registering of devices with Communication Manager, in AE Services, is done
through Device and Media Control to monitor or control a device using first-party call
control. This tells Communication Manager which dependency mode you want (Main,
Dependent or Independent control of the device) and what kind of media mode you
want. Only devices that are softphone enabled on Communication Manager’s Station
form can be registered.

Note:
The registration dependency modes and media modes are described in
“Dependency Modes” and “Media Modes”. You will find information on the call
capacities your application can expect to be able to handle in the "Capacities for
calls in Device, Media and Call Control applications" section of the "Capacities

Release 7.0.0
66 02-602658
Issue 1
 for types of applications" chapter of the Avaya Aura® Application Enablement
Services Overview.

You must check the registration state of a device with a

Phone.GetRegistrationState request before sending a register request if it is
controlled by more than one clients session.

Note:
Registering a device with Communication Manager is only necessary for
Device and Media Control. This is not necessary for Call Control.

AE Services will verify that the user invoking any DeviceID based service request is
authorized to control that DeviceID. An error will be returned if an unauthorized user
attempts to control a device.

Communication Manager 5.0 and later allows up to three Device, Media and Call Control
station clients to register to one extension. This extension must be administered as a
DCP or Avaya H323 IP Softphone. If necessary, all three DMCC endpoints registered to
a common extension can be configured to be in 3 different “network regions”. All three
endpoints that are registering to an extension can request separate media streams.
Each DMCC endpoint registration must either:
• act through different AE Services servers, if they specify the same instance of the
deviceID (instance ‘0’ by default).
• act through one AE Services server, if they specify different instances of the
deviceID.

The first option provides a measure of high availability with standalone (not in a standard
High-Availability configuration) AE Services servers. For example, the client could
register the same endpoint through two different AE Services servers and have recorded
media flowing to both. The second option also provides the ability to record dual feeds
for recorded media, but provides High-Availability through the standard AE Services
paired-servers configuration.

Each media (RTP) stream is the summed stream of all the participants in the call. For
example, if an Agent using a physical phone with extension 1000, is talking to extension
1001 and extension 1002. And a DMCC endpoint is registered to extension 1000 as
Dependent in Client media mode, at the time of the call, the DMCC endpoint will receive
the summed talk streams of the Agent (at extension 1000) and extensions 1001 and
1002.

Note:
The DMCC endpoint registered in Dependent (or Independent mode when a
physical set is registered/present), is connected to the call in listen only mode.
Therefore no additional talk time slot is allocated for this DMCC endpoint. Also,
this DMCC endpoint does not count toward the number of participants that can
be in a conference call.

Registration is performed through the registerTerminal request of the Phone Class

found in the Avaya.ApplicationEnablement.DMCC.Phone namespace. In the

Release 7.0.0
67 02-602658
Issue 1
RegisterTerminal request you must at a minimum specify which device to register
and the password that is administered for the device on the Communication Manager
Station form. There are also a number of options to choose from. For more details on
setting up a RegisterTerminal request, see the .NET Programmer’s Reference.

The only registration-related event supported is the Phone class’s

OnTerminalUnregistered event. This event is sent if the AE Services server
automatically unregisters the device. The typical cause is when the network or
Communication Manager is unresponsive. The reason for unregistration is reflected in
the event’s cause code. Its value is one of the Registration Constants listed in Appendix
C: Constant Values.

If a device becomes automatically unregistered, it is up to the application to re-register.

Avaya recommends retrying every 30 seconds.

Some important decisions you will need to make when registering a device include:
• What registration dependency mode to choose
• What registration media mode to choose
• What codecs to choose
• What media encryption to choose

Note:
If your application needs to register many devices, we recommend you spread
out the registration of the devices. Register no more than 50 stations at one time
and wait until your application has received all of the responses before
attempting to register more stations.

Endpoint Registration Events

Endpoint Registration events were first introduced for AE Services 6.3 and
Communication Manager 6.3, and can be monitored just like any other DMCC
Registration Services event.

The main difference between Endpoint Registration events and the existing Registration
& Terminal events is that Endpoint Registration events can be monitored for any H.323
or SIP endpoint that can be registered to Communication Manager. The endpoints do
not have to be registered using DMCC, as is the case for the existing Registration &
Terminal events. For Endpoint Registration events, the endpoints can be registered to
Communication Manager via any current means, provided they use the H.323 or SIP
protocol for registering.

Endpoint Registration events can be monitored by a DMCC application in the same

manner that other DMCC events are monitored – by using DMCC Monitoring services.

Similarly to the existing Registration events, Endpoint Registration events are monitored
on a "per device" basis. Whenever the monitored endpoint registers or unregisters
against the Communication Manager switch, the appropriate EndpointRegistered or

Release 7.0.0
68 02-602658
Issue 1
EndpointUnregistered event will be called, enabling the DMCC application to handle the
event and the data contained within it.

The EndpointRegistered event contains the following data:

1. Monitored DeviceID. The Monitored DeviceID is the DeviceID specified in the

original StartMonitor request. This DeviceID may be different from the Endpoint
Device ID and it may be any instance of a device since up to 3 H.323 endpoints
and 1 SIP endpoint can be registered to the same extension number.
2. Endpoint DeviceID. The Endpoint DeviceID is the DeviceID, as known by CM, of
the endpoint being registered or unregistered. This DeviceID may be different
from the Monitored Device ID and it may be any instance of a device since up to
3 H.323 endpoints and 1 SIP endpoint can be registered to the same extension
number.
3. IP address of the endpoint. In the case where an endpoint was registered via
DMCC, this will be the IP address of the AE Services server.
4. MAC address of the endpoint. In the case where an endpoint was registered via
DMCC, the MAC address wil be all zeros.
5. Product Type – the product type as provisioned in Communication Manager.
6. Network Region – the network region for the extension as provisioned in
Communication Manager.
7. Dependency Mode – the dependency mode used during registration: main,
dependent or independent.
8. Media Mode – the media mode used during registration: client, telecommuter or
none. Note that DMCC’s “server media” mode is considered the same as “client
media” by the Communication Manager.
9. Unicode Script – the Unicode script options as provisioned in Communication
Manager.
10. Set Type – the model of the phone as provisioned in Communication Manager.
11. Signaling Protocol Type – the protocol used to register: H.323 or unknown.
12. Service State – the overall service state of the station after the endpoint has
registered. This will normally be “in-service”.

The EndpointUnregistered event contains the following data:

1. Monitored DeviceID. The Monitored DeviceID is the DeviceID specified in the

original StartMonitor request. This DeviceID may be different from the Endpoint
Device ID and it may be any instance of a device since up to 3 endpoints can be
registered to the same extension number.
2. Endpoint DeviceID. The Endpoint DeviceID is the DeviceID, as known by CM, of
the endpoint being registered or unregistered. This DeviceID may be different
from the Monitored Device ID and it may be any instance of a device since up to
3 endpoints can be registered to the same extension number.
3. IP address of the endpoint. In the case where an endpoint was registered via
DMCC, this will be the IP address of the AE Services server.
4. Dependency Mode – the dependency mode used during registration: main,
dependent or independent.
5. Reason – a string value indicating the reason for the unregistration.

Release 7.0.0
69 02-602658
Issue 1
 6. Code – an integer value indicating the reason for the unregistration.
7. Set Type – the model of the phone as provisioned in Communication Manager.
8. Service State – the overall service state of the station after the endpoint has
unregistered. Note that the overall service state may still be “in-service” if there
are other endpoints registered to the same extension.

Endpoint Registration Information

Not only can the DMCC application be notified whenever an endpoint registers or
unregisters against the Communication Manager switch, it can also send a request to
get the current registration state and endpoint data associated with the extension. This
request may be sent at any time after the DMCC client has acquired the DeviceID. Thus,
the device may, or may not, be registered against Communication Manager at the time
of the request for Endpoint Registration Information.

The EndpointRegistrationInfo request should be used for queries of physical stations,

not for extensions associated with agent IDs. Note that it will return an error if a logical
agent extension number is used as the deviceID for the query.

If the specified device has one or more endpoints registered against Communication
Manager for that extension, then the response will contain a set of data for each of the
registered endpoints. The set of data for each registered endpoint is identical to the data
outlined in the Endpoint RegisteredEvent. However, if there are no endpoints registered
against Communication Manager for the specified device, then the response to the
Endpoint Registration Information request will be empty.

Controllable telephone types

For Device and Media Control, any DCP or H323 IP Softphone that can be enabled for
IP Softphone can be controlled by the AE Services server. However, the device type
administered on Communication Manager must be one that is equipped with a speaker-
phone. Devices that are not speaker-phone equipped (e.g. CallMaster sets) are not
supported at this time. In the case of DCP and H323 IP softphones, it is not necessary to
have a physical set present. Device, Media and Call Control endpoints can register in
any registration dependency mode. An endpoint registered in Main mode is usually
associated with a physical set, but a DMCC endpoint can also register as Main (see
“Dependency Modes”).

Note:
For details on how to softphone enable a device, see the appropriate Avaya
Aura® Application Enablement Services Installation and Upgrade Guide for the
offer you have purchased (VMware or Software Only).

Device and Media Control support of SIP endpoints is extremely limited. Of course,
DMCC can register a virtual H.323 station which can then be used to record calls that
involve SIP stations. However, you cannot register an independent or dependent DMCC

Release 7.0.0
70 02-602658
Issue 1
station against a SIP endpoint, so you cannot exercise device monitoring/control over it.
Note that, DMCC can register an H.323 station in main mode against an extension that
is provisioned as a SIP set. The use case here would be that the user has a SIP station
on their desk but also wants to use a DMCC app to register in telecommuter mode when
they’re at home. However, in this case, a special Feature Named Extension (FNE) has
to be dialed to tell CM whether ASAI should be controlling / monitoring the H.323 set or
the SIP set at any given time."

For DMCC Call Control Services, any Communication Manager supported endpoint can
be controlled by the AE Services server. This includes some of the available SIP
endpoints, as well as DCP and H.323 IP endpoints.

Note:
You cannot choose Independent or Dependent dependency mode with SIP
endpoints, so you cannot exercise device monitoring/control over them.

For more information on the types of endpoints supported for Call Control Services, see
the AE Services TSAPI documentation. Finally, for more specific information on SIP
device support, see the AE Services Overview document.

Registration Modes

Dependency Modes

At registration time, the application specifies the desired registration dependency mode.
This indicates who controls the device’s physical elements and media.

The dependency mode choices are:

• Main dependency mode

There can be only one Main registrant associated with an extension.

An instance of a device that registers in this mode does not depend on

registration of any other endpoints using the same extension.

Once in a call this end point can talk and listen.

Only an endpoint registered as Main can block the transfer of talk capability to
an endpoint registered as Dependent or Independent via the "share-talk"
button.
Note:

Release 7.0.0
71 02-602658
Issue 1
 The "share-talk" button push is processed only if an endpoint registers
using any media mode other than No Media.

• Independent dependency mode

An instance of a device that registers in this mode can originate and receive calls
and can talk and listen even when the Main device is not registered.

If an end point registers as Main after an endpoint registers as Independent on

the same extension, talk capability is transferred to the endpoint registered as
Main.

An endpoint registered as Independent cannot block transfer of talk capability by

pressing the "share-talk" button.

• Dependent dependency mode

A device will be allowed to register in this mode only if another device is already
registered to Communication Manager using the same extension in Main mode.

A request to register using Dependent mode will fail unless another endpoint is
already registered to that extension in Main mode.

Communication Manager will unregister a device registered in Dependent mode

if the Main endpoint unregisters.

When on a call, endpoints registered as Dependent will be in listen-only mode.

An endpoint registered as Dependent cannot block transfer of talk capability by

pressing the "share-talk" button.
Note:
For further information on the "share-talk" button see The "share-talk"
button.

When to use:

• Main
Use this mode when you need to be able to answer calls, make calls, talk, or
listen, regardless of the presence of other registrants.

This mode can be used with any Media Mode including No Media.

A simple IVR application would use Main mode.

• Independent

Release 7.0.0
72 02-602658
Issue 1
 Use this mode when you wish registration to succeed regardless of whether a
Main registrant already exists.

This mode can be useful when two instances of an application register an

extension that doesn’t have an associated end-user telephone. One instance of
the application would register in Main mode and the other in Independent mode.
Communication Manager will allow either application to answer calls, make calls,
talk (one at a time) or listen, immediately after they register.

• Dependent
Use this mode when you wish registration to succeed only if a Main registrant
already exists and you want to unregister when the Main registrant unregisters.

This mode can be useful if you wish to listen to a call whose device is already
registered as Main.

This mode would also be useful if you wish to monitor/control a physical device.

Media Modes

When a device is registered by an application, the application has access to the real-
time protocol (RTP) media stream coming into and going out from the softphone.

There are four media modes available when a device is registered in Main dependency
mode: server media, client media, telecommuter, and No Media.

When the device is registered in either Dependent or Independent dependency mode,

then only server media, client media or No media is available to control the media
stream.

The following table, Registration Dependency and Media modes, illustrates what media
modes are allowed with each dependency mode.

Table 19: Registration Dependency and Media modes

Client Telecommuter Server No Media

Main Allowed2 Allowed2 Allowed2 Allowed

Dependent Allowed Not Allowed Allowed Allowed3
Independent Allowed Not Allowed Allowed Allowed

2
Corresponds to Exclusive Control in previous releases.
3
Corresponds to Shared Control in previous releases. In this mode, the user of a telephone is not
notified of actions initiated by an application except through resulting status changes to the device’s
lamps and display. Also in this mode, the application is not notified of actions initiated by a user of
the telephone except by status changes to device’s hookswitch, lamps, ringer, and display.
Release 7.0.0
73 02-602658
Issue 1
 When multiple endpoints are registered to the same extensions, all endpoints see
activity on other endpoints when status changes to the device’s hookswitch, lamps,
ringer, and display. An endpoint in this case would not be aware of the following action
taken by another endpoint:

• If endpoint A presses a digit to make a call, other endpoints (for examples, B and
C, assuming 3 endpoints registered to an extension) will not see the digits sent
by A to the AE Services server.
• Speaker button press, head-set button press and taking head-set off the cradle
are all seen as off-hook requests by Communication Manager. And therefore
other endpoints registered to the same extension will only see an off-hook event.
• Feature button presses are undetectable unless the feature button has a lamp
that toggles when the button is pressed.

The RTP parameters that an application can control or state preferences for at
registration time are:

• Local RTP and RTCP addresses

• Coder/decoder (codec): G.711 A–law, G.711 Mu–law, G.729, G.729A

Choosing a media mode

The following table “Choosing a media mode” shows the media modes available, when
to use each, and how to request each:

Note:
Although it is possible for the client application to start a monitor on a
terminal that is registered in telecommuter or no-media mode, the client
application will not receive MediaStart or MediaStop events.

Table 20: Choosing a media mode

Media modes When to use How to set

Release 7.0.0
74 02-602658
Issue 1
 Table 20: Choosing a media mode

Media modes When to use How to set

Server media This mode is used when the application Set

mode wants the AE Services server to handle MediaInfo.MediaControl
media processing. The AE Services server to
handles media with Voice Unit Services Media.MediaMode.SERVER
and Tone Detection Services or Tone _MODE
Collection Services. Voice Unit Services is in the MediaInfo argument
used to record and play messages. Tone that is passed in the
Detection Services or Tone Collection Phone.RegisterTerminal
Services are used to detect out-of-band () method.
DTMF tones. In server media mode, the
media stream terminates on the AE
Services server. To detect changes to the
far-end RTP/RTCP parameters, add
delegates on
Media.MediaStartedEvents and
Media.MediaStoppedEvents.

Client media This mode is used when application wants Set

mode to process the media itself. The RTP MediaInfo.MediaControl
stream can be terminated on any machine to
that can be controlled by the application. To Media.MediaMode.CLIENT
detect changes to the far-end RTP/RTCP _MODE
parameters, add delegates on in the MediaInfo argument
Media.MediaStartedEvents and that is passed in the
Media.MediaStoppedEvents. To Phone.RegisterTerminal
detect out-of-band DTMF tones, add () method.
delegates to the tone collection or tone
detection events in the Media class.

Telecommuter This mode is used when an application Set

mode wants the media to go to a real telephone. MediaInfo.MediaControl
The real telephone can be an internal dial to
string to Communication Manager or a Media.MediaMode.TELECO
PSTN telephone number. MMUTER
Note: Although it is possible for the client in the MediaInfo argument
application to start a monitor on a terminal that is passed in the
that is registered in telecommuter mode, Phone.RegisterTerminal
the client application will not receive () method.
events.

Release 7.0.0
75 02-602658
Issue 1
 Table 20: Choosing a media mode

Media modes When to use How to set

No Media This mode is used when the application Set

does not want an RTP stream to be setup MediaInfo.MediaControl
to it by Communication Manager. to
Note: Although it is possible for the client Media.MediaMode.NONE
application to start a monitor on a terminal in the MediaInfo argument
that is registered in no-media mode, the that is passed in the
client application will not receive events. Phone.RegisterTerminal
() method.

No media When the application does not need the

media stream to be processed.

The following table Media Control Capabilities shows the media control capabilities of
the AE Services server for both server media mode and client media mode.

Table 21: Media Control Capabilities

Media control capabilities server media mode client media mode

Record media from a call into a WAV provided by the provided by the
file server application

Dub a recording with the contents of provided by the provided by the

another compatible WAV file server application

Play a voice announcement or tone provided by the provided by the

from a prerecorded WAV file server application

Play a list of prerecorded provided by the provided by the

announcements from separate WAV server application
files

Stop, pause, or resume outstanding provided by the provided by the

play or record operations server application

Detect out-of-band DTMF tones provided by the provided by the

server application

Detect inband DTMF tones provided by the provided by the

server application

Release 7.0.0
76 02-602658
Issue 1
 Table 21: Media Control Capabilities

Media control capabilities server media mode client media mode

Manage media related event listeners provided by the provided by the

server application

Originate and terminate RTP streams provided by the provided by the

on any machine that the application has server application
control of

Media encryption provided by the provided by the

server application4

Insert a Warning Tone provided by provided by

Communication Communication Manager
Manager 6.3 or later 6.3 or later

Choosing a codec
A codec is the algorithm used to encode and decode audio media. For devices choosing
media modes of either client-media or server-media, the application can optionally
specify at registration time what codecs are preferred for the device. The codec options
are:

• G.711 A-law (g711A)

• G.711 Mu-law (g711U)
• G.729 (g729)
• G.729 Annex A (g729A)
• G.723 (supported as an option for Client Media mode only)
• G.726 (supported as an option for Client Media mode only)

Specify the set of codecs your application supports and list them in preferential order in
the Phone.MediaInfo parameter of RegisterTerminal request. If you do not
specify a set of codecs in the Phone.MediaInfo parameter of the
RegisterTerminal request, the AE Services server will default to G.711 A-law as the
first choice and G.711 Mu-law as the second choice. If Communication Manager cannot

4
Media encryption is provided by the application unless the application is using the Avaya provided
client media stack in which case it will be provided by the server.
Release 7.0.0
77 02-602658
Issue 1
satisfy your request for specific codecs, then calls will still go through, but there will be
no media.

Note:
For server media mode you cannot specify a mixture of G.711 and G.729
codecs for a single device. This is because there is no conversion offered
by the server.

For more information about selecting and administering network regions and their
codecs, see the Avaya Aura® Application Enablement Services Administration and
Maintenance Guide.

Choosing the media encryption

For devices choosing media modes of client or server media, the application can
optionally specify, at registration time, what media encryption is preferred for the
device’s media stream.

The media encryption options are:

• Advanced Encryption Standard (AES)
• SRTP (multiple options)
• none (i.e. no encryption of the media stream)

Specify the set of encryption options your application supports and list them, in
preferential order, in the MediaInfo parameter of the RegisterTerminal request. If
you do not specify a set of encryption options in the MediaInfo parameter, the AE
Services server will default to "none" (no media encryption).

Note:
You will find information on call capacities your application can expect to
be able to handle in the "Capacities for calls in Device, Media and Call
Control applications" section of the "Capacities for types of applications"
chapter of the Avaya Aura® Application Enablement Services Overview.
This section includes information on how the choice of registration
dependency modes, media modes, codecs and encryption can affect the
performance of your applications.

Redirecting Media
This request is provided by the Medis class. It allows an application that has registered a
device in client media mode to redirect the media to any destination, even in the middle
of a call.
If a call is underway, redirecting the media stream causes the current media stream to
be directed to the requested location; otherwise, it will cause any future media stream to
be directed to the requested location. The new media destination will remain in effect
until another RedirectMedia request is received or the device is unregistered.
Release 7.0.0
78 02-602658
Issue 1
There is a known limitation in the implementation of this feature in Communication
Manager. The CM expectation is that the media will be directed to a new IP destination.
Thus, when CM checks the RedirectMedia request for a new destination, it only checks if
the IP address has changed (not the port number). Thus, a RedirectMedia request that
specifies the same IP address, but a different port number, will not be redirected for the
call in progress. However, there is a workaround for this scenario. This workaround
requires the application to send two RedirectMedia requests, instead of one.
For example, if the media is currently going to IP address 10.9.20.17 and port 4725, and
you want to redirect it to port 4730 at the same IP address, you could do the following:
1. RedirectMedia to IP address 0.0.0.0 and port 4725 (specifying a null IP
address will effectively stop the media to the device, but will not end the call)
2. RedirectMedia to IP address 10.9.20.17 and port 4730 (since the IP address
has now changed, Communication Manager will correctly process this request)

The "share-talk" button

Although Communication Manager 5.0 and later allows up to three Device, Media and
Call Control station clients to register to one extension, for each extension only one
"Talk" time slot is used. If there are three endpoints registered with that extension, only
one at a time will be able to talk, but all three can listen.

If your application wants the ability to share the talk capability, you will use the "share-
talk" button. The "share-talk" button must have been administered in Communication
Manager. For information on how to administer the share-talk button on Communication
Manager, please see the Avaya Aura® Application Enablement Services Administration
and Maintenance Guide.

Communication Manager will process a "share-talk" button push only if the media mode
of that endpoint is not No Media and the extension is in a call.

Once in a call, an endpoint registered as Main can press this button to block any
endpoint registered as Dependent or Independent from taking over the talk capability.
The Main endpoint can then unblock it by pushing this button again.

If a Main endpoint has not blocked the talk capability, a Dependent or Independent
endpoint can press this button to acquire the "Talk" capability. The Dependent or
Independent endpoint can press this button a second time to move the talk capability
back to the Main endpoint.

Interpretation of the ’share-talk’ button lamp state

By an endpoint registered as Main:
• Steady On
The Main endpoint currently has the Talk capability. If Main presses the button
while in this state, the Talk capability will be blocked (see Flutter).
Release 7.0.0
79 02-602658
Issue 1
 • Flutter
The Main has blocked the talk capability from being taken over by a Dependent
or Independent endpoint. Main can unblock by pressing this button one more
time and the lamp will transit back to "Steady On".
• Off
A Dependent or Independent endpoint has taken over the talk capability. If a
Main endpoint wants to talk it can take over the talk capability at any time by
pressing the button (lamp will transit back to "Steady On" after the button push).

By an endpoint registered as Dependent or Independent:

• Steady On
The Dependent or Independent endpoint currently has the Talk capability.
When this transition happens Communication Manager will turn the "share-talk"
button lamp off at other endpoints associated with this extension. While in this
state, a Dependent or Independent endpoint can transfer the talk capability
back to Main by pushing the button.
• Flutter
The Main has blocked the talk capability from being taken over. The Dependent
or Independent endpoint cannot obtain the talk capability.
• Off
A Dependent or Independent endpoint has no Talk capability, however it can
take over the Talk capability if it desires.

Using E.164 Conversion Services

E.164 is an ITU-T recommendation defining the international public telecommunication
numbering plan used in the PSTN and other data networks. E.164 numbers can have a
maximum of 15 digits and are usually written with a + prefix. To actually dial such
numbers from a normal fixed line phone the appropriate international call prefix must be
used.

Many organizations use E.164 format when storing employee’s telephone numbers in
their directory (for example, Microsoft Active Directory or Lotus Domino). If your
application performs directory queries based on an individual’s name, it may receive
E.164 format numbers in return. In such cases, you must convert the E.164 number to a
Communication Manager extension or dial string before getting a Device ID to use with
the Device, Media and Call Control services.

Likewise, if you need to perform a directory query to resolve an extension number

received from Device, Media and Call Control into a name, you must convert the
extension number to an E.164 number before performing your query.

Release 7.0.0
80 02-602658
Issue 1
E.164 Conversion, in conjunction with the AE Services Dial Plan rules, can help your
application perform both of these conversions. The ServiceProvider class supports the
following:
• ConvertDialStringToE164 (String, List<String>,Object)
• ConvertE164ToDialString(String, List<String>,Object)

The following code snippet shows how you can convert E.164 numbers into
Communication Manager extensions/dial strings.

Note:
This example presumes that dial plan rules have been administered to indicate
that numbers starting with "+1303538" are Communication Manager extensions
that should be converted to 7 digit numbers, and that any other numbers starting
with "+1" should have an ARS code (for example, ’9’ for an outside number)
placed in front. The resulting converted numbers would then be "5381212",
"5381234" and "917205554321".

An application can perform a ConvertE164ToDialString request by calling the sample

method “ConvertE164ToDialStringRequest” below, passing it the sample data
“e164Array” and “mySwitch”. The application will also have to register the below
handler “ServiceProvider_OnConvertE164ToDialStringResponse” in order to
receive the converted data back from the AE Services server.

…
string[] e164Array = {"+13035381212", "+13035381234", "+17205554321"};
string mySwitch = “myCM”;

ConvertE164ToDialStringRequest(e164SplitList, mySwitch)
…

public void ConvertE164ToDialStringRequest(string[] e164SplitList,

string mySwitch)
{
try
{
int InvokeId;
List<string> e164List = new List<string>();

// Now add each entry into the ArrayList

foreach (string s in e164SplitList)
e164List.Add(s);

InvokeId =
ServiceProvider.ConvertE164ToDialString(mySwitch, e164List, null);

}
catch (Exception exc)
{

MessageBox.Show("\r\nConvertE164ToDialStringButton_Click Exception: " +

exc.Message);
}
Release 7.0.0
81 02-602658
Issue 1
 }

void ServiceProvider_OnConvertE164ToDialStringResponse(object sender,

ServiceProvider.ConvertE164ToDialStringResponseArgs e)
{
try
{
if (e.getError != "")
{
MessageBox.Show(" Error: " + e.getError + "\r\n");
return;
}
MessageBox.Show(" Switch Name: " + e.getSwitchName +
"\r\n");

List<ServiceProvider.ConvertE164ToDialStringResponseArgs.Result>
ResultList = e.getResultList;
for (int i = 0; i < ResultList.Count; i++)
{

ServiceProvider.ConvertE164ToDialStringResponseArgs.Result Result;
Result = e.getResultList[i];
MessageBox.Show(" e164: " + Result.gete164 + "
Dial String: " +
Result.getDialString + " Result Type: " +
Result.getResultType + "\r\n");
}
}
catch (Exception exc)
{

MessageBox.Show("\r\nServiceProvider_OnConvertE164ToDialStringResponse
Exception: " + exc.Message);
}
}

Converting from dial strings to E.164 is done in a very similar fashion.

For more information on administering dial plan rules, see the Administering Dial Plan
Settings chapter of the Avaya Aura® Application Enablement Services Administration
and Maintenance Guide.

Exercise: Performing a Device Registration

Note:
This exercise is a continuation of the previous exercise.

Notice that the Register Terminal button is now available. If we hold the mouse over the
Register Terminal button we see what information we need to fill in.
Release 7.0.0
82 02-602658
Issue 1
Specifically we need:
• Password
• E911 Information (if any)
• Force Login
• Media Mode
• Dependency Mode

Release 7.0.0
83 02-602658
Issue 1
Fill in the required information and push the Register Terminal button:

The device is now registered and

• some display and lamp update are now in the Events area
• the dial pad buttons (0 thru 9, *, and #) are now active
• the Drop, Hold, Conf, Trans, On Hook, and Off Hook buttons are now active

Release 7.0.0
84 02-602658
Issue 1
Exercise: Performing Operations on a Registered Device
Note:
This exercise is a continuation of the previous exercise.

So, let’s make an outgoing call to 5386000 and see what happens.

Now we will hang up:

Release 7.0.0
85 02-602658
Issue 1
In the Events textbox are we see a lot of display updates, lamp updates, and hook
switch updates.

We now make and receive a few calls and observe the Events textbox.

By scrolling the Events textbox area we notice that we are getting an OFF HOOK event
every time the phone makes or answers a call and an ON HOOK event every time a
user disconnects a call. We decide, for this example, that monitoring the hookswitch
status is how we want to decide if the user is on a call or not.

To do this:
• Stop the existing phone monitor by selecting the monitor in the Monitor Ids
textbox and then pushing the Stop Monitor Button
• Start another one that just monitor hook switch changes by unchecking all the
events in the Phone Events area except for Hookswitch and then push the Start
Phone Monitor button.

Release 7.0.0
86 02-602658
Issue 1
A new monitor was created.

Our steps to this point have been:

• Start an application session to the AE Service server
• Get a Device Id for extension 5382834
• Start a monitor for that Device Id which will only monitor Hookswitch changes
• Register the terminal

Once you have done the above your application should be able to record the call
duration.

When your application is done, you must:

• Unregister the terminal
• Stop the monitor
• Release the Device ID
• Stop the Application Session

Expanded help feature

The Dashboard tool offers an expanded help feature. To use this feature
1. click on the ? button (top right)
2. click on any button (for example, the Register Terminal button) that you wish to
have more detailed help with
Release 7.0.0
87 02-602658
Issue 1
The more detailed help will be presented.

Note:
In addition, in most cases you will be prompted to also launch a browser
which will take you directly to the documentation on the Avaya
DevConnect site for that particular method.

If you do this with the Register Terminal button the following dialog will appear:

Select Yes to get more information about the RegisterTerminal method.

Internet Explorer will bring up the Programmers Reference with the information about the
RegisterTerminal method. From there you can click on the links to learn more about the
parameters or other related methods.

Release 7.0.0
88 02-602658
Issue 1
Writing Code
This section covers starting an application session. The other steps are virtually
identical.

Start Visual Studio. We will assume you are familiar with Visual Studio so start a new
Windows Application project and for this example call your application logger.

Add 4 buttons to the form and label them:

• Start Application Session
• Get Device Id
• Start Monitor
• Register Terminal

Before we add any code, we need to add a reference to the ServiceProvider.dll file.

Release 7.0.0
89 02-602658
Issue 1
Right click on References and select Add Reference

Release 7.0.0
90 02-602658
Issue 1
A dialog will show up, select the Browse tab and go to the folder where the
ServiceProvider.dll file resides (it comes with the .NET SDK).

Release 7.0.0
91 02-602658
Issue 1
Select OK and you should now see it in the list of references.

Release 7.0.0
92 02-602658
Issue 1
Now right click on Form1.cs and select View Code.

Insert the following below the using directives:

using System.Collections.Generic;
using Avaya.ApplicationEnablement.DMCC;

Go back to design view by double clicking on the Form1.cs file in the Solution Explorer.

Release 7.0.0
93 02-602658
Issue 1
 Release 7.0.0
94 02-602658
Issue 1
Create the handler for the Start Application Session button by double clicking on it.

Add the code for starting an application session

• Right click in the StartApplicationSessionButton_Click() method
• select Insert Snippet --> DMCCCodeSnippetsC# --> Methods -->
StartApplicationSession
Note:
This assumes you have already imported the code snippets which ship
with the SDK.

Release 7.0.0
95 02-602658
Issue 1
Code will automatically be brought in to your workspace.

There will be comments on what you need to do in order to make it work and fields will
be highlighted on what needs to be changed.

Follow the instructions and then attempt to build.

Release 7.0.0
96 02-602658
Issue 1
The build was successful.

Add the code to handle the response for the Start Application Session.

Use code snippets to create the majority of the code.

As the comments for Start Application Session indicate, we want to insert the event
manager code right after we create it r (i.e., do a New).

Put the curser right after the code that creates it:
• Right click
• select Insert Snippet --> DMCCCodeSnippetsC# --> Events -->
StartApplicationSessionResponseEvent

Release 7.0.0
97 02-602658
Issue 1
The code is brought in, modify as the comments direct you to.

Modify the response handler to give you a pop-up message when it arrives.

Release 7.0.0
98 02-602658
Issue 1
Run the application.

Press the Start Application Session button.

You will get a pop-up giving you the Session ID.

You have finished putting in the code for Start Application Session. By using the
included Code Snippets, very little code had to be written from scratch.

You need to follow these same steps to write the code for Get Device, Start
Monitors, and Register.

In this context we have ignored error detection and correction. However, this small
example should provide you with the tools you need to start writing Device, Media and
Call Control .NET applications.

Note:
If you want to write the code in Visual Basic, follow the same steps using
the supplied Visual Basic code snippets instead.

We have only covered a very small part of the Dashboard’s capabilities.

Release 7.0.0
99 02-602658
Issue 1
The Dashboard exposes all the DMCC functionality which is available to you from .NET
including, but not limited to:
• Playing wave files
• Recording Wave files
• All Third party call control features
• Receiving RTP media
• Tone Detection
• Liink Status
• Getting Button Information
• Pushing Buttons
• Making Calls
• Answering Calls
• Conference and Transfer
• Monitoring XML messages going to/from the DMCC server
• Ability to Inject and XML message that you want

Note:
The combination of the Dashboard and code snippets should allow
you to not only quickly learn about what DMCC can do but also be
able to write applications very quickly.

Writing applications that run in a browser

You can write Device, Media and Call Control .NET applications that will run in an
Internet Explorer browser.

Note:
This API is not compatible with non Microsoft browsers.

Extensive JavaScript libraries have been provided to make it relatively easy to write thin
clients.

An HTML version of the Dashboard ships with the SDK. It allows you to try out the
various interfaces in Internet Explorer. You can also view sample JavaScript code from
the browser dashboard.

The HTML version of the dashboard is located in the jscript/dashboard folder and
the html file is called dashboard.html.

There is also an HTML softphone sample application in the js/softphone folder.

By looking at the source code for the softphone and using the dashboard you should be
able to start writing thin client applications with minimal effort.

Release 7.0.0
100 02-602658
Issue 1
Telephony Logic
The AE Services server notifies your application when requested telephony events
occur:
• Registration events indicate unregistration by Communication Manager.
• Endpoint Registration events, available in AE Services 6.3 and later, indicate
device registration and unregistration by Communication Manager.
• Physical Device events indicate changes to the status of the ringer, display, and
lamps.
• Media Control events indicate when the media stream parameters have
changed.
• Voice Unit events indicate the status of recording and playing messages.
• Tone Detection events indicate when DTMF digits are received.
• Tone Collection events indicate when specified tone retrieval criteria are met,
and when collection begins and ends.
• Call Control events indicate changes to the status of the call.
• Logical Device Feature events indicate when agent status events occur.
• System Status events indicate when a TSAPI Tlink comes up or goes down.
• Call Associated events indicate when a regenerated telephony tone request
fails.

The following sections will give general instruction how to perform common things
around the telephone.

Note:
We encourage you to use the Dashboard application to investigate the
available features of the .NET SDK further. The actual .NET source code is
available by using the Visual Studio Code Snippets that are in the SDK.

Device and Media Control

When your application wishes to monitor or control devices, your logic for what to do
with a device begins once it is registered; therefore the receipt of a
RegisterTerminalResponse is usually the starting point for your application’s telephony
logic.

You will monitor for server unregistration by implementing a

Phone.OnTerminalUnregisterEvent delegate and adding a Phone.PhoneEvents for
the TerminalUnregisteredEvent using the Phone.StartMonitor method.

Release 7.0.0
101 02-602658
Issue 1
Once a device is registered, your application may begin monitoring or controlling it with
any of the services provided by the ServiceProvider.

As part of the registration initialization process, multiple physical device events are sent
by the Communication Manager indicating the initial states of the lamps, ringer,
hookswitch and display. These events may occur before and/or after the Registered
event.

Note:
If your application needs to register many devices, we recommend you spread
out the registration of the devices. Register no more than 50 stations at one time
and wait until your application has received all of the responses before
attempting to register more stations.

Monitoring and Controlling Physical Elements

Physical elements of a device are monitored and controlled with the Phone class. An
instance of the Phone class can be used to manipulate a device and start a monitor to be
notified about changes related to the physical aspects of the device (i.e. lamp state
change, switchhook state change, etc.).

Device based call control can be accomplished with a combination of:

• determining the current status of physical elements on a device, such as
requesting the list of buttons administered for the device
• listening for particular physical device events, such as when the phone starts
ringing
• activating physical elements of the device, such as going off-hook

Using the Dashboard, the Phone events can be configured using the tab under the
Event Registration section on the Main tab. The buttons in the upper left corner of the
Dashboard can be used to manipulate a phone and the Phone Commnads tab can be
used to obtain data related to the physical aspect of a registered device. The actual
.NET source code is available by using the Visual Studio Code Snippets that are in the
SDK.

Knowing what buttons are administered

If your application needs to press any buttons or determine which lamps have changed
state, you will need to know what buttons are administered on the device. Buttons are
assigned to devices during station administration via the Communication Manager
system access terminal (SAT) interface.

Release 7.0.0
102 02-602658
Issue 1
Your application must use the Phone.GetButtonInfo()method to ask about a
particular button or to ask to get all button information. Look under the Dashboard
"Phone Commands" to test this functionality.

Each button item in the list includes the following information:

• button identifier - indicates the address or location of the button. Its value is one
of the constants listed in ButtonIDConstants listed in Appendix C: Constant
Values. Constants are available for both administered buttons and fixed buttons
(those buttons that are preset and pre-labeled on a telephone set).
• button function - indicates what the button does when pressed. Its value is one of
the ButtonFunctionConstants listed in Appendix C: Constant Values.
• associated extension - indicates whether there is an extension number
associated with this button and what the extension number is.
• associated lamp - indicates whether there is a lamp associated with the button. If
there is, its lamp identifier is the same as the button identifier.

Note:
There is no direct indication provided by the API to the application of changes to
the provisioned information for a monitored device. Thus, collecting the device's
configuration, when the application initializes is an incomplete solution. A robust
application should periodically validate that the current configuration of the device
is aligned with the representation of that configuration as derived by the
application. In order to do so, an audit of the information should be developed
and run at some recurring cycle, or when unexpected feedback to button presses
is received. An audit can be realized by utilizing the Phone.GetButtonInfo
request and comparing the results with the previously obtained information.

Detecting an incoming call

When a call comes into a device, these three changes occur to the physical device:
• The phone rings.
• A green call appearance lamp flashes.
• The display changes to show caller information.

Therefore, the following events will be sent to an application that has started a Phone
monitor for these events:
• RingerStatusEvent - The ring pattern is supplied in the event structure. For a list
of possible ring patterns see Appendix C: Constant Values for “Ringer Pattern
Constants”.
• LampModeEvent - The identifier of the lamp that has changed and the lamp’s
mode is supplied in the event structure. Once you know where the call
appearance lamps are (see Knowing what buttons are administered), you can
determine if it is a call appearance lamp and if it is flashing by comparing the
lamp mode against the FLASH constant. For a complete list of the possible
lamp modes, see Appendix C: Constant Values for Lamp Mode Constants.
Release 7.0.0
103 02-602658
Issue 1
 • DisplayUpdatedEvent - The display contents are supplied in the event structure.
In general, the number of DisplayUpdatedEvent messages you will receive
before the display update is complete can vary.

You may want your application to key off of just the LampModeEvent, or it may want to
wait for the other events before responding to an incoming call. The events may come in
any order.

You can try this in the dashboard and use the Visual Studio code snippets to look at
sample source code.

Determining that far end has ended the call

If all far-end parties drop on a call, these changes occur on the local device:
• The call appearance green lamp turns off.
• The display is updated based on the current state of the extension.
For example:
o Returns to an idle state showing extension, date and time information
o Begins showing information about a ringing call at the extension
o Is not updated and continues to show information relative to an active
display feature such as Directory Lookup

Therefore the following events will be sent to an application that has started a Phone
monitor for these events:
• LampModeEvent - The identifier of the lamp that has changed and the lamp’s
mode is supplied in the event structure. Once you know where the call
appearance lamps are (see Knowing what buttons are administered), you can
determine if it is a call appearance lamp and if the lamp is now off by comparing
the green lamp mode against the OFF constant. A complete list of possible lamp
modes can be found in Appendix C: Constant Values under Lamp Mode
Constants.
Note:
Communication Manager sends lamp updates not only for lamp
transitions, but also to refresh lamps. Therefore, some LampModeEvents
indicate that the lamp is in the same state it was in before the event.
• DisplayUpdateEvent - The display contents are supplied in the event structure.

You can try this in the dashboard and use the Visual Studio code snippets to look at
sample source code.

Making a call

To make a call from a telephone, a person would typically:

Release 7.0.0
104 02-602658
Issue 1
 1. Go off-hook
2. Press a sequence of dial pad buttons (0-9, *, #) to initiate a call, such as pressing
5551234, with a 100 msec delay in between each digit
3. Listen for an answer
4. Begin a two-way conversation or listen to a recording
Here is how you might program each of those steps:
1. To go off-hook, you could simply use the Phone.SetHookswitchStatus request.
However, this approach could cause a conflict with a potential incoming call. That
is, if a call came in just before you went off-hook, then your dialing attempt would
fail and instead you would be connected with the incoming caller.
The only way to avoid conflicting with an incoming call is to keep track of the
lamp transitions of the call appearances. If a lamp goes from off to steady, then
you can make an outbound call. But if the lamp goes from off to flashing and then
to steady, then you have just picked up an incoming call.
One method to reduce the chance of conflicting with an incoming call is to begin
a call by pressing the last call appearance button using the Phone.PressButton
request. This avoids using the same call appearance as an incoming call which
comes in to the first available call appearance. To further assure that even the
last call appearance is not in use, make sure the lamp is off before you press the
button. Observing the sequence of lamp transitions is still necessary even with
these precautions.
2. To press the dial pad buttons to dial a number, use the Phone.PressButton
request and the constants (Phone.ButtonIDConstants) defined for dial pad
buttons in Appendix C: Constant Values for ButtonID Constants, such as
DIAL_PAD_7 or DIAL_PAD_POUND.
Note:
DIAL_PAD_0 through DIAL_PAD_9 have string values of “0” through “9”,
therefore using the strings “0” - “9” will work. However, DIAL_PAD_STAR
and DIAL_PAD_POUND are not set to “*” and “#”; instead they are “10”
and “11”, respectively (as specified by CSTA). The Phone.PressButton
request will not work with “*” and “#”. Therefore, it is safer to get in the
habit of using the constants (Phone.ButtonIDConstants), not the literals.
3. If your application is handling its own media (as determined by the local RTP
address and media mode set at registration) then you can determine from the
media stream that there is media other than ringback coming from the far end.
Your application will need an RTP stack and a call progress tone detector. For
the RTP stack, you may use a third-party vendor stack, your own stack or the
media stack provided by Avaya. Avaya’s media stack is described in the Media
Stack API Javadoc. Avaya does not provide a call progress tone detector.
If the AE Services server is handling the media, wait for an appropriate period of
time before playing a message to the far end or recording the far end’s media
stream. This is to allow time for the RTP connection to be made end-to-end.
4. To have a real-time conversation in server media mode, the application must
handle the media.
To play message to the far end or record the far end’s media stream, use
Media.StartPlaying or Media.StartRecording (see Recording and playing
voice media below for more details)

Release 7.0.0
105 02-602658
Issue 1
You can try this in the dashboard and use the Visual Studio code snippets to look at
sample source code.

Call Control

Monitoring and Controlling Calls

Before attempting to use Call Control Services, you must first perform the following:
• Acquire an instance of ServiceProvider.
• Acquire the ThirdPartyCallControl instance from the ServiceProvider instance.
• Acquire a ThirdParty Call Control DeviceID.
• Using the ThirdPartyCallControl instance register the call control events.

You will monitor for call control events by implementing

ThirdPartyCallController.StartMonitor and adding event delegates from the
ThirdPartyController class that is of interest to you (i.e.
ThirdPartyController.OnDeliveredEvent). See Notification of Events for more
information.

When a Call Control request requires a ConnectionID parameter, it can be obtained from
a previous call control response, event or by issuing a
ThirdPartyCallController.SnapshotDevice request.

When a DeviceID representing an extension is needed in the request, the DeviceID can
be obtained from a previous call control response, a previous call control event or by
using the ThirdPartyCallController.GetThirdPartyDeviceId request.

Example of using the GetThirdPartyDeviceId request and response:

// The third-party device ID

string thirdPartyDeviceId = “”;

//
// Register the response handler
//
ServiceProvider.getThirdPartyCallController.OnGetThirdPartyDeviceIdResp
onse += new
GetThirdPartyDeviceIdResponseHandler(My_OnGetThirdPartyDeviceIdResponse
);

//
// GetThirdPartyDeviceId Response Callback Handler
//
void My_OnGetThirdPartyDeviceIdResponse(object sender,
ThirdPartyCallController.GetThirdPartyDeviceIdResponseArgs e)
Release 7.0.0
106 02-602658
Issue 1
 {
try
{
OneThreadAtATimeEvent.WaitOne(5000, false);

if (e.getError != "")
{
// Handle Error
}
else
{
thirdPartyDeviceId = e.getDeviceIdAsString;
}
}
catch (Exception) { }
finally { OneThreadAtATimeEvent.Set(); }
}

//
// GetThirdPartyDeviceId Request
//
int InvokeId;
string switchName = “myServer”;
string myExtension = “5551234”;
InvokeId =
ServiceProvider.getThirdPartyCallController.GetThirdPartyDeviceId(switc
hName, myExtension, null);

Making a call

You can make a call with the ThirdPartyCallController.MakeCall request. By

adding a ThirdPartyCallController.OnMakeCallResponse delegate you will be
notified about the success or failure of the MakeCall request. Depending on which
event delegates that you registered, you will start to receive events.

Answering a call

If your application receives the DeliveredEvent your application may answer the call,
using the connectionID from the DeliveredEvent with the
ThirdPartyCallController.AnswerCall request.

Ending a call

Release 7.0.0
107 02-602658
Issue 1
After your application has received the EstablishedEvent and you wish to end the
call. Your application may end the call, using the
ThirdPartyCallController.ClearConnection request. When a call has ended, your
application will receive a ConnectionClearedEvent.

Getting ANI information for a call

Use either of the following methods to get ANI information for a call.
• Start a Third Party Call Control Monitor configured to monitor at least one of the
"On Originated", "On Delivered", "On Established", and "On Failed" events.
When any of these events arrive, the ANI information will be available via the
"getCallingDeviceId" accessor in the event parameter.

• Use the conference display button to get ANI information for a call.
If the application wishes to use only device and media control, it can alternatively
use the conference display button.
In order to use the conference display button to get ANI information for the call,
the conference display button (conf-dsp) will have to have been administered for
that extension in Communication Manager.
Once an incoming call is received by your application for the extension, your
application should press the conference display button of the extension
repeatedly to get the ANI information (through the DisplayUpdatedEvent of
Phone Services) for each party on the call.

Recording and playing voice media

If your application needs to record incoming media or play a message on a call, then at
registration time:
• You must choose to either handle the media yourself (client media) or have the
AE Services server do it for you (server media). See Choosing a media mode on
page 74.

This section describes how to use the Media Object to have the AE Services server
record and play media for you. The supported services are described in the Media Class
on page 25. The details about using the services are described in the Programmers
Reference. To see sample code using the Media Class, see the sample application
called SimpleRecord referenced in Learning from sample code on page 46.

Some basic rules of Voice Unit Services are:

• Wave files
All digital audio files that are created or played are in the Wave Resource
Interchange File Format (RIFF). The standard Wave file structure is used for all
encoded media types.

Release 7.0.0
108 02-602658
Issue 1
 G.729 formatted files, however, use non-standard field values in some of the
standard format chunk fields. They are:
Compression code value: 131 (0x0083)
Block align value: 10 (0x000A)
Bits per sample value: 1 (0x0001)
An external G.729 converter is required to convert a G.729 Wave file into a
standard RIFF Wave file that can be played.
• Files on the AE Services server
All Wave files are assumed to be on the AE Services server machine in the
directories specified in the AE Services Management Console interface under
the media properties as the player directory and the recorder directory.
Note:
These two directories do not have to be the same. These directories are
the root directory of the relative paths specified in the playMessage and
recordMessage requests.

• Encoding algorithms
Files to be played can be encoded in these formats:
PCM 8-bit or 16-bit
G.711 A-law
G.711 Mu-law
G.729
G.729A
Recordings can be made of calls in these formats
PCM 8-bit or 16-bit
G.711 A-law
G.711 Mu-law
G.729
Note:
Once the call has been established, you can find out what codecs have
been chosen by Communication Manager from the
MediaStartedEvent, which will contain a list of the codecs.

Codecs must be specified at registration time and while in server media

mode you cannot specify a mixture of G.711 and G.729 codecs for a
single device. This is because there is no conversion offered by the
server.

• Conversions between encoding algorithms

Files to be played can be converted from any PCM type to any G.711. No other
conversions are supported for playing.

Release 7.0.0
109 02-602658
Issue 1
 Messages to be recorded can be converted from G.711 to PCM. No other
conversions are supported for recording.
• Using with Tone Detection or Tone Collection Services
The Voice Unit Services player and recorder may be setup to detect DTMF tones
at the same time Tone Detection or Tone Collection Services is being used.
However, there is no guarantee which service will detect a tone first. See
Possible race conditions for more specifics.

Media Operations
Media operations such as Recording, Dubbing, playing wave files are all done through
the Media Object. Use the dashboard tool to learn more about these capabilities and use
the Visual Studio code snippets to help you write the actual code.

Recording

To record the RTP media stream of a device, use the Media.StartRecording request.
This will record only the media coming from other parties on the call to the device not the
media that is being played from this device using the Media.StartPlaying request.
Only media packets that are received are recorded: lost packets are not replaced.

The application can specify an alphanumeric filename for the recording or let the
filename default to a format of <timestamp><extension>.wav. The alphanumeric
filename may contain a relative directory path. Filenames specified for recorded files
must be relative to the configured directory, their directories must already exist, and
recordings cannot overwrite an existing file. If it is defaulted, then the resulting filename
is returned in the RecordMessageResponse.

Since recording is associated with a device rather than a call, a recording could contain
the incoming media from multiple calls. Recording continues until one of the following
occurs:
• Application explicitly stops the recording with a Media.StopRecording request.
• Application requests that the AE Services server automatically stop the recording
when a specified termination criterion is met. Multiple termination criteria can be
specified in which case the first criterion that is met stops the recording.
Termination criteria options include:
o when a DTMF tone is received by the device. To request this
termination criterion, set the toneTermination parameter’s terminating
conditions so that DTMFDigitDetected is set to true.
o when recording reaches a specified duration. To request this
termination criterion, set the duration parameter to the maximum
number of milliseconds allowed for the recording.

Release 7.0.0
110 02-602658
Issue 1
If you wish to record one entire call and only one call, then your application can watch
the lamp events to determine when the call has ended and explicitly stop the recording
after the call has ended.

Note:
No exception is thrown if the application requests that recording stop when there
is no active recording.

Once an active recording on a device has been stopped, a StopEvent, sent to the
application, indicates that the recording has finished and the recorded file is ready for the
application.

The recording can also be:

• suspended temporarily - with the Media.SuspendRecording request.
• dubbed with another recording - with the Media.StartDubbing and
Media.StopDubbing requests.

• resumed - with the Media.ResumeRecording request.

• stopped - with the Media.StopRecording request.
• deleted - with the Media.DeleteMessage request.

Playing a Recording Warning Tone

AE Services 6.3 and later and Communication Manager 6.3 and later, provides the
ability for an application to request Communication Manager to insert a tone into the
audio stream of the parties in a call. This tone serves to indicate that the audio stream is
being recorded using either the Single Step Conferencing method or the Multiple
Registrations method. The tone that is played is inserted by Communication Manager
and is identical to that already used by the Service Observing feature.

Note:
The client application requests the recording warning tone for a specific device,
not a specific call. Thus, if the recording warning tone has been activated for a
device, any time that the specified device is included in a call, the recording
warning tone will be inserted into the call. This will continue to be the case for
every call in which the device is a party, until such time that the client application
requests that Communication Manager deactivate the recording warning tone.

To activate the recording warning tone for a device, use the GenerateTelephonyTones
request from the Call Associated service. And to deactivate the tone for the device, use
the CancelTelephonyTones request.

Note:
If the client application requests the activation of the recording warning tone while
the specified device is already in a call, the tone will not be applied to the existing
Release 7.0.0
111 02-602658
Issue 1
 call. However, the tone will be applied to all subsequent calls in which the device
is a party.

Similarly, if the client application requests the deactivation of the recording

warning tone while the specified device is already in a call, the tone will not be
removed from the existing call. However, the tone will be removed from all
subsequent calls.

In the case of an AE Services server fail-over (or Communication Manager fail-over), AE

Services will automatically re-establish the recording warning tone for all devices on
which the tone is currently activated. However, there is a very small chance that the tone
may not be re-established for some reason. In this rare case, AE Services will send a
GenerateTelephonyTonesAbort event to the client application. In order to receive this
event, the application should set a monitor by using the Call Associated StartMonitor
request.

In order to stop monitoring for the event, the application can remove the appropriate Call
Associated Service monitor by using the StopMonitor request.

Playing a recording warning tone - single step conference method

To use the Single Step Conference method, a recording application registers to Avaya
Aura® Communications Manager extension “A” and monitors a user’s extension “B” that
will be recorded. Prior to the user accepting any calls, the recording application sends a
GenerateTelephonyTones request for the extension to which it is registered (“A”). When
the user’s extension (“B”) accepts a call, the recording application joins the call using
Single Step Conference and begins recording the call. The warning tone is played when
the recording application extension (“A”) joins the call at the user’s extension (“B”).

After the final call to be recorded has finished, the recording application sends a
CancelTelephonyTones request to the extension to which it is registered (“A”) to stop the
warning tone from being played.

Playing a recording warning tone - multiple registration method

To use the Multiple Registration method, a recording application registers to the same
extension (in either dependent or independent DependencyMode) of the user that is
taking the calls to be recorded. Prior to the user accepting any calls, the recording
application sends a GenerateTelephonyTone request for the extension to which it is
registered. When the (Main) user answers a call, the recording application is
automatically connected to the call and a warning tone is played.

After the final call to be recorded has finished, the recording application sends a
CancelTelephonyTones request to the extension to which it is registered, to stop the
warning tone from being played.

Release 7.0.0
112 02-602658
Issue 1
Dubbing

A recording can be dubbed with another Wave file by using Media.StartDubbing and
Media.StopDubbing requests. Dubbing records the specified Wave file over the
recording repeatedly from the time Media.StartDubbing is called until
Media.StopDubbing is called. This may be helpful to avoid recording sensitive
information such as a spoken password or other private or security-based information.

Since the application must explicitly stop the dubbing, the application must have the
logic to know when to stop. It may be based on time, an incoming DTMF tone such as
“#”, or a manual action by an agent who is listening

Playing

To play one or more messages to the RTP stream of a call as if the message(s) are
coming from the device, use the Media.StartPlaying request. The message(s) can be
played once, multiple times, for a particular duration, or until a DTMF tone is received by
the device.

The filename of the file to be played can be alphanumeric. The alphanumeric filename
may contain a relative directory path. One or more files can be specified as long as they
are of the same encoding type. For an example of how multiple files can be specified,
see the Dashboard.

Since playing is associated with a device rather than a call, the playing of the
message(s) may continue across multiple calls to which the device is a party. Playing
continues until one of the following occurs:
• Application explicitly stops the playing with the Media.StopPlaying request.
• A specified termination criterion is met.

Multiple termination criteria can be specified, in which case the first criterion
that is met stops the playing. Termination criteria options include:
1. When a DTMF tone is received by the device.

To request this termination criterion, set the termination parameter’s

toneTermination condition so that DTMFDigitDetected is set to true.
2. When playing occurs for a specified duration.

To request this termination criterion, set the duration parameter to the

maximum number of milliseconds allowed for the playing in the
repeatInfo parameter using Media.PlayRepeatInfo.
3. When the message(s) have been repeated a specified number of times
with a specified interval in between.

Release 7.0.0
113 02-602658
Issue 1
 To request this termination criterion, set PlayCount and PlayInterval
in the repeatInfo parameter using Media.PlayRepeatInfo.

If you wish to play message(s) to one entire call and only one call, then your application
can watch the lamp events to determine when the call has ended and explicitly stop the
playing after the call has ended.

Once active playing on a device has stopped, a StopEvent, sent to the application,
indicates that the playing has finished.

Note:
No exception is thrown and no event is generated if the application requests that
playing stop when there is no active message playing.

The playing of the message can also be:

• suspended temporarily- with the Media.SuspendPlaying request.
• resumed - with the Media.ResumePlaying request.
• stopped - with the Media.StopPlaying request.

Monitoring Media Events

Your application can receive and respond to the Media events and responses by
invoking the Media.StartMonitor request and adding delegates to the Media instance (i.e.
Media.OnMediaStartedEvent). The Media events and responses will indicate when
requests have been accepted, processing has begun and when processing has ended.

Detecting and collecting DTMF tones

If your application needs to detect DTMF tones coming to a device from another party on
the call, then you can use AE Services DMCC ToneDetectionServices or
ToneCollectionServices. To use these services, you must either:
• Register the device in server media mode to detect both out-of-band and in-band
tones.
• Register the device in client media mode to detect only out-of-band tones.

DTMF tones are generated by parties on a call by pressing the dial pad digits 0 through
9 and * and # during the call. If the device that is being monitored is on a call and
another party on the call presses a dial pad digit, then a registered
Media.OnToneDetectedEvent delegate can be used to report each DTMF tone to the
application. The Media.MediaEvents should be configured to monitor for the
ToneDetectedEvent issued by the AE Services server using Media.StartMonitor.
Release 7.0.0
114 02-602658
Issue 1
In contrast, Media.StartToneCollection can be used to buffer the received tones and
report them to the application when the specified retrieval criteria are met. The retrieval
criteria, specified with the Media.SetToneRetrievalCriteria request, may be one or
more of the following:
• A specified number of tones have been detected.
• A specified tone (called a "flush character") has been detected.
• A specified amount of time (called a "timeout interval") has elapsed.

When at least one of the retrieval criteria is met, the following retrieval steps are
performed by the AE Services server:
1. The buffered tones up to and including the tone which met the retrieval criteria,
are removed from the buffer.
2. The retrieval criteria are cleared (optional).
3. The application is notified of the retrieved tones with the TonesRetrievedEvent.

If more than one retrieval criterion is specified, the first one to occur causes the retrieval
criteria to be met.

A registered Media.OnToneRetrievedEvent delegate can be used to report the

collected DTMF tones to the application. The Media.MediaEvents should be configured
to monitor for the TonesRetrievedEvent, issued by the AE Services server, using
Media.StartMonitor.

Note:
Use the Dashboard tool to learn more about these capabilities and use the Visual
Studio code snippets to help you write the actual code.

The supported services are summarized in Media Class.

Some basic rules of these services are:

• Touch tone detection mode

Both sets of services can detect in-band and out-of-band DTMF tones. In-band
tones are transmitted within the media stream. Out-of-band tones are
transmitted in the signalling channel. The AE Services server always detects
out-of-band tones. If the application wishes to also detect in-band tones (in-
band tone detection is not recommended), then the tone detection mode must
be explicitly set to in-band.

Set the tone detection mode before the AE Services server is started up. The
mode is provisioned in the AE Services Management Console web pages on
the “AE Services > DMCC > Media Properties” screen as the ttd_mode.

Release 7.0.0
115 02-602658
Issue 1
 To detect only out-of-band, set the mode to OUT_BAND (default). To detect both
in-band and out-of-band, set to IN_BAND. See the appropriate Avaya Aura®
Application Enablement Services Installation and Upgrade Guide for the offer
you have purchased (VMware or Software Only) for instructions on how to
choose between in-band and out-of-band for the AE Services server and for
Communication Manager, and how to setup the ttd_mode property.

• Using with Media Player and Recorder tone detection

The Media Player and Recorder may be set up to detect DTMF tones at the
same time Tone Detection or Tone Collection is being used. However, there is
no guarantee which service will detect a tone first, see “Possible race
conditions” for more specifics.

Detecting individual tones

To detect DTMF tones one at a time, use the Media methods in this order:
1. Implement the Media.OnToneDetectedEvent delegate to handle each tone that
is detected.
2. The Media.MediaEvents must be configured to monitor for the
ToneDetectedEvent issued by the AE Services server using the
Media.StartMonitor request.
3. Now each time a tone is detected by the AE Services server, a
ToneDetectedEvent is issued to the application and handled by the registered
delegate.
4. When you no longer wish to be notified of detected tones, remove the listener
with the Media.StopMonitor request.

You may want to set up interdigit timers limiting the maximum amount of time the
application will wait between tones or a duration timer limiting the maximum amount of
time before stopping the tone detection.

Use the Dashboard tool to experiment and use the Visual Studio code snippets to help
you write the code.

Collecting multiple tones

To have the AE Services server collect multiple DTMF tones and report them to the
application based on specified retrieval criteria, use the Media Tone Collection methods
in this order:
1. Implement the Media.OnToneRetrievedEvent delegate to handle a retrieved set
of tones. The TonesRetrievedEvent , issued by the AE Services server, that is

Release 7.0.0
116 02-602658
Issue 1
 passed to the delegate, supplies the set of tones that were retrieved and the
cause of the event. The cause of the event may be any of the following:
• BUFFERFLUSHED - when the flushBuffer method is called
• CHARCOUNTRECEIVED - when the number of tones specified in the
retrieval criteria is received
• FLUSHCHARRECEIVED - when the tone specified in the retrieval
criteria is received
• TIMEOUT - when the amount of time specified in the retrieval criteria
has elapsed
2. Add the listener to the device with the Media.StartMonitor request. The
Media.MediaEvents must be configured to monitor for the
TonesRetrievedEvent.

Note:
Adding the listerner does not start the buffering of tones.
3. Start tone collection with the Media.StartToneCollection request. This
causes each detected tone to be put in a buffer.
4. Set the retrieval criteria with the Media.SetToneRetrievalCriteria request.
5. When one of the retrieval criteria is met, the application’s delegate,
Media.OnToneRetrievedEvent, is called and optionally, the retrieval criteria
are cleared. The AE Services server continues buffering detected tones.
6. If you wish to be notified of more tones, call the
Media.SetToneRetrievalCriteria request again. There is no need to stop
and restart the collection.
7. You can add and remove listeners at any time during collection.
8. If for any reason you wish to flush the buffer during collection, use the
Media.FlushToneCollectionBuffer request. This will report the tones
collected since the last time the buffer was flushed in the
TonesRetrievedEvent. You may want to flush the buffer at the end of a call.
9. When you no longer wish to be notified of collected tones, stop tone collection
with the Media.StopMonitor request. This will cause the server to stop
collecting DTMF tones sent to a device and report the tones that have been
buffered. This flushes the buffer. The delegate may be removed if it is no longer
needed.

Use the Dashboard tool to experiment and use the Visual Studio code snippets to help
you write the code.

Release 7.0.0
117 02-602658
Issue 1
Determining when far-end RTP media parameters change
Applications that control their own media (client media mode) will need to use the Media
monitors to determine when the far-end RTP media parameters change. Here is the
sequence of media control events an application should be prepared to receive:

1. When media is first established for a call, the application receives a

MediaStartEvent. However, it does not guarantee that the call has been
established end-to-end yet.
2. If Communication Manager changes the far-end RTP parameters for a call, the
application receives a MediaStopEvent. At that point the current far-end RTP
parameters should no longer be used. A MediaStopEvent could indicate that the
call has ended, but do not depend on that event alone to determine the end of a
call. The call appearance lamp will also change if it is the end of a call.
3. If there are new far-end RTP parameters, then the application will subsequently
receive a MediaStartEvent.

One scenario in which a MediaStopEvent and then a MediaStartEvent may be

received is when Communication Manager shuffles a call. Shuffling occurs when
Communication Manager changes the path of the media.

For example, if the media is going from calling party A to Communication Manager and
then to called party B, Communication Manager may choose to change the media path
such that it goes directly between endpoints A and B. In this case, Communication
Manager would tell both A and B to stop using the Communication Manager address as
the far-end address and to start using the other endpoint as the far-end address. In other
words, A would be notified that B is now the far end and B would be notified that A is the
far end. Later Communication Manager may choose to change the path again due to
some change in the call, such as a conference or transfer. Each time the path changes,
the endpoints are notified via media control events to stop using the current far-end
address and to start using the new far-end address.

In server media mode all of this is usually transparent to the user, unless the codec
happens to change. In this case you may need to play a different wav file in the codec of
the new form. For this reason it is recommended that you give a single codec when
registering devices.

You should use Media.StartMonitor to set a monitor for the MediaStartEvent and
MediaStopEvent. When the RTP media changes, you will be notified by these events by
registering a Media.OnMediaStartedEvent and Media.OnStoppedEvent delegate. Use
the Dashboard tool to experiment and use the Visual Studio code snippets to help you
write the code.

Release 7.0.0
118 02-602658
Issue 1
Chapter 4: Recovery
This section informs you how to take advantage of the recovery feature to design a more
robust Device, Media and Call Control application.

The application session protocol has several recovery benefits for the Device, Media and
Call Control application. The “keep alive” (ResetApplicationSessionTimer) messages
that are sent periodically by the .NET API to the AE Services server provide a way for
the AE Services server to verify that the client application is still operational, even if there
is no other activity from the application. Similarly, the server response
(ResetApplicationSessionTimerPosResponse) messages allow the application to
verify that the AE Services server is also still responsive.

Note:
The “keep alive” message exchange is initiated and completely handled
by the .NET API. Also, the frequency of the “keep alive” messages
depends on the value of the “session duration” specified during the
initial creation of the application session.

The session cleanup delay provides a mechanism for the application to reestablish its
session after a short network interruption without having to reestablish their state (e.g.
register devices again).

Two important times are defined as part of the application session creation. These are:
• Session duration - the maximum time that the AE Services server will wait for a
timer reset, before moving the session to the inactive state. This timer is reset
when the server receives a ResetApplicationSessionTimer message from
the application.
• Session cleanup time – the amount of time that the AE Services server waits,
after the connection to the client has been lost. Once this time has expired, the
session, and any devices, monitors and device registrations associated with the
session, are cleaned up. This timer defaults to 0 for backwards compatibility
purposes, but it is recommended that it be set to a higher value, such as 60.

If a socket closes or if an active session is terminated by the AE Services server or

manually by an administrator, the application will receive a
ServerConnectionDownEvent.

In order for the application to be notified about some form of connection failure,
reconnect failure, or heartbeat failure, the application should implement the following
event/response handlers:

• ServiceProvider.OnStartApplicationSessionResponse
• ServiceProvider.OnServerConnectionDownEvent
• ServiceProvider.OnServerConnectionNotActiveEvent

Release 7.0.0
119 02-602658
Issue 1
 • ServiceProvider.OnMissedAtLeastOneKeepAliveEvent

Session Recovery
Since the session cleanup time delays the cleanup of a client application’s session, it
provides a mechanism for the application to reestablish its session after a short network
interruption. Following the short network interruption, the client application can resume
the same session, without having to reestablish its state information (e.g. monitor and
register devices again). This section tells you how to take advantage of these new
features to design a more robust Device, Media and Call Control application.

The best way to monitor for problems with a session is to monitor for
ServerConnectionDownEvents, ServerConnectionNotActiveEvents, and
MissedAtLeastOneKeepAliveEvents within the Service Provider object. The
following is a description of the events the application can receive and the proper
recovery actions to take in the case of each event.

• ServerConnectionDownEvent. This event is sent if the socket to the AE

Services server has gone down for some reason.

The recovery action to take for this event is to call reconnect on the application’s
ServiceProvider instance. This method will attempt to open a new socket to
the AE Services server, and to reestablish the existing session with a new
socket.
If successful, the application should be able to resume operations without
reestablishing its state although your application may have missed some events.
To be sure that you know the current state of the lamps, hookswitch and display,
you will have to query for those states using getLampState, getHookswitch
and getDisplay to update the states.
The operation may fail if the network is down, or if the session has been
terminated on the AE Services server because the cleanup timer expired. If the
session has already been terminated by the server, the getError() method
associated with the received StartApplicationSessionResponse will contain a
StartApplicationSessionNegResponse XML string with additional information
about the reconnect failure.
For example:
<StartApplicationSessionNegResponse xmlns="http://www.ecma-
international.org/standards/ecma-354/appl_session">
<errorCode>
<applError>
Terminated session can not be reconnected.
Reason: Session timer timed out
</applError>
</errorCode>
Release 7.0.0
120 02-602658
Issue 1
 </StartApplicationSessionNegResponse>

In order for the application to connect to the AE Services server again after a
session cleanup, a new ServiceProvider.StartApplicationSession request
will need to be issued. If any other exception or error message is received, like a
network failure, the application should set a timer and try to reconnect again at
some later time. Any requests that the application was trying to send that timed
out in the interval will generate an exception or error message from the SDK.

• ServerConnectionNotActiveEvent. This event is sent if a message was

received by the AE Services server but the session has timed out and been
placed in the inactive state. A session enters the inactive state if the Application
Session Duration expires before a ResetApplicationSessionTimer
message is received. Upon receiving this event, an application should take the
same recovery action as for the ServerConnectionDownEvent.

• MissedAtLeastOneKeepAliveEvent.This event comes in if the server has

missed at least one keep alive.

Note:
By default, the .NET Service Provider handles the automatic sending of
Keep Alives to the AE Services server for you. However, you can turn this
capability off via the StopAutoKeepAlive()method in the Service
Provider object (use StartAutoKeepAlive()method to start the
processing back up).

The following figure shows the sequence of events that occurs between the client
application, the API library and the AE Services server during establishment of an
application session, and an instance of a ServerConnectionDownEvent occurring
during subsequent session management.

Release 7.0.0
121 02-602658
Issue 1
 Figure 1: Session Management Recovery

Client Application API Library Connector Server

<Get Service Provider>

<StartApplicationSession>

<StartApplicationSessionResponse>

<GetServiceProviderResponse>

<ResetApplicationSessionTimer>

<ResetApplicationSessionNegResponse>

<ServerConnectionDownEvent>

<reconnect>

<StartApplicationSession>

<StartApplicationSessionResponse>

Transfer Monitor Objects

The TransferMonitorObject request of Device Services is used to transfer the
DeviceIDs for a given session to another session belonging to the same user. This
request will also transfer the listeners that were added for each DeviceID. This allows
one application instance to take over for another application instance in the event of a
failure.
Each deviceID and its established monitors are returned in a MonitorObjectData.
A list of MonitorObjectData is returned in the GetMonitorListResponse.
The processing of a TransferMonitorObjects request may cause event
notification to be interrupted if the client application has not set up the new session to
receive the original session's events. This can be achieved by retrieving the established
cross reference identifiers from the TransferMonitorObjects response. The

Release 7.0.0
122 02-602658
Issue 1
response will contain a MonitorStartResponse for each valid monitor that is
associated with a transferred device ID.
Important side effects and recommended client application actions:
• The client application must set up the new session to receive the events from
the transferred monitors.
• All the monitors for each device ID will be transferred from the original to the
new session.
• The original session will be removed at the end of the transfer.
• The client application must release the resources that were allocated for the
original session.
Note:
The transfer request should be issued from the new session in order to pull in the
transferred objects from the old session.

Use the Dashboard tool to experiment and use the Visual Studio code snippets to help
you write the code.

Release 7.0.0
123 02-602658
Issue 1
Chapter 5: Cleanup
If the cleanup session expires, resources are reclaimed. It is important to free resources
when they are no longer needed. This is most likely to occur when your application:
• detects the end of a call
• is finished with a device
• is about to exit

Cleanup should occur in this order:

1. Stop collecting tones
At the end of a call, you can choose to stop collecting DTMF tones for the
device. Alternatively, you can let the collection and the retrieval criteria continue
across calls. In that case you might just flush the buffer at the end of each call.
When finished with a device, stop the tone collection for that device.
When the application is about to exit, stop tone collection on all devices.
2. Stop recording or playing
At the end of a call, you can choose to stop recording or playing or let the
recording or playing continue across calls on the device.
When finished with a device, stop both recording and playing on that device.
When the application is about to exit, stop both recording and playing on all
registered devices.
Both recording and playing can be stopped on a device using the
Media.StopRecording and Media.StopPlaying request.
3. Unregister the device
When finished with a device, unregister it using the
Phone.UnregisterTerminal method.
When the application is about to exit, unregister each registered device.
Note:
If you fail to unregister a device, Communication Manager will keep the
device registered to the AE Services server indefinitely.

In addition, it is possible that this device is being controlled by more than

this application session. If this device is controlled by more than one
session, the various application sessions that are working with the device
should be communicating to determine whether or not the device should
be released before sending an unregister request. If this session is the
only session controlling the device, a negative acknowledgement will be
issued against the Device.ReleaseDeviceId request indicating that
unregistration is required before the device can be released.
4. Stop the monitor(s)

Release 7.0.0
124 02-602658
Issue 1
 When your application no longer needs to receive events for a device, stop the
monitors that were started using the StopMonitor() methods for the
appropriate services.
5. Release the device identifier
When finished with a device identifier, release it using the
Device.ReleaseDeviceID method.
When the application is about to exit, release each device identifier.
6. Stop the Application Session
Stop the application session by calling the StopApplicationSession method
on the application’s ServiceProvider instance.

Release 7.0.0
125 02-602658
Issue 1
Chapter 6: High Availability
AE Services 5.2 introduced a number of High Availability (HA) feature enhancements to
the platform. One of these feature enhancements is the AE Services 5.2 DMCC
Service Recovery feature, which increases the availability of the DMCC service to a
client application. This feature is available on all of the AE Services server platforms.
For additional information, please see the “DMCC Service Recovery” section. The other
HA feature was Fast Reboot High Availability (FRHA). With FRHA, the standby server
monitors the active server and takes over when the active server fails on a System
Platform High Availability configuration.
In AE Services 6.1 another HA feature was added to provide better support for Avaya
Aura® Communication Manager failover strategies. In particularly, it supports
Communication Manager’s failover to an Enterprise Survivable Server (ESS) and/or to
a Local Survivable Processor (LSP). For additional information, please see the “DMCC
Support of Communication Manager High Availability Using ESS and LSP Servers”
section.
In AE Services 6.2 another enhancement was added, Machine Preserving High
Availability (MPHA), which offered faster and smoother recovery than FRHA whenever
AE Services fails over to the standby server of a System Platform High Availability
configuration.
In AE Services 6.3.1, the Geo Redundant High Availability (GRHA) feature set was
introduced. GRHA was later enhanced in AE Services 7.0. The GRHA feature allows
the active and standby AE Services servers to be in either one or two different data-
centers separated by a LAN/WAN.
Note:
Starting with the AE Services 7.0 release, the System Platform offer, including
the FRHA and MPHA features has been dropped.
This chapter describes all of the High Availability features available with AE Services:
• AE Services Geo-Redundant High Availability
• DMCC Service Recovery
• DMCC Support of Communication Manager High Availability Using ESS and LSP
Servers
• Programming Considerations for High Availability

AE Services Geo-Redundant High Availability

(GRHA)
The AE Services on VMware offer, with GRHA, forms the basis of the AE Services
server High Availability Failover feature. With the High Availability Failover feature, you
can install two identical servers that can be addressed and administered as a single
entity. One server is active and provides service to client applications, while the other
server remains in standby mode, waiting to take over should the active server fail.
When the active server fails, the second server quickly and automatically becomes
Release 7.0.0
126 02-602658
Issue 1
available to client applications. Thus, the High Availability Failover feature is
synonymous with the Automatic Failover of the AE Services servers from the active
server to the standby.
Note:
This feature is only supported on the AE Services on VMware offer. It is
not supported on the AE Services Software-Only offer. Additionally, the
GRHA feature does not use, nor take advantage of, any of the inherent
VMware high-availability features and, in fact, the GRHA feature is
completely independent of any VMware HA implementation.

In the AE Services 6.3.1 release, GRHA was introduced as a HA option that allows the
active and standby AE Services servers to be in two different data-centers that are
separated by a LAN/WAN, provided that the maximum round trip network delay is
within 100 milliseconds. This ensured that failures that affect the entire data-center (for
example, a power failure) can be minimized.

In AE Services 7.0, the GRHA feature was enhanced to allow the active and standby
servers to be in the same data-center connected by a LAN, thus mimicking the FRHA
feature from previous AE Services releases.

A typical GRHA deployment might look like the following:

Active Standby
AES GRHA AES
VM VM

Active Active
VMware Host VMware Host
LAN/WAN
< 100ms RTT

Active datacenter Standby datacenter

For the purposes of this discussion, the term “controlled” failover refers to a failover
requested by either an administrator or by software logic, when it detects degradation
in state of health of the current active server. The term “uncontrolled” failover refers to a
failover which occurs because the current active server is not reachable from the
current standby server.

Release 7.0.0
127 02-602658
Issue 1
When a controlled failover occurs, AE Services are turned off on the current active
server and are turned on for the new active (previously standby) server. In the case of
an “uncontrolled” failover, AE Services are started on new active (previously standby)
server. Depending on the “uncontrolled” failover reason, the previous active could
continue to be in an isolated network, or it could be in shutdown state.

What does GRHA provide?

GRHA provides some very valuable features, such as:
• Protection against AE Services server failure
• Protection against data-center failure
• Protection against network failure (if configured).
• Preservation of provisioned and other configuration data. The data provisioned
via the AE Services Management Console, and other means, is copied from the
active server to the standby. After a failover, the new active server will have the
same provisioning data as before.
• The need for only one set of AE Services licenses, for both AE Services servers
(active and standby).
• The AE Services server on each datacenter can be in different networks or
subnets.
• A set of one or more virtual IP addresses, used to represent a HA pair of AE
Services servers, can be used to automatically point to whichever GRHA AE
Services server is active. This assumes that the virtual IP addresses can span
both data-centers – for example, when both data-centers are part of an
extended layer-2 network.
• GRHA utilizes very little CPU resources, and therefore does not impact AE
Services server capacities.
• Three levels of GRHA licenses are available: SMALL, MEDIUM and LARGE.
Please refer to the Avaya Aura® Application Enablement Services
Administration and Maintenance Guide, section “Administering the Geo
Redundant High Availability feature” for more information.
• When a virtual IP address is used to connect the AE Services servers to
Communication Manager, AE Services may be able to preserve or reconstruct
the following DMCC objects:
o Sessions
o Device
o Device and Call Monitors
o Device Registrations
o System Registrations
o Recording Warning Tones

What does GRHA not provide?

Note that, for this release, GRHA does not provide the following:

Release 7.0.0
128 02-602658
Issue 1
 • Preservation of the current state of the system (if a virtual IP address is not
used for the Communication Manager connections). After a GRHA failover has
occurred, and once the application has connected to the new active AE
Services server, the application must re-establish any:
o Sessions
o DeviceIDs
o Device and Call Monitors
o Device Registrations
o System Registrations
o Recording Warning Tones
• Protection against AE Services software failures. However, DMCC Service
Recovery (discussed in the next section) does recover from software failure.
• Service on IPv6 networks. Currently, GRHA is only supported on IPv4 networks.

Effect of controlled/uncontrolled failover on AE Services clients

For this release, AE Services clients must have the ability to connect to two AE
Services IP addresses, or one virtual IP address used for Client Connectivity. When
failover occurs, the client application must detect a session (or socket) drop. Then, it
should attempt to get service from the same AE Server for a couple of times. If the
session cannot be reestablished, it should then try the “other” AE Services server IP
address to get service.
If the client connects using a new session, it must re-establish all deviceIDs and,
monitors, as well as re-register all the endpoints as if AE Services server came out of a
reboot.
The time it takes for the client to start receiving service would depend on the total time
associated with following activities:
• Time taken by the standby AE Server to detect failure. This depends on the
administered “failure detection” interval, and applies only in case of uncontrolled
failover. For controlled failover this time is close to 0.
• Time it takes for AE Services to be activated on the new active server.
Currently, this time is approximately 1 minute.
• Time it takes for the client application to connect to the new AE Server and to
recreate all of its devices, monitors and registrations.

DMCC Service Recovery

DMCC Service Recovery is an implementation within the DMCC subsystem of AE
Services. It is a software feature designed to recover one or more DMCC devices’
previous states, following a software fault (or shutdown) that does not allow the DMCC
Java Virtual Machine (JVM) to exit normally. The recovery attempts to re-create the
state of the DMCC service prior to the fault. It does this by reading from a persisted
store that contains selected state information for each DMCC session, device, monitor
and registration.
Release 7.0.0
129 02-602658
Issue 1
The DMCC Service Recovery feature was introduced for AE Services 5.2 and is
available on all AE Services offers Note that on a single server, the feature will not
guard against a hardware failure, but it will allow your application to retrieve its state
when a software failure leads to a restart of the AE Services software. Alternatively,
when used in conjunction with the AE Services on VMWare offer, this combination of
features will allow your application to retrieve its state even when there is a hardware
failover to the standby server.
Note:
In order to recover DMCC registrations, the device(s) must be registered
using the Communication Manager Time-to-Service (TTS) feature. This
does not affect the way that the client application registers the device(s)
via the AE Services server. However, the Time-to-Service feature must
be enabled for the appropriate “IP network region” on Communication
Manager, otherwise DMCC will not be able to perform a service recovery
of the device registration(s). For more information on enabling the Time-
to-Service feature, see the “AE Services Administration Guide”.

Why is DMCC Service Recovery needed?

DMCC Service Recovery increases the availability of the DMCC Service to a client
application. This is achieved by reducing the time needed to reconstruct runtime state
information within DMCC, following a JVM restart. Also, since the reconstruction is
done automatically, it relieves the client application of the responsibility of
reconstructing the state. Finally, it reduces the traffic between the client application and
DMCC service when recovery actions are needed.

When is DMCC Service Recovery used?

The DMCC Service goes through its life cycle management steps whenever it’s Java
Virtual Machine (JVM) platform is restarted. The initialization step of life cycle
management is responsible for using the DMCC Service Recovery feature. The JVM
may be restarted due to:
1. An unrecoverable software error condition.
2. An administrator initiated restart of AE Services.
3. A reboot of an AE Servics server.
4. A failover operation from one AE Services Virtual Machine (AE Services VM) to
another one on the same High-Availability setup (GRHA).

How does DMCC Service Recovery work?

As in prior releases, a session is created for a client application when it is authenticated
by the DMCC service. Starting with AE Services 5.2, information about the session is
added to persistent storage before the StartApplicationSession response is sent to the
client. This persisted information is used to reconstruct the session in the event of a
JVM restart. Similarly, the session information is removed from persistent storage when
Release 7.0.0
130 02-602658
Issue 1
a StopApplicationSession request or an administrator request or a session cleaned up
event is processed by the DMCC service.
Similarly for DMCC Device Services, (as in previous releases) a device is created for a
client when a GetDeviceID request is processed by the DMCC service. Starting with AE
Services 5.2, the device information is added to persistent storage before the response
is sent to the client. This persisted information is used to reconstruct the deviceID in the
event of a JVM restart. Again, the device information is removed from persistent
storage when a ReleaseDeviceID request or an administrator request or a session
cleaned up event is processed by the DMCC service.
Also as in previous releases, a monitor is created for a client when a MonitorStart
request is processed by the DMCC service, or a ChangeMonitorFilter request changes
the filter configuration of the monitor. Starting with AE Services 5.2, the monitor
information is added to persistent storage before the response is sent to the client, and
removed from persistent storage when a MonitorStop request or a session cleaned up
event is processed by the DMCC service.
Finally, as usual, a device registration is performed for an endpoint (extension) when a
RegisterTerminal request is processed by the DMCC service. Again, starting with AE
Services 5.2, the registration information is added to persistent storage before the
response is sent to the client, and the registration information is removed from
persistent storage when an UnregisterTerminal request or a session cleaned up event
is processed by the DMCC service.
Following a DMCC JVM restart, the initialization of DMCC follows the same order of
precedence as for the original creation of the session etc. In other words, when DMCC
is restarted, it will read any state information available in the persistent store. Then, it
will proceed to recover the runtime state, from this persisted data, by reconstructing its
internal data objects, and thus reproducing the previous state that the client
applications were aware of. The recovered session data is applied first, followed by
device data, and then concurrently for monitor and registration data.
To a client application, a DMCC JVM restart should manifest itself as a temporary
outage of the connection between the client and the AE Services server. Thus, on
detecting such an outage, the client application should attempt to re-establish the
connection and its associated DMCC session(s).
Note:
In order to recover DMCC registrations, the device(s) must be registered
using the Communication Manager Time-to-Service (TTS) feature. This
does not affect the way that the client application registers the device(s)
via the AE Services server. However, the Time-to-Service feature must
be enabled for the appropriate “IP network region” on Communication
Manager, otherwise DMCC will not be able to perform a service recovery
of the device registration(s). For more information on enabling the Time-
to-Service feature, see the “AE Services Administration Guide”.

How does DMCC Service Recovery differ from releases prior to AE Services 5.2?

Release 7.0.0
131 02-602658
Issue 1
The DMCC Service Recovery subsystem may cause the AE Services server to act a
little differently to previous releases. The following is a list of points to keep in mind when
dealing with AE Services 5.2 and later:
• The DMCC Service recovery time will vary depending on the number of call
control service monitors and H.323 registrations that need to be recovered. This
is because such recovery actions require asynchronous protocol messaging to
the Communication Manager across an IP network.
• A recovered session that is not re-established by the client application will be
released:
o Immediately if the cleanup timeout value equals 0 mins.
o After 5 minutes if the cleanup timeout value is less than 5 mins.
o After the cleanup timeout expires if it is more than 5 mins.
• There is no event to indicate that DMCC service recovery has completed.
However, there are events to indicate that a registration or a monitor was lost
during recovery. In contrast, the loss of a session will be detected when an
attempt to re-establish it fails. Similarly, the loss of a device will be detected
when a device based API service request fails.
Note:
For the AE Services on VMware offer, the GRHA failover may take a few
minutes, and so, any session re-establishment failures within this
interval will not be valid.
• In general, a recovered session can be re-established before the reconstruction
of its associated runtime state is completed. This can lead to undesirable
behavior, if the client application assumes that all reconstruction was
completed. A client application may explicitly determine whether a given
resource is ready to be used, through the existing API methods
GetSessionIdList, GetDeviceIdList, GetMonitorList and
GetRegistrationState. It can implicitly determine readiness of a resource
from the responses to other API service requests.
• Some requests or events in progress at the time of the failover may be lost,
although every effort will be made by the AE Services server to retain all
requests in progress.
• Only Time-to-Service (TTS) H.323 registrations can be recovered by the DMCC
service. The client application is responsible for recovering (i.e. re-registering)
all non-TTS registrations.
• DMCC Service Recovery will not preserve an “in-progress” server-media
recording or playback of a “wav” file. However, following the successful
recovery of the device registration(s) after a fault, a new recording or playback
may be started on the device(s).

How does Time-to-Service Support differ from releases prior to AE Services 5.2?
Note:
Release 7.0.0
132 02-602658
Issue 1
 The DMCC Service Recovery subsystem relies on the Time-to-Service
feature of Communication Manager to allow the recovery of device
registrations.
Some side-effects of TTS registration include:
• The RAS keep-alive messages between the AE Services server and
Communication Manager, for each device registration, are much less frequent.
Instead of occurring every minute (as for non-TTS registrations), the keep-alive
messages will be sent only every 7 hours, under some conditions.
• The Q931 signaling channel between the AE Services server and
Communication Manager, for each device registration, may be torn down by
Communication Manager, and re-established when needed. The loss of the
signaling channel will no longer cause the endpoint to be unregistered.
• If a client application makes a request that requires the Q931 signaling channel
(e.g. an off-hook or on-hook request), there may be a slight delay (usually
milliseconds) while the signaling channel is re-established.

DMCC Support of Communication Manager High

Availability Using ESS and LSP Servers
DMCC support of Communication Manager’s High Availability was introduced in AE
Services 6.1. This feature is available on all AE Services offers (VMware and Software-
Only).
Note:
It does not guard against a failover of the AE Services server itself. Instead, it
guards against the possibly unfortunate consequences resulting from a failover
of the Communication Manager server.
Like “DMCC Service Recovery” feature, DMCC Support of ESS & LSP is a software
feature designed to recover one or more DMCC devices’ previous states. However, in
this case, the recovery follows a software fault (or shutdown) that causes the
Communication Manager to failover to an Enterprise Survivable Server (ESS) or to a
Local Survivable Processor (LSP). The DMCC recovery procedure attempts to restore
the registration state of the DMCC stations prior to the fault.

Why is ESS and LSP support needed?

Prior to AE Services 6.1, the failover of Communication Manager from the Main to an
ESS or an LSP would result in all previously registered DMCC stations becoming
unregistered. The client application would receive a TerminalUnregisteredEvent for
each station, with an indication that connection to the CM had been lost - but no further
information was included. It was then up to the application to attempt to re-register with
the Main and, if that failed, to re-register with an ESS or LSP. The application would
need to know the IP addresses of the CLANs or Processor Ethernet connections to

Release 7.0.0
133 02-602658
Issue 1
each ESS and LSP, since registration to anything other than the Main, using the
switchName, was not possible.

What has changed?

In AE Services 6.1, this situation was widely improved. If ESS/LSP support has been
properly administered, then:
• A failover of CM from Main to ESS or LSP will be detected by the AE Services
Transport server. This information will be automatically passed on to DMCC.
• DMCC will then unregister the stations from that particular Main, and re-register
them with the appropriate ESS or LSP node. This is done automatically by
DMCC, and no intervention from the client application is required.
• If the re-registration is successful, it is completely transparent to the client
application, except that the client will receive a TerminalReregisteredEvent (if
monitored) for that station. If the re-registration fails (for any reason), then the
client application will receive a TerminalUnregisteredEvent (if monitored).
• Similarly, a switch from the ESS or LSP back to the Main CM will be detected
by the AE Services Transport server, and DMCC will be informed. Note that this
switch back to Main can be administered to be either automatic or controlled.
• Again, DMCC will then unregister the stations from that particular ESS or LSP
node, and re-register them with Main. This is done automatically by DMCC, and
no intervention from the client application is required. The re-registration is
completely transparent to the client application, except for the receipt of another
TerminalReregisteredEvent (if monitored), unless a failure occurs.
Note:
In all cases in which a re-registration must be performed, any active call
on the device will be terminated.

How is ESS and LSP support administered?

In AE Services 6.1 amd later releases, the user has the option of administering a
survivability hierarchy for each “Switch Connection”, via the AE Services Management
Concole web pages. The AE Services Transport server will manage all of the
connections to the ESS and LSP nodes (as well as to the Main).
From the “Switch Connections” page, the user can still specify the IP address(es) of the
Processor Ethernet or the CLANs used by the Main Communication Manager server
(as previously in AE Services 5.2 and earlier releases). However, additionally, the user
may specify:
• a list of ESS and/or LSP nodes, including their Processor Ethernet IP
addresses.
• a priority order/hierarchy for the nodes.

Release 7.0.0
134 02-602658
Issue 1
This list and its hierarchy will be used by the AE Services Transport server (in
conjunction with the Communication Manager nodes themselves) to determine which
Switch Connection is active, at any given time, and (hence) which nodes are providing
service.

Programming Considerations for High Availability

As mentioned earlier, an AE Services failover to a standby server or a DMCC JVM
restart on the same server should manifest itself as a temporary outage of the
connection between the client and the AE Services server. The duration of the outage
depends on a number of factors:
• the type of failover
• the number of DMCC sessions currently established
• the number of DeviceIDs currently in use
• the number of devices currently registered
• the number of device and/or call monitors currently in use

Typically, the outage can last anywhere from one to several minutes depending on the
factors mentioned above.
On detecting a temporary network outage, the client application should attempt to re-
establish the connection and its associated DMCC session(s).
The DMCC Dashboard can be used to simulate session recovery and failover by
unchecking the “Auto Cleanup” checkbox at the top of the Main dashboard screen.

Release 7.0.0
135 02-602658
Issue 1
Chapter 7: Media Encryption
Application Enablement Services offers the user the ability to encrypt the voice RTP
streams between the DMCC softphone and the far end of the call when the application
chooses to use server media mode.

For Application Enablement Services, the only encryption scheme available is the
Advanced Encryption Standard (AES) media encryption.

Note:
This Chapter was taken from the DMCC Java Programmers Guide to be
used as a reference for .NET developers. A future release of this
document will provide the .NET equivalent of the Java Cryptography
Extension (JCE) code examples.

The AES Encryption Scheme

1. Encrypting the Voice Stream
To transmit voice information over a digital medium, the analog voice signal is
sampled at discrete intervals. Each sample is represented as an 8-bit number or
8-bit byte. Samples (bytes) are transmitted sequentially as a stream of bits. If a
G.711 codec is used to generate the samples and if 20 milliseconds worth of
data is sent in each Internet Protocol (IP) packet, then each packet will contain
160 bytes which equals 1280 bits. (8000 samples/second for 20 milliseconds).
To send the voice data, the stream of voice bits is exclusive OR’d with a second
stream of bits before being transmitted. This second stream of bits is generated
cryptographically and the resulting transmitted stream is said to be “encrypted”.
The two bit streams are processed in fixed “chunks” of 128 bits as illustrated in
Figure 2

Figure 2: Encryption of the Voice Stream

IV IV+1 IV+2

Key = Ke AES Key = Ke AES Key = Ke AES

Voice Bits Voice Bits Voice Bits

0-127 128-255 256-383 Release 7.0.0
136 02-602658
Issue 1
Transmitted Transmitted Transmitted
Bits 0-127 Bits128-255 Bits 256-383
 A 128 bit initialization vector (IV) is encrypted with key KE (128 bits) using the
AES encryption algorithm to produce 128 bits of output. Those 128 bits are
exclusive OR’d with the first 128 bits of the voice packet. The initialization vector
is incremented by one, and the process repeated for the next 128 bits. Ten
repetitions are required to send one 20 millisecond packet which contains 1280
bits of voice data. This means that the AES encryption engine is run 10 times to
send one packet. This mode of using AES is called counter mode (because the
IV acts as a counter).
On the receiving end, the same process is used to recover the original voice
data. The receiver must have the exact same key (KE) and the same
initialization vector (IV).
2. Generating Key Material
In order to generate the encryption key, initialization vector, and other keys to be
seen shortly, the following operations are performed. Note that these
computations are performed anew for each RTP packet.
Let the packet index “i” be defined as:
i = (32-bit ROC) || (SEQ for RTP)
where ROC is the roll over counter, SEQ is the 16-bit sequence number from the
RTP packet and || indicates concatenation. This is shown in Figure 3.

Figure 3: Structure of the Packet Index

32 bits of ROC 16 bits of SEQ 48 bit packet index, i

Let
r=i DIV key_derivation_rate
where DIV denotes integer division rounded down with the convention that
dividing by 0 equals 0. The SRTP algorithm supports changing the keys
periodically, even while the voice stream is active. The key derivation rate is the
rate of this change. A value of zero indicates that the keys are not changed
periodically. When the rate is zero, “r” is also zero (48 bits). Note that in the first
computation of “r”, the value of SEQ used in the computation of “i” is the initial
value at the beginning of the media stream.
Release 7.0.0
137 02-602658
Issue 1
 Let
key_id = <label> || r
where <label> = 0x00 for RTP packet encryption and 0x02 for the salting key
used to generate the IV as illustrated in Figure 4 .

Figure 4: key_id Structure

48 bits of "i" DIV key_derivation_rate 56 bits of key_id

8 bits of label

Let x = key_id XOR master_salt

This is shown in Figure 5:

Figure 5: Computation of ’"x"

The keys for encryption and IV generation are the result of encryption of (“x” *
216) with a key called the master key. (The master key is distributed by the Media
Gateway Controller for each voice IP media link as the link is established.)
The values of “x” for Avaya’s implementation are shown in figure 6. Note that
two values of “x” are computed, one (xe) is used to compute the value of KE and
a second value of “x” (xs) is used in the computation of the IV.
For Avaya’s implementation: Key_derivation_rate = 0 Master_salt =
0

Figure 6: Values of "x" for Avaya’s Implementation

Release 7.0.0
138 02-602658
Issue 1
 3. Creating the Initialization Vector
The Initialization Vector (IV) changes for each packet (1280 voice bits for 20ms
G.711) according to the following equation: IV = (SSRC * 264) XOR (KS *
216) XOR (i * 216)
where KS is known as the session salting key and SSRC is the synchronization
source from the RTP packet currently being encrypted. Note that “i” contains the
packet sequence number SEQ and therefore the IV must be recalculated for
each RTP packet.
The 112 bit KS is computed from xs using the pseudo random function (PRF) as
follows.
KS = PRF_112 (master_key, xs * 216)
The pseudo random function is defined to be AES in counter mode with its
output stream truncated as necessary (left most bits are retained).
The process for IV generation is shown in Figure 7.

Figure 7: 128-bit IV Generation

4. Creating the Encryption Key KE

Release 7.0.0
139 02-602658
Issue 1
 The process for generating the session key (KE) uses the pseudo random
function (AES in counter mode) to produce a 128 bit value as follows: KE =
PRF_128 (master_key, xE * 216)

Specifying the Devices’ Encryption Capability

You may control whether your DMCC softphone will support media encryption or not by
specifying the supported encryption types in the local MediaInfo structure:

// specify either AES or no encryption for this device (let CM choose)

String [] encryption = {MediaConstants.AES,
MediaConstants.NOENCRYPTION};
MediaInfo localMediaInfo = new MediaInfo();
localMediaInfo.setEncryptionList(encryption);
station.register (password, false, localMediaInfo, new
MyAsyncRegistrationCallback());

This specifies that the DMCC softphone will support both AES encryption and no media
encryption. In this case, the decision to encrypt the media stream is left up to the
Communication Manager (as specified in the CM’s “change ip-codec” form).

Alternatively, you may force AES media encryption to be chosen by specifying a

supported encryption type of only AES:

// must use AES encryption

String [] encryption = {MediaConstants.AES};

and, of course, you may force no encryption to be chosen by specifying:

// encryption not supported

String [] encryption = {MediaConstants.NOENCRYPTION};

MediaStartEvent Handling
If you have chosen to receive and handle the media stream as part of your application
(you have chosen client-media mode), you will receive the media encryption information
in the MediaStartEvent. In addition to the usual “RTP address”, “RTP port”, “codec”
etc., the MediaStartEvent will also contain an “Encryption” object containing the
encryption protocol and keys chosen by Communication Manager.

When you start to process the RTP stream, you need to pass the encryption information
to your RTP stream read/write methods to enable them to do the media
encryption/decryption. On receipt of a new MediaStartEvent, you must use the new
encryption keys provided in the event, recalculate the Initialization vector (IV), and reset
the Roll Over Counter (ROC).

If you are using Avaya’s client-media-stack, you may call the Audio “start” method (as
usual) passing the encryption information as an extra parameter:
Release 7.0.0
140 02-602658
Issue 1
MediaEncryption encryption = new MediaEncryption();
encryption.setProtocol(startEvent.getEncryption().getProtocol());
encryption.setTransmitKey(startEvent.getEncryption().getTransmitKey());
encryption.setReceiveKey(startEvent.getEncryption().getReceiveKey());
encryption.setPayloadType(startEvent.getEncryption().getPayloadType().i
ntValue());
audio.start(rtpAddress, rtcpAddress, codec, packetSize, encryption);

Media Encryption Information

The Encryption object in the MediaStartEvent contains the following information:
• Encryption protocol
• Separate media encryption transmit and receive keys
• Payload type

For release 3.1, the encryption keys and the payload type are only required if the
encryption protocol is “MediaConstants.AES”.

For SDK compatibility reasons, the transmit and receive keys are formatted as Strings.

For example, the transmit key may be in the form:

String transmitKey = “{38,4F,0B,34,DF,00,2A,BE,F0,C7,55,80,1D,1D,33,A8}”

and similarly for the receive key. The curly braces and commas are actually part of the
String. In order to be used by the encryption/decryption routines, the keys need to be
converted to byte arrays of the form (for example):

byte[] txKey = { 0x38, 0x4F, 0x0B, 0x34, 0xDF, 0x00, 0x2A, 0xBE, 0xF0,
0xC7, 0x55, 0x80, 0x1D, 0x1D, 0x33, 0xA8 };

If you use Avaya’s client-media-stack, the Audio “start” method will automatically do the
String to byte[] conversion for you.

Encrypting and Decrypting the RTP Stream

The encryption transmit and receive keys, along with the roll over counter (ROC) plus
the RTP header’s SSRC and sequence number, are used to calculate the Initialization
Vector.

Roll Over Counter (ROC)

The ROC (initially set to zero) is a 32-bit unsigned integer which records how many
times the 16-bit RTP sequence number (SEQ) has been reset to zero within the same
SSRC (after incrementing up through 65,535) Unlike the sequence number (SEQ),
which your secure RTP implementation (SRTP) extracts from the RTP packet header,
Release 7.0.0
141 02-602658
Issue 1
the ROC is maintained by the header of each RTP packet. The ROC must also be
knowledgeable of the SSRC that is included in the header of each RTP packet. The
SSRC is a 32 bit randomly chosen value in an RTP packet that is used to represent the
synchronization source (RFC1889). From one MediaStartEvent to the next
MediaStopEvent, the SSRC will remain the same. If the SSRC changes this is usually
an indication that a new RTP stream has started. However, note that it is also possible
for a new RTP stream to start without changing the SSRC. Thus, if a new
MediaStartEvent is received, then a new RTP stream is deemed to have started.
When this situation occurs the new encryption keys (included in the event) must be
used, the Initialization Vector (IV) must be recalculated, and the ROC must be reset to
zero.

// Increment the ROC whenever the sequence number rolls over

incomingReadSSRC = rtpHdr.ssrc;
incomingSeqNum = rtpHdr.seqNum;
if (currentReadSSRC == incomingReadSSRC) {
if (incomingSeqNum > currentSeqNum) {
// Do nothing
} else if (incomingSeqNum < (currentSeqNum - 100)) {
// Sequence number has probably rolled over
++readROC;
} else {
// out of sequence RTP packet - ignore it
return 0;
}
} else if (incomingReadSSRC == prevReadSSRC) {
// very late RTP packet from previous call - ignore it
return 0;
} else {
// New SSRC (i.e. new call) - reset ROC
readROC = 0;
prevReadSSRC = currentReadSSRC;
currentReadSSRC = incomingReadSSRC;
}
currentSeqNum = incomingSeqNum;

and similarly for writeROC.

Creating the Encryption Keys Using the Pseudo Random Function

The pseudo random function PRF_n(key,x) produces a bit string of length “n” from a
string “x” which is encrypted using the encryption key named “key”. The AES Symmetric
algorithm mode is “ECB” with no padding.

private status final byte Xe{} =

{0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,}
// Set up and initialize JCE Engine
SymmetricEncryptionEngineIF see =
SymmetricFactory.getInstance().createFactory(
SymmetricFactory.AES);
see.initializeEngine("ECB","NoPadding");
// Generate the symmetric key using the JCE Engine and the
Release 7.0.0
142 02-602658
Issue 1
 // readMasterKey from the
// MediaStart event and then use the AVAYA XE value to calculate
// the Ke-Rx value
see.generateKey(readMasterKey);
Ke-Rx = see.encryptBlock((Xe);

And, similarly for Ke-Tx based on the writeMasterKey.

Once the media receive and transmit encryption keys (Ke-Rx and Ke-Tx) are created,
they will be used within the AES algorithm to encrypt and decrypt the RTP stream.

Creating the Initialization Vectors (IV)

The ROC, together with the media encryption keys from the MediaStartEvent, the
SSRC and the RTP header sequence number are used to calculate the IV for each
direction (transmit & receive):

private static final byte Xs-Rx[] =

{0,0,0,0,0,0,0,2,0,0,0,0,0,0,0,0};
byte[] Ks-Rx = new byte[14];
ByteBuffer ssrcBuffer = ByteBuffer.allocate(16);
ByteBuffer KsBuffer = ByteBuffer.allocate(16);
ByteBuffer iBuffer = ByteBuffer.allocate(16);

// Convert the RTP header sequence number to bytes

byte[] seqHex = convert2Bytes(seq);
// Clear the local 16-byte buffers used in the IV calculation
ssrcBuffer.clear();
KsBuffer.clear();
iBuffer.clear();

// Softphone PRF version

// Set up and initialize JCE Engine
SymmetricEncryptionEngineIF see =
SymmetricFactory.getInstance().createFactory(
SymmetricFactory.AES)
see.initializeEngine("ECB","NoPadding");

// Generate the symmetric key using the JCE Engine and the
// readMasterKey from the
// MediaStart event and then use the Acaya Xs value to calculate
// the Ks-Rx value
see.generateKey(readMasterKey);
Ks-Rx = see.encrypBlock(Xs);
KsBuffer.put(Ks-Rx, 0, Ks-Rx.length-2);

And, similarly for Ks-Tx based on the writeMasterKey

// Grab the SSRC from the RTP header and populate the SSRCbuffer
ssrcBuffer.position(4);
ssrcBuffer.putInt(ssrc);

// Setup and populate the iBuffer - this will currently

Release 7.0.0
143 02-602658
Issue 1
 // make the roll over counter to be zero always
iBuffer.position(8);
iBuffer.putInt(readROC);
iBuffer.put(seqHex[2]);
iBuffer.put(seqHex[3]);

byte[] ssrcBytes = ssrcBuffer.array();

byte[] ksBytes = KsBuffer.array();
byte[] iBytes = iBuffer.array();
byte[] iv-Rx = new byte [16];
iBuffer.put(seqHex[2]);
iBuffer.put(seqHex[2]);

// XOR all 3 buffers

for (int ii = 0; ii < iv-Rx.length; ii++) {
iv-Rx[ii] = (byte)(ssrcBytes[ii] ^ ksBytes[ii] ^ iBytes[ii]);

and similarly for calculating the write buffer IV (iv-Tx).

Decrypting the Media Payload

In the draft SRTP specification, the encryption algorithm is defined as AES in counter
mode (CTR and NoPadding). The generated IVs, along with the Ke-Rx or Ke-Tx, can be
used to secure the RTP stream during each transmit and receive operation.
// get the RTP packet from the read socket
ByteBuffer dst = rtpPacket.getPacket();

// Point to payload start and obtain the encrypted payload

int hLength = 12; (RTP header size)
pLength = dst.limit() – hLength; (RTP payload size)

dst.position(hLength);
byte[] buf2 = new byte[pLength];
dst.get(buf2, 0, pLength);

// Decrypt payload
byte[] buf3 = decryptEngine.decryptBlock(buf2, iv-Rx, Ke-Rx);

The decryptBlock will look something like the following:

// decryptBlock sample code
Public byte[] decryptBlock(buf2, iv-Rx, Ke-Rx){
// Set up cipher engine
SymmetricEncryptionEngineIF see =
SymmetricFactory.getInstance().createFactory(
SymmetricFactory.AES);
see.initializeEngine("CTR", "NoPadding");

// Pass to JCE etc. . . .

see.decrypt(buf2, iv-Rx, Ke-Rx);
}

Release 7.0.0
144 02-602658
Issue 1
Test Data
In order to validate your code, we present here some test data against which you may
run your decipher code. Following that is the expected output.

• Input Data
// From the MediaStart event, we get
byte[] readMasterKey = {
(byte)0xaa,(byte)0xaa,(byte)0xaa,(byte)0xaa,

(byte)0xaa,(byte)0xaa,(byte)0xaa,(byte)0xaa,

(byte)0xaa,(byte)0xaa,(byte)0xaa,(byte)0xaa,

(byte)0xaa,(byte)0xaa,(byte)0xaa,(byte)0xaa
};

// From the RTP packet, we get

int ssrc = 987011809;
int seq = 3;
int roc = 0;

// And the data to decipher is:

cipherData = {(byte)0xbb,(byte)0xbb,(byte)0xbb,(byte)0xbb };

• Expected Output
Ke-Rx:
(byte)0xba, (byte)0xeb, (byte)0xc6, (byte)0x18, (byte)0xa5,
(byte)0x5c, (byte)0x35, (byte)0x1f, (byte)0x25, (byte)0xce,
(byte)0xdf, (byte)0x37, (byte)0xbf, (byte)0x70, (byte)0xf3,
(byte)0x90
Ks-Rx:
(byte)0x98, (byte)0x12, (byte)0xf4, (byte)0x3c, (byte)0x17,
(byte)0xc5, (byte)0xd4, (byte)0x0e, (byte)0xe3,
(byte)0x8f, (byte)0x09, (byte)0xe1, (byte)0x7f, (byte)0xa8,
(byte)0xba, (byte)0xb7
IV-Rx:
(byte)0x98, (byte)0x12, (byte)0xf4, (byte)0x3c, (byte)0x2d,
(byte)0x11, (byte)0x4e, (byte)0xef, (byte)0xe3,
(byte)0x8f, (byte)0x09, (byte)0xe1, (byte)0x7f, (byte)0xab,
(byte)0x00, (byte)0x00

// And the deciphered data should be:

plainData = {(byte)0x05, (byte)0x43, (byte)0x2a, (byte)0x3d };

Release 7.0.0
145 02-602658
Issue 1
Chapter 8: Security Considerations
Your application development organization has the responsibility of providing the
appropriate amount of security for your particular application and/or recommending
appropriate security measures to your application customers for the deployment of your
application. Therefore you should be aware of the security measures that AE Services
Device, Media and Call Control API already take and what risks are known.

In addition to the advanced authentication and authorization policies outlined in the next
section, Application Enablement Services provides these basic security measures:

• Username and password are authenticated by the Device, Media and Call
Control service. Optionally, user authentication can be disabled by provisioning
a security policy for a machine, as detailed in the “Advanced Authentication and
Authorization Policies” section below.

• Authorization Measures:
The DMCC service supports three different authorization mechanisms. See the
"Advanced Authentication and Authorization Policies" section for more details.

- Security Database (SDB). This is the default authorization mechanism.

- LDAP based authorization

- Unrestricted Access

AE Services performs an authorization check on each data request that is based

on one or more SessionID’s, by making sure that each one belongs to the same
user who made the request. This applies to GetDeviceIdList,
GetMonitorList and TransferMonitorObjects requests.
• The station password is required to register a device.

• Filenames specified for recorded files must be relative to the configured

directory, their directories must already exist, and recordings cannot overwrite an
existing file.

• Only files within the configured recorder directory can be deleted using the
Media.DeleteMessage method.

Application Enablement Services offers the user the ability to encrypt the voice RTP
streams between the IP softphone and the far end of the call. See Chapter 7: Media
Encryption for more information.

If you are using encryption, AE Services Device, Media and Call Control API provides
these additional security measures:

• The signaling and bearer channels are encrypted.

Release 7.0.0
146 02-602658
Issue 1
 • XML messages transmitted between the client application and the AE Services
server software are encrypted.
• The station password is passed encrypted.
• Username and password are encrypted.
Note:
If you do not use SSL/TLS encryption on the client link, there is no
encryption of XML messages transmitted between the client application
and the AE Services server software. In this case, the station password is
passed unencrypted and, similarly, the username and password are also
sent unencrypted.

For a complete discussion of the security guidelines for AE Services, see the White-
paper on Security in Avaya Aura® Application Enablement Services. This white paper is
available on the Avaya support site along with the customer documents.

Advanced authentication and authorization policies

Starting with AE Services 5.2, new options were added for provisioning of
authentication and authorization policies to specific application servers based on PKI
(Public Key Infrastructure). The User Authentication and Authorization (AA) policies
will first be detailed separately. Then several use cases will be provided to illustrate
how these policies can be applied to provide new AA models for applications to
leverage.
In order to apply AA policies to a machine, it is necessary to have checked the “Require
Trusted Host Entry” field in the AE Services Management Console pages. It is critical
to the security model that the identity of the application machine be validated and that
they are considered a trusted host in order to suspend otherwise required user
authentication / authorization administration.
It is also important to note that in order for DMCC to properly authenticate the
application machine, that application must have been provisioned with a certificate and
associated private key that identify that machine. The machine’s identity can be
provided in either the Common Name field or the Subject Alternative Name (SAN) field.
DNS and IP Address SAN types are accepted. The provided certificate must have
been signed by a certificate authority (CA) that has been provisioned in AE Services as
being a trusted CA.
Note:
For AE Services 6.3.3 and later, the AE Services Management Console
also contain provisions for certificate authentication on the
Communication Manager interface, as well as the client interface. For
more information on certificate authentication for both interfaces, see the
“AE Services Administration & Maintenance” document and the “AE
Services White Paper on Security” (available for download on the Avaya
Support site) for more information.
Release 7.0.0
147 02-602658
Issue 1
User Authentication Policies
The User Authentication policy setting allows an administrator to specify whether or not
user-level authentication is required for sessions originating from the application
machine. If the administrator disables user-level authentication, the far end machine
can still supply a username through the normal mechanisms, but the password will be
ignored. This allows the application machine to assert a user identity that could still be
used for authorization purposes. In order to assert a user identity, the application
machine should have somehow authenticated the user.

User Authorization Policies

There are three different authorization policies that can be applied: SDB, Enterprise
Directory, and Unrestricted Access.

SDB
This authorization policy states that the AE Services Security Database (SDB) shall be
used for authorization. When this policy is applied, DMCC applies SDB-based
authorization exactly as it did in previous releases of AE Services.
AE Services can optionally enforce an authorization policy as specified in the Security
Database (SDB) to ensure that only authorized users can monitor and control a given
device.
The SDB allows an administrator to give a user control of a specific device or list of
devices. An administrator can also allow a user to monitor/control any device by
granting them "Unrestricted Access". The administrator can also disable the SDB
entirely, which turns off all authorization enforcement and allows any user to monitor or
control any device. See the Avaya Aura® AE Services Administration and Maintenance
Guide for more information about SDB administration.
For AE Services 5.x and later when used with Communication Manager 5.1 or later, the
client application does not have to know the extension password to register a device,
provided the following is true:
• The DeviceID contains the administered switch name associated with a valid
switch connection to Communication Manager
• The switch connection to the Communication Manager is active and talking
• The SDB on the AE Services server is enabled
• The CTI user has “Unrestricted Access” in the SDB
Note:
A CTI user can be administered for "Unrestricted Access" via the "Edit
CTI User" web page on the AE Services Management Console.

Release 7.0.0
148 02-602658
Issue 1
 • The extension’s class of restriction (COR) on the Communication Manager has:
o “Can Be Service Observed” set to “y”
o “Can Be a Service Observer” set to “y”

Note:
If the “Enabled SDB for DMCC Service” is not checked on the “Security
Database -> Control” page, no authorization enforcement will occur even if an
SDB authorization policy has been specified for a given host.

Enterprise Directory
This authorization policy states that an LDAP enterprise directory shall be used for
authorization. This authorization mechanism leverages the AE Services Management
Console web page, “Enterprise Directory”. In addition to specifying basic connection
parameters, this page contains the following fields that are critical to this authorization
method:
• Search Filter Attribute Name: This indicates the attribute name in the user
record that corresponds to username. DMCC will attempt to match a username
to the contents of this attribute. An example is “SAM-Account-Name” in
Windows Active Directory.
• Device ID Attribute: This indicates the attribute name in the user record that
corresponds to the device ID to be authorized for the user. A primary example
here would be an attribute such as “Phone Number” that contains a provisioned
E.164 number for users.
When this authorization mechanism is selected, DMCC will use LDAP to query the user
record for the provisioned Device ID (e.g. Phone Number) and will cache the retrieved
Device ID. When DMCC attempts to authorize a request, it will verify that the Device
ID retrieved from the user record is a substring of the Device ID specified in the
request. This allows per-user authorization without per-user provisioning on AE
Services. The substring match accounts for a very common scenario where a Tel URI
is specified in the request (e.g. tel:+13035381234) but the user record contains an
E.164 number (+13035381234) or extension (5380112).

Unrestricted Access
This authorization policy states that DMCC shall not apply any authorization checks to
sessions originating from the specified host. This allows the administrator to give a
specific application unrestricted access to all devices without provisioning a “user” for
that application.

Release 7.0.0
149 02-602658
Issue 1
AA Policy Use Cases
The following are some use cases that illustrate the value in AA policy provisioning.

Server based applications without enterprise user identities

In many cases for server based applications that are not associated with an enterprise
user identity, provisioning a user for the application is rather artificial. It makes more
sense to authenticate the machine instead of using PKI. Certificate based
authentication is generally accepted as being far more secure than username /
password based authentication. In general, this type of application would have access
to a large number of devices on Communication Manager, and would therefore be
given unrestricted access to all devices.
Previously, in order to support this type of scenario a “user” would have to be
provisioned for the application in AE Services User Management, and then either the
SDB would have to be disabled or that user would have to be granted unrestricted
access in the SDB.
Now, the administrator is not required to provision a user at all for this scenario.
Instead the administrator can provision a User Authentication policy of “Not Required”
and a User Authorization policy of “Unrestricted Access” for the application host. The
username and password supplied by the application to DMCC are completely ignored
in this case. The SDB or Enterprise Directory can still be used to authorize other users
/ applications but would not be used for this particular application.

Enterprise user based applications where user controls only their

own telephone
Many “personal productivity” applications are directly associated with an enterprise
user that wishes to monitor / control their telephone / softphone through a DMCC-
based application. In such scenarios it is desirable to ensure that the user can only
monitor / control their own Device ID, but it is not desirable to add every enterprise user
to the SDB in order to perform this authorization.
An administrator can now authorize such requests against the provisioned Phone
Number / Extension in the LDAP enabled Enterprise Directory (e.g., Active Directory or
Domino). For example, if a user has a provisioned E.164 Phone Number of
+13035381234 and DMCC retrieves a request with a Tel URI type Device ID of
tel:+13035381234, it would perform a substring match and authorize this request.
Two authentication mechanisms could be used in order to enable this scenario without
the need to add users to the AE Services User Management database. For both of
these mechanisms, an administrator would choose a User Authorization policy of
“Enterprise Directory”.
• User Authentication Required. With this mechanism, AE Services would still be
responsible for authenticating the username / password supplied by the

Release 7.0.0
150 02-602658
Issue 1
 application, but the administrator would ensure that this authentication would
not use the internal User Management database. Instead the authentication
would be performed against the enterprise directory using the provisioned
Enterprise Directory configuration, or would be performed using Kerberos as
specified in the Avaya Aura® AE Services Administration and Maintenance
Guide.
• User Authentication Not Required: With this mechanism, DMCC trusts the
application to have properly authenticated the user, and allows the application
to assert a user identity. This sort of mechanism would make sense for a web
app where the user has already authenticated with the web app and AE
Services has been provisioned to trust the web app host with respect to user
identity.

Release 7.0.0
151 02-602658
Issue 1
Chapter 9: Debugging
This section assumes that you have verified the operation of your AE Services server
using the verification application that comes with the AE Services server RPM file.
Please refer to the appropriate Avaya Aura® Application Enablement Services
Installation and Upgrade Guide for the offer you have purchased (AE Services on
VMware or Software Only) for troubleshooting procedures if this verification application
does not function properly.

Error Messages
In debugging your application, you will rely on Error Messages returned in response
events. Every request you make to the .NET API which results in a message being sent
to the AE Services server should result in a response message coming back. You
should always have an event handler for every message you send and when you get the
event, verify that the error attribute of the response is an empty string. If it is not an
empty string, the error attribute will contain information on why the response failed.

You should always catch exceptions when invoking methods in the API. The most
common exception is trying to send a message to the AE Services server after the
socket has been closed.

The .Net SDK ships with a DMCC.config file. This file is the configuration file for the
lognet error logger. By changing the log levels you can enable all XML messages sent
to/from your application and the AE Services server, to be logged to a file. In addition,
you can also enable logging of internal error conditions that may have occurred in the
API. The DMCC.config file has comments in it instructing you how to do this. In order
for your application to load and use the DMCC.config file the file must be located in the
same folder as your applications .exe file. The DMCC.config file also has a logger just
for the dashboard and information on how to enable it is in the file.

If you want to use the Device, Media and Call Control’s .NET log4net capabilities in
your application, you need to add the following code to your application:

private static DMCC_log4net.ILog Logger =

DMCC_log4net.LogManager.GetLogger("NAME_OF_YOUR_LOGGER");

Where NAME_OF_YOUR_LOGGER is how you want you logger identified in the DMCC.config
file.

Then in the DMCC.config file you need to add the following:

<logger name="NAME_OF_YOUR_LOGGER">
<!-- <appender-ref ref="B" /> -->
<level value="DEBUG" />
<appender-ref ref="RollingLogFileAppender"/>
<appender-ref ref="ConsoleAppender" />

Release 7.0.0
152 02-602658
Issue 1
</logger>

The AE Services server side logs will also be helpful when debugging your application.
Please see Appendix E: DMCC Server Logging for additional information.

The remainder of this section helps you with:

• Possible race conditions
• Improving performance

Possible race conditions

• If a thread is playing/recording a message on a phone and another thread
attempts to play/record a message to the same phone then the second attempt
will fail.

• If an application is using the Media object to request that playing/recording

terminate when a specified DTMF tone is detected AND is also configured to
listen for DTMF tones then there is no guarantee of the order for the
Play/Recording Stopped Event and the Tone Detected Event.

Improving performance
Many different factors may potentially affect the performance of your system. The
system has three main parts that may be affected:
• The AE Services server
• Communication Manager
• The network

An excessive load on any of these may slow down the overall system. Here are other
factors to check that also may affect your system performance.

On the AE Services server:

• Ensure that your AE Services server machine meets the minimum requirements
specified in the appropriate Avaya Aura® Application Enablement Services
Installation ad Upgrade Guide for the offer you have purchased (AE Services on
VMware or Software Only).
• Avoid running any other applications on the AE Services server machine.
• Check that the AE Services server’s Linux operating system resources are tuned
correctly for your application needs. The server software makes no assumptions
concerning your application needs and therefore does not tune the kernel for
you. See the “Performance Tuning” chapter in the Red Hat Linux Deployment
Guide found at http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/5/.

Release 7.0.0
153 02-602658
Issue 1
 • Update the Linux kernel with the latest updates available.

On Communication Manager:
• Ensure that Communication Manager is properly configured for your network and
business needs. Misconfigured Communication Manager elements can lead to
performance issues.

On the network:
• Ensure that your network traffic is properly balanced. One way to do this
professionally is to ask Avaya to perform a network assessment. There is also a
VoIP Readiness Guide available from the Avaya Support Centre
(http://www.avaya.com/support). For more information about improving the
performance of your network, see the “Network Quality and Management”
section of Administration for Network Connectivity for Avaya Communication
Manager (555-233-504).

Getting support
Development support is only available through Avaya's DevConnect Program at this
time. As an Innovator/Premier/Strategic level member of the DevConnect Program,
technical support questions can be answered through the DevConnect Portal at
www.avaya.com/devconnect

As a Registered member of the program, support is not available. If you require support
as a Registered member, you can apply for a higher level of membership that offers
support and testing opportunities through the DevConnect Portal. Membership at the
Innovator/Premier/Strategic level is not open to all companies. Avaya determines
membership status above the Registered level.

The DevConnect web site offers discussion forums for a variety of Device, Media and
Call Control areas. There is one that is dedicated to the .NET API. If you have a question
regarding the .NET API feel free to post the question on the forum. Before posting,
please look at the other topics which have already been posted to see if your question
has already been asked and answered.

Release 7.0.0
154 02-602658
Issue 1
Appendix A: The J-Scripts Library
Application Enablement (AE) Services Device, Media and Call Control .NET API offers a
thin client prototype which uses a modified .NET SDK inside Internet Explorer. The
modified .NET SDK – call it the ActiveX ServiceProvider – combines into one class all of
the methods of all of the classes of the unmodified SDK. In order to use the ActiveX
ServiceProvider, a web application has to interact with it using Jscript.

The purpose of this appendix is to define the interface and implementation of a JScript
library with which you can develop web applications using the ActiveX ServiceProvider.

In this interface the method signatures are almost identical to the methods of the .NET
SDK, making this interface general-purpose and easy to use.

J-Script
We have developed the Jscript library with the assumption that it will be imported into
HTML documents by way of the src attribute of a script element, as in:

<script src=”../sp.js” type=”text/Jscript”></script>

This helps maintain a strict separation of concerns; our Jscript library publishes an
interface and the developer writes code using that interface, all in separate files. It
simplifies your HTML files by allowing you to remove large blocks of JavaScript code
from them – that is, it helps keep content and behavior separate.

We will also use namespaces for each of the Jscript objects (not classes) described
below. Namespaces prevent name collisions and, when used with an anonymous
function can “seal” a JavaScript object so that its private properties are invisible outside
of the scope of the object. The following code is an example of creating
com.avaya.dmcc and populating it with a constructor:

var com;
if (!com){
com = {}
} else if (typeof com != object) {
throw new Error("com is not an object")
}
if (!com.avaya) {
com.avaya = {}
} else if (typeof com.avaya != object) {
throw new Error("com.avaya is not an object")
}
if (!com.avaya.dmcc) {
com.avaya.dmcc = {}
} else if (typeof com.avaya.dmcc != object) {
throw new Error("com.avaya.dmcc is not an object")
}
/* Begin anonymous function */

Release 7.0.0
155 02-602658
Issue 1
 (function() {
function ServiceProvider() { /* empty */ }
ServiceProvider.prototype.startApplicationSession =
function(/* args list */) {
/* body of function */
}
ServiceProvider.prototype.stopApplicationSession =
function(/* args list */) {
/* body of function */
}
/* Populate the namespace */
com.avaya.dmcc.ServiceProvider = ServiceProvider
})(); // End anonymous function and invoke it
sp = new com.avaya.dmcc.ServiceProvider();
sp.startApplicationSession();

Note:
JavaScript is an object- or prototype-based object-oriented language. We
saw an example of prototypes occurs in the code above, where the
instance functions startApplicationSession and
stopApplicationSession are created using the prototype for the
ServiceProvider object.

ActiveX Service Provider

The implementation of this project depends on the completion of a proxy class that will
allow the .NET SDK to be used inside Internet Explorer. Its methods will be annotated
using Microsoft Interop Services annotations to make them COM-visible. This in turn will
allow us to invoke those methods using Jscript. The web application’s Jscript depends
on the Jscript library, which depends on ActiveX ServiceProvider. By association,
ActiveX ServiceProvider has a dependency on the unadulterated .NET
ServiceProvider.

To create an instance of the ActiveX ServiceProvider inside Internet Explorer, the web
application developer will need to include an HTML object element in their web page(s).
The Jscript library assumes that the value of the element’s id attribute is DMCC; it will
not function if the object element is missing from the page, the id attribute is missing
from the object element, or the id attribute has a different value. The element looks like
this:

<object id=”DMCC" . . . ></object>

Also, the Jscript library will not function if the ActiveX ServiceProvider object has not
been instantiated, so the object element must appear before the script element in the
HTML document.

Release 7.0.0
156 02-602658
Issue 1
Static event handlers
It is not possible to instantiate COM objects dynamically (using new) in Jscript when you
need to be able to handle events propagated through Interop Services.

JavaScript and Jscript natively handle asynchronous browser events, such as page
loads, button clicks, and so on, but those events originate in the browser or from the
user. Consequently, we must statically define handlers for events in the Jscript library.
Using the Jscript extension to JavaScript for handling events via Interop Services, the
signature of a static handler looks like:

function DMCC::MediaStartedEvent(
deviceId, monitorId,
rtpAddress, rtpPort,
rtcpAddress, rtcpPort, packetSize)

Since only one static handler exists for a event, the static handler will be responsible for
dispatching events and response events to the object to which they ultimately belong.

Basically, the declaration of this function binds the function to a C# delegate in the
ActiveX ServiceProvider. Note that the prefix of the function name – DMCC:: – refers to
the value of the id attribute of the object element in the web page. This binds the function
mediaStartedEvent to the instance of the ActiveX ServiceProvider instantiated by
Internet Explorer and acts as a proxy between the ActiveX ServiceProvider and the
Jscript callback provided by the web application developer.

Static handlers will be defined for each event and each response event.

Requests, response events, and events

In the implementation of the Jscript library, requests are non-blocking, and a response to
a request is considered a response event. A response event is similar to but slightly
different than a regular event.

Consider a request to register a terminal. When invoking registerTerminal: the

developer passes in the usual arguments (media mode, codec, etc.) as well as a
function that the library will call when the response event occurs.

The Jscript library forwards the parameters to the corresponding method in the ActiveX
ServiceProvider (without the developer-provided function), which in turn, creates an
Invoke ID, converts the request to XML, sends it to the server and returns the
Invoke ID to the Jscript library. The Jscript library places the Invoke ID along with
the developer-provided function into a hash. A response event occurs when the server’s
response is received, at which time the ActiveX ServiceProvider invokes the static
handler, RegisterTerminalResponseEvent, passing it the Device ID string, the
Invoke ID, and some other parameters. Using the Invoke ID, the static handler

Release 7.0.0
157 02-602658
Issue 1
retrieves the developer –provided function, deletes it from the hash, and invokes it with
all of the arguments that were passed to its self.

A Request and Subsequent Response Event illustrates this process.

Figure 8: A Request and Subsequent Response Event

This process is similar for regular events. To register interest in an event, the developer
calls startMonitor() using a reference to a Phone, Media, CallControl, or
CallInformation object. Instead of passing in a boolean value to indicate interest
in a particular type of event, however, the developer will pass in a function to be called
when an event of that type occurs.

The primary differences between response events and regular events are:
• an Invoke ID is not returned when the developer calls startMonitor()
• the function that the developer provides for an event type remains in the library’s
internal hash for that event type until it is deleted when the developer calls
stopMonitor().

The normal value of the Invoke ID is in correlating responses with requests. The
function-based approach just described manages this for the developer, so the value of
the Invoke ID to the user is unknown. Each request method in the Jscript library will
nonetheless return the Invoke ID, should the user wish to do something with it.

The following code are examples of registering for and handling request events and
events.

Release 7.0.0
158 02-602658
Issue 1
When the StartApplicationSessionRequestEvent occurs, the function
sasCallback is invoked.

sp = new com.avaya.dmcc.ServiceProvider();

sasCallback = function(error, protoVersion, sessionDuration, invokeId)

{
/* web application code */
}

sp.startApplicationSession(/* normal argument list */, sasCallback);

Similarly, when the Phone’s StartMonitorResponseEvent occurs, the Jscript library

invokes the web application’s responseFunc, and when a DisplayUpdatedEvent
occurs it invokes the web application’s displayUpdatedHandler. If the developer
wishes to register interest in other events, they will assign a handler to the other
properties of the Phone Events object. The names of the properties of the Jscript Phone
Events object will be the same as the corresponding Boolean fields of the C# Phone
Events class, except in camelCase.

responseFunc = function(invokeId, deviceId, monitorId, userState,

error) {
/* web application code */
}

displayUpdatedHandler = function(deviceId, displayContents) {

/* web application code */
}

events = new PhoneEvents();

events.displayUpdated = displayUpdatedHandler;

phone.startMonitor(events, 0, responseFunc)

J-Script object
The Jscript library will have objects with the following names: ServiceProvider,
Device, Phone, Media, ThirdPartyCallController, and
CallInformation.

Note:
An XMLProcessor object is not included in this design, but can be added
if requested.

The following tables show the methods and events belonging to each object. The
methods that do not take a callback function as the final argument are italicized.

The names follow the JavaScript naming conventions:

Release 7.0.0
159 02-602658
Issue 1
 • Pascal case for types
• camel case for identifiers and methods.

An object will not have a method named after an event. The object will have a method
for registering a function (which is anonymous from the perspective of the Jscript library)
to handle events of that type.

Note:
If this list is not exhaustive, any additional methods or events not shown
here will be added when they are added to the ActiveX ServiceProvider.

Service Provider Methods and Events

Table 22: Service Provider

Methods Events

startApplicationSession serverConnectionDownEvent

stopApplicationSession serverConnectionNotActiveEvent

reconnect missedAtLeastOneKeepAliveEvent

getNewDevice

startAutoKeepAlive

stopAutoKeepAlive

shutdown

getSessionId

getAutoKeepAliveEnabled

getDeviceId

releaseDeviceId

getThirdPartyDeviceId

Phone Methods and Events

Table 23: Device

Methods Events

startMonitor displayUpdatedEvent

Release 7.0.0
160 02-602658
Issue 1
stopMonitor lampUpdatedEvent

registerTerminal ringerStatusEvent

unregisterTerminal terminalUnregisteredEvent

redirectMedia hookSwitchUpdatedEvent

getHookswitchStatus

setHookswitchStatus

pressButton

getButtonInfo

getDisplay

getLampMode

getMessageWaitingIndicator

getRingerStatus

Media Methods and Events

Table 24: Phone

Methods Events

startMonitor mediaStartedEvent

stopMonitor mediaStoppedEvent

mediaDeleteMessage mediaPlayingEvent

mediaSetToneRetrievalCriteria mediaPlayingStoppedEvent

mediaStartDubbing mediaPlayingSuspendedEvent

mediaStopDubbing mediaRecordingEvent

mediaStartRecording mediaRecordingStoppedEvent

mediaStopRecording mediaRecordingSuspendedEvent

mediaSuspendRecording mediaToneDetectedEvent

mediaResumeRecording mediaTonesRetrievedEvent

mediaStartPlaying

mediaSuspendPlaying

mediaResumePlaying

Release 7.0.0
161 02-602658
Issue 1
mediaStartToneCollection

mediaStopToneCollection

mediaFlushToneCollectionBuffer

Third Party Call Controller Methods and Events

Table 25: Media

Methods Events

startMonitor conferencedEvent

stopMonitor deliveredEvent

snapshotDevice connectionClearedEvent

singleStepConferenceCall doNotDisturbEvent

alternateCall establishedEvent

answerCall failedEvent

clearCall forwardingEvent

clearConnection heldEvent

conferenceCall originatedEvent

consultationCall retrievedEvent

deflectCall transferredEvent

generateDigits

holdCall

makeCall

getDoNotDisturb

getForwarding

reconnectCall

retrieveCall

setDisplay

setDoNotDisturb

setForwarding

singleStepTransfer

Release 7.0.0
162 02-602658
Issue 1
snapshotCall

transferCall

Call Information Methods and Events

Table 26: Third Party Call Controller

Methods Events

startMonitor linkUpEvent

stopMonitor linkDownEvent

getCallInformation

getLinkStatus

J-Script library configuration

All JScript-related things are stored in the .NET SDK at dmcc-dotnet-sdk/JScript.
Inside that are three folders:
• dashboard containing all the code of the JScript dashboard
• doc containing the simple reference documentation for the JScript library
• src containing the JScript library code

Server-side Instructions
Modify the object element that appears near the top of dashboard.html.

In particular, you must:

• Change host.example.com to the name of the machine on which the web server
is running.

• Change path/to to the path to the directory containing ServiceProvider.dll.

(ServiceProvider.dll must reside in the same directory on your web server as
dashboard.html.)

• Do not change the value of the object element's id attribute; doing so will cause
the dashboard and any DMCC JScript library-based application to fail to function.

Release 7.0.0
163 02-602658
Issue 1
Client-side Instructions
In order for the dashboard page to function in Internet Explorer, you must do the
following:

1. Start a DOS window

2. Go to C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727 (or whatever
2.x .NET framework is installed)
3. Run .\caspol.exe -lg, noting the 2 digit Zone number for LocalIntranet (e.g.,
1.2), hereafter referred to as Z.N.
4. Run .\caspol.exe -m -ag Z.N -url http://host.example.com/*
FullTrust, where Z.N is the two digit zone number from the previous step and
host.example.com is the name of the machine on which the dashboard page
resides. This is necessary because the .NET control opens sockets.
5. In Internet Explorer go to Tools --> Internet Options -- > Security
6. Select Local Intranet
7. Click Sites
8. Select Advanced
9. Enter http://host.example.com
10. Select Add

You may also have to configure additional security settings in Internet Explorer. They
can be set by going to Tools --> Internet Options --> Security--> Local Intranet -->
Custom Level.

The setting that affect whether or how this page (including ServiceProvider.dll) functions
are:
1. Run components signed with Authenticode
2. Download signed ActiveX controls
3. Run ActiveX controls and plugins
4. Script ActiveX controls marked safe for scripting

The dashboard page has only been tested with Internet Explorer 6 on Windows XP.

Release 7.0.0
164 02-602658
Issue 1
Appendix B: Communication Manager
Features
Here is a list of key features in Communication Manager that you may wish to take
advantage of in developing your applications. This is not an exhaustive list - just a
subset of features most likely to be used in applications. For descriptions of these
features, see any of the Communication Manager administration guides.

• AAR/ARS Partitioning
• Abbreviated Dialing
• Abbreviated and Delayed Ringing
• Abbreviated Programming
• Administration Without Hardware
• Authorization Codes
• Automatic Alternate Routing (AAR)
• Automatic Call Distribution (ACD) Features
o Announcements
o Automatic Answering With Zip Tone
o Multiple Call Handling
o Service Observing
• Observe Digital Sets/IP Phones
• Observe Logical Agent IDs
• Automatic Call Distribution (ACD) Features:
o Basic Hunt Group Call
o Agents in Multiple Splits
o Agent Login/Out
o Display - Agent Terminal
• Automatic Callback (on Busy)
• Automatic Callback on Don’t Answer
• Automatic Route Selection (ARS)
• Bridged Call Appearance (single-line, multi-appearance)
o Hunt Group Redirect Coverage
o Multiple Coverage Paths
o Temporary Bridged Appearance
o Remove Temporary Bridged Appearance
• Call Coverage Features
o Call Coverage Consult with Conference/Transfer
• Call Coverage Features
o Consult
o Coverage Paths
o Send All Calls
o Temporary Bridged Appearance
• Call Forwarding / Busy Don’t Answer @ Call Vectoring
o VDN of Origin Announcements
• Call Forwarding by Service Observer
• Call Forwarding by Service Observed
• Call Forwarding Features:
Release 7.0.0
165 02-602658
Issue 1
 o Call Forwarding All Calls
o Call Forwarding - Busy and Don’t Answer
o Call Forwarding - Don’t Answer
o Call Forwarding - Off Net
• Call Park
• Call Pickup
o Directed Call Pickup
o Remove Temporary Bridged Appearance
o Remove Auto-Intercom
• Call Vectoring:
o VDN of Origin Display
• Consult
• Coverage of Calls Redirected Off Net
• Drop (button operation)
• Group Paging
• Hold (single-line, multi-appearance)
• Hold - Automatic
• Hold (single-line, multi-appearance)
• Hold - Automatic [from IR1V4 WCC]
• Hunting/Hunt Groups
• IP Trunks
• Last Number Dialed
• Leave Word Calling - Switch
• Malicious Call Trace
• Message Waiting Indication
• Music-on-Hold Access
o Held Calls
o Conference-Terminal Calls
o Transferred Trunk Calls
• Personalized Ringing
• Personal Station Access
• Priority Calling
• Recorded Announcement
• Terminal Translation Initialization (TTI)
• Tone on Hold
• Transfer (single-line, multi-appearance)
• Voice Terminal Display
o Calling Number Display (SID/ANI/Extn ID)
o Called Number Display (internal & DCS)
o Stored Button Display

Release 7.0.0
166 02-602658
Issue 1
Appendix C: Constant Values
Here are tables describing the values for the XML message parameters which take a
constant value and that are switch specific. These values are specific to Avaya’s
Communication Manager switch. These include:
• Phone Object Enumerations and Constants
o Lamp State - enumeration which defines all of the lamp states
o Lamp Color - enumeration which defines all of the lamp colors
o Button Function - enumeration which defines all of the button functions
o Button ID - enumeration which defines all of the button ID’s
o Registration States - enumeration which defines all of the registration
states
o Dependency Modes - enumeration which defines all of the dependency
modes
o Ringer Pattern Constants
o Registration Constants
• Media Mode Enumerations
o Media Mode - enumeration which defines all of the media modes
• Service Provider Enumerations
o Convert E164 to Dial String - enumeration which defines
o Convert Dial String to E164 - enumeration which defines
• Third Party Call Control Enumeration
o Single Step Conference Call - enumeration which defines all of the Single
Step Conference Call states
o Call Forwarding - enumeration which defines all of the Call Forwarding
states

Phone Object Enumerations and Constants

Table 27: Lamp Mode Enumeration

Name Description

Broken Flutter Usually indicates a feature activation has been

denied.
Flutter Usually indicates a feature activation has been
denied or a button with no feature associated
with it has been pushed.
Off Lamp is off.
Steady Lamp is on.
Wink Lamp is winking (fast blink). Usually indicates a
feature is pending activation.
Inverted Wink Lamp is winking in reverse. Usually indicates
some kind of denial.

Release 7.0.0
167 02-602658
Issue 1
Flash Lamp is flashing. Usually indicates a call is on
hold or a feature is pending activation.
Inverted Flash Lamp is flashing in reverse. Usually indicates
some kind of denial.
Undefined Some other lamp state. You should never get
this.

Table 28: Lamp Color Enumeration

Name Description

Red Red lamp

Green Green lamp
Undefined Some other color. You should never get this

Table 29: Button Function Enumeration

Name Description

ABR_PROG Abbreviated Dial Program

ABR_SPCHAR AD Special Character
ABRDG_APPR Analog Bridged Appearance
ABRV_DIAL Abbreviated Dial
ABRV_RING Button to force Abbreviated / Delayed Ring
Transition
AC_ALARM Administered Connection alarm button
ACA_HALT ACA referral call activate button
ACCOUNT CDR Account Code Button
ADMIN Enter Terminal Self-Admin Mode
AFTER_CALL ACD - After Call Work
ALRT_AGCHG Move agent while staffed alert
ALT_FRL Alternate FRL button
ANI_REQUST Incoming ANI Request (Russian trunks only)
ASSIST ACD - supervisor assist button
ASVN_HALT SVN Auth Code Halt
ATD_QCALLS Attended group - number of queued calls

Release 7.0.0
168 02-602658
Issue 1
ATD_QTIME Attended group - oldest time
AUDIX_REC Audix One-Step Recording
AUT_MSG_WT Automatic message waiting indication
AUTO_CBACK Auo call back
AUTO_ICOM Auto-dial ICOM
AUTO_IN ACD - Auto-In
AUTO_WKUP Automatic Wakeup entry mode
AUTODIAL Autodial button
AUX_WOR

BRDG_APPR Bridged appearance of primary extension

BTN_RING Button Ring Control entry mode
BTN_VIEW Enhanced View Button
BUSY_IND Station busy indicator
CALL_APPR General call appearance, no aux data
CALL_DISP Call the displayed number
CALL_FWD Call forwarding button
CALL_PARK Park/Unpark button
CALL_PKUP UM call pickup
CALL_SCRN

CALL_TIMER Call Timer

CALLR_INFO Caller Information
CAS_BACKUP CAS (branch) back-up mode lamp
CDR1_ALRM SMDR primary printer alarm
CDR2_ALRM SMDR secondary printer alarm
CFWD_BSYDA Call Forward/Busy Don't answer
CFWD_ENH Check-in entry mode
CHECK_IN Check-in entry mode
CHECK_OUT Check-out entry mode
CLK_OVERID Clocked override-time of day routing
CONFERENCE Conference
CONF_DSP Display conference parties
Release 7.0.0
169 02-602658
Issue 1
CONSULT Consult/return
COV_CBACK Coverage LWC call back
COV_MSG_RT Coverage retrieve LWC message
CPN_BLK Per call CPN blocking activate
CPN_UNBLK Per call CPN unblocking activate
CRSS_ALERT Crisis Alert to Digital Station or Attendant.
DATA_EXT Data extension button
DATE_TIME TOD/DATE display mode
DELETE_MSG Delete LWC message
DIAL_ICOM Autodial, aux is uid of destination
DID_REMOVE DID remove entry mode
DID_VIEW DID view entry mode
DIR_PKUP Directed call pickup
DIRECTORY Directory listing for name search
DISP_CHRG Display Charge button
DISP_NORM NORMAL/LOCAL mode button
DN_DST User do not disturb button
DROP Drop the last party on a conference call
EC500 EC500 Feature plus timer
EXCLUSION Manual exclusion
EXT_DN_DST Do not disturb - ext.
EXTND_CALL OPTIM Extend call
FE_MUTE Conf Select Far End Mute
FLASH Flash button for station on CAS MAIN call OR a
call using Trunk Flash
GOTO_COVER Goto coverage button
GRP_DN_DST Do not disturb - grp.
GRP_PAGE Group Paging button
HEADSET Headset in use
HOLD Hold
HUNT_NS Hunt night service button

Release 7.0.0
170 02-602658
Issue 1
IN_CALL_ID

INSPECT Inspect display mode

INT_AUT_AN Internal Automatic Answer button
LAST_NUMB Last number dialed
LIC_ERROR License error
LIMIT_CALL

LINK_ALARM Link alarm button

LOGOUT_OVR SVN login security violation
LSVN_HALT

LWC_CANCEL Cancel LWC

LWC_LOCK Lockout LWC
LWC_STORE LWC store message
MAJOR_ALRM Major alarm button
MAN_MSG_WT Manual message waiting button
MAN_OVERID Manual override-time of day routing
MANUAL_IN ACD - Manual-In
MCT_ACT MCT: Malicious Call Trace Activate
MCT_CONTR MCT: Malicious Call Trace Control
MF_DA_INTL International directory assistance - Mexico
MF_OP_INTL International CO operator - Mexico
MJ_MN_ALRM Major/Minor alarm button
MWI Message Waiting Indicator
MM_BASIC Multimedia Voice/Data activate/deactivate
MM_CALL Multimedia Call Mode activate
MM_CFWD Multimedia Call Forward
MM_DATACNF Multimedia Data Conference activate
MM_MULTNBR Multimedia Multi Address activate
MM_PCAUDIO Multimedia PC-Audio activate
MMI_CP_ALM MMI pack or port (video) alarm
MSG_RETR Principal retrieve LWC message
MWN_ACT Message notification on mode
Release 7.0.0
171 02-602658
Issue 1
MWN_DEACT Message notification off mode
NEXT Step through LWC message
NIGHT_SERV Night Activate
NO_HLD_CNF No hold conference
NH_CONSULT

NOANS_ALRT No Answer Alert button for Redirect On No

Answer (RONA) timeout for split.
NORMAL Normal display mode
OFF_BD_ALM Off-board DS1 board alarm button
PER_COLINE Personal CO line, aux is grp id
PG1_ALARM SA8312 PAGE1 alarm
PG2_ALARM SA8312 PAGE2 alarm
PMS_ALARM PMS alarm button
POST_MSGS Posted messages
PR_AWU_ALM Wakeup journal printer alarm
PR_PMS_ALM PMS journal printer alarm
PR_SYS_ALM BCMS printer link alarm button
PRINT_MSGS

PRIORITY Priority calling button

Q_CALLS Hunt group - number of queued calls
Q_TIME Hunt group - oldest queued time
RELEASE ACD - Release
RING_STAT Ringer status
RINGER_OFF Ringer cut button for stations
RS_ALERT System reset alert
RSVN_HALT SVN remote access security violation
SCROLL SCROLL mode button
SEND_CALLS Send all calls button
SEND_TERM Terminating extension group SAC button
SERV_OBSRV Service observing button
SIGNAL Manual signalling

Release 7.0.0
172 02-602658
Issue 1
SHARE_TALK

SSVN_HALT SVN station security call activate button

STA_LOCK Station Lock
START_BILL Start Billing
STORED_NUM STORED-NUMBER display mode
STROKE_CNT Single-Digit Stroke Counts
TEAM

TERM_X_GR

TIMER ELAPSED-TIME display mode

TOGLE_SWAP Conf/Transfer Toggle Swap
TRANSFER Transfer
TRK_AC_ALM Facility acc test trunk access alert
TRK_ID Trunk ID button
TRUNK_NAME Trunk name when DCS (also DCS CAS MN)
TRUNK_NS Trunk night service button
USR_ADDBSY Add FBI to station
USR_REMBSY Remove FBI from station
UUI_INFO UUI-info button
VC_CP_ALM VC pack or port (audio) alarm
VERIFY Busy verification button
VIP_CHKIN VIP check-in
VIP_RETRY Reschedule VIP wakeup as regular wakeup
VIP_WAKEUP Place VIP wakeup call
VOA_REPEAT VDN of Origin Annc. Repeat Button
VOICE_MAIL Engen fixed voice mail
VU_DISPLAY Vu-Stats Station Displays
WARN_ALRM Warn alarm
WHISP_ACT Activate Whisper Page
WHISP_ANBK Answerback for Whisper Page
WHISP_OFF Whisper Page Off
WORK_CODE Multi-Digit Stroke Count
Release 7.0.0
173 02-602658
Issue 1
 Table 30: Button Id Enumeration
Name Description
ALL Use when you want to get information about ALL
the buttons
DIGIT_1 The digit 1 on the dialpad.
DIGIT_2 The digit 2 on the dialpad.
DIGIT_3 The digit 3 on the dialpad.
DIGIT_4 The digit 4 on the dialpad.
DIGIT_5 The digit 5 on the dialpad.
DIGIT_6 The digit 6 on the dialpad.
DIGIT_7 The digit 7 on the dialpad.
DIGIT_8 The digit 8 on the dialpad.
DIGIT_9 The digit 9 on the dialpad.
DIGIT_0 The digit 0 on the dialpad.
DDIGIT_STAR The digit * on the dialpad.
DIGIT_POUND The digit # on the dialpad.
CONFERENCE The conference button
Drop The drop button
TRANSFER The transfer button
HOLD hold button
BUTTON_1 The first button in the Principal Module starts here.
If you want to get to other feature buttons start with
this number and add the appropriate offset. For
example, Principal Module Button 3 would be
(BUTTON_1 + 2). The Principal Module is the
module where the primary buttons for a station are
configured. Depending on the set type, other
buttons may also exist in the Feature Module,
Display Module, and Coverage Module.
FEATURE_MODULE_START The first button in the Feature Module starts here.
If you want to get to other feature buttons start with
this number and add the appropriate offset. For
example, Feature Module Button 3 would be
(FEATURE_MODULE_START + 2)

Release 7.0.0
174 02-602658
Issue 1
DISPLAY_MODULE_START The first button in the Display Module starts here.
If you want to get to other feature buttons start with
this number and add the appropriate offset. For
example, Display Module Button 3 would be
(DISPLAY_MODULE_START + 2)
COVERAGE_MODULE_START The first button in the Coverage Module starts
here. If you want to get to other feature buttons
start with this number and add the appropriate
offset. For example, Coverage Module Button 3
would be (COVERAGE_MODULE_START + 2)

Table 31: Registration States Enumeration

Name Description

Idle
Registering
Registered
Unregistering
Unknown

Table 32: Dependency Modes Enumeration

Name Description

Main
Independent
Dependent

Table 33: Ringer Pattern Constants

Ring Pattern Value

Ringer Off 0
Manual Signal 1
Attendant Incoming Call 4
Attendant Held Call 5
Attendant Call Waiting 6
Attendant Emergency 7

Release 7.0.0
175 02-602658
Issue 1
Intercom 9
Standard Ring 11
DID/Attendant Ring 12
Priority Ring 13
Ring Ping 14

Table 34: Registration Constants

Reason code constants for Value
the registerTerminalRequest
Unknown -1
Non-specific -2
Internal failure -3
Network timeout 1000

Media Enumerations
Table 35: Media Modes Enumeration
Name Description

None NONE is when do not want access to the media.

Typically, you want to share the control of a hard phone.
You can monitor all messages going to/from the phone
and inject messages (e.g., go off hook, push a button).
Telecommuter Selecting TELECOMMUTER mode allows you to
redirect the media to any device that has a phone
number (e.g., cell phone). You can monitor all messages
going to/from the phone and inject messages (e.g., go
off hook, push a button). However, you have no access
to media itself.
Server_Mode Selecting SERVER_MODE mode allows you to register the
phone directly on the server. The media will go to the
server. You can monitor all messages going to/from the
phone and inject messages (e.g., go off hook, push a
button). However, you have no access to media itself.
This mode will allow you to inject wav files into a call (as
long as the wav files are stored on the server) and also
to record calls.

Release 7.0.0
176 02-602658
Issue 1
Client_Mode Selecting CLIENT_MODE mode allows you to register the
phone directly on the computer where the application is
running. You can specify where the media is supposed
to go. You can monitor all messages going to/from the
phone and inject messages (e.g., go off hook, push a
button). However, you have no access to media itself.
Since the application has access to the media it can do
whatever it wants to with it.
UNDEFINED UNDEFINED mode should never be used.

Service Provider Enumeration

Table 36: Convert E164 to Dial String Enumeration
Name Description

CONVERTED

NO_MATCH

INVALID_INPUT

Table 37: Convert Dial String to E164 Enumeration

Name Description

CONVERTED

NO_MATCH

INVALID_INPUT

Third Party Call Control Enumerations

Table 38: Single Step Conference Call Enumeration
Name Service Provider Description
Class Requests
None No participation type for a Single Step Conference
Silent Silent participation type for a single step conference
Active Active participation type for a single step conference

Table 39: Call Forwarding Enumeration

Release 7.0.0
177 02-602658
Issue 1
Name Description

ForwardImmediate Immediate Forwarding

None Specified No Forwarding Type Specified

Release 7.0.0
178 02-602658
Issue 1
Appendix D: Unicode Mapping Table
When the Unicode Script parameter is used in the Register Terminal Request the
following table indicates the number of bits 1 should be shifted to the left. Multiple
character sets may be specified by ‘ORing’ the values together. For example, if Basic
Latin and Armenian were desired then the value for the Unicode Script would be (1 << 0
| 1 << 6) which is 0x41.

NOTE: Communication Manager requires Basic Latin to be specified when any other
character set is specified.

Number of bits to left shift Character set Name

1 by
0 Basic Latin (common in Germany and most of
Europe)
1 Latin-1 Supplement (common in Germany and most
of Europe)
2 Latin Extended-A
3 Latin Extended-B
4 Greek and Coptic
5 Cyrillic
6 Armenian
7 Hebrew
8 Arabic
9 Devanagari
10 Bengali
11 Gurmukhi
12 Gujarati
13 Oriya
14 Tamil
15 Telugu
16 Kannada
17 Malayalam
18 Sinhala
19 Thai
20 Lao
21 Myanmar
22 Georgian
23 Tagalog
24 Khmer
25 Halfwidth and Fullwidth Forms (Kana)
26 CJKV Radicals Supplement (Jpan)
27 CJKV Radicals Supplement (ChiS)
28 CJKV Radicals Supplement (ChiT)
29 29:CJKV Radicals Supplement (Korn)
30 CJKV Radicals Supplement (Viet)
31 Hangul Jamo

Release 7.0.0
179 02-602658
Issue 1
Appendix E: DMCC Server Logging
If you want to increase the detail of the DMCC logging, you will want to change what is getting logged to
the dmcc-trace.log.* files. You will need to edit the /opt/mvap/conf/dmcc-logging.properties file, replacing
the text in /opt/mvap/conf/dmcc-logging.properties with the text below (or similar).
The new logging levels/information can be enabled by one of the following:
• Restart the AE Services as the root user via the following command line interface:
[root@youraes ~]# /sbin/service aesvcs restart
• To enable the logging levels without a service disruption, you may restart the DmccMain JVM from
the command line as follows as a root user:
[root@youraes ~]# jps
3250 Bootstrap
3732 run.jar
3707 WrapperSimpleApp
5552 Jps
4119 SnmpAgent
3649 Main
3466 LcmMain
8035 DmccMain

[root@youraes ~]# kill -12 8035

The log files are located in the /var/log/avaya/aes directory.

############################################################
# MVAP Server Logging Configuration File
############################################################
############################################################
# Global properties
# Default global logging level.
# This specifies which kinds of events are logged across
# all loggers. For any given facility this global level
# can be overridden by a facility specific level
# Note that the ConsoleHandler also has a separate level
# setting to limit messages printed to the console.
.level=FINE
# handlers defines a whitespace separated list of class
# names for handler classes to load and register as handlers
# on the root Logger (the Logger named ""). Each class name
# must be for a Handler class which has a default
# constructor. Note that these Handlers may be created
# lazily, when they are first used.

Release 7.0.0
180 02-602658
Issue 1
handlers=com.avaya.common.logger.ThreadedHandler
com.avaya.common.logger.ErrorFileHandler
com.avaya.common.logger.ApiFileHandler
com.avaya.common.logger.NistFileHandler

# config defines a whitespace separated list of class names.

# A new instance will be created for each named class. The
# default constructor of each class may execute arbitrary
# code to update the logging configuration, such as setting
# logger levels, adding handlers, adding filters, etc.
#config=
############################################################
############################################################
# configure com.avaya.common.logger.ThreadedHandler
# com.avaya.common.logger.ThreadedHandler logs to its target
# Handler asynchronously (on an independent thread),
# preventing server threads from blocking for disk I/O
com.avaya.common.logger.ThreadedHandler.target=java.util.logging.FileHa
ndler
com.avaya.common.logger.ThreadedHandler.level=FINEST
############################################################
############################################################
# configure java.util.logging.FileHandler
# level specifies the default level for the Handler (defaults to Level.ALL).
# filter specifies the name of a Filter class to use (defaults to no #Filter).
# formatter specifies the name of a Formatter class to use (defaults to #java.util.logging.XMLFormatter)
# encoding the name of the character set encoding to use (defaults to the default platform #encoding).
# limit specifies an approximate maximum amount to write (in bytes) to any one file. If this is #zero, then
there is no limit. (Defaults to no limit).
# count specifies how many output files to cycle through (defaults to 1).
# pattern specifies a pattern for generating the output file name. (Defaults to "%h/java%u.log").
# append specifies whether the FileHandler should append onto any existing files (defaults to #false).
java.util.logging.FileHandler.level=FINEST
java.util.logging.FileHandler.pattern=../logs/dmcc-trace.log
java.util.logging.FileHandler.limit=10485760
java.util.logging.FileHandler.count=20
java.util.logging.FileHandler.formatter=com.avaya.common.logger.Millise
cFormatter
############################################################

Release 7.0.0
181 02-602658
Issue 1
############################################################
# configure com.avaya.common.logger.ErrorFileHandler
# This handler contains code that uses a MemoryHandler that
# pushes to a ThreadedHandler whose target is a FileHandler
# with the pattern specified here. The level set here
# is propagated through the entire Handler chain.
# The result is a log containing detailed error pretext.
com.avaya.common.logger.ErrorFileHandler.level=WARNING
com.avaya.common.logger.ErrorFileHandler.pattern=../logs/dmcc-error.log
############################################################
############################################################
# configure java.util.logging.MemoryHandler
# filter specifies the name of a Filter class to use (defaults to no Filter).
# level specifies the level for the Handler (defaults to Level.ALL)
# size defines the buffer size (defaults to 1000).
# push defines the pushLevel (defaults to level.SEVERE).
# target specifies the name of the target Handler class. (no default).
java.util.logging.MemoryHandler.level=FINEST
java.util.logging.MemoryHandler.size=1000
java.util.logging.MemoryHandler.push=WARNING
############################################################
############################################################
# configure com.avaya.common.logger.ApiFileHandler
# This handler is a ThreadedHandler whose target is a
# FileHandler with the pattern specified here. The level set
# here is propagated to the FileHandler. By default, this
# Handler is configured with a filter to log all API calls.
# filter specifies the name of a Filter class to use (defaults to no Filter).
com.avaya.common.logger.ApiFileHandler.level=FINE
com.avaya.common.logger.ApiFileHandler.pattern=../logs/dmcc-api.log
com.avaya.common.logger.ApiFileHandler.filter=com.avaya.common.logger.R
egExFilter
############################################################
############################################################
# configure com.avaya.common.logger.RegExFilter
# Filters LogRecords by matching their Logger name using the
# regular expression specified in the pattern property.

Release 7.0.0
182 02-602658
Issue 1
com.avaya.common.logger.RegExFilter.pattern=^com\.avaya\.api.*
############################################################
############################################################
# Facility specific properties (extra control per logger)
#com.xyz.foo.level = SEVERE
sun.rmi.level = WARNING
com.avaya.platform.jmx.Mx4jXSLTProcessor.level = WARNING
############################################################
# configure com.avaya.common.logger.NistFileHandler
# It is configured with a filter to log nist sip stack output.
# NIST SIP Stack log level : FINEST, FINER, INFO, WARNING, OFF
############################################################
com.avaya.common.logger.NistFileHandler.level=OFF
com.avaya.common.logger.NistFileHandler.pattern=/var/log/avaya/aes/dmcc
-nist.log
com.avaya.common.logger.NistFileHandler.filter=com.avaya.common.logger.
NistRegExFilter
com.avaya.common.logger.NistRegExFilter.pattern=^gov\.nist\.javax\.sip\
.stack\.ServerLog
com.avaya.common.logger.NistFileHandler.LOG_MESSAGE_CONTENT=true
############################################################
# #################################################
# Enable tracing of all XML messages into the dmcc-trace.log.* files
com.avaya.mvcs.proxy.CstaMarshallerNode.level=FINEST
com.avaya.mvcs.proxy.CstaUnmarshallerNode.level=FINEST
############################################################

Release 7.0.0
183 02-602658
Issue 1
Appendix F: TSAPI Error Code Definitions
This appendix lists all of the values for the TSAPI error codes that you may encounter
in the DMCC/TSAPI logfiles, when employing DMCC Call Control Services. These error
codes are generated by TSAPI and passed on to DMCC which, in turn, may convert
them into Java Exceptions in the DMCC server side log files. A CSTA Error will be
issued to the client.
There are two major classes of TSAPI error codes:
• CSTA universal Failures
• ACS Universal Failures

CSTA Universal Failures

CSTA Universal Failures are error codes returned by CSTAErrorCode:Unexpected
CSTA error code. The following table lists the definitions for the CSTA error codes.
Consult the TSAPI Programmer’s Guide found online on the Avaya Support website for
the definition of the numeric error code.

CSTA Error Definitions

Error Numeric Code
genericUnspecified 0
genericOperation 1
requestIncompatibleWithObject 2
valueOutOfRange 3
objectNotKnown 4
invalidCallingDevice 5
invalidCalledDevice 6
invalidForwardingDestination 7
privilegeViolationOnSpecifiedDevice 8
privilegeViolationOnCalledDevice 9
privilegeViolationOnCallingDevice 10
invalidCstaCallIdentifier 11
invalidCstaDeviceIdentifier 12
invalidCstaConnectionIdentifier 13
invalidDestination 14

Release 7.0.0
184 02-602658
Issue 1
invalidFeature 15
invalidAllocationState 16
invalidCrossRefId 17
invalidObjectType 18
securityViolation 19
genericStateIncompatibility 21
invalidObjectState 22
invalidConnectionIdForActiveCall 23
noActiveCall 24
noHeldCall 25
noCallToClear 26
noConnectionToClear 27
noCallToAnswer 28
noCallToComplete 29
genericSystemResourceAvailability 31
serviceBusy 32
resourceBusy 33
resourceOutOfService 34
networkBusy 35
networkOutOfService 36
overallMonitorLimitExceeded 37
conferenceMemberLimitExceeded 38
genericSubscribedResourceAvailability 41
objectMonitorLimitExceeded 42
externalTrunkLimitExceeded 43
outstandingRequestLimitExceeded 44
genericPerformanceManagement 51
performanceLimitExceeded 52
unspecifiedSecurityError 60
sequenceNumberViolated 61
timeStampViolated 62
Release 7.0.0
185 02-602658
Issue 1
pacViolated 63
sealViolated 64
genericUnspecifiedRejection 70
genericOperationRejection 71
duplicateInvocationRejection 72
unrecognizedOperationRejection 73
mistypedArgumentRejection 74
resourceLimitationRejection 75
acsHandleTerminationRejection 76
serviceTerminationRejection 77
requestTimeoutRejection 78
requestsOnDeviceExceededRejection 79
unrecognizedApduRejection 80
mistypedApduRejection 81
badlyStructuredApduRejection 82
initiatorReleasingRejection 83
unrecognizedLinkedidRejection 84
linkedResponseUnexpectedRejection 85
unexpectedChildOperationRejection 86
mistypedResultRejection 87
unrecognizedErrorRejection 88
unexpectedErrorRejection 89
mistypedParameterRejection 90
nonStandard 100

ACS Universal Failures

ACS Universal Failures are error codes returned by CSTAErrorCode:Unexpected ACS
error code. The following table lists the definitions for the ACS error codes. Consult the
TSAPI Programmer’s Guide for the definition of the numeric error code

Release 7.0.0
186 02-602658
Issue 1
ACS Error Definitions
Error Numeric Code Description
ACSERR_APIVERDENIED -1 This return indicates that the API
Version requested is invalid and not
supported by the existing API Client
Library.
ACSERR_BADPARAMETER -2 One or more of the parameters is
invalid.
ACSERR_DUPSTREAM -3 This return indicates that an ACS
Stream is already established with
the requested Server.
ACSERR_NODRIVER -4 This error return value indicates that
no API Client Library Driver was
found or installed on the system.
ACSERR_NOSERVER -5 This indicates that the requested
Server is not present in the network.
ACSERR_NORESOURCE -6 This return value indicates that there
are insufficient resourcesto open a
ACS Stream.
ACSERR_UBUFSMALL -7 The user buffer size was smaller
than the size of the next available
event.
ACSERR_NOMESSAGE -8 There were no messages available
to return to the application.
ACSERR_UNKNOWN -9 The ACS Stream has encountered
an unspecified error.
ACSERR_BADHDL -10 The ACS Handle is invalid.
ACSERR_STREAM_FAILED -11 The ACS Stream has failed due to
network problems. No further
operations are possible on this
stream.
ACSERR_NOBUFFERS -12 There were not enough buffers
available to place an outgoing
message on the send queue. No
message has been sent.
ACSERR_QUEUE_FULL -13 The send queue is full.

Release 7.0.0
187 02-602658
Issue 1
Appendix G: Routeing Services

Routeing Services Sequence Diagram

Sequence of messages to establish a Routeing Registration and subsequent routeing

requests, responses and events:

1. A RouteRegister request is sent by the client to register as a routeing server for

a specific device or for all devices. Routeing services sends the request to
TSAPI. TSAPI sends the response to Routeing Services, which sends the
RouteRegisterResponse.
Release 7.0.0
188 02-602658
Issue 1
 2. A Route Request is sent by TSAPI to request a destination for a call that has
arrived on a routeing device. The request includes call-related information that
the routing server (ie client application) uses to determine the destination of the
call. RouteingServices sends the Route Request to the client.
3. The client can respond in one of the following ways to the Route Request:
4. Send a Route Select Request that provides a destination, in which case the
request is sent to TSAPI.
5. Send a Route End request to terminate the routeing dialog for the call and
Routeing Services sends the request to TSAPI. The client may send this if it
cannot provide a route for the call in question, in which case the switch provides
the default routing for the call.
6. A RouteUsed Event is sent by TSAPI that contains the actual destination of a
call for which the application previously sent a Route Select Request containing
a destination. RouteingServices sends the RouteUsed event to the client.
7. A Route End Event is sent by TSAPI to terminate a routing dialog for a call and
to inform the client of the outcome of the call routing. RouteingServices sends
the Route End Request to the client. The errorValue parameter in the request
specifies the reason for the route end request.

Requests to end a routeing registration session:

The following requests end a routeing registration session.
1. Client Application->Server Request: A Route Register Cancel request is sent by
the client application to Routeing Services which sends the request to TSAPI.
TSAPI de-allocates a routeRegisterRequestID and returns a response to
RouteingServices which sends a RouteRegisterCancel response.
2. Server->Client application Request: A Route Register Abort event is sent by
TSAPI and a Route Register Abort request is sent to the client application that
contains the Route Register Request Id.

Release 7.0.0
189 02-602658
Issue 1
RouteRegister
Client applications use RouteRegister request to register as a routing server for
RouteReques(s) from a specific device. The application must register for routing
services before it can receive any RouteRequest(s) from the routing device. An
application may be a routing server for more that one routing device. For a specific
routing device,however, only one application is allowed to be registered as the routing
server. If a routing device already has a routing server registered, subsequent
RouteRegister requests will be negatively acknowledged, except as described in
Special usage cases.

Special usage cases: In some cases it is desirable to allow the same application to re-
register as a routing device. That is, if a routing device already has a routing server
registered, subsequent RouteRegister requests will be positvely acknowledged if
certain criteria conditions are satisfied. For example, if a link goes down with an AE
Services application, the application can re-establish itself if the following criteria are
met:
• If the login matches that of the previously registered application
• If the application name matches that of the previously registered application
• If the IP address of the client machine matches that of the previously registered
Application

The RouteRegister is sent to and handled by the TSAPI Service, not by

Communication Manager. The RouteRequest(s) are sent from the switch to the TSAPI
Service and AE Services through call vector processing. From the perspective of the
switch, the TSAPI Service is the routing server. The TSAPI Service processes the
RouteRequests and sends the RouteRequest(s) to the proper routing servers based on
the route registrations from applications.

If no routing server is registered for Communication Manager, all RouteRequests from

the switch will be terminated by the TSAPI Service with a Route End Request, as if
RouteEnd requests were received from a routing server.

RouteRegister Request
ErrorValue Description
OutstandingRequestLimitExceeded The specified routing device already has a
registered routing server.

Release 7.0.0
190 02-602658
Issue 1
RouteRequest
The switch sends a RouteRequest to request a destination for a call arrived on a
routing device from a routing server application. The application may have registered
as the routing server for the routing device on the switch that is making the request, or
it may have registered as the default routing server. The RouteRequest includes call-
related information. A routing server application typically uses the call-related
information and a database to determine the destination for the call. The routing server
application responds to the RouteRequest via a RouteSelect request that specifies a
destination for the call or a RouteEnd request, if the application has no destination for
the call.

The Routing Request Service can only be administered through the Basic Call
Vectoring feature. The switch initiates the Routing Request when the Call Vectoring
processing encounters the adjunct routing command in a call vector. The vector
command will specify a CTI link’s extension through which the switch will send the
RouteRequest to AE Services DMCC through the TSAPI Service.

Multiple adjunct routing commands are allowed in a call vector. In G3V3, the Multiple
Outstanding Route Requests feature allows 16 outstanding Route Requests per call.
The Route Requests can be over the same or different CTI links. The requests are all
made from the same vector. They may be specified back-to-back, without intermediate
(wait, announcement, goto, or stop) steps. If the adjunct routing commands are not
specified back-to-back, pre-G3V3 adjunct routing functionality will apply. This means
that previous outstanding RouteRequests are canceled when an adjunct routing vector
step is executed.

The first RouteSelect response received by the switch is used as the route for the call,
and all other Route Requests for the call are canceled via RouteEnd event(s).

If an application terminates the RouteRequest via a RouteEnd request, the switch

continues vector processing.

A RouteRequest will not affect the Call Event Reports.

Like Delivered or Established Event, the RouteRequest currentRoute parameter

contains the called device. The currentRoute in Route Request contains
the originally called device if there is no distributing device, or the distributing device if
the call vectoring with VDN override feature of the PBX is turned on. In the later case,
the originally called device is not reported. The distributingDevice feature is not
supported in the RouteRequest private data.

Release 7.0.0
191 02-602658
Issue 1
RouteSelect
The routing server application uses RouteSelect to provide a destination to the switch
in response to a RouteRequest for a call.

An application may receive one RouteEnd event and one Error for a
RouteSelect request for the same call in one of the following call scenarios:
• A RouteRequest is sent to the application.
• Caller drops the call.
• Application sends a RouteSelect request.
• A RouteEnd event (errorValue = NoActiveCall) is sent to the application.
• TheRouteSelect request is sent, but the call has been dropped.
• An Error is sent for the RouteSelect request (errorValue = InvalidCrossRefId) to
application.

RouteSelect Request
ErrorValue Description
InvalidDeviceId An invalid
routeRegisterReqID has been specified in the RouteEndInv()
request
InvalidCrossRefId An invalid routeCrossRefID has been
specified in the Route Select request.

Release 7.0.0
192 02-602658
Issue 1
RouteUsed Event
The switch uses a RouteUsed to provide a destination to the routing server application
with the actual destination of a call for which the application previously sent a request
containing a destination. The routeUsed and destRoute parameters contain the same
information specified in the routeSelected and destRoute parameters of the previous
RouteSelect request of this call, respectively. The callingDevice parameter contains the
same calling device number provided in the previous RouteRequest of this call.

Note that the number provided in the routeUsed parameter is from the routeSelected
parameter of the previous RouteSelect request of this call received by the TSAPI
Service. This information in routeUsed is not from Communication Manager and it may
not represent the true route that Communication Manager used.

Note that the number provided in the destRoute parameter is from the destRoute
parameter of the previous RouteSelect request of this call received by the TSAPI
Service. This information in destRoute is not from the Communication Manager and it
may not represent the true route that the Communication Manager used.
The number provided in the callingDevice parameter is from the callingDevice
parameter of the previous RouteRequest of this call sent by the TSAPI Service.

Release 7.0.0
193 02-602658
Issue 1
RouteEnd Request
This request is sent by the routing server application to terminate a routing dialog for a
call. The service request includes a cause value giving the reason for the routing dialog
termination.
• If an application terminates a RouteRequest via a RouteEnd request, the switch
continues vector processing.
• An application may receive one RouteEnd Event and one Error for a RouteEnd
request for the same call in the following call scenario:
o A RouteRequest is sent to the application.
o Caller drops the call.
o Application sends a RouteEnd request.
o A RouteEnd Event (errorValue = NoActiveCall) is sent to the application.
o TSAPI Service receives the cstaRouteEndInv() request, but call has
been dropped.
o TSAPI Service sends universalFailure for the cstaRouteEndInv() request
(errorValue = INVALID_CROSS_REF_ID) to application.
The errorValue is ignored by Communication Manager and has no effect for the routed
call, but it must be present in the API. Suggested error codes that may be useful for
error logging purposes are:

RouteEnd Request
ErrorValue Description
Generic Normal termination (for example, application does not want to
route the call or does not know how to route
the call).

InvalidDeviceId An invalid routeRegisterReqID has been specified in the

RouteEnd request
ResourceBusy Routing server is too busy to handle the route request.
ResourceOutOfService Routing service temporarily unavailable due to internal
problem (for example, the database is out of service).

RouteEnd Event:
This event is sent by the switch to terminate a routing dialog for a call and to inform the
routing server application of the outcome of the call routing.

Release 7.0.0
194 02-602658
Issue 1
An application may receive one RouteEnd Event and one Error for a RouteSelect
request for the same call in one of the following call scenarios:
• A RouteRequest is sent to the application.
• Caller drops the call.
• Application sends a RouteSelect Request.
• A RouteEnd Event (errorValue = NoActiveCall) is sent to the application.
• The TSAPI Service receives the RouteSelect Request, but call has been
dropped.
• An error is sent for the RouteSelect request (errorValue =InvalidCrossRefId) to
application.
RouteEnd Event
ErrorValue Description
Generic The call has been successfully routed or The
adjunct route request to route using NCR resulted
in the call not being routed by NCR because of an
internal system error.

SubscribedResourceAvailability The adjunct route request to route using NCR

resulted in the call not being routed by NCR
because the NCR contained incorrectly
administered trunk (NCR is active but not set up
correctly).
InvalidCallingDevice Upon routing to an agent (for a direct-agent call),
the agent is not logged in.
PrivilegeViolationSpecifiedDevice Lack of calling permission; for example, for an
ARS call, there is an insufficient Facility
Restriction Level (FRL). For a direct-agent call,
the originator’s Class Of Restriction (COR) or the
destination agent’s COR does not allow a direct-
agent call.
InvalidDestination The destination address in the RouteSelect
request is invalid or the adjunct route request to
route using NCR resulted in the call not being
routed by NCR because the NCR contained in
invalid PSTN number.
InvalidObjectType Upon routing to an agent (for direct-agent call),
the agent is not a member of the specified split.
InvalidObjectState A RouteSelect request was received in the wrong
state. A second RouteSelect request sent by the
application before the routing dialog is ended may
cause this.
NetworkBusy The adjunct route request to route
using NCR resulted in the call not being routed by
NCR because there was no NCT outgoing trunk.

Release 7.0.0
195 02-602658
Issue 1
 RouteEnd Event
ErrorValue Description
NetworkOutOfService The adjunct route request to route using NCR
resulted in the call not being routed by NCR
because the NCT contained an invalid PSTN
number, and the second leg can not be set up.

The adjunct route request to route using NCR

resulted in the call not being routed by NCR
because of a PSTN NCD network error.

The adjunct route request to route using NCR

resulted in the call not being routed by NCR
because of a PSTN NCD no disc error.
NoActiveCall The call was dropped (for example, caller
abandons, vector disconnect timer times out, a
non-queued call encounters a "stop" step, or the
application clears the call) while waiting for a
response to a RouteSelect request.
NoCallToAnswer The call has been redirected. The switch has
canceled or terminated any outstanding
RouteRequest(s) for the call after receiving the
first valid RouteSelect message. The switch
sends a RouteEnd Event with this cause to all
other outstanding RouteRequest(s) for the call.
Note that this error can happen when Route
Registers are registered for the same routing
device from two different AE Services servers
and the switch is set to send multiple
RouteRequests for the same call.
PrivilegeViolationOnSpecifiedDevice The adjunct route request to route using NCR
resulted in the call not being routed by NCR
because the PSTN NCD exceeds the maximum
Redirections
ResourceBusy The destination is busy and does not have
coverage. The caller will hear either a reorder or
busy tone.
PerformanceLimitExceeded Call vector processing encounters any steps
other than wait, announcement, goto, or stop
after the RouteRequest has been issued. This
can also happen when a wait step times out.
When the switch sends RouteEnd event with this
cause, call vector processing continues.
ValueOutOfRange The adjunct route request to route using NCR
resulted in the call not being routed by NCR
because RouteSelect does not contain a called
number.

Release 7.0.0
196 02-602658
Issue 1
RouteRegisterAbort
This event notifies the application that the TSAPI Service or switch aborted a routing
registration session. After the abort occurs, the application receives no more
RouteRequest(s) from this routing registration session and the routeRegisterReqID is
no longer valid. The routing requests coming from the routing device will be sent to the
default routing server, if a default routing registration is still active.

• If no CTI link has ever received any RouteRequest(s) for the registered routing
device and all of the CTI links are down, this event is not sent.
• In a multi-link configuration, if at least one link that has received at least one
RouteRequest for the registered routing device is up, this event is not sent. It is
sent only when all of the CTI links that have received at least one
RouteRequest for the registered routing device are down.

Note:
How Communication Manager sends the RouteRequest (s) for the registered
routing device, via which CTI links, is controlled by the call vectoring
administered on the switch. A routing device can receive RouteRequest (s)
from different CTI links. It is possible that links are up and down without
generating this event.
• If the application wants to continue the routing service after the CTI link is up, it
must issue a RouteRegister request to re-establish a routing registration
session for the routing device.
• The RouteRegisterAbort Event is sent when a competing application sends a
RouteRequest and it has the same criteria (login, application name, and IP
address).

Release 7.0.0
197 02-602658
Issue 1
RouteRegisterCancel
Client applications use RouteRegisterCancel to cancel a previously registered
RouteRegister session. When this service request is positively acknowledged, the
client application is no longer a routing server for the specific routing device and the
RouteRequest(s) are not longer sent for the specific routing device associated with the
routeRegisterReqID to the requesting client application. Any further RouteRequest(s)
from the routing device will be sent to the default routing server application, if there is
one registered.

An application may receive RouteRequest(s) after a RouteRegisterCancel request is

sent and before a RouteRegisterCancelResponse is received. The application should
ignore the RouteRequest. If a RouteSelect request is sent for the RouteRequest, a
RouteEnd response will be received with error InvalidDeviceId. If a RouteEnd request
is sent for the RouteRequest, it will be ignored. The outstanding RouteRequest will
receive no response and will be timed out eventually.

RouteRegisterCancel Request
ErrorValue Description
InvalidDeviceId An invalid routeRegisterReqID has been specified in
the RouteEndInv() request

Release 7.0.0
198 02-602658
Issue 1
Appendix H: IPv6 Support
Network layer Internet Protocol version 6 (IPv6) increases the IP address field from 32
bits wide to 128 bits, allowing a greater number of addressable nodes (among other
improvements). With the internet migrating to IPv6 addressing, AE Services support for
it will ensure Application Enablement Services’ compatibility with the new Internet
Protocol.
Thus, in release 6.1 of Application Enablement Services, support for IPv6 networks
were added. This includes:
• Support for “pure” IPv6 networks
• Support for mixed IPv4 & IPv6 networks

IPv6 addresses are normally written as eight groups of four hexadecimal digits. There
are 3 defined forms for representing IPv6 addresses as text strings:

1. The preferred form is x:x:x:x:x:x:x:x, where the 'x's are one to four hexadecimal digits of
the eight 16-bit pieces of the address. Examples include:
• ABCD:EF01:2345:6789:ABCD:EF01:2345:6789
• 2001:DB8:0:0:8:800:200C:417A

2. It may be common for addresses to contain long strings of zeroes. In order to make
writing addresses containing zero bits easier, a special syntax is available to compress
the zeros. The use of "::" indicates one or more groups of 16 bits of zeros. The "::" can
only appear once in an address. The "::" can also be used to compress leading or trailing
zeros in an address. For example, the following addresses:
• 2001:DB8:0:0:8:800:200C:417A a unicast address
• FF01:0:0:0:0:0:0:101 a multicast address
• 0:0:0:0:0:0:0:1 the loopback address
• 0:0:0:0:0:0:0:0 the unspecified (wildcard) address
may be represented as:
• 2001:DB8::8:800:200C:417A a unicast address
• FF01::101 a multicast address
• ::1 the loopback address
• :: the unspecified (wildcard) address

3. An alternative form that may be convenient when dealing with a mixed environment of
IPv4 and IPv6 nodes is ::FFFF:d.d.d.d, where the 'd's are the decimal values of the four
low-order 8-bit pieces of the address (standard IPv4 representation). Examples include:
• 0:0:0:0:0:FFFF:13.1.68.3
• 0:0:0:0:0:FFFF:129.144.52.38
which are compressed to:
• ::FFFF:13.1.68.3
• ::FFFF:129.144.52.38

This form, also known as an “IPv4-mapped address”, is not commonly used at the user
application layer. There are security concerns associated with this form, and several
Microsoft Windows implementations do not support it. To address these concerns and
Release 7.0.0
199 02-602658
Issue 1
 limitations, the network stacks specifically require either an IPv4 address or an IPv6
address. Thus, the use of this form in Application Enablement Services is discouraged.
To use a literal IPv6 address in a URL, the literal address should be enclosed in “[“ and
“]” characters. For example the literal IPv6 address “1080:0:0:0:8:800:200C:417A”
would be represented as: “[1080:0:0:0:8:800:200C:417A]”. This notation allows parsing
a URL with no confusion between the IPv6 address and port number. For example:
https://[2001:0db8:85a3:08d3:1319:8a2e:0370:7344]:443/index.html
Oracle (Sun) Java version 1.4 and later versions are IPv6-enabled with the extending
of the InetAddress class to the Inet6Address and Inet4Address classes. The JVM
determines whether to use Inet4Address or Inet6Address automatically, which is
transparent to the developer. For example:
• InetAddress ip = InetAddress.getByName(“java.sun.com”); or:
• InetAddress ip = InetAddress.getByName(“135.9.30.40”); or:
• InetAddress ip = InetAddress.getByName(“2001:db8::1428:57ab”); then:
• Socket s = new Socket(ip, 80);

Usage of IPv6 addresses in AE Services

IP addresses are prevalent throughout AE Services. For example, they can be found in:
• AE Services Management Console web pages
• Switch Connections
• DMCC DeviceIDs
• Real Time Transport Protocol (RTP)
• Client applications
and for other uses within DMCC.

In fact, wherever an IPv4 address can be used in AE Services, an IPv6 address can
now also be employed - assuming, of course, that it makes sense for the target network
topography. Thus, IPv6 addresses can be used for such things as:

• The AE Services server address, including:

o DMCC unsecured port (4721)

o DMCC secured port (4722)

o DMCC TR87 port (4723)

o AE Services Management Console web pages (443)

Release 7.0.0
200 02-602658
Issue 1
 • Communication Manager addresses of various types, including:

o Processor Ethernet addreses

o Media Gateway addresses

o Media Processor addresses

• Client application addresses, including:

o The client server

o Endpoint RTP address (for client media mode)

Note that Communication Manager 6.0 or later is required for IPv6 connections
between AE Services and Communication Manager. Also note that there is no official
support of IPv6 for the CLANs. Processor Ethernet connections to Communication
Manager should be used in IPv6 networks.

Mixed IPv4 and IPv6 networks

Beginning with AE Services 6.1 and Communication Manager 6.0, a dual stack
implementation will be provided that will allow AE Services to communicate with CM
using either IPv4 or IPv6. An IPv6 server on a dual-stack host is capable of servicing
both IPv4 clients and IPv6 clients. IPv4 clients send IPv4 datagrams to the server, and
the server’s protocol stack converts the client’s address into an IPv4-mapped IPv6
address. Simililarly, an IPv6 client on a dual-stack host can communicate with an IPv4
server. The client’s resolver returns an IPv4-mapped IPv6 address for the server. When
the client calls connect() for one of these addresses, the dual stack sends an IPv4
SYN segment.
Both IPv4 and IPv6 address formats may be used on a single AE Services installation.
For example, if multiple switch connections are administered, the PE IP address for
one switch connection may be in IPv4 format, while the PE IP addresses for another switch
connection may be in IPv6 format. It is the administrator’s responsibility to enter the correct IP
address for each entity.
Note that, when working within a mixed network that includes both IPv4 and IPv6
subnets, it is your responsibility to ensure that the network infrastructure (routers,
Ethernet switches, etc.) is capable of handling and routing IPv4 and/or IPv6 traffic as
needed.

Release 7.0.0
201 02-602658
Issue 1
Appendix I: ACS Universal Error Codes
The following table contains a list of private error codes that may be returned instead of
the generic CSTA Error Code that was returned as a negative acknowledgement in
previous releases of AE Services.
ACS Error Code

ACS Error Code Description

acsError TSAPI ACS Error

acsError0 TSAPI No Thread

acsError1 TSAPI Bad Driver

acsError2 TSAPI Bad Driver ID

acsError3 TSAPI Dead Driver

acsError5 TSAPI Free Buffer Failed

acsError6 TSAPI Send to Driver

acsError7 TSAPI Receive From Driver

acsError8 TSAPI Registration Failed

acsError11 TSAPI No Memory

acsError12 TSAPI Encode Failed

acsError13 TSAPI Decode Failed

acsError19 TSAPI No Security Database

acsError23 TSAPI Bad Server ID

Release 7.0.0
202 02-602658
Issue 1
acsError24 TSAPI Bad Stream Type

acsError25 TSAPI Bad Password or Login

acsError26 TSAPI No User Record

acsError27 TSAPI No Device Record

acsError47 TSAPI Open Failed

acsError65 TSAPI Driver Unregistered

acsError66 TSAPI No ACS Stream

acsError72 TSAPI TDI Queue Fault

acsError73 TSAPI Driver Congestion

acsError74 TSAPI No TDI Buffers

acsError86 TSAPI License Mismatch

acsError87 TSAPI Bad Attribute List

acsError88 TSAPI Bad TList Type

acsError93 TSAPI System Error

acsError95 TSAPI TCP Failed

acsError105 TSAPI Load Lib Failed

Release 7.0.0
203 02-602658
Issue 1
Glossary
A
AE
Used as a “shorthand” term in this documentation for Application Enablement.
AES
Stands for Advanced Encryption Scheme.
API
Application Programming Interface. A “shorthand” term in this documentation for the
Java interface provided by the Application Enablement Services. See also connector
client API library
application machine
The hardware platform that the connector client API library and the client application
are running on
B
BHCC
busy hour call capacity
C
client application
An application created using the Device, Media and Call Control API
CMAPI softphone
Application Enablement Services Device, Media and Call Control API software objects
that represent softphone-enabled, Communication Manager telephones or extensions
Application Enablement Services Device, Media and Call Control API
The product name. This includes the server-side runtime software (see the AE Services
server software ) and the connector client API library . This term is never used to
reference only the client API library.
connector
This describes the function of Application Enablement Services Device, Media and Call
Control API.
In this context, “connector” means software and communications protocol(s) that allow
two disparate systems to communicate. Often used to provide open access to a
proprietary system. In the case of Application Enablement Services Device, Media and
Call Control API, the connector enables applications running on a computing platform to
incorporate telephony functionality through interaction with Communication Manager.
connector client API library
The Application Enablement Services Device, Media and Call Control Java API, also
referred to as the AE
connector server machine
The hardware platform that the connector server software is running on. In these
documents, the term “connector server” by itself never refers to the connector server
machine. See connector server software .
connector server software
The Application Enablement Services server-side runtime software, often referred to as
the “connector server” in these documents
CSTA
Computer-Supported Telecommunications Applications
D
DMA
Release 7.0.0
204 02-602658
Issue 1
Direct memory access
DMCC softphone
Application Enablement Services Device, Media and Call Control API software objects
that represent softphone-enabled, Communication Manager telephones or extensions
E
ECMA
European Computer Manufacturers Association. A European association for
standardizing information and communication systems in order to reflect the international
activities of the organization.
H
hold time
The total length of time in minutes and seconds that a facility is used during a call
J
JDK
Java Developers Kit
J2SE
Java 2 Platform, Standard Edition
JMX

JMX (Java Management Extensions) is a set of specifications for application and

network management in the J2EE development and application environment. JMX
defines a method for Java developers to integrate their applications with existing network
management software by dynamically assigning Java objects with management
attributes and operations
JSW
Java Service Wrapper
JVM
Java Virtual Machine. Interprets compiled Java binary code for a computer’s processor
so that is can perform a Java program’s instructions
O
OAM
Operations, Administration and Maintenance
R
RPM
Red Hat Package Manager
S
SAT
System Access Terminal (for Communication Manager)
SDK
Software Development Kit. An SDK typically includes API library, software platform,
documentation, and tools.
T
TCP
Transmission Control Protocol. A connection-oriented transport-layer protocol, IETF STD
7. RFC 793, that governs the exchange of sequential data. Whereas the Internet
Protocol (IP) deals only with packets, TCP enables two hosts to establish a connection
and exchange streams of data. TCP guarantees delivery of data, and also guarantees
that packets are delivered in the same order in which the packets are sent.
TSAPI
Release 7.0.0
205 02-602658
Issue 1
Telephony Services Application Programming Interface. A service that provides 3rd
party call control.
TTI
Terminal Translation Initialization. This is a feature in Communication Manager that
allows administrators, when initially administering new DCP stations, to not initially bind
the extension number to a port. When the technician is installing the stations, they then
use the TTI feature access code to bind the extension number to the station.
V
VoIP
Voice over IP. A set of facilities that use the Internet Protocol (IP) to manage the delivery
of voice information. In general, VoIP means to send voice information in digital form in
discrete packets instead of in the traditional circuit-committed protocols of the public
switched telephone network (PSTN). Users of VoIP and Internet telephony avoid the
tolls that are charged for ordinary telephone service.
X
XML
Extensible Markup Language
XSD
XML Schema Definition. Specifies how to formally describe the elements in an
Extensible Markup Language (XML) document. This description can be used to verify
that each item of content in a document adheres to the description of the element in
which the content is to be placed. This protocol uses these instead of DTD’s.

Release 7.0.0
206 02-602658
Issue 1