Professional Documents
Culture Documents
Aes61 DMCC Dotnet Prog
Aes61 DMCC Dotnet Prog
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: [email protected]. Trademarks Avaya Aura is a registered trademark of Avaya. All non-Avaya trademarks are the property of their respective owners. PuTTY is copyright 1997-2009 Simon Tatham. Downloading documents For the most current versions of documentation, see the Avaya Support Web site: http://www.avaya.com/support Contact Avaya Support Avaya provides a telephone number for you to use to report problems or to ask questions about your product. The support telephone number is 1-800-242-2121 in the United States. For additional support telephone numbers, see the Avaya Web site: http://www.avaya.com/ support
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
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.
Code and Linux commands .NET class, method and field names
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.
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)
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
12
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
13
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
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.
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
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.
Get Actual Protocol Version Get Call Information Link Get Last Incoming Xml Message Get Session ID Get Third Party Call Controller Get Xml Processor
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.
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
21
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 Message Waiting Indicator Get Registration State Get Ringer Status
See Appendix D for more information. Sets the hookswitch status of a specified device to either onhook or offhook
22
Start Monitor
Informs the API of what type of phone events the application wishes to be notified of. Phone events are events like lamp updates, display updates, ringer updates, etc 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.
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
Media Stopped
25
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
Consultation Call
27
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 Forwarding
28
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
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
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).
Set Display
Set Forwarding
30
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).
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
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.
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
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
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
35
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
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
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.
Dashboard in a Browser
JScript\dashboard
41
42
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
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).
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).
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
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.
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
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.
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:
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
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.
55
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
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
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.
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 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 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
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
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 server
provided by the application provided by the application provided by the application provided by the application provided by the applicationa
Originate and terminate RTP streams on any machine that the application has control of Media encryption provided by the server
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.
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.
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.
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
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
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
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
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
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.
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.
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.
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
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>
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
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).
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.
100
Figure 2:
IV
IV+1
Key = Ke
AES
Key = Ke
AES
Key = Ke
AES
Transmitted Bits128-255
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
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
8 bits of label
Let x = key_id
XOR
master_salt
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)
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};
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);
105
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.
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 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.
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);
108
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
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
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.
112
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.
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
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
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.
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
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.
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.
Methods
startMonitor stopMonitor registerTerminal unregisterTerminal redirectMedia getHookswitchStatus
124
Methods
startMonitor stopMonitor mediaDeleteMessage
mediaSetToneRetrievalCriteria mediaStartDubbing mediaStopDubbing mediaStartRecording mediaStopRecording mediaSuspendRecording mediaResumeRecording mediaStartPlaying mediaSuspendPlaying mediaResumePlaying mediaStartToneCollection mediaStopToneCollection mediaFlushToneCollectionBuffer
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
126
linkUpEvent linkDownEvent
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
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
131
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.
Lamp Color Enumeration Description Red lamp Green lamp Some other color. You should never get this
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
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
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
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
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
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
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 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
139
Ring Ping
14
Table 32: Reason code constants for the registerTerminalRequest Unknown Non-specific Internal failure Network timeout
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
141
142
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
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
148
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
-8 -9 -10 -11
ACSERR_NOBUFFERS
-12
ACSERR_QUEUE_FULL
-13
149
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.
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
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
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
160
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
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
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
162
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.
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