Avaya™ Interaction Center Release 6.1 VTel Automation Server Programmer Guide

585-248-201 Issue 2.1 August 2003

© 2003 Avaya Inc. All Rights Reserved. Notice While reasonable efforts were made to ensure that the information in this document was complete and accurate at the time of printing, Avaya Inc. can assume no liability for any errors. Changes and corrections to the information in this document may be incorporated in future releases. Preventing toll fraud "Toll fraud" is the unauthorized use of your telecommunications system by an unauthorized party (for example, anyone who is not a corporate employee, agent, subcontractor, or person working on your company's behalf). Be aware that there may 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.

Warranty Avaya Inc. provides a limited warranty on this product. Refer to your sales agreement to establish the terms of the limited warranty. In addition, Avaya’s standard warranty language, as well as information regarding support for this product, while under warranty, is available through the following Web site: http://www.avaya.com/support Link disclaimer Avaya Inc. is not responsible for the contents or reliability of any linked Web sites and does not necessarily endorse the products, services, or information described or offered within them. We cannot guarantee that these links will work all of the time and we have no control over the availability of the linked pages. Trademarks

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 Web site: http://www.avaya.com Select Support, then select Escalation Lists. This Web site includes telephone numbers for escalation within the United States. For escalation telephone numbers outside the United States, select Global Escalation List.

All trademarks identified by the ® or ™ are registered trademarks or trademarks, respectively, of Avaya Inc. All other trademarks are the property of their respective owners. Avaya, CONVERSANT, CustomerQ, DEFINITY, DefinityOne, MultiVantage, Nabnasset, Quintus, and WebQ are registered trademarks or trademarks of Avaya Inc. in the United States or other countries or both.

Providing telecommunications security Telecommunications security (of voice, data, and video communications) is the prevention of any type of intrusion to (that is, either unauthorized or malicious access to or use of) your company's telecommunications equipment by some party. Your company's "telecommunications equipment" includes both this Avaya product and any other voice/data/video equipment that could be accessed via this Avaya product (that is, "networked equipment"). An "outside party" is anyone who is not a corporate employee, agent, subcontractor, or person working on your company's behalf. Whereas, a "malicious party" is anyone (including someone who may be otherwise authorized) who accesses your telecommunications equipment with either malicious or mischievous intent. Such intrusions may be either to/through synchronous (time-multiplexed and/or circuit-based) or asynchronous (character-, message-, or packet-based) equipment or interfaces for reasons of: • Use (of capabilities special to the accessed equipment) • Theft (such as, of intellectual property, financial assets, or toll-facility access) • Eavesdropping (privacy invasions to humans) • Mischief (troubling, but apparently innocuous, tampering) • Harm (such as harmful tampering, data loss or alteration, regardless of motive or intent) Be aware that there may be a risk of unauthorized intrusions associated with your system and/or its networked equipment. Also realize that, if such an intrusion should occur, it could result in a variety of losses to your company (including, but not limited to, human and data privacy, intellectual property, material assets, financial resources, labor costs, and legal costs).

Fax:

+1-207-626-7269 1-800-457-1764 (Toll-free, U.S. and Canada only)

Write:

Globalware Solutions 200 Ward Hill Avenue Haverhill, MA 01835 USA Attention: Avaya Account Manager http://www.avayadocs.com [email protected] Document No. 585-248-201, Issue 2.1 August 2003

Your responsibility for your company's telecommunications security The final responsibility for securing both this system and its networked equipment rests with you, an Avaya customer's system administrator, your telecommunications peers, and your managers. Base the fulfillment of your responsibility on acquired knowledge and resources from a variety of sources, including, but not limited to: • Installation documents • System administration documents • Security documents • Hardware-/software-based security tools • Shared information between you and your peers • Telecommunications security experts To prevent intrusions to your telecommunications equipment, you and your peers should carefully program and configure: • Your Avaya-provided telecommunications systems and their interfaces • Your Avaya-provided software applications, as well as their underlying hardware/software platforms and interfaces • Any other equipment networked to your Avaya products.

Ordering information: Avaya Publications Center Voice: +1-207-866-6701 1-800-457-1764 (Toll-free, U.S. and Canada only)

Web: E-mail: Order:

Avaya support Avaya provides a telephone number for you to use to report problems or to ask questions about your contact center. 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 Select Support, then select Escalation Lists. This Web site includes telephone numbers for escalation within the United States. For escalation telephone numbers outside the United States, select Global Escalation List. Avaya Training Avaya provides training for Avaya Operational Analyst. For more information, contact Avaya University at: Web site: http://www.avaya-learning.com/logon_form.asp E-mail address: [email protected] US telephone: 1-800-288-5327 Outside US telephone: +1-303-406-6089 Comments To comment on this document, send e-mail to [email protected]. Acknowledgment This document was written by the CRM Information Development group.

Contents

Avaya™ Interaction Center Release 6.1 VTel Automation Server Programmer’s Guide

Contents Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9

Chapter 1: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13

Defining OLE automation . . . . . . . . . . . . . . . . Getting started . . . . . . . . . . . . . . . . . . . . . Error messages while launching VTel using OLE . . . . Visual Basic error: Cannot create ActiveX control. . . VTel Login error: VESP:00000000 . . . . . . . . . . Test programs . . . . . . . . . . . . . . . . . . . . Using VTel as an automation server from Visual Basic Using VTel as an automation server in Visual C++ . . Breaking the OLE connection with VTel. . . . . . . . .

. . . . . . . . . Visual Basic and Visual C++ programming conventions. . .

. . . . . . . . . .

14 15 16 16 16 16 16 17 18 19

Chapter 2: The Automation API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

21

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preventing VB polling conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . .

22 24 26 27 30 30 31

Chapter 3: Programming example: implementing a softphone . . . . . . . . . . . .

33

Event processing . . . . . . . . . Error handling . . . . . . . . . . Sequences of strings and couples . Sequence of strings . . . . . . . Sequence of couples . . . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

Logging into the server . . . . . . . . . . . . Logging out of the server . . . . . . . . . . . Using the Make Call button . . . . . . . . . . Event processing . . . . . . . . . . . . . . . Programming the Hang Up and Answer buttons Programming the Transfer button . . . . . . . Programming the Conference button . . . . .

. . . . .

. . . . . . .

. . . . .

. . . . . . .

. . . . .

. . . . . . .

. . . . .

. . . . . . .

. . . . .

. . . . . . .

. . . . .

. . . . . . .

. . . . . . . . . .

. . . . .

. . . . . . .

. . . . . . . . . .

. . . . .

. . . . . . .

. . . . . . . . . .

. . . . .

. . . . . . .

. . . . . . . . . .

. . . . .

. . . . . . .

. . . . . . . . . .

. . . . .

. . . . . . .

. . . . . . . . . .

. . . . .

. . . . . . .

. . . . . . . . . .

. . . . .

. . . . . . .

. . . . . . . . . .

. . . . .

. . . . . . .

. . . . . . . . . .

. . . . .

. . . . . . .

. . . . . . . . . .

. . . . .

. . . . . . .

. . . . . . . . . .

. . . . .

. . . . . . .

. . . . . . . . . .

. . . . .

. . . . . . .

. . . . . . . . . .

. . . . .

. . . . . . .

. . . . . . . . . .

. . . . .

. . . . . . .

. . . . . . .

35 36 37 38 41 42 43

Chapter 4: Cautions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

45

Enabling automation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Registering VTel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

45 46

Issue 2.1 August 2003

3

Contents Using convenience methods . Using multiple controllers . . . Using multiple servers . . . . Programming Exit events . . . Editing system registry entries

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

46 46 47 47 48

Chapter 5: API Methods: Relationships . . . . . . . . . . . . . . . . . . . . . . . . .

49

General methods . . . . . . . . . . . . . . . Call management methods . . . . . . . . . . Asynchronous methods for call management . Synchronous methods for call management .

. . . . .

. . . . .

. . . . EDU management methods. . . . . . . . . . . Asynchronous methods for EDU management . Convenience methods for EDU management . . Session management methods . . . . . . . . . Asynchronous methods for session management . Synchronous methods for session management . Response processing methods . . . . . . . . . . General methods . . . . . . . . . . . . . . . . Asynchronous-only methods . . . . . . . . . . . Event processing methods . . . . . . . . . . . . Sequence management methods . . . . . . . . . Sequence of couples . . . . . . . . . . . . . . Sequence of strings . . . . . . . . . . . . . . . Response and event codes . . . . . . . . . . . . Response codes . . . . . . . . . . . . . . . . Event codes . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

4 VTel Automation Server Programmer Guide

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

67

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

Chapter 6: API Methods: Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

50 50 51 52 53 53 54 55 55 56 57 57 58 59 60 60 61 61 61 65

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

Summary of methods . . . . Methods . . . . . . . . . . Answer . . . . . . . . . . AnswerSynch . . . . . . . Busy . . . . . . . . . . . BusyOverride . . . . . . . BusyOverrideSynch . . . . BusyPhoneset . . . . . . BusyPhonesetSynch . . . BusySynch . . . . . . . . ChangePassword . . . . . ChangePasswordSynch . . ChangeBusyReasonCode . ConferenceCancel . . . . ConferenceCancelSynch . ConferenceComplete . . . ConferenceCompleteSynch

. . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

67 75 75 76 77 78 79 81 82 83 84 85 86 87 88 89 90

Contents ConferenceInit . . . . . . . . ConferenceInitSynch . . . . . Drop . . . . . . . . . . . . . DropSynch . . . . . . . . . . Exit . . . . . . . . . . . . . . ExitSynch. . . . . . . . . . . FreeAllEvents . . . . . . . . . FreeAllResponses . . . . . . FreeEvent . . . . . . . . . . FreeResponse . . . . . . . . GetEventArg . . . . . . . . . GetEventCode . . . . . . . . GetEventCount . . . . . . . . GetEventName . . . . . . . . GetEventString . . . . . . . . GetGetInfoResponse . . . . . GetGetPhoneInfoResponse . . GetInfo . . . . . . . . . . . . GetInfoSynch . . . . . . . . . GetLastResponseDetail . . . . GetMakeCallResponse . . . . GetPhoneInfo . . . . . . . . . GetPhoneInfoSynch . . . . . . GetResponseArg . . . . . . . GetResponseCode . . . . . . GetResponseCount . . . . . . GetResponseDetail . . . . . . GetResponseName . . . . . . GetResponseStatus . . . . . . GetResponseString . . . . . . GetVDUCreateResponse . . . GetVDUFindVDUResponse . . GetVDUGetActiveResponse . . GetVDUGetCurrentResponse . GetVDUGetDataResponse . . GetVDUGetOneValueResponse GetVDUGetValuesResponse . Hangup . . . . . . . . . . . . HangupSynch. . . . . . . . . Hold . . . . . . . . . . . . . HoldReconnect . . . . . . . . HoldReconnectSynch . . . . . HoldSynch . . . . . . . . . . LogEntry . . . . . . . . . . . LogEntrySynch . . . . . . . . Login . . . . . . . . . . . . . LoginACD . . . . . . . . . . LoginACDSynch . . . . . . . LoginSynch . . . . . . . . . . LoginTelephony . . . . . . . . LoginTelephonySynch . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

92 93 94 96 97 98 99 100 101 104 106 109 113 114 118 119 122 124 125 126 128 130 131 132 134 137 138 142 144 145 146 149 151 154 156 158 161 163 164 165 166 168 169 170 171 172 174 176 178 180 182

Issue 2.1 August 2003

5

Contents LoginVESP . . . . . . . . LoginVESPSynch . . . . . Logout . . . . . . . . . . LogoutSynch . . . . . . . LogoutTelephony . . . . . LogoutTelephonySynch . . LogoutVESP . . . . . . . LogoutVESPSynch . . . . MakeCall . . . . . . . . . MakeCallSynch . . . . . . MakeRequest . . . . . . . MakeRequestSynch . . . . PeekEvent . . . . . . . . PeekResponse . . . . . . Ping . . . . . . . . . . . PingSynch . . . . . . . . Ready . . . . . . . . . . ReadyOverride . . . . . . ReadyOverrideSynch . . . ReadyPhoneset . . . . . . ReadyPhonesetSynch. . . ReadySynch . . . . . . . ResetPhones . . . . . . . ResetPhonesSynch . . . . RestartServer . . . . . . . RestartServerSynch . . . . Rona . . . . . . . . . . . SendDefinityAux . . . . . SendDefinityAuxSynch . . SendDefinityLogout . . . . SendDefinityLogoutSynch . SendDTMFtones . . . . . SendDTMFtonesSynch . . SeqCoupleCount . . . . . SeqCoupleCreate . . . . . SeqCoupleGet . . . . . . SeqCoupleGetAttrib . . . . SeqCoupleGetVal . . . . . SeqCoupleLimit . . . . . . SeqCoupleSet . . . . . . SeqStringAdd . . . . . . . SeqStringCount . . . . . . SeqStringCreate . . . . . SeqStringGet . . . . . . . SeqStringLimit . . . . . . SetAutoIn. . . . . . . . . SetAutoInSynch . . . . . SupressEvents . . . . . . SupressResponses . . . . SwapHeld . . . . . . . . SwapHeldSynch . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6 VTel Automation Server Programmer Guide

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

184 185 186 187 188 190 191 192 194 195 197 201 203 206 208 209 210 211 212 213 214 215 216 217 218 220 221 222 223 224 226 227 228 230 231 232 233 235 237 238 239 241 242 243 245 246 247 248 249 250 251

Contents Terminate . . . . . . . . TerminateSynch . . . . . Transfer . . . . . . . . TransferCancel . . . . . TransferCancelSynch . . TransferComplete . . . . TransferCompleteSynch . TransferInit . . . . . . . TransferInitSynch . . . . TransferSynch . . . . . VDUCreate . . . . . . . VDUCreateSynch . . . . VDUFindVDU . . . . . . VDUFindVDUSynch . . . VDUGetActive . . . . . VDUGetActiveSynch . . VDUGetCurrent . . . . . VDUGetCurrentSynch . . VDUGetData . . . . . . VDUGetDataSynch . . . VDUGetOneValue . . . . VDUGetOneValueSynch. VDUGetValues . . . . . VDUGetValuesSynch . . VDUSetCurrent . . . . . VDUSetCurrentSynch . . VDUSetValues . . . . . VDUSetValuesSynch . . WaitForResponse . . . . WrapUp . . . . . . . . WrapUpOverride . . . . WrapUpOverrideSynch . WrapUpSynch . . . . .

Index

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

252 253 254 255 256 257 258 260 261 262 263 265 266 267 269 270 271 272 273 274 275 277 278 279 280 282 283 284 286 288 289 290 291

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

293

Issue 2.1 August 2003

7

Contents

8 VTel Automation Server Programmer Guide

Before You Begin Typographical Conventions This guide uses the following font conventions: Font Type

Meaning

command

This font signifies commands, information that you enter into the computer, or information contained in a file on your computer.

commandvariable

This font indicates variables in a command string.

italics

This font is used to add emphasis to important words and for references to other chapter names and manual titles.

link

Blue underlined text in online documents indicates a hypertext jump to related information. To view the related material, click the blue underlined text.

Notes, Tips, and Cautions Note:

Note: A note calls attention to important information.

! Important:

Important: An important note calls attention to a situation that has the potential to cause serious inconvenience or other similar repercussions.

Tip: Tip:

A tip offers additional how-to advice.

! CAUTION: CAUTION:

A caution points out actions that may lead to data loss or other serious problems.

Issue 2.1 August 2003

9

Before You Begin

Contacting Technical Support If you are having trouble using Avaya software, you should: 1. Retry the action. Carefully follow the instructions in written or online documentation. 2. Check the documentation that came with your hardware for maintenance or hardware-related issues. 3. Note the sequence of events that led to the problem and the exact messages displayed. Have the Avaya documentation available. 4. If you continue to have a problem, contact Avaya Technical Support by: ●

Logging in to the Avaya Technical Support Web site http://www.avaya.com/support/qq

●

Calling or faxing one of the following numbers from 8:30 a.m. to 8:30 p.m. (Eastern Standard Time), Monday through Friday (excluding holidays): - Toll free in the U.S. and Canada: 1-888-TECH-SPT (1-888-832-4778) - Direct line for international and domestic calls: 1-512-425-2201 - Direct line for faxes: 1-512-997-4330

●

Note:

Sending email with your question or problem to [email protected]. You may be asked to email one or more files to Technical Support for analysis of your application and its environment.

Note: If you have difficulty reaching Avaya Technical Support through the above URL or email address, please go to http://www.avaya.com for further information.

Product Documentation Most Avaya product documentation is available in both printed and online form. However, some reference material is available only online, and certain information is available only in printed form. A PDF document with detailed information about all of the documentation for the Avaya Interaction Center is included in the Doc directory on the product CD-ROM. This PDF document is also included on the separate documentation CD-ROM.

Readme File The Readme file is a PDF file included on the Avaya Interaction Center software CD-ROM. This file contains important information that was collected too late for inclusion in the printed documentation. The Readme file can include installation instructions, system

10 VTel Automation Server Programmer Guide

requirements, information on new product features and enhancements, suggested work-arounds to known problems, and other information critical to successfully installing and using your Avaya software. Avaya may also deliver an Addendum to the Readme, which will be posted on the Avaya Technical Support Website. The Readme Addendum will contain similar information uncovered after the manufacture of the product CD-ROM. Review the Readme file and the Readme Addendum before you install your new Avaya software.

Electronic Documentation The electronic documentation (in PDF or HTML format) for each Avaya Interaction Center product is installed automatically with the program. Electronic documentation for the entire Avaya product suite is included on the product CD-ROM and the documentation CD-ROM. You can also view the documentation set online at http://www.avayadocs.com.

Printed Documentation You can purchase printed copies of these manuals separately. For details, see Ordering information: Avaya Publications Center on the back of this manual’s title page.

License to Print the Electronic Documentation Online copies of documentation are included on the CD-ROM that accompanies every software release. An Avaya customer who has licensed software (a “Licensee”) is entitled to make this online documentation available on an internal network or “intranet” solely for the Licensee's use for internal business purposes. Licensees are granted the right to print the documentation corresponding to the software they have purchased solely for such purposes.

Right-To-Print License Terms Documents must be printed “as-is” from the provided online versions. Making changes to documents is not permitted. Documents may be printed only by any employee or contractor of Licensee that has been given access to the online documentation versions solely for Licensee's internal business purposes and subject to all applicable license agreements with Avaya. Both online and printed versions of the documents may not be distributed outside of Licensee enterprise or used as part of commercial time-sharing, rental, outsourcing, or service bureau use, or to train persons other than Licensee's employees and contractors for Licensee's internal business purposes, unless previously agreed to in writing by Avaya. If Licensee reproduces copies of printed documents for Licensee's internal business purposes, then these copies should be marked “For internal use only within only.” on the first page or cover (where is the name of Licensee). Licensee must fully and faithfully reproduce any proprietary notices contained

Issue 2.1 August 2003

11

Before You Begin

in the documentation. The copyrights to all documentation provided by Avaya are owned by Avaya and its licensors. By printing any copy of online documentation Licensee indicates its acceptance of these terms and conditions. This license only governs terms and conditions of printing online documentation. Please reference the appropriate license agreement for terms and conditions applicable to any other use, reproduction, modification, distribution or display of Avaya software and documentation.

Educational Services Avaya University provides excellent training courses on a variety of topics. For the latest course descriptions, schedules, and online registration, you can get in touch with us: ●

Through the web at http://www.avaya-learning.com/logon_form.asp

●

Over the telephone at 800-288-5327 (within the U.S.) +001 303-406-6089 (outside of the U.S.)

●

Through email at [email protected]

12 VTel Automation Server Programmer Guide

Chapter 1: Introduction This document describes and illustrates an automation API for VTel. You should be familiar with the basic functioning of VTel, as described in VTel Programmer’s Guide. The VTel Automation Server is part of the Telephony Agent module. This section includes the following topics: ●

Defining OLE automation on page 14

●

Getting started on page 15

●

Visual Basic and Visual C++ programming conventions on page 19

Issue 2.1 August 2003

13

Introduction

Defining OLE automation OLE (Object Linking and Embedding) automation is a Microsoft programming standard. Applications that adhere to the standard expose their functions and routines so that they are available to Visual Basic and C++ programmers. Many of Microsoft's applications support OLE; for example, programs you write can call Microsoft Word and Excel functions. Imagine you are faced with a programming task that requires telephony functions from both Avaya and a third party vendor, as well as charting capabilities from Excel:

VTel Soft-Phone

Excel

Third Party Telephony

OLE Automation

OLE Controller

Your Application

Your program can invoke telephony functions in both VTel and the third party application. Your program can also make use of Excel's calculation functions or its charting engine. Typically, only your application will appear on the screen. The others execute, but remain invisible throughout the session. They serve principally as programming libraries on which you can build. Alternatively, your program can make itself invisible, and have the automated applications appear. This approach may be useful in coordinating a number of otherwise unrelated applications.

14 VTel Automation Server Programmer Guide

Getting started

Using the terms associated with OLE, your program is an Automation Controller, since your application is controlling the automated applications. The three applications are themselves called Automation Servers, since they offer their services to your controller. Both servers and controllers can be written in Visual Basic and Visual C++.

! CAUTION: The Avaya Agent does not support other applications using other VTel OLE sessions for telephony function calls.

CAUTION:

Getting started VTel continues to function exactly as it did in the past. No changes to its operation have been made. See VTel Programmer’s Guide for a complete description of VTel.

!

Important: With Interaction Center releases 6.0 and higher, VTel does not function outof-the-box. If you need to enable VTel, please contact Technical Support for assistance. For contact information, see Contacting Technical Support on page 10.

Important:

To use VTel as an automation server, you may need to relocate some of the files you installed with VTel. To relocate the files: 1. If you have not already done so, install the 32-bit version of VTel. The installation directory you specified contains two subdirectories: ●

●

bin\ , which contains ●

.h and .cpp files useful for writing C++ automation controllers

●

the Automation Server’s type library, which is required for all C++ controllers

etc\ , which is used by VTel when VTel is launched by OLE.

2. Copy the .pk and .imp files into the etc\ directory. 3. Copy the vesporb.dll file to the bin\VTel directory. 4. The install automatically configures the VTel .ini file to the PBX type that you chose during the VTel install. This file resides in the etc\ directory and is named vtel.ini. Copy vtel.ini to the bin\ directory. 5. Check vtel.ini to make sure automation and synchronous pass-through are enabled. In the Options section, set OLE and VESPddeSync to Y. 6. Start VTel and then exit VTel. This registers VTel with the OLE subsystem. 7. Verify the TCP/IP connection to the Contact Engine server by pinging the connection.

Issue 2.1 August 2003

15

Introduction

Error messages while launching VTel using OLE Visual Basic error: Cannot create ActiveX control If you receive this Visual Basic error message, the OLE subsystem may not be able to locate VTel on your system, or VTel cannot find the file vesporb.dll. Make sure you have: ●

run VTel once and exited VTel

●

copied the vesporb.dll into the bin\ directory

●

set the OLE option for the vtel.ini file in the Options menu to Y

●

verified that vtel.ini is in the bin\ directory

VTel Login error: VESP:00000000 If you receive this VTel Login error, there is something wrong with the connection to Avaya TS. Make sure that you have: ●

verified your TCP/IP connection

●

copied the correct .pk and .imp files into the etc\ directory

●

verified that your Contact Engine servers are running by using IC Manager

Test programs Using VTel as an automation server from Visual Basic You can run VTel as an automation server from Visual Basic (or from Microsoft Excel, for example, using Visual Basic for Applications) with the following test program: Dim VTel As Object Dim Status As Boolean ' Launch the Automation Server and bind our "VTel" object variable to it Set VTel = CreateObject("VTEL.SESSION") ' See if VTel is alive Status = VTel.PingSynch() ' Close down VTel Status = VTel.ExitSynch() Set VTel = Nothing

16 VTel Automation Server Programmer Guide

Getting started

You can now use the debugger to step through your program. You should see: ●

Note:

the VTel login dialog when the VTel OLE object is created Note: If the login dialog does not appear, make sure that the vtel.ini file specifies a GUI type other than none.

●

VTel.PingSynch() return a status of TRUE

●

VTel exit when ExitSynch() is invoked

Using VTel as an automation server in Visual C++ Writing a controller in Visual C++ requires creating a C++ project first. To create the project: 1. Choose the New option from the File menu, then select Project Workspace.

Note:

Note: The method described uses Visual C++ version 6.0 as an example. 2. From the New Project Workspace dialog, select MFC AppWizard (exe), specify a target directory and project name, then click OK. 3. From Step 1 of the MFCAppWizard dialog, select Dialog Based. Click the Next button. 4. From Step 2 of the MFCAppWizard dialog, check the OLE Automation option, then click Finish.

Note:

Note: In Visual C++ version 6.0, this option is no longer available. After completing Step 1 of the MFCAppWizard dialog, select Finish. 5. Open the MFC Class Wizard dialog by pressing Ctrl+W. 6. Select Add Class..., then select From a type library... 7. Locate the vtel.tlb type library in the VTel \lib directory.

Note:

Note: This library can also be found in the \bin directory, depending on your installation. 8. In the Confirm Classes dialog, select only the IVTelOleSession class, then click OK. 9. Click OK to close the MFC Class Wizard dialog.

You have generated a proxy class from the type library. It is possible to control the server using this generated proxy. You can also use the proxy class files provided by the Avaya TS. To use the Avaya TS proxy files, copy the VProxy.cpp and VProxy.h files into your project from the VTel \source directory.

Issue 2.1 August 2003

17

Introduction

Note: Be sure to add these files into the project using Insert > Files Into Project…

Note:

10. In your project .cpp file, add this line to the other #include statements: #include VProxy.h 11. You can now place the following code in your project’s OnInitDialog() method: BOOL Status; CString VduID; // Connect to Automation Server using Avaya Telephony's proxy class: CVTelProxy VTel; // See if we can talk to VTel Status = VTel.PingSynch(); // Shut down VTel Status = VTel.ExitSynch();

You can now use the debugger to step through your program. You should see: ●

the VTel login dialog when the CVTelProxy object is created

●

PingSynch() return a status of TRUE

●

VTel exit when ExitSynch() is invoked

Breaking the OLE connection with VTel VTel keeps an internal count of active OLE connections. When a client makes an initial OLE connection to VTel: Set VTel = CreateObject("VTEL.SESSION") the OLE connection count is incremented. When a client ends or terminates that OLE connection: Set VTel = Nothing VTel decrements its connection count. This internal count must be 0 for VTel to exit cleanly. Thus, after a client sends a VTel.Exit command, or receives a VTel.Exit.event, the client should immediately issue the command Set VTel = Nothing. This will terminate the OLE session with VTel and allow VTel to exit cleanly.

Note:

Note: Once the Set VTel = Nothing command is executed, the programmer must make sure that no other automation commands, such as PeekResponse or PeekEvent, are called.

18 VTel Automation Server Programmer Guide

Visual Basic and Visual C++ programming conventions

Visual Basic and Visual C++ programming conventions Throughout this document, programming examples will be given in both Visual Basic and Visual C++. Function names are the same in both cases. Variable types can be converted back and forth according to the following table. Automation Type

VB Type

C++ Type

Status

Boolean

BOOL

ResponseHandle, EventHandle, Any numeric value

Long

long

Sequence Of Strings, Sequence Of Couples, Any String Value

String

CString

Most functions return a value (Boolean, long integer, or string). Several also deliver values through output parameters. In the following example, MakeCallSynch() returns a TRUE/FALSE status and assigns a new electronic Data Unit (EDU) ID to its output parameter, VduID: Dim VTel As Object Dim Status As Boolean Dim VduID As String 'Start the Automation Server and bind our object variable "VTel" to it. Set VTel = CreateObject("VTEL.SESSION") ' Login as Fred Status = VTel.LoginSynch("Fred","","","","") ' Use the default phone to call extension 4004. Store the resulting ' VDUID in our "VduID" variable. Status = VTel.MakeCallSynch("", "4004", VduID) . .

Issue 2.1 August 2003

19

Introduction

In Visual C++, substitute "BOOL" for "Boolean", "long" for "Long", and "CString" for "String" when declaring variables: BOOL Status; CString VduID; // Connect to Automation Server using Avaya Telephony's proxy class: CVTelProxy VTel; // Login as Fred Status = VTel.LoginSynch("Fred","","","",""); // Call extension 4004. Store new VDUID in our "VduID" variable. Status = VTel.MakeCallSynch("", "4004", VduID); . . .

20 VTel Automation Server Programmer Guide

Chapter 2: The Automation API This chapter provides an introduction to the API, and contains the following sections: ●

Overview on page 22

●

Event processing on page 26

●

Error handling on page 27

●

Sequences of strings and couples on page 30

Issue 2.1 August 2003

21

The Automation API

Overview The functions described in Chapter 1 are synchronous functions. They are designated with the suffix "Synch". Synchronous functions do not return a value until a response has been received. For example, this Visual Basic code fragment: // Call extension 4004. Store new VDUID in our "VduID" variable. Status = VTel.MakeCallSynch("", "4004", VduID);

executes a MakeCallSynch() inside the Automation Server. This request is issued: [VTel.MakeCall("","4004",)]

Since the automation method is synchronous, a matching response must be received: [VTel.MakeCall.response(,,"4004","324fe7840000000078000011203d0002")]

In this case, the response indicates no error has occurred. The returned status will be TRUE. These Synch routines are called convenience methods, since they wrap up several automation calls. For example, the MakeCallSynch() method really performs a number of functions, shown in the code for the method: ' Needed to process response from MakeCall() Dim ResponseHandle As Long Dim StatusRequest As Boolean Dim StatusResponse As Boolean ' Call extension 4004, but do not wait for a response ResponseHandle = VTel.MakeCall("", "4004") ' Pause until a response is received VTel.WaitForResponse ResponseHandle ' Parse the response string and store the new VDUID in our variable, "VduID" ' StatusRequest should never be FALSE (indicates an invalid response handle) StatusRequest = VTel.GetMakeCallResponse(ResponseHandle, VduID) ' Set StatusResponse to FALSE if response string indicates error has occurred StatusResponse = VTel.GetResponseStatus(ResponseHandle) ' Release server resources associated with this response VTel.FreeResponse ResponseHandle ' Display the new VDUID VduIDTextBox.Text = VduID

22 VTel Automation Server Programmer Guide

Overview

The convenience methods can simplify small programming tasks; for example, synchronous functions combine request posting and response processing. Consider the following Visual Basic fragment for the Call button: Private Sub Call_Click() Dim Status As Boolean Status = VTel.MakeCallSynch("", "4004", VduID) If Status = True Then StatusTextBox.Text = "OK" VduIDTextBox.Text = VduID Else StatusTextBox.Text = "ERROR" End If End Sub

Since this example uses the convenience method (MakeCallSynch()rather than MakeCall()), execution will be paused in the control method until a response is received. As a result, the application may be unresponsive for a time. The specific duration will vary with the type of request. Many simple requests, such as PingSynch(), are handled quickly. Other requests, such as VDUFindVDUSynch(), require external services and may take quite a few seconds to complete. If this blocking behavior is inappropriate for your application, you should use the asynchronous functions instead of the convenience methods. The following Visual Basic fragment shows how the asynchronous MakeCall method might be used to handle a Call button click: Private Sub Call_Click() VTel.MakeCall "", "4004" End Sub

This simply posts the MakeCall request and returns without waiting for a response. Consequently, the application will no longer pause when the Call button is clicked. You will still need to process the response elsewhere. One possibility is to set up a timer method that will be invoked three or four times a second: Private Sub PollingTimer_Timer() Dim ResponseName As String Dim ResponseExists As Boolean ' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.MakeCall": ' Response from MakeCall request, display new VduID VTel.GetMakeCallResponse ResponseHandle, VduID VduIDTextBox.Text = VduID

Issue 2.1 August 2003

23

The Automation API

Case "VTel.Logout": . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

Here, the timer routine checks for a response to the MakeCall request. If a response is received, this routine parses the response to obtain the VDUID, and then displays the ID in a text box. Finally, FreeResponse() is called to release server resources associated with the response. There are several functions are available to assist in the processing of responses. For more information, see Response processing methods on page 57. The sample softphone application in Programming example: implementing a softphone on page 33 expands on this example using Visual C++. The sample application focuses more on the processing of events rather than responses, but the concepts are similar. For additional information on event processing, see Event processing on page 26, and Event processing methods on page 59.

Preventing VB polling conflicts Using timer routines in Visual Basic clients is an effective way to poll VTel for responses and events. VTel.PeekResponse and VTel.PeekEvent are timer routines. In Visual Basic, timer routines are given a higher Windows message priority than any other Windows message sent from Visual Basic. If you are invoking an OLE Automation API call outside of a timer routine, it is possible that the OLE API call will be interrupted by a timer routine. If the OLE API call is interrupted, the timer routine will invoke another OLE Automation API call before the interrupted call has completed. When this condition occurs, the Windows messaging queue becomes full, resulting in an OLE Automation error.

24 VTel Automation Server Programmer Guide

Overview

To prevent this condition from arising, your program should use a flag (a mutex global) to prevent a timer routine from processing responses or events while an OLE Automation call is being made from outside of the timer routine. For example: 'Declared in the Declarations section of a code module 'Initialize to False Global Mutex as Boolean Private Sub Call_Click() Mutex = True VTel.MakeCall() Mutex = False End Sub

Private Sub Response_Timer() Dim ResponseExists as Boolean Dim ResponseHandle as Long If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then 'Process and free response End If End Sub

The last two code fragments in the Call_Click()routine should read (the additional lines of code are in boldface): Private Sub Call_Click() Mutex = True VTel.MakeCall "", "4004" Mutex = False End Sub

and Private Sub PollingTimer_Timer() Dim ResponseName As String Dim ResponseExists As Boolean ' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.MakeCall": ' Response from MakeCall request, display new VduID

Issue 2.1 August 2003

25

The Automation API

VTel.GetMakeCallResponse ResponseHandle, VduID VduIDTextBox.Text = VduID Case "VTel.Logout": . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

Event processing During a call, many events are generated by VTel. The VTel event stream is a source of information for phone state, call state, and EDU values. For a detailed description of each VTel event, please see the "Event Notifications" chapter in VTel Programmer’s Guide. Events should be processed in the same manner as asynchronous responses. One way to do this is to set up a timer method that will be invoked three or four times a second; for an example, see PeekEvent on page 203. For a listing of the event processing methods, see Event processing methods on page 59. For a discussion of these methods see API Methods: Descriptions on page 67. For a listing of event codes, see Event codes on page 65. For comments on Exit events, see Breaking the OLE connection with VTel on page 18, and Programming Exit events on page 47.

26 VTel Automation Server Programmer Guide

Error handling

Error handling The convenience methods return FALSE if an error occurs. To obtain error specifics, call GetLastResponseDetail() as in the following Visual C++ example: BOOL Status; // TRUE if request succeeded CString Origin; // e.g.: USER, SYSTEM, or VTEL CString ErrorCode; // Hexadecimal error code CString Description; // A descriptive error message CString ReturnCode; // Return code from Avaya Telephony // Use the default phone to call (508) 555-1212, and wait for response Status = VTel.MakeCallSynch("","5085551212"); // Did everything go OK? if (!Status) { // No, find out why not. Note that response details are overwritten on each // new error. VTel.GetLastResponseDetail(Origin, ErrorCode, Description, ReturnCode); } . .

Response processing is performed in a loop, idle-time processing method, or timer handler. Error processing takes place there as well. Consider the following C++ code fragment: // On idle() or OnTimer() long NextResponse; // Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case 0: // The response was "VTel.Error". Check the response details // for more information. They will most likely show that the // request syntax was invalid. AfxMessageBox("Response was VTel.Error"); break; case -1: // The response handle from GetResponseType() was invalid// should not happen. AfxMessageBox("Internal error in Automation Server!"); break;

Issue 2.1 August 2003

27

The Automation API

case -2: // Server response queue overrun, we must have forgotten to free // responses! AfxMessageBox("Server ran out of space and dropped responses."); break; case -3: // Unrecognized response type, no response code available. // Use GetResponseName() to obtain the name of a new type of // response. . . . case 22: // MakeCall. Use specific response parsing routine to obtain // the associated VDUID. CString VduID; if ( VTel.GetMakeCallResponse(ResponseHandle, VduID) ) { // Response was OK. Do something with this VDUID such as // add it to a collection of active calls. . . . } else { // Response indicates error, get specifics. VTel.GetResponseDetail(ResponseHandle, Origin, ErrorCode, Description, ReturnCode); . . . } break;

case 15: // Hangup— handled as a generic response. if ( VTel.GetResponseStatus(ResponseHandle) ) { // Response was OK. Do something such as set the call // state. . . . } else

28 VTel Automation Server Programmer Guide

Error handling

{ // Response indicates error, get specifics. VTel.GetResponseDetail(ResponseHandle, Origin, ErrorCode, Description, ReturnCode); . . . } break; default: // Not handling any other responses } // We are done with the response, release resources. VTel.FreeResponse(NextResponse); } else { // No response waiting, do some other work . . } }

In Visual Basic examples, GetResponseName() determined which response to process. In the C++ example above, GetResponseCode() is called to obtain a response code instead. Values less than or equal to zero indicate errors. Values greater than zero represent specific responses such as the VTel.MakeCall response. A complete listing of response codes is provided in Response codes on page 61.

Note:

Note: A response code value greater than zero indicates that a response was received. The response itself may indicate that an error has occurred. In the example above, Case 22 illustrates response processing for the MakeCall request. Here, GetMakeCallResponse() is called to obtain the new VDUID. If the return value is FALSE, the response indicates an error. In that case, further information can be obtained via GetResponseDetail().

Issue 2.1 August 2003

29

The Automation API

Sequences of strings and couples Some functions accept or return sequences. There are two types of sequences: ●

sequence of strings , which is an ordered collection of strings, each referenced by position

●

sequence of couples, which is an unordered collection of values each referenced by name

Sequence of strings This is an example of a sequence of strings: "2df5d9e6003b00007800002a1f43002", "2df5d9e6003b00007800003bff430002"

Each of the two strings in this simplified example is a VDUID. A sequence of strings like this might be returned by the VDUGetActiveSynch() method. VDUGetActiveSynch() returns a sequence of strings, each containing one of the currently active VDUIDs. This Visual Basic example shows how to use the VDUGetActiveSynch() method to return strings from a sequence of strings: Dim Dim Dim Dim

Status As Boolean SeqStrings As String NumberOfStrings As Long VduID1 As String

' Get list of currently active VDUs Mutex = True Status = VTel.VDUGetActiveSynch (SeqStrings) Mutex = False ' Find out how many strings there are NumberOfStrings = VTel.SeqStringCount (SeqStrings) ' Get the first string Mutex = True VduID1 = VTel.SeqStringGet (SeqStrings, 0) Mutex = False

30 VTel Automation Server Programmer Guide

Sequences of strings and couples

Sequence of couples A sequence of couples consists of name-value pairs. This is an example as a sequence of couples: "agentID","Fred" "vduID","2df5d9e6003b00007800002a1f43002" "ani","4003" "dnis","4004"

In this simplified example, the first string in each pairing is the "name" in the name-value pair; the second is the "value." A sequence of couples like this one might be returned by VDUGetValuesSynch(). VDUGetValuesSynch() returns the contents of a specified VDU, each value of which can be obtained by name . This Visual Basic example shows how to use VDUGetValuesSynch() to retrieve values associated with a sequence of couples: Dim Dim Dim Dim

SeqCouples As String Ani As String Dnis As String VduID As String

' Make call, use new VDUID to obtain ANI and DNIS Mutex = True Status = VTel.MakeCallSynch("", "4004", VduID) Mutex = False Mutex = True Status = VTel.VDUGetValuesSynch(VduID, SeqCouples) Mutex = False Mutex = True Ani = VTel.SeqCoupleGet(SeqCouples, "ani") Mutex = False Mutex = True Dnis = VTel.SeqCoupleGet(SeqCouples, "dnis") Mutex = False

One useful function of a sequence of couples is to add or change a VDU's values. The function VDUSetValues() takes a VDUID and a sequence of couples as arguments. For each couple in the sequence, the name is compared against those in the specified VDU. If a match is found, the new value is assigned. If no match is found, both the name and its value are added to the VDU: Dim SeqCouples As String ' Make a new, empty sequence of couples Mutex = True SeqCouples = VTel.SeqCoupleCreate() Mutex = False

Issue 2.1 August 2003

31

The Automation API

' Add a name/value pair Mutex = True SeqCouples = VTel.SeqCoupleSet(SeqCouples, "ivrCode", "32") Mutex = False ' Add another name/value pair Mutex = True SeqCouples = VTel.SeqCoupleSet(SeqCouples, "reasonCode", "4201") Mutex = False ' Replace value for existing name/value pair Mutex = True SeqCouples = VTel.SeqCoupleSet(SeqCouples, "ivrCode", "95") Mutex = False ' Add to (or replace) couples in a specified VDU Mutex = True Status = VTel.VDUSetValuesSynch (VduID, SeqCouples) Mutex = False

Creation of a sequence of strings is similar: Dim SeqStrings As String ' Make a new, empty sequence of strings Mutex = True Status = VTel.SeqStringCreate () Mutex = False ' Add strings Mutex = True SeqStrings = VTel.SeqStringAdd (SeqStrings, "String1") Mutex = False Mutex = True SeqStrings = VTel.SeqStringAdd (SeqStrings, "String2") Mutex = False . . .

Note:

Note: Unlike responses, sequences consume no server resources. Consequently, there is no need for a call analogous to FreeResponse().

32 VTel Automation Server Programmer Guide

Chapter 3:Programming example: implementing a softphone This chapter explains how to create the simplified softphone shown in the following illustration, created in Visual C++:

Issue 2.1 August 2003

33

Programming example: implementing a softphone

.The following illustration shows the member variables and functions for the dialog box: CControllerDlg

m_butAnswer m_butMakeCall OnAnswer() OnMakeCall()

m_editDestination

m_butHangUp m_butTransfer OnHangUp() OnTransfer()

m_editAni

VTel Automation Server

m_butConference m_butLogout OnConference() OnLogout()

m_editDnis

m_editVdu m_editStatus m_editEvents

Other CControllerDlg member data: CString m_vduID; CVTelProxy* m_VTel;

The framework for this application can be created by following the steps outlined in Using VTel as an automation server from Visual Basic on page 16.

34 VTel Automation Server Programmer Guide

Logging into the server

Logging into the server The OnInitDialog() method used in this example will also log into the server: BOOL CControllerDlg::OnInitDialog() { CDialog::OnInitDialog(); // Add "About..." menu item to system menu. . . // Get a session and login m_VTel = new CVTelProxy; VERIFY(m_VTel->LoginSynch("fred","","","","")); // Enable only the MakeCall and Logout buttons. // All others are disabled at start up. m_butMakeCall.EnableWindow(TRUE); m_butLogout.EnableWindow(TRUE); // Initialize the destination and status edit controls. m_editDestination.SetWindowText("4004"); m_editStatus.SetWindowText("Ready"); return TRUE; // return TRUE unless you set the focus to a control }

Issue 2.1 August 2003

35

Programming example: implementing a softphone

Logging out of the server When clicked, the Logout button executes LogoutSynch()and changes the Logout button text to Exit. When clicked again, both the server and the controller are terminated: void CControllerDlg::OnLogout() { static BOOL Logout = TRUE; CWaitCursor Busy; // Logout or exit? if (Logout) { // Logout m_butAnswer.EnableWindow(FALSE); m_butMakeCall.EnableWindow(FALSE); m_butHangUp.EnableWindow(FALSE); m_butTransfer.EnableWindow(FALSE); m_butConference.EnableWindow(FALSE); m_butLogout.SetWindowText("Exit"); VERIFY(m_VTel->LogoutSynch()); Logout = FALSE; } else { // Terminate server and quit m_butLogout.EnableWindow(FALSE); m_VTel->ExitSynch(); delete m_VTel; m_VTel = 0; PostQuitMessage(0); } }

36 VTel Automation Server Programmer Guide

Using the Make Call button

Using the Make Call button The Make Call button handler issues a call to the phone number in the Destination edit box: void CControllerDlg::OnMakecall() { CString Destination; CString VduID; CString ErrorMsg; // Call the number in the destination edit box m_editDestination.GetWindowText(Destination); if (m_VTel) { // MakeCall failed if (!m_VTel->MakeCallSynch("", Destination, VduID)) { ErrorMsg.Format("MakeCall failed trying to call \"%s\"", Destination); AfxMessageBox(ErrorMsg); } else { // MakeCall succeeded m_butMakeCall.EnableWindow(FALSE); } } }

No other button will function until an event is issued enabling the button. For example, the Hang Up button is enabled whenever a Connect event occurs. Conversely, it is disabled on any occurrence of a Disconnect event.

Issue 2.1 August 2003

37

Programming example: implementing a softphone

Event processing Event processing takes place in the dialog's OnIdle() method. The dialog's OnIdle() method should be invoked from your application's OnIdle() method: // Handle incoming events and responses. void CControllerDlg::OnIdle() { long ResponseHandle; long EventHandle; CString ResponseStr; CString EventName; CString EventStr; CString CallState; CString VduID; CString SeqCouples; CString Ani; CString Dnis; CString StatusMsg; // Do we have a connection to the server? if (m_VTel) { // Yes, handle all currently queued responses while (m_VTel->PeekResponse(&ResponseHandle)) { // Place holder. This example does not actually do anything with responses. // We will just free them up as they arrive. VERIFY( m_VTel->FreeResponse(ResponseHandle) ); } // Now handle all currently queued events while (m_VTel && m_VTel->PeekEvent(&EventHandle)) { // Display the event in our scrolling event window EventStr = m_VTel->GetEventString(EventHandle); VERIFY( !EventStr.IsEmpty() ); EventStr += "\n"; appendText(EventStr, m_editEvents); // Take action based on event code switch ( m_VTel->GetEventCode(EventHandle) ) { // Bad handle case -1: AfxMessageBox("Internal error- Invalid event handle!"); break; // Event queue overrun case -2: AfxMessageBox("Event queue overflow. Please terminate session."); break;

38 VTel Automation Server Programmer Guide

Event processing

// Unrecognized (newly introduced) event case -3: EventName = m_VTel->GetEventName(EventHandle); // The CallChange event is new, is this it? if (EventName == "VTel.CallChange") { // Yes. Are we in call? CallState = m_VTel->GetEventArg(EventHandle, "CallState"); if (CallState == "InCall") { // Yes, display a message such as "From 4100 to 5305 (State: In Call)" VduID = m_VTel->GetEventArg(EventHandle, "vdu_id"); VERIFY( m_VTel->VDUGetValuesSynch(VduID, SeqCouples) ); Ani = m_VTel->SeqCoupleGet(SeqCouples, "ani"); Dnis = m_VTel->SeqCoupleGet(SeqCouples, "dnis"); StatusMsg.Format("From %s to %s (State: In Call)", Ani, Dnis); m_editStatus.SetWindowText(StatusMsg); } } break; // Connect case 3: // Store away the new VDUID for hang up or anyone else who is interested m_vduID = m_VTel->GetEventArg(EventHandle, "vdu_id"); // New call, so only buttons enabled are "Hang Up", "Transfer" and "Conference" m_butHangUp.EnableWindow(TRUE); m_butAnswer.EnableWindow(FALSE); m_butTransfer.EnableWindow(TRUE); m_butConference.EnableWindow(TRUE); m_butLogout.EnableWindow(FALSE); break; // Disconnect case 4: // Lost call, so the only buttons enabled will be "MakeCall" and "Logout" m_editStatus.SetWindowText("Ready"); m_butMakeCall.EnableWindow(TRUE); m_butHangUp.EnableWindow(FALSE); m_butAnswer.EnableWindow(FALSE); m_butTransfer.EnableWindow(FALSE); m_butConference.EnableWindow(FALSE); m_butLogout.EnableWindow(TRUE); break; // Exit case 6: // Quit PostQuitMessage(0); delete m_VTel; m_VTel = 0; break;

Issue 2.1 August 2003

39

Programming example: implementing a softphone

// IncomingCall case 8: // Store away the VDUID for the "Hang Up" button handler and // anyone else who is interested. m_vduID = m_VTel->GetEventArg(EventHandle, "vdu_id"); // Display a message such as "From 4100 to 5305 (State: Ringing)" VERIFY( m_VTel->VDUGetValuesSynch(m_vduID, SeqCouples) ); Ani = m_VTel->SeqCoupleGet(SeqCouples, "ani"); Dnis = m_VTel->SeqCoupleGet(SeqCouples, "dnis"); StatusMsg.Format("From %s to %s (State: Ringing)", Ani, Dnis); m_editStatus.SetWindowText(StatusMsg); // New call coming in, so disable "Make Call" and enable "Answer" m_butMakeCall.EnableWindow(FALSE); m_butAnswer.EnableWindow(TRUE); break; // VDUChange case 22: // Display updated ANI, DNIS, and VDUID m_editAni.SetWindowText(m_VTel->GetEventArg(EventHandle, "ani")); m_editDnis.SetWindowText(m_VTel->GetEventArg(EventHandle, "dnis")); m_editVdu.SetWindowText(m_VTel->GetEventArg(EventHandle, "vdu_id")); break; // VDUTerminated case 24: // Clear all edit controls m_editAni.SetWindowText(""); m_editDnis.SetWindowText(""); m_editVdu.SetWindowText(""); break; } // Was m_VTel deleted above? if (m_VTel) { // No, clean up event VERIFY( m_VTel->FreeEvent(EventHandle) ); } } } }

40 VTel Automation Server Programmer Guide

Programming the Hang Up and Answer buttons

Programming the Hang Up and Answer buttons Note that the current VDUID (m_vduID) is updated above in the cases for Connect and IncomingCall. The Hang Up and Answer button handlers make use of the ID as shown below: // Message handle for the "Hang Up" button void CControllerDlg::OnHangup() { if (m_VTel) { if (!m_VTel->HangupSynch(m_vduID)) AfxMessageBox("HangUp failed"); } } // Message handle for the "Answer" button void CControllerDlg::OnAnswer() { if (m_VTel) { if (!m_VTel->AnswerSynch(m_vduID)) AfxMessageBox("Answer failed"); } }

Issue 2.1 August 2003

41

Programming example: implementing a softphone

Programming the Transfer button The Transfer button handler also makes use of the current VDUID. When first clicked, the button initiates a transfer and sets its button text to Complete. When clicked again, the transfer is completed and the original button text is restored: // Message handler for the "Transfer" button void CControllerDlg::OnTransfer() { CString Destination; CString ErrorMsg; static BOOL IsTransfer = TRUE; // Initiate transfer to the number in the destination edit box m_editDestination.GetWindowText(Destination); if (m_VTel) { // Transfer or transfer complete? if (IsTransfer) { // Transfer if (!m_VTel->TransferInitSynch(m_vduID, Destination)) { ErrorMsg.Format("Transfer init failed trying to call \"%s\"", Destination); AfxMessageBox(ErrorMsg); } else { IsTransfer = FALSE; m_butTransfer.SetWindowText("Complete"); } } else { // Transfer complete if (!m_VTel->TransferCompleteSynch(m_vduID)) AfxMessageBox("Transfer complete failed"); else { IsTransfer = TRUE; m_butTransfer.SetWindowText("Transfer"); } } } }

42 VTel Automation Server Programmer Guide

Programming the Conference button

Programming the Conference button The code for the Conference button is similar to the code in the Transfer button: // Message handler for the "Conference" button void CControllerDlg::OnConference() { CString Destination; CString ErrorMsg; static BOOL IsConference = TRUE; // Initiate conference to the number in the destination edit box m_editDestination.GetWindowText(Destination); if (m_VTel) { // Conference or conference complete? if (IsConference) { // Conference if (!m_VTel->ConferenceInitSynch(m_vduID, Destination)) { ErrorMsg.Format("Conference init failed trying to call \"%s\"",Destination); AfxMessageBox(ErrorMsg); } else { IsConference = FALSE; m_butConference.SetWindowText("Complete"); } } else { // Conference complete if (!m_VTel->ConferenceCompleteSynch(m_vduID)) AfxMessageBox("Conference complete failed"); else { IsConference = TRUE; m_butConference.SetWindowText("Conference"); } } } }

Issue 2.1 August 2003

43

Programming example: implementing a softphone

44 VTel Automation Server Programmer Guide

Enabling automation

Chapter 4: Cautions This section explains some potential problems associated with installing and using the Automation Server. This section includes the following topics: ●

Enabling automation on page 45

●

Registering VTel on page 46

●

Using convenience methods on page 46

●

Using multiple controllers on page 46

●

Using multiple servers on page 47

●

Programming Exit events on page 47

●

Editing system registry entries on page 48

Enabling automation Before you can run VTel as an automation server, you will need to enable automation in the configuration file, called vtel.ini. To enable automation: 1. In the vtel.ini file, change the value of the OLE variable to Y. The OLE variable is in the Options section of the vtel.ini file. 2. You may also need to change the value of the VESPddeSync variable to Y. VESPddeSync is also in the Options section of the vtel.ini file. For more information about the vtel.ini file, see Appendix A of VTel Programmer Guide.

Issue 2.1 August 2003

45

Cautions

Registering VTel You can place the executable for VTel in any directory. When VTel is started from an automation controller, however, VTel still uses the .pk, .imp, and .ini files located in the installation directory.

Note:

Note: You must run VTel once before attempting to use it as an automation server. This will register the server with your system so that controllers can locate and execute it. Before running VTel for the first time, be sure that automation is enabled in the vtel.ini file.

Using convenience methods When using the convenience methods, be aware that they are synchronous. This means that they may block the server for a long period of time. If another controller makes a call to the server during the same period, it will become unresponsive. If this happens, you will see a dialog box alerting you of the conflict. While this is an inconvenience, the conflict will eventually be resolved when the blocked function times out. You may experience a similar problem if two different parts of the same program simultaneously access the server. For example, this condition might occur if a convenience routine blocks and a timer routine is used to poll for events and responses simultaneously. Because timer routines can be invoked preemptively, you can eliminate this conflict by using the OnIdle() function. To avoid these conflicts, you should use asynchronous functions in all but simple programs.

Using multiple controllers As noted in Using convenience methods, problems may occur if multiple controllers are running and one or more of those controllers make use of convenience methods. However, you may not be able to simultaneously run multiple controllers even if you only use the asynchronous functions, because VTel does not currently support concurrent logins. If you must run several controllers at the same time, be sure that only one performs a login. This restriction will likely be removed in an upcoming release.

46 VTel Automation Server Programmer Guide

Using multiple servers

Using multiple servers As noted in Enabling automation, you must enable automation in the vtel.ini file. When automation is enabled, any manually launched instance of VTel will be available as an automation server. Any controllers then running will connect to this process. Only one automation-enabled instance of VTel should ever be running. Unfortunately, there is currently no way for VTel to determine if it is being run as an automation server when an automation-enabled instance of VTel is already running. For example, there is nothing preventing an automation-enabled instance of VTel from being launched by a controller and a subsequent automation-enabled VTel process from being launched manually. Multiple servers will not exist when VTel is manipulated solely from automation controllers. The first automation controller being run will cause VTel to be launched. Subsequent controllers will connect to the same process.

Programming Exit events Controllers must respond to Exit events properly. When your application receives an Exit event, it should terminate its connection to the server. This C++ example shows a controller terminating the connection by deleting the proxy object: // Handle incoming events and responses. // void CControllerDlg::OnIdle() { . . . // Now handle all currently queued events while (m_VTel && m_VTel->PeekEvent(&EventHandle)) { // Take action based on event code switch ( m_VTel->GetEventCode(EventHandle) ) { . . // Exit case 6: // Quit PostQuitMessage(0); delete m_VTel;

Issue 2.1 August 2003

47

Cautions

m_VTel = 0; break; . . .

This Visual Basic example performs the same action: Private Sub PollingTimer_Timer() . . . ' Is there an event to process? If Mutex = True then Exit Sub EventExists = VTel.PeekEvent(EventHandle) If EventExists = True Then ' Yes, take action based on the event name EventName = VTel.GetEventName(EventHandle) Select Case EventName Case "VTel.Exit": ' Terminate session with server VTel = Nothing . . .

Editing system registry entries When the install script runs, it creates the following entries in the system registry: Registry Path

Value

HKEY_LOCAL_MACHINE, SOFTWARE, Microsoft, Windows, CurrentVersion, App Paths, VTEL.EXE, (default)

C:\Avaya\IC61\bin\VTel.exe

HKEY_LOCAL_MACHINE, SOFTWARE, Microsoft, Windows, CurrentVersion, App Paths, VTEL.EXE, Path

C:\Avaya\IC61\etc

The first entry points to the VTel executable. The second is used by VTel to locate its configuration, .pk, .imp, and vesporb.dll files. The values shown above are the defaults. Your values will differ if you choose another directory during installation. You should not normally need to edit these entries. However, you must change them should you move VTel and its associated files from the installation directory.

48 VTel Automation Server Programmer Guide

Chapter 5: API Methods: Relationships This section describes the Automation Server methods according to their relationships. This section includes the followng topics: ●

General methods on page 50.

●

Call management methods on page 50.

●

EDU management methods on page 53.

●

Session management methods on page 55.

●

Response processing methods on page 57.

●

Event processing methods on page 59.

●

Sequence management methods on page 60.

●

Response and event codes on page 61.

Descriptions of the Automation Server methods are presented in API Methods: Descriptions on page 67.

Note:

Note: Currently, each asynchronous method has an analogous synchronous convenience method. There is no guarantee, however, that this will be true of all asynchronous methods added in the future.

Issue 2.1 August 2003

49

API Methods: Relationships

General methods General methods are the basic methods on which all call management methods are based. Individual, type-safe methods have been provided for all functions exported by VTel. However, two general methods are provided for issuing these or any other requests: void MakeRequest( in string Request, out long ResponseHandle ) BOOL MakeRequestSynch( in string Request, out long ResponseHandle ) The automation API does not provide specific functions for accessing servers other than VTel. However, you can use VTel’s "pass-through" mechanism to post arbitrary requests to VTel or any other server. To post a request: 1. manually format a request string using the syntax for the function, as described in VTel Programmer Guide. 2. set the request string so that it will be passed to MakeRequest() or its synchronous counterpart, MakeRequestSynch(). 3. process the response. If MakeRequestSynch() is used, response processing can be performed immediately upon return. If MakeRequest() is used, a timer or idle function will most likely process the response. Response processing methods are described in Response processing methods on page 57. The examples for these general methods, given in MakeCall on page 194 and MakeCallSynch on page 195, use the MakeCall request. Individual functions have been provided for all VTel functions, including MakeCall (MakeCall() and MakeCallSynch()). You will only need to use MakeRequest() when the desired request is not explicitly provided as a function, (to issue a DS.Ping request, for example).

Call management methods Call management methods act on calls (for example, Answer() or Hangup()). This section covers telephony control. The various methods described here enable you to establish, receive, and transfer calls, or otherwise affect their state or that of the phone set.

50 VTel Automation Server Programmer Guide

Call management methods

Asynchronous methods for call management These methods correspond to the methods with the same names listed in VTel Programmer Guide. long Answer( in string VduID ) long Busy( in string PhoneNumber ) long BusyOverride( in string PhoneNumber ) long BusyPhoneset( ) long ConferenceCancel( in string VduID ) long ConferenceComplete( in string VduID ) long ConferenceInit( in string VduID, in string PhoneNumber ) long Drop( in string VduID, in string PhoneNumber ) long GetPhoneInfo( in string PhoneNumber ) long Hangup( in string VduID ) long Hold( in string VduID ) long HoldReconnect( in string VduID ) long MakeCall( in string PhoneOrig, in string PhoneDest ) long Ready( in string PhoneNumber ) long ReadyOverride( in string PhoneNumber ) long ReadyPhoneset( ) long ResetPhones( ) long RestartServer( in string Server, in long RetryLimit, in long WaitSeconds ) long SwapHeld( in string VduID ) long Terminate( in string VduID ) long Transfer( in string VduID, in string PhoneNumber ) long TransferCancel( in string VduID ) long TransferComplete( in string VduID ) long TransferInit( in string VduID, in string PhoneNumber ) long WrapUp( in string PhoneNumber ) long WrapUpOverride( in string PhoneNumber )

Issue 2.1 August 2003

51

API Methods: Relationships

Synchronous methods for call management Each synchonronous, or convenience, method in this section corresponds to the similarly named method in the preceding section. These methods help simplify some programming. BOOL AnswerSynch( in string VduID ) BOOL BusySynch( in string PhoneNumber ) BOOL BusyOverrideSynch( in string PhoneNumber ) BOOL BusyPhonesetSynch( ) BOOL ConferenceCancelSynch( in string VduID ) BOOL ConferenceCompleteSynch( in string VduID ) BOOL ConferenceInitSynch( in string VduID, in string PhoneNumber ) BOOL DropSynch( in string VduID, in string PhoneNumber ) BOOL GetPhoneInfoSynch( in string PhoneNumber, out string SequenceOfCouples ) BOOL HangupSynch( in string VduID ) BOOL HoldSynch( in string VduID ) BOOL HoldReconnectSynch( in string VduID ) BOOL MakeCallSynch( in string PhoneOrig, in string PhoneDest, out string VduID ) BOOL ReadySynch( in string PhoneNumber ) BOOL ReadyOverrideSynch( in string PhoneNumber ) BOOL ReadyPhonesetSynch( ) BOOL ResetPhonesSynch( ) BOOL RestartServerSynch( in string Server, in long RetryLimit, in long WaitSeconds ) BOOL SwapHeldSynch( in string VduID ) BOOL TerminateSynch( in string VduID ) BOOL TransferSynch( in string VduID, in string PhoneNumber ) BOOL TransferCancelSynch( in string VduID ) BOOL TransferCompleteSynch( in string VduID ) BOOL TransferInitSynch( in string VduID, in string PhoneNumber )

52 VTel Automation Server Programmer Guide

EDU management methods

BOOL WrapUpSynch( in string PhoneNumber ) BOOL WrapUpOverrideSynch( in string PhoneNumber )

EDU management methods These methods create, locate, modify, and obtain values from EDUs.

Asynchronous methods for EDU management These methods correspond to the methods with the same names in VTel Programmer Guide. long VDUCreate( in string SequenceOfCouples ) long VDUFindVDU( in string Criteria ) long VDUGetActive( ) long VDUGetCurrent( ) long VDUGetData( in string VduID ) long VDUGetOneValue( in string VduID, in string Attribute ) long VDUGetValues( in string VduID ) long VDUSetCurrent( in string VduID ) long VDUSetValues( in string VduID, in string SequenceOfCouples )

Issue 2.1 August 2003

53

API Methods: Relationships

Convenience methods for EDU management Each method in this section corresponds to the similarly named method in the preceding section, adding to it synchronous response processing. These methods are intended to simplify small programming tasks. BOOL VDUCreateSynch( in string SequenceOfCouples, out string VduID ) BOOL VDUFindVDUSynch( in string Criteria, out string SequenceOfStrings ) BOOL VDUGetActiveSynch( out string SequenceOfStrings ) BOOL VDUGetCurrentSynch( out string VduID ) BOOL VDUGetDataSynch( in string VduID, out string SequenceOfCouples ) BOOL VDUGetOneValueSynch( in string VduID, in string Attribute, out string Value ) BOOL VDUGetValuesSynch( in string VduID, out string SequenceOfCouples ) BOOL VDUSetCurrentSynch( in string VduID ) BOOL VDUSetValuesSynch( in string VduID, in string SequenceOfCouples )

54 VTel Automation Server Programmer Guide

Session management methods

Session management methods These methods establish, end, query, and test sessions.

Asynchronous methods for session management These methods correspond to the methods with the same names in VTel Programmer Guide. long ChangePassword( in string OldPassword, in string NewPassword ) long Exit( ) long GetInfo( ) long LogEntry( in string Text ) long Login( in string LoginID, in string Password, in string AgentID, in string AgentPassword, in string StationID ) long LoginACD( in string LoginID, in string Password, in string AgentID, in string AgentPassword, in string StationID, in string Queue ) long LoginTelephony( in string LoginID, in string Password, in string AgentID, in string AgentPassword, in string StationID, in string Queue ) long LoginVESP( in string LoginID, in string Password ) long Logout( ) long LogoutTelephony( in string retry_limit, in string wait_secs ) long LogoutVESP( ) long Ping( )

Issue 2.1 August 2003

55

API Methods: Relationships

Synchronous methods for session management The synchronous, or convenience, methods in this section correspond to the similarly named methods in the preceding section. These methods are intended to simplify small programming tasks. BOOL ChangePasswordSynch( in string OldPassword, in string NewPassword ) BOOL ExitSynch( ) BOOL GetInfoSynch( out string SequenceOfCouples ) BOOL LogEntrySynch( in string Text ) BOOL LoginSynch( in string LoginID, in string Password, in string AgentID, in string AgentPassword, in string StationID ) BOOL LoginACDSynch( in string LoginID, in string Password, in string AgentID, in string AgentPassword, in string StationID, in string Queue ) BOOL LoginTelephonySynch( in string LoginID, in string Password, in string AgentID, in string AgentPassword, in string StationID, in string Queue ) BOOL LoginVESPSynch( in string LoginID, in string Password ) BOOL LogoutSynch( ) BOOL LogoutTelephonySynch( in string retry_limit, in string wait_secs ) BOOL LogoutVESPSynch( ) BOOL PingSynch( )

56 VTel Automation Server Programmer Guide

Response processing methods

Response processing methods All asynchronous requests generate responses. This section lists methods that enable you to obtain, test, query, release, and suppress responses. Methods are also provided for interpreting specific responses (for example, GetMakeCallResponse()). For an example of response processing, see the OnIdle() function in the example in Error handling on page 27.

General methods This section covers general methods for working with responses. Methods for processing specific responses are given in Asynchronous-only methods on page 58. long FreeAllResponses( ) BOOL FreeResponse( in long ResponseHandle ) string GetResponseArg( in long ResponseHandle, in int ArgumentPosition ) long GetResponseCode( in long ResponseHandle ) long GetResponseCount( ) BOOL GetResponseDetail( in long ResponseHandle, out string Origin, out string ErrorCode, out string Description, out string ReturnCode ) void GetLastResponseDetail( out string Origin, out string ErrorCode, out string Description, out string ReturnCode ) string GetResponseName( in long ResponseHandle ) BOOL GetResponseStatus( in long ResponseHandle ) BOOL GetResponseString( in long ResponseHandle, out string OutResponseString ) BOOL PeekResponse( out long OutResponseHandle ) void SupressResponses( in BOOL Flag ) BOOL WaitForResponse( in long ResponseHandle )

Issue 2.1 August 2003

57

API Methods: Relationships

Asynchronous-only methods The methods in this section are used in extracting data from asynchronous responses. Each asynchronous request ( MakeCall(), for example) has a corresponding response function (GetMakeCallResponse(), for example). All the methods return FALSE if the response indicates an error, the handle is invalid, or the response is not of the expected type (for example, an attempt to parse a MakeCall response with GetGetInfoResponse()). BOOL GetGetInfoResponse( in long ResponseHandle, out string SequenceOfCouples ) BOOL GetGetPhoneInfoResponse( in long ResponseHandle, out string SequenceOfCouples ) BOOL GetMakeCallResponse( in long ResponseHandle, out string VduID ) BOOL GetVDUCreateResponse( in long ResponseHandle, out string VduID ) BOOL GetVDUFindVDUResponse( in long ResponseHandle, out string SequenceOfStrings ) BOOL GetVDUGetActiveResponse( in long ResponseHandle, out string SequenceOfStrings ) BOOL GetVDUGetDataResponse( in long ResponseHandle, out string SequenceOfCouples ) BOOL GetVDUGetCurrentResponse( in long ResponseHandle, out string VduID ) BOOL GetVDUGetOneValueResponse( in long ResponseHandle, out string Value ) BOOL GetVDUGetValuesResponse( in long ResponseHandle, out string SequenceOfCouples ) Should any of the above methods return FALSE, the following can be consulted for additional details: BOOL GetResponseDetail( in long ResponseHandle, out string Origin, out string ErrorCode, out string Description, out string ReturnCode ) The return value will be FALSE if the response indicates an error.

58 VTel Automation Server Programmer Guide

Event processing methods

Event processing methods These methods obtain, test, query, release, and suppress events. For an example of event processing, see the OnIdle() function in the example in Event processing on page 38. For descriptions of VTel events, see VTel Programmer Guide. long FreeAllEvents( ) BOOL FreeEvent( in long EventHandle ) string GetEventArg( in long EventHandle, in string ArgumentName ) long GetEventCode( in long EventHandle ) long GetEventCount( ) string GetEventName( in long EventHandle ) string GetEventString(in long EventHandle ) BOOL PeekEvent( out long OutEventHandle ) void SupressEvents( in BOOL Flag )

Issue 2.1 August 2003

59

API Methods: Relationships

Sequence management methods These methods create, query, and modify sequences of strings and sequences of couples. Sequence management is handle-free, consumes no server resources, and is very easy to maintain.

Sequence of couples Functions such as VDUCreate() take a sequence of couples as an argument. You can create a sequence of couples by calling the SeqCoupleCreate() function, and adding the couples with SeqCoupleSet(). A third function, SeqCoupleGet() can retrieve a specified value from an existing sequence of couples. This can be used for manually parsing response arguments retrieved from GetResponseArg(), for example. The string returned by each of these functions is a sequence of couples in Telephony string format. long SeqCoupleCount( in string SeqCouple ) string SeqCoupleCreate( ) string SeqCoupleGet( in string SeqCouple, in string Attribute ) string SeqCoupleGetAttrib( in string SeqCouple, in long AttribPosition ) string SeqCoupleGetVal( in string SeqCouple, in long AttribValue ) string SeqCoupleLimit( in string SeqCouple, in long Limit ) string SeqCoupleSet( in string SeqCouple, in string Attribute, in string Value )

60 VTel Automation Server Programmer Guide

Response and event codes

Sequence of strings Functions such as VDUGetActive() return a sequence of strings. You can iterate through strings by calling SeqStringCount() and SeqStringGet().You can also create a sequence of strings by calling SeqStringCreate(), and then adding strings with SeqStringAdd(). The string returned by these functions is a sequence of strings in Telephony string format. string SeqStringAdd( in string SeqString, in string String ) long SeqStringCount( in string SeqString ) string SeqStringCreate( ) string SeqStringGet( in string SeqString, in long StringPosition ) string SeqStringLimit( in string SeqString, in long Limit )

Response and event codes To simplify programming, all known responses and events have been assigned codes. These are enumerated here along with relevant error codes.

Response codes The following table describes each of the values returned by GetResponseCode(). For an example that uses this table, see Error handling on page 27 Code

Response or Error

-1

Invalid response handle

-2

Response queue overrun

-3

Unrecognized response (use GetResponseName())

0

VTel.Error

1

VTel.Answer

2

VTel.Assign

3

VTel.Busy

Issue 2.1 August 2003

61

API Methods: Relationships

Code

Response or Error

47

VTel.BusyOverride

44

VTel.BusyPhoneset

4

VTel.ChangePassword

5

VTel.ConferenceCancel

6

VTel.ConferenceComplete

7

VTel.ConferenceInit

8

VTel.Deassign

42

VTel.Drop

9

VTel.Exit

10

VTel.GetActive [an obsolete command (replaced by VDUGetActive())]

11

VTel.GetInfo

12

VTel.GetPhoneInfo

13

VTel.GuiCallHistory

14

VTel.GuiLogin

15

VTel.Hangup

16

VTel.Hold

17

VTel.HoldReconnect

46

VTel.LogEntry

18

VTel.Login

19

VTel.LoginACD

50

VTel.LoginTelephony

20

VTel.LoginVESP

21

VTel.Logout

51

VTel.LogoutTelephony

52

VTel.LogoutVESP

22

VTel.MakeCall

23

VTel.Ping

62 VTel Automation Server Programmer Guide

Response and event codes

Code

Response or Error

24

VTel.Ready

48

VTel.ReadyOverride

45

VTel.ReadyPhoneset

25

VTel.Release [an obsolete command (replaced by Terminate())]

26

VTel.ResetPhones

43

VTel.RestartServer

56

VTel.SendDefinityAux

57

VTel.SendDefinityLogout

58

VTel.SendDTMFtones

53

VTel.SwapHeld

27

VTel.Terminate

28

VTel.Transfer

29

VTel.TransferCancel

30

VTel.TransferComplete

31

VTel.TransferInit

32

VTel.VDUCreate

33

VTel.VDUFindVDU

41

VTel.VDUGetActive

34

VTel.VDUGetData

35

VTel.VDUGetOneValue

36

VTel.VDUGetValues

37

VTel.VDUSetCurrent

38

VTel.VDUSetValues

39

VTel.WrapUp

49

VTel.WrapUpOverride

41

VTel.VDUGetActive

42

VTel.Drop

Issue 2.1 August 2003

63

API Methods: Relationships

Note:

Code

Response or Error

43

VTel.RestartServer

44

VTel.BusyPhoneset

45

VTel.ReadyPhoneset

46

VTel.LogEntry

47

VTel.BusyOverride

48

VTel.ReadyOverride

49

VTel.WrapUpOverride

50

VTel.LoginTelephony

51

VTel.LogoutTelephony

52

VTel.LogoutVESP

53

VTel.SwapHeld

56

VTel.SendDefinityAux

57

VTel.SendDefinityLogout

58

VTel.SendDTMFtones

59

VTel.VDUGetCurrent Note: GuiCallHistory and GuiLogin are not included as part of the Automation API. However, these commands are part of VTel, for use with the VTel-specific GUI. Since this command is theoretically accessible through the Automation general methods (see General methods on page 50), this response has been included for completeness.

64 VTel Automation Server Programmer Guide

Response and event codes

Event codes The following table describes each of the values returned by GetEventCode(). For an example, see Programming example: implementing a softphone on page 33. For descriptions of VTel events, see VTel Programmer Guide. Code

Event or Error

-1

Invalid event handle

-2

Event queue overrun

-3

Unrecognized event (use GetEventName())

0

VTel.Announcement

1

VTel.Busy

37

VTel.BusyOutbound

2

VTel.BusyPreset

28

VTel.Conference

33

VTel.ConferenceCancel

32

VTel.ConferenceComplete

31

VTel.ConferenceInit

3

VTel.Connect

4

VTel.Disconnect

5

VTel.Drop

6

VTel.Exit

7

VTel.InCall

8

VTel.IncomingCall

9

VTel.Login

34

VTel.LoginTelephony

10

VTel.Logout

35

VTel.LogoutTelephony

36

VTel.LogoutVESP

11

VTel.MakeCall

12

VTel.OnHold

Issue 2.1 August 2003

65

API Methods: Relationships

Code

Event or Error

13

VTel.Ready

14

VTel.ReadyPreset

29

VTel.ResetPhones

15

VTel.RingOutbound

16

VTel.ServerFailed

30

VTel.ServerRestart

17

VTel.TerminateConnection

18

VTel.Transfer

19

VTel.TransferCancel

20

VTel.TransferComplete

21

VTel.TransferInit

22

VTel.VDUChange

23

VTel.VDUCurrent

24

VTel.VDUTerminated

25

VTel.WrapUp

26

VTel.WrapUpPreset

28

VTel.Conference

29

VTel.ResetPhones

30

VTel.ServerRestart

31

VTel.ConferenceInit

32

VTel.ConferenceComplete

33

VTel.ConferenceCancel

34

VTel.LoginTelephony

35

VTel.LogoutTelephony

36

VTel.LogoutVESP

37

VTel.BusyOutbound

66 VTel Automation Server Programmer Guide

Summary of methods

Chapter 6: API Methods: Descriptions This section describes all of the Automation Server methods. They are presented in alphabetical order. Relationships among the methods are discussed in API Methods: Relationships on page 49. This section includes the following topics: ●

Summary of methods on page 67

●

Methods on page 75

Summary of methods The following table lists the Automation Server methods in alphabetical order with a brief description: Name

Description

Answer

Answer a call (asynchronous)

AnswerSynch

Answer a call (synchronous)

Busy

Make a phone number Busy (asynchronous)

BusyOverride

Change the current preset to Busy (asynchronous)

BusyOverrideSynch

Change the current preset to Busy (synchronous)

BusyPhoneset

Make a phoneset Busy (asynchronous)

BusyPhonesetSynch

Make a phoneset Busy (synchronous)

BusySynch

Make a phone number Busy (synchronous)

ChangePassword

Change the Avaya Computer Telephony Server (Avaya TS) password for the current user (asynchronous)

Issue 2.1 August 2003

67

API Methods: Descriptions

Name

Description

ChangeBusyReasonCode

Allow agents to change the aux work reason code while remaining in the Busy state

ConferenceCancel

Cancel a conference (asynchronous)

ConferenceCancelSynch

Cancel a conference (synchronous)

ConferenceComplete

Establish an n-way conference (asynchronous)

ConferenceCompleteSynch

Establish an n-way conference (synchronous)

ConferenceInit

Begin a conference call (asynchronous)

ConferenceInitSynch

Begin a conference call (synchronous)

Drop

Drop a party from a conference call (asynchronous)

DropSynch

Drop a party from a conference call (synchronous)

Exit

Direct VTel to terminate (asynchronous)

ExitSynch

Direct VTel to terminate (synchronous)

FreeAllEvents

Deallocate contents of event queue

FreeAllResponses

Deallocate contents of response queue

FreeEvent

Deallocate a specific event

FreeResponse

Deallocate a specific response

GetEventArg

Return value associated with ArgumentName

GetEventCode

Return event code of specified event

GetEventCount

Return number of events queued

GetEventName

Return name of specified event

GetEventString

Return string representation of specified event

GetGetInfoResponse

Assign response's first argument to SequenceOfCouples, if handle matches

GetGetPhoneInfoResponse

Assign response's second argument to SequenceOfCouples, if handle matches

GetInfo

Get general information about the current session (asynchronous)

68 VTel Automation Server Programmer Guide

Summary of methods

Name

Description

GetInfoSynch

Get general information about the current session (synchronous)

GetLastResponseDetail

Return error information for last synchronous request that failed

GetMakeCallResponse

Assign response's third argument to VduID, if handle matches

GetPhoneInfo

Get general information about the default phone (asynchronous)

GetPhoneInfoSynch

Get general information about the default phone (synchronous)

GetResponseArg

Return argument at specified position in specified response

GetResponseCode

Return response code of specified response

GetResponseCount

Return number of responses queued

GetResponseDetail

Return error information for specified response

GetResponseName

Return name of specified response

GetResponseStatus

Return TRUE if exception argument fields are empty

GetResponseString

Assign string of specified response to OutResponseString

GetVDUCreateResponse

Assign response's second argument to VduID, if handle matches

GetVDUFindVDUResponse

Assign response's second argument to SequenceOfStrings, if handle matches

GetVDUGetActiveResponse

Assign response's first argument to SequenceOfStrings, if handle matches

GetVDUGetCurrentResponse

Assign response’s first argument to VduID, if handle matches

GetVDUGetDataResponse

Assign response's second argument to SequenceOfCouples, if handle matches

GetVDUGetOneValueResponse

Assign response's third argument to Value, if handle matches

GetVDUGetValuesResponse

Assign response's second argument to SequenceOfCouples, if handle matches

Issue 2.1 August 2003

69

API Methods: Descriptions

Name

Description

Hangup

Hang up the phone and the EDU remains (asynchronous)

HangupSynch

Hang up the phone and the EDU remains (synchronous)

Hold

Place an active call on hold (asynchronous)

HoldReconnect

Remove the hold state for a current call and make it active (asynchronous)

HoldReconnectSynch

Remove the hold state for a current call and make it active (synchronous)

HoldSynch

Place an active call on hold (synchronous)

LogEntry

Add an entry to the VTel log file (asynchronous)

LogEntrySynch

Add an entry to the VTel log file (synchronous)

Login

Log user into Avaya TS and assign to the user's phone (asynchronous)

LoginACD

Log user into Avaya TS as an ACD phone (asynchronous)

LoginACDSynch

Log user into Avaya TS as an ACD phone (synchronous)

LoginSynch

Log user into Avaya TS and assign to the user's phone (synchronous)

LoginTelephony

Log user into Telephony and EDU Servers only, assigning to the user's phone (asynchronous)

LoginTelephonySynch

Log user into Telephony and EDU Servers only, assigning to the user's phone (synchronous)

LoginVESP

Log user into Avaya TS only; no phone access through VTel (asynchronous)

LoginVESPSynch

Log user into Avaya TS only; no phone access through VTel (synchronous)

Logout

Log user out of Avaya TS, deassigning the user's phone (asynchronous)

LogoutSynch

Log user out of Avaya TS, deassigning the user's phone (synchronous)

70 VTel Automation Server Programmer Guide

Summary of methods

Name

Description

LogoutTelephony

Log user out of Telephony and EDU Servers only, deassigning user's phone (asynchronous)

LogoutTelephonySynch

Log user out of Telephony and EDU Servers only, deassigning user's phone (synchronous)

LogoutVESP

Log user out of Avaya TS only, does not deassign user's phone (asynchronous)

LogoutVESPSynch

Log user out of Avaya TS only, does not deassign user's phone (synchronous)

MakeCall

Dial a number and return a VDUID (asynchronous)

MakeCallSynch

Dial a number and return a VDUID (synchronous)

MakeRequest

Post a request to VTel (asynchronous)

MakeRequestSynch

Post a request to VTel (synchronous)

PeekEvent

Assign handle of first event in queue to OutEventHandle

PeekResponse

Assign handle of first response in queue to OutResponseHandle

Ping

Test the connection from an external application (asynchronous)

PingSynch

Test the connection from an external application (synchronous)

Ready

Set a phone to the Ready state (asynchronous)

ReadyOverride

Change the current preset to Ready (asynchronous)

ReadyOverrideSynch

Change the current preset to Ready (synchronous)

ReadyPhoneset

Set a phoneset to the Ready state (asynchronous)

ReadyPhonesetSynch

Set a phoneset to the Ready state (synchronous)

ReadySynch

Set a phone to the Ready state (synchronous)

ResetPhones

Release all calls and set VTel to a neutral state (asynchronous)

Issue 2.1 August 2003

71

API Methods: Descriptions

Name

Description

ResetPhonesSynch

Release all calls and set VTel to a neutral state (synchronous)

RestartServer

Attempt to restart the specified server (asynchronous)

RestartServerSynch

Attempt to restart the specified server (synchronous)

Rona

Return a VDU on no answer to the Telephony Server.

SendDefinityAux

Put agent in Busy state and sends Aux code to switch (asynchronous)

SendDefinityAuxSynch

Put agent in Busy state and sends Aux code to switch (synchronous)

SendDefinityLogout

Log out agent and sends Logout code to switch (asynchronous)

SendDefinityLogoutSynch

Log out agent and sends Logout code to switch (synchronous)

SendDTMFtones

Send tones to switch (asynchronous)

SendDTMFtonesSynch

Send tones to switch (synchronous)

SeqCoupleCount

Return the number of couples in the sequence

SeqCoupleCreate

Create and return an empty sequence of couples

SeqCoupleGet

Return the value associated with Attribute

SeqCoupleGetAttrib

Return the name of a name/value pair

SeqCoupleGetVal

Return the value of a name/value pair

SeqCoupleLimit

Limit the number of returned items

SeqCoupleSet

Set a name/value pair

SeqStringAdd

Add String to the end of the sequence

SeqStringCount

Return number of strings in the sequence

SeqStringCreate

Create and return an empty sequence of strings

SeqStringGet

Return string at the specified position in the sequence

SeqStringLimit

Limit the number of returned items

72 VTel Automation Server Programmer Guide

Summary of methods

Name

Description

SetAutoIn

Enable/disable the VTel.ini AutoIn parameter asynchronously

SetAutoInSynch

Enable/disable the VTel.ini AutoIn parameter synchronously

SupressEvents

Disable/re-enable queuing of incoming events

SupressResponses

Disable/re-enable queuing of incoming responses

SwapHeld

Toggle between a newly added call and call(s) on hold (asynchronous)

SwapHeldSynch

Toggle between a newly added call and call(s) on hold (synchronous)

Terminate

Hang up a call and release the EDU (asynchronous)

TerminateSynch

Hang up a call and release the EDU (synchronous)

Transfer

Blind transfer (asynchronous)

TransferCancel

Cancel a consultative transfer (asynchronous)

TransferCancelSynch

Cancel a consultative transfer (synchronous)

TransferComplete

Finish a consultative transfer (asynchronous)

TransferCompleteSynch

Finish a consultative transfer (synchronous)

TransferInit

Begin a consultative transfer (asynchronous)

TransferInitSynch

Begin a consultative transfer (synchronous)

TransferSynch

Blind transfer (synchronous)

VDUCreate

Create a new EDU and have it monitored by VTel (asynchronous)

VDUCreateSynch

Create a new EDU and have it monitored by VTel (synchronous)

VDUFindVDU

Find all EDUs that match search criteria (asynchronous)

VDUFindVDUSynch

Find all EDUs that match search criteria (synchronous)

VDUGetActive

Get a list of all EDUs active in VTel (asynchronous)

Issue 2.1 August 2003

73

API Methods: Descriptions

Name

Description

VDUGetActiveSynch

Get a list of all EDUs active in VTel (synchronous)

VDUGetCurrent

Get the current EDU in focus (asynchronous)

VDUGetCurrentSynch

Get the current EDU in focus (synchronous)

VDUGetData

Get all data from any EDU (asynchronous)

VDUGetDataSynch

Get all data from any EDU (synchronous)

VDUGetOneValue

Return one value from a EDU in use (asynchronous)

VDUGetOneValueSynch

Return one value from a EDU in use (synchronous)

VDUGetValues

Return multiple values from an EDU in use (asynchronous)

VDUGetValuesSynch

Return multiple values from an EDU in use (synchronous)

VDUSetCurrent

Set the "current" EDUID context, notifying any GUI (asynchronous)

VDUSetCurrentSynch

Set the "current" EDUID context, notifying any GUI (synchronous)

VDUSetValues

Set multiple values in the EDU (asynchronous)

VDUSetValuesSynch

Set multiple values in the EDU (synchronous)

WaitForResponse

Wait for specified response

WrapUp

Hang up the call, entering a WrapUp state (asynchronous)

WrapUpOverride

Change the current preset to WrapUp (asynchronous)

WrapUpOverrideSynch

Change the current preset to WrapUp (synchronous)

WrapUpSynch

Hang up the call, entering a WrapUp state (synchronous)

74 VTel Automation Server Programmer Guide

Methods

Methods Answer Syntax

Description

: Language

Syntax

IDL

long Answer( in string VduID )

Visual C++

long Answer( LPCTSTR VduID )

Visual Basic

Answer( ByVal VduID As String ) As Long

Issues the VTel.Answer request asynchronously. Answers an incoming call. This is required only if neither the telephone switch nor VTel are in auto-answer mode. A previous incoming call event will have provided the VDUID to use here. If the call has already been answered, this is harmless and without error.

Input Parameters

Name

Description

VduID

The VDUID corresponding to the incoming call

Output Parameters

None.

Return Value

You can use the returned handle to process the response as soon as it is available. In this case, you will need to call WaitForResponse() to ensure that the response has arrived before invoking any response processing methods. You will most likely find it more convenient to process the response elsewhere, in a timer or idle function. Response processing functions are described in Response processing methods on page 57.

Issue 2.1 August 2003

75

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.Answer( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy long CString . . . ResponseHandle

VTel; ResponseHandle; VduID;

= VTel.Answer( VduID );

AnswerSynch Syntax

Description

Language

Syntax

IDL

BOOL AnswerSynch( in string VduID )

Visual C++

BOOL AnswerSynch( LPCTSTR VduID )

Visual Basic

AnswerSynch( ByVal VduID As String ) As Boolean

Issues the VTel.Answer request synchronously. Answers an incoming call. This is required only if neither the telephone switch nor VTel are in auto-answer mode. A previous incoming call event will have provided the VDUID to use here. If the call has already been answered, this is harmless and without error.

Input Parameters

Output Parameters

Name

Description

VduID

The VDUID corresponding to the incoming call.

None.

76 VTel Automation Server Programmer Guide

Methods

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.AnswerSynch( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; . . . Status = VTel.AnswerSynch( VduID );

Busy Syntax

Description

Language

Syntax

IDL

long Busy( in string PhoneNumber )

Visual C++

long Busy( LPCTSTR PhoneNumber )

Visual Basic

Busy( ByVal PhoneNumber As String ) As Long

Issue the VTel.Busy request asynchronously. If not in an active ACD call, this sets a phone to the busy state. From within an ACD call, it may either preset the busy state or hang up the call, placing the phone in the busy state. This method is dependent on the telephone switch and the type of phone assigned. Refer to the IDL chapter of your Telephony Services manual. This method does not typically affect incoming calls that are not processed through a queue.

Issue 2.1 August 2003

77

API Methods: Descriptions

Input Parameters

Name

Definition

PhoneNumber

Dialable number or null (default phone).

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.Busy( PhoneNumber ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString PhoneNumber; . . . ResponseHandle = VTel.Busy( PhoneNumber );

BusyOverride Syntax

Description

Language

Syntax

IDL

long BusyOverride( in string PhoneNumber )

Visual C++

long BusyOverride( LPCTSTR PhoneNumber )

Visual Basic

BusyOverride( ByVal PhoneNumber As String ) As Long

Issue the VTel.BusyOverride request asynchronously. If in call, and presets are on, changes the current preset to Busy and disallows any attempts to change the preset for the remainder of the call, unless by means of another override command (ReadyOverride, WrapUpOverride).

78 VTel Automation Server Programmer Guide

Methods

If not in call, or presets are not on, behaves like the Busy command. This method is dependent on the telephone switch and the type of phone assigned. Refer to the IDL chapter of your Telephony Services manual. Input Parameters

Name

Description

PhoneNumber

Dialable number or null (default phone).

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.BusyOverride( PhoneNumber ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString PhoneNumber; . . . ResponseHandle = VTel.BusyOverride( PhoneNumber );

BusyOverrideSynch Syntax Language

Syntax

IDL

BOOL BusyOverrideSynch( in string PhoneNumber )

Visual C++

BOOL BusyOverrideSynch( LPCTSTR PhoneNumber )

Visual Basic

BusyOverrideSynch( ByVal PhoneNumber As String ) As Boolean

Issue 2.1 August 2003

79

API Methods: Descriptions

Description

Issue the VTel.BusyOverride request synchronously. If in call, and presets are on, changes the current preset to Busy and disallows any attempts to change the preset for the remainder of the call, unless by means of another override command (ReadyOverride, WrapUpOverride). If not in call, or presets are not on, behaves like the BusySynch command. This method is dependent on the telephone switch and the type of phone assigned. Refer to the IDL chapter of your Telephony Services manual.

Input Parameters

Name

Definition

PhoneNumber

Dialable number or null (default phone).

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.BusyOverrideSynch( PhoneNumber ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString PhoneNumber; . . . Status = VTel.BusyOverrideSynch( PhoneNumber );

80 VTel Automation Server Programmer Guide

Methods

BusyPhoneset Syntax

Description

Language

Description

IDL

long BusyPhoneset( )

Visual C++

long BusyPhoneset( )

Visual Basic

BusyPhoneset( ) As Long

Issue the VTel.BusyPhoneset request asynchronously. If there are no active calls, this sets the entire phoneset to the Busy state. If there are active calls, the result is switch dependent (see the documentation for your telephone switch). This method is dependent on the telephone switch. Refer to the IDL chapter of your Telephony Services manual to determine availability.

Input Parameters

None.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.BusyPhoneset( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; . . . ResponseHandle = VTel.BusyPhoneset( );

Issue 2.1 August 2003

81

API Methods: Descriptions

BusyPhonesetSynch Syntax

Description

Language

Syntax

IDL

BOOL BusyPhonesetSynch( )

Visual C++

BOOL BusyPhonesetSynch( )

Visual Basic

BusyPhonesetSynch( ) As Boolean

Issue the VTel.BusyPhoneset request synchronously. If there are no active calls, this sets the entire phoneset to the Busy state. If there are active calls, the result is switch dependent (see the documentation for your telephone switch). This method is dependent on the telephone switch. Refer to the IDL chapter of your Telephony Services manual to determine availability.

Input Parameters

None.

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.BusyPhonesetSynch( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; . . . Status = VTel.BusyPhonesetSynch( );

82 VTel Automation Server Programmer Guide

Methods

BusySynch Syntax

Description

Language

Syntax

IDL

BOOL BusySynch( in string PhoneNumber )

Visual C++

BOOL BusySynch( LPCTSTR PhoneNumber )

Visual Basic

BusySynch( ByVal PhoneNumber As String ) As Boolean

Issue the VTel.Busy request synchronously. If not in an active ACD call, this sets a phone to the busy state. From within an ACD call, it may either preset the busy state or hang up the call, placing the phone in the busy state. This method is dependent on the telephone switch and the type of phone assigned. Refer to the IDL chapter of your Telephony Services manual. This method does not typically affect incoming calls that are not processed through a queue.

Input Parameters

Name

Description

PhoneNumber

Dialable number or null (default phone)

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.BusySynch( PhoneNumber ) Mutex = False

Issue 2.1 August 2003

83

API Methods: Descriptions

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString PhoneNumber; . . . Status = VTel.BusySynch( PhoneNumber );

ChangePassword Syntax

Description

Language

Syntax

IDL

long ChangePassword( in string OldPassword, in string NewPassword )

Visual C++

long ChangePassword( LPCTSTR OldPassword LPCTSTR NewPassword )

Visual Basic

ChangePassword( ByVal OldPassword As String, ByVal NewPassword As String ) As Long

Issue the VTel.ChangePassword request asynchronously. Changes the current Avaya TS password. Some configurations may not permit an empty or blank password.

Input Parameters

Name

Description

OldPassword

The currently used Avaya TS password.

NewPassword

The new password, or empty for no password.

Output Parameters

None.

Return Value

Returns handle to the expected response.

84 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim OldPassword As String Dim NewPassword As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.ChangePassword( OldPassword, NewPassword ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString OldPassword; CString NewPassword; . . . ResponseHandle = VTel.ChangePassword( OldPassword, NewPassword );

ChangePasswordSynch Syntax

Description

Language

Syntax

IDL

BOOL ChangePasswordSynch( in string OldPassword, in string NewPassword )

Visual C++

BOOL ChangePasswordSynch( LPCTSTR OldPassword, LPCTSTR NewPassword )

Visual Basic

ChangePasswordSynch(ByValOldPasswordAsString, ByVal NewPassword As String ) As Boolean

Issue the VTel.ChangePassword request synchronously. Changes the current Avaya TS password. Some configurations may not permit an empty or blank password.

Input Parameters

Name

Description

OldPassword

The currently used Avaya TS password.

NewPassword

The new password, or empty for no password.

Issue 2.1 August 2003

85

API Methods: Descriptions

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim OldPassword As String Dim NewPassword As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.ChangePasswordSynch( OldPassword, NewPassword ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString OldPassword; CString NewPassword; . . . Status = VTel.ChangePasswordSynch( OldPassword, NewPassword );

ChangeBusyReasonCode Syntax

Description

Language

Syntax

IDL

long ChangeBusyReasonCode ( in string ReasonCode )

Visual C++

long ChangeBusyReasonCode ( LPCTSTR ReasonCode )

Visual Basic

ChangeBusyReasonCode ( ByVal ReasonCode As String ) As Long

Issue a VTel.ChangeBusyReasonCode request. Puts the agent into a different Busy (Auxiliary Work) state than previously recorded without requiring the agent to exit and re-enter the Busy state.

86 VTel Automation Server Programmer Guide

Methods

Input Parameters

Name

Description

ReasonCode

The single digit (0-9) Aux reason code.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim ReasonCode As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.ChangeBusyReasonCode( ReasonCode ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString ReasonCode; . . . ResponseHandle = VTel.ChangeBusyReasonCode ( ReasonCode );

ConferenceCancel Syntax

Description

Language

Syntax

IDL

long ConferenceCancel( in string VduID )

Visual C++

long ConferenceCancel( LPCTSTR VduID )

Visual Basic

ConferenceCancel( ByVal VduID As String ) As Long

Issue the VTel.ConferenceCancel request asynchronously. Following a ConferenceInit, this will terminate the call made to the additional party. The previous conversation(s) are taken off hold.

Issue 2.1 August 2003

87

API Methods: Descriptions

Input Parameters

Name

Description

VduID

The VDUID of a current call in the ConferenceInit state.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.ConferenceCancel( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; . . . ResponseHandle = VTel.ConferenceCancel( VduID );

ConferenceCancelSynch Syntax

Description

Language

Syntax

IDL

BOOL ConferenceCancelSynch( in string VduID )

Visual C++

BOOL ConferenceCancelSynch( LPCTSTR VduID )

Visual Basic

ConferenceCancelSynch( ByVal VduID As String ) As Boolean

Issue the VTel.ConferenceCancel request synchronously. Following a ConferenceInit, this will terminate the call made to the additional party. The previous conversation(s) are taken off hold.

88 VTel Automation Server Programmer Guide

Methods

Input Parameters

Name

Description

VduID

The VDUID of a current call in the ConferenceInit state.

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.ConferenceCancelSynch( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; . . . Status = VTel.ConferenceCancelSynch( VduID );

ConferenceComplete Syntax Language

Syntax

IDL

long ConferenceComplete( in string VduID )

Visual C++

long ConferenceComplete( LPCTSTR VduID )

Visual Basic

ConferenceComplete( ByVal VduID As String ) As Long

Issue 2.1 August 2003

89

API Methods: Descriptions

Description

Input Parameters

Issue the VTel.ConferenceComplete request asynchronously. Following a ConferenceInit, this retains the new conversation with the additional party, while the previous conversation(s) are taken off hold so that all connected parties can speak together.

Name

Description

VduID

The VDUID of a current call in the ConferenceInit state.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.ConferenceComplete( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; . . . ResponseHandle = VTel.ConferenceComplete( VduID );

ConferenceCompleteSynch Syntax Language

Syntax

IDL

BOOL ConferenceCompleteSynch( in string VduID )

Visual C++

BOOL ConferenceCompleteSynch( LPCTSTR VduID )

Visual Basic

ConferenceCompleteSynch( ByVal VduID As String ) As Boolean

90 VTel Automation Server Programmer Guide

Methods

Description

Input Parameters

Issue the VTel.ConferenceComplete request synchronously. Following a ConferenceInit, this retains the new conversation with the additional party, while the previous conversation(s) are taken off hold so that all connected parties can speak together.

Name

Description

VduID

The VDUID of a current call in the ConferenceInit state.

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.ConferenceCompleteSynch( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; . . . Status = VTel.ConferenceCompleteSynch( VduID );

Issue 2.1 August 2003

91

API Methods: Descriptions

ConferenceInit Syntax

Description

Input Parameters

Language

Syntax

IDL

long ConferenceInit( in string VduID, in string PhoneNumber )

Visual C++

long ConferenceInit( LPCTSTR VduID, LPCTSTR PhoneNumber )

Visual Basic

ConferenceInit( ByVal VduID As String, ByVal PhoneNumber As String ) As Long

Issue the VTel.ConferenceInit request asynchronously. Initiates a conference with an additional party. All previous conversations are placed on hold, and a call is made to the new party.

Name

Description

VduID

The VDUID of a current call

PhoneNumber

Dialable number, UserID, or ACD queue of the phone that is to be conferenced in.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Dim DestPhone As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.ConferenceInit( VduID, DestPhone ) Mutex = False

92 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; CString DestPhone; . . . ResponseHandle = VTel.ConferenceInit( VduID, DestPhone );

ConferenceInitSynch Syntax

Description

Input Parameters

Language

Syntax

IDL

BOOL ConferenceInitSynch( in string VduID, in string PhoneNumber )

Visual C++

BOOL ConferenceInitSynch( LPCTSTR VduID, LPCTSTR PhoneNumber )

Visual Basic

ConferenceInitSynch( ByVal VduID As String, ByVal PhoneNumber As String ) As Boolean

Issue the VTel.ConferenceInit request synchronously. Initiates a conference with an additional party. All previous conversations are placed on hold, and a call is made to the new party.

Name

Description

VduID

The VDUID of a current call.

PhoneNumber

Dialable number, UserID, or ACD queue of the phone that is to be conferenced in.

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Issue 2.1 August 2003

93

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Dim DestPhone As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.ConferenceInitSynch( VduID, DestPhone ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; CString DestPhone; . . . Status = VTel.ConferenceInitSynch( VduID, DestPhone );

Drop Syntax

Description

Language

Syntax

IDL

long Drop( in string VduID, in string PhoneNumber )

Visual C++

long Drop( LPCTSTR VduID, LPCTSTR PhoneNumber )

Visual Basic

Drop( ByVal VduID As String, ByVal PhoneNumber As String ) As Long

Issue the VTel.Drop request asynchronously. Drops a party from a conference call. If only two parties are in the call, the call is ended and both parties are disconnected. Attempting to drop a party that is no longer present returns an error. Attempting to drop yourself returns an error. This method is dependent on the telephone switch and the type of phone assigned. Refer to the IDL chapter of your Telephony Services manual to determine availability.

94 VTel Automation Server Programmer Guide

Methods

Input Parameters

Name

Description

VduID

The VDUID of a current conference call.

PhoneNumber

The dialable number, UserID, or ACD queue of the party to be dropped.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.Drop( VduID, PhoneNumber ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; CString PhoneNumber; . . . ResponseHandle = VTel.Drop( VduID, PhoneNumber );

Issue 2.1 August 2003

95

API Methods: Descriptions

DropSynch Syntax

Description

Language

Syntax

IDL

BOOL DropSynch( in string VduID, in string PhoneNumber )

Visual C++

BOOL DropSynch( LPCTSTR VduID, LPCTSTR PhoneNumber )

Visual Basic

DropSynch( ByVal VduID As String, ByVal PhoneNumber As String) As Boolean

Issue the VTel.Drop request synchronously. Drops a party from a conference call. If only two parties are in the call, the call is ended and both parties are disconnected. Attempting to drop a party that is no longer present returns an error. Attempting to drop yourself returns an error. This method is dependent on the telephone switch and the type of phone assigned. Refer to the IDL chapter of your Telephony Services manual to determine availability.

Input Parameters

Name

Description

VduID

The VDUID of a current conference call.

PhoneNumber

The dialable number, UserID, or ACD queue of the party to be dropped.

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

96 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.DropSynch( VduID, PhoneNumber ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; CString PhoneNumber; . . . Status = VTel.DropSynch( VduID, PhoneNumber );

Exit Syntax

Description

Language

Syntax

IDL

long Exit( )

Visual C++

long Exit( )

Visual Basic

Exit( ) As Long

Issue the VTel.Exit request asynchronously. Causes the VTel application to end. This will be rejected if there is a current login in effect.

Input Parameters

None.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Issue 2.1 August 2003

97

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.Exit( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; . . . ResponseHandle = VTel.Exit( );

ExitSynch Syntax

Description

Language

Syntax

IDL

BOOL ExitSynch( )

Visual C++

BOOL ExitSynch( )

Visual Basic

ExitSynch( ) As Boolean

Issue the VTel.Exit request synchronously. Causes the VTel application to end. This will be rejected if there is a current login in effect.

Input Parameters

None.

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

98 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.ExitSynch( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; . . . Status = VTel.ExitSynch( );

FreeAllEvents Syntax

Description

Language

Syntax

IDL

long FreeAllEvents( )

Visual C++

long FreeAllEvents( )

Visual Basic

FreeAllEvents( ) As Long

Deallocates the contents of the event queue. For deallocating a specific event, use FreeEvent(). Events consume server resources. You must free them when no longer required. Failure to do so will not imperil the server; however, it will quickly result in an event queue overflow. Should this happen, PeekEvent() will return an error code of 2, and your application should terminate. For additional information on event codes, see Event codes on page 65.

Input Parameters

None.

Output Parameters

None.

Return Value

Returns the number of events deallocated.

Issue 2.1 August 2003

99

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Dim EventsFreed As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True EventsFreed = VTel.FreeAllEvents( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long EventsFreed; . . . EventsFreed = VTel.FreeAllEvents();

FreeAllResponses Syntax

Description

Language

Syntax

IDL

long FreeAllResponses( )

Visual C++

long FreeAllResponses( )

Visual Basic

FreeAllResponses( ) As Long

Deallocates the contents of the response queue. For deallocating a specific response, use FreeResponse(). Responses consume server resources. You must free them when no longer required. Failure to do so will not imperil the server; however, it will quickly result in a response queue overflow. Should this happen, PeekResponse() will return an error code of -2, and your application should terminate. For additional information on response codes, see Response codes on page 61.

Input Parameters

None.

Output Parameters

None.

Return Value

Returns the number of responses deallocated.

100 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Dim VTel As Object Dim ResponsesFreed As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponsesFreed = VTel.FreeAllResponses( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponsesFreed; . . . ResponsesFreed = VTel.FreeAllResponses();

FreeEvent Syntax

Description

Language

Syntax

IDL

BOOL FreeEvent( in long EventHandle )

Visual C++

BOOL FreeEvent( long EventHandle )

Visual Basic

FreeEvent( ByVal EventHandle As Long ) As Boolean

Deallocates a specific event. For deallocating the entire contents of the event queue, use FreeAllEvents(). Events consume server resources. You must free them when no longer required. Failure to do so will not imperil the server; however, it will quickly result in an event queue overflow. Should this happen, PeekEvent() will return an error code of 2, and your application should terminate. For additional information on event codes, see Event codes on page 65.

Input Parameters

Name

Description

EventHandle

An event handle previously obtained from PeekEvent().

Issue 2.1 August 2003

101

API Methods: Descriptions

Output Parameters

None.

Return Value

Returns FALSE if event not found.

Visual Basic Example

' Handle incoming events. Private Sub Response_Timer() Dim EventHandle As Long Dim EventCode As Long Dim VduID As String If Mutex = True then Exit Sub ' Do we have a connection to the server? If (VTelConnected = True ) Then ' Handle all currently queued events While ( (VTelConnected = True) And _ (VTel.PeekEvent(EventHandle) = True) ) ' Take action based on event code EventCode = VTel.GetEventCode(EventHandle) Select Case EventCode ' Connect Case 3: ' Store away the new VDUID for hang up or anyone else ' who is interested VduID = VTel.GetEventArg(EventHandle, "vdu_id") ' Disconnect Case 4: . . . ' Exit Case 6: ' Quit ' Call any shut-down code here VTel = Nothing End Select ' Was VTel terminated above? If VTelConnected = True Then ' No, clean up event VTel.FreeEvent EventHandle End If Wend End If End Sub

102 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

// OnTimer() or OnIdle() // Handle incoming events. // long EventHandle; // Do we have a connection to the server? if (m_VTel) { // Handle all currently queued events while (m_VTel && m_VTel->PeekEvent(&EventHandle)) { // Take action based on event code switch ( m_VTel->GetEventCode(EventHandle) ) { // Connect case 3: // Store away the new VDUID for hang up or anyone else // who is interested m_vduID = m_VTel->GetEventArg(EventHandle, "vdu_id"); break; // Disconnect case 4: . . . break; // Exit case 6: // Quit PostQuitMessage(0); delete m_VTel; m_VTel = 0; break; } // Was m_VTel deleted above? if (m_VTel) { // No, clean up event VERIFY( m_VTel->FreeEvent(EventHandle) ); } . . .

Issue 2.1 August 2003

103

API Methods: Descriptions

FreeResponse Syntax

Description

Language

Syntax

IDL

BOOL FreeResponse( in long ResponseHandle )

Visual C++

BOOL FreeResponse( long ResponseHandle )

Visual Basic

FreeResponse( ByVal ResponseHandle As Long ) As Boolean

Deallocates a specific response. For deallocating the entire contents of the response queue, use FreeAllResponses(). Responses consume server resources. You must free them when no longer required. Failure to do so will not imperil the server; however, it will quickly result in a response queue overflow. Should this happen, PeekResponse() will return an error code of -2, and your application should terminate. For additional information on response codes, see Response codes on page 61.

Input Parameters

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch().

Output Parameters

None.

Return Value

Returns FALSE if response not found.

Visual Basic Example

Private Sub PollingTimer_Timer() Dim ResponseName As String Dim ResponseExists As Boolean Dim ResponseHandle As Long ' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then

104 VTel Automation Server Programmer Guide

Methods

' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.MakeCall": ' Response from MakeCall request, display new VDUID VTel.GetMakeCallResponse ResponseHandle, VduID VduIDTextBox.Text = VduID Case "VTel.Logout": . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

Visual C++ Example

// OnTimer() or OnIdle() long

NextResponse;

// Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case 22: // MakeCall. Use specific response parsing routine to // obtain the associated VDUID. CString VduID; if ( VTel.GetMakeCallResponse(ResponseHandle, VduID) ) { // Response was OK.Do something with this VDUID such as // add it to a collection of active calls. . . . } break;

Issue 2.1 August 2003

105

API Methods: Descriptions

default: // Not handling any other responses } // We are done with the response, release resources. VTel.FreeResponse(NextResponse); . . .

GetEventArg Syntax

Description Input Parameters

Language

Syntax

IDL

string GetEventArg( in long EventHandle, in string ArgumentName )

Visual C++

CString GetEventArg( long EventHandle, LPCTSTR ArgumentName )

Visual Basic

GetEventArg( ByVal EventHandle As Long, ByVal ArgumentName As String ) As String

Returns the value associated with the attribute given by ArgumentName, for the specified event.

Name

Description

EventHandle

An event handle previously obtained from PeekEvent().

ArgumentName

The name associated with the desired value.

Output Parameters

None.

Return Value

Returns the empty string (" ") if the event handle is invalid, or if ArgumentName is invalid.

106 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

' Handle incoming events. Private Sub Response_Timer() Dim EventHandle As Long Dim EventCode As Long Dim VduID As String If Mutex = True Then Exit Sub ' Do we have a connection to the server? If VTelConnected = True Then ' Handle all currently queued events While (VTelConnected = True) And (VTel.PeekEvent(EventHandle) = True) ' Take action based on event code EventCode = VTel.GetEventCode(EventHandle) Select Case EventCode ' Connect Case 3: ' Store away the new VDUID for hang up or anyone else ' who is interested VduID = VTel.GetEventArg(EventHandle, "vdu_id") ' Disconnect Case 4: . . . ' Exit Case 6: ' Quit ' Call any shut-down code here VTel = Nothing End Select ' Was VTel terminated above? If VTelConnected = True Then ' No, clean up event VTel.FreeEvent EventHandle End If Wend End If End Sub

Issue 2.1 August 2003

107

API Methods: Descriptions

Visual C++ Example

// OnTimer() or OnIdle() // Handle incoming events. // long EventHandle; // Do we have a connection to the server? if (m_VTel) { // Handle all currently queued events while (m_VTel && m_VTel->PeekEvent(&EventHandle)) { // Take action based on event code switch ( m_VTel->GetEventCode(EventHandle) ) { // Connect case 3: // Store away the new VDUID for hang up or anyone else // who is interested m_vduID = m_VTel->GetEventArg(EventHandle, "vdu_id"); break; // Disconnect case 4: . . . break; // Exit case 6: // Quit PostQuitMessage(0); delete m_VTel; m_VTel = 0; break; } // Was m_VTel deleted above? if (m_VTel) { // No, clean up event VERIFY( m_VTel->FreeEvent(EventHandle) ); } . . .

108 VTel Automation Server Programmer Guide

Methods

GetEventCode Syntax

Description Input Parameters

Language

Syntax

IDL

long GetEventCode( in long EventHandle )

Visual C++

long GetEventCode( long EventHandle )

Visual Basic

GetEventCode( ByVal EventHandle As Long ) As Long

Returns the event code of the specified event.

Name

Description

EventHandle

An event handle previously obtained from PeekEvent()

Output Parameters

None.

Return Value

The event codes are as given in Event codes on page 65.

Visual Basic Example

' Handle incoming events. Private Sub Response_Timer() Dim Dim Dim Dim Dim Dim Dim Dim Dim Dim

EventHandle As Long EventCode As Long EventName As String EventStr As String CallState As String VduID As String SeqCouples As String Ani As String Dnis As String StatusMsg As String

If Mutex = True then Exit Sub ' Do we have a connection to the server? If VTelConnected = True Then ' Handle all currently queued events While (VTelConnected = True) And (VTel.PeekEvent(EventHandle) = True) ' Display the event in our text box EventStr = VTel.GetEventString(EventHandle) EventBox.Text = EventStr

Issue 2.1 August 2003

109

API Methods: Descriptions

' Take action based on event code EventCode = VTel.GetEventCode(EventHandle) Select Case EventCode ' Bad handle Case -1: MsgBox "Internal error- Invalid event handle!" ' Event queue overrun Case -2: MsgBox "Event queue overflow. Please terminate session." ' Unrecognized (newly introduced) event Case -3: EventName = VTel.GetEventName(EventHandle) ' The CallChange event is new, is this it? If EventName = "VTel.CallChange" Then ' Yes. Are we in call? CallState = VTel.GetEventArg(EventHandle, "CallState") If CallState = "InCall" Then ' Yes, display a message such as ' "From 4100 to 5305 (State: In Call)" VduID = VTel.GetEventArg(EventHandle, "vdu_id") VTel.VDUGetValuesSynch(VduID, SeqCouples) Ani = VTel.SeqCoupleGet(SeqCouples, "ani") Dnis = VTel.SeqCoupleGet(SeqCouples, "dnis") StatusMsg = "From " & Ani & " to " & Dnis & _ "(State: In Call)" StatusBox.Text = StatusMsg End If End If ' Connect Case 3: ' Store away the new VDUID for hang up or anyone else ' who is interested VduID = VTel.GetEventArg(EventHandle, "vdu_id") ' Disconnect Case 4: . . . ' Exit Case 6: ' Quit ' Call any shut-down code here VTelConnected = False VTel = Nothing End Select ' Was VTel terminated above? If VTelConnected = True Then

110 VTel Automation Server Programmer Guide

Methods

' No, clean up event VTel.FreeEvent EventHandle End If Wend End If End Sub

Visual C++ Example

// OnTimer() or OnIdle() // Handle incoming events. // long EventHandle; CString EventName; CString EventStr; CString CallState; CString SeqCouples; CString Ani; CString Dnis; CString StatusMsg; // Do we have a connection to the server? if (m_VTel) { // Handle all currently queued events while (m_VTel && m_VTel->PeekEvent(&EventHandle)) { // Display the event in our scrolling event window EventStr = m_VTel->GetEventString(EventHandle); VERIFY( !EventStr.IsEmpty() ); EventStr += "\n"; appendText(EventStr, m_editEvents); // Take action based on event code switch ( m_VTel->GetEventCode(EventHandle) ) { // Bad handle case -1: AfxMessageBox("Internal error- Invalid event handle!"); break; // Event queue overrun case -2: AfxMessageBox("Event queue overflow. Please terminate session."); break; // Unrecognized (newly introduced) event case -3: EventName = m_VTel->GetEventName(EventHandle); // The CallChange event is new, is this it? if (EventName == "VTel.CallChange") { // Yes. Are we in call? CallState = m_VTel->GetEventArg(EventHandle, "CallState");

Issue 2.1 August 2003

111

API Methods: Descriptions

if (CallState == "InCall") { // Yes, display a message such as "From 4100 to 5305 //(State: In // Call)" VduID = m_VTel->GetEventArg(EventHandle, "vdu_id"); VERIFY( m_VTel->VDUGetValuesSynch(VduID, SeqCouples) ); Ani = m_VTel->SeqCoupleGet(SeqCouples, "ani"); Dnis = m_VTel->SeqCoupleGet(SeqCouples, "dnis"); StatusMsg.Format("From %s to %s (State: In Call)", Ani, Dnis); m_editStatus.SetWindowText(StatusMsg); } } break; // Connect case 3: // Store away the new VDUID for hang up or anyone else // who is interested m_vduID = m_VTel->GetEventArg(EventHandle, "vdu_id"); break; // Disconnect case 4: . . . break; // Exit case 6: // Quit PostQuitMessage(0); delete m_VTel; m_VTel = 0; break; } // Was m_VTel deleted above? if (m_VTel) { // No, clean up event VERIFY( m_VTel->FreeEvent(EventHandle) ); . . .

112 VTel Automation Server Programmer Guide

Methods

GetEventCount Syntax Language

Syntax

IDL

long GetEventCount( )

Visual C++

long GetEventCount( )

Visual Basic

GetEventCount( ) As Long

Description

Returns the number of events currently queued.

Input Parameters

None.

Output Parameters

None.

Return Value

The number of pending events.

Visual Basic Example

Dim VTel As Object Dim EventsWaiting As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True EventsWaiting = VTel.GetEventCount( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long EventsWaiting; . . . EventsWaiting = VTel.GetEventCount( );

Issue 2.1 August 2003

113

API Methods: Descriptions

GetEventName Syntax

Description Input Parameters

Language

Syntax

IDL

string GetEventName( in long EventHandle )

Visual C++

CString GetEventName( long EventHandle )

Visual Basic

GetEventName( ByVal EventHandle As Long ) As String

Returns the name of the specified event.

Name

Description

EventHandle

An event handle previously obtained from PeekEvent()

Output Parameters

None.

Return Value

Returns the empty string (" ") if the event handle is invalid.

Visual Basic Example

' Handle incoming events. Private Sub Response_Timer() Dim Dim Dim Dim Dim Dim Dim Dim Dim Dim

EventHandle As Long EventCode As Long EventName As String EventStr As String CallState As String VduID As String SeqCouples As String Ani As String Dnis As String StatusMsg As String

If Mutex = True then Exit Sub ' Do we have a connection to the server? If VTelConnected = True Then ' Handle all currently queued events While (VTelConnected = True) And (VTel.PeekEvent(EventHandle) = True) ' Display the event in our text box EventStr = VTel.GetEventString(EventHandle) EventBox.Text = EventStr

114 VTel Automation Server Programmer Guide

Methods

' Take action based on event code EventCode = VTel.GetEventCode(EventHandle) Select Case EventCode ' Bad handle Case -1: MsgBox "Internal error- Invalid event handle!" ' Event queue overrun Case -2: MsgBox "Event queue overflow. Please terminate session." ' Unrecognized (newly introduced) event Case -3: EventName = VTel.GetEventName(EventHandle) ' The CallChange event is new, is this it? If EventName = "VTel.CallChange" Then ' Yes. Are we in call? CallState = VTel.GetEventArg(EventHandle, "CallState") If CallState = "InCall" Then ' Yes, display a message such as ' "From 4100 to 5305 (State: In Call)" VduID = VTel.GetEventArg(EventHandle, "vdu_id") VTel.VDUGetValuesSynch(VduID, SeqCouples) Ani = VTel.SeqCoupleGet(SeqCouples, "ani") Dnis = VTel.SeqCoupleGet(SeqCouples, "dnis") StatusMsg = "From " & Ani & " to " & Dnis & "(State: In Call)" StatusBox.Text = StatusMsg End If End If ' Connect Case 3: ' Store away the new VDUID for hang up or anyone else ' who is interested VduID = VTel.GetEventArg(EventHandle, "vdu_id") ' Disconnect Case 4: . . . ' Exit Case 6: ' Quit ' Call any shut-down code here VTel = Nothing End Select

Issue 2.1 August 2003

115

API Methods: Descriptions

' Was m_VTel deleted above? If VTelConnected = True Then ' No, clean up event VTel.FreeEvent EventHandle End If Wend End If End Sub

Visual C++ Example

// OnTimer() or OnIdle() // Handle incoming events. // long EventHandle; CString EventName; CString EventStr; CString CallState; CString SeqCouples; CString Ani; CString Dnis; CString StatusMsg; // Do we have a connection to the server? if (m_VTel) { // Handle all currently queued events while (m_VTel && m_VTel->PeekEvent(&EventHandle)) { // Display the event in our scrolling event window EventStr = m_VTel->GetEventString(EventHandle); VERIFY( !EventStr.IsEmpty() ); EventStr += "\n"; appendText(EventStr, m_editEvents); // Take action based on event code switch ( m_VTel->GetEventCode(EventHandle) ) { // Bad handle case -1: AfxMessageBox("Internal error- Invalid event handle!"); break; // Event queue overrun case -2: AfxMessageBox("Event queue overflow. Please terminate session."); break; // Unrecognized (newly introduced) event case -3: EventName = m_VTel->GetEventName(EventHandle);

116 VTel Automation Server Programmer Guide

Methods

// The CallChange event is new, is this it? if (EventName == "VTel.CallChange") { // Yes. Are we in call? CallState = m_VTel->GetEventArg(EventHandle, "CallState"); if (CallState == "InCall") { // Yes, display a message such as "From 4100 to 5305 //(State: InCall)" VduID = m_VTel->GetEventArg(EventHandle, "vdu_id"); VERIFY( m_VTel->VDUGetValuesSynch(VduID, SeqCouples) ); Ani = m_VTel->SeqCoupleGet(SeqCouples, "ani"); Dnis = m_VTel->SeqCoupleGet(SeqCouples, "dnis"); StatusMsg.Format("From %s to %s (State: In Call)", Ani, Dnis); m_editStatus.SetWindowText(StatusMsg); } } break; // Connect case 3: // Store away the new VDUID for hang up or anyone else // who is interested m_vduID = m_VTel->GetEventArg(EventHandle, "vdu_id"); break; // Disconnect case 4: . . . break; // Exit case 6: // Quit PostQuitMessage(0); delete m_VTel; m_VTel = 0; break; } // Was m_VTel deleted above? if (m_VTel) { // No, clean up event VERIFY( m_VTel->FreeEvent(EventHandle) ); } . . .

Issue 2.1 August 2003

117

API Methods: Descriptions

GetEventString Syntax

Description Input Parameters

Language

Syntax

IDL

string GetEventString( in long EventHandle )

Visual C++

CString GetEventString( long EventHandle )

Visual Basic

GetEventString( ByVal EventHandle As Long ) As String

Returns the string representation of the specified event in the queue.

Name

Description

EventHandle

An event handle previously obtained from PeekEvent()

Output Parameters

None.

Return Value

Returns with an empty string if there is no matching event handle.

Visual Basic Example

' Handle incoming events. Dim Dim Dim Dim

EventHandle As Long EventCode As Long EventName As String EventStr As String

' Handle all currently queued events While (VTelConnected = True) And (VTel.PeekEvent(EventHandle) = True) 'Display the event in our text box EventStr = VTel.GetEventString(EventHandle) EventBox.Text = EventStr . . . Wend

118 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

// OnTimer() or OnIdle() // Handle incoming events. // long EventHandle; CString EventStr; // Do we have a connection to the server? if (m_VTel) { // Handle all currently queued events while (m_VTel && m_VTel->PeekEvent(&EventHandle)) { // Display the event in our scrolling event window EventStr = m_VTel->GetEventString(EventHandle); VERIFY( !EventStr.IsEmpty() ); EventStr += "\n"; appendText(EventStr, m_editEvents); // Take action based on event code switch ( m_VTel->GetEventCode(EventHandle) ) { . . .

GetGetInfoResponse Syntax

Description

Language

Syntax

IDL

BOOL GetGetInfoResponse( in long ResponseHandle, out string SequenceOfCouples )

Visual C++

BOOL GetGetInfoResponse( long ResponseHandle, CString& SequenceOfCouples )

Visual Basic

GetGetInfoResponse( ByVal ResponseHandle As Long, SequenceOfCouples As String ) As Boolean

If there is a response in the queue with a matching handle, assigns its first argument to SequenceOfCouples. Leaves SequenceOfCouples unmodified if no such match is found.

Issue 2.1 August 2003

119

API Methods: Descriptions

Input Parameters

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch()

Output Parameters

SequenceOfCouples The first argument of a response in the queue with a handle matching the given response handle.

Return Value

Returns the response's status via GetResponseStatus(). Returns FALSE if there is no matching response handle.

Visual Basic Example

Private Sub PollingTimer_Timer() Dim Dim Dim Dim

ResponseName As String ResponseExists As Boolean ResponseHandle As Long SequenceOfCouples As String

' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.GetInfo": ' Response from GetInfo request, obtain sequence of couples VTel.GetGetInfoResponse ResponseHandle, SequenceOfCouples . . . Case "VTel.Logout": . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

120 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

// OnTimer() or OnIdle() long NextResponse; CString SequenceOfCouples; // Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case 11: // GetInfo. Use specific response parsing routine to // obtain the associated sequence of couples. VTel.GetGetInfoResponse(NextResponse, SequenceOfCouples); . . . break; case 15: // Hangup— handled as a generic response. . . . break;

default: // Not handling any other responses } // We are done with the response, release resources. VTel.FreeResponse(NextResponse); . . .

Issue 2.1 August 2003

121

API Methods: Descriptions

GetGetPhoneInfoResponse Syntax

Description

Input Parameters

Output Parameters

Language

Syntax

IDL

BOOL GetGetPhoneInfoResponse( in long ResponseHandle, out string SequenceOfCouples )

Visual C++

BOOL GetGetPhoneInfoResponse( long ResponseHandle, CString& SequenceOfCouples )

Visual Basic

GetGetPhoneInfoResponse( ByVal ResponseHandle As Long, SequenceOfCouples As String ) As Boolean

If there is a response in the queue with a matching handle, assigns its second argument to SequenceOfCouples. Leaves SequenceOfCouples unmodified if no such match is found.

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch().

Name

Description

SequenceOfCouples

The second argument of a response in the queue with a handle matching matches the given response handle.

Return Value

Returns the response's status via GetResponseStatus(). Returns FALSE if there is no matching response handle.

Visual Basic Example

Private Sub PollingTimer_Timer() Dim Dim Dim Dim

ResponseName As String ResponseExists As Boolean ResponseHandle As Long SequenceOfCouples As String

122 VTel Automation Server Programmer Guide

Methods

' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.GetPhoneInfo": ' Response from GetPhoneInfo request, ' obtain sequence of couples VTel.GetGetPhoneInfoResponse ResponseHandle, SequenceOfCouples . . . Case "VTel.Logout": . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

Visual C++ Example

// OnTimer() or OnIdle() long CString

NextResponse; SequenceOfCouples;

// Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case 12: // GetPhoneInfo. Use specific response parsing routine to // obtain the associated sequence of couples. VTel.GetGetPhoneInfoResponse(NextResponse, SequenceOfCouples); . . . break;

Issue 2.1 August 2003

123

API Methods: Descriptions

case 15: // Hangup— handled as a generic response. . . . break;

default: // Not handling any other responses } // We are done with the response, release resources. VTel.FreeResponse(NextResponse); . . .

GetInfo Syntax

Description

Language

Syntax

IDL

long GetInfo( )

Visual C++

long GetInfo( )

Visual Basic

GetInfo( ) As Long

Issue the VTel.GetInfo request asynchronously. Returns general information about the current state and configuration of VTel. The available information may vary in different configurations.

Input Parameters

None.

Output Parameters

None.

Return Value

Returns handle to the expected response.

124 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.GetInfo( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; . . . ResponseHandle = VTel.GetInfo( );

GetInfoSynch Syntax

Description

Language

Syntax

IDL

BOOL GetInfoSynch( out string SequenceOfCouples )

Visual C++

BOOL GetInfoSynch( CString& SequenceOfCouples )

Visual Basic

GetInfoSynch( SequenceOfCouples As String ) As Boolean

Issue the VTel.GetInfo request synchronously. Returns general information about the current state and configuration of VTel. The available information may vary in different configurations.

Input Parameters Output Parameters

.Return Value

None.

Name

Description

SequenceOfCouples

Information about the current status of VTel.

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Issue 2.1 August 2003

125

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim SequenceOfCouples As String Set VTel = CreateObject("VTEL.SESSION") . . . SequenceOfCouples = SeqCoupleCreate() Mutex = True Status = VTel.GetInfoSynch( SequenceOfCouples ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString SequenceOfCouples; . . . SequenceOfCouples = SeqCoupleCreate(); Status = VTel.GetInfoSynch( SequenceOfCouples );

GetLastResponseDetail Syntax

Description

Language

Syntax

IDL

void GetLastResponseDetail( out string Origin, out string ErrorCode, out string Description, out string ReturnCode )

Visual C++

void GetLastResponseDetail( CString& Origin, CString& ErrorCode, CString& Description, CString& ReturnCode )

Visual Basic

GetLastResponseDetail( Origin As String, ErrorCode As String, Description As String, ReturnCode As String)

Returns error information for the last synchronous request that failed. This information will be overwritten with each new error. Therefore, care must be taken if synchronous calls are used in multi-threaded applications. Each OLE session maintains its own error information. Therefore, multiple sessions may be used without conflict.

126 VTel Automation Server Programmer Guide

Methods

Input Parameters Output Parameters

None.

Name

Description

Origin

The source of the error (e.g., SYSTEM, USER, VTel, " ").

ErrorCode

The hexadecimal error code.

Description

The error description.

ReturnCode

The return code from the Avaya TS.

Return Value

Returns FALSE if the response indicates an error.

Visual Basic Example

Dim VTel As Object Dim VduID As String ' Output value from MakeCall() Origin As String ' e.g.: USER, SYSTEM, or VTEL ErrorCode As String ' Hexadecimal error code Description As String ' A descriptive error message ReturnCode As String ' Return code from Avaya Telephony Set VTel = CreateObject("VTEL.SESSION") . . Mutex = True If VTel.MakeCallSynch("", "4004", VduID) = False Then VTel.GetLastResponseDetail Origin, ErrorCode, Description, ReturnCode EndIf Mutex = False . .

Visual C++ Example

#include "VProxy.h" CVTelPro VTel; CString VduID; // Output value from MakeCall() CString Origin; // e.g.: USER, SYSTEM, or VTEL CString ErrorCode; // Hexadecimal error code CString Description; // A descriptive error message CString ReturnCode; // Return code from Avaya Telephony . . if (!VTel.MakeCallSynch("", "4004", VduID) = False) { VTel.GetLastResponseDetail(Origin, ErrorCode, Description, ReturnCode); . .

Issue 2.1 August 2003

127

API Methods: Descriptions

GetMakeCallResponse Syntax

Description Input Parameters

Output Parameters

Language

Syntax

IDL

BOOL GetMakeCallResponse( in long ResponseHandle, out string VduID )

Visual C++

BOOL GetMakeCallResponse( long ResponseHandle, CString& VduID )

Visual Basic

GetMakeCallResponse( ByVal ResponseHandle As Long, VduID As String ) As Boolean

If there is a response in the queue with a matching handle, assigns its third argument to VduID. Leaves VduID unmodified if no such match is found.

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch().

Name

Description

VduID

The third argument of a response in the queue with a handle matching the given response handle.

Return Value

Returns the response's status via GetResponseStatus(). Returns FALSE if there is no matching response handle.

Visual Basic Example

Private Sub PollingTimer_Timer() Dim Dim Dim Dim

ResponseName As String ResponseExists As Boolean ResponseHandle As Long VduID As String

' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then

128 VTel Automation Server Programmer Guide

Methods

' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.MakeCall": ' Response from MakeCall request, ' obtain VDUID VTel.GetMakeCallResponse ResponseHandle, VduID . . . Case "VTel.Logout": . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

Visual C++ Example

// OnTimer() or OnIdle() long CString

NextResponse; VduID;

// Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case 22: // MakeCall. Use specific response parsing routine to // obtain the associated VDUID. VTel.GetMakeCallResponse(NextResponse, VduID); . . . break; case 15: // Hangup— handled as a generic response. . . . break;

Issue 2.1 August 2003

129

API Methods: Descriptions

default: // Not handling any other responses } // We are done with the response, release resources. VTel.FreeResponse(NextResponse); . . .

GetPhoneInfo Syntax

Description

Language

Syntax

IDL

long GetPhoneInfo( in string PhoneNumber )

Visual C++

long GetPhoneInfo( LPCTSTR PhoneNumber )

Visual Basic

GetPhoneInfo( ByVal PhoneNumber As String ) As Long

Issue the VTel.GetPhoneInfo request asynchronously. Returns switchdependent information about the default phone. This method is dependent on the telephone switch and the type of phone assigned. Refer to the IDL chapter of your Telephony Services manual to determine availability.

Input Parameters

PhoneNumber

Currently only null (default phone) is allowed.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . Mutex = True ResponseHandle = VTel.GetPhoneInfo( PhoneNumber ) Mutex = False

130 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString PhoneNumber; . . . ResponseHandle = VTel.GetPhoneInfo( PhoneNumber );

GetPhoneInfoSynch Syntax

Description

Language

Syntax

IDL

BOOL GetPhoneInfoSynch( in string PhoneNumber, out string SequenceOfCouples )

Visual C++

BOOL GetPhoneInfoSynch( LPCTSTR PhoneNumber, CString& SequenceOfCouples )

Visual Basic

GetPhoneInfoSynch( ByVal PhoneNumber As String, SequenceOfCouples As String ) As Boolean

Issue the VTel.GetPhoneInfo request synchronously. Returns switchdependent information about the default phone. This method is dependent on the telephone switch and the type of phone assigned. Refer to the IDL chapter of your Telephony Services manual to determine availability.

Input Parameters

.Output Parameters

Return Value

Name

Description

PhoneNumber

Currently only null (default phone) is allowed.

Name

Description

SequenceOfCouples

Information about the current status of the default phone.

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Issue 2.1 August 2003

131

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim PhoneNumber As String Dim SequenceOfCouples As String Set VTel = CreateObject("VTEL.SESSION") . . . SequenceOfCouples = SeqCoupleCreate() Mutex = True Status = VTel.GetPhoneInfoSynch( PhoneNumber, SequenceOfCouples ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString PhoneNumber; CString SequenceOfCouples; . . . SequenceOfCouples = SeqCoupleCreate(); Status = VTel.GetPhoneInfoSynch( PhoneNumber, SequenceOfCouples );

GetResponseArg Syntax

Description

Language

Syntax

IDL

string GetResponseArg( in long ResponseHandle, in int ArgumentPosition )

Visual C++

CString GetResponseArg( long ResponseHandle, long ArgumentPosition )

Visual Basic

GetResponseArg( ByVal ResponseHandle As Long, ByVal ArgumentPosition As Long ) As String

Returns the argument at the specified position in the specified response.

132 VTel Automation Server Programmer Guide

Methods

Input Parameters

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch()

ArgumentPosition

Position of the desired argument.

Output Parameters

None.

Return Value

Returns the empty string (" ") if the response handle is invalid, if the response has not yet arrived, or if the position is invalid.

Visual Basic Example

Private Sub PollingTimer_Timer() Dim Dim Dim Dim Dim

ResponseName As String ResponseExists As Boolean ResponseHandle As Long VduID As String Phone As String

' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.MakeCall": ' Response from MakeCall request, display new VDUID VTel.GetMakeCallResponse ResponseHandle, VduID VduIDTextBox.Text = VduID Case "VTel.Logout": . . . Case "VTel.FooBarRequest": ' This is a new type of request that the automation ' server does not know about. We'll obtain its ' arguments manually using GetResponseArg(). VduID = VTel.GetResponseArg(ResponseHandle, 0) Phone = VTel.GetResponseArg(ResponseHandle, 1) . . .

Issue 2.1 August 2003

133

API Methods: Descriptions

Visual C++ Example

// OnTimer() or OnIdle() long CString CString CString

NextResponse; ResponseName; VduID; Phone;

// Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case -3: // Unrecognized response type, no response code available. // Use GetResponseName() to obtain the name of a new type // of response. ResponseName = VTel.GetResponseName(NextResponse); if (ResponseName == "VTel.FooBar") { // It's the FooBar response, get the args manually VduID = VTel.GetResponseArg(ResponseHandle, 0) Phone = VTel.GetResponseArg(ResponseHandle, 1) . . .

GetResponseCode Syntax

Description

Language

Syntax

IDL

long GetResponseCode( in long ResponseHandle )

Visual C++

long GetResponseCode( long ResponseHandle )

Visual Basic

GetResponseCode( ByVal ResponseHandle As Long ) As Long

Returns the response code of the specified response.

134 VTel Automation Server Programmer Guide

Methods

Input Parameters

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch()

Output Parameters

None.

Return Value

The response codes are as given in Response codes on page 61.

Visual Basic Example

Private Sub PollingTimer_Timer() Dim ResponseCode As Long Dim ResponseExists As Boolean Dim ResponseHandle As Long ' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response code ResponseCode = VTel.GetResponseCode(ResponseHandle) Select Case ResponseCode Case 0: ' The response was "VTel.Error". Check the response ' details for more information. They will most likely ' show that the request syntax was invalid. . . . Case -1: ' The response handle from GetResponseType() was invalid ' - should not happen. . . . Case -2: ' Server response queue overrun, we must have forgotten ' to free responses! . . . Case -3: ' Unrecognized response type, no response code ' available. Use GetResponseName() to obtain the name ' of a new type of response. . .

Issue 2.1 August 2003

135

API Methods: Descriptions

. Case 22: ' Response from MakeCall request, display new VDUID VTel.GetMakeCallResponse ResponseHandle, VduID VduIDTextBox.Text = VduID Case 21: ' Response from Logout request . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

Visual C++ Example

// OnTimer() or OnIdle() long NextResponse; // Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case 0: // The response was "VTel.Error". Check the response // details for more information. They will most likely // show that the request syntax was invalid. AfxMessageBox("Response was VTel.Error"); break; case -1: // The response handle from GetResponseType() was invalid // - should not happen. AfxMessageBox("Internal error in Automation Server!"); break; case -2: // Server response queue overrun, we must have forgotten // to free responses! AfxMessageBox("Server ran out of space and dropped responses."); break;

136 VTel Automation Server Programmer Guide

Methods

case -3: // Unrecognized response type, no response code available. // Use GetResponseName() to obtain the name of a new type // of response. . . . case 22: // MakeCall. Use specific response parsing routine to // obtain the associated VDUID. . . . break; case 15: // Hangup— handled as a generic response. . . . break;

default: // Not handling any other responses } // We are done with the response, release resources. VTel.FreeResponse(NextResponse); . . .

GetResponseCount Syntax Language

Syntax

IDL

long GetResponseCount( )

Visual C++

long GetResponseCount( )

Visual Basic

GetResponseCount( ) As Long

Description

Returns the number of responses currently queued.

Input Parameters

None.

Issue 2.1 August 2003

137

API Methods: Descriptions

Output Parameters

None.

Return Value

Count of queued responses.

Visual Basic Example

Dim VTel As Object Dim ResponsesWaiting As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponsesWaiting = VTel.GetResponseCount( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponsesWaiting; . . . ResponsesWaiting = VTel.GetResponseCount( );

GetResponseDetail Syntax

Description

Language

Syntax

IDL

BOOL GetResponseDetail( in long ResponseHandle, out string Origin, out string ErrorCode, out string Description, out string ReturnCode )

Visual C++

BOOL GetResponseDetail( long ResponseHandle, CString& Origin, CString& ErrorCode, CString& Description, CString& ReturnCode )

Visual Basic

GetResponseDetail( ByVal ResponseHandle As Long, Origin As String, ErrorCode As String, Description As String, ReturnCode As String ) As Boolean

Returns error information for the specified response.

138 VTel Automation Server Programmer Guide

Methods

Input Parameters

Output Parameters

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch().

Name

Description

Origin

The source of the error (e.g., SYSTEM, USER, VTel, " ").

ErrorCode

The hexadecimal error code or " ".

Description

The error description or " ".

ReturnCode

The return code or " ".

Note that each of these values will be " " when no error occurred. Return Value

Returns FALSE if the response handle is invalid or the response has not yet arrived.

Visual Basic Example

Private Sub PollingTimer_Timer() Dim Dim Dim Dim Dim Dim Dim

ResponseName As String ResponseExists As Boolean ResponseHandle As Long Origin As String ErrorCode As String Description As String ReturnCode As String

' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.MakeCall": ' Response from MakeCall request, display new VDUID VTel.GetMakeCallResponse ResponseHandle, VduID If VTel.GetMakeCallResponse ResponseHandle, VduID VduIDTextBox.Text = VduID Else ' Response indicates error, get specifics.

Issue 2.1 August 2003

139

API Methods: Descriptions

VTel.GetResponseDetail ResponseHandle, Origin, ErrorCode, Description, ReturnCode . . . EndIf Case "VTel.Logout": . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

Visual C++ Example

// OnTimer() or OnIdle() long NextResponse; // Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case 0: // The response was "VTel.Error". Check the response // details for more information. They will most likely // show that the request syntax was invalid. AfxMessageBox("Response was VTel.Error"); break; case -1: // The response handle from GetResponseType() was invalid // should not happen. AfxMessageBox("Internal error in Automation Server!"); break; case -2: // Server response queue overrun, we must have forgotten // to free responses! AfxMessageBox("Server ran out of space and dropped responses."); break;

140 VTel Automation Server Programmer Guide

Methods

case // // //

-3: Unrecognized response type, no response code available. Use GetResponseName() to obtain the name of a new type of response. . . .

case 22: // MakeCall. Use specific response parsing routine to obtain // the associated VDUID. CString VduID; if ( VTel.GetMakeCallResponse(ResponseHandle, VduID) ) { // Response was OK. Do something with this VDUID such //as add it to a collection of active calls. . . . } else { // Response indicates error, get specifics. VTel.GetResponseDetail(ResponseHandle, Origin, ErrorCode, Description, ReturnCode); . . . } break; case 15: // Hangup— handled as a generic response. if ( VTel.GetResponseStatus(ResponseHandle) ) { // Response was OK. Do something such as set the call // state. . . . } else { // Response indicates error, get specifics. VTel.GetResponseDetail(ResponseHandle, Origin, ErrorCode, Description, ReturnCode); . . . } break;

Issue 2.1 August 2003

141

API Methods: Descriptions

default: // Not handling any other responses } // We are done with the response, release resources. VTel.FreeResponse(NextResponse); . . .

GetResponseName Syntax

Description Input Parameters

Language

Syntax

IDL

string GetResponseName( in long ResponseHandle )

Visual C++

CString GetResponseName( long ResponseHandle )

Visual Basic

GetResponseName( ByVal ResponseHandle As Long ) As String

Returns the name of the specified response, e.g., VTel.MakeCall.

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch()

Output Parameters

None.

Return Value

Returns the empty string (" ") if the response handle is invalid.

Visual Basic Example

Private Sub PollingTimer_Timer() Dim ResponseName As String Dim ResponseExists As Boolean Dim ResponseHandle As Long

142 VTel Automation Server Programmer Guide

Methods

' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.MakeCall": ' Response from MakeCall request, display new VDUID VTel.GetMakeCallResponse ResponseHandle, VduID VduIDTextBox.Text = VduID Case "VTel.Logout": . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

Visual C++ Example

// OnTimer() or OnIdle() long CString CString CString

NextResponse; ResponseName; VduID; Phone;

// Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case -3: // Unrecognized response type, no response code available. // Use GetResponseName() to obtain the name of a new type // of response. ResponseName = VTel.GetResponseName(NextResponse); if (ResponseName == "VTel.FooBar") { // It's the FooBar response, get the args manually VduID = VTel.GetResponseArg(ResponseHandle, 0) Phone = VTel.GetResponseArg(ResponseHandle, 1) . .

Issue 2.1 August 2003

143

API Methods: Descriptions

GetResponseStatus Syntax

Description Input Parameters

Language

Syntax

IDL

BOOL GetResponseStatus( in long ResponseHandle )

Visual C++

BOOL GetResponseStatus( long ResponseHandle )

Visual Basic

GetResponseStatus( ByVal ResponseHandle As Long ) As Boolean

Returns TRUE if all three fields of the response's exception argument are empty.

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch()

Output Parameters

None.

Return Value

Returns FALSE if response indicates error.

Visual Basic Example

Private Sub PollingTimer_Timer() Dim ResponseName As String Dim ResponseExists As Boolean Dim ResponseHandle As Long ' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, make sure response OK If VTel.GetResponseStatus(ResponseHandle) = False Then ' Something went wrong, call GetResponseDetail() . . .

144 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

// OnTimer() or OnIdle() long NextResponse; // Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, make sure response OK if VTel.GetResponseStatus(NextResponse) == FALSE { // Something went wrong, call GetResponseDetail() . . .

GetResponseString Syntax

Description

Input Parameters

Language

Syntax

IDL

BOOL GetResponseString( in long ResponseHandle, out string OutResponseString )

Visual C++

BOOL GetResponseString( long ResponseHandle, CString& OutResponseString )

Visual Basic

GetResponseString( ByVal ResponseHandle As Long, OutResponseString As String ) As Boolean

Assigns the string of the specified response in the queue to OutResponseString. Leaves OutResponseString unmodified if no such response is found.

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch()

Issue 2.1 August 2003

145

API Methods: Descriptions

Output Parameters

Name

Description

OutResponseStrin g

The string representation of a response in the queue with a handle matching the given response handle

Return Value

Returns FALSE if there is no matching response handle.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim ResponseString As String Dim Status As Boolean Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.GetResponseString(ResponseHandle,ResponseString) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString ResponseString; BOOL Status; . . . Status = VTel.GetResponseString(ResponseHandle,ResponseString);

GetVDUCreateResponse Syntax

Description

Language

Syntax

IDL

BOOL GetVDUCreateResponse( in long ResponseHandle, out string VduID )

Visual C++

BOOL GetVDUCreateResponse( long ResponseHandle, CString& VduID )

Visual Basic

GetVDUCreateResponse( ByVal ResponseHandle As Long, VduID As String ) As Boolean

If there is a response in the queue with a matching handle, assigns its second argument to VduID. Leaves VduID unmodified if no such match is found.

146 VTel Automation Server Programmer Guide

Methods

Input Parameters

Output Parameters

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch().

Name

Description

VduID

The second argument of a response in the queue with a handle matching the given response handle.

Return Value

Returns the response's status via GetResponseStatus(). Returns FALSE if there is no matching response handle.

Visual Basic Example

Private Sub PollingTimer_Timer() Dim Dim Dim Dim

ResponseName As String ResponseExists As Boolean ResponseHandle As Long VduID As String

' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.VDUCreate": ' Response from VDUCreate request, ' obtain VDUID VTel.GetVDUCreateResponse ResponseHandle, VduID . . Case "VTel.Logout": . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

Issue 2.1 August 2003

147

API Methods: Descriptions

Visual C++ Example

// OnTimer() or OnIdle() long CString

NextResponse; VduID;

// Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case 32: // VduCreate. Use specific response parsing routine to // obtain the associated VDUID. VTel.GetVDUCreateResponse(NextResponse, VduID); . . . break; case 15: // Hangup is handled as a generic response. . . . break;

default: // Not handling any other responses } // We are done with the response, release resources. VTel.FreeResponse(NextResponse); . . .

148 VTel Automation Server Programmer Guide

Methods

GetVDUFindVDUResponse Syntax

Description

Input Parameters

Output Parameters

Language

Syntax

IDL

BOOL GetVDUFindVDUResponse( in long ResponseHandle, out string SequenceOfStrings )

Visual C++

BOOL GetVDUFindVDUResponse( long ResponseHandle, CString& SequenceOfStrings )

Visual Basic

GetVDUFindVDUResponse( ByVal ResponseHandle As Long, SequenceOfStrings As String ) As Boolean

If there is a response in the queue with a matching handle, assigns its second argument to SequenceOfStrings. Leaves SequenceOfStrings unmodified if no such match is found.

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch().

Name

Description

SequenceOfStrings

The second argument of a response in the queue with a handle matching the given response handle.

Return Value

Returns the response's status via GetResponseStatus(). Returns FALSE if there is no matching response handle.

Visual Basic Example

Private Sub PollingTimer_Timer() Dim Dim Dim Dim

ResponseName As String ResponseExists As Boolean ResponseHandle As Long SequenceOfStrings As String

'Only execute if "VTel" object variable is bound to running server' If IsConnected = True Then 'Is there a response to process? If Mutex = True then Exit Sub

Issue 2.1 August 2003

149

API Methods: Descriptions

ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.VDUFindVDU": ' Response from VDUFindVDU request, ' obtain sequence of strings VTel.GetVDUFindVDUResponse ResponseHandle, SequenceOfStrings . . . Case "VTel.Logout": . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

Visual C++ Example

// OnTimer() or OnIdle() long CString

NextResponse; SequenceOfCStrings;

// Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case 33: // VDUFindVDU. Use specific response parsing routine // to obtain the associated sequence of strings. VTel.GetVDUFindVDUResponse(NextResponse, SequenceOfStrings); . . . break;

150 VTel Automation Server Programmer Guide

Methods

case 15: // Hangup— handled as a generic response. . . . break;

default: // Not handling any other responses } // We are done with the response, release resources. VTel.FreeResponse(NextResponse); . . .

GetVDUGetActiveResponse Syntax

Description

Input Parameters

Language

Syntax

IDL

BOOL GetVDUGetActiveResponse( in long ResponseHandle, out string SequenceOfStrings )

Visual C++

BOOL GetVDUGetActiveResponse( long ResponseHandle, CString& SequenceOfStrings )

Visual Basic

GetVDUGetActiveResponse( ByVal ResponseHandle As Long, SequenceOfStrings As String ) As Boolean

If there is a response in the queue with a matching handle, assigns its first argument to SequenceOfStrings. Leaves SequenceOfStrings unmodified if no such match is found.

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch()

Issue 2.1 August 2003

151

API Methods: Descriptions

Output Parameters

Name

Description

SequenceOfStrings

The first argument of a response in the queue with a handle matching the given response handle.

Return Value

Returns the response's status via GetResponseStatus(). Returns FALSE if there is no matching response handle.

Visual Basic Example

Private Sub PollingTimer_Timer() Dim Dim Dim Dim

ResponseName As String ResponseExists As Boolean ResponseHandle As Long SequenceOfStrings As String

' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.VDUGetActive": ' Response from VDUGetActive request, ' obtain sequence of strings VTel.GetVDUGetActiveResponse ResponseHandle, SequenceOfStrings . . . Case "VTel.Logout": . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

152 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

// OnTimer() or OnIdle() long CString

NextResponse; SequenceOfCStrings;

// Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case 10: // VDUGetActive. Use specific response parsing // routine to obtain the associated sequence // of strings. VTel.GetVDUGetActiveResponse(NextResponse, SequenceOfStrings); . . . break; case 15: // Hangup is handled as a generic response. . . . break;

default: // Not handling any other responses } // We are done with the response, release resources. VTel.FreeResponse(NextResponse); . . . .

Issue 2.1 August 2003

153

API Methods: Descriptions

GetVDUGetCurrentResponse Syntax

Description Input Parameters

Output Parameters

Language

Description

IDL

BOOL GetVDUGetCurrentResponse( in long ResponseHandle, out string VduID)

Visual C++

BOOL GetVDUGetCurrentResponse( long ResponseHandle, CString& VduID )

Visual Basic

GetVDUGetCurrentResponse( ByVal ResponseHandle As Long, VduID As String ) As Boolean

If there is a response in the queue with a matching handle, assigns its first argument to VduID. Leaves VduID unmodified if no such match is found.

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch().

Name

Description

VduID

The first argument of a response in the queue with a handle matching the given response handle.

Return Value

Returns the response’s status via GetResponseStatus(). Returns FALSE if there is no matching response handle.

Visual Basic Example

Private Sub PollingTimer_Timer() Dim Dim Dim Dim

ResponseName As String ResponseExists As Boolean ResponseHandle As Long VduID As String

' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub

154 VTel Automation Server Programmer Guide

Methods

ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.VDUGetCurrent": ' Response from VDUGetCurrent request, obtain VDUID VTel.GetVDUGetCurrentResponse ResponseHandle, VduID . . . Case "VTel.Logout": . . .

End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

Visual C++ Example

// OnTimer() or OnIdle() long CString

NextResponse; VduID;

// Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case 59: // VDUGetCurrent. Use specific response parsing routine // to obtain the associated VduID. VTel.GetVDUGetCurrentResponse(NextResponse,VduID); . . break; default: // Not handling any other responses } // We are done with the response, release resources.

Issue 2.1 August 2003

155

API Methods: Descriptions

VTel.FreeResponse(NextResponse); . . .

GetVDUGetDataResponse Syntax

Description

Input Parameters

Output Parameters

Language

Syntax

IDL

BOOL GetVDUGetDataResponse( in long ResponseHandle, out string SequenceOfCouples )

Visual C++

BOOL GetVDUGetDataResponse( long ResponseHandle, CString& SequenceOfCouples )

Visual Basic

GetVDUGetDataResponse( ByVal ResponseHandle As Long, SequenceOfCouples As String ) As Boolean

If there is a response in the queue with a matching handle, assigns its second argument to SequenceOfCouples. Leaves SequenceOfCouples unmodified if no such match is found.

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch()

Name

Description

SequenceOfCouples

The second argument of a response in the queue with a handle matching the given response handle.

Return Value Returns the response's status via GetResponseStatus(). Returns FALSE if there is no matching response handle.

156 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Private Sub PollingTimer_Timer() Dim Dim Dim Dim

ResponseName As String ResponseExists As Boolean ResponseHandle As Long SequenceOfCouples As String

' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.VDUGetData": ' Response from VDUGetData request, obtain sequence of couples VTel.GetVDUGetDataResponse ResponseHandle, SequenceOfCouples . . . Case "VTel.Logout": . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

Visual C++ Example

// OnTimer() or OnIdle() long CString

NextResponse; SequenceOfCouples;

// Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case 34:

Issue 2.1 August 2003

157

API Methods: Descriptions

// VDUGetData. Use specific response parsing routine to // obtain the associated sequence of couples. VTel.GetVDUGetDataResponse(NextResponse, SequenceOfCouples); . . . break; case 15: // Hangup— handled as a generic response. . . . break;

default: // Not handling any other responses } // We are done with the response, release resources. VTel.FreeResponse(NextResponse); . . .

GetVDUGetOneValueResponse Syntax

Description

Language

Syntax

IDL

BOOL GetVDUGetOneValueResponse( in long ResponseHandle, out string Value )

Visual C++

BOOL GetVDUGetOneValueResponse( long ResponseHandle, CString& Value )

Visual Basic

GetVDUGetOneValueResponse( ByVal ResponseHandle As Long, Value As String ) As Boolean

If there is a response in the queue with a matching handle, assigns its third argument to Value. Leaves Value unmodified if no such match is found.

158 VTel Automation Server Programmer Guide

Methods

Input Parameters

Output Parameters

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch().

Name

Description

Value

The third argument of a response in the queue with a handle matching the given response handle.

Return Value Returns the response's status via GetResponseStatus(). Returns FALSE if there is no matching response handle. Visual Basic Example

Private Sub PollingTimer_Timer() Dim Dim Dim Dim

ResponseName As String ResponseExists As Boolean ResponseHandle As Long Value As String

' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.VDUGetOneValue ": ' Response from VDUGetOneValue request, obtain string VTel.GetVDUGetOneValueResponse ResponseHandle, Value . . Case "VTel.Logout": . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

Issue 2.1 August 2003

159

API Methods: Descriptions

Visual C++ Example

// OnTimer() or OnIdle() long CString

NextResponse; Value;

// Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case 35: // VDUGetOneValue. Use specific response parsing routine // to obtain the associated string. VTel.GetVDUGetOneValueResponse(NextResponse, Value); . . . break; case 15: // Hangup is handled as a generic response. . . . break;

default: // Not handling any other responses } // We are done with the response, release resources. VTel.FreeResponse(NextResponse); . . .

160 VTel Automation Server Programmer Guide

Methods

GetVDUGetValuesResponse Syntax

Description

Input Parameters

Output Parameters

Language

Syntax

IDL

BOOL GetVDUGetValuesResponse( in long ResponseHandle, out string SequenceOfCouples )

Visual C++

BOOL GetVDUGetValuesResponse( long ResponseHandle, CString& SequenceOfCouples )

Visual Basic

GetVDUGetValuesResponse( ByVal ResponseHandle As Long, SequenceOfCouples As String ) As Boolean

If there is a response in the queue with a matching handle, assigns its second argument to SequenceOfCouples. Leaves SequenceOfCouples unmodified if no such match is found.

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch().

Name

Description

SequenceOfCouples

The second argument of a response in the queue with a handle matching the given response handle.

Return Value

Returns the response's status via GetResponseStatus(). Returns FALSE if there is no matching response handle.

Visual Basic Example

Private Sub PollingTimer_Timer() Dim Dim Dim Dim

ResponseName As String ResponseExists As Boolean ResponseHandle As Long SequenceOfCouplesAsString

' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub

Issue 2.1 August 2003

161

API Methods: Descriptions

ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.VDUGetValues": ' Response from VDUGetValues request, obtain sequence of couples VTel.GetVDUGetValuesResponse ResponseHandle, SequenceOfCouples . . . Case "VTel.Logout": . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

Visual C++ Example

// OnTimer() or OnIdle() long CString

NextResponse; SequenceOfCouples;

// Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case 36: // VDUGetValues. Use specific response parsing routine to // obtain the associated sequence of couples. VTel.GetVDUGetValuesResponse(NextResponse, SequenceOfCouples); . . break; case 15: // Hangup is handled as a generic response. . . break; default: // Not handling any other responses }

162 VTel Automation Server Programmer Guide

Methods

// We are done with the response, release resources. VTel.FreeResponse(NextResponse); . . .

Hangup Syntax

Description

Language

Syntax

IDL

long Hangup( in string VduID )

Visual C++

long Hangup( LPCTSTR VduID )

Visual Basic

Hangup( ByVal VduID As String ) As Long

Issue the VTel.Hangup request asynchronously. Places the phone on-hook, disconnecting the call. The state of the EDU depends on the current configuration and any preset actions. Race conditions may occur if the agent also releases the call through the VTel user interface, or the caller hangs up at about the same time. An error condition indicating an invalid VDUID should generally be considered a normal return. If the call has been hung up but the EDU is still available, this is harmless and no error is returned, since it correctly reflects the state at that time. Should you need to know when the call is hung up, look for the Disconnect event. If a ConferenceInit or TransferInit is in progress and Hangup is invoked:

Input Parameters

●

the conference or consultative transfer is canceled

●

the conversation(s) that were placed on hold remain on hold

Name

Description

VduID

The VDUID of the telephone call.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Issue 2.1 August 2003

163

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.Hangup( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; . . ResponseHandle = VTel.Hangup( VduID );

HangupSynch Syntax

Description

Language

Syntax

IDL

BOOL HangupSynch( in string VduID )

Visual C++

BOOL HangupSynch( LPCTSTR VduID )

Visual Basic

HangupSynch( ByVal VduID As String ) As Boolean

Issue the VTel.Hangup request synchronously. Places the phone on-hook, disconnecting the call. The state of the EDU depends on the current configuration and any preset actions. Race conditions may occur if the agent also releases the call through the VTel user interface, or the caller hangs up at about the same time. An error condition indicating an invalid VDUID should generally be considered a normal return. If the call has been hung up but the EDU is still available, this is harmless and no error is returned, since it correctly reflects the state at that time. Should you need to know when the call is hung up, look for the Disconnect event. If a ConferenceInit or TransferInit is in progress and Hangup is invoked: ●

The conference or consultative transfer is canceled.

●

The conversation(s) that were placed on hold remain on hold.

164 VTel Automation Server Programmer Guide

Methods

Input Parameters

Name

Description

VduID

The VDUID of the telephone call.

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.HangupSynch( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; . . . Status = VTel.HangupSynch( VduID );

Hold Syntax Language

Syntax

IDL

long Hold( in string VduID )

Visual C++

long Hold( LPCTSTR VduID )

Visual Basic

Hold( ByVal VduID As String ) As Long

Issue 2.1 August 2003

165

API Methods: Descriptions

Description

Input Parameters

Issue the VTel.Hold request asynchronously. Sets an active call to the hold state. If the call exists and is currently on-hold, this is harmless and ignored without error. Should you need to know when the call is actually placed on hold, look for the OnHold event.

Name

Description

VduID

The VDUID of the telephone call.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.Hold( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; . . . ResponseHandle = VTel.Hold( VduID );

HoldReconnect Syntax Language

Syntax

IDL

long HoldReconnect( in string VduID )

Visual C++

long HoldReconnect( LPCTSTR VduID )

Visual Basic

HoldReconnect( ByVal VduID As String ) As Long

166 VTel Automation Server Programmer Guide

Methods

Description

Input Parameters

Issue the VTel.HoldReconnect request asynchronously. Removes the hold state for a current call and makes it active. If the call exists but is currently offhold, this is harmless and ignored without error. Should you need to know when the call is actually reconnected, look for the InCall event.

Name

Description

VduID

The VDUID of the telephone call.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.HoldReconnect( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; . . . ResponseHandle = VTel.HoldReconnect( VduID );

Issue 2.1 August 2003

167

API Methods: Descriptions

HoldReconnectSynch Syntax

Description

Language

Syntax

IDL

BOOL HoldReconnectSynch( in string VduID )

Visual C++

BOOL HoldReconnectSynch( LPCTSTR VduID )

Visual Basic

HoldReconnectSynch( ByVal VduID As String ) As Boolean

Issue the VTel.HoldReconnect request synchronously. Removes the hold state for a current call and makes it active. If the call exists but is currently off-hold, this is harmless and ignored without error. Should you need to know when the call is actually reconnected, look for the InCall event.

Input Parameters

Name

Description

VduID

The VDUID of the telephone call.

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.HoldReconnectSynch( VduID ) Mutex = False

168 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; . . . Status = VTel.HoldReconnectSynch( VduID );

HoldSynch Syntax

Description

Language

Syntax

IDL

BOOL HoldSynch( in string VduID )

Visual C++

BOOL HoldSynch( LPCTSTR VduID )

Visual Basic

HoldSynch( ByVal VduID As String ) As Boolean

Issue the VTel.Hold request synchronously. Sets an active call to the hold state. If the call exists and is currently on-hold, this is harmless and ignored without error. Should you need to know when the call is actually placed on hold, look for the OnHold event.

Input Parameters

Name

Description

VduID

The VDUID of the telephone call.

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Issue 2.1 August 2003

169

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.HoldSynch( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; . . . Status = VTel.HoldSynch( VduID );

LogEntry Syntax

Description

Language

Syntax

IDL

long LogEntry( in string Text )

Visual C++

long LogEntry( LPCTSTR Text )

Visual Basic

LogEntry( ByVal Text As String ) As Long

Issue the VTel.LogEntry request asynchronously. Permits a desktop application to add entries to the VTel log file. Each LogEntry entry is automatically given a date-time stamp, identified as to the connection number of the requester, and followed by a new line.

Input Parameters

Output Parameters

. Name

Description

Text

The text that is to be written to the VTel log file.

None.

170 VTel Automation Server Programmer Guide

Methods

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim Text As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.LogEntry( Text ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString Text; . . . ResponseHandle = VTel.LogEntry( Text );

LogEntrySynch Syntax

Description

Language

Syntax

IDL

BOOL LogEntrySynch( in string Text )

Visual C++

BOOL LogEntrySynch( LPCTSTR Text )

Visual Basic

LogEntrySynch( ByVal Text As String ) As Boolean

Issue the VTel.LogEntry request synchronously. Permits a desktop application to add entries to the VTel log file. Each LogEntry entry is automatically given a date-time stamp, identified as to the connection number of the requester, and followed by a new line.

Input Parameters

Name

Description

Text

The text that is to be written to the VTel log file.

Issue 2.1 August 2003

171

API Methods: Descriptions

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim Text As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.LogEntrySynch( Text ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString Text; . . . Status = VTel.LogEntrySynch( Text );

Login Syntax

Description

Language

Syntax

IDL

long Login( in string LoginID, in string Password, in string AgentID, in string AgentPassword, in string StationID )

Visual C++

long Login( LPCTSTR LoginID, LPCTSTR Password, LPCTSTR AgentID, LPCTSTR AgentPassword, LPCTSTR StationID )

Visual Basic

Login( ByVal LoginID As String, ByVal Password As String, ByVal AgentID As String, ByVal AgentPassword As String, ByVal StationID As String ) As Long

Issue the VTel.Login request asynchronously. Directs VTel to log in to the Telephony system, creating an assignment to the agent's telephone set.

172 VTel Automation Server Programmer Guide

Methods

This will return an error for an invalid login, or if another login is currently in progress. The agent and station parameters may not be needed, depending on your configuration and the type of login desired. For the Meridian Link, AgentID corresponds to the position ID and StationID to the equipment number. The agent ID (if agent ID software is being used) can only be entered through IC Manager; it cannot be entered through VTel. See the Agent Configuration section of the Telephony Services for the Northern Telecom Meridian Link manual. Input Parameters

Name

Description

LoginID

Avaya TS login ID

Password

Avaya TS password, if one was assigned

AgentID

Phone login ID

AgentPassword

Phone password

StationID

Station or equipment number for this phoneset

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim LoginID As String Dim Password As String Dim AgentID As String Dim AgentPassword As String Dim StationID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.Login( LoginID, Password, AgentID, AgentPassword, StationID ) Mutex = False

Issue 2.1 August 2003

173

API Methods: Descriptions

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString LoginID; CString Password; CString AgentID; CString AgentPassword; CString StationID; . . . ResponseHandle = VTel.Login( LoginID, Password, AgentID, AgentPassword, StationID );

LoginACD Syntax

Description

Language

Syntax

IDL

long LoginACD( in string LoginID, in string Password, in string AgentID, in string AgentPassword, in string StationID, in string Queue )

Visual C++

long LoginACD( LPCTSTR LoginID, LPCTSTR Password, LPCTSTR AgentID, LPCTSTR AgentPassword, LPCTSTR StationID, LPCTSTR Queue )

Visual Basic

LoginACD( ByVal LoginID As String, ByVal Password As String, ByVal AgentID As String, ByVal AgentPassword As String, ByVal StationID As String, ByVal Queue As String ) As Long

Issue the VTel.LoginACD request asynchronously. Directs VTel to log in to the Telephony system, creating an assignment to the agent's ACD telephone set. This will return an error for an invalid login, or if another login is currently in progress. The agent, station and queue parameters may not be needed, depending on your configuration and the type of login desired. For the Meridian Link, AgentID corresponds to the position ID and StationID to the equipment number. The agent ID (if agent ID software is being used) can only be entered through IC Manager; it cannot be entered through VTel. See the Agent Configuration section of the Telephony Services for the Northern Telecom Meridian Link manual.

174 VTel Automation Server Programmer Guide

Methods

Input Parameters

Name

Description

LoginID

Avaya TS login ID

Password

Avaya TS password, if one was assigned

AgentID

Phone login ID

AgentPassword

Phone password

StationID

Station or equipment number for this phoneset

Queue

Queue for assignment

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim LoginID As String Dim Password As String Dim AgentID As String Dim AgentPassword As String Dim StationID As String Dim Queue As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.LoginACD( LoginID, Password, AgentID, AgentPassword, StationID, Queue ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString LoginID; CString Password; CString AgentID; CString AgentPassword; CString StationID; CString Queue; . . . ResponseHandle = VTel.LoginACD( LoginID, Password, AgentID, AgentPassword, StationID, Queue );

Issue 2.1 August 2003

175

API Methods: Descriptions

LoginACDSynch Syntax

Description

Language

Syntax

IDL

BOOL LoginACDSynch( in string LoginID, in string Password, in string AgentID, in string AgentPassword, in string StationID, in string Queue )

Visual C++

BOOL LoginACDSynch( LPCTSTR LoginID, LPCTSTR Password, LPCTSTR AgentID, LPCTSTR AgentPassword,LPCTSTR StationID, LPCTSTR Queue )

Visual Basic

LoginACDSynch( ByVal LoginID As String, ByVal Password As String, ByVal AgentID As String, ByVal AgentPassword As String, ByVal StationID As String; ByVal Queue As String ) As Boolean

Issue the VTel.LoginACD request synchronously. Directs VTel to log in to the Telephony system, creating an assignment to the agent's ACD telephone set. This will return an error for an invalid login, or if another login is currently in progress. The agent, station, and queue parameters may not be needed, depending on your configuration and the type of login desired. For the Meridian Link, AgentID corresponds to the position ID and StationID to the equipment number. The agent ID (if agent ID software is being used) can only be entered through IC Manager; it cannot be entered through VTel. See the Agent Configuration section of the Telephony Services for the Northern Telecom Meridian Link manual.

Input Parameters

Name

Description

LoginID

Avaya TS login ID

Password

Avaya TS password, if one was assigned

AgentID

Phone login ID

AgentPassword

Phone password

StationID

Station or equipment number for this phoneset

Queue

Queue for assignment

176 VTel Automation Server Programmer Guide

Methods

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim LoginID As String Dim Password As String Dim AgentID As String Dim AgentPassword As String Dim StationID As String Dim Queue As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.LoginACDSynch( LoginID, Password, AgentID, AgentPassword, StationID, Queue ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString LoginID; CString Password; CString AgentID; CString AgentPassword; CString StationID; CString Queue; . . . Status = VTel.LoginACDSynch( LoginID, Password, AgentID, AgentPassword, StationID, Queue );

Issue 2.1 August 2003

177

API Methods: Descriptions

LoginSynch Syntax

Description

Language

Syntax

IDL

BOOL LoginSynch( in string LoginID, in string Password, in string AgentID, in string AgentPassword, in string StationID )

Visual C++

BOOL LoginSynch( LPCTSTR LoginID, LPCTSTR Password, LPCTSTR AgentID, LPCTSTR AgentPassword, LPCTSTR StationID )

Visual Basic

LoginSynch( ByVal LoginID As String, ByVal Password As String, ByVal AgentID As String, ByVal AgentPassword As String, ByVal StationID As String ) As Boolean

Issue the VTel.Login request synchronously. Directs VTel to log in to the Telephony system, creating an assignment to the agent's telephone set. This will return an error for an invalid login, or if another login is currently in progress. The agent and station parameters may not be needed, depending on your configuration and the type of login desired. For the Meridian Link, AgentID corresponds to the position ID and StationID to the equipment number. The agent ID (if agent ID software is being used) can only be entered through IC Manager; it cannot be entered through VTel. See the Agent Configuration section of the Telephony Services for the Northern Telecom Meridian Link manual.

Input Parameters

Output Parameters

Name

Description

LoginID

Avaya TS login ID

Password

Avaya TS password, if one was assigned

AgentID

Phone login ID

AgentPassword

Phone password

StationID

Station or equipment number for this phoneset

None.

178 VTel Automation Server Programmer Guide

Methods

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim LoginID As String Dim Password As String Dim AgentID As String Dim AgentPassword As String Dim StationID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.LoginSynch( LoginID, Password, AgentID, AgentPassword, StationID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString LoginID; CString Password; CString AgentID; CString AgentPassword; CString StationID; . . . Status = VTel.LoginSynch( LoginID, Password, AgentID, AgentPassword, StationID );

Issue 2.1 August 2003

179

API Methods: Descriptions

LoginTelephony Syntax

Description

Language

Syntax

IDL

long LoginTelephony( in string LoginID, in string Password, in string AgentID, in string AgentPassword, in string StationID, in string Queue )

Visual C++

long LoginTelephony( LPCTSTR LoginID, LPCTSTR Password, LPCTSTR AgentID, LPCTSTR AgentPassword, LPCTSTR StationID, LPCTSTR Queue )

Visual Basic

LoginTelephony( ByVal LoginID As String, ByVal Password As String, ByVal AgentID As String, ByVal AgentPassword As String, ByVal StationID As String, ByVal Queue As String ) As Long

Issue the VTel.LoginTelephony request asynchronously. Directs VTel to assign and log into the Telephony and EDU Servers. LoginVESP() must be called before LoginTelephony(). This method allows a two-step process for logging into VTel. It is paired with LogoutTelephony(). This will return an error for an invalid login, or if another login is currently in progress. The agent, station and queue parameters may not be needed, depending on your configuration and the type of login desired. For the Meridian Link, AgentID corresponds to the position ID and StationID to the equipment number. The agent ID (if agent ID software is being used) can only be entered through IC Manager; it cannot be entered through VTel. See the Agent Configuration section of the Telephony Services for the Northern Telecom Meridian Link manual.

Input Parameters

Name

Description

LoginID

Avaya TS login ID

Password

Avaya TS password, if one was assigned

AgentID

Phone login ID

AgentPassword

Phone password

180 VTel Automation Server Programmer Guide

Methods

Name

Description

StationID

Station or equipment number for this phoneset

Queue

Queue for assignment

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim LoginID As String Dim Password As String Dim AgentID As String Dim AgentPassword As String Dim StationID As String Dim Queue As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.LoginTelephony( LoginID, Password, AgentID, AgentPassword, StationID, Queue ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString LoginID; CString Password; CString AgentID; CString AgentPassword; CString StationID; CString Queue; . . . ResponseHandle = VTel.LoginTelephony( LoginID, Password, AgentID, AgentPassword, StationID, Queue );

Issue 2.1 August 2003

181

API Methods: Descriptions

LoginTelephonySynch Syntax

Description

Language

Syntax

IDL

BOOL LoginTelephonySynch( in string LoginID, in string Password, in string AgentID, in string AgentPassword, in string StationID, in string Queue )

Visual C++

BOOL LoginTelephonySynch( LPCTSTR LoginID, LPCTSTR Password, LPCTSTR AgentID, LPCTSTR AgentPassword, LPCTSTR StationID, LPCTSTR Queue )

Visual Basic

LoginTelephonySynch( ByVal LoginID As String, ByVal Password As String, ByVal AgentID As String, ByVal AgentPassword As String, ByVal StationID As String, ByVal Queue As String ) As Boolean

Issue the VTel.LoginTelephony request synchronously. Directs VTel to assign and log into the Telephony and EDU Servers. LoginVESP() must be called before LoginTelephony(). This method allows a two-step process for logging into VTel. It is paired with LogoutTelephonySynch(). This will return an error for an invalid login, or if another login is currently in progress. The agent, station, and queue parameters may not be needed, depending on your configuration and the type of login desired. For the Meridian Link, AgentID corresponds to the position ID and StationID to the equipment number. The agent ID (if agent ID software is being used) can only be entered through IC Manager; it cannot be entered through VTel. See the Agent Configuration section of the Telephony Services for the Northern Telecom Meridian Link manual.

Input Parameters

Name

Description

LoginID

Avaya TS login ID

Password

Avaya TS password, if one was assigned

AgentID

Phone login ID

AgentPasswor d

Phone password

182 VTel Automation Server Programmer Guide

Methods

Name

Description

StationID

Station or equipment number for this phoneset

Queue

Queue for assignment

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim LoginID As String Dim Password As String Dim AgentID As String Dim AgentPassword As String Dim StationID As String Dim Queue As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.LoginTelephonySynch( LoginID, Password, AgentID, AgentPassword, StationID, Queue ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString LoginID; CString Password; CString AgentID; CString AgentPassword; CString StationID; CString Queue; . . . Status = VTel.LoginTelephonySynch( LoginID, Password, AgentID, AgentPassword, StationID, Queue );

Issue 2.1 August 2003

183

API Methods: Descriptions

LoginVESP Syntax

Description

Language

Syntax

IDL

long LoginVESP( in string LoginID, in string Password )

Visual C++

long LoginVESP( LPCTSTR LoginID, LPCTSTR Password )

Visual Basic

LoginVESP( ByVal LoginID As String, ByVal Password As String ) As Long

Issue the VTel.LoginVESP request asynchronously. Directs VTel to log in to the Telephony system only. No phone assignments are made. This will return an error for an invalid login, or if another login is currently in progress.

Input Parameters

LoginID:Avaya TS login ID

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim LoginID As String Dim Password As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.LoginVESP( LoginID, Password ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString LoginID; CString Password; . . . ResponseHandle = VTel.LoginVESP( LoginID, Password );

Password:Avaya TS password, if one was assigned

184 VTel Automation Server Programmer Guide

Methods

LoginVESPSynch Syntax

Description

Language

Syntax

IDL

BOOL LoginVESPSynch( in string LoginID, in string Password )

Visual C++

BOOL LoginVESPSynch( LPCTSTR LoginID, LPCTSTR Password )

Visual Basic

LoginVESPSynch( ByVal LoginID As String, ByVal Password As String ) As Boolean

Issue the VTel.LoginVESP request synchronously. Directs VTel to log in to the Telephony system only. No phone assignments are made. This will return an error for an invalid login, or if another login is currently in progress.

Input Parameters

Name

Description

LoginID

Avaya TS login ID

Password

Avaya TS password, if one was assigned

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim LoginID As String Dim Password As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.LoginVESPSynch( LoginID, Password ) Mutex = False

Issue 2.1 August 2003

185

API Methods: Descriptions

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString LoginID; CString Password; . . . Status = VTel.LoginVESPSynch( LoginID, Password );

Logout Syntax

Description

Language

Syntax

IDL

long Logout( )

Visual C++

long Logout( )

Visual Basic

Logout( ) As Long

Issue the VTel.Logout request asynchronously. Directs VTel to log out from the Telephony system, deassigning the agent's telephone set. This will fail if there is any work in progress. Work in progress includes active phone calls and VDUs that have not been terminated because of either a WrapUp state or an application locking the resources. If the VTel GUI was visible before logout, it will be hidden after logout and the user will not be prompted for another login, unless a GuiLogin() request is made. This allows the external application to display its own login interface, or to determine when the VTel login dialog is visible.

Input Parameters

None.

Output Parameters

None.

Return Value

Returns handle to the expected response.

186 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.Logout( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; . . . ResponseHandle = VTel.Logout( );

LogoutSynch Syntax

Description

Language

Syntax

IDL

BOOL LogoutSynch( )

Visual C++

BOOL LogoutSynch( )

Visual Basic

LogoutSynch( ) As Boolean

Issue the VTel.Logout request synchronously. Directs VTel to log out from the Telephony system, deassigning the agent's telephone set. This will fail if there is any work in progress. Work in progress includes active phone calls and VDUs that have not been terminated because of either a WrapUp state or an application locking the resources. If the VTel GUI was visible before logout, it will be hidden after logout and the user will not be prompted for another login, unless a GuiLogin() request is made. This allows the external application to display its own login interface, or to determine when the VTel login dialog is visible.

Input Parameters

None.

Output Parameters

None.

Issue 2.1 August 2003

187

API Methods: Descriptions

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.LogoutSynch( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; . . . Status = VTel.LogoutSynch( );

LogoutTelephony Syntax

Description

Language

Syntax

IDL

long LogoutTelephony( in string retry_limit, in string wait_secs )

Visual C++

long LogoutTelephony( LPCTSTR retry_limit, LPCTSTR wait_secs )

Visual Basic

LogoutTelephony( ByVal retry_limit As String, ByVal wait_secs As String ) As Long

Issue the VTel.LogoutTelephony request asynchronously. Directs VTel to deassign and log out of the Telephony and EDU Servers. LogoutVESP() must be called after LogoutTelephony(). This method will fail (i.e., a given try will fail) if there is any work in progress. Work in progress includes active phone calls and VDUs that have not been terminated because of either a WrapUp state or an application locking the resources. If retry_limit is -1, retries will occur at intervals of wait_secs until success is achieved.

188 VTel Automation Server Programmer Guide

Methods

If retry_limit is a positive integer, a maximum of that many retries will occur, with an interval of wait_secs between each try. A response will not be returned until success is achieved or until the retry_limit has been reached. If the request was ultimately unsuccessful, an error response is returned. This method allows a two-step process for logging out of VTel. It is paired with LoginTelephony(). If the VTel GUI was visible before logout, it will be hidden after logout and the user will not be prompted for another login, unless a GuiLogin() request is made. This allows the external application to display its own login interface, or to determine when the VTel login dialog is visible. Input Parameters

Name

Description

retry_limit

Number of attempts to make (the default is 0)

wait_secs

Number of seconds between attempts (the default is 0)

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim retry_limit As String Dim wait_secs As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.LogoutTelephony( retry_limit, wait_secs ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString retry_limit; CString wait_secs; . . . ResponseHandle = VTel.LogoutTelephony( retry_limit, wait_secs );

Issue 2.1 August 2003

189

API Methods: Descriptions

LogoutTelephonySynch Syntax

Description

Language

Syntax

IDL

BOOL LogoutTelephonySynch( in string retry_limit, in string wait_secs )

Visual C++

BOOL LogoutTelephonySynch( LPCTSTR retry_limit, LPCTSTR wait_secs )

Visual Basic

LogoutTelephonySynch( ByVal retry_limit As String, ByVal wait_secs As String ) As Boolean

Issue the VTel.LogoutTelephony request synchronously. Directs VTel to deassign and log out of the Telephony and EDU Servers. LogoutVESP() must be called after LogoutTelephony(). This method will fail (i.e., a given try will fail) if there is any work in progress. Work in progress includes active phone calls and VDUs that have not been terminated because of either a WrapUp state or an application locking the resources. If retry_limit is -1, retries will occur at intervals of wait_secs until success is achieved. If retry_limit is a positive integer, a maximum of that many retries will occur, with an interval of wait_secs between each try. A response will not be returned until success is achieved or until the retry_limit has been reached. If the request was ultimately unsuccessful, an error response is returned. This method allows a two-step process for logging out of VTel. It is paired with LoginTelephonySynch(). If the VTel GUI was visible before logout, it will be hidden after logout and the user will not be prompted for another login, unless a GuiLogin() request is made. This allows the external application to display its own login interface, or to determine when the VTel login dialog is visible.

Input Parameters

Output Parameters

Name

Description

retry_limit

Number of attempts to make (the default is 0)

wait_secs

Number of seconds between attempts (the default is 0)

None.

190 VTel Automation Server Programmer Guide

Methods

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim retry_limit As String Dim wait_secs As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.LogoutTelephonySynch( retry_limit, wait_secs ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString retry_limit; CString wait_secs; . . . Status = VTel.LogoutTelephonySynch( retry_limit, wait_secs );

LogoutVESP Syntax

Description

Language

Syntax

IDL

long LogoutVESP( )

Visual C++

long LogoutVESP( )

Visual Basic

LogoutVESP( ) As Long

Issue the VTel.LogoutVESP request asynchronously. Directs VTel to log out from the Telephony system only; does not deassign the agent's telephone set. This method will fail if LoginVESP() has not been issued or if there is any work in progress. Work in progress includes active phone calls and VDUs that have not been terminated because of either a WrapUp state or an application locking the resources. If the VTel GUI was visible before logout, it will be hidden after logout and the user will not be prompted for another login, unless a GuiLogin() request is made. This

Issue 2.1 August 2003

191

API Methods: Descriptions

allows the external application to display its own login interface, or to determine when the VTel login dialog is visible. Input Parameters

None.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.LogoutVESP( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; . . . ResponseHandle = VTel.LogoutVESP( );

LogoutVESPSynch Syntax

Description

Language

Syntax

IDL

BOOL LogoutVESPSynch( )

Visual C++

BOOL LogoutVESPSynch( )

Visual Basic

LogoutVESPSynch( ) As Boolean

Issue the VTel.LogoutVESP request synchronously. Directs VTel to log out from the Telephony system only; does not deassign the agent's telephone set. This method will fail if LoginVESP() has not been issued or if there is any work in progress. Work in progress includes active phone calls and VDUs that have not

192 VTel Automation Server Programmer Guide

Methods

been terminated because of either a WrapUp state or an application locking the resources. If the VTel GUI was visible before logout, it will be hidden after logout and the user will not be prompted for another login, unless a GuiLogin() request is made. This allows the external application to display its own login interface, or to determine when the VTel login dialog is visible. Input Parameters

None.

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.LogoutVESPSynch( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; . . . Status = VTel.LogoutVESPSynch( );

Issue 2.1 August 2003

193

API Methods: Descriptions

MakeCall Syntax

Description

Language

Syntax

IDL

long MakeCall( in string PhoneOrig, in string PhoneDest )

Visual C++

long MakeCall( LPCTSTR PhoneOrig, LPCTSTR PhoneDest )

Visual Basic

MakeCall( ByVal PhoneOrig As String, ByVal PhoneDest As String ) As Long

Issue the VTel.MakeCall request asynchronously. Directs VTel to initiate a call on the selected phone line. Race conditions may occur if a telephone call arrives simultaneously with an attempt to make an outgoing call, resulting in an error return. If the phone can be set to a busy state, this will prevent queue calls, but direct calls typically cannot be held off. Depending on the available outbound line appearances and the destination (internal or outside line), this request may fail. Some of these failures cannot be easily predicted due to the number of factors involved.

Input Parameters

Name

Description

PhoneOrig

Dialable number, UserID, or null (default phone) for the phone from which the outbound call is originating.

PhoneDest

Dialable number, UserID, or ACD queue of the phone that is the destination of the outbound call.

Output Parameters

None.

Return Value

Returns handle to the expected response.

194 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim PhoneNumber As String Dim Destination As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.MakeCall( PhoneNumber, Destination ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString PhoneNumber; CString Destination; . . . ResponseHandle = VTel.MakeCall( PhoneNumber, Destination );

MakeCallSynch Syntax

Description

Language

Syntax

IDL

BOOL MakeCallSynch( in string PhoneOrig, in string PhoneDest, out string VduID )

Visual C++

BOOL MakeCallSynch( LPCTSTR PhoneOrig, LPCTSTR PhoneDest, CString& VduID )

Visual Basic

MakeCallSynch( ByVal PhoneOrig As String, ByVal PhoneDest As String, VduID As String ) As Boolean

Issue the VTel.MakeCall request synchronously. Directs VTel to initiate a call on the selected phone line. Race conditions may occur if a telephone call arrives simultaneously with an attempt to make an outgoing call, resulting in an error return. If the phone can be set to a busy state, this will prevent queue calls, but direct calls typically cannot be held off. Depending on the available outbound line appearances and the destination (internal or outside line), this request may fail. Some of these failures cannot be easily predicted due to the number of factors involved.

Issue 2.1 August 2003

195

API Methods: Descriptions

Input Parameters

Output Parameters

Name

Description

PhoneOrig

Dialable number, UserID, or null (default phone) for the phone from which the outbound call is originating

PhoneDest

Dialable number, UserID, or ACD queue of the phone that is the destination of the outbound call

Name

Description

VduID

The VDUID of the completed telephone call

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim PhoneNumber As String Dim Destination As String Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.MakeCallSynch( PhoneNumber, Destination, VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProy VTel; BOOL Status; CString PhoneNumber; CString Destination; CString VduID; . . . Status = VTel.MakeCallSynch( PhoneNumber, Destination, VduID );

196 VTel Automation Server Programmer Guide

Methods

MakeRequest Syntax

Description Input Parameters

Output Parameters

Return Value

Language

Syntax

IDL

void MakeRequest( in string Request, out long OutResponseHandle )

Visual C++

void MakeRequest( LPCTSTR Request, long* OutResponseHandle )

Visual Basic

MakeRequest( ByVal Request As String, OutResponseHandle As Long )

Asynchronously posts a request to VTel and returns a handle that can be used to get the response (via GetResponseString(), etc.).

Name

Description

Request

The desired request, formatted using Avaya TS syntax. You will find this syntax documented in the "Message Syntax" chapter of VTel Programmer Guide. Currently, no functions are provided to assist you in formatting your requests. However, these may be available in a subsequent release.

Name

Description

OutResponseHandle

You can use the returned handle to process the response as soon as it is available. In this case, you will need to call WaitForResponse() to ensure that the response has arrived before invoking any response processing methods. In nearly all cases, however, you will simply process the response elsewhere, in a timer or idle function. Response processing functions are described in Response processing methods on page 57.

None.

Issue 2.1 August 2003

197

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long . . . Private Sub Call_Click() ' Use the default phone to call extension 4004. Mutex = True VTel.MakeRequest "[VTel.MakeCall("""",""4004"",)]", ResponseHandle Mutex = False End Sub Private Sub PollingTimer_Timer() Dim ResponseName As String Dim ResponseExists As Boolean ' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then ' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.MakeCall": ' Response from MakeCall request, display new VduID VTel.GetMakeCallResponse ResponseHandle, VduID VduIDTextBox.Text = VduID Case "VTel.Logout": . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

198 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

#include "VProxy.h" CVTelProxy

VTel;

void OnCallButtonPress() { long ResponseHandle; . . . VTel.MakeRequest("[VTel.MakeCall("","4004",)]", ResponseHandle); } // What follows will be in an OnIdle() or OnTimer() function long NextResponse; // Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) case 0: // The response was "VTel.Error". Check the response // details for more information. They will most likely // show that the request syntax was invalid. AfxMessageBox("Response was VTel.Error"); break; case -1: // The response handle from GetResponseType() was invalid// should not happen. AfxMessageBox("Internal error in Automation Server!"); break; case -2: // Server response queue overrun, we must have forgotten // to free responses! AfxMessageBox("Server ran out of space and dropped responses."); break; case // // //

-3: Unrecognized response type, no response code available. Use GetResponseName() to obtain the name of a new type of response. . . .

Issue 2.1 August 2003

199

API Methods: Descriptions

case 22: // MakeCall. Use specific response parsing routine to obtain // the associated VDUID. CString VduID; if ( VTel.GetMakeCallResponse(ResponseHandle, VduID) ) { // Response was OK. Do something with this VDUID such as // add it to a collection of active calls. . . . } else { // Response indicates error, get specifics. VTel.GetResponseDetail(ResponseHandle, Origin, ErrorCode, Description, ReturnCode); . . . } break; case 15: // Hangup is handled as a generic response. if ( VTel.GetResponseStatus(ResponseHandle) ) { // Response was OK. Do something such as set the call // state. . . . } else { // Response indicates error, get specifics. VTel.GetResponseDetail(ResponseHandle, Origin, ErrorCode, Description, ReturnCode); . . . } break; default: // Not handling any other responses } // We are done with the response, release resources. VTel.FreeResponse(NextResponse); } else {

200 VTel Automation Server Programmer Guide

Methods

// No response waiting, do some other work . . . } }

MakeRequestSynch Syntax

Description

Input Parameters

Output Parameters

Language

Syntax

IDL

BOOL MakeRequestSynch( in string Request, out long OutResponseHandle )

Visual C++

BOOL MakeRequestSynch( LPCTSTR Request, long* OutResponseHandle )

Visual Basic

MakeRequestSynch( ByVal Request As String, OutResponseHandle As Long ) As Boolean

Synchronously posts a request to VTel and returns a handle that can be used to get the response (via GetResponseString(), etc.). If no response is received, OutResponseHandle will be set to 0.

Name

Description

Request

The desired request, formatted using Avaya TS syntax. You will find this syntax documented in the "Message Syntax" chapter of Vtel Programmer Guide. Currently, no functions are provided to assist you in formatting your requests. However, these may be available in a subsequent release.

Name

Description

OutResponseHandle

You can use the returned handle to process the response as soon as it is available. The responses returned by MakeRequestSynch() are not available to response-processing timer or idle functions. Nor does SupressResponse() have any effect on the responses returned by MakeRequestSynch(). Therefore, these responses must be freed.

Issue 2.1 August 2003

201

API Methods: Descriptions

Return Value Visual Basic Example

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Dim Dim Dim Dim Dim Dim Dim . . .

VTel As Object Status As Boolean ResponseHandle As Long Origin As String ErrorCode As String Description As String ReturnCode As String

' Use the default phone to call extension 4004. Mutex = True Status = VTel.MakeRequestSynch("[VTel.MakeCall("""",""4004"",)]", ResponseHandle) Mutex = False Mutex = True If VTel.GetMakeCallResponse(ResponseHandle, VduID) = True Then Mutex = False // Response was OK. Do something with this VDUID such as add it to a //collection of active calls. . . . Else: Mutex = False // Response indicates error, get specifics. Mutex = True VTel.GetResponseDetail ResponseHandle, Origin, ErrorCode, Description, ReturnCode; Mutex = False . . . End If Mutex = True VTel.FreeResponse ResponseHandle Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; long ResponseHandle; CString VduID; . . .

202 VTel Automation Server Programmer Guide

Methods

Status = VTel.MakeRequestSynch("[VTel.MakeCall("","4004",)]", ResponseHandle); { . Status = VTel.MakeRequestSynch("[VTel.MakeCall("","4004",)]", ResponseHandle); // Response was OK. Do something with this VDUID such as // add it to a collection of active calls. . . . } else { // Response indicates error, get specifics. VTel.GetResponseDetail(ResponseHandle, Origin, ErrorCode, Description, ReturnCode); . . . } VTel.FreeResponse(ResponseHandle);

PeekEvent Syntax

Description

Language

Syntax

IDL

BOOL PeekEvent( out long OutEventHandle )

Visual C++

BOOL PeekEvent( long* OutEventHandle )

Visual Basic

PeekEvent( OutEventHandle As Long ) As Boolean

Assigns the handle of the first event in the queue to OutEventHandle. Leaves OutEventHandle unmodified if the queue is empty. PeekEvent() and PeekResponse() are the workhorses of your program’s event processing routine. Typically, an application will contain a timer or idle loop where PeekEvent() continually looks for new events. When one is found, an event handle is returned. The handle can subsequently be used to obtain event specifics. When no longer needed, the event can be deallocated by passing its handle to FreeEvent().

Input Parameters

None.

Issue 2.1 August 2003

203

API Methods: Descriptions

Output Parameters

Name

Description

OutEventHandle

The handle of an event found in the queue. Note that this value may be 0.

Return Value

Returns FALSE if the queue is empty.

Visual Basic Example

' Handle incoming events. Private Sub Polling_Timer() Dim EventHandle As Long Dim EventCode As Long Dim VduID As String If Mutex = True then Exit Sub ' Handle all currently queued events While (VTelConnected = True) And (VTel.PeekEvent(EventHandle) = True) ' Take action based on event code EventCode = VTel.GetEventCode(EventHandle) Select Case EventCode ' Connect Case 3: ' Store away the new VDUID for hang up or anyone else ' who is interested VduID = VTel.GetEventArg(EventHandle, "vdu_id") ' Disconnect Case 4: . . . ' Exit Case 6: ' Quit ' Call any shut-down code here VTel = Nothing End Select ' Was VTel terminated above? If VTelConnected = True Then ' No, clean up event VTel.FreeEvent EventHandle End If Wend End Sub

204 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

// OnTimer() or OnIdle() // Handle incoming events. // long EventHandle; // Do we have a connection to the server? if (m_VTel) { // Handle all currently queued events while (m_VTel && m_VTel->PeekEvent(&EventHandle)) { // Take action based on event code switch ( m_VTel->GetEventCode(EventHandle) ) { // Connect case 3: // Store away the new VDUID for hang up or anyone else // who is interested m_vduID = m_VTel->GetEventArg(EventHandle, "vdu_id"); break; // Disconnect case 4: . . . break; // Exit case 6: // Quit PostQuitMessage(0); delete m_VTel; m_VTel = 0; break; } // Was m_VTel deleted above? if (m_VTel) { // No, clean up event VERIFY( m_VTel->FreeEvent(EventHandle) ); } . . .

Issue 2.1 August 2003

205

API Methods: Descriptions

PeekResponse Syntax

Description

Language

Syntax

IDL

BOOL PeekResponse( out long OutResponseHandle )

Visual C++

BOOL PeekResponse( long* OutResponseHandle )

Visual Basic

PeekResponse( OutResponseHandle As Long ) As Boolean

Assigns the handle of the first response in the queue to OutResponseHandle. Leaves OutResponseHandle unmodified if the queue is empty. PeekResponse() and PeekEvent() are the workhorses of your program’s response processing routine. Typically, an application will contain a timer or idle loop where PeekResponse() continually looks for new responses to asynchronous requests. When one is found, a response handle is returned. The handle can subsequently be used to obtain response specifics. When no longer needed, the response can be deallocated by passing its handle to FreeResponse().

Input Parameters Output Parameters

None.

Name

Description

OutResponseHandle

The handle of a response found in the queue. Note that the value may be 0.

Return Value

Returns FALSE if the queue is empty.

Visual Basic Example

Private Sub PollingTimer_Timer() Dim ResponseName As String Dim ResponseExists As Boolean Dim ResponseHandle As Long ' Only execute if "VTel" object variable is bound to running server If IsConnected = True Then ' Is there a response to process? If Mutex = True then Exit Sub ResponseExists = VTel.PeekResponse(ResponseHandle) If ResponseExists = True Then

206 VTel Automation Server Programmer Guide

Methods

' Yes, take action based on the response name ResponseName = VTel.GetResponseName(ResponseHandle) Select Case ResponseName Case "VTel.MakeCall": ' Response from MakeCall request, display new VDUID VTel.GetMakeCallResponse ResponseHandle, VduID VduIDTextBox.Text = VduID Case "VTel.Logout": . . . End Select ' Release server resources VTel.FreeResponse ResponseHandle End If End If End Sub

Visual C++ Example

// OnTimer() or OnIdle() long NextResponse; // Process all queued responses without blocking while (1) { // Is there a response waiting? if ( VTel.PeekResponse(&NextResponse) ) { // Yes, figure out what it is switch ( VTel.GetResponseCode(NextResponse) ) { case 22: // MakeCall. Use specific response parsing routine to obtain the // associated VDUID. . . . break; case 15: // Hangup is handled as a generic response. . . . break; default: // Not handling any other responses } // We are done with the response, release resources.

Issue 2.1 August 2003

207

API Methods: Descriptions

VTel.FreeResponse(NextResponse); . . .

Ping Syntax

Description

Language

Syntax

IDL

long Ping( )

Visual C++

long Ping( )

Visual Basic

Ping( ) As Long

Issue the VTel.Ping request asynchronously. Tests the connection (i.e., OLE) to ensure that VTel is still responding to requests. As this only tests the connection to VTel, it does not require a valid login.

Input Parameters

None.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.Ping( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; . . . ResponseHandle = VTel.Ping( );

208 VTel Automation Server Programmer Guide

Methods

PingSynch Syntax

Description

Language

Syntax

IDL

BOOL PingSynch( )

Visual C++

BOOL PingSynch( )

Visual Basic

PingSynch( ) As Boolean

Issue the VTel.Ping request synchronously. Tests the connection (i.e., OLE) to ensure that VTel is still responding to requests. As this only tests the connection to VTel, it does not require a valid login.

Input Parameters

None.

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.PingSynch( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; . . . Status = VTel.PingSynch( );

Issue 2.1 August 2003

209

API Methods: Descriptions

Ready Syntax

Description

Language

Syntax

IDL

long Ready( in string PhoneNumber )

Visual C++

long Ready( LPCTSTR PhoneNumber )

Visual Basic

Ready( ByVal PhoneNumber As String ) As Long

Issue the VTel.Ready request asynchronously. If not in an active ACD call, sets a phone to the ready state. From within an ACD call, may either preset the call in the ready state or hang up the call, placing the phone in the ready state. This method is dependent on the telephone switch and the type of phone assigned. Refer to the IDL chapter of your Telephony Services manual. This method does not typically affect inbound calls that are not processed through a queue.

Input Parameters

Name

Description

PhoneNumber

Dialable number or null (default phone).

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.Ready( PhoneNumber ) Mutex = False

210 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString PhoneNumber; . . . ResponseHandle = VTel.Ready( PhoneNumber );

ReadyOverride Syntax

Description

Language

Syntax

IDL

long ReadyOverride( in string PhoneNumber )

Visual C++

long ReadyOverride( LPCTSTR PhoneNumber )

Visual Basic

ReadyOverride( ByVal PhoneNumber As String ) As Long

Issue the VTel.ReadyOverride request asynchronously. If in call, and presets are on, changes the current preset to Ready and disallows any attempts to change the preset for the remainder of the call, unless by means of another override command (BusyOverride, WrapUpOverride). If not in call, or presets are not on, behaves like the Ready command. This method is dependent on the telephone switch and the type of phone assigned. Refer to the IDL chapter of your Telephony Services manual.

Input Parameters

Name

Description

PhoneNumber

Dialable number or null (default phone).

Output Parameters

None.

Return Value

Returns handle to the expected response.

Issue 2.1 August 2003

211

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.ReadyOverride( PhoneNumber ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString PhoneNumber; . . . ResponseHandle = VTel.ReadyOverride( PhoneNumber );

ReadyOverrideSynch Syntax

Description

Language

Syntax

IDL

BOOL ReadyOverrideSynch( in string PhoneNumber )

Visual C++

BOOL ReadyOverrideSynch( LPCTSTR PhoneNumber )

Visual Basic

ReadyOverrideSynch( ByVal PhoneNumber As String ) As Boolean

Issue the VTel.ReadyOverride request synchronously. If in call, and presets are on, changes the current preset to Ready and disallows any attempts to change the preset for the remainder of the call, unless by means of another override command (BusyOverride, WrapUpOverride). If not in call, or presets are not on, behaves like the ReadySynch command. This method is dependent on the telephone switch and the type of phone assigned; refer to the IDL chapter of your Telephony Services manual.

Input Parameters

Name

Description

PhoneNumber

Dialable number or null (default phone).

212 VTel Automation Server Programmer Guide

Methods

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.ReadyOverrideSynch( PhoneNumber ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString PhoneNumber; . . . Status = VTel.ReadyOverrideSynch( PhoneNumber );

ReadyPhoneset Syntax

Description

Language

Syntax

IDL

long ReadyPhoneset( )

Visual C++

long ReadyPhoneset( )

Visual Basic

ReadyPhoneset( ) As Long

Issue the VTel.ReadyPhoneset request asynchronously. If there are no active calls, this sets the entire phoneset to the Ready state. If there are active calls, the result is switch dependent (see the documentation for your telephone switch). This method is dependent on the telephone switch; refer to the IDL chapter of your Telephony Services manual to determine availability.

Input Parameters

None.

Issue 2.1 August 2003

213

API Methods: Descriptions

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.ReadyPhoneset( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; . . . ResponseHandle = VTel.ReadyPhoneset( );

ReadyPhonesetSynch Syntax

Description

Language

Syntax

IDL

BOOL ReadyPhonesetSynch( )

Visual C++

BOOL ReadyPhonesetSynch( )

Visual Basic

ReadyPhonesetSynch( ) As Boolean

Issue the VTel.ReadyPhoneset request synchronously. If there are no active calls, this sets the entire phoneset to the Ready state. If there are active calls, the result is switch dependent (see the documentation for your telephone switch). This method is dependent on the telephone switch; refer to the IDL chapter of your Telephony Services manual to determine availability.

Input Parameters

None.

Output Parameters

None.

214 VTel Automation Server Programmer Guide

Methods

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.ReadyPhonesetSynch( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; . . . Status = VTel.ReadyPhonesetSynch( );

ReadySynch Syntax

Description

Language

Syntax

IDL

BOOL ReadySynch( in string PhoneNumber )

Visual C++

BOOL ReadySynch( LPCTSTR PhoneNumber )

Visual Basic

ReadySynch( ByVal PhoneNumber As String ) As Boolean

Issue the VTel.Ready request synchronously. If not in an active ACD call, sets a phone to the ready state. From within an ACD call, may either preset the call in the ready state or hang up the call, placing the phone in the ready state. This method is dependent on the telephone switch and the type of phone assigned; refer to the IDL chapter of your Telephony Services manual. This method does not typically affect inbound calls that are not processed through a queue.

Issue 2.1 August 2003

215

API Methods: Descriptions

Input Parameters

Name

Description

PhoneNumber

Dialable number or null (default phone).

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.ReadySynch( PhoneNumber ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString PhoneNumber; . . . Status = VTel.ReadySynch( PhoneNumber );

ResetPhones Syntax

Description

Language

Syntax

IDL

long ResetPhones( )

Visual C++

long ResetPhones( )

Visual Basic

ResetPhones( ) As Long

Issue the VTel.ResetPhones request asynchronously. For use when VTel has lost sync with the teleset. This method clears all current telephony activity from

216 VTel Automation Server Programmer Guide

Methods

VTel, terminating all calls and VDUs. The user should complete all business with active calls before this method is called. As this method is used for recovery from synchronization errors, any additional errors received during the execution of this method are ignored. Input Parameters

None.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.ResetPhones( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; . . . ResponseHandle = VTel.ResetPhones( );

ResetPhonesSynch Syntax

Description

Language

Syntax

IDL

BOOL ResetPhonesSynch( )

Visual C++

BOOL ResetPhonesSynch( )

Visual Basic

ResetPhonesSynch( ) As Boolean

Issue the VTel.ResetPhones request synchronously. For use when VTel has lost sync with the teleset. This method clears all current telephony activity from

Issue 2.1 August 2003

217

API Methods: Descriptions

VTel, terminating all calls and VDUs. The user should complete all business with active calls before this method is called. As this method is used for recovery from synchronization errors, any additional errors received during the execution of this method are ignored. Input Parameters

None.

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.ResetPhonesSynch( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; . . . Status = VTel.ResetPhonesSynch( );

RestartServer Syntax Language

Syntax

IDL

long RestartServer( in string Server, in long RetryLimit, in long WaitSeconds )

Visual C++

long RestartServer( LPCTSTR Server, long RetryLimit, long WaitSeconds )

Visual Basic

RestartServer( ByVal Server As String, ByVal RetryLimit As Long, ByVal WaitSeconds As Long ) As Long

218 VTel Automation Server Programmer Guide

Methods

Description

Issue the VTel.RestartServer request asynchronously. Attempts to restart the server specified, restoring the connection with the same user login information that was used previously. When the server restarts, call state and information context will have been lost. This request is ignored if the server has already restarted.

Input Parameters

Name

Definition

Server

The name of the server (e.g., "TS") to be restarted.

RetryLimit

The number of restart attempts to make.

WaitSeconds

The number of seconds to wait between attempts.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.RestartServer("VDU", 3, 3) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; . . . ResponseHandle = VTel.RestartServer("VDU", 3, 3);

Issue 2.1 August 2003

219

API Methods: Descriptions

RestartServerSynch Syntax

Description

Language

Syntax

IDL

BOOL RestartServerSynch( in string Server, in long RetryLimit, in long WaitSeconds )

Visual C++

BOOL RestartServerSynch( LPCTSTR Server, long RetryLimit, long WaitSeconds)

Visual Basic

RestartServerSynch( ByVal Server As String, ByVal RetryLimit As Long, ByVal WaitSeconds As Long ) As Boolean

Issue the VTel.RestartServer request synchronously. Attempts to restart the server specified, restoring the connection with the same user login information that was used previously. When the server restarts, call state and information context will have been lost. This request is ignored if the server has already restarted.

Input Parameters

Name

Description

Server

The name of the server (e.g., "TS") to be restarted.

RetryLimit

The number of restart attempts to make.

WaitSeconds

The number of seconds to wait between attempts.

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.RestartServerSynch("VDU", 3, 3) Mutex = False

220 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; . . . Status = VTel.RestartServerSynch("VDU", 3, 3);

Rona Syntax

Description

Language

Syntax

IDL

BOOL Rona ( in string VDUID )

Visual C++

BOOL Rona ( LPCTSTR VDUID )

Visual Basic

Rona ( ByVal VDUID As String ) As Boolean

RONA is an acronym for Return On No Answer. If VTel.Rona is called, it reroutes the call associated with the VDUID.

Input Parameters

Name

Description

VduID

The VDUID of the unanswered call.

Output Parameters

None.

Return Value

Status of method call.

Note:

Note: Make sure to set the TS configuration parameter "rona_default_dn" in ICManager, otherwise, the TS.Rona() request will fail. The Telephony Server needs to be directed where to return the call. For example, the rona_default_dn parameter can be a queue which would route the call back to the queue whence it came for another agent to handle.

Issue 2.1 August 2003

221

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Dim VduID As String Dim Status as Boolean Set VTel = CreateObject("VTEL.SESSION") . . . Status = VTel.Rona( VduID )

Visual C++ Example

#include "VProxy.h" CVTelProxy Bool long . . . Status = VTel.Rona(

VTel; Status VduID;

VduID );

SendDefinityAux Syntax

Description

Input Parameters

Language

Syntax

IDL

long SendDefinityAux( in string ReasonCode )

Visual C++

long SendDefinityAux( LPCTSTR ReasonCode )

Visual Basic

SendDefinityAux( ByVal ReasonCode As String ) As Long

Issue the VTel.SendDefinityAux request asynchronously. Puts the agent into the Busy (Auxiliary Work) state and sends the Aux reason code to the DEFINITY switch.

Name

Description

ReasonCode

The single digit (0-9) Aux reason code.

Output Parameters

None.

Return Value

Returns handle to the expected response.

222 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim ReasonCode As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.SendDefinityAux( ReasonCode ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString ReasonCode; . . . ResponseHandle = VTel.SendDefinityAux( ReasonCode );

SendDefinityAuxSynch Syntax

Description

Input Parameters

Output Parameters

Language

Syntax

IDL

long SendDefinityAuxSynch( in string ReasonCode )

Visual C++

long SendDefinityAuxSynch( LPCTSTR ReasonCode )

Visual Basic

SendDefinityAuxSynch( ByVal ReasonCode As String ) As Long

Issue the VTel.SendDefinityAux request synchronously. Puts the agent into the Busy (Auxiliary Work) state and sends the Aux reason code to the DEFINITY switch.

Name

Description

ReasonCode

The single digit (0-9) Aux reason code.

None.

Issue 2.1 August 2003

223

API Methods: Descriptions

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim ReasonCode As String Set VTel = CreateObject("VTEL.SESSION") . . Mutex = True Status = VTel.SendDefinityAuxSynch( ReasonCode ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; Bool Status; CString ReasonCode; . . . Status = VTel.SendDefinityAuxSynch( ReasonCode );

SendDefinityLogout Syntax

Description Input Parameters

Language

Syntax

IDL

long SendDefinityLogout( in string Queue, in string Extension, in string ReasonCode )

Visual C++

long SendDefinityLogout( LPCTSTR Queue, LPCTSTR Extension, LPCTSTR ReasonCode )

Visual Basic

SendDefinityLogout( ByVal Queue As String, ByVal Extension As String, ByVal ReasonCode As String ) As Long

Issue the VTel.SendDefinityLogout request asynchronously. Logs out the agent and sends the Logout reason code to the DEFINITY switch.

Name

Definition

Queue

The queue the agent is logged into

224 VTel Automation Server Programmer Guide

Methods

Name

Definition

Extension

The extension the agent is logged into

ReasonCode

The single digit (0-9) Logout reason code

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim Queue As String Dim Extension As String Dim ReasonCode As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.SendDefinityLogout( Queue, Extension, ReasonCode ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString Queue; CString Extension; CString ReasonCode; . . . ResponseHandle = VTel.SendDefinityLogout( Queue, Extension, ReasonCode );

Issue 2.1 August 2003

225

API Methods: Descriptions

SendDefinityLogoutSynch Syntax

Description Input Parameters

Language

Syntax

IDL

long SendDefinityLogoutSynch( in string Queue, in string Extension, in string ReasonCode )

Visual C++

long SendDefinityLogoutSynch( LPCTSTR Queue, LPCTSTR Extension, LPCTSTR ReasonCode )

Visual Basic

SendDefinityLogoutSynch( ByVal Queue As String, ByVal Extension As String, ByVal ReasonCode As String ) As Long

Issue the VTel.SendDefinityLogout request synchronously. Logs out the agent and sends the Logout reason code to the DEFINITY switch.

Name

Description

Queue

The queue the agent is logged into

Extension

The extension the agent is logged into

ReasonCode

The single digit (0-9) Logout reason code

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim Queue As String Dim Extension As String Dim ReasonCode As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.SendDefinityLogoutSynch( Queue, Extension, ReasonCode ) Mutex = False

226 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; Bool Status; CString Queue; CString Extension; CString ReasonCode; . . . Status = VTel.SendDefinityLogoutSynch( Queue, Extension, ReasonCode );

SendDTMFtones Syntax

Description Input Parameters

Language

Syntax

IDL

long SendDTMFtones( in string VduID, in string Tones,)

Visual C++

long SendDTMFtones( LPCTSTR VduID, LPCTSTR Tones )

Visual Basic

SendDTMFtones( ByVal VduID As String, ByVal Tones As String ) As Long

Issue the VTel.SendDTMFtones request asynchronously. Sends the tones to the DEFINITY switch.

Name

Definition

VduID

The VDUID of a current call.

Tones

The characters that will be sent to the switch as though they were tones entered through a telephone. Valid characters are digits (0-9), *, #.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Issue 2.1 August 2003

227

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Dim Tones As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.SendDTMFtones( VduID, Tones ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; CString Tones; . . . ResponseHandle = VTel.SendDTMFtones( VduID, Tones );

SendDTMFtonesSynch Syntax

Description

Language

Syntax

IDL

long SendDTMFtonesSynch( in string VduID, in string Tones,)

Visual C++

long SendDTMFtonesSynch( LPCTSTR VduID, LPCTSTR Tones )

Visual Basic

SendDTMFtonesSynch( ByVal VduID As String, ByVal Tones As String ) As Long

Issue the VTel.SendDTMFtones request synchronously. Sends the tones to the DEFINITY switch.

228 VTel Automation Server Programmer Guide

Methods

Input Parameters

Language

Syntax

VduID

The VDUID of a current call.

Tones

The characters that will be sent to the switch as though they were tones entered through a telephone. Valid characters are digits (0-9), *, #.

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Dim Tones As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.SendDTMFtonesSynch( VduID, Tones ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; CString Tones; . . . Status = VTel.SendDTMFtonesSynch( VduID, Tones );

Issue 2.1 August 2003

229

API Methods: Descriptions

SeqCoupleCount Syntax

Description Input Parameters

Language

Syntax

IDL

long SeqCoupleCount( in string SeqCouple )

Visual C++

long SeqCoupleCount( LPCTSTR SeqCouple )

Visual Basic

SeqCoupleCount( ByVal SeqCouple As String ) As Long

Returns the number of couples in the sequence.

Name

Description

SeqCouple

A sequence of couples

Output Parameters

None.

Return Value

The number of couples in the sequence as a long.

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim SequenceOfCouples As String Dim Value As String Dim Count As Long Dim Index As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfCouples = VTel.SeqCoupleCreate( ) Status = VTel.VDUGetDataSynch(VduId, SequenceOfCouples) Mutex = False Index = 0 Mutex = True Count = VTel.SeqCoupleCount(SequenceOfCouples) Mutex = False While Index < Count Mutex = True Value = VTel.SeqCoupleGetVal(SequenceOfCouples, Index) Mutex = False Index = Index + 1 .

230 VTel Automation Server Programmer Guide

Methods

. . Wend

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString SequenceOfCouples; CString Value; long Count; . . . SequenceOfCouples = VTel.SeqCoupleCreate( ); Status = VTel.VDUGetDataSynch(VduID, SequenceOfCouples); Count = VTel.SeqCoupleCount(SequenceOfCouples); for (long i=0; i < Count; i++) { Value = VTel.SeqCoupleGetVal(SequenceOfCouples, i); . . . }

SeqCoupleCreate Syntax Language

Syntax

IDL

string SeqCoupleCreate( )

Visual C++

CString SeqCoupleCreate( )

Visual Basic

SeqCoupleCreate( ) As String

Description

Creates and returns an empty sequence of couples.

Input Parameters

None.

Output Parameters

None.

Return Value

An empty sequence of couples as a string.

Visual Basic Example

Dim VTel As Object Dim SequenceOfCouples As String

Issue 2.1 August 2003

231

API Methods: Descriptions

Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfCouples = VTel.SeqCoupleCreate( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; CString SequenceOfCouples; . . . SequenceOfCouples = VTel.SeqCoupleCreate( );

SeqCoupleGet Syntax

Description Input Parameters

Language

Syntax

IDL

string SeqCoupleGet( in string SeqCouple, in string Attribute )

Visual C++

CString SeqCoupleGet( LPCTSTR SeqCouple, LPCTSTR Attribute )

Visual Basic

SeqCoupleGet( ByVal SeqCouple As String, ByVal Attribute As String ) As String

Returns the value associated with Attribute.

Name

Definition

SeqCouple

A sequence of couples.

Attribute

Data element to be returned from the sequence of couples.

Output Parameters

None.

Return Value

Value associated with Attribute.

232 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Dim VTel As Object Dim SequenceOfCouples As String Dim Value As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfCouples = VTel.SeqCoupleCreate( ) Mutex = False Mutex = True SequenceOfCouples = VTel.SeqCoupleSet(SequenceOfCouples, "Account", "123") Mutex = False ' Should yield "123" Mutex = True Value = VTel.SeqCoupleGet(SequenceOfCouples, "Account") Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; CString SequenceOfCouples; CString Value; . . . SequenceOfCouples = VTel.SeqCoupleCreate( ); SequenceOfCouples = VTel.SeqCoupleSet(SequenceOfCouples, "Account","123"); // Should yield "123" Value = VTel.SeqCoupleGet(SequenceOfCouples, "Account");

SeqCoupleGetAttrib Syntax

Description

Language

Syntax

IDL

string SeqCoupleGetAttrib( in string SeqCouple, in long AttributePostion )

Visual C++

CString SeqCoupleGetAttrib( LPCTSTR SeqCouple, long AttributePosition )

Visual Basic

SeqCoupleGetAttrib( ByVal SeqCouple As String, ByVal AttributePosition As Long ) As String

Returns the name of the name/value pair that is at the position specified by AttributePosition.

Issue 2.1 August 2003

233

API Methods: Descriptions

Input Parameters

Name

Description

SeqCouple

A sequence of couples

AttributePosition

Position of the desired couple in the sequence of couples

Output Parameters

None.

Return Value

The name of the name/value pair at the position given by AttributePosition.

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim SequenceOfCouples As String Dim Name As String Dim Count As Long Dim Index As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfCouples = VTel.SeqCoupleCreate( ) Status = VTel.VDUGetDataSynch(VduId, SequenceOfCouples) Mutex = False Index = 0 Mutex = True Count = VTel.SeqCoupleCount(SequenceOfCouples) Mutex = False While Index < Count Mutex = True Name = VTel.SeqCoupleGetAttrib(SequenceOfCouples, Index) Mutex = False Index = Index + 1 . . . Wend

Visual C++ Example

#include "VProxy.h" CVTelProxy BOOL CString CString long . . . SequenceOfCouples =

VTel; Status; SequenceOfCouples; Name; Count;

VTel.SeqCoupleCreate( );

234 VTel Automation Server Programmer Guide

Methods

Status = VTel.VDUGetDataSynch(VduID, SequenceOfCouples); Count = VTel.SeqCoupleCount(SequenceOfCouples); for (long i=0; i < Count; i++) { Name = VTel.SeqCoupleGetAttrib(SequenceOfCouples, i); . . . }

SeqCoupleGetVal Syntax

Description Input Parameters

Language

Syntax

IDL

string SeqCoupleGetVal( in string SeqCouple, in long ValuePostion )

Visual C++

CString SeqCoupleGetVal( LPCTSTR SeqCouple, long ValuePosition )

Visual Basic

SeqCoupleGetVal( ByVal SeqCouple As String, ByVal ValuePosition As Long ) As String

Returns the value of the name/value pair that is at the position specified by ValuePosition.

Name

Description

SeqCouple

A sequence of couples

ValuePosition

Position of the desired couple in the sequence of couples

Output Parameters

None.

Return Value

The value of the name/value pair at the position given by ValuePosition.

Visual Basic Example

Dim Dim Dim Dim

VTel As Object Status As Boolean SequenceOfCouples As String Value As String

Issue 2.1 August 2003

235

API Methods: Descriptions

Dim Count As Long Dim Index As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfCouples = VTel.SeqCoupleCreate( ) Status = VTel.VDUGetDataSynch(VduId, SequenceOfCouples) Mutex = False Index = 0 Mutex = True Count = VTel.SeqCoupleCount(SequenceOfCouples) Mutex = False While Index < Count Mutex = True Value = VTel.SeqCoupleGetVal(SequenceOfCouples, Index) Mutex = False Index = Index + 1 . . . Wend

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString SequenceOfCouples; CString Value; long Count; . . . SequenceOfCouples = VTel.SeqCoupleCreate( ); Status = VTel.VDUGetDataSynch(VduID, SequenceOfCouples); Count = VTel.SeqCoupleCount(SequenceOfCouples); for (long i=0; i < Count; i++) { Value = VTel.SeqCoupleGetVal(SequenceOfCouples, i); . . . }

236 VTel Automation Server Programmer Guide

Methods

SeqCoupleLimit Syntax

Description

Input Parameters

Language

Syntax

IDL

string SeqCoupleLimit( in string SeqCouple, in long Limit )

Visual C++

CString SeqCoupleLimit( LPCTSTR SeqCouple, long Limit )

Visual Basic

SeqCoupleLimit( ByVal SeqCouple As String, ByVal Limit As Long ) As String

This function is only useful when passing an empty sequence to be used as an output value. In such a case, SeqCoupleLimit() can limit the number of returned items.

Name

Description

SeqCouple

A sequence of couples

Limit

The maximum number of elements to be associated with the sequence of couples

Output Parameters

None.

Return Value

The original sequence of couples with its limit set as specified.

Visual Basic Example

Dim VTel As Object Dim SequenceOfCouples As String Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfCouples = VTel.SeqCoupleCreate( ) Mutex = False ' Get values from VDU, limit to 75 couples Mutex = True SequenceOfCouples = VTel.SeqCoupleLimit(SequenceOfCouples, 75) Mutex = False Mutex = True If VTel.VDUGetValuesSynch( VduID, SequenceOfCouples ) = True Then

Issue 2.1 August 2003

237

API Methods: Descriptions

Mutex = False . . .

Visual C++ Example

#include "VProxy.h" CVTelProxy CString CString . . . SequenceOfCouples =

VTel; SequenceOfCouples; VduID;

VTel.SeqCoupleCreate( );

' Get values from VDU, limit to 75 couples SequenceOfCouples = VTel.SeqCoupleLimit(SequenceOfCouples, 75); if ( VTel.VDUGetValuesSynch( VduID, SequenceOfCouples ) ) . . .

SeqCoupleSet Syntax

Description Input Parameters

Language

Syntax

IDL

string SeqCoupleSet( in string SeqCouple, in string Attribute, in string Value )

Visual C++

CString SeqCoupleSet( LPCTSTR SeqCouple, LPCTSTR Attribute, LPCTSTR Value )

Visual Basic

SeqCoupleSet( ByVal SeqCouple As String, ByVal Attribute As String, ByVal Value As String ) As String

Sets a name/value pair, or creates one if one does not exist.

Name

Description

SeqCouple

A sequence of couples

Attribute

The name of the name/value pair that is to be set/ created in the sequence of couples

Value

The value of the name/value pair that is to be set/ created in the sequence of couples

238 VTel Automation Server Programmer Guide

Methods

Output Parameters

None.

Return Value

The original sequence of couples with the Attribute and Value added.

Visual Basic Example

Dim VTel As Object Dim SequenceOfCouples As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfCouples = VTel.SeqCoupleCreate( ) Mutex = False Mutex = True SequenceOfCouples = VTel.SeqCoupleSet(SequenceOfCouples, "Account", "123") Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; CString SequenceOfCouples; . . . SequenceOfCouples = VTel.SeqCoupleCreate( ); SequenceOfCouples = VTel.SeqCoupleSet(SequenceOfCouples, "Account", "123");

SeqStringAdd Syntax

Description

Language

Syntax

IDL

string SeqStringAdd( in string SeqString, in string String )

Visual C++

CString SeqStringAdd( LPCTSTR SeqString, LPCTSTR String )

Visual Basic

SeqStringAdd( ByVal SeqString As String, ByVal String As String ) As String

Adds String to the end of the sequence and returns the new sequence.

Issue 2.1 August 2003

239

API Methods: Descriptions

Input Parameters

Name

Description

SeqString

A sequence of strings

String

The string to be appended to the sequence of strings

Output Parameters

None.

Return Value

The original sequence of strings with String appended.

Visual Basic Example

Dim VTel As Object Dim SequenceOfStrings As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfStrings = VTel.SeqStringCreate( ) Mutex = False Mutex = True SequenceOfStrings = VTel.SeqStringAdd(SequenceOfStrings, "String1") Mutex = False Mutex = True SequenceOfStrings = VTel.SeqStringAdd(SequenceOfStrings, "String2") Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy CString . . . SequenceOfStrings = SequenceOfStrings = SequenceOfStrings =

VTel; SequenceOfStrings;

VTel.SeqStringCreate( ); VTel.SeqStringAdd(SequenceOfStrings, "String1"); VTel.SeqStringAdd(SequenceOfStrings, "String2");

240 VTel Automation Server Programmer Guide

Methods

SeqStringCount Syntax

Description Input Parameters

Language

Syntax

IDL

long SeqStringCount( in string SeqString )

Visual C++

long SeqStringCount( LPCTSTR SeqString )

Visual Basic

SeqStringCount( ByVal SeqString As String ) As Long

Returns the number of strings in the sequence.

Name

Description

SeqString

A sequence of strings

Output Parameters

None.

Return Value

The number of strings in the sequence as a long.

Visual Basic Example

Dim VTel As Object Dim SequenceOfStrings As String Dim VduID As String Dim Count As Long Dim Index As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfStrings = VTel.SeqStringCreate( ) Mutex = False Mutex = True If VTel.VDUFindVDUSynch( "Account = 123", SequenceOfStrings ) = True Then Mutex = False Index = 0 Mutex = True Count = VTel.SeqStringCount(SequenceOfStrings) Mutex = False While Index < Count Mutex = True VduID = VTel.SeqStringGet(SequenceOfStrings, Index) Mutex = False Index = Index + 1

Issue 2.1 August 2003

241

API Methods: Descriptions

. . . Wend End If

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; CString SequenceOfStrings; CString VduID; long Count; . . . SequenceOfStrings = VTel.SeqStringCreate( ); if ( VTel.VDUFindVDUSynch( "Account = 123", SequenceOfStrings ) ) { Count = VTel.SeqStringCount(SequenceOfStrings); for (long i=0; i < Count; i++) { VduID = VTel.SeqStringGet(SequenceOfStrings, i); . . . } }

SeqStringCreate Syntax Language

Syntax

IDL

string SeqStringCreate( )

Visual C++

CString SeqStringCreate( )

Visual Basic

SeqStringCreate( ) As String

Description

Creates and returns an empty sequence of strings.

Input Parameters

None.

Output Parameters

None.

Return Value

An empty sequence of strings as a string.

242 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Dim VTel As Object Dim SequenceOfStrings As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfStrings = VTel.SeqStringCreate( ) Mutex = False Mutex = True VTel.VDUFindVDUSynch "Account = 123", SequenceOfStrings Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; CString SequenceOfStrings; . . . SequenceOfStrings = VTel.SeqStringCreate( ); VTel.VDUFindVDUSynch( "Account = 123", SequenceOfStrings );

SeqStringGet Syntax

Description Input Parameters

Language

Syntax

IDL

string SeqStringGet( in string SeqString, in long StringPosition )

Visual C++

CString SeqStringGet( LPCTSTR SeqString, long StringPosition )

Visual Basic

SeqStringGet( ByVal SeqString As String, ByVal StringPosition As Long ) As String

Returns the string that is at the position specified by StringPosition.

Name

Description

SeqString

A sequence of strings

StringPosition

Position of the desired string in the sequence of strings

Issue 2.1 August 2003

243

API Methods: Descriptions

Output Parameters

None.

Return Value

The string at the position given by StringPosition.

Visual Basic Example

Dim VTel As Object Dim SequenceOfStrings As String Dim VduID As String Dim Count As Long Dim Index As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfStrings = VTel.SeqCoupleCreate( ) Mutex = False Mutex = True If VTel.VDUFindVDUSynch( "Account = 123", SequenceOfStrings ) = True Then Mutex = False Index = 0 Mutex = True Count = VTel.SeqStringCount(SequenceOfStrings) Mutex = False While Index < Count Mutex = True VduID = VTel.SeqStringGet(SequenceOfStrings, Index) Mutex = False Index = Index + 1 . . Wend End If

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; CString SequenceOfStrings; CString VduID; long Count; . . . SequenceOfStrings = VTel.SeqCoupleCreate( ); if ( VTel.VDUFindVDUSynch( "Account = 123", SequenceOfStrings ) ) { Count = VTel.SeqStringCount(SequenceOfStrings); for (long i=0; i < Count; i++) { VduID = VTel.SeqStringGet(SequenceOfStrings, i); . . } }

244 VTel Automation Server Programmer Guide

Methods

SeqStringLimit Syntax

Description

Input Parameters

Language

Syntax

IDL

string SeqStringLimit( in string SeqString, in long Limit )

Visual C++

CString SeqStringLimit( LPCTSTR SeqString, long Limit )

Visual Basic

SeqStringLimit( ByVal SeqString As String, ByVal Limit As Long ) As String

This function is only useful when passing an empty sequence to be used as an output value. In such a case, SeqStringLimit() can limit the number of returned items.

Name

Description

SeqString

A sequence of strings

Limit

The maximum number of elements to be associated with the sequence of strings

Output Parameters

None.

Return Value

The original sequence of strings with its limit set as specified.

Visual Basic Example

Dim VTel As Object Dim SequenceOfStrings As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfStrings = VTel.SeqCoupleCreate( ) Mutex = False ' Limit the number of returned strings to 75 Mutex = True SequenceOfStrings = VTel.SeqStringLimit(SequenceOfStrings, 75) Mutex = False Mutex = True VTel.VDUFindVDUSynch "Account = 123", SequenceOfStrings Mutex = False

Issue 2.1 August 2003

245

API Methods: Descriptions

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; CString SequenceOfStrings; . . . SequenceOfStrings = VTel.SeqCoupleCreate( ); // Limit the number of returned strings to 75 SequenceOfStrings = VTel.SeqStringLimit(SequenceOfStrings, 75); VTel.VDUFindVDUSynch( "Account = 123", SequenceOfStrings );

SetAutoIn Syntax

Description Input Parameters

Language

Syntax

IDL

long SetAutoIn(in string flag)

Visual C++

long SetAutoIn(LPCTSTR flag)

Visual Basic

SetAutoIn(ByVal flag As String) As Long

Issue the VTel.SetAutoIn request asynchronously. Sets the VTel.ini AutoIn parameter to Y, as if the VTel.ini file changed and reloaded.

Name

Description

flag

Either 0 or 1 to indicate whether to enable or disable AutoIn from VTel

Output Parameters

None.

Return Value

Returns handle to the expected response.

246 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim ReasonCode As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.SetAutoIn("1") Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString ReasonCode; . . . ResponseHandle = VTel.SetAutoIn("1");

SetAutoInSynch Syntax

Description Input Parameters

Language

Syntax

IDL

long SetAutoInSynch(in string flag)

Visual C++

long SetAutoInSynch(LPCTSTR flag)

Visual Basic

SetAutoInSynch(ByVal flag As String) As Long

Issue the VTel.SetAutoIn request synchronously. Sets the VTel.ini AutoIn parameter to Y, as if the VTel.ini file changed and reloaded.

Name

Description

flag

Either 0 or 1 to indicate whether to enable or disable AutoIn from VTel

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained using GetLastResponseDetails().

Issue 2.1 August 2003

247

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim ReasonCode As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.SetAutoInSynch("1") Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString ReasonCode; . . . ResponseHandle = VTel.SetAutoInSynch("1");

SupressEvents Syntax

Description

Language

Syntax

IDL

void SupressEvents( in BOOL Flag )

Visual C++

void SupressEvents( BOOL Flag )

Visual Basic

SupressEvents( ByVal Flag As Boolean )

If Flag is TRUE, the queuing of incoming events is disabled. Subsequently setting the flag to FALSE will restore eventing; however, all prior events will have been lost.

Input Parameters

Name

Description

Flag

TRUE or FALSE

Output Parameters

None.

Return Value

None.

248 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Dim VTel As Object Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True VTel.SupressEvents True Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; . . . VTel.SupressEvents(TRUE);

SupressResponses Syntax

Description

Language

Description

IDL

void SupressResponses( in BOOL Flag )

Visual C++

void SupressResponses( BOOL Flag )

Visual Basic

SupressResponses( ByVal Flag As Boolean )

If Flag is TRUE, the queuing of incoming responses is disabled. Subsequently setting the flag to FALSE will restore response posting; however, all prior responses will have been lost.

Input Parameters

Name

Description

Flag

TRUE or FALSE

Output Parameters

None.

Return Value

None

Issue 2.1 August 2003

249

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True VTel.SupressResponses(True) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; . . . VTel.SupressResponses(TRUE);

SwapHeld Syntax

Description

Language

Syntax

IDL

long SwapHeld( in string VduID )

Visual C++

long SwapHeld( LPCTSTR VduID )

Visual Basic

SwapHeld( ByVal VduID As String ) As Long

Issue the VTel.SwapHeld request asynchronously. After a TransferInit() or ConferenceInit(), this method toggles between the new party and the conversation(s) on hold. This method is dependent on the telephone switch; refer to the IDL chapter of your Telephony Services manual to determine availability.

Input Parameters

Name

Description

VduID

The VDUID of the telephone call

Output Parameters

None.

Return Value

Returns handle to the expected response.

250 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.SwapHeld( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; . . . ResponseHandle = VTel.SwapHeld( VduID );

SwapHeldSynch Syntax

Description

Language

Syntax

IDL

BOOL SwapHeldSynch( in string VduID )

Visual C++

BOOL SwapHeldSynch( LPCTSTR VduID )

Visual Basic

SwapHeldSynch( ByVal VduID As String ) As Boolean

Issue the VTel.SwapHeld request synchronously. After a TransferInit() or ConferenceInit(), this method toggles between the new party and the conversation(s) on hold. This method is dependent on the telephone switch; refer to the IDL chapter of your Telephony Services manual to determine availability.

Input Parameters

Output Parameters

Name

Description

VduID

The VDUID of the telephone call

None.

Issue 2.1 August 2003

251

API Methods: Descriptions

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.SwapHeldSynch( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; . . . Status = VTel.SwapHeldSynch( VduID );

Terminate Syntax

Description

Language

Syntax

IDL

long Terminate( in string VduID )

Visual C++

long Terminate( LPCTSTR VduID )

Visual Basic

Terminate( ByVal VduID As String ) As Long

Issue the VTel.Terminate request asynchronously. Hangs up a telephone call and terminates its VDU. No further work can be performed related to this call. If the EDU is locked, the call is terminated but the EDU remains held by VTel.

Input Parameters

Output Parameters

Name

Description

VduID

A VDUID active in VTel

None.

252 VTel Automation Server Programmer Guide

Methods

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.Terminate( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; . . . ResponseHandle = VTel.Terminate( VduID );

TerminateSynch Syntax

Description

Language

Syntax

IDL

BOOL TerminateSynch( in string VduID )

Visual C++

BOOL TerminateSynch( LPCTSTR VduID )

Visual Basic

TerminateSynch( ByVal VduID As String ) As Boolean

Issue the VTel.Terminate request synchronously. Hangs up a telephone call and terminates its VDU. No further work can be performed related to this call. If the EDU is locked, the call is terminated but the EDU remains held by VTel.

Input Parameters

Output Parameters

Name

Description

VduID

A VDUID active in VTel

None.

Issue 2.1 August 2003

253

API Methods: Descriptions

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.TerminateSynch( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; . . . Status = VTel.TerminateSynch( VduID );

Transfer Syntax

Description Input Parameters

Language

Syntax

IDL

long Transfer( in string VduID, in string PhoneNumber )

Visual C++

long Transfer( LPCTSTR VduID, LPCTSTR PhoneNumber )

Visual Basic

Transfer( ByVal VduID As String, ByVal PhoneNumber As String ) As Long

Issue the VTel.Transfer request asynchronously. Performs a blind transfer of current conversation(s) to another phone.

Name

Description

VduID

The VDUID of a current call.

PhoneNumber

Dialable number, UserID, or ACD queue of the phone that the call is to be transferred to.

254 VTel Automation Server Programmer Guide

Methods

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.Transfer( VduID, PhoneNumber ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; CString PhoneNumber; . . . ResponseHandle = VTel.Transfer( VduID, PhoneNumber );

TransferCancel Syntax

Description

Language

Syntax

IDL

long TransferCancel( in string VduID )

Visual C++

long TransferCancel( LPCTSTR VduID )

Visual Basic

TransferCancel( ByVal VduID As String ) As Long

Issue the VTel.TransferCancel request asynchronously. Ends a consultative transfer by disconnecting the additional party and taking the original conversation(s) off hold.

Issue 2.1 August 2003

255

API Methods: Descriptions

Input Parameters

Name

Description

VduID

The VDUID of a current call

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.TransferCancel( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; . . . ResponseHandle = VTel.TransferCancel( VduID );

TransferCancelSynch Syntax

Description

Language

Syntax

IDL

BOOL TransferCancelSynch( in string VduID )

Visual C++

BOOL TransferCancelSynch( LPCTSTR VduID )

Visual Basic

TransferCancelSynch( ByVal VduID As String ) As Boolean

Issue the VTel.TransferCancel request synchronously. Ends a consultative transfer by disconnecting the additional party and taking the original conversation(s) off hold.

256 VTel Automation Server Programmer Guide

Methods

Input Parameters

Name

Description

VduID

The VDUID of a current call

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . Mutex = True Status = VTel.TransferCancelSynch( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; . . . Status = VTel.TransferCancelSynch( VduID );

TransferComplete Syntax

Description

Language

Syntax

IDL

long TransferComplete( in string VduID )

Visual C++

long TransferComplete( LPCTSTR VduID )

Visual Basic

TransferComplete( ByVal VduID As String ) As Long

Issue the VTel.TransferComplete request asynchronously. Ends a consultative transfer by connecting the additional party to the original conversation(s), and disconnecting the initiating agent from the call. The initiating agent will typically retain the EDU and move to WrapUp state, unless a different VTel configuration option has been selected, or a preset state has been set.

Issue 2.1 August 2003

257

API Methods: Descriptions

Input Parameters

Name

Description

VduID

The VDUID of a current call

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.TransferComplete( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; . . . ResponseHandle = VTel.TransferComplete( VduID );

TransferCompleteSynch Syntax Language

Syntax

IDL

BOOL TransferCompleteSynch( in string VduID )

Visual C++

BOOL TransferCompleteSynch( LPCTSTR VduID )

Visual Basic

TransferCompleteSynch( ByVal VduID As String ) As Boolean

258 VTel Automation Server Programmer Guide

Methods

Description

Input Parameters

Issue the VTel.TransferComplete request synchronously. Ends a consultative transfer by connecting the additional party to the original conversation(s), and disconnecting the initiating agent from the call. The initiating agent will typically retain the EDU and move to WrapUp state, unless a different VTel configuration option has been selected, or a preset state has been set.

Name

Description

VduID

The VDUID of a current call

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.TransferCompleteSynch( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; . . . Status = VTel.TransferCompleteSynch( VduID );

Issue 2.1 August 2003

259

API Methods: Descriptions

TransferInit Syntax

Description

Input Parameters

Language

Syntax

IDL

long TransferInit( in string VduID, in string PhoneNumber )

Visual C++

long TransferInit( LPCTSTR VduID, LPCTSTR PhoneNumber )

Visual Basic

TransferInit( ByVal VduID As String, ByVal PhoneNumber As String ) As Long

Issue the VTel.TransferInit request asynchronously. Begins a consultative transfer. The current conversation(s) are placed on hold, and an outbound call is placed to an additional party, using the same VDUID as the previous call.

Name

Description

VduID

The VDUID of a current call.

PhoneNumber

Dialable number, UserID, or ACD queue of the phone that the call is to be transferred to.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.TransferInit( VduID, PhoneNumber ) Mutex = False

260 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; CString PhoneNumber; . . . ResponseHandle = VTel.TransferInit( VduID, PhoneNumber );

TransferInitSynch Syntax

Description

Input Parameters

Language

Syntax

IDL

BOOL TransferInitSynch( in string VduID, in string PhoneNumber )

Visual C++

BOOL TransferInitSynch( LPCTSTR VduID, LPCTSTR PhoneNumber )

Visual Basic

TransferInitSynch( ByVal VduID As String, ByVal PhoneNumber As String ) As Boolean

Issue the VTel.TransferInit request synchronously. Begins a consultative transfer. The current conversation(s) are placed on hold, and an outbound call is placed to an additional party, using the same VDUID as the previous call.

Name

Description

VduID

The VDUID of a current call

PhoneNumber

Dialable number, UserID, or ACD queue of the phone that the call is to be transferred to

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Issue 2.1 August 2003

261

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.TransferInitSynch( VduID, PhoneNumber ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; CString PhoneNumber; . . . Status = VTel.TransferInitSynch( VduID, PhoneNumber );

TransferSynch Syntax

Description Input Parameters

Language

Syntax

IDL

BOOL TransferSynch( in string VduID, in string PhoneNumber )

Visual C++

BOOL TransferSynch( LPCTSTR VduID, LPCTSTR PhoneNumber )

Visual Basic

TransferSynch( ByVal VduID As String, ByVal PhoneNumber As String ) As Boolean

Issue the VTel.Transfer request synchronously. Performs a blind transfer of current conversation(s) to another phone.

Name

Description

VduID

The VDUID of a current call.

PhoneNumber

Dialable number, UserID, or ACD queue of the phone that the call is to be transferred to.

262 VTel Automation Server Programmer Guide

Methods

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.TransferSynch( VduID, PhoneNumber ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; CString PhoneNumber; . . . Status = VTel.TransferSynch( VduID, PhoneNumber );

VDUCreate Syntax

Description

Language

Syntax

IDL

long VDUCreate( in string SequenceOfCouples )

Visual C++

long VDUCreate( LPCTSTR SequenceOfCouples )

Visual Basic

VDUCreate( ByVal SequenceOfCouples As String ) As Long

Issue the VTel.VDUCreate request asynchronously. Creates a unique Voice/ Data Unit (VDU) for a phone call. You may not specify the VDUID. This is assigned by the Telephony system. You must explicitly terminate any VDUs that are created with VDUCreate. Use Terminate to do so.

Issue 2.1 August 2003

263

API Methods: Descriptions

Input Parameters

Name

Description

SequenceOfCouples

Zero or more name/value pairs to place into the new VDU

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim SequenceOfCouples As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfCouples = VTel.SeqCoupleCreate() SequenceOfCouples = VTel.SeqCoupleSet( SequenceOfCouples, "Attribute", "Value" ) ResponseHandle = VTel.VDUCreate( SequenceOfCouples ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy long CString . . . SequenceOfCouples = SequenceOfCouples =

VTel; ResponseHandle; SequenceOfCouples;

VTel.SeqCoupleCreate(); VTel.SeqCoupleSet( SequenceOfCouples, "Attribute","Value" ); ResponseHandle = VTel.VDUCreate( SequenceOfCouples );

264 VTel Automation Server Programmer Guide

Methods

VDUCreateSynch Syntax

Description

Input Parameters

Output Parameters

Language

Syntax

IDL

BOOL VDUCreateSynch( in string SequenceOfCouples, out string VduID )

Visual C++

BOOL VDUCreateSynch( LPCTSTR SequenceOfCouples, CString& VduID )

Visual Basic

VDUCreateSynch( ByVal SequenceOfCouples As String, VduID As String ) As Boolean

Issue the VTel.VDUCreate request synchronously. Creates a unique Voice/ Data Unit (VDU) for a phone call. You may not specify the VDUID. This is assigned by the Telephony system. You must explicitly terminate any VDUs that are created with VDUCreate. Use Terminate to do so.

Name

Description

SequenceOfCouples

Zero or more name/value pairs to place into the new VDU

Name

Description

VduID

Identifies the newly created VDU

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim SequenceOfCouples As String Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfCouples = VTel.SeqCoupleCreate() SequenceOfCouples = VTel.SeqCoupleSet( SequenceOfCouples, "Attribute", "Value" )

Issue 2.1 August 2003

265

API Methods: Descriptions

Status = VTel.VDUCreateSynch( SequenceOfCouples, VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy BOOL CString CString . . . SequenceOfCouples = SequenceOfCouples =

VTel; Status; SequenceOfCouples; VduID;

VTel.SeqCoupleCreate(); VTel.SeqCoupleSet( SequenceOfCouples, "Attribute", "Value" ); Status = VTel.VDUCreateSynch( SequenceOfCouples, VduID );

VDUFindVDU Syntax

Description

Language

Syntax

IDL

long VDUFindVDU( in string Criteria )

Visual C++

long VDUFindVDU( LPCTSTR Criteria )

Visual Basic

VDUFindVDU( ByVal Criteria As String ) As Long

Issue the VTel.VDUFindVDU request asynchronously. Retrieves a list of all VDUs in the Telephony system that match the given criteria, including both active calls and those stored in the DUStore Server. The EDU may exist anywhere in the Telephony system. This method requires that the DUStore Server be available.

Input Parameters

Name

Description

Criteria

The search criteria to be used

Note:

Output Parameters

Note: The criteria are the same as those used by the EDU Server for event monitoring. See the "Event Monitoring" chapter of Electronic Data Unit Server Programmer Guide.

None.

266 VTel Automation Server Programmer Guide

Methods

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.VDUFindVDU( "Account=123" ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; . . . ResponseHandle = VTel.VDUFindVDU( "Account=123" );

VDUFindVDUSynch Syntax

Description

Language

Syntax

IDL

BOOL VDUFindVDUSynch( in string Criteria, out string SequenceOfStrings )

Visual C++

BOOL VDUFindVDUSynch( LPCTSTR Criteria, CString& SequenceOfStrings )

Visual Basic

VDUFindVDUSynch( ByVal Criteria As String, SequenceOfStrings As String ) As Boolean

Issue the VTel.VDUFindVDU request synchronously. Retrieves a list of all VDUs in the Telephony system that match the given criteria, including both active calls and those stored in the DUStore Server. The EDU may exist anywhere in the Telephony system. This method requires that the DUStore Server be available.

Issue 2.1 August 2003

267

API Methods: Descriptions

Input Parameters

Name

Description

Criteria

The search criteria to be used

Note:

Output Parameters

Note: The criteria are the same as those used by the EDU Server for event monitoring. See the "Event Monitoring" chapter of Electronic Data Unit Server Programmer Guide.

Name

Description

SequenceOfStrings

A list of VDUIDs matching the criteria

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim SequenceOfStrings As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfStrings = VTel.SeqStringCreate() Status = VTel.VDUFindVDUSynch( "Account=123", SequenceOfStrings ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString SequenceOfStrings; . . . SequenceOfStrings = VTel.SeqStringCreate(); Status = VTel.VDUFindVDUSynch( "Account=123", SequenceOfStrings );

268 VTel Automation Server Programmer Guide

Methods

VDUGetActive Syntax Language

Syntax

IDL

long VDUGetActive( )

Visual C++

long VDUGetActive( )

Visual Basic

VDUGetActive( ) As Long

Description

Issue the VTel.VDUGetActive request asynchronously. Returns a list of all VDUIDs currently being monitored by VTel. These VDUIDs may or may not be related to a current phone conversation. Connected applications may enter or change information in these VDUs; any changes will result in notification events.

Input Parameters

None.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.VDUGetActive( ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; . . . ResponseHandle = VTel.VDUGetActive( );

Issue 2.1 August 2003

269

API Methods: Descriptions

VDUGetActiveSynch Syntax Language

Syntax

IDL

BOOL VDUGetActiveSynch( out string SequenceOfStrings )

Visual C++

BOOL VDUGetActiveSynch( CString& SequenceOfStrings )

Visual Basic

VDUGetActiveSynch( SequenceOfStrings As String ) As Boolean

Description

Issue the VTel.VDUGetActive request synchronously. Returns a list of all VDUIDs currently being monitored by VTel. These VDUIDs may or may not be related to a current phone conversation. Connected applications may enter or change information in these VDUs; any changes will result in notification events.

Input Parameters

None.

Output Parameters

Name

Description

SequenceOfStrings

A list of all VDUIDs currently active in VTel

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim SequenceOfStrings As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfStrings = VTel.SeqStringCreate() Status = VTel.VDUGetActiveSynch( SequenceOfStrings ) Mutex = False

270 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString SequenceOfStrings; . . . SequenceOfStrings = VTel.SeqStringCreate(); Status = VTel.VDUGetActiveSynch( SequenceOfStrings );

VDUGetCurrent Syntax Language

Syntax

IDL

long VDUGetCurrent( )

Visual C++

long VDUGetCurrent( )

Visual Basic

VDUGetCurrent( ) As Long

Description

Issue the VTel.VDUGetCurrent request asynchronously. Retrieves the current EDU in focus.

Input Parameters

None.

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.VDUGetCurrent() Mutex = False

Issue 2.1 August 2003

271

API Methods: Descriptions

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; Long ResponseHandle; . . . ReponseHandle = VTel.VDUGetCurrent();

VDUGetCurrentSynch Syntax Language

Syntax

IDL

BOOL VDUGetCurrentSynch(out string VduID )

Visual C++

BOOL VDUGetCurrentSynch(CString& VduID )

Visual Basic

VDUGetCurrentSynch(VduID As String) As Boolean

Description

Issue the VTel.VDUGetCurrent request synchronously. Retrieves the current EDU in focus.

Input Parameters

None.

Output Parameters

Name

Description

VduID

The VDUID of the current EDU in focus

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Boolean Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.VDUGetCurrentSynch(VduID) Mutex = False

272 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; . . . Status = VTel.VDUGetCurrentSynch(VduID);

VDUGetData Syntax

Description

Language

Syntax

IDL

long VDUGetData( in string VduID )

Visual C++

long VDUGetData( LPCTSTR VduID )

Visual Basic

VDUGetData( ByVal VduID As String ) As Long

Issue the VTel.VDUGetData request asynchronously. Retrieves all values from a VDU, which may reside anywhere in the Telephony system. This method may return a large number of data elements. Be sure to allow enough room for the response. While it can be limited by setting the maximum number to return, this is not very useful in this case as the ordering of return values is arbitrary and you cannot determine what has been missed.

Input Parameters

Name

Description

VduID

Any EDU in the Telephony system

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim Dim Dim Set . . .

VTel As Object ResponseHandle As Long VduID As String VTel = CreateObject("VTEL.SESSION")

Issue 2.1 August 2003

273

API Methods: Descriptions

Mutex = True ResponseHandle = VTel.VDUGetData( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; . . . ResponseHandle = VTel.VDUGetData( VduID );

VDUGetDataSynch Syntax

Description

Language

Syntax

IDL

BOOL VDUGetDataSynch( in string VduID, out string SequenceOfCouples )

Visual C++

BOOL VDUGetDataSynch( LPCTSTR VduID, CString& SequenceOfCouples )

Visual Basic

VDUGetDataSynch( ByVal VduID As String, SequenceOfCouples As String ) As Boolean

Issue the VTel.VDUGetData request synchronously. Retrieves all values from a VDU, which may reside anywhere in the Telephony system. This method may return a large number of data elements. Be sure to allow enough room for the response. While it can be limited by setting the maximum number to return, this is not very useful in this case as the ordering of return values is arbitrary and you cannot determine what has been missed.

Input Parameters

Output Parameters

Name

Description

VduID

Any EDU in the Telephony system

Name

Description

SequenceOfCouples

Values of all data elements currently in the VDU

274 VTel Automation Server Programmer Guide

Methods

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Dim SequenceOfCouples As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfCouples = VTel.SeqCoupleCreate() Status = VTel.VDUGetDataSynch( VduID, SequenceOfCouples ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; CString SequenceOfCouples; . . . SequenceOfCouples = VTel.SeqCoupleCreate(); Status = VTel.VDUGetDataSynch( VduID, SequenceOfCouples );

VDUGetOneValue Syntax

Description

Language

Syntax

IDL

long VDUGetOneValue( in string VduID, in string Attribute )

Visual C++

long VDUGetOneValue( LPCTSTR VduID, LPCTSTR Attribute )

Visual Basic

VDUGetOneValue( ByVal VduID As String, ByVal Attribute As String ) As Long

Issue the VTel.VDUGetOneValue request asynchronously. Retrieves one value from a VDU. The EDU must currently exist within VTel.

Issue 2.1 August 2003

275

API Methods: Descriptions

Input Parameters

Name

Description

VduID

An EDU active in VTel

Attribute

EDU data element to be returned

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Dim Attribute As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.VDUGetOneValue( VduID, Attribute ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; CString Attribute; . . . ResponseHandle = VTel.VDUGetOneValue( VduID, Attribute );

276 VTel Automation Server Programmer Guide

Methods

VDUGetOneValueSynch Syntax

Description Input Parameters

Output Parameters

Language

Syntax

IDL

BOOL VDUGetOneValueSynch( in string VduID, in string Attribute, out string Value )

Visual C++

BOOL VDUGetOneValueSynch( LPCTSTR VduID, LPCTSTR Attribute, CString& Value )

Visual Basic

VDUGetOneValueSynch( ByVal VduID As String, ByVal Attribute As String, Value As String ) As Boolean

Issue the VTel.VDUGetOneValue request synchronously. Retrieves one value from a VDU. The EDU must currently exist within VTel.

Name

Description

VduID

An EDU active in VTel

Attribute

EDU data element to be returned

Name

Description

Value

Value of the specified data element

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Dim Attribute As String Dim Value As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.VDUGetOneValueSynch( VduID, Attribute, Value ) Mutex = False

Issue 2.1 August 2003

277

API Methods: Descriptions

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; CString Attribute; CString Value; . . . Status = VTel.VDUGetOneValueSynch( VduID, Attribute, Value );

VDUGetValues Syntax

Description

Language

Syntax

IDL

long VDUGetValues( in string VduID )

Visual C++

long VDUGetValues( LPCTSTR VduID )

Visual Basic

VDUGetValues( ByVal VduID As String ) As Long

Issue the VTel.VDUGetValues request asynchronously. Retrieves all values from a VDU. The EDU must currently exist within VTel. This method may return a large number of data elements. Be sure to allow enough room for the response. While it can be limited by setting the maximum number to return, this is not very useful in this case as the ordering of return values is arbitrary and you cannot determine what has been missed.

Input Parameters

Name

Description

VduID

An EDU active in VTel

Output Parameters

None.

Return Value

Returns handle to the expected response.

278 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.VDUGetValues( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; . . . ResponseHandle = VTel.VDUGetValues( VduID );

VDUGetValuesSynch Syntax

Description

Language

Syntax

IDL

BOOL VDUGetValuesSynch( in string VduID, out string SequenceOfCouples )

Visual C++

BOOL VDUGetValuesSynch( LPCTSTR VduID, CString& SequenceOfCouples )

Visual Basic

VDUGetValuesSynch( ByVal VduID As String, SequenceOfCouples As String ) As Boolean

Issue the VTel.VDUGetValues request synchronously. Retrieves all values from a VDU.The EDU must currently exist within VTel. This method may return a large number of data elements. Be sure to allow enough room for the response. While it can be limited by setting the maximum number to return, this is not very useful in this case as the ordering of return values is arbitrary and you cannot determine what has been missed.

Input Parameters

Name

Description

VduID

An EDU active in VTel

Issue 2.1 August 2003

279

API Methods: Descriptions

Output Parameters

Name

Description

SequenceOfCouples

All data elements contained in this VDU

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Dim SequenceOfCouples As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfCouples = VTel.SeqCoupleCreate() Status = VTel.VDUGetValuesSynch( VduID, SequenceOfCouples ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; CString SequenceOfCouples; . . . SequenceOfCouples = VTel.SeqCoupleCreate(); Status = VTel.VDUGetValuesSynch( VduID, SequenceOfCouples );

VDUSetCurrent Syntax Language

Syntax

IDL

long VDUSetCurrent( in string VduID )

Visual C++

long VDUSetCurrent( LPCTSTR VduID )

Visual Basic

VDUSetCurrent( ByVal VduID As String ) As Long

280 VTel Automation Server Programmer Guide

Methods

Description

Issue the VTel.VDUSetCurrent request asynchronously. From the list of VDUIDs being monitored at the time, this method allows you to select a single VDUID to have the current focus. An event is sent to all GUI screens and all connected applications when the focus is changed to a different VDU. Those GUI screens that present available calls will typically respond to this immediately. This may cause another call to be placed on hold and an abrupt change in the EDU information presented to the user. If the user initiates this change by selecting another call from a VTel GUI, the attached application will be notified. If an external application initiates this change, it must coordinate this action with the user interface to prevent the user from being "surprised" by the abrupt change in displayed information or by a phone conversation suddenly being placed on hold.

Input Parameters

Name

Description

VduID

VDUID to be given the current focus

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.VDUSetCurrent( VduID ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString VduID; . . . ResponseHandle = VTel.VDUSetCurrent( VduID );

Issue 2.1 August 2003

281

API Methods: Descriptions

VDUSetCurrentSynch Syntax

Description

Language

Syntax

IDL

BOOL VDUSetCurrentSynch( in string VduID )

Visual C++

BOOL VDUSetCurrentSynch( LPCTSTR VduID )

Visual Basic

VDUSetCurrentSynch( ByVal VduID As String ) As Boolean

Issue the VTel.VDUSetCurrent request synchronously. From the list of VDUIDs being monitored at the time, this method allows you to select a single VDUID to have the current focus. An event is sent to all GUI screens and all connected applications when the focus is changed to a different VDU. Those GUI screens that present available calls will typically respond to this immediately. This may cause another call to be placed on hold and an abrupt change in the EDU information presented to the user. If the user initiates this change by selecting another call from a VTel GUI, the attached application will be notified. If an external application initiates this change, it must coordinate this action with the user interface to prevent the user from being "surprised" by the abrupt change in displayed information or by a phone conversation suddenly being placed on hold.

Input Parameters

Name

Description

VduID

VDUID to be given the current focus

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Set VTel = CreateObject("VTEL.SESSION") . . Mutex = True Status = VTel.VDUSetCurrentSynch( VduID ) Mutex = False

282 VTel Automation Server Programmer Guide

Methods

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; . . . Status = VTel.VDUSetCurrentSynch( VduID );

VDUSetValues Syntax

Description

Language

Syntax

IDL

long VDUSetValues( in string VduID, in string SequenceOfCouples )

Visual C++

long VDUSetValues( LPCTSTR VduID, LPCTSTR SequenceOfCouples )

Visual Basic

VDUSetValues( ByVal VduID As String, ByVal SequenceOfCouples As String ) As Long

Issue the VTel.VDUSetValues request asynchronously. Sets one or more values in a VDU. The EDU must currently exist within VTel. For existing names the old values will be replaced. New names will produce additional entries. Duplicate names are not useful, as the last value entered for a given name will dominate.

Input Parameters

Name

Description

VduID

An EDU active in VTel

SequenceOfCouples

EDU data element(s) to be set

Output Parameters

None.

Return Value

Returns handle to the expected response.

Issue 2.1 August 2003

283

API Methods: Descriptions

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim VduID As String Dim SequenceOfCouples As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfCouples = VTel.SeqCoupleCreate() SequenceOfCouples = VTel.SeqCoupleSet(SequenceOfCouples, "Attribute", "Value") ResponseHandle = VTel.VDUSetValues( VduID, SequenceOfCouples ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy long CString CString . . . SequenceOfCouples = SequenceOfCouples =

VTel; ResponseHandle; VduID; SequenceOfCouples;

VTel.SeqCoupleCreate(); VTel.SeqCoupleSet(SequenceOfCouples, "Attribute", "Value"); ResponseHandle = VTel.VDUSetValues( VduID, SequenceOfCouples );

VDUSetValuesSynch Syntax

Description

Language

Syntax

IDL

BOOL VDUSetValuesSynch( in string VduID, in string SequenceOfCouples )

Visual C++

BOOL VDUSetValuesSynch( LPCTSTR VduID, LPCTSTR SequenceOfCouples )

Visual Basic

VDUSetValuesSynch( ByVal VduID As String, ByVal SequenceOfCouples As String ) As Boolean

Issue the VTel.VDUSetValues request synchronously. Sets one or more values in a VDU. The EDU must currently exist within VTel. For existing names the old values will be replaced. New names will produce additional entries. Duplicate names are not useful, as the last value entered for a given name will dominate.

284 VTel Automation Server Programmer Guide

Methods

Input Parameters

Name

Description

VduID

An EDU active in VTel

SequenceOfCouples

EDU data element(s) to be set

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim VduID As String Dim SequenceOfCouples As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True SequenceOfCouples = VTel.SeqCoupleCreate() Status = VTel.VDUSetValuesSynch( VduID, SequenceOfCouples ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString VduID; CString SequenceOfCouples; . . . SequenceOfCouples = VTel.SeqCoupleCreate(); Status = VTel.VDUSetValuesSynch( VduID, SequenceOfCouples );

Issue 2.1 August 2003

285

API Methods: Descriptions

WaitForResponse Syntax

Description Input Parameters

Language

Syntax

IDL

BOOL WaitForResponse( in long ResponseHandle )

Visual C++

BOOL WaitForResponse( long ResponseHandle )

Visual Basic

WaitForResponse( ByVal ResponseHandle As Long ) As Boolean

Waits for a specified response to arrive.

Name

Description

ResponseHandle

A response handle previously obtained from PeekResponse(), MakeRequest(), or MakeRequestSynch().

Output Parameters

None.

Return Value

Returns FALSE if a bad handle is passed in, or if timeout occurs.

Visual Basic Example

' Needed to process response from MakeCall() Dim ResponseHandle As Long Dim StatusRequest As Boolean Dim StatusResponse As Boolean ' Call extension 4004, but do not wait for a response Mutex = True ResponseHandle = VTel.MakeCall("", "4004") Mutex = False ' Pause until a response is received Mutex = True VTel.WaitForResponse ResponseHandle Mutex = False ' Parse the response string and store the new VDUID ' in our variable, "VduID" ' StatusRequest should never be FALSE (indicates an invalid ' response handle) Mutex = True StatusRequest = VTel.GetMakeCallResponse(ResponseHandle, VduID)

286 VTel Automation Server Programmer Guide

Methods

Mutex = False ' Set StatusResponse to FALSE if response string indicates error ' has occurred Mutex = True StatusResponse = VTel.GetResponseStatus(ResponseHandle) Mutex = False ' Release server resources associated with this response Mutex = True VTel.FreeResponse ResponseHandle Mutex = False ' Display the new VDUID VduIDTextBox.Text = VduID

Visual C++ Example

// Needed to process response from MakeCall() long ResponseHandle; BOOL StatusRequest; BOOL StatusResponse; // Call extension 4004, but do not wait for a response ResponseHandle = VTel.MakeCall("", "4004"); // Pause until a response is received VTel.WaitForResponse(ResponseHandle); // Parse the response string and store the new VDUID // in our variable, "VduID" // StatusRequest should never be FALSE (indicates an invalid // response handle) StatusRequest = VTel.GetMakeCallResponse(ResponseHandle, VduID); // Set StatusResponse to FALSE if response string indicates error // has occurred StatusResponse = VTel.GetResponseStatus(ResponseHandle); // Release server resources associated with this response VTel.FreeResponse(ResponseHandle); // Display the new VDUID VduIDEdit.SetWindowText(VduID);

Issue 2.1 August 2003

287

API Methods: Descriptions

WrapUp Syntax

Description

Input Parameters

Language

Syntax

IDL

long WrapUp( in string PhoneNumber )

Visual C++

long WrapUp( LPCTSTR PhoneNumber )

Visual Basic

WrapUp( ByVal PhoneNumber As String ) As Long

Issue the VTel.WrapUp request asynchronously. From within an ACD call, may either preset the wrap-up state or hang up the call, placing the phone in the wrapup state. This method is dependent on the telephone switch and the type of phone assigned; refer to the IDL chapter of your Telephony Services manual.

Name

Description

PhoneNumber

Dialable number or null (default phone)

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.WrapUp( PhoneNumber ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString PhoneNumber; . . . ResponseHandle = VTel.WrapUp( PhoneNumber );

288 VTel Automation Server Programmer Guide

Methods

WrapUpOverride Syntax

Description

Language

Syntax

IDL

long WrapUpOverride( in string PhoneNumber )

Visual C++

long WrapUpOverride( LPCTSTR PhoneNumber )

Visual Basic

WrapUpOverride( ByVal PhoneNumber As String ) As Long

Issue the VTel.WrapUpOverride request asynchronously. If in call, and presets are on, changes the current preset to WrapUp and disallows any attempts to change the preset for the remainder of the call, unless by means of another override command (BusyOverride, ReadyOverride). If not in call, or presets are not on, behaves like the WrapUp command. This method is dependent on the telephone switch and the type of phone assigned; refer to the IDL chapter of your Telephony Services manual.

Input Parameters

Name

Description

PhoneNumber

Dialable number or null (default phone)

Output Parameters

None.

Return Value

Returns handle to the expected response.

Visual Basic Example

Dim VTel As Object Dim ResponseHandle As Long Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True ResponseHandle = VTel.WrapUpOverride( PhoneNumber ) Mutex = False

Issue 2.1 August 2003

289

API Methods: Descriptions

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; long ResponseHandle; CString PhoneNumber; . . . ResponseHandle = VTel.WrapUpOverride( PhoneNumber );

WrapUpOverrideSynch Syntax

Description

Language

Syntax

IDL

BOOL WrapUpOverrideSynch( in string PhoneNumber )

Visual C++

BOOL WrapUpOverrideSynch( LPCTSTR PhoneNumber )

Visual Basic

WrapUpOverrideSynch( ByVal PhoneNumber As String ) As Boolean

Issue the VTel.WrapUpOverride request synchronously. If in call, and presets are on, changes the current preset to WrapUp and disallows any attempts to change the preset for the remainder of the call, unless by means of another override command (BusyOverride, ReadyOverride). If not in call, or presets are not on, behaves like the WrapUpSynch command. This method is dependent on the telephone switch and the type of phone assigned; refer to the IDL chapter of your Telephony Services manual.

Input Parameters

Name

Description

PhoneNumber

Dialable number or null (default phone)

Output Parameters

None.

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

290 VTel Automation Server Programmer Guide

Methods

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.WrapUpOverrideSynch( PhoneNumber ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString PhoneNumber; . . . Status = VTel.WrapUpOverrideSynch( PhoneNumber );

WrapUpSynch Syntax

Description

Language

Syntax

IDL

BOOL WrapUpSynch( in string PhoneNumber )

Visual C++

BOOL WrapUpSynch( LPCTSTR PhoneNumber )

Visual Basic

WrapUpSynch( ByVal PhoneNumber As String ) As Boolean

Issue the VTel.WrapUp request synchronously. From within an ACD call, may either preset the wrap-up state or hang up the call, placing the phone in the wrapup state. This method is dependent on the telephone switch and the type of phone assigned; refer to the IDL chapter of your Telephony Services manual.

Input Parameters

Output Parameters

Name

Description

PhoneNumber

Dialable number or null (default phone)

None.

Issue 2.1 August 2003

291

API Methods: Descriptions

Return Value

Returns FALSE if a time-out occurs, or if the response indicates an error. In either case, the specifics can be obtained via GetLastResponseDetail().

Visual Basic Example

Dim VTel As Object Dim Status As Boolean Dim PhoneNumber As String Set VTel = CreateObject("VTEL.SESSION") . . . Mutex = True Status = VTel.WrapUpSynch( PhoneNumber ) Mutex = False

Visual C++ Example

#include "VProxy.h" CVTelProxy VTel; BOOL Status; CString PhoneNumber; . . . Status = VTel.WrapUpSynch( PhoneNumber )

292 VTel Automation Server Programmer Guide

Index Symbols .cpp files .h files . .imp files .ini file . .pk files .

. . . . .

. . . . .

D . . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

15, 17 15, 17 15, 46 15, 46 15, 46

. . . .

. 86, 221, 222, 223, 224, 226 . . . . . . . . . . . . 51, 94 . . . . . . . . . . . . 52, 96 . . . . . . . . . . . 227, 228

E

A Answer . . . . . . . AnswerSynch . . . . API . . . . . . . . . Automation API . . . Automation Controller Automation Server . .

Definity Reason Codes Drop. . . . . . . . . DropSynch. . . . . . DTMF . . . . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

51, 75 52, 76 21, 49 . . 21 . . 15 . . 15

bin directory . . . . . . . . Breaking OLE connections . Busy . . . . . . . . . . . Busy state . . . . . . . . BusyOverride . . . . . . . BusyOverrideSynch . . . . BusyPhoneset . . . . . . . BusyPhonesetSynch . . . . BusySynch . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

15, 16 . . 18 51, 77 . . 78 51, 78 52, 79 51, 81 52, 82 52, 83

C++ . . . . . . . . . . . . Call Management Methods . . Cautions . . . . . . . . . . ChangeBusyReasonCode . . ChangePassword . . . . . . ChangePasswordSynch . . . Codes Event . . . . . . . . . . Response . . . . . . . . Commands . . . . . . . . . ConferenceCancel . . . . . . ConferenceCancelSynch . . . ConferenceComplete . . . . ConferenceCompleteSynch . ConferenceInit. . . . . . . . ConferenceInitSynch. . . . . Consultative transfer . . 255, Convenience Methods . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

17, 19 . . 50 . . 45 . . 86 55, 84 56, 85

B

C

. . . . . . . . . . . 65 . . . . . . . . . . . 61 . . . . . . . . . . . 49 . . . . . . . . . 51, 87 . . . . . . . . . 52, 88 . . . . . . . . . 51, 89 . . . . . . . . . 52, 90 . . . . . . . . . 51, 92 . . . . . . . . . 52, 93 256, 257, 259, 260, 261 . 22, 46, 49, 52, 54, 56

eDU Management Methods . educational services . . . . Enabling automation . . . . Error handling . . . . . . . etc directory . . . . . . . . Event codes . . . . . . . . Event processing . . . . . . Exit events . . . . . . . Example . . . . . . . . . . Exit . . . . . . . . . . . . Exit events . . . . . . . . . ExitSynch . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . 53 . . 12 15, 45 . . 27 15, 16 . . 65 26, 38 . . 18 . . 33 55, 97 18, 47 56, 98

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. 15, 17 . 15, 17 . 15, 46 . 15, 46 . 15, 46 . 59, 99 57, 100 59, 101 57, 104 . . . 49

General Methods . . . . . . GetEventArg . . . . . . . . GetEventCode . . . . . . . GetEventCount . . . . . . GetEventName . . . . . . GetEventString . . . . . . . GetGetInfoResponse . . . . GetGetPhoneInfoResponse . GetInfo . . . . . . . . . . GetInfoSynch . . . . . . . GetLastResponseDetail . . GetMakeCallResponse . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . 50 59, 106 59, 109 .59, 113 .59, 114 .59, 118 .58, 119 58, 122 55, 124 56, 125 57, 126 58, 128

F Files .cpp . . . . . .h . . . . . . .imp . . . . . .ini . . . . . . .pk . . . . . . FreeAllEvents . . FreeAllResponses FreeEvent . . . . FreeResponse . . Functions . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

G

Issue 2.1 August 2003

293

GetPhoneInfo . . . . . . . . . GetPhoneInfoSynch . . . . . . GetResponseArg . . . . . . . . GetResponseCode . . . . . . . GetResponseCount . . . . . . GetResponseDetail . . . . . . GetResponseName . . . . . . GetResponseStatus . . . . . . GetResponseString . . . . . . Getting started . . . . . . . . . GetVDUCreateResponse . . . . GetVDUFindVDUResponse . . . GetVDUGetActiveResponse . . GetVDUGetCurrentResponse . . GetVDUGetDataResponse . . . GetVDUGetOneValueResponse GetVDUGetValuesResponse . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . 51, 130 . . 52, 131 . . 57, 132 . . 57, 134 . . 57, 137 57, 58, 138 . . 57, 142 . . 57, 144 . . 57, 145 . . . . . 15 . . 58, 146 . . 58, 149 . . 58, 151 . . 58, 154 . . 58, 156 . . 58, 158 . . 58, 161

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

H Hangup . . . . . . . HangupSynch . . . . Hold . . . . . . . . . HoldReconnect . . . HoldReconnectSynch HoldSynch . . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

51, 163 52, 164 51, 165 51, 166 52, 168 52, 169

I Implementing a softphone Example . . . . . . . . . . . . . . . . . . . . 33 Installation . . . . . . . . . . . . . . . . . . . . . 15

L LogEntry . . . . . . . . LogEntrySynch . . . . . Login . . . . . . . . . LoginACD . . . . . . . LoginACDSynch . . . . LoginSynch . . . . . . LoginTelephony . . . . LoginTelephonySynch . LoginVESP . . . . . . LoginVESPSynch . . . Logout . . . . . . . . . LogoutSynch . . . . . . LogoutTelephony. . . . LogoutTelephonySynch. LogoutVESP . . . . . . LogoutVESPSynch . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

55, 170 56, 171 55, 172 55, 174 56, 176 56, 178 55, 180 56, 182 55, 184 56, 185 55, 186 56, 187 55, 188 56, 190 55, 191 56, 192

294 VTel Automation Server Programmer Guide

M MakeCall . . . . . . . . . . . MakeCallSynch . . . . . . . . MakeRequest. . . . . . . . . MakeRequestSynch. . . . . . Making OLE connections . . . Methods . . . . . . . . . . . Answer . . . . . . . . . . AnswerSynch . . . . . . . Busy . . . . . . . . . . . BusyOverride . . . . . . . BusyOverrideSynch . . . . BusyPhoneset . . . . . . . BusyPhonesetSynch . . . . BusySynch . . . . . . . . ChangePassword . . . . . ChangePasswordSynch . . ConferenceCancel . . . . . ConferenceCancelSynch . . ConferenceComplete . . . ConferenceCompleteSynch ConferenceInit. . . . . . . ConferenceInitSynch. . . . Drop . . . . . . . . . . . DropSynch . . . . . . . . Exit . . . . . . . . . . . . ExitSynch . . . . . . . . . FreeAllEvents . . . . . . . FreeAllResponses . . . . . FreeEvent . . . . . . . . . FreeResponse . . . . . . GetEventArg . . . . . . . GetEventCode . . . . . . GetEventCount . . . . . . GetEventName . . . . . . GetEventString . . . . . . GetGetInfoResponse . . . GetGetPhoneInfoResponse GetInfo . . . . . . . . . . GetInfoSynch . . . . . . . GetLastResponseDetail . . GetMakeCallResponse . . GetPhoneInfo . . . . . . . GetPhoneInfoSynch . . . . GetResponseArg . . . . . GetResponseCode . . . . GetResponseCount . . . . GetResponseDetail . . . . GetResponseName . . . . GetResponseStatus . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . 51, 194 . . 52, 195 . . 50, 197 . . 50, 201 . . . 16, 18 . . . . . 49 . . . 51, 75 . . . 52, 76 . . . 51, 77 . . . 51, 78 . . . 52, 79 . . . 51, 81 . . . 52, 82 . . . 52, 83 . . . 55, 84 . . . 56, 85 . . . 51, 87 . . . 52, 88 . . . 51, 89 . . . 52, 90 . . . 51, 92 . . . 52, 93 . . . 51, 94 . . . 52, 96 . . . 55, 97 . . . 56, 98 . . . 59, 99 . . 57, 100 . . 59, 101 . . 57, 104 . . 59, 106 . . 59, 109 . . 59, 113 . . 59, 114 . . 59, 118 . . 58, 119 . . 58, 122 . . 55, 124 . . 56, 125 . . 57, 126 . . 58, 128 . . 51, 130 . . 52, 131 . . 57, 132 . . 57, 134 . . 57, 137 57, 58, 138 . . 57, 142 . . 57, 144

GetResponseString . . . . . . GetVDUCreateResponse . . . . GetVDUFindVDUResponse . . . GetVDUGetActiveResponse . . GetVDUGetDataResponse . . . GetVDUGetOneValueResponse GetVDUGetValuesResponse . . Hangup . . . . . . . . . . . . HangupSynch . . . . . . . . . Hold . . . . . . . . . . . . . . HoldReconnect. . . . . . . . . HoldReconnectSynch. . . . . . HoldSynch . . . . . . . . . . . LogEntry . . . . . . . . . . . . LogEntrySynch . . . . . . . . . Login . . . . . . . . . . . . . LoginACD . . . . . . . . . . . LoginACDSynch . . . . . . . . LoginSynch . . . . . . . . . . LoginTelephony . . . . . . . . LoginTelephonySynch . . . . . LoginVESP . . . . . . . . . . LoginVESPSynch . . . . . . . Logout . . . . . . . . . . . . . LogoutSynch . . . . . . . . . . LogoutTelephony . . . . . . . . LogoutTelephonySynch . . . . . LogoutVESP . . . . . . . . . . LogoutVESPSynch . . . . . . . MakeCall . . . . . . . . . . . MakeCallSynch . . . . . . . . MakeRequest . . . . . . . . . MakeRequestSynch . . . . . . PeekEvent . . . . . . . . . . . PeekResponse . . . . . . . . . Ping . . . . . . . . . . . . . . PingSynch . . . . . . . . . . . Ready . . . . . . . . . . . . . ReadyOverride . . . . . . . . . ReadyOverrideSynch . . . . . . ReadyPhoneset . . . . . . . . ReadyPhonesetSynch . . . . . ReadySynch . . . . . . . . . . ResetPhones . . . . . . . . . ResetPhonesSynch . . . . . . RestartServer . . . . . . . . . RestartServerSynch . . . . . . SendDefinityAux . . . . . . . . SendDefinityAuxSynch . . . . . SendDefinityLogout . . . . . . SendDefinityLogoutSynch . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . 57, 145 . . . 58, 146 . . . 58, 149 . . . 58, 151 . . . 58, 156 . . . 58, 158 . . . 58, 161 . . . 51, 163 . . . 52, 164 . . . 51, 165 . . . 51, 166 . . . 52, 168 . . . 52, 169 . . . 55, 170 . . . 56, 171 . . . 55, 172 . . . 55, 174 . . . 56, 176 . . . 56, 178 . . . 55, 180 . . . 56, 182 . . . 55, 184 . . . 56, 185 . . . 55, 186 . . . 56, 187 . . . 55, 188 . . . 56, 190 . . . 55, 191 . . . 56, 192 . . . 51, 194 . . . 52, 195 . . . 50, 197 . . . 50, 201 . . . 59, 203 . . . 57, 206 . . . 56, 208 . . . 56, 209 . . . 51, 210 . . . 51, 211 . . . 52, 212 . . . 51, 213 . . . 52, 214 . . . 52, 215 . . . 51, 216 . . . 52, 217 . . . 51, 218 . . . 52, 220 86, 221, 222 . . . . . 223 . . . . . 224 . . . . . 226

SendDTMFtones . . . . SendDTMFtonesSynch . SeqCoupleCount . . . . SeqCoupleCreate . . . . SeqCoupleGet . . . . . SeqCoupleGetAttrib . . . SeqCoupleGetVal . . . . SeqCoupleLimit . . . . . SeqCoupleSet . . . . . SeqStringAdd . . . . . . SeqStringCount . . . . . SeqStringCreate . . . . SeqStringGet . . . . . . SeqStringLimit . . . . . SupressEvents . . . . . SupressResponses . . . SwapHeld . . . . . . . SwapHeldSynch . . . . Terminate . . . . . . . TerminateSynch . . . . Transfer . . . . . . . . TransferCancel . . . . . TransferCancelSynch . . TransferComplete . . . . TransferCompleteSynch . TransferInit . . . . . . . TransferInitSynch . . . . TransferSynch . . . . . VDUCreate . . . . . . . VDUCreateSynch . . . . VDUFindVDU . . . . . . VDUFindVDUSynch . . . VDUGetActive . . . . . VDUGetActiveSynch . . VDUGetData . . . . . . VDUGetDataSynch . . . VDUGetOneValue . . . VDUGetOneValueSynch VDUGetValues . . . . . VDUGetValuesSynch . . VDUSetCurrent . . . . . VDUSetCurrentSynch . . VDUSetValues . . . . . VDUSetValuesSynch . . WaitForResponse . . . . WrapUp . . . . . . . . WrapUpOverride . . . . WrapUpOverrideSynch . WrapUpSynch . . . . . Multiple controllers . . . . . Multiple servers . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . 227 . . . . 228 . . 60, 230 . . 60, 231 . . 60, 232 . . 60, 233 . . 60, 235 . . 60, 237 . . 60, 238 . . 61, 239 . . 61, 241 . . 61, 242 . . 61, 243 . . 61, 245 . . 59, 248 . . 57, 249 . . 51, 250 . . 52, 251 . . 51, 252 . . 52, 253 . . 51, 254 . . 51, 255 . . 52, 256 . . 51, 257 . . 52, 258 . . 51, 260 . . 52, 261 . . 52, 262 . . 53, 263 . . 54, 265 . . 53, 266 . . 54, 267 . . 53, 269 . . 54, 270 53, 54, 273 . . 54, 274 . . 53, 275 . . 54, 277 . . 53, 278 . . 54, 279 . . 53, 280 . . 54, 282 . . 53, 283 . . 54, 284 . . 57, 286 . . 51, 288 . . 51, 289 . . 53, 290 . . 53, 291 . . . . . 46 . . . . . 47

Issue 2.1 August 2003

295

Mutex . . . . . . . . . . . . . . . . . . . . . . . 25

O OLE Automation . . . . . . . . . . . . . . . . . . 14 OLE connections Breaking . . . . . . . . . . . . . . . . . . . . 18 Making . . . . . . . . . . . . . . . . . . . 16, 18

P PeekEvent . . . . . . . . . . PeekResponse . . . . . . . . Phone states Busy . . . . . . . . . . . Ready . . . . . . . . . . WrapUp . . . . . . . . . Ping . . . . . . . . . . . . . PingSynch . . . . . . . . . . Polling conflicts in Visual Basic Programming example . . . . Proxy class . . . . . . . . .

. . . . . . . . 59, 203 . . . . . . . . 57, 206 . . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . 78 . 211, 212 . 289, 290 . 56, 208 . 56, 209 . . . . 24 . . . . 33 . . . . 17

R

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

60, 232 60, 233 60, 235 60, 237 60, 238 61, 239 61, 241 61, 242 61, 243 61, 245 . . . 60 . 30, 60 . 30, 61 . . . 55 . . 246 . . 247

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . 33 59, 248 57, 249 51, 250 52, 251 . . . 46

T

Ready . . . . . . . . . . . . . . . . . Ready state . . . . . . . . . . . . . . ReadyOverride . . . . . . . . . . . . . ReadyOverrideSynch . . . . . . . . . . ReadyPhoneset . . . . . . . . . . . . ReadyPhonesetSynch . . . . . . . . . ReadySynch . . . . . . . . . . . . . . Reason Codes (Definity) . 86, 221, 222, Registering VTel . . . . . . . . . . . . Registry entries . . . . . . . . . . . . ResetPhones . . . . . . . . . . . . . ResetPhonesSynch . . . . . . . . . . Response codes . . . . . . . . . . . . Response processing . . . . . . . . . Response Processing Methods . . . . . RestartServer . . . . . . . . . . . . . RestartServerSynch . . . . . . . . . . Rona . . . . . . . . . . . . . . . . .

. . . 51, 210 . . . 211, 212 . . . .51, 211 . . . 52, 212 . . . 51, 213 . . . 52, 214 . . . 52, 215 223, 224, 226 . . . . 15, 46 . . . . . . 48 . . . 51, 216 . . . 52, 217 . . . . . . 61 . . . . . . 27 . . . . . . 57 . . . 51, 218 . . . 52, 220 . . . . . 221

S SendDefinityAux . . . . . SendDefinityAuxSynch . . SendDefinityLogout . . . SendDefinityLogoutSynch SendDTMFtones . . . . . SendDTMFtonesSynch . . SeqCoupleCount . . . . . SeqCoupleCreate . . . .

SeqCoupleGet . . . . . . . . . SeqCoupleGetAttrib . . . . . . . SeqCoupleGetVal . . . . . . . . SeqCoupleLimit . . . . . . . . . SeqCoupleSet . . . . . . . . . SeqStringAdd. . . . . . . . . . SeqStringCount . . . . . . . . . SeqStringCreate . . . . . . . . SeqStringGet . . . . . . . . . . SeqStringLimit . . . . . . . . . Sequence Management Methods Sequence of couples . . . . . . Sequence of strings . . . . . . . Session Management Methods . SetAutoIn . . . . . . . . . . . SetAutoInSynch . . . . . . . . Softphone implementation Example . . . . . . . . . . SupressEvents . . . . . . . . . SupressResponses . . . . . . . SwapHeld . . . . . . . . . . . SwapHeldSynch . . . . . . . . Synchronous Methods . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. 86, 221, 222 . . . . . 223 . . . . . 224 . . . . . 226 . . . . . 227 . . . . . 228 . . . 60, 230 . . . 60, 231

296 VTel Automation Server Programmer Guide

Terminate . . . . . . . . . . . . TerminateSynch . . . . . . . . . Transfer . . . . . . . . . . . . . consultative . . . . . 255, 256, TransferCancel . . . . . . . . . . TransferCancelSynch . . . . . . . TransferComplete . . . . . . . . . TransferCompleteSynch . . . . . . TransferInit . . . . . . . . . . . . TransferInitSynch . . . . . . . . . TransferSynch . . . . . . . . . .

. . . . . . 51, 252 . . . . . . 52, 253 . . . . . . 51, 254 257, 259, 260, 261 . . . . . . 51, 255 . . . . . . 52, 256 . . . . . . 51, 257 . . . . . . 52, 258 . . . . . . 51, 260 . . . . . . 52, 261 . . . . . . 52, 262

V VDUCreate . . . . . . . VDUCreateSynch . . . . VDUFindVDU. . . . . . VDUFindVDUSynch. . . VDUGetActive . . . . . VDUGetActiveSynch . . VDUGetCurrent . . . . . VDUGetCurrentSynch . . VDUGetData . . . . . . VDUGetDataSynch . . . VDUGetOneValue . . . VDUGetOneValueSynch VDUGetValues . . . . . VDUGetValuesSynch . . VDUSetCurrent . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

53, 263 54, 265 53, 266 54, 267 53, 269 54, 270 53, 271 54, 272 53, 273 54, 274 53, 275 54, 277 53, 278 54, 279 53, 280

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. 54, 282 . 53, 283 . 54, 284 . . . 16 . 16, 19 . . . 24 . 17, 19 . . . 15 . 15, 46 . . . 15

WaitForResponse . . . WrapUp . . . . . . . . WrapUp state . . . . . WrapUpOverride . . . WrapUpOverrideSynch WrapUpSynch . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. 57, 286 . 51, 288 289, 290 . 51, 289 . 53, 290 . 53, 291

VDUSetCurrentSynch VDUSetValues . . . VDUSetValuesSynch vesporb.dll . . . . . Visual Basic . . . . . Polling conflicts . Visual C++ . . . . . VTel . . . . . . . . Registering . . . vtel.ini . . . . . . .

W

Issue 2.1 August 2003

297

298 VTel Automation Server Programmer Guide