Você está na página 1de 168

Avaya Aura Application Enablement Services Device, Media and Call Control .

NET API Programmers Guide Release 6.1

02-602658 Issue 1 January 2011

2010 Avaya Inc. All Rights Reserved. Notices While reasonable efforts have been made to ensure that the information in this document is complete and accurate at the time of printing, Avaya assumes no liability for any errors. Avaya reserves the right to make changes and corrections to the information in this document without the obligation to notify any person or organization of such changes. Documentation disclaimer Avaya shall not be responsible for any modifications, additions, or deletions to the original published version of this documentation unless such modifications, additions, or deletions were performed by Avaya. End User agree to indemnify and hold harmless Avaya, Avaya's agents, servants and employees against all claims, lawsuits, demands and judgments arising out of, or in connection with, subsequent modifications, additions or deletions to this documentation, to the extent made by End User. Link disclaimer Avaya is not responsible for the contents or reliability of any linked Web sites referenced within this site or documentation(s) provided by Avaya. Avaya is not responsible for the accuracy of any information, statement or content provided on these sites and does not necessarily endorse the products, services, or information described or offered within them. Avaya does not guarantee that these links will work all the time and has no control over the availability of the linked pages. Warranty Avaya provides a limited warranty on this product. Refer to your sales agreement to establish the terms of the limited warranty. In addition, Avayas standard warranty language, as well as information regarding support for this product, while under warranty, is available to Avaya customers and other parties through the Avaya Support Web site: http://www.avaya.com/support. Please note that if you acquired the product from an authorized Avaya reseller outside of the United States and Canada, the warranty is provided to you by said Avaya reseller and not by Avaya. Licenses THE SOFTWARE LICENSE TERMS AVAILABLE ON THE AVAYA WEBSITE, HTTP://SUPPORT.AVAYA.COM/LICENSEINFO/ ARE APPLICABLE TO ANYONE WHO DOWNLOADS, USES AND/OR INSTALLS AVAYA SOFTWARE, PURCHASED FROM AVAYA INC., ANY AVAYA AFFILIATE, OR AN AUTHORIZED AVAYA RESELLER (AS APPLICABLE) UNDER A COMMERCIAL AGREEMENT WITH AVAYA OR AN AUTHORIZED AVAYA RESELLER. UNLESS OTHERWISE AGREED TO BY AVAYA IN WRITING, AVAYA DOES NOT EXTEND THIS LICENSE IF THE SOFTWARE WAS OBTAINED FROM ANYONE OTHER THAN AVAYA, AN AVAYA AFFILIATE OR AN AVAYA AUTHORIZED RESELLER, AND AVAYA RESERVES THE RIGHT TO TAKE LEGAL ACTION AGAINST YOU AND ANYONE ELSE USING OR SELLING THE SOFTWARE WITHOUT A LICENSE. BY INSTALLING, DOWNLOADING OR USING THE SOFTWARE, OR AUTHORIZING OTHERS TO DO SO, YOU, ON BEHALF OF YOURSELF AND THE ENTITY FOR WHOM YOU ARE INSTALLING, DOWNLOADING OR USING THE SOFTWARE (HEREINAFTER REFERRED TO INTERCHANGEABLY AS YOU AND END USER), AGREE TO THESE TERMS AND CONDITIONS AND CREATE A BINDING CONTRACT BETWEEN YOU AND AVAYA INC. OR THE APPLICABLE AVAYA AFFILIATE (AVAYA). Avaya grants End User a license within the scope of the license types described below. The applicable number of licenses and units of capacity for which the license is granted will be one (1), unless a different number of licenses or units of capacity is specified in the Documentation or other materials available to End User. Designated Processor means a single stand-alone computing device. Server means a Designated Processor that hosts a software application to be

accessed by multiple users. Software means the computer programs in object code, originally licensed by Avaya and ultimately utilized by End User, whether as stand-alone products or pre-installed on Hardware. Hardware means the standard hardware originally sold by Avaya and ultimately utilized by End User. License types Designated System(s) License (DS). End User may install and use each copy of the Software on only one Designated Processor, unless a different number of Designated Processors is indicated in the Documentation or other materials available to End User. Avaya may require the Designated Processor(s) to be identified by type, serial number, feature key, location or other specific designation, or to be provided by End User to Avaya through electronic means established by Avaya specifically for this purpose. Concurrent User License (CU). End User may install and use the Software on multiple Designated Processors or one or more Servers, so long as only the licensed number of Units are accessing and using the Software at any given time. A Unit means the unit on which Avaya, at its sole discretion, bases the pricing of its licenses and can be, without limitation, an agent, port or user, an e-mail or voice mail account in the name of a person or corporate function (e.g., webmaster or helpdesk), or a directory entry in the administrative database utilized by the Software that permits one user to interface with the Software. Units may be linked to a specific, identified Server. Database License (DL). End User may install and use each copy of the Software on one Server or on multiple Servers provided that each of the Servers on which the Software is installed communicate with no more than a single instance of the same database. CPU License (CP). End User may install and use each copy of the Software on a number of Servers up to the number indicated by Avaya provided that the performance capacity of the Server(s) does not exceed the performance capacity specified for the Software. End User may not re-install or operate the Software on Server(s) with a larger performance capacity without Avaya's prior consent and payment of an upgrade fee Named User License (NU). End User may: (i) install and use the Software on a single Designated Processor or Server per authorized Named User (defined below); or (ii) install and use the Software on a Server so long as only authorized Named Users access and use the Software. Named User, means a user or device that has been expressly authorized by Avaya to access and use the Software. At Avaya's sole discretion, a Named User may be, without limitation, designated by name, corporate function (e.g., webmaster or helpdesk), an e-mail or voice mail account in the name of a person or corporate function, or a directory entry in the administrative database utilized by the Software that permits one user to interface with the Software. Shrinkwrap License (SR). With respect to Software that contains elements provided by third party suppliers, End User may install and use the Software in accordance with the terms and conditions of the applicable license agreements, such as shrinkwrap or clickwrap license accompanying or applicable to the Software (Shrinkwrap License). The text of the Shrinkwrap License will be available from Avaya upon End Users request (see Third-party Components for more information). Copyright Except where expressly stated otherwise, no use should be made of materials on this site, the Documentation(s) and Product(s) provided by Avaya. All content on this site, the documentation(s) and the product(s) provided by Avaya including the selection, arrangement and design of the content is owned either by Avaya or its licensors and is protected by copyright and other intellectual property laws including the sui generis rights relating to the protection of databases. You may not modify, copy, reproduce, republish, upload, post, transmit or distribute in any way any content, in whole or in part, including any code and software. Unauthorized reproduction, transmission, dissemination, 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.

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: securityalerts@avaya.com. 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

Contents
About this document ....................................................................................................................................... 8 Scope of this document.............................................................................................................................. 8 Intended Audience ..................................................................................................................................... 9 Conventions used in this document ........................................................................................................... 9 Related documents .................................................................................................................................. 10 Application Enablement Services documents...................................................................................... 10 Communication Manager documents .................................................................................................. 11 ECMA documents................................................................................................................................ 11 Providing documentation feedback .......................................................................................................... 12 New Features and Capabilities ..................................................................................................................... 13 Chapter 1: API Services................................................................................................................................ 14 Service Provider Class ............................................................................................................................. 17 Device Class ............................................................................................................................................ 20 Phone Class............................................................................................................................................. 21 Media Class ............................................................................................................................................. 23 Call Information Link Class....................................................................................................................... 26 Third Party Call Controller Class .............................................................................................................. 27 XML Processor Class............................................................................................................................... 32 Constant Classes ..................................................................................................................................... 33 Chapter 2: Getting started............................................................................................................................. 34 Setting up the development environment ................................................................................................. 34 Downloading the Application Enablement Services Device, Media and Call Control .NET API SDK .. 34 Setting up Visual Studio ...................................................................................................................... 35 Setting up your test environment......................................................................................................... 35 Understanding basic CSTA concepts....................................................................................................... 35 First Party vs Third Party ..................................................................................................................... 36 Devices................................................................................................................................................ 36 Physical Elements ............................................................................................................................... 36 Logical Elements ................................................................................................................................. 37 Calls .................................................................................................................................................... 37 Service Requests ................................................................................................................................ 37 Service Responses.............................................................................................................................. 38 Events ................................................................................................................................................. 38 Negative acknowledgements............................................................................................................... 38 Signaling Encryption ................................................................................................................................ 39 Media Encryption ..................................................................................................................................... 39 Accessing the client API reference documentation .................................................................................. 40 Using the Device, Media and Call Control Dashboard ............................................................................. 40 Learning from sample code...................................................................................................................... 40

Chapter 3: Writing a client application........................................................................................................... 42 The Dashboard tool.................................................................................................................................. 42 Session Management............................................................................................................................... 43 Start Application Session..................................................................................................................... 44 Reset Application Session Timer......................................................................................................... 45 Exercise: Starting the Application Session .......................................................................................... 46 SessionCharacteristics............................................................................................................................. 47 DeviceID Type..................................................................................................................................... 47 Event Filter Mode ................................................................................................................................ 48 Device Identifiers (DeviceID).................................................................................................................... 49 Populating the Device ID Switch Name ............................................................................................... 50 Controllable By Other Sessions........................................................................................................... 51 Device ID Instances............................................................................................................................. 52 Exercise: Getting A Device ID ............................................................................................................. 53 Notification of Events ............................................................................................................................... 54 Register for Events .............................................................................................................................. 55 Unregister for Events........................................................................................................................... 55 Exercise: Registering for Events ......................................................................................................... 56 Registering Devices ................................................................................................................................. 57 Controllable telephone types ............................................................................................................... 59 Dependency Modes............................................................................................................................. 59 Media Modes....................................................................................................................................... 61 Choosing a media mode...................................................................................................................... 62 The "share-talk" button ........................................................................................................................ 64 Interpretation of the share-talk button lamp state............................................................................... 65 Choosing a codec................................................................................................................................ 66 Choosing the media encryption ........................................................................................................... 66 Exercise: Performing a Device Registration ........................................................................................ 67 Exercise: Performing Operations on a Registered Device................................................................... 69 Expanded help feature ............................................................................................................................. 71 Writing Code ............................................................................................................................................ 73 Writing applications that run in a browser................................................................................................. 84 Telephony Logic....................................................................................................................................... 84 Knowing what buttons are administered.............................................................................................. 85 Detecting an incoming call................................................................................................................... 85 Determining that far end has ended the call ........................................................................................ 85 Getting ANI information for a call......................................................................................................... 85 Recording and playing voice media..................................................................................................... 86 Media Operations ................................................................................................................................ 87 Determining when far-end RTP media parameters change................................................................. 88

Chapter 4: Recovery ..................................................................................................................................... 89 Session Recovery................................................................................................................................ 89 Transfer Monitor Objects ..................................................................................................................... 91 Chapter 5: Cleanup....................................................................................................................................... 93 Chapter 6: High Availability ........................................................................................................................... 95 DMCC Service Recovery ......................................................................................................................... 95 DMCC Support of ESS and LSP .............................................................................................................. 98 Programming Considerations for High Availability ................................................................................. 100 Chapter 7: Media Encryption....................................................................................................................... 101 The AES Encryption Scheme................................................................................................................. 101 Specifying the Devices Encryption Capability........................................................................................ 104 MediaStartEvent Handling...................................................................................................................... 105 Media Encryption Information............................................................................................................ 105 Encrypting and Decrypting the RTP Stream........................................................................................... 106 Roll Over Counter (ROC) .................................................................................................................. 106 Creating the Encryption Keys Using the Pseudo Random Function.................................................. 107 Creating the Initialization Vectors (IV) ............................................................................................... 107 Decrypting the Media Payload........................................................................................................... 109 Test Data........................................................................................................................................... 109 Chapter 8: Security Considerations ............................................................................................................ 111 Advanced authentication and authorization policies............................................................................... 112 User Authentication Policies................................................................................................................... 112 User Authorization Policies .................................................................................................................... 113 SDB ................................................................................................................................................... 113 Enterprise Directory........................................................................................................................... 113 Unrestricted Access........................................................................................................................... 114 AA Policy Use Cases ............................................................................................................................. 114 Server based applications without enterprise user identities ............................................................. 114 Enterprise user based applications where user controls only their own telephone............................ 115 Chapter 9: Debugging................................................................................................................................. 116 Error Messages...................................................................................................................................... 116 Possible race conditions.................................................................................................................... 117 Improving performance...................................................................................................................... 117 Getting support....................................................................................................................................... 118 Appendix A: The J-Scripts Library............................................................................................................... 119 J-Script ................................................................................................................................................... 119 ActiveX Service Provider........................................................................................................................ 120 Static event handlers.............................................................................................................................. 121 Requests, response events, and events ................................................................................................ 121 J-Script object ........................................................................................................................................ 123

Service Provider Methods and Events............................................................................................... 124 Phone Methods and Events .............................................................................................................. 124 Media Methods and Events ............................................................................................................... 125 Third Party Call Controller Methods and Events................................................................................ 125 Call Information Methods and Events................................................................................................ 126 J-Script library configuration................................................................................................................... 127 Server-side Instructions.......................................................................................................................... 127 Client-side Instructions ........................................................................................................................... 127 Appendix B: Communication Manager Features......................................................................................... 129 Appendix C: Constant Values ..................................................................................................................... 131 Phone Object Enumerations and Constants .......................................................................................... 131 Media Enumerations .............................................................................................................................. 140 Service Provider Enumeration................................................................................................................ 141 Third Party Call Control Enumerations ................................................................................................... 141 Appendix D: Unicode Mapping Table.......................................................................................................... 142 Appendix E: Server Logging ...................................................................................................................... 143 Appendix F: TSAPI Error Code Definitions ................................................................................................. 146 CSTA Universal Failures ........................................................................................................................ 146 ACS Universal Failures .......................................................................................................................... 148 Appendix G: Routeing Services .................................................................................................................. 150 Routeing Services Sequence Diagram................................................................................................... 150 Requests to end a routeing registration session:............................................................................... 151 RouteRegister ........................................................................................................................................ 152 RouteRequest ........................................................................................................................................ 153 RouteSelect............................................................................................................................................ 154 RouteUsed Event ................................................................................................................................... 155 RouteEnd Request................................................................................................................................. 156 RouteEnd Event: .................................................................................................................................... 156 RouteRegisterAbort................................................................................................................................ 159 RouteRegisterCancel ............................................................................................................................. 160 Appendix H: IPv6 Support........................................................................................................................... 161 Usage of IPv6 addresses in AE Services ............................................................................................... 162 Mixed IPv4 and IPv6 networks ............................................................................................................... 163 Glossary...................................................................................................................................................... 164 Index ........................................................................................................................................................... 167

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 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. Appendix H: IPv6 Support discusses the ability to use IPv6.

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

Conventions used in this document


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

Code and Linux commands .NET class, method and field names

request = new GetDeviceId();

the getDeviceID method

Window names Browser selections Hypertext links

The buttons are assigned on the Station form. Select Member Login 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 42.

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 Programmers Reference Dashboard Users Guide (see the SDK zip file) ReadMe.txt (see the SDK zip 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 (02-300360) Avaya Aura Application Enablement Services Installation and Upgrade Guide for a Software Only Offer (02-300355) Avaya Aura Application Enablement Services Installation and Upgrade Guide for a Bundled Server (02-300356) Avaya Aura Application Enablement Services Administration and Maintenance Guide (02-300357) Avaya Aura Application Enablement Services Device, Media and Call Control API XML Programmer Guide (02-300358)

10

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 Avaya Aura Application Enablement Services TSAPI for Avaya Communication Manager Programmer Reference (02-300544) Avaya Aura Application Enablement Services TSAPI Programmer Reference (02-300545) Avaya Aura Application Enablement Services Java Telephony API (JTAPI) Programmer 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 (02300549) Avaya Aura Application Enablement Services ASAI Protocol Reference (02300550)

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

11

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 document@avaya.com Thank you.

12

New Features and Capabilities


New features and capabilities in AE Services 6.1 are:

Enhancements to DMCC Service and API (see Chapter 1 )

Supplement Third-Party Call Control functionality to include additional TSAPI functionality


Call Control Services LogicalDeviceFeature services Call Monitoring (PerCall or CallsViaDevice)

Add support for Avaya value-added extensions Ability to change an existing service monitor Routeing Services (New Service see Appendix G) Support for pure IPv6 network Support for mixed IPv4 & IPv6 networks AE Services detection and response to failover of Main Communication Manager to ESS or LSP

IPv6 Support. (see Appendix H)


Enhanced Support of Communication Manager Failover (see Chapter 6)

13

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

14

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 AES License Classes CSTA specifications XML Consumed Services protocol Service Application ECMA-354 ECMANone Provider Session Ch.4 354, Services Ch.5 Service Capability ECMA-269, ECMANone Provider Exchange sec. 13 323, sec. Services 11 Phone Physical ECMA-269, ECMANone2 Device sec. 21 323, sec. Services and 19 Events Media Voice Unit ECMA-269, ECMANone 2 Services and sec. 26 323, sec. Events 24 Third Party Call Control ECMA-269, ECMATSAPI or Advanced Call Control Services sec. 17 323, sec. TSAPI 15 Third Party Logical Device ECMA-269, ECMATSAPI Call Control Services sec. 22 323, sec. 20 Third Party Snapshot ECMA-269, ECMATSAPI Call Control Services sec. 16 323, sec. 14 ECMA-269, ECMADepends on Service All Monitoring Services1 sec. 15 323, sec. being monitored 13 Third Party Routeing ECMA-269, ECMAAdvanced TSAPI Call Control Services sec. 20 323, sec. 18 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.

1 2

This API implements the intent of CSTAs Monitoring Services using .NET Event Handlers 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.

15

Table 2: Correlate Avaya Extensions to the .NET API Avaya Extends Purpose Extensions which CSTA Service Set Call Call None Provides the ability to 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 Services for a given dial string on Communication Manager Media Extended Voice Unit Provides dubbing of Voice Unit Services recorded messages Services and other extensions to playing and recording of files Media Media Control None Provides the ability to Events be notified when the far-end RTP and RTCP parameters for a media stream change. Phone Registration None Provides ability to Services gain main, dependent or independent control over Communication Manager endpoints also referred to as device registration Service E164 None Allows an application Provider Conversion to convert from an Services E.164 to a Communication Manager dial string and vice versa. Media Tone None Detects DTMF tones Collection and buffers them as Services and requested before Events reporting them to the application Media Tone Replaces Detects DTMF tones Detection Data and reports each Events Collection tone as it is detected Services .NET API Classes

AES License Consumed None

None

None

None

DMCC or IP_API_A

None

None

None

16

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 acts as a bootstrap class for connecting to the server, performing session management, retrieving other objects and disconnecting from the server. To learn how to use the Service Provider Class, see The Dashboard tool on page 42 The Service Provider Class provides the following asynchronous operations:

Table 3: Method Name ConvertDialStringToE164 ConvertE164ToDialString Get Auto Keep Alive Enabled Get Device Get Device ID List Get Monitor List Get New Device

Service Provider Class Requests Description Convert one or more dial strings to E164 format. Convert one or strings which are in E164 format to dial strings. Lets the application know if auto keep alive is enabled. Given a device name (Id), returns a reference to the associated Device. Get all the Device IDs that are active on the DMCC server. Get a list of all the monitors which are active on this DMCC server. 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 AES. Before Release 5.2 you would need three separate AES computers to do this. Requesting the Device Instance is optional so your existing

17

application will work the same if you do not need or desire this capability. Get Physical Device Information Get Physical Device Name Get Session ID List Reconnect Gets device information for the specified device. Gets the device name for the specified device. Retrieve all the active sessions that are running in a DMCC server. 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. Sends a ResetApplicationSession XML message to the server. Start the monitor for session management. Stop a session management monitor. 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.

Reset Application Session Session Management Start Monitor Session Management Stop Monitor SetSessionCharacteristics

18

Shut Down

Start Application Session Start Auto Keep Alive

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). Initiates an application session between an application and a server Tells the API to start automatically sending the ResetApplicationSession messages every intervalInMs milliseconds. 1,000 milliseconds is 1 second. Terminates an existing application session. Stops the ResetApplicationSession messages from automatically being sent to the server. 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. Retrieves the API version for the server. Returns a reference to the CallInformationLink object. Retireves the last XML message received. Returns the session name (id) as a string. Returns a reference to the ThirdPartyCallControl object. Returns a reference to the XML Processor object.

Stop Application Session Stop Auto Keep Alive

Transfer Monitor Objects

Get Actual Protocol Version Get Call Information Link Get Last Incoming Xml Message Get Session ID Get Third Party Call Controller Get Xml Processor

The Service Provider Class raises the following events:

19

Table 4: Event Name Missed At Least One Keep Alive Event Server Connection Down Server Connection Not Active

Service Provider Events Description Occurs if the server has missed at least one keepalive Occurs if the socket to the AE Services server has gone down for some reason Occurs if a message was received by the AE Services server but the session has timed out and been placed in the inactive state

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 on page 42. The Device Class provides the following asynchronous operations: Table 5: Method Name Get Device ID As String Device Class Requests Description Gets the device identifier that represents the device described by its extension number and the Communication Manager upon which it resides, as a string Returns the extension associated with this device. Returns the reference to the phone object for this Device. Returns an instance of a Service Provider object. 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. Sends a ReleaseDeviceId XML message to the server.

Get Extension Get Phone Get Service Provider Get Device ID

Release Device ID

20

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 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 on page 42. The Phone Class provides the following asynchronous operations: Table 6: Method Name Change Device Security Code Phone Class Requests Description Allows a DMCC client to change the security code of an extension on Communication Manager. Allows a DMCC client the ability to change the attributes of an existing monitor. Allows a DMCC client to validate the security code of an extension on Communication Manager. Returns the device that this phone object is in. Returns the current media mode that the phone is in.

Change Monitor

Validate Device Security Code

Get Device Get Media Mode

21

Get Media Get Registered Get Button Info

Returns the media object which will perform all media operations on this phone. Returns true if the phone is currently in the registered state. 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) Gets a snapshot of the contents of the physical device's display Gets the hookswitch status of a specified device, either on hook or off hook 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 Gets the message waiting status at a specified device, either on or off Get the current registration state for the phone. 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 Simulates the depression of a specified button on a device Instruct Communication Manager to direct the media to a different IP Address 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.

Get Display Get Hookswitch Status Get Lamp Mode

Get Message Waiting Indicator Get Registration State Get Ringer Status

Press Button Redirect Media Register Terminal

Set Hookswitch Status

See Appendix D for more information. Sets the hookswitch status of a specified device to either onhook or offhook

22

Start Monitor

Stop Monitor Unregister Terminal

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 Cancels a previously initiated Start Monitor request 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: Event Name Display Updated Hookswitch Updated Lamp Updated Ringer Status Updated Unregister Terminal Phone Class Events Description Occurs if the contents of a device's display has changed Occurs if Communication Manager has changed the device's hookswitch status Occurs if the lamp mode status of a particular lamp has changed Occurs if the ringer attribute associated with a device has changed status 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. This class will allow an application to record voice stream data coming into a device and to play messages to the devices 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

23

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 on page 42 and Recording and playing voice media on page 86. The Media Class provides the following asynchronous operations: Table 8: Method Name Change Monitor Delete Message Flush tone Collection Buffer Media Class Requests Description Allows a DMCC client to change the attributes of an existing monitor. Deletes a specified file from the connector server Reports the DTMF tones received since the last time the buffer was flushed and flushes the buffer Returns the parent Device object that the media object is a part of. Resume only playing, not recording Resumes only recording, not playing. 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 Cancels a previously initiated Monitor Start request Sends a Start Playing XML message to the server. Stops only the player, not the recorder. Suspends only the player, not the recorder. Sends a Start Recording XML message to the server.

Get Device Resume Playing Resume Recording Start Monitor

Stop Monitor Start Playing Stop Playing Suspend Playing Start Recording

24

Stop Recording Suspend Recording Start Dubbing Stop Dubbing Set Tone Retrieval Criteria Start Tone Collection Stop Tone Collection

Sends a Stop Recording XML message to the server. Suspends only the recorder, not the player. Starts replacing an existing recording session with the specified file Stops replacement of an existing recording session Specifies the retrieval criteria Used to start collecting DTMF tones sent to a device and specifies the termination criteria. 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: Event Name Playing Playing Suspended Playing Stopped Media Class Events Description Indicates that a message is being played Indicates that a message is suspended in play Indicates that a play (or record) operation of a message on a device has been stopped or has completed. Indicates that a message is being recorded Indicates that a message is suspended during recording Occurs when DTMF tones are retrieved from the buffer. This event reports the retrieved tones to the application. Occurs when a DTMF tone has been sent to the device 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. Indicates when the far-end RTP parameters have changed to null and the RTP session has been disconnected

Recording Recording Suspended Tones Retrieved

Tone Detected Media Started

Media Stopped

25

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 connector server. The Call Information Link Class provides the following asynchronous operations: Table 10: Method Name Get Call Information Get Link Status Start Monitor Call Information Link Class Requests Description Used to get detailed call information. Used to get the status of the call information link to the connector server. 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. Cancels a previously initiated Monitor Start request

Stop Monitor

The Call Information Link Class raises the following events: Table 11: Event Name Link Up Call Information Link Class Events Description 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. 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 connector server will attempt to reconnect automatically.

Link Down

26

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 The Third Party Call Controller Class provides the following asynchronous operations: Table 12: Method Name Alternate Call Answer Call Change Monitor Clear Call Clear Connection Conference Call Third Party Call Controller Class Requests Description Performs a third party Alternate Call operation (put active call on hold and unhold held call). Performs a third party Answer Call operation (answers an incoming call). Allows a DMCC client to change the attributes of an existing monitor. Perform a third party Clear Call operation (drops all parties on a call). Performs a third party Clear Call operation (drops all parties on a connection). Performs a third party Conference Call operation (merges the held call into the active call). Performs a third party Consultation Call operation (puts the active call on hold and calls another device). Provides support for a

Consultation Call

27

Direct Agent or Supervisor Assist Call.

Deflect Call

Performs a third party Deflect Call operation (directs an incoming call to another destination). Performs a third party Directed Pick Up operation (moves a specified call and connects it at a new specified destination). Performs a third party Generate Digits operation (inject touch tone digits into an active call). 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. Provides the extension of each ACD agent logged into the specified ACD split.. Provides the agent state at a specified device. Retrieve the Call Linkage Data for a normal callID. (Avaya Universal Call ID - UCID). Performs a third party Get Do Not Disturb operation (determines if Do Not Disturb, AKA Send All Calls, is active). Gets a third party device identifier information for the selected DeviceId. This information is necessary in order to perform other third party call functions. Performs a third party Get Forwarding operation (determines if call forwarding is active, if so the call forwarding destination is provided). Performs a third party Hold Call operation (puts an active call on hold). 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

Directed Pick Up

Generate Digits

Get ACD Split

Get Agent Login

Get Agent State

Get Call Linkage Data

Get Do Not Disturb

Get Third Party Device ID

Get Forwarding

Hold Call Make Call

28

Make Predictive Call

devices for a user station and an ACD agent logged into a specified split (aka Agent Call) or an ACD agents extension and another station extension (typically a supervisor) device (aka Supervisor Assist Call). Performs a third party Make Predictive Call operation (originates a call between two devices by first creating a connection to the called device). Performs a third party Reconnect Call operation (drops the active call and unhold a call that is held). Performs a third party Retrieve Call operation (takes a call off of hold and makes it active). The RouteRegister request is used to tell AES 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 AES to the client application. When the client application receives the "RouteRequest" event from AES the client application then decides how to route the call and instructs AES via the "RouteSelect" method.

Reconnect Call

Retrieve Call Route Register

Route Register Cancel

The RouteRegisterCancel request is used to tell AES that the client application is no longer interested in receiving RouteRequests for the specified Route Register Requester Id. The RouteSelect request is used to tell AES how the call should be routed.

Route Select

Route End

The RouteEnd request is used to tell AES that the client application is done routing the call.

29

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 another specific party or all other parties on the call. It allows a client application to put a partys (subjectConnection) listening path to a selected party (selectedParty) on listenhold, or all parties on an active call on listenhold. 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). Allows the client application to allow a party, which was in a listen hold state, to resume listening to a call. Allows the client application to change the agents state at a specified device (including work mode and reason code). Performs a third party Set Display operation (overwrites the current display of the specified Device ID. Note:Special administration on DMCC must be done to support this capability). Performs a third party Set Do Not Disturb operation (allows you to enable/disable Do Not Disturb AKA Send All Calls). Performs a third party Set Forwarding operation (allows you to enable/disable Call Forwarding for the specified Device ID). Adds a device to an existing call. Performs a third party Single Step Transfer Call operation (transfers an active call to another device).

Selective Listening Retrieve

Set Agent State

Set Display

Set Do Not Disturb

Set Forwarding

Single Step Conference Call Single Step Transfer Call

30

Snapshot Call Snapshot Device Start Monitor

Provides information about the devices participating in a specified call. Provides information on the status of calls at a specific device. Informs the API of what type of Third Party Call Control events the application wishes to be notified of. There are two Call information events: link-up and link-down. Turn a monitor off. Performs a third party Transfer Call operation (transfers the call on hold to the active call and drops the party doing the transfer).

Stop Monitor Transfer Call

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: Event Name Agent Logged Off Agent Logged On Agent Login Extension Call Cleared Conferenced Connection Cleared Delivered Diverted Do No Disturb Established Failed Forwarding Held Network Reached Third Party Call Control Class Events Description Event registration for Agent Logged Off event. Event registration for Agent Logged On event. Event registration for Agent Login Extension event. Event registration for Call Cleared event. Event registration for Conferenced event. Event registration for Connection Cleared event. Event registration for Delivered event. Event registration for Diverted event. Event registration for Do Not Disturb event. Event registration for Established event. Event registration for Failed event. Event registration for Forwarding event. Event registration for Held event. Event registration for Network Reached event.

31

Originated Queued Retrieved Service Initiated Transferred

Event registration for Originated event. Event registration for Queued event. Event registration for Retrieved event. Event registration for Service Initiated event. Event registration for Transferred event.

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 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: Method Name Inject XML XML Processor Class Requests Description 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: Event Name Unhandled XML Message XML Data Inject XML Response XML Message Sent XML Processor Class Events Description Event registration for getting notified when XML messages are not processed by the API. Event registration for responses to InjectXml request. Event registration for getting notified when XML messages are sent to the server.

32

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

Please see Appendix C: Constant Values for more information on these constant classes.

33

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 up the development environment Understanding basic CSTA concepts 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. 2. 3. 4. Go to www.avaya.com/devconnect Select Member Login. Log in with your email address and password. Download the SDK (dmcc-dotnet-sdk-x.zip) 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.zip, 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. Expand the SDK ZIP file using any application or tool that recognizes the ZIP file format. All of the SDK files are placed into a directory named dmcc-dotnetsdk.

34

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 Installation and Upgrade Guide for the offer you have purchased (Bundled, Software Only or System Platform).

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 Devices Physical Elements Logical Elements Calls Service Requests Service Responses Events Negative Acknowledgements

35

First Party vs Third Party


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

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

36

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 lamps status, or notify me when a tone comes into the device. 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 requests 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 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

37

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 CSTAs atomic model). Other service requests, particularly those that require the AE Server to pass on a request to Communication Manager, take multiple steps to complete. (These follow CSTAs multistep 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 40.

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

38

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 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) 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 66. The list of application-supported media encryption schemes will be matched to the list of encryption schemes provisioned on Communication Managers change ip-codec-set page for the devices 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 105.

39

Accessing the client API reference documentation


You may need to reference the .NET Programmers 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 42.

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 following directory:
cmapinet-sdk/examples/src/samples

40

Application or Class

Simple Record

Table 16: Sample code Language written File path names under in cmapinetsdk/examples/src/sampl es simpleRecord C#

Description

Simple RecordVB Soft phone in a browser

Visual Basic

simpleRecordVB

This application provides a 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. This application is identical to Simple Record except is was written in Visual Basic. This is an HTML page which demonstrates a simple softphone which runs in a browser. The softphone can run in telecommuter mode or in no media mode. This is an HTML page which provides basic dashboard capabilities.

HTML and JScript

Sample web page is in:


jScript/softphone

The html document name is:


IeSoftphone.html

Dashboard in a Browser

HTML and JScript

JScript\dashboard

41

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 6.1 SDK ships with an updated version of the Dashboard. All the new 6.1 capabilities are supported in the Dashboard. The Dashboard has a checkbox which will highlight all the new and modified features in 6.1. 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.

42

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.

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 Server to connect to identify the application establish an application session gain access to all API services

43

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.

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 Server. Using a browser, go the AE Services OAM 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 Server. You need to indicate if this port is a secure socket (usually checked if port 4722 is used)

44

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 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: 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 vaule. 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 / 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: 1. Close the socket 2. Mark the session as inactive 3. Start the cleanup timer using the time specified in the Cleanup Delay.

45

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.

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

46

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
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 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 Charcteristics 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 on AE Services OAM 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. 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.

47

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 and Logical Device Feature 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 OAM 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 generally beneficial to hide the presence of such silent observers from an enduser 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

48

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 assistants 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 peruser provisioning.

Device Identifiers (DeviceID)


AES 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 AES. A Device ID can be controlled by more than one session based on either of the following: Device ID Instances AES Services allows you to create up to three instances of a device identifier. 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. Additional information on each of these items will be discussed in a later section. 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 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 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

49

Must be released to be cleaned up Are not exclusive to session Can be obtained from Device Services or may be returned by Call Control Services/Logical Device Feature Services/Snapshot Services Can only be used with Call Control Services, Logical Device Feature Services and Snapshot Services Need not be released

Third party device identifiers have the following properties:

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

Populating the Device ID Switch Name and Switch IP Interface fields


For first-party device IDs 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 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 web OAM for the given Switch Connection. Thus, 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

50

of the DeviceID. Later, when the application attempts to register the device, it would register with that gatekeeper. Unfortunately, if the gatekeeper was out-ofservice 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. 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. Furhermore, the probability of picking an out-of-service gatekeeper IP address is much reduced.

For third-party device IDs: Your application must always specify a switchName, and an extension when getting a device ID. There is no switchIPInterface for third-party device IDs. 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.

Note:

Controllable By Other Sessions


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, clientside, 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

51

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 Server. For first-party device IDs: There are two ways to populate the controllableByOtherSessions field: 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 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 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 that 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.

52

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.

Specifically we need: Extension Switch Name (or IP Address) Do we want other sessions to also control this station

53

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. For example, after requesting to register a device an event is received from the AE Server indicating whether the request succeeded or failed.

54

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 Server. ResponseHandlers are used to inform the application of soliciated events (responses) to a request originally issued by the application to the AE 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 Programmers Reference. 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 Server which can be used to modify or stop the associated monitor. This will be perform from the Dashborad tool in the Registering for Events section.

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.

55

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.

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.

56

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
To monitor or control a device, an application must register the device with Communication Manager. This tells Communication Manager whether you want Main, Dependent or Independent control of the device and what kind of media access you want. Only devices that are softphone enabled on Communication Managers Station form can be registered. 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, not call control.

57

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 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. All three endpoints that are registering to an extension can request separate media streams. Each DMCC endpoint registration must go through AE Servers. All three DMCC endpoints registered to a common extension can be configured to be in 3 different network regions. AE Services 4.1 and Communication Manager 5.0 allow up to two DMCC clients to register to a common extension to which an Avaya IP Softphone is registered in Roadwarrior/Telecommuter mode. If an Avaya IP Softphone is registered in shared control mode to a physical set, one DMCC Station client can register to the same extension. 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 Agent (at extension 1000) and extensions 1001 and 1002. Note that 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 RegisterTerminal request you must at a minimum specify which device to register and the password that is administered for the device on the Station form. There are also a number of options to choose from. For more details on setting up a RegisterTerminal request, see the Programmers Reference. The only registration-related event supported is the Phone classs 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. 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

58

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. 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 (bundled server or software only). 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 end point can also register as Main. For Call Control, any Communication Manager supported endpoint can be controlled by the AE Services server You cannot choose Independent or Dependent dependency mode with SIP endpoints, so you cannot exercise device monitoring/control over them.

Dependency Modes
At registration time, the application specifies the desired registration dependency mode. This indicates who controls the devices physical elements and media. The dependency choices are: Main dependency mode There can be only one Main registrant associated with an extension. 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 register as Dependent or Independent via the "share-talk" button. Note: "share-talk" button push is processed only if an endpoint registers using any media mode other than No Media.

Independent dependency mode

59

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 on page 64 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. Independent 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 doesnt 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

60

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 realtime 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 17: Registration Dependency and Media modes Client Telecommuter Server No Media Main Dependent Independent Allowed2 Allowed Allowed Alloweda Not Allowed Not Allowed Alloweda Allowed Allowed Allowed Allowed3 Allowed

When multiple endpoints are registered to the same extensions, all endpoints see activity on other endpoints when status changes to the devices 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.

2 3

Corresponds to Exclusive Control in previous releases.

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 devices 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 devices hookswitch, lamps, ringer, and display.

61

Speaker button press, Head Set button press and taking Head Set off the cradle are seen as off-hook by Communication manager. And therefore other endpoints registered to the same extensions will only see 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 Alaw, G.711 Mulaw, 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 events.

Table 18: Media modes Server media mode When to use

Choosing a media mode How to set Set MediaInfo.MediaControl to Media.MediaMode.SERVER _MODE in the MediaInfo argument that is passed in the Phone.RegisterTerminal () method.

This mode is used when the application wants the AE Services server to handle media processing. The AE Services server handles media with Voice Unit Services and Tone Detection Services or Tone Collection Services. Voice Unit Services is used to record and play messages. Tone Detection Services or Tone Collection Services are used to detect out-of-band 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.

62

Client media mode

This mode is used when application wants to process the media itself. The RTP stream can be terminated on any machine that can be controlled by the application. To detect changes to the far-end RTP/RTCP parameters, add delegates on Media.MediaStartedEvents and Media.MediaStoppedEvents. To detect out-of-band DTMF tones, you can add delegates to the tone collection events or the tone detection events in the Media class. This mode is used when an application wants the media to go to a real telephone. The real telephone can be an internal dial string to Communication Manager or a PSTN telephone number. Note: Although it is possible for the client application to start a monitor on a terminal that is registered in telecommuter mode, the client application will not receive events. This mode is used when the application does not want an RTP stream to be setup to it by Communication Manager. Note: Although it is possible for the client application to start a monitor on a terminal that is registered in no-media mode, the client application will not receive events. When the application does not need the media stream to be processed.

Set MediaInfo.MediaControl to Media.MediaMode.CLIENT _MODE in the MediaInfo argument that is passed in the Phone.RegisterTerminal () method.

Telecommuter mode

Set MediaInfo.MediaControl to Media.MediaMode.TELECO MMUTER in the MediaInfo argument that is passed in the Phone.RegisterTerminal () method. Set MediaInfo.MediaControl to
Media.MediaMode.NONE

No Media

in the MediaInfo argument that is passed in the Phone.RegisterTerminal () method.

No media

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 19: Media control capabilities Record media from a call into a WAV file Media Control Capabilities server media mode provided by the server client media mode provided by the application

63

Dub a recording with the contents of another compatible WAV file Play a voice announcement or tone from a prerecorded WAV file Play a list of prerecorded announcements from separate WAV files Stop, pause, or resume outstanding play or record operations Detect out-of-band DTMF tones

provided by the server provided by the server provided by the server

provided by the application provided by the application provided by the application

provided by the server provided by the server provided by the server provided by the server

provided by the application provided by the application provided by the application provided by the application provided by the applicationa

Detect inband DTMF tones

Manage media related event listeners

Originate and terminate RTP streams on any machine that the application has control of Media encryption provided by the server

provided by the application4

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

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.

64

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

65

Choosing a codec
A codec is the algorithm used to encode and decode audio media. For devices choosing media modes of either client 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)

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 connector 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 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 Chapter 1 of the Avaya Aura 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 devices media stream. The media encryption options are: Advanced Encryption Standard (AES) 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 connector 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

66

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.

Exercise: Performing a Device Registration


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. Specifically we need: Password E911 Information (if any) Force Login Media Mode Dependency Mode

67

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

68

Exercise: Performing Operations on a Registered Device


So, lets make an outgoing call to 5386000 and see what happens.

Now we will hang up:

69

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.

70

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

71

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.

72

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.

73

Right click on References and select Add Reference

74

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 .zip file).

75

Select OK and you should now see it in the list of references.

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;

76

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

77

78

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.

79

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.

80

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

81

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.

82

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 Dashboards capabilities. The Dashboard exposes all the DMCC functionality which is available to you from .NET including, but not limited to:

83

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

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.

Telephony Logic
The following sections will give general instruction how to perform common things around the telephone. We encourage you to use the Dashboard application to

84

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

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. To get this information, you must set a phone monitor to monitor these events. 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: Returns to an idle state showing extension, date and time information Begins showing information about a ringing call at the extension Is not updated and continues to show information relative to an active display feature such as Directory Lookup

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.

85

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 62. 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 23. 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 40. 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. See http://www.sonicspot.com/guide/wavefiles.html for a description of the Wave structure. 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 connector server All Wave files are assumed to be on the AE Services server machine in the directories specified in the OAM 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.

86

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: While in server mode, you can find out what codecs have been chosen 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. 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 on page 117 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.

87

Determining when far-end RTP media parameters change


You will need to set a monitor for the Media Started and M3dia Stopped events. When the RTP media changes, you will be notified by these events. Use the Dashboard tool to experiment and use the Visual Studio code snippets to help you write the code.

88

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.

Session Recovery
Since the session cleanup time delays the cleanup of a client applications 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

89

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 applications 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 a SessionCleanedUp exception is received on the call to reconnect, it should be processed as a ServerSessionTerminated event would be. If any other exception is received, 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 exceptions. 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 connector server during establishment of an application session, and an instance of a ServerConnectionDownEvent occurring during subsequent session management.

90

Figure 1:
Client Application <Get Service Provider>

Session Management Recovery


API Library Connector Server

<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 is 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 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:

91

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 set up the new session to receive the events from the transferred monitors. The client application must release the resources that were allocated for the original session.

92

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 Media.stopRecording method and Media.stopPlaying 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 connector 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 indicating that unregistration is required before the device can be released. 4. Stop the monitor(s)

93

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 applications ServiceProvider instance.

94

Chapter 6: High Availability


The AE Services on System Platform offer provides the High Availability feature. With the High Availability feature, you can install two identical servers that can be addressed and administered as a single entity. If one server fails, the second server quickly and automatically becomes available to client applications. High Availability is synonymous with Automatic Failover of AE Server. This feature applies to the AE Services on System Platform offer only. It is not provided with the AE Services Software-Only offer or the AE Services Bundled Server Upgrade (Dell 1950 and IBM x306 and x306m platforms). For more information on the AE Services High Availability feature, see the document: Implementing AE Services on System Platform. AE Services 5.2 introduced a number of High Availability 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 Server platforms. For additional information, please see the DMCC Service Recovery section. For AE Services 6.1, another High Availability feature has been added. This features better support of Avaya Aura Communication Manager failover strategies particularly, failover to an Enterprise Survivable Server (ESS) and/or to a Local Survivable Processor (LSP). For additional information, please see the DMCC Support of ESS and LSP section. This chapter describes: DMCC Service Recovery DMCC Support of ESS and LSP Programming considerations for HA

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, from a persisted store that contains selected state information for session, device, monitors and registration. This feature is available on a single server platform in addition to the dual-server System Platform. On a single server, the feature will not guard against a hardware failure but does allow your application to retrieve its state if a software failure leads to a restart. In conjunction with the AE Services on System Platform, this feature will allow your application to retrieve its state even if 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

95

does not affect the way that the client application registers the device(s) via the AE Server. However, the Time-to-Service feature must be enabled for the appropriate IP network region on Communication Manager, or DMCC recovery of the device registration(s) will not be possible. 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 its 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 server. 4. A failover operation from one AE Services Virtual Machine (AES VM) to another one on the same System Platform (SP). How does DMCC Service Recovery work? As usual, a session is created for a client application when it is authenticated by the DMCC service. 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 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 usual) a device is created for a client when a GetDeviceID request is processed by the DMCC service. 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. Again, (as usual) a monitor is created for a client when a MonitorStart request is processed by the DMCC service, and a ChangeMonitorFilter request changes the filter

96

configuration of the monitor. 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 registration is created for an endpoint (extension) when a RegisterTerminal request is processed by the DMCC service. Again 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 Server. Thus, on detecting such an outage, the client application should attempt to re-establish the connection and its associated DMCC session(s). Some important considerations for DMCC Service Recovery Note: 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 keeping 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 o o Immediately if the cleanup timeout value equals 0 mins. After 5 minutes if the cleanup timeout value is less than 5 mins. 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 that, for the AES Virtual Appliance Offer, the System Platform failover takes approximately 3 mins, 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

97

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 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. Note: 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: o The RAS keep-alive messages between the AE 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 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 reestablished.

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

DMCC Support of ESS and LSP


This feature is available on a single server platform, in addition to the dual-server System Platform. Note that it does not guard against a failover of the AE Server itself; instead, it guards against the possibly unfortunate consequences of a failover of the Communication Manager Server. Like DMCC Service Recovery, DMCC ESS & LSP Support is a software feature designed to recover one or more DMCC devices previous states, following a software

98

fault (or shutdown) that causes the Communication Manager to failover to an Enterprise Survivable Server (ESS) or to a Local Survivable Processor (LSP). The recovery 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 an UnregisterTerminalEvent 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 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 has been 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. If a re-registration fails (for any reason), then the client application will receive a normal UnregisterTerminalEvent for that station. 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-regsitration is complately transparent to the client application, 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, the user has the option of administering a survivability hierarchy for each Switch Connection, via the AE Services OAM 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).

99

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

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, a DMCC JVM restart should manifest itself as a temporary outage of the connection between the client and the AE Server. On detecting such an 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.

100

Chapter 7: Media Encryption


Application Enablement Services offers the user the ability to encrypt the voice RTP streams between the CMAPI 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.

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 ORd 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:
IV

Encryption of the Voice Stream


IV+2

IV+1

Key = Ke

AES

Key = Ke

AES

Key = Ke

AES

Voice Bits 0-127

Voice Bits 128-255

Voice Bits 256-383

Transmitted Bits 0-127

Transmitted Bits128-255

Transmitted Bits 256-383

101

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 ORd 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:
32 bits of ROC

Structure of the Packet Index


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. 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
56 bits of key_id

48 bits of "i" DIV key_derivation_rate


102

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 Avayas 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 Avayas implementation: Key_derivation_rate = 0 Master_salt = 0 Figure 6: Values of "x" for Avayas Implementation

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

103

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 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 CMAPI 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 CMAPI 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 CMs change ip-codec form).

104

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 Avayas client-media-stack, you may call the Audio start method (as usual) passing the encryption information as an extra parameter:
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.

105

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 Avayas 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 headers 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, 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

106

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 // 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);

107

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

108

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); }

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;

109

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)0xc5, (byte)0x8f, (byte)0xba, IV-Rx: (byte)0x98, (byte)0x11, (byte)0x8f, (byte)0x00, (byte)0x12, (byte)0xf4, (byte)0x3c, (byte)0x2d, (byte)0x4e, (byte)0xef, (byte)0xe3, (byte)0x09, (byte)0xe1, (byte)0x7f, (byte)0xab, (byte)0x00 (byte)0x12, (byte)0xf4, (byte)0x3c, (byte)0x17, (byte)0xd4, (byte)0x0e, (byte)0xe3, (byte)0x09, (byte)0xe1, (byte)0x7f, (byte)0xa8, (byte)0xb7

// And the deciphered data should be: plainData = {(byte)0x05, (byte)0x43, (byte)0x2a, (byte)0x3d };

110

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 takes 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 SessionIDs, 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.

111

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

Note:

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

Advanced authentication and authorization policies


This release provides provisioning of authentication and authorization policies to specific application servers based on PKI (Public Key Infrastructure). The User Authentication and Authorization 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. Note that 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 OAM 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 machines 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 AES as being a trusted CA.

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.

112

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 AE Services Administration and Maintenance Guide, 02300357, for more information about SDB administration. For AE Services with Communication Manager 5.1 or later, if the SDB (security database) is enabled, and a user has "Unrestricted Access," then the client application does not have to know the extension password to register a device. (A CTI user can be administered for "Unrestricted Access" via the "Edit CTI User" Web page AE Services OAM). The registration without password will succeed only if the extension's class of restriction (COR) on Communication Manager has both fields "Can Be Service Observed:" and "Can Be A Service Observer:" set to "y". Note that 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 Enterprise Directory OAM page. 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.

113

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

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 using PKI. Certificate based authentication is generally accepted as being fare 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.

114

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 DMCCbased 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 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 AE Services OAM 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.

115

Chapter 9: Debugging
This section assumes that you have verified the operation of your AE Server using the verification application that comes with the AE Server RPM file. Please refer to the appropriate Avaya Aura Application Enablement Services Installation and Upgrade Guide for the offer you have purchased (Bundled, AES on System Platform 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 Controls .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" /> </logger>

116

The AE Server side logs will also be helpful when debugging your application. Please see Appendix E: 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 (Bundled, AES on System Platform or Software Only). Avoid running any other applications on the AE Services server machine. Check that the AE Services servers 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/enUS/Red_Hat_Enterprise_Linux/5/. Update the Linux kernel with the latest updates available. On Communication Manager:

117

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.

118

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 */ (function() {

119

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

120

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 servers 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 retrieves the developer provided function, deletes it from the hash, and invokes it with all of the arguments that were passed to its self.

121

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 librarys 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. When the StartApplicationSessionRequestEvent occurs, the function sasCallback is invoked.
sp = new com.avaya.dmcc.ServiceProvider();

122

sasCallback = function(error, protoVersion, sessionDuration, invokeId) { /* web application code */ } sp.startApplicationSession(/* normal argument list */, sasCallback);

Similarly, when the Phones StartMonitorResponseEvent occurs, the Jscript library invokes the web applications responseFunc, and when a DisplayUpdatedEvent occurs it invokes the web applications 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: 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.

123

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 20: Methods
startApplicationSession stopApplicationSession reconnect getNewDevice startAutoKeepAlive stopAutoKeepAlive shutdown getSessionId getAutoKeepAliveEnabled getDeviceId releaseDeviceId getThirdPartyDeviceId

Service Provider Events


serverConnectionDownEvent serverConnectionNotActiveEvent missedAtLeastOneKeepAliveEvent

Phone Methods and Events


Table 21: Device Events
displayUpdatedEvent lampUpdatedEvent ringerStatusEvent terminalUnregisteredEvent hookSwitchUpdatedEvent

Methods
startMonitor stopMonitor registerTerminal unregisterTerminal redirectMedia getHookswitchStatus

124

setHookswitchStatus pressButton getButtonInfo getDisplay getLampMode getMessageWaitingIndicator getRingerStatus

Media Methods and Events


Table 22: Phone Events
mediaStartedEvent mediaStoppedEvent mediaPlayingEvent mediaPlayingStoppedEvent mediaPlayingSuspendedEvent mediaRecordingEvent mediaRecordingStoppedEvent mediaRecordingSuspendedEvent mediaToneDetectedEvent mediaTonesRetrievedEvent

Methods
startMonitor stopMonitor mediaDeleteMessage

mediaSetToneRetrievalCriteria mediaStartDubbing mediaStopDubbing mediaStartRecording mediaStopRecording mediaSuspendRecording mediaResumeRecording mediaStartPlaying mediaSuspendPlaying mediaResumePlaying mediaStartToneCollection mediaStopToneCollection mediaFlushToneCollectionBuffer

Third Party Call Controller Methods and Events

125

Methods
startMonitor stopMonitor snapshotDevice singleStepConferenceCall alternateCall answerCall clearCall clearConnection conferenceCall consultationCall deflectCall generateDigits holdCall makeCall getDoNotDisturb getForwarding reconnectCall retrieveCall setDisplay setDoNotDisturb setForwarding singleStepTransfer snapshotCall transferCall

Table 23: Media Events


conferencedEvent deliveredEvent connectionClearedEvent doNotDisturbEvent establishedEvent failedEvent forwardingEvent heldEvent originatedEvent retrievedEvent transferredEvent

Call Information Methods and Events


Table 24: Methods Third Party Call Controller Events

126

startMonitor stopMonitor getCallInformation getLinkStatus

linkUpEvent linkDownEvent

J-Script library configuration


All JScript-related things are stored in the .NET SDK zip file in dmcc-dotnetsdk/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.

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.

127

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.

128

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 Dont 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 Dont Answer @ Call Vectoring o VDN of Origin Announcements Call Forwarding by Service Observer Call Forwarding by Service Observed Call Forwarding Features: o Call Forwarding All Calls

129

o Call Forwarding - Busy and Dont Answer o Call Forwarding - Dont 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

130

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 Avayas 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 IDs 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 25: Name Broken Flutter Flutter Lamp Mode Enumeration Description Usually indicates a feature activation has been denied. Usually indicates a feature activation has been denied or a button with no feature associated with it has been pushed. Lamp is off. Lamp is on. Lamp is winking (fast blink). Usually indicates a feature is pending activation. Lamp is winking in reverse. Usually indicates some kind of denial.

Off Steady Wink Inverted Wink

131

Flash Inverted Flash Undefined

Lamp is flashing. Usually indicates a call is on hold or a feature is pending activation. Lamp is flashing in reverse. Usually indicates some kind of denial. Some other lamp state. You should never get this.

Table 26: Name Red Green Undefined

Lamp Color Enumeration Description Red lamp Green lamp Some other color. You should never get this

Table 27: Name


ABR_PROG ABR_SPCHAR ABRDG_APPR ABRV_DIAL ABRV_RING AC_ALARM ACA_HALT ACCOUNT ADMIN AFTER_CALL ALRT_AGCHG ALT_FRL ANI_REQUST ASSIST ASVN_HALT ATD_QCALLS ATD_QTIME

Button Function Enumeration Description Abbreviated Dial Program AD Special Character Analog Bridged Appearance Abbreviated Dial Button to force Abbreviated / Delayed Ring Transition Administered Connection alarm button ACA referral call activate button CDR Account Code Button Enter Terminal Self-Admin Mode ACD - After Call Work Move agent while staffed alert Alternate FRL button Incoming ANI Request (Russian trunks only) ACD - supervisor assist button SVN Auth Code Halt Attended group - number of queued calls Attended group - oldest time

132

AUDIX_REC AUT_MSG_WT AUTO_CBACK AUTO_ICOM AUTO_IN AUTO_WKUP AUTODIAL AUX_WOR BRDG_APPR BTN_RING BTN_VIEW BUSY_IND CALL_APPR CALL_DISP CALL_FWD CALL_PARK CALL_PKUP CALL_SCRN CALL_TIMER CALLR_INFO CAS_BACKUP CDR1_ALRM CDR2_ALRM CFWD_BSYDA CFWD_ENH CHECK_IN CHECK_OUT CLK_OVERID CONFERENCE CONF_DSP CONSULT

Audix One-Step Recording Automatic message waiting indication Auo call back Auto-dial ICOM ACD - Auto-In Automatic Wakeup entry mode Autodial button

Bridged appearance of primary extension Button Ring Control entry mode Enhanced View Button Station busy indicator General call appearance, no aux data Call the displayed number Call forwarding button Park/Unpark button UM call pickup

Call Timer Caller Information CAS (branch) back-up mode lamp SMDR primary printer alarm SMDR secondary printer alarm Call Forward/Busy Don't answer Check-in entry mode Check-in entry mode Check-out entry mode Clocked override-time of day routing Conference Display conference parties Consult/return

133

COV_CBACK COV_MSG_RT CPN_BLK CPN_UNBLK CRSS_ALERT DATA_EXT DATE_TIME DELETE_MSG DIAL_ICOM DID_REMOVE DID_VIEW DIR_PKUP DIRECTORY DISP_CHRG DISP_NORM DN_DST DROP EC500 EXCLUSION EXT_DN_DST EXTND_CALL FE_MUTE FLASH GOTO_COVER GRP_DN_DST GRP_PAGE HEADSET HOLD HUNT_NS IN_CALL_ID INSPECT

Coverage LWC call back Coverage retrieve LWC message Per call CPN blocking activate Per call CPN unblocking activate Crisis Alert to Digital Station or Attendant. Data extension button TOD/DATE display mode Delete LWC message Autodial, aux is uid of destination DID remove entry mode DID view entry mode Directed call pickup Directory listing for name search Display Charge button NORMAL/LOCAL mode button User do not disturb button Drop the last party on a conference call EC500 Feature plus timer Manual exclusion Do not disturb - ext. OPTIM Extend call Conf Select Far End Mute Flash button for station on CAS MAIN call OR a call using Trunk Flash Goto coverage button Do not disturb - grp. Group Paging button Headset in use Hold Hunt night service button

Inspect display mode

134

INT_AUT_AN LAST_NUMB LIC_ERROR LIMIT_CALL LINK_ALARM LOGOUT_OVR LSVN_HALT LWC_CANCEL LWC_LOCK LWC_STORE MAJOR_ALRM MAN_MSG_WT MAN_OVERID MANUAL_IN MCT_ACT MCT_CONTR MF_DA_INTL MF_OP_INTL MJ_MN_ALRM MWI MM_BASIC MM_CALL MM_CFWD MM_DATACNF MM_MULTNBR MM_PCAUDIO MMI_CP_ALM MSG_RETR MWN_ACT MWN_DEACT NEXT

Internal Automatic Answer button Last number dialed License error

Link alarm button SVN login security violation

Cancel LWC Lockout LWC LWC store message Major alarm button Manual message waiting button Manual override-time of day routing ACD - Manual-In MCT: Malicious Call Trace Activate MCT: Malicious Call Trace Control International directory assistance - Mexico International CO operator - Mexico Major/Minor alarm button Message Waiting Indicator Multimedia Voice/Data activate/deactivate Multimedia Call Mode activate Multimedia Call Forward Multimedia Data Conference activate Multimedia Multi Address activate Multimedia PC-Audio activate MMI pack or port (video) alarm Principal retrieve LWC message Message notification on mode Message notification off mode Step through LWC message

135

NIGHT_SERV NO_HLD_CNF NH_CONSULT NOANS_ALRT NORMAL OFF_BD_ALM PER_COLINE PG1_ALARM PG2_ALARM PMS_ALARM POST_MSGS PR_AWU_ALM PR_PMS_ALM PR_SYS_ALM PRINT_MSGS PRIORITY Q_CALLS Q_TIME RELEASE RING_STAT RINGER_OFF RS_ALERT RSVN_HALT SCROLL SEND_CALLS SEND_TERM SERV_OBSRV SIGNAL SHARE_TALK SSVN_HALT STA_LOCK

Night Activate No hold conference

No Answer Alert button for Redirect On No Answer (RONA) timeout for split. Normal display mode Off-board DS1 board alarm button Personal CO line, aux is grp id SA8312 PAGE1 alarm SA8312 PAGE2 alarm PMS alarm button Posted messages Wakeup journal printer alarm PMS journal printer alarm BCMS printer link alarm button

Priority calling button Hunt group - number of queued calls Hunt group - oldest queued time ACD - Release Ringer status Ringer cut button for stations System reset alert SVN remote access security violation SCROLL mode button Send all calls button Terminating extension group SAC button Service observing button Manual signalling

SVN station security call activate button Station Lock

136

START_BILL STORED_NUM STROKE_CNT TEAM TERM_X_GR TIMER TOGLE_SWAP TRANSFER TRK_AC_ALM TRK_ID TRUNK_NAME TRUNK_NS USR_ADDBSY USR_REMBSY UUI_INFO VC_CP_ALM VERIFY VIP_CHKIN VIP_RETRY VIP_WAKEUP VOA_REPEAT VOICE_MAIL VU_DISPLAY WARN_ALRM WHISP_ACT WHISP_ANBK WHISP_OFF WORK_CODE

Start Billing STORED-NUMBER display mode Single-Digit Stroke Counts

ELAPSED-TIME display mode Conf/Transfer Toggle Swap Transfer Facility acc test trunk access alert Trunk ID button Trunk name when DCS (also DCS CAS MN) Trunk night service button Add FBI to station Remove FBI from station UUI-info button VC pack or port (audio) alarm Busy verification button VIP check-in Reschedule VIP wakeup as regular wakeup Place VIP wakeup call VDN of Origin Annc. Repeat Button Engen fixed voice mail Vu-Stats Station Displays Warn alarm Activate Whisper Page Answerback for Whisper Page Whisper Page Off Multi-Digit Stroke Count

Table 28: Name

Button Id Enumeration Description

137

ALL DIGIT_1 DIGIT_2 DIGIT_3 DIGIT_4 DIGIT_5 DIGIT_6 DIGIT_7 DIGIT_8 DIGIT_9 DIGIT_0 DDIGIT_STAR DIGIT_POUND CONFERENCE Drop TRANSFER HOLD BUTTON_1

Use when you want to get information about ALL the buttons The digit 1 on the dialpad. The digit 2 on the dialpad. The digit 3 on the dialpad. The digit 4 on the dialpad. The digit 5 on the dialpad. The digit 6 on the dialpad. The digit 7 on the dialpad. The digit 8 on the dialpad. The digit 9 on the dialpad. The digit 0 on the dialpad. The digit * on the dialpad. The digit # on the dialpad. The conference button The drop button The transfer button hold button 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. 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) 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)

FEATURE_MODULE_START

DISPLAY_MODULE_START

138

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 29: Name Idle Registering Registered Unregistering Unknown

Registration States Enumeration Description

Table 30: Name Main Independent Dependent

Dependency Modes Enumeration Description

Table 31: Ring Pattern Ringer Off Manual Signal Attendant Incoming Call Attendant Held Call Attendant Call Waiting Attendant Emergency Intercom Standard Ring DID/Attendant Ring Priority Ring

Ringer Pattern Constants Value 0 1 4 5 6 7 9 11 12 13

139

Ring Ping

14

Table 32: Reason code constants for the registerTerminalRequest Unknown Non-specific Internal failure Network timeout

Registration Constants Value -1 -2 -3 1000

Media Enumerations
Name
None

Table 33: Media Modes Enumeration Description 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). 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. 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. 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 mode should never be used.

Telecommuter

Server_Mode

Client_Mode

UNDEFINED

140

Service Provider Enumeration


Table 34: Name
CONVERTED NO_MATCH INVALID_INPUT

Convert E164 to Dial String Enumeration Description

Table 35: Name


CONVERTED NO_MATCH INVALID_INPUT

Convert Dial String to E164 Enumeration Description

Third Party Call Control Enumerations


Table 36: Single Step Conference Call Enumeration Name Service Provider Description Class Requests None No participation type for a Single Step Conference Silent Active Silent participation type for a single step conference Active participation type for a single step conference

Table 37: Name ForwardImmediate None Specified

Call Forwarding Enumeration Description Immediate Forwarding No Forwarding Type Specified

141

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 Basic Latin (common in Germany and most of 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
Europe) Latin-1 Supplement (common in Germany and most of Europe) Latin Extended-A Latin Extended-B Greek and Coptic Cyrillic Armenian Hebrew Arabic Devanagari Bengali Gurmukhi Gujarati Oriya Tamil Telugu Kannada Malayalam Sinhala Thai Lao Myanmar Georgian Tagalog Khmer Halfwidth and Fullwidth Forms (Kana) CJKV Radicals Supplement (Jpan) CJKV Radicals Supplement (ChiS) CJKV Radicals Supplement (ChiT) 29:CJKV Radicals Supplement (Korn) CJKV Radicals Supplement (Viet) Hangul Jamo

142

Appendix E: Server Logging


If you want to increase the detail of the 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), and then restart the AE Services server. ############################################################ # 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. handlers=com.avaya.common.logger.ThreadedHandler com.avaya.common.logger.ErrorFileHandler com.avaya.common.logger.ApiFileHandler # 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

143

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

144

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

145

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 for the client application. 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 Programmers Guide found online on the Avaya Support website for the definition of the numeric error code.

CSTA Error Definitions Error genericUnspecified genericOperation requestIncompatibleWithObject valueOutOfRange objectNotKnown invalidCallingDevice invalidCalledDevice invalidForwardingDestination privilegeViolationOnSpecifiedDevice privilegeViolationOnCalledDevice privilegeViolationOnCallingDevice invalidCstaCallIdentifier invalidCstaDeviceIdentifier invalidCstaConnectionIdentifier invalidDestination invalidFeature

Numeric Code 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

146

invalidAllocationState invalidCrossRefId invalidObjectType securityViolation genericStateIncompatibility invalidObjectState invalidConnectionIdForActiveCall noActiveCall noHeldCall noCallToClear noConnectionToClear noCallToAnswer noCallToComplete genericSystemResourceAvailability serviceBusy resourceBusy resourceOutOfService networkBusy networkOutOfService overallMonitorLimitExceeded conferenceMemberLimitExceeded genericSubscribedResourceAvailability objectMonitorLimitExceeded externalTrunkLimitExceeded outstandingRequestLimitExceeded genericPerformanceManagement performanceLimitExceeded unspecifiedSecurityError sequenceNumberViolated timeStampViolated pacViolated

16 17 18 19 21 22 23 24 25 26 27 28 29 31 32 33 34 35 36 37 38 41 42 43 44 51 52 60 61 62 63

147

sealViolated genericUnspecifiedRejection genericOperationRejection duplicateInvocationRejection unrecognizedOperationRejection mistypedArgumentRejection resourceLimitationRejection acsHandleTerminationRejection serviceTerminationRejection requestTimeoutRejection requestsOnDeviceExceededRejection unrecognizedApduRejection mistypedApduRejection badlyStructuredApduRejection initiatorReleasingRejection unrecognizedLinkedidRejection linkedResponseUnexpectedRejection unexpectedChildOperationRejection mistypedResultRejection unrecognizedErrorRejection unexpectedErrorRejection mistypedParameterRejection nonStandard

64 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 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 Programmers Guide for the definition of the numeric error code

148

ACS Error Definitions Error ACSERR_APIVERDENIED

Numeric Code -1

Description This return indicates that the API Version requested is invalid and not supported by the existing API Client Library. One or more of the parameters is invalid. This return indicates that an ACS Stream is already established with the requested Server. This error return value indicates that no API Client Library Driver was found or installed on the system. This indicates that the requested Server is not present in the network. This return value indicates that there are insufficient resourcesto open a ACS Stream. The user buffer size was smaller than the size of the next available event. There were no messages available to return to the application. The ACS Stream has encountered an unspecified error. The ACS Handle is invalid. The ACS Stream has failed due to network problems. No further operations are possible on this stream. There were not enough buffers available to place an outgoing message on the send queue. No message has been sent. The send queue is full.

ACSERR_BADPARAMETER ACSERR_DUPSTREAM

-2 -3

ACSERR_NODRIVER

-4

ACSERR_NOSERVER ACSERR_NORESOURCE

-5 -6

ACSERR_UBUFSMALL

-7

ACSERR_NOMESSAGE ACSERR_UNKNOWN ACSERR_BADHDL ACSERR_STREAM_FAILED

-8 -9 -10 -11

ACSERR_NOBUFFERS

-12

ACSERR_QUEUE_FULL

-13

149

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.

150

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.

151

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 reregister 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 AES 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 OutstandingRequestLimitExceeded Description

The specified routing device already has a registered routing server.

152

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 callrelated 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 links extension through which the switch will send the RouteRequest to AES 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.

153

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 InvalidDeviceId Description An invalid routeRegisterReqID has been specified in the RouteEndInv() request InvalidCrossRefId An invalid routeCrossRefID has been specified in the Route Select request.

154

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.

155

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 o o o o o A RouteRequest is sent to the application. Caller drops the call. Application sends a RouteEnd request. A RouteEnd Event (errorValue = NoActiveCall) is sent to the application. TSAPI Service receives the cstaRouteEndInv() request, but call has been dropped. 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 Generic Description Normal termination (for example, application does not want to route the call or does not know how to route the call). InvalidDeviceId ResourceBusy ResourceOutOfService An invalid routeRegisterReqID has been specified in the RouteEnd request Routing server is too busy to handle the route request. 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. 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:

156

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

ErrorValue Generic

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

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 originators Class Of Restriction (COR) or the destination agents 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. 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
InvalidCallingDevice

157

RouteEnd Event ErrorValue Description

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. 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. 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 Servers and the switch is set to send multiple RouteRequests for the same call. 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 The destination is busy and does not have coverage. The caller will hear either a reorder or busy tone. 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. 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.

NoActiveCall

NoCallToAnswer

PrivilegeViolationOnSpecifiedDevice

ResourceBusy

PerformanceLimitExceeded

ValueOutOfRange

158

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

159

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 InvalidDeviceId Description

An invalid routeRegisterReqID has been specified in the RouteEndInv() request

160

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 have been 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

161

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

Usage of IPv6 addresses in AE Services


IP addresses are prevalent throughout AE Services. For example, they can be found in: AE Services OAM 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 Server address, including: o o o o DMCC unsecured port (4721) DMCC secured port (4722) DMCC TR87 port (4723) AE Services OAM web pages (443)

Communication Manager addresses of various types, including: o o o Processor Ethernet addreses Media Gateway addresses Media Processor addresses

Client application addresses, including: o The client server

162

Endpoint RTP address (for client media mode)

Note that Communication Manager 6.0 or later is required for IPv6 connections between AE Services and CM. 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 servers protocol stack converts the clients address into an IPv4-mapped IPv6 address. Simililarly, an IPv6 client on a dual-stack host can communicate with an IPv4 server. The clients 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 CLAN IP addresses for one switch connection may be in IPv4 format, while the CLAN IP addresses for another switch connection may be in IPv6 format. It is the administrators 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 IPv4 and/or IPv6 traffic as needed.

163

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 connector 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 Direct memory access

164

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 computers processor so that is can perform a Java programs 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 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

165

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

166

Index
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 client application, 164 <$nopage>coder/decoder, see codecs, 62, 84 RTP;RTP:media stream, 61, 84 <$nopage>Resource Interchange File Format, see RIFF, 86 <Italic>Programmers Reference, 11 positive acknowledgement, 38 client API library:using reference documentation, 34, 40 , 116 application:developing, 42 performance, 117 Avaya Support Centre:website, 10, 11 bearer channels:unencrypted, 111, 112 BHCC, 164 buttons:function, 132 buttons:ID constants, 137 buttons:knowing, 85 buttons:on a device, 85 buttons:get information, 22 call appearances:detecting incoming call, 85 call appearances:green lamp turns off, 85 incoming call:detecting;detecting incoming call, 85 calls, 37 calls:ended by far end, 85 calls:end-of-call cleanup, 93 cleanup, 93 client media mode, 63, 84 client/server model, 14 CM Link, 164 CMAPI softphone, 164 codecs:choosing, 66, 84 encoding algorithms, 87 codecs:recordings, 87 Communication Manager:features, 129 Communication Manager:loss of communication with, 58, 84 Communication Manager:network configuration, 117 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 connector, 164 CSTA:atomic model, 38 CSTA:Avaya extensions to, 15 CSTA:becoming familiar with, 9 CSTA:concepts, 34, 35 CSTA:multi-step model, 38 deployment:security, 111 development environment, 34 device:cleanup, 93 device:unregistering, 93 device:identifier, 16 logical elements, 37 device:registration, 16 display:for incoming call, 85 display:get contents, 22 display:updated event, 23 DMA, 164 downloading:Communication Manager API SDK, 34 dropped call, 85 DTMF digits:start collecting, 25 DTMF digits:stop collecting, 25 DTMF digits:Tone Detected event, 25 ECMA, 165 , 112 events, 38 Display Updated event, 20 exiting application, 93 extension:specifying for a device, 21 extensions to CSTA, 15 freeing up resources, 93 G.711, 62, 84 G.711:specifying during registration, 66, 84 G.729, 62, 84 G.729:converter, 86 G.729:non-standard RIFF values, 86 G.729:specifying during registration, 66, 84 hold time, 165 hookswitch:get status, 22

167

80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 139 140

hookswitch:set status, 22 hookswitch:status changed event, 23 ideas, 129 J2SE, 165 JDK, 165 JVM, 165 lamps:color, 132 lamps:mode, 124, 125, 131 lamps:status change, 23 Linux kernel:updates, 117 Linux operating system:tuning, 117 far-end RTP media parameters;RTP:parameters;media:when farend RTP parameters change, 88 Media Start event:using, 88 media:controlling, 61, 84 media:encoding, 66, 84 media:modes, 62, 84 server media mode, 62 , 84 message waiting indicator:get status, 22 network regions, 66, 84 network:failure, 58, 84 network:performance, 117 no media, 63, 84 password:specifying for station, 58, 84 device:physical element, 36 physical elements, 21 media stream:recording messages from;media stream:playing messages to;recording, 24, 86

110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138

race conditions, 117 recovery, 89 device:registering, 57, 84 requests:errors on, 38 responses:asynchronous vs. synchronous, 37 RIFF, 86 ringer:detecting incoming call, 85 ringer:get status, 22 ringer:pattern, 139 ringer:status changed event, 23 RPM, 165 RTP:parameter changes, 62, 63, 84 RTP:parameters, 62, 84 SAT, 165 SDK, 165 security:considerations, 111 registerDevice method, 58, 84 signaling channel:unencrypted, 111, 112 station administration:button assignments, 85 test environment, 35 TTI, 165 verification application, 116 VoIP, 166 VOIP:readiness guide, 118 Wave files:file structure, 86 websites:Avaya Developer Connection, 9 Avaya University, 9 ECMA, 11 , 112

168

Você também pode gostar