Web Telephony Engine

Purpose

The Microsoft® Web Telephony Engine is a service that can be installed and run on systems running Windows® 2000 Server or Windows® 2000 Advanced Server. This service lets you use Web-development tools such as HTML, Microsoft ActiveX® controls, scripting languages, and Active Server Pages (ASP) to create Web pages accessible by telephone and Internet browser and to build HTML-based telephony applications.

Where Applicable

Web Telephony Engine lets you create dedicated telephony applications, such as Interactive Voice Response solutions, for business and consumer users. Developers wanting to build telephony solutions using HTML, Active Server Pages and related technologies and services will find that Web Telephony Engine makes that process faster and easier. Developers wanting to extend their Web sites to enable telephone users to browse the content using telephone dial pad or speech commands for navigation and text-to-speech or pre-recorded media for content rendering also will find Web Telephony Engine a very productive tool. The ability to provide graphical and telephony user interfaces from a single source makes your application accessible to millions of people using telephones in addition to the people using regular Web browsers. This can be an innovative and affordable way to make your current Web site content and applications useful in mobility scenarios in which use of a PC is not possible or preferred by the user. This also can provide the ability to enable new content or applications to be developed specifically for mobile users via the telephone. On the server side, the single code base means easier maintenance on the installed application.

Audience

Software developers can use the various COM interfaces that Web Telephony Engine exposes, along with standard HTML coding, to create, configure, and maintain IVR applications that run on a variety of hardware and software configurations. Vendors of development tools can use the same set of interfaces to provide monitoring and analysis tools for development and administration applications. Finally, systems administrators can access the interfaces to customize Web telephony applications, and to collect and log user data.

To develop Web telephony applications, you should be familiar with interactive telephony application design, HTML, and COM object programming (in any supporting language). In addition, an understanding of client- and server-side scripting, the Microsoft Speech API (SAPI), the Windows Telephony Application Programming Interface (TAPI) 3.0 Call object, and the Microsoft Internet Explorer Object Model are recommended.

Hardware and Software Requirements

In addition to Windows® 2000 and Web Telephony Engine, which is distributed with the Platform SDK, you will need an IP device, or a TAPI 2.1-compliant voice board or voice modem. If your voice board or modem driver is not integral to Windows® 2000, you also will need to install the appropriate telephony service provider (TSP).

Your application can use any text-to-speech or speech-recognition engine that supports Microsoft SAPI 4.0a technology. Narrator, the Microsoft TTS engine, is part of the Windows® 2000 operating system. You can also download, at no charge, Microsoft's SAPI 4.0a speech-recognition engine from http://www.microsoft.com/IIT.

See Also

Microsoft Telephony Overview,

Internet Information Services SDK,

Component Object Model

ActiveX Controls

Overview

General information about Web Telephony Engine.

Reference

Documentation of Web Telephony Engine.

Feedback via email

Make error reports and feature requests directly to Microsoft.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


Legal Information

Microsoft Web Telephony Engine

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, people and events depicted herein are fictitious and no association with any real company, organization, product, person or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 1999-2000 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Windows, Windows NT, Active Directory, ActiveX, BackOffice, JScript, MSDN, Visual Basic, Visual C++, Windows NetMeeting, and Win32 are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries/regions.

International CorrectSpell is a trademark of Lernout & Hauspie Speech Products, N.V.

Macintosh is a trademark of Apple Computer, Inc., used under license.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.


About Web Telephony Engine

The Microsoft® Web Telephony Engine is a system-level component that renders HTML code over the telephone. Web Telephony Engine lets you use HTML and other Web technologies to create single-source, dual-access Web sites and speech-enabled, interactive voice response (IVR) applications. You can accomplish this with WTE almost as easily as you can build a conventional Web site and with far less difficulty than when you create traditional IVR applications. Building traditional IVR applications typically means you must learn a complex, often proprietary language.

With the explosion in wireless mobile devices, Web Telephony Engine enables you to make your Web site or Web applications available to your users anytime, any place using speech or telephone dial pad navigation commands and text-to-speech or recorded media content rendering.

This section gives a general overview of Web Telephony Engine applications and technologies, explains the benefits and opportunities that Web Telephony Engine provides, and describes the various Web Telephony Engine components and features. For information about specific topics, see the following sections:

  • About Interactive Voice Response
  • Benefits of Web Telephony Engine
  • Opportunities for Third-Party Vendors
  • Web Telephony Components
  • Features of the Web Telephony Engine

If you are interested in learning more about developing dual-access Web sites and IVR applications for WTE, as well as exchanging news and information with other WTE developers, you can subscribe to the Usenet newsgroup, microsoft.public.platformsdk.telephony.wte. You can also send questions by e-mail to wtetalk@microsoft.com.


About Interactive Voice Response

An interactive voice response (IVR) application is a set of rules and commands. These instructions allow a voice-response engine to lead a telephone caller through a hierarchy of menus, collect voice and data input, and perform other operations on behalf of the caller or the program sponsor.

Large businesses use IVR to perform or support many telecommunications functions. If PC-based solutions were more widely available and adaptable, small businesses and departments within larger enterprises could also make use of IVR. See Benefits of Web Telephony Engine.

Typical IVR applications for businesses include auto-attendants. These provide recordings asking callers who get a busy signal or no answer to leave a message. The recordings also provide information and transaction services such as bank balances and account transfers.

The elements of a traditional IVR system typically include:

  • Authoring environment. Creates the program database.
  • Program database. Contains programming specific to the IVR configuration.
  • Run-time engine. Processes the program database either to answer incoming phone calls or generate outgoing phone calls.
  • Telephone. Initiates incoming call or fulfills outgoing call.

The following illustration shows the relationships among these elements:

IVR development platforms offer integration with other computer and telephone technologies such as unified messaging, corporate databases, telephony systems, security, and user verification. In larger companies, IVR systems are commonly connected by means of a private branch exchange (PBX). The following illustration shows how an IVR system based on Web Telephony Engine (WTE) connects with the PBX to control the switch operation and conduct a phone conversation with the customer. The agents are available for callers whose inquiry cannot be satisfied by the automated IVR system. In a small business, the agent could be the office receptionist and, after office hours, an answering machine.

IVR platforms can be integrated with other computer technologies as well. As the preceding illustration shows, an IVR system can also be connected to a range of applications, such as a Microsoft® Exchange server that provides an infrastructure for unified messaging and to a SQL server that provides database connectivity. Also, note that the illustration shows WTE connected to the PBX with the out-of-band link. Typically, only one machine can connect to the PBX. In most systems, the WTE connects to the PBX through an Internet Information Services (IIS) computer because it can arbitrate requests from multiple WTE computers.


Benefits of Web Telephony Engine

Designing and producing interactive voice response (IVR) applications by means of traditional methods is complicated, time-consuming, and expensive. Highly-skilled designers and programmers must work closely with the customer to specify, test, and implement an IVR application. Redesigning or reprogramming a traditional IVR application is also difficult and costly. As a result, IVR applications have been restricted to large scale, repetitive applications.

By contrast, Web telephony brings the convenience of Web authoring to the IVR development world. Web Telephony Engine (WTE) lets IVR developers use HTML and other Web authoring technologies such as scripting, Java, Microsoft® ActiveX® and Active Server Pages (ASP) to design, publish, and refine IVR applications quickly and efficiently.

WTE makes it possible to create a single application, called a dual-access application, that is accessible to both graphical browsers and telephone users. In a dual-access application, it is possible to show parts of an application's HTML content in one medium and not another. For example, content involving telephony operations would be hidden from the user of a Web browser and descriptive text voice files would be substituted for graphics when a user accessed the application by telephone.

Web telephony is distributable; that is, the actual Web Telephony Engine can be located anywhere, as long as it can connect to your Web server through Hypertext Transfer Protocol (HTTP). The WTE application can run on any Web server that supports server-side scripting.

Web telephony lets developers publish information, solicit user input, create links, execute telephony-specific commands, and access peripheral technologies such as unified messaging and databases.

WTE supports Windows Telephony Applicatoins Programming Interface (TAPI) 3.0 (TAPI) 3.0. This means that you can use any telephony service provider that supports TAPI 2.1 or TAPI 3.0, including voice boards or voice modems. You can even combine several platforms at once, or change them. This is all transparent to the application.


Opportunities for Third-Party Vendors

Web telephony technology offers a platform to facilitate cooperation between many industry segments:

  • Vendors of voice boards, Integrated Services Digital Network (ISDN) BRI (144,000 bits per second, two voice channels), ISDN PRI (1,544,000 bits per second, 30 voice channels), and station emulation boards can create TAPI drivers for their hardware.
  • Vendors of speech products can create Service Access Point (SAP) IDs to bind applications to their speech boards or engines.
  • Vendors of development tools can use the debugging COM objects of the Web Telephony Engine (WTE) to create tools to develop Web telephony applications. Those vendors add value by providing monitoring and analysis tools that help administrators fine-tune their applications to better serve their customers over time. For more information, see Developing a Debugging Application.
  • Vendors of telephony technology (for example, caller verification and directory assistance) can provide ActiveX® components.

These vendor-supplied components can be used together with Web telephony technology to create a dual-access Web site or pure IVR applications in industry sectors such as finance, insurance, real estate, health care, travel, and telemarketing.

Authorized resellers can use Web telephony to tailor solutions such as those shown in the diagram in About Interactive Voice Response. Software vendors that provide IVR application generators and those that develop Internet authoring tools can provide authoring environments for this system. Because Web telephony technology is open and standards based, vendors need to comply with the published set of HTML attributes and telephony-specific ActiveX interfaces. Vendors of Internet management tools can develop capacity planning, statistical analysis, and other management tools in the same way.


Web Telephony Components

Web telephony includes the following components:

  • The run-time engine, which renders HTML and Web scripting languages over the telephone.
  • The administration user interface (UI), which is used to configure Web Telephony Engine (WTE) and to install and configure Web telephony applications. The COM interfaces that service this UI are also exposed for you to create customized administration and configuration tools, set configuration parameters during installation, and embed as objects directly into your WTE application.
  • The application programming interface (API), including the extended object model and the pertinent HTML elements and rules that allow these elements to be rendered over the phone.
  • Access to the TAPI 3.0 Call object, which enables telephony operations such as call transfer using the TAPI 3.0 scripting API.

Together, these components provide a flexible platform for telephony-accessible Web sites. Because Web telephony is based on Web technology, it is easy to extend its capabilities to interact with other Microsoft Internet and e-mail products such as Internet Information Services (IIS) and Exchange. Moreover, the HTML-based design facilitates single sourcing of a business telephone and Internet/intranet information.


Features of the Web Telephony Engine

Web Telephony Engine (WTE) uses the Web-browser component of Microsoft® Internet Explorer to access applications and render them over the telephone. Essentially, WTE is Internet Explorer with a telephony user interface (TUI) added and the graphical user interface (GUI) turned off. The engine is designed primarily to render pages of Web telephony applications—it cannot render any and all Web pages.

This section discusses the features of the Web telephony engine. For information about specific topics, see the following sections.

The following sections discuss these aspects of Web telephony building blocks:

  • HTML Support
  • Scripting Support
  • Java Applets and ActiveX Support
  • Interoperability with Other Microsoft Server Products
  • Integration with Telephones, Speech Engines, and Other Technologies


HTML Support

The WTE supports applications written in the hypertext markup language (HTML)—the standard publication language of the World Wide Web. Because HTML is designed to facilitate links between documents, it is suitable for creating the nested menus that are typical in interactive voice response (IVR) applications. WTE supports standard HTML, and defines HTML extensions that provide phone-specific functionality.

To leverage a well-documented and widely understood publication HTML platform, the WTE adds phone-specific attributes to applicable HTML elements. For example, the VOICEFILE attribute allows a voice file to be played as an alternative to text-to-speech (TTS) rendering.

Using HTML elements and extensions, IVR application developers can build a hierarchy of audio information pages, and these pages are simple to rewrite and replace. In fact, the Web model allows the entire application hierarchy to be redesigned should the need arise.

Microsoft is a member of the Voice Browsing Working Group of the World Wide Web Consortium (W3C) and is working together with the group to make these extensions a part of the HTML language.


Scripting Support

In cases where HTML lacks the flexibility required for some IVR applications, Microsoft Visual Basic® Scripting Edition (VBScript) and JScript® can be used. The scripts can be used in the same way as in a regular HTML page. Using scripting, the IVR developer can create more powerful and flexible IVR applications.

WTE uses the same component object model (COM) as Internet Explorer. This means that all the familiar Internet Explorer scripting objects are also available to Web telephony applications. In addition, the engine provides extensions to the Internet Explorer object model to support IVR applications. For more information, see Extended Object Model Overview.


Java Applets and ActiveX Support

To support more flexible operations, WTE allows the integration of Microsoft ActiveX® components and scripts written in popular scripting languages. For example, phone-specific ActiveX components operating in the context of the run-time engine can provide object-oriented access to telephony equipment. Third-party vendors can publish their code as ActiveX components, and receive call-context information from the run-time engine. Examples of applications that third-party vendors can develop include user verification and speech recognition-based directory assistance. The functionality of ActiveX components is accessible using VBScript and JScript. WTE also supports Java applets.


Interoperability with Other Microsoft Server Products

Web telephony provides interoperability with other Microsoft Windows NT®/Windows® 2000 server products. It can access Internet Information Services (IIS) using the Hypertext Transfer Protocol (HTTP) to render HTML scripts over the phone. With just a few conditional tags, data available to an intranet or Internet site can be sent over the phone from a single source. Note that because of design differences between the telephony user interface (TUI) and an Internet browser's interface, the data navigation path through the TUI may differ from the data navigation path through the browser UI. However, large blocks of data can be single sourced in this way.


Integration with Telephones, Speech Engines, and Other Technologies

Microsoft Telephony Application Programming Interface (TAPI) provides a well-documented set of application interfaces designed to handle telephone system integration. TAPI isolates an application from the complexities of the telephone system and lets developers focus on their programming goals. WTE supports the TAPI 3.0 interface to access telephony line devices used for IVR, such as voice boards and modems. WTE does not include a TAPI interface for accessing a switching device such as automatic call distributor (ACD), private branch exchange (PBX), or key system. However, WTE allows application writers to use any standard to access these switching devices.

Web telephony applications also use Microsoft Speech API (SAPI) technology, which performs speech recognition (SR) and text to speech (TTS) over any SAPI-compliant speech engine. If no other speech engine is selected, Web telephony uses the Microsoft automatic system reconfiguration (ASR) and TTS engines. Note that the Microsoft ASR engine must be installed from the SAPI 4.0a Software Developer's Kit (SDK)—it is not installed by default.

The Web provides a solid integration model for IVR-related technologies. Many of the technologies used in Web development apply to IVR as well, such as security and authentication, database access, and unified messaging. Because many vendors of such technologies provide ActiveX or Active Server scripting interfaces, their integration with HTML and Visual Basic scripts is routine. Web telephony provides access to the TAPI call object for scripts and ActiveX components designed to interact with the caller or affect the progress of a call.


Using Web Telephony Engine

This section consists of the following topics:

  • Administering Web Telephony Engine Service
  • Authoring a Web Telephony Application
  • Programming Administration and Configuration Tasks
  • Using the Web Telephony Log
  • Developing a Debugging Application


Administering Web Telephony Engine Service

This section tells you how to set up the Microsoft® Web Telephony Engine (WTE) service, and how to add, configure, and run Web telephony applications. For information about specific topics, see:

  • Setting up the Web Telephony Engine Service
  • Adding and Running a Web Telephony Application
  • Setting the Configuration Parameters of an Application
  • Using the Web Telephony Engine COM Objects for Configuration and Administration
  • Troubleshooting


Setting up the Web Telephony Engine Service

This section provides the information you need to get the Web Telephony Engine (WTE) up and running. For information about specific topics, see:

  • Known Issues and Limitations
  • System Requirements
  • Installing the Telephony Service Provider
  • Installing a Modem
  • Installing the Audio Driver
  • Installing Web Telephony Engine Software
  • Determining or Modifying Account Information
  • Controlling the Web Telephony Service


Known Issues and Limitations

Following is a list of the known issues and limitations associated with this release of WTE:

  • WTE must be running in the context of a system administrator account, or Local System Account.
  • WTE supports only pulse code modulation (PCM) audio formats. For a list of supported formats, see PCMWaveFormats. For best results, use a format supported by the audio driver.
  • This release was tested with up to 24 concurrent calls, yielding good results on a Pentium III computer, 500 megahertz (mHz), 256 megabytes (MB) of random access memory (RAM). It is possible to use the system with more telephone lines.
  • WTE may not answer calls right after rebooting the host system in automatic startup mode. The TAPI service and the voice board's service start concurrently and as a result the TAPI service may fail to open the lines. To avoid delays in call answering by WTE, you need to configure the services by means of the Computer Management service.
  • In this release, WTE does not use the Address Group logging field.
  • WTE supports Microsoft JScript®, but not the JScript protocol (<A HREF=javascript:foo()></A>). If the caller chooses such a link, a warning log is generated but the operation is not carried out.
  • The GoBack method does not return to the correct point if the WTE loads a page into a frame in which the page is already loaded.
  • If the LANGUAGE attribute is not specified in a SCRIPT element or in an event handler, the WTE assumes that the default language is JScript. This is not always the case for Microsoft Internet Explorer. It is recommended that you specify the LANGUAGE attribute on all SCRIPT elements and event handlers.
  • The NOHREF attribute is ignored when it is used on an AREA element. WTE disables the menu item only if the NOHREF attribute is set from a script.
  • The window.close method is not supported. It will cause a call to be blocked.
  • If a script invokes a message box, the call might be blocked (see Message Box Management). Other calls are not affected. If the caller hangs up the current call, the next call will be answered. The window mode of the WTE is useful for determining the cause of a blocked call. For more information, see Running the Web Telephony Service in Window Mode.
  • Setting any of the text-to-speech (TTS) speed, pitch or volume parameters to a value that is out of the TTS engine's range disconnects the call. An audio failure is logged.


System Requirements

This section describes the software and hardware requirements of the WTE.

Operating System

The WTE runs only on machines that have the Microsoft Windows® 2000 operating system installed.

SAPI 4.0a-Compliant Speech Engines

The WTE uses a TTS engine to generate spoken words from the text in an application's HTML pages. It can also use a speech-recognition (SR) engine to receive spoken input from the caller. The WTE can use any TTS or SR engine that supports Microsoft SAPI technology.

Because Windows 2000 includes the Microsoft TTS Engine, you do not need to install a TTS engine in order to use the WTE. However, you need to install an SR engine to enable the WTE to use SR. You can install the Microsoft SR engine from the SAPI 4.0a Software Developer's Kit.

Hardware Requirements

The preferred way to run a Web telephony application is with a voice board or voice modem. For more information, see Installing the Telephony Service Provider and Installing the Audio Driver. You can also run the Web telephony service by using the Internet Protocol (IP) device integral to the Windows 2000 operating system.

Verifying the Hardware Installation

To verify that the voice modem or voice board is functioning properly, try calling the telephone line attached to the modem or board. Then, using any sample TAPI application, try to play an audio (wave) file. You should hear the file being played over the telephone if the modem or board is functioning properly.


Installing the Telephony Service Provider

If your Web telephony configuration includes a voice board or voice modem that is not integral to Windows 2000, you may need to install the telephone service provider (TSP) driver for your device.

To add a telephony service provider

  1. Click the Start button, point to Settings, and then click Control Panel.
  2. Double-click Phone and Modem options.
  3. On the Advanced tab, click Add.
  4. In Telephony Providers, click the specific TSP.
  5. Click Add.
  6. Click Configure to configure the TSP.

Note When you install a TSP, you must also install the associated audio driver.

If you are using a universal modem driver (Unimodem) V device for voice, you do not need to install a TSP.

This procedure adds only TSPs with drivers that are already installed on your hard drive in the systemroot\system32 folder. To install new drivers, use the setup or installation program provided on the manufacturer's disk.


Installing a Modem

If your Web telephony configuration includes a voice modem that is not integral to Windows 2000, you will need to install the modem.

To install a modem

  1. Click the Start button, point to Settings, and then click Control Panel.
  2. Double-click the Phone and Modem Options.
  3. On the Modems tab, click Add.
  4. Follow the instructions in the Add/Remove Hardware Wizard.


Installing the Audio Driver

If your Web telephony configuration does not use the IP device or a modem that is integral to Windows 2000, you must install the audio (wave) driver.

To install the audio driver

  1. Click the Start button, point to Settings, and then click Control Panel.
  2. Double-click Add/Remove Hardware, and then click Next.
  3. Click Add/Troubleshoot a device, and then click Next.
  4. Select Add a new device from the Devices list, and then click Next.
  5. Click No, I want to select the hardware from a list, and then click Next.
  6. Click Sound, video, and game controllers, and then click Next.
  7. Click Have Disk, and then click Browse. Find the .inf file for the associated driver.

    Note In many cases, the audio driver is automatically installed when you install the voice board.


Installing Web Telephony Engine Software

When Web Telephony Engine (WTE) is installed, it runs as a service under Windows 2000. Before installing WTE, read the information in the Read1st.txt file included in the Platform Software Developer' Kit.

To install the WTE software:

At a command prompt, type

path\WTESETUP.exe

where path is the location of the WTE installation files. The path may be a folder on the Platform SDK compact disc (CD) or a shared folder on your network that contains the WTE files.

Follow the instructions in the Setup wizard. During setup, you will be prompted to enter account information for the Web telephony service. In the Web telephony Service Configuration dialog box, type the Domain Name, User Name, and Password. Note that the domain\user must be an administrator. Whenever you change the password, be sure to also change the password for the Web telephony service, unless you are running in LocalSystem mode. The Local System Account does not require a password.

Managing an Unattended Installation or Removal

To run the WTE setup program unattended (if, for example, you are installing WTE on several machines at once), set the environment variable WTE_INSTALL_FLAGS to one of the following:

  • /q — to suppress all dialog boxes except the exit dialog box.
  • /q1 — to suppress all dialog boxes, including the exit dialog box.
  • /qt — to suppress dialog boxes for the entire setup process, including the blue background and the copy gauge.

Note that the default installation directory for Web Telephony Engine is"%ProgramFiles%\Web Telephony Engine". With this default, the WTE service will be logged on to the Local System Account. See Running WTE in a Local System Account for more information.

To change the default installation directory in unattended setup, create a file named "wte.ini" in the %WINNT% directory, with the following:

    [WTE Setup Install]
    Install Dir=<Directory_Name>

where <Directory_Name> is the directory in which you want WTE installed.

To silently uninstall the WebTelephony Engine (WTE) Server, run

<WTEInstallPath>\setupbin\setup.exe /u <options>

where <WTEInstallPath> is the WTE Server installation directory, and <options> can be one of the following:

  • /q—to suppress all dialog boxes except the exit dialog box.
  • /q1—to suppress all dialog boxes, including the exit dialog box.
  • /qt—to suppress dialog boxes for the entire setup process, including the blue background and the copy gauge.

Running WTE in a Local System Account

The option to run WTE in a local system account is available during setup. Be aware, however, that this configuration means that many resources are not available to your WTE application.

Here are some specific resources that will be unavailable if you run WTE in a local system account:

  • WTE running in LocalSystem mode cannot access network resources relying on NT LAN Manager (NTLM) authentication. These resources include file shares, named pipes, and access to a remote computer's event log, registry or Service Control Manager. For example, if you have the following line in your HTML code:
    <A VoiceFile="file:<\\server\netshare\wave.wav>"></A>
    WTE will not be able to retrieve that file while running in LocalSystem mode. If WTE is running in a Local system account, either the files must also be local, or you must use the HTTP protocol for access.
  • WTE running in LocalSystem mode cannot open the HKLM_CURRENT_USER registry key. Since WTE uses Internet Explorer browser options and stores each user's settings (Internet Explorer->Tools->Internet options), any changes you make to these settings will be ineffective if WTE is running as LocalSystem. For example, if a Microsoft ActiveX® control requires custom security settings, those settings will not be known to WTE if running in LocalSystem mode.

Note If the computer on which you install WTE is not part of a Windows 2000 domain, WTE is installed as a stand-alone server. You can subsequently add the server to a Windows 2000 domain, and then join it to an array of WTE servers.


Determining or Modifying Account Information

After installation, you can use the Computer Management tool in Windows 2000 to determine which account is running the Web telephony service and to modify the account information.

To determine or modify the account

  1. Click the Start button, point to Programs, point to Administrative Tools, and then click Computer Management.
  2. Open the node System Tools, click Services, and double-click Microsoft Web Telephony Engine Service.
  3. On the Log On tab, select This Account to access the user account information, or Local System Account to access the local system account information.
  4. Enter your account information.


Controlling the Web Telephony Service

You can control the Web telephony service by performing the operations described below. Note that the account used to log on to the WTE service must have administrator privileges.

  • Start—Starts the WTE service.
  • Hard stop—Immediately ends all calls and terminates the WTE service. Use this operation if there are no active calls and all post-processing is completed.
  • Hard pause—Disconnects all active calls, but does not shut down the service.
  • Soft stop—Refuses to accept new calls, but allows existing calls to continue for the specified amount of time before the service stops.
  • Soft pause—Same as soft stop, but does not shut down the service.
  • Resume—Resumes the service after it was paused and begins accepting calls again.

There are several ways to perform the preceding operations:

  • Select an operation by using the Computer Management application.
  • Send a command through the net utility.
  • Use the sc.exe utility to send private WTE control values defined in the PrivateWTEControlsType enumeration.
  • Call the Microsoft Win32® ControlService function within an application.

Using Computer Management to Control the Service

The Computer Management application lets you perform the start, hard stop, hard pause, and resume operations.

To use Computer Management

  1. Click the Start button, point to Programs, point to Administrative Tools, and then click Computer Management.
  2. Open the node System Tools and then click Services.
  3. Right-click Microsoft Web Telephony Engine Service and select the desired command from the menu.

Using the Net Utility to Control the Service

The net utility lets you perform the start, hard stop and hard pause operations from the command line. To perform these operations, use one of the following commands.

net start mswtesrv

net stop mswtesrv

net pause mswtesrv

Using the SC.exe Utility to Control the Service

The SC.exe utility lets you perform the soft-pause and soft-stop operations, flush logging data to the log file, and reload (refresh) configuration parameters from the persistent storage. To perform these operations, use one of the following commands:

Soft pause:            sc control mswtersv 128
Soft stop:             sc control mswtesrv 129
Flush to the log file: sc control mswtesrv 130
Refresh from storage:  sc control mswtesrv 131

Using the ControlService Function to Control the Service

Web telephony supports two private service-control values that you can use in an application to perform a soft-pause or soft-stop operation. These values are defined in the PrivateWTEControlsType enumeration.

To perform a soft pause, pass the wteServicePauseSoft service-control value to the ControlService function.

To perform a soft stop, pass the wteServiceStopSoft service-control value to the ControlService function. Web telephony responds by playing a shut-down announcement to alert each caller that the service is about to stop.

The ShutdownTime and ShutdownAnnouncement properties of the WTEApplication object specify the amount of time that calls are allowed to continue, and the text or wave file that Web telephony uses for the shutdown announcement. These properties can also be configured through the application's property sheet in the WTE administration tool.

Note that if the ShutdownTime property is set to zero, the soft stop behaves like a hard stop. Also, if the ShutdownTime property is set to -1, the time-out period is infinite; that is, if calls do not disconnect themselves, they will not be disconnected when the service is soft paused or soft stopped. After the ShutdownTime property is set to -1, the service will not pause or stop.


Adding and Running a Web Telephony Application

This section explains how to add and run your Web telephony applications. For information about specific topics, see:

  • Adding an Application
  • Running an Application
  • Running the Web Telephony Service in Window Mode


Adding an Application

An application must be added before WTE can run it. Adding an application provides the engine with the application's name and description, the location of its home page, and the line(s) that the application will use for incoming calls. You add an application by using the Add Web Telephony Application Wizard in the WTE administration tool. A setup program can use the administration COM interfaces to install an application. For more information, see The Web Telephony Object Model.

To add a Web telephony application

  1. Click the Start button, point to Programs, point to Microsoft Web Telephony, and then click Web Telephony Engine Administration Tool.
  2. In the Console Root tree, double-click Web Telephony, right-click Applications, click New, and then click Application. When Add Web Telephony Application Wizard appears, click Next.
  3. Enter the name and an optional brief description of the application, and then click Next.
  4. Enter the home page for the application. This is the first HTML page that the WTE renders when a call arrives. Although you can enter a path as the home page, it is better to use the HTTP protocol to access HTML pages. For example: http://MyIIS/Demo/demo.htm

    Note that Active Server Pages (.asp) files must be accessed by means of the HTTP protocol.

  5. After entering the home page, click Next.
  6. Select the line to use to connect to your application from the Available addresses or DNISes and addresses or DNISes assigned to other applications list, click Associate (move up), and then click Next.
  7. Click Finish to complete the installation procedure.


Running an Application

When a new call arrives on the line with which an application is associated, WTE navigates to the application's home page. If the 'Automatic answer' option is on (the default setting), the call is answered.

Calling an Application

You can use a telephone to dial the number of the line associated with the application. Alternatively, you can use your own TAPI 3.0 application or Phone Dialer, which is a telephony application distributed with Windows 2000.

To use Phone Dialer to call a Web telephony application

  1. Click Start, point to Programs, point to Accessories, point to Communications, and then click Phone Dialer.
  2. Click Edit, then click Options.
  3. On the Addresses tab, for Internet Calls, select H.323 Line.
  4. On the Audio/Video tab, set:
    • Line to Internet Calls.
    • Audio Record and Audio Playback to the audio device driver of the speakers installed on your computer. (WTE will use the IP TAPI device during the call and the sound on the caller party will be directed to the speakers.)
  5. Click Dial. In the Dial dialog box:
    • Click the Internet Call radio button.
    • Type the IP address (machine name) of the computer on which the WTE is installed.

Configuration Changes

The WTE periodically checks for configuration changes. After making any configuration changes, wait approximately five seconds for the changes to take effect. The delay between the change in the storage and the time that the service adopts the new configuration is defined by the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Web Telephony Engine under the NotifyPeriodAfterFirstUpdate attribute (the value is in seconds).

An application can force a configuration change to take effect by calling the Win32 ControlService function and specifying the wteServiceRefreshStorage service-control value.


Running the Web Telephony Service in Window Mode

WTE supports a command-line option that lets you run the Web telephony service in window mode. This mode is useful while developing or debugging an application. While in window mode, the WTE service displays the currently loaded HTML page in a window on the host computer, allowing you to see your application as it runs. Note that window mode does not affect what a caller or browser user sees or hears.

To run the Web telephony service in a window

  1. Stop the Web telephony service. For instructions on how to stop the service, see Controlling the Web Telephony Service.
  2. Determine the Web telephony directory by following these steps:
    1. Click the Start button, click Programs, click Administrative Tools, and then click Computer Management.
    2. Open the node System Tools, click Services, right-click Microsoft Web Telephony, and then click Properties.
    3. On the General tab, note the Path to executable – this is the Web telephony directory.
  3. Run Web telephony as an executable from its directory, by typing the following command:
    mswtesrv.exe -exe

Type the following command to stop the WTE executable:

mswtesrv.exe -stop

Application Images and Browser Messages

By default, the Web telephony service does not display any application images while running in a window, nor does it show any browser messages such as security warnings and script errors. However, the WTE administration tool lets you change the configuration so that the Web telephony service displays images and browser messages while running in a window. This is useful if you want to add error messages to help you debug scripts that execute only under the Web telephony service.

To see images and browser messages

  1. Click Start, click Programs, click Microsoft Web Telephony Engine, and then click Web Telephony Engine Administration Tool.
  2. Open the following node:
    Console Root\Web Telephony Engine\<array name>\Applications
  3. In the right pane, right-click the name of the application and select Properties from the pop-up menu.
  4. In the Properties menu, click the Advanced tab, and then click the Browser Download button. To see application images, uncheck the following check box in the Browser Download dialog box:
    Download Web page but do not display it.

    and check the following check box:

    Download images from the server.

    To see browser messages, uncheck the following check box:

    Do not display user interface.


Setting the Configuration Parameters of an Application

WTE maintains an extensive set of configuration parameters for each installed application. System administrators can view and change the configuration parameters through the administration UI provided by the WTE administration tool. For more information, see the documentation for the WTE administration tool.


Using the Web Telephony Engine COM Objects for Configuration and Administration

The application configuration parameters are also exposed to COM applications through the WTE object model (OM). The OM allows you to create applications that administer and configure Web telephony applications programmatically. For example, you can use these objects in your setup program for a specific application to ensure that settings cannot be changed by an administrator, or to override the WTE default settings. You can also write stand-alone utility programs that work with any number of Web telephony applications, even when the applications reside on different computers. Every application configuration parameter accessible through the WTE administration tool is also exposed through the WTE COM objects.

The WTE objects are also accessible within Web telephony applications. An application can include scripts that call WTE objects to set configuration parameters at run time. However, note that configuration parameters modified within an application affect only the current instance of the application and are not saved when the instance is closed. By contrast, changes made through a setup program or administration utility affect the way all instances start running and may be saved between instances.

For more information about setting configuration parameters within an application, see Web Telephony Configuration Object.

For more information on using the WTE object model to administer Web telephony applications see Programming Administration and Configuration Tasks.


Troubleshooting

This section provides information to help solve problems you may encounter while using the Web telephony service.

If the Web telephony service doesn't answer calls, the service may not be started. To confirm that the service is started:

Using the Windows 2000 Task Manager application (accessible by pressing CTRL+ALT+ DEL), check for the process MSWTESRV.exe under the Processes tab. If you cannot find it, the Web telephony service did not start.

To determine the problem:

  • Check the Event Viewer for Web telephony events and errors in the Application Log section.

If the Web telephony service is listed under the Processes tab of Task Manager but still does not answer calls, make sure you have a TSP installed and properly configured:

  • To verify proper installation and configuration, try running other TAPI applications that also use audio to verify that the telephony configuration is correct.
  • Make sure that your machine can answer calls, play voice output over the line, and detect Dual Tone Multi-Frequency (DTMF) signaling.

If the Web telephony service disconnects after answering calls, check the following:

  • The voice board's audio driver may not be properly installed. Try to play a wave file to the device using another TAPI application.
  • WTE could not find the voice file that it was directed to play. Look in the log file for errors of this type.
  • WTE attempted to navigate to an undefined destination. Check your Web site for inaccurate references by using Internet Explorer or one of the many tools available for checking the integrity of references.
  • Check the Web telephony log file. WTE logs many types of events into a file or SQL database. Examples of events include new calls, navigation operations, authoring errors, and so on. The default configuration contains a log file name under the <target directory>\Log. The name of the log file is taken from the configuration.
  • Depending on which events occurred while WTE was running, another log, called the developer log, may have been created. For more information on this log file and its contents, see The Developer Log.

If the application stops responding to DTMF digits, first check to make sure your HTML pages do not cause Internet Explorer to display a message box. All message boxes appear on the computer monitor screen. For more information, see Message Box Management.

One way to find and resolve problems that occur in a WTE application is to run the WTE service in window mode. While in window mode, the WTE service displays the currently loaded HTML page in a window on the host computer. This allows you to see your application as it runs. For more information, see Running the Web Telephony Service in Window Mode.

If you are having a problem that you cannot solve, check Known Issues and Limitations. If the problem is not a known issue, do the following:

  • Prepare an e-mail message.
  • Attach the log file, the exported file from your registry (HKEY_LOCAL_MACHINE\Software\Microsoft\Web Telephony Engine), and the Web telephony-related events from Event Viewer.
  • Send to Web Telephony Engine Customer Feedback.


Authoring a Web Telephony Application

This section provides the information that an author needs to create a Microsoft® Web telephony application. For information about specific topics, see:

  • About Web Telephony Applications
  • Extended Object Model Overview
  • Handling a Call
  • Speaking to the Caller
  • Playing Background Music
  • Getting Input from the Caller
  • Getting Spoken Input from the Caller
  • Using Menus
  • Controlling Navigation
  • Using HTML Elements
  • Handling Events
  • Using Other Web Technologies


About Web Telephony Applications

This topic provides an overview of Web telephony applications, describes the programming model, and details issues that you need to consider when developing an application. For information about specific topics, see the following sections:

  • What is a Web Telephony Application?
  • The Web Telephony Programming Model
  • Programming Considerations


What is a Web Telephony Application

Platform SDK: Web Telephony Engine

What is a Web Telephony Application?

To telephone callers, a Web telephony application is a voice that answers the telephone and guides them through a hierarchy of menus to complete a task or obtain information. A typical application begins by greeting the caller, presenting a list of items, and directing the caller to select an item. The caller responds by pressing the telephone key that corresponds to the desired item or, optionally, by speaking the selection. This process continues until the caller's needs are met or the caller hangs up.

To a developer, a Web telephony application is a Web site designed to be rendered by the Microsoft Web Telephony Engine (WTE). In most respects, a Web telephony application resembles a "regular" Web site because each consists of a set of HTML pages that use scripting and other Web technologies to provide content to the user. The main difference is that a Web telephony application uses HTML extensions, Telephony Application Programming Interface (TAPI), and extensions to the Internet Explorer Object Model to create a Web site that can be rendered to a caller over a telephone line.

Although a Web telephony application is designed to be accessed by telephone, it is also possible to access any Web telephony application through a graphical Web browser. However, making the same application work well in both media requires additional effort, such as hiding parts of the application's HTML from one medium or the other. A Web telephony application designed to also work well while being accessed through a graphical Web browser is called a dual-access application. For more information, see Dual-access Considerations.

The WTE maintains a list of applications that it can run. An application must be added to the list before the engine can run the application. Adding an application allows the engine to associate the application with a particular telephony service provider (TSP) line attached to the computer. When a call comes on a given line, the WTE starts the application associated with that line. An application can be added to the list either by using the WTE administration tool, or by a third-party setup program or administration application.

All applications must have a home page and, optionally, can have a post-call page. The home page is the first HTML page to which the engine navigates when a call comes on the line with which the application is associated. Authors can use the home page to initialize application variables or perform telephony operations. For example, an application might check the caller ID of the incoming call to decide whether to answer the call, transfer it to another extension, and so on.

The post-call page is an HTML page to which the WTE navigates after the call has ended. It is typically the last page in an application, and allows the application to process data collected from the caller during the course of the call.


The Web Telephony Programming Model

The programming model for creating a Web telephony application is similar in many respects to building a regular Web site. You use your favorite Web authoring tools to create a set of Web pages containing HTML elements, scripts, Microsoft ActiveX® controls, Java applets, and so on. The main difference is that in a Web telephony application you use additional HTML attributes, cascading style sheet (CSS) styles, scripting events, and Internet Explorer objects that are currently supported only by the WTE. In addition, a Web telephony application uses TAPI to perform telephony operations, and can query and set configuration parameters of the text-to-speech (TTS) and speech-recognition (SR) engines. For information on specific topics, see:

  • HTML Extensions
  • Extended Object Model
  • TAPI 3.0
  • Speech Objects


HTML Extensions

You use standard HTML elements to create a Web telephony application. In addition, the WTE supports five additional items that are not currently part of the HTML standard:

  • VOICEFILE attribute. For more information, see Speaking to the Caller.
  • GRAMMAR attribute. For more information, see Using the GRAMMAR Attribute.
  • onselectiontimeout event. For more information, see Handling Time-outs and Non-valid Keys.
  • onselectionerror event. For more information, see Handling Time-outs and Non-valid Keys.
  • cut-through CSS property. For more information, see Receiving a Selection from the Caller.

Microsoft is working with the World Wide Web Consortium (W3C) to add these extensions to the next version of HTML in order to support aural browsers such as the WTE. These extensions are described in subsequent sections of this documentation.


Extended Object Model

The WTE uses the same component object model (COM) used by Microsoft Internet Explorer. In fact, the engine is essentially Internet Explorer without the graphical user interface (GUI). This means that all the Internet Explorer scripting objects available to regular Web sites are also available to Web telephony applications. Also, the WTE extends the Internet Explorer object model with additional objects that support Web telephony applications. The extensions are referred to as the Web telephony extended object model.

Applications have access to the extended object model through the ExOM object. The engine includes a predefined reference to the ExOM object called External, which applications can use to access the object directly. The External object provides access to the following objects:

  • WTEApplication object — Lets an application query and change its own configuration parameters. An application accesses its configuration parameters by using the Configuration property on the External object. For more information, see Web Telephony Configuration Object.
  • Session object — Lets an application store strings, numbers, and objects that it needs to use before answering a call, during the call, and after the call is disconnected. Variables stored by using the Session object are available to all pages for the duration of the session.
  • Internet Explorer Event object — Lets an application access the WTE private event object, which is similar to the Event object of Internet Explorer. For more information, see Handling Events.
  • TAPI Call object — Lets an application perform telephony operations through a telephony service provider such as a voice board or voice modem.
  • TTSMode object — Lets an application query the read-only properties of the TTS engine.
  • SRMode object — Lets an application query the read-only properties of the SR engine.
  • LogCustomField object — Lets an application set the contents of the custom field in the Web telephony event log.

For more information, see Extended Object Model Overview.


TAPI 3.0

The WTE uses a telephony service provider (TSP) to access the telephone system. Typical TSPs include voice boards, voice modems, and the IP device integral to the Windows 2000 operating system. The engine communicates with the TSP by using Microsoft TAPI 3.0. This means that the engine can use any telephony service provider that supports TAPI.

The engine exposes the TSP's functionality to a Web telephony application through the ITBasicCallControl object exposed through the TAPI 3.0 Call object. An application can use the ITBasicCallControl object to direct the TSP to perform any supported telephony operation. An application has access to the ITBasicCallControl object through the Web telephony extended object model.

The WTE does not include a programming interface for communicating with the public branch exchange (PBX). If your PBX supports TAPI 3.0, your WTE application can communicate with the PBX by using the TAPI 3.0 Call object. Otherwise, your application must use the programming interface supported by your PBX.


Speech Objects

The WTE uses a TTS engine to render HTML content to a telephone caller and, optionally, an SR engine to gather spoken input from the caller. To communicate with a TTS or SR engine, the WTE uses the Microsoft Speech Application Programming Interface (SAPI) 4.0a. For this reason, any SAPI-compliant TTS or SR engine can be used. The WTE can use the Microsoft TTS Engine included with Windows 2000, and the Microsoft SR Engine, if it is installed on the computer. The Microsoft SR Engine must be installed from the SAPI 4.0a Software Developer's Kit (SDK)—it is not installed by default. For more information about SAPI, see the MSDN library.

The mode information maintained by the TTS and SR engines is exposed to a Web telephony application through the TTSMode and SRMode objects of the extended object model. These objects provide read-only access. In addition, the WTEApplication object provides read-write access to several speech-related configuration parameters for an application.


Programming Considerations

This section outlines general issues that you need to keep in mind while developing a Web telephony application. For information about specific topics, see the following sections:

  • Dual-access Considerations
  • Message Box Management
  • Caching Issues
  • Web Telephony Sessions
  • Monitoring Mechanism


Dual-access Considerations

You can develop a Web site that is accessible by telephone and through a Web browser. When developing a dual-access Web site, you need to be aware of the differences between the way that the WTE renders your Web pages, and the way a browser renders them.

For information about specific topics, see the following sections:

  • How the Web Telephony Engine Renders a Web Page
  • Determining whether the Phone or Browser is Being Used
  • Using the CSS Display Property
  • Error Messages


How the Web Telephony Engine Renders a Web Page

The Web Telephony Engine (WTE) renders the content of an application's HTML pages from top to bottom. Any HTML elements that a graphical Web browser would render as text are read to the telephone caller by the engine using TTS (if the WTEApplication.RenderTTS property is TRUE). If an element has a wave file associated with it, the WTE plays the wave file and ignores any text associated with the element (see Using Wave Files). The WTE also ignores any graphics in an application's HTML pages.

When the WTE reaches an element that requires a response from the caller, such as a menu or a data-entry field, the engine stops rendering and waits for the caller to respond. Time-out values determine the length of time that the engine will wait for the caller's response. The engine continues rendering the application after the caller responds, navigating to the application's error-handling page if the caller commits too many time-out or data-entry errors. For more information about handling errors, see Handling Time-outs and Non-valid Keys.


Determining Whether the Phone or Browser is Being Used

In a dual-access application, you often need to determine, at run time, whether an application's pages are being rendered by the WTE or by a graphical browser. For example, before attempting to perform telephony operations, you would need to be sure your application is being rendered by the WTE.

You can use the hostName property of the External (ExOM) object in your scripts and Microsoft ActiveX® controls to determine which component is running your application. When an application is running under the WTE, the hostName property is "Microsoft Web Telephony Engine"; otherwise, it is null.

The following example shows how to use the hostName property in a script to set up conditional sections of code:

<html>
<body>
<script>
// hostname is not implemented in graphical browsers, so
//   start with this check
var IsMSWTE = (typeof(window.external.hostName)=="string")

if (IsMSWTE == true)
{
  IsMSWTE = (window.external.hostName == "Microsoft Web Telephony Engine");
}

if (IsMSWTE == true)
{
  // Put Web telephony-specific code here
}

else
{
  // Put browser-specific code here
}
</script>


Using the CSS Display Property

The CSS display property controls how an element appears when it is displayed. The 'none' value of the display property is especially useful in dual-access WTE applications because it allows you to mark HTML elements as telephony-only or browser-only. For example, the following embedded CSS creates a paragraph element that a graphical Web browser will render, but that the WTE will not render.

<style type="text/css" media=aural>
P.GraphicalOnly {display : none}
</style>

The paragraph element in the following embedded style will be rendered by the WTE but not a graphical Web browser:

<style type="text/css" media=screen>
P.TelephonyOnly {display : none}
</style>


Error Messages

A Web site author typically uses message boxes to notify users of a graphical Web browser that an error has occurred. Under the WTE, message boxes are not rendered to the caller, yet the call might be blocked (for more information, see Message Box Management). For this reason, an application must not use message boxes when running under the WTE. Instead, use wave files or TTS to communicate error messages to the caller.

Internet Information Services (IIS) servers and proxy servers maintain a default error page that they return when they cannot fulfill a client's request. For example, IIS and proxy servers return the default error page when a Web browser tries to navigate to a page or server that does not exist.

An administrator should ensure that the default error pages are authored so that the WTE can render them, possibly by adding the VOICEFILE attribute to appropriate HTML elements. That way, if the caller selects a key that has a broken link, the engine will play a friendly error message. For example, "We are sorry, the page you want is currently unavailable. Please call again later." Because Internet connections can fail, it is especially important to have friendly default error pages on a proxy server offering access to applications through the Internet.


Message Box Management

When the WTE is running as a service (rather than running in a window), the WTE captures most message boxes and clicks the default button. This is because a WTE application has no user interface (UI) while the WTE is running as a service. Capturing message boxes and clicking the default button helps prevent unexpected message boxes from blocking a WTE application. These unexpected message boxes include those that originate in the operating system or in some other component, such as an ODBC component.

As a WTE application author, you must carefully design and preview your application's pages to prevent any undesired effects that may occur when the WTE clicks the default button in a message box.

The WTE service captures only those pop-up windows and message boxes that are displayed by the Win32® MessageBox and MessageBoxIndirect functions. These functions are typically called under the following circumstances:

  • Calling the Microsoft Visual Basic® or Visual Basic Scripting Edition (VBScript) MsgBox function.
  • Calling the assert, MessageBox or MessageBoxIndirect function from a C/C++ implementation of an ActiveX object.

Note that the WTE service cannot capture the message box displayed by the window.close method. For this reason, a WTE application should not call window.close while the application is running under the WTE service.

The WTE displays message boxes and pop-up windows stemming from an application's HTML code only when the WTE is running the application in a window. Each application window shows the message boxes and pop-up windows created by the currently loaded HTML page. The application remains blocked until the user dismisses the message box by clicking one of its buttons. Running your WTE application in a window is a convenient way to preview the application. For more information, see Running the Web Telephony Service in Window Mode.


Caching Issues

The WTE gets its Web-browsing capabilities from a component called the Web-browser control, which is the same component used by Microsoft Internet Explorer. Because they both use the Web-browser control, the WTE and Internet Explorer share many characteristics. One common characteristic is the caching behavior. Understanding how the Web-browser control performs caching is important because caching can prevent callers from accessing recently updated files in your application.

As a caller browses your application's Web site, the Web-browser control stores (caches) a copy of each accessed HTML file in the Temporary Internet Files folder (the cache) on the local disk. Whenever the control needs to access a file, it first looks in the cache. If it doesn't find the file in the cache, the control retrieves it from the Web server.

Outdated Cached HTML Files

Caching becomes an issue when you update files on your applications Web site. If you edit or replace an HTML file, the Web-browser control will not use the updated or new file if the cache contains a file with the same name. The control continues to use its cached file and never checks for a newer version.

Caching is not an issue when your application uses the File protocol to access a file (for example, File://\\MyWTEdir\start.HTM). In this case, the Web-browser control always gets the file from the local disk or network share. Because it does not cache files that are on the local disk or network share, the control always gets the newest version.

There are several ways you can ensure that the Web-browser control uses the latest versions of your application's files:

  • Manually delete old versions of files from the cache.
  • Author your application on your local disk if you don't need ASP pages. If you do need ASP pages, you can write an ASP expression on the first line of the file to prevent caching. For example:
    <% response.expires = 0 %>
  • Use Internet Explorer to change the caching behavior of the Web-browser control. If you choose this option, keep in mind that you must change the caching behavior while you are logged on to the same account as the WTE or the changes will not affect your application. Also note that changing caching behavior through Internet Explorer alters the behavior for all subsequent Internet Explorer sessions on that account.

To change the caching behavior

  1. Log on to the user account under which the Web telephony service is running.
  2. Open an instance of Internet Explorer on the computer where the WTE is installed. From the Tools menu, select Internet Options.
  3. From the General tab on the Internet Options property sheet, select Settings in the Temporary Internet Files dialog box.
  4. From the Settings dialog box, under Check for newer versions of stored pages, choose one of the following:
    • Every visit to the page—The Web-browser control checks for the latest version with each page reference. It does this by checking the time on the file in the IIS server. If the file has not been changed, it will not be brought in again. This means that if the file was replaced by a file that had an earlier time stamp than the first one, the replacement file will not be brought in.
    • Every time you start Internet Explorer—The Web-browser control checks for new pages only after the Web telephony service has been restarted.

For a complete description of the caching options, see the Internet Explorer help file.

Outdated Cached Wave Files

The Web-browser control caches wave files in the same way that it caches HTML pages. The setting under Check for newer versions of stored pages in Internet Explorer also affects wave files. If the setting is Every visit to the page, the WTE checks for a newer version of a file on every reference to it. If the setting is Every time you start Internet Explorer or Automatically, the engine checks for a newer version only after the Web telephony service is restarted.


Web Telephony Sessions

A key difference between the WTE and graphical Web browsers is the concept of a session. The WTE supports sessions; graphical Web browsers do not.

In Web telephony, a session begins when TAPI offers a call to the WTE before the call is even answered. A session ends when an application calls the External.Abandon method, which typically occurs some time after the call has been disconnected.

The WTE creates a new instance of the Session object at the beginning of each session, and destroys the object when the session ends. The Session object is always available to the application, providing a convenient place for storing client-side variables and objects the application may need throughout the session. These objects can be TAPI objects, MAPI objects, or any others that run on the client side. You can also use the Session object to keep track of the call, the HTML pages that the caller has visited, variables that the application changed at run time, and so on. For more information, see The Session Object.


Monitoring Mechanism

WTE implements a monitoring mechanism, which supervises how WTE applications use memory, and ensures that memory and handles are released. WTE applications can include components (such as ActiveX), which may allocate but not release memory or other operating system resources.

Here's how it works. When WTE is invoked, a call handling mechanism starts up, and registers with TAPI to receive call notifications on specified addresses. The call handling mechanism answers these calls and manages interaction with the caller until the call (and its session) is ended.

Meanwhile, the monitoring mechanism monitors the call handling mechanism, checking for memory consumption and handle allocation. When the monitoring mechanism determines that the call mechanism is using too much memory or too many handles, it creates a new call handling mechanism and notifies the old call handling mechanism. The old call handling mechanism finishes handling current calls, and then release its system resources and exits. This switching mechanism, between two call handling mechanisms, repeats itself as long as the WTE service is running.

Each time the call handling mechanism switches instances, a Line Opened event is logged to the event log for each address associated with the application.

The call handling mechanism is switched in the following conditions:

  • The process uses more than a specified number of handles.
  • The process uses more than a specified amount of memory ("Private bytes").
  • The process cannot answer any more calls.

Note that since WTE switches the engine based on the total amount of memory and handles consumed by the acting process, applications that are supposed to use a lot of memory may cause an unintended engine switch.

Impact of Monitoring Mechanism on ActiveX Components

WTE's monitoring mechanism may impact applications that use ActiveX components. If you wrote an ActiveX component that uses process-specific global storage in order to store information between calls, bear in mind that the ActiveX component may start and stop without administrator intervention. This doesn't happen in the middle of any call but may happen between calls.

Impact of Monitoring Mechanism on Dial-out Applications

If you have an application which processes a database of phone numbers, dials each of them, and hands off the call to WTE, be sure that the application hands off the call to any TAPI call waiting for notification on this address for voice media.


Extended Object Model Overview

The WTE provides an extension to the Internet Explorer Object Model called the extended object model (ExOM). The Web Telephony ExOM allows the application author to change the configuration parameters of an application dynamically, store and retrieve variables between pages, and access the current TAPI Call object. In addition, the author can use the ExOM to control the operation of the Web telephony session handling the call. The ExOM is accessible from VBScript, Microsoft JScript® or ActiveX controls. Note that any changes made through scripting affect only the current instance of an application.

An application accesses the ExOM by means of the ExOM object. The WTE includes a predefined reference to the ExOM object called External, which applications can use to access the object directly. For example, the following code retrieves the name of the current application:

AppName =  External.Configuration.Name

The ExOM is actually a collection of objects that are exposed to applications through properties on the External (ExOM) object. For a general overview of these objects, see the following topics:

  • Web Telephony Configuration Object
  • The Session Object
  • The TAPI Call Object
  • The WTE Event Object
  • The TTSMode Object
  • The SRMode Object
  • The LogCustomField Object

In addition to the preceding objects, the External object exposes the following properties and methods:

  • The AlternativePhrases Property
  • The hostName Property
  • The Log Method

The Objects section contains detailed descriptions of the objects, methods, and properties exposed by the WTE through the ExOM object.

To access the External objects and methods from a scriptlet, use the window.parent.External property. In addition, some External objects such as Session, Configuration, and ITBasicCallControl can be passed into a scriptlet as parameters of public methods. Within the scriptlets, the External object behaves according to the Internet Explorer Object Model (OM) specification.


Web Telephony Configuration Object

The WTE maintains a large set of configuration parameters for an application, and exposes the parameters through the WTEApplication object. This object is intended for third-party vendors to create programs that install and configure Web telephony applications. In addition, authors of Web telephony applications can use this object to change an application's configuration parameters dynamically at run time.

Retrieving the WTEApplication Object

There are two ways to retrieve the WTEApplication object. First, third-party installation and configuration programs can use the COM interfaces exposed for administrative purposes through the WTE object. Changing the configuration through this object changes the stored configuration parameters of the given Web telephony application (after the program calls the Save method). For more information, see The Web Telephony Object Model.

The second way to retrieve the WTEApplication object is to use the Configuration property of the External object. For example, an application can use the following code in a script to retrieve the WTEApplication object for the active call:

set conf = window.external.configuration

An application can use the WTEApplication object to query and change its parameters dynamically through the ExOM. The changes affect only the active call and last only the duration of the session.

Saving and Restoring Configuration Parameters

When an application dynamically changes a configuration parameter, the change affects all pages that the caller subsequently visits. If you want a change to affect only a particular page, you must save the parameter's old setting as the page is loaded, change the setting, and then restore the old setting when the page is unloaded. Typically, an application saves and changes a parameter by using an immediate script, and restores the parameter's old setting by using a handler for the onunload event on the BODY element.

The following example shows an immediate script that saves and changes the settings of the OfferItems, UserSR, and FirstTimeoutInterval properties:

<SCRIPT LANGUAGE="JSCRIPT">
    var CallConfiguration;
    var PreviousOfferItems, PreviousUseSR, PreviousTimeOut;

    var IsMSWTE = (typeof(window.external.hostName) == "string")
    if( IsMSWTE == true)
    {
    IsMSWTE = (window.external.hostName ==
        "Microsoft Web Telephony Engine");
    }

    if( IsMSWTE == true)
    {
        CallConfiguration=window.External.Configuration;
        PreviousOfferItems = CallConfiguration.OfferItems;
        CallConfiguration.OfferItems = false;
        PreviousUseSR = CallConfiguration.UseSR;
        CallConfiguration.UseSR = true;
        PreviousTimeOut = CallConfiguration.FirstTimeoutInterval;
        CallConfiguration.FirstTimeoutInterval = 30;
    }
</SCRIPT>

The following example shows an onunload event handler that restores the parameter settings that were changed in the previous example:

<BODY onunload="CancelPageSettings();">

<SCRIPT LANGUAGE="JSCRIPT">
    function CancelPageSettings()
    {
    var IsMSWTE = (typeof(window.external.hostName) == "string")
    if( IsMSWTE == true)
    {
    IsMSWTE = (window.external.hostName ==
        "Microsoft Web Telephony Engine");
    }

    if( IsMSWTE == true)
        {
            CallConfiguration.OfferItems = PreviousOfferItems;
            CallConfiguration.UseSR = PreviousUseSR;
            CallConfiguration.FirstTimeoutInterval =  PreviousTimeOut;
        }
    }
</SCRIPT>
 <!-- put page content here. -->

</BODY>

Properties of the WTEApplication Object

The properties of the WTEApplication object provide access to several configuration parameters. For example, one group of properties defines the phone keys that the caller uses to navigate and interact with the application. Another group determines the text or wave files that the WTE plays when the caller presses a non-valid key or waits too long before responding. The following sections briefly describe the properties of the WTEApplication object (for more detailed information, see Objects in the WTE Reference section):

  • Key-Assignment Properties
  • Text and Wave-File Properties
  • Input-Control Properties
  • Speech Recognition and Text-to-Speech Properties
  • Information Properties
  • Other Properties


Key-Assignment Properties

The WTE includes built-in functionality that the caller can access by pressing keys on the telephone. This functionality includes operations that allow the caller to navigate backward, transfer a call to the operator, confirm or deny a selection, and so on. The key-assignment properties of the WTEApplication object allow an application to assign its own phone keys to these common key-based operations.

For example, in most applications, the "0" key transfers the call to the operator. However, suppose your application contains an input field in which the caller enters a credit card number. Because the number may contain a zero, you would need to change the operator key to "#" before the input field, as the following example shows:

OldChar = External.Configuration.OperatorKey
External.Configuration.OperatorKey = "#"

... <!-- code for entry field -->

External.Configuration.OperatorKey = OldChar

The following table lists and describes the key-assignment properties.

Property | Description
BackKey | The key used to navigate backward.
HomeKey | The key used to navigate to the home page.
SelectCheckBoxKey | The key used to select a check box in the HTML page.
ClearCheckBoxKey | The key used to clear a check box in the HTML page.
ClickButtonKey | The key used to click a button in the HTML page.
SkipButtonKey | The key used to skip a button in the HTML page.
RepeatMenuKey | The key used to specify that the caller did not say any of the phrases recognized by the SR engine.
OperatorKey | The key used to transfer the call to the operator.
OperatorExtension | Operator extension to use when the caller presses the key specified in the OperatorKey property.
OperatorTransferType | Transfer type when transferring to the operator extension. It can be a blind or supervised transfer.


Text and Wave-File Properties

The WTE automatically plays text or wave files in certain situations or in response to certain actions on the part of the caller. For example, text or a wave file plays while navigating, when a time-out has expired, when the caller presses a non-valid key, and so on. The text and wave-file properties of the WTEApplication object allow an application to query and change the text or wave files that Web telephony plays in these situations. The following table lists and describes the text and wave-file properties.

Property | Description
SelectCheckBoxPhrases | Phrases to say for 'select check box'.
ClearCheckBoxPhrases | Phrases to say for 'clear check box'.
ClickButtonPhrases | Phrases to say for 'click button'.
SkipButtonPhrases | Phrases to say for 'skip button'.
InvalidKeyAnnouncement | Wave file or text to play when the user presses a non-valid key.
ConfirmBefore | Phrase to play before an SR confirmation request.
ConfirmAfter | Phrase to play after an SR confirmation request.
ConfirmationMenuAnnouncement | Phrase to play after the caller has selected a menu item by using SR.
RepeatMenuAnnouncement | Wave file or text to play at the end of the confirmation menu.
NavigationAnnouncement | Wave file or text to play while navigating.
TimeoutAnnouncement | Wave file or text to play when a time-out has expired.
ShutdownAnnouncement | Wave file or text to play when the service shuts down.


Input-Control Properties

Web telephony maintains a set of parameters that control how the application behaves while collecting input from the caller. These parameters determine the length of time that the application waits for the caller to respond, the page to navigate to when the caller makes too many mistakes, the string that signals the end of the caller's input, and so forth. A Web telephony application can use the input-control properties of the WTEApplication object to change the way the application behaves while collecting caller input. The following table lists and describes the input-control properties.

Property | Description
FirstTimeoutInterval | Interval of time available for a caller to enter a choice after listening to the announcements of menus or controls.
InterTimeoutInterval | Interval of time between consecutive digits of multiple-digit access keys, and between consecutive digits of input for a text control or a text area. In all other cases, the time-out interval is defined by the FirstTimeoutInterval property.
InputTerminator | Termination string for caller input into a text-entry field, a text area, or multiple-selection menu. This string also designates the end of a record operation.
MaxRetries | Number of times the WTE performs default error-handling actions because of a caller's mistakes before dropping the call or navigating to the page specified by the RecurringErrorPage property. Mistakes include pressing a non-valid key or the occurrence of a time-out.
RecurringErrorPage | Page that the WTE renders when the number of consecutive caller errors exceeds the value of the MaxRetries property.
IgnoreNavigationKeysTillTermination | Flag that determines whether Web telephony ignores all navigation keys (those defined by the BackKey, OperatorKey, and HomeKey properties) while receiving caller input for a text control or text area.
InputWaveFormat | Wave format of recorded files, or wave format to be used for SR.
RecordStopSilenceTime | Duration of silence after which recording stops.
MaxRecordTime | Maximum duration of a recorded message.
DetectABCD | Flag indicating whether to detect the A, B, C, and D keys as Dual Tone Multi-Frequency (DTMF) signals (for European countries).


Speech Recognition and Text-to-Speech Properties

An application can use the WTEApplication object to query and change speech-recognition (SR) and text-to-speech (TTS) properties for the application. The following table lists and describes the SR and TTS properties.

Property | Description
UseSR | Flag indicating whether Web telephony uses SR in this application. This means that text-input controls are used for dictation, and menus can be activated with phrases.
SRThreshold | Threshold of certainty at which speech is recognized.
SRParameters | String that encapsulates the SRMODEINFO and SRMODEINFORANK structures. For more information, see the MSDN library.
SuggestConfirmation | Flag indicating whether the WTE plays a confirmation menu after the caller selects a menu item by means of SR.
RenderTTS | Flag indicating whether the WTE plays HTML text using a TTS engine.
TTSParameters | String that encapsulates the TTSMODEINFO and TTSMODEINFORANK structures. For more information, see the MSDN library.
TTSWaveFormat | Wave format that the TTS engine should use to speak text to the caller.


Information Properties

The information properties of the WTEApplication object provide access to information about an application. The information includes the name and description of the application, and the name of the vendor that created the application. Additional vendor-supplied information is available through the WTEVendorDataSets object. An application can retrieve a reference to this object by using the VendorDataSets property. The following table lists and describes the information properties.

Property | Description
Name | Name of the application.
Description | Description of the application.
Vendor | Name of the application vendor.
VendorDataSets | Reference to a WTEVendorDataSets object for storing and loading of custom data.


Other Properties

The WTEApplication object includes a number of miscellaneous properties for setting configuration parameters of the WTE application. The following table lists and describes these properties.

Property | Description
HomePage | URL of the first page of the application.
PostCallPage | URL of the page used to execute scripts after a call is disconnected.
DelayedAnswering | Flag indicating whether to start the session without answering the telephony call.
DownloadControlFlags | Group of flags that control the download mode of the browser (Internet Explorer).
EnableFullConfiguration | Flag indicating whether the WTE administration tool displays all application property pages or just the General and the Addresses pages.
InitialAutoNumber | Initial access-key value assigned by the "Autonumbering algorithm."
LogEventSelection | Group of flags that specify the types of events to log.
OfferItems | Flag indicating whether audio items inside a menu will be gathered.
RenderTablesAsTabularData | Flag indicating whether a table in the HTML page is rendered as a table or as regular text.
ShutdownTime | Amount of time, in seconds, that elapses between a shut-down announcement and the actual termination of the session.


The Session Object

A session is the period during which the WTE handles a call. A session begins when TAPI offers a call to the WTE, and the engine responds by creating a Session object. A session ends, and the Session object is destroyed, when the application calls the Session.Abandon method. At that point, all resources allocated for the call are destroyed.

A Web telephony application retrieves a reference to the session object by using the Session property of the ExOM object. An application uses the Session object to store and retrieve strings, numbers, and objects that it may need throughout the session. An application stores and retrieves items by using the Value property, specifying a name and value pair, as follows:

   External.Session ("UserName") = "Mr. Smith"

   UserName = External.Session ("UserName")

In case of objects, the application must use the Set statement to retrieve the object, or call the object's methods directly. For example:

   Set MySession = External.Session

   Set MyMapiSession ("MapiSession") = CreateObject ("mapi.session")

   Set MyMapiSession = External.Session ("MapiSession")

   External.Session ("MapiSession").Logon

The Session object includes a number of useful read-only properties. An application can use the LastVisitedTagID and LastVisitedPage properties to keep track of the pages that the caller visited. The SessionName and SessionState parameters identify the session and provide the status of the call. The ServerName property identifies the computer on which the WTE is running.


The TAPI Call Object

The WTE uses TAPI 3.0 to communicate with the telephony service provider (TSP) installed on the computer. Typical TSPs include voice boards, voice modems, and the IP device integral to the Windows 2000 operating system. All TAPI functionality is exposed to a Web telephony application through the ITBasicCallControl object. An application retrieves a reference to the interface by using the ITBasicCallControl property of the ExOM object. For more information, see the TAPI version 3.0 documentation.


The WTE Event Object

The Event property of the ExOM object lets an application access the WTE private event object, which is similar to the Event object of Internet Explorer. The event object represents the state of an event, such as the element in which the event occurred.

The event object is available only during an event. That is, you can use it in event handlers but not in other code. Although all event properties are available to all event objects, some properties might not have meaningful values during some events.

For more information, see Handling Events. For more information about the Internet Explorer Event object, see the Web Workshop on the Microsoft Developer Network (MSDN) Web site.


The TTSMode Object

The TTSMode object provides access to the mode information of the selected TTS engine. All the fields of the TTSMODEINFO structure are accessible through read-only properties of the TTSMode object. An application uses the object to identify the currently selected TTS engine and learn its capabilities and current configuration parameters. For example, the configuration parameters set by the WTE administration tool could direct WTE to use an English TTS engine, and the application could use the TTSMode object to discover the engine that was selected by SAPI.

An application retrieves a reference to the TTSMode object by using the TTSMode property of the ExOM object. The following table lists and describes the properties of the TTSMode object.

Property | Description
Age | Flag indicating age of the voice.
Dialect | Retrieves name of the dialect specific to the language. For example, "Texas" or "New York City."
EngineFeatures | Flags that identify features specific to the TTS engine. These values are defined by the engine author.
EngineID | Globally unique identifier (GUID) for the TTS engine.
Features | Flags that identify the available TTS features.
Gender | Flag indicating gender of the voice.
Interfaces | Flags that identify interfaces that the TTS engine supports.
LanguageID | Win32® language identifier.
MfgName | Name of the TTS engine manufacturer.
ModeName | Name of the TTS mode.
ModeID | GUID that uniquely identifies TTS mode.
ProductName | Product name of the TTS engine.
Speaker | Name of the voice.
Style | Name of the personality of the voice. For example: "Business", "Casual", "Computer", "Excited", and "Singsong".


The SRMode Object

The SRMode object lets you access the mode information of the selected SR engine. All the fields of the SRMODEINFO structure are accessible through read-only properties of the SRMode object. An application uses the object to identify the SR engine and find out its capabilities and current configuration parameters. The application can use this information to determine whether the current SR engine meets its needs.

An application retrieves a reference to the SRMode object by using the SRMode property of the ExOM object. The following table lists and describes the properties of the SRMode object.

Property | Description
Dialect | Name of the dialect specific to the language. For example, "Texas" or "New York City."
EngineFeatures | Flags that identify the features specific to the engine. These values are defined by the engine author.
EngineID | GUID that uniquely identifies the SR engine.
Features | Flags that indicate the available SR features.
Grammars | Types of grammar the SR engine supports.
Interfaces | Flags that identify the interfaces the SR engine supports.
LanguageID | Win32 language identifier.
MaxWordsState | Maximum number of words in any state of a grammar.
MaxWordsVocab | Maximum number of words allowed in an active vocabulary at a given time.
MfgName | Name of the manufacturer of the SR engine.
ModeID | GUID that uniquely identifies the SR mode.
ModeName | Name of the SR mode.
ProductName | Product name of the SR engine.
Sequencing | Value that identifies the SR scheme.


The LogCustomField Object

The Web telephony service maintains a log where it records WTE-related events that occur while an application is running. Each entry in the log consists of a set of fields. One of the fields is called the custom log field.

The custom log field is empty at the start of each call. During a call, an application's scripts and ActiveX controls can write data to the custom log field by using the LogCustomField object.

For more information, see Using the Web Telephony Log. For information about how to use the custom log field, see Entering a Record into the Log.


The AlternativePhrases Property

The AlternativePhrases property of the ExOM object represents an array (possibly containing a single item) of the phrases returned by the SR engine. This is a read-only property. This property is valid only when invoked from the event handler for the onselectionerror event, when the event is fired before the SR confirmation menu is rendered. The AlternativePhrases property is not valid when the onselectionerror event is fired due to a selection error by the caller. An application can offer any specific confirmation menu based on the phrases contained inside this property, and disable the default confirmation menu by setting the returnValue property of External.Event to FALSE:

<script For=MenuOwner Event=OnSelectionError>
External.Event.returnValue = False
</script>.


The hostName Property

An application can use the hostName property within a script to find out whether the script is running under Web telephony. If it is, the property returns "Microsoft Web Telephony Engine".

For more information, see Determining Whether the Phone or Browser is Being Used.


The Log Method

Scripts and ActiveX controls can use the Log method of the ExOM object to submit log entries into the Web telephony log. For more information, see Entering a Record into the Log.


Handling a Call

This section describes how to handle incoming calls in an application, including how to answer, disconnect, and transfer calls. For information about specific topics, see the following topics:

  • Answering a Call
  • Disconnecting a Call
  • Transferring a Call
  • Retrieving Address Information
  • Retrieving the Called ID
  • Controlling Media Transport during a Call


Answering a Call

When a TAPI line device receives an incoming call, TAPI offers the call to the WTE. At this point, Web telephony creates a Session object, answers the call, and starts the application associated with the line being used for an incoming call. Web telephony starts an application by rendering the content of the application's HTML home page.

Having an Application Answer a Call

Alternatively, an administrator can configure Web telephony to leave call answering to an application by using the WTE administration tool. You can also do this programmatically by setting the WTEApplication.DelayedAnswering property to TRUE.

Allowing the application to answer calls gives the application a chance to perform lengthy pre-processing tasks before answering the call, or to check the caller ID (if provided) to determine whether to answer the call at all. Note that performing tasks before answering may cause the caller to hear an additional ringing sound while the task completes, but this is preferable to having one or two seconds of silence after the call is answered.

When an application is configured to answer calls, the WTE creates a Session object when TAPI offers a call to the engine, and then the engine navigates to the home page of the application. The home page must include an immediate script that answers the call, abandons it, or hands it off to another application. To answer or hand off the call, the application uses methods of the TAPI Call object, which can be obtained from the ITBasicCallControl property of the External object. To end the call, the application calls the Abandon method on the External object. In this case, no contact is established with the caller. The caller hears the phone ringing, followed by a dial tone when the call ends.

The following example shows how to write a script that either answers or abandons a call:

<SCRIPT Language=VBS>
' some code for determining whether to answer the call.

If WantToAnswer=1 Then
  Window.external.ITBasicCallControl.Answer

Else
  Window.external.Abandon

End If

</SCRIPT>

The WTE receives a notification from TAPI when the application answers the call. At that point, the engine begins rendering the application's HTML content.

Web telephony renders the application's HTML pages as the caller and the application interact. During the session, the WTE application can use the Session object to store objects and variables, keep track of the pages that the caller visited, retrieve status information, and so on. For more information, see Session Object.


Disconnecting a Call

After Web telephony or an application answers a call, the call continues until one of the following disconnection events occurs:

  • The caller hangs up the phone.
  • The caller navigates to an application page that causes the call to disconnect. The page either contains a script that calls the Disconnect method on the ITBasicCallControl object, or the engine reaches the end of the HTML content and there is nothing more for the engine to render.
  • The call is transferred either by a script that calls a method on the ITBasicCallControl object, or by the caller pressing the operator key.
  • An error occurs that causes Web telephony to disconnect. For example, the application tries to navigate to a file that does not exist.

Processing the Post-Call Page

When the call is disconnected for whatever reason, Web telephony navigates to the post-call page of the application. At this point, the phone line and other telephony resources allocated for the call are freed and made available for new incoming calls. However, the resources that Web telephony allocated for the application, including the Session object, remain available.

The WTE application should use its post-call page to perform any necessary post-call processing on the information gathered from the caller or stored in the Session object. For example, your post-call page can use the LastVisitedPage and LastVisitedTagID properties of the Session object to identify the last HTML page and element that the caller visited before the call was disconnected. You can use this information in a program that processes the post-call page according to the caller's location in the WTE application when the disconnection occurred.

An application should use its post-call page to perform any lengthy processing operations that would otherwise tie up the line or keep the caller waiting.

When no post-call page is specified, a default post-call page is rendered. This page calls the Abandon method and nothing more.

Abandoning the Session

When the post-call-page processing is finished, the application must call the Abandon method. Calling Abandon causes Web telephony to end the session, destroy the Session object, and free all other resources that it allocated for the call. The following example shows how to call the Abandon method:

<script language=vbscript>
external.abandon
</script>


Transferring a Call

You can use the TAPI ITBasicCallControl.BlindTransfer method in a script to transfer a call to another dialable address. Be aware that a call-transfer operation that is performed through a script may failwhile the engine is playing a wave file. To avoid a failure, write a call-transfer script using the following example as a guide:

<script language=vbscript>
sub stopstream
    DIM pCall
    DIM myDispMapper
    DIM pITStreamControl
    DIM pITStream

    Set pCall=external.itbasiccallcontrol
    Set myDispMapper = CreateObject("DispatchMapper.DispatchMapper.1")

    Set pITStreamControl = myDispMapper.QueryDispatchInterface(_
                  "{EE3BD604-3868-11D2-A045-00C04FB6809F}",pCall)

    For Each pITStream in pITStreamControl.Streams
        lMediaType = pITStream.MediaType

        if lMediaType = 8 Then
            pITStream.StopStream
        End If
    Next

    pCall.blindTransfer "1148"
end sub
</script>


Retrieving Address Information

This section describes how to retrieve the TAPI object and the TAPI Addresses collection from a WTE application.

The TAPI object is the application's entry point to TAPI 3.0. This object represents all telephony resources to which the local computer has access, allowing an application to enumerate all local and remote addresses.

The TAPI Addresses collection contains all of the currently available Address objects. Each Address object represents an entity that can make or receive calls. An application uses this object to get and set information concerning the address, such as whether it has caller ID support. Capabilities can be retrieved from an Address object, such as media and terminal support. An application can wait for a call on an Address object, or can create an outgoing call object from an Address object.

For more information about the TAPI object and Addresses collection, see Microsoft Telephony Overview.

To retrieve the TAPI object and Addresses collection

  1. Retrieve an instance of the DispatchMapper object.
  2. Use the DispatchMapper.QueryDispatchInterface method to retrieve an instance of the CallInfo object. When calling QueryDispatchInterface, you must specify the GUID of the CallInfo object and a reference to the ITBasicCallControl object.
  3. Use the CallInfo.Address property to retrieve an instance of the Address object.
  4. Use the Address.TAPIObject property to get an instance of the TAPI object.
  5. Use the TAPI.Addresses property to access the Addresses collection.

The following example shows how to use VBScript to get the TAPI object and TAPI Addresses collection:

IIDCallInfo = "{350F85D1-1227-11D3-83D4-00C04FB6809F}"
Set myDispMapper = CreateObject("DispatchMapper.DispatchMapper.1")
Set myBasicCallControl = window.external.ITBasicCallControl
Set myCallInfo = myDispMapper.QueryDispatchInterface(IIDCallInfo, myBasicCallControl)
Set myAddress = myCallInfo.Address
Set myTAPI = myAddress.TAPIObject
Set myAllAddresses = myTAPI.Addresses
For Each pITAddress in myAllAddresses
    stringOutput = "AdressName " & pITAddress.AddressName &
      "Dial. Addr " & pITAddress.DialableAddress
    MsgBox stringOutput
    window.external.LogCustomField.DefaultValue = stringOutput
    window.external.log()
    window.external.LogCustomField.DefaultValue = ""
Next

The following example shows how to use JScript to get the TAPI object and TAPI Addresses collection:

IIDCallInfo = "{350F85D1-1227-11D3-83D4-00C04FB6809F}";
IIDTapi = "{B1EFC382-9355-11d0-835C-00AA003CCABD}";
myDispMapper = new ActiveXObject("DispatchMapper.DispatchMapper.1");
myBasicCallControl = window.external.ITBasicCallControl;
myCallInfo = myDispMapper.QueryDispatchInterface(IIDCallInfo, myBasicCallControl);
myAddress = myCallInfo.Address;
myTAPI = myAddress.TAPIObject;
myAllAddresses = myTAPI.Addresses;
for(i = 1; i <= myAllAddresses.Count; i++) {
    pITAddress = myAllAddresses.Item(i);
    stringOutput = "AdressName " + pITAddress.AddressName +
      "Dial. Addr " + pITAddress.DialableAddress;
    window.external.LogCustomField.DefaultValue = stringOutput;
    window.external.log();
    window.external.LogCustomField.DefaultValue = "";
}

The scripting code in the previous examples is useful in the following scenario: Suppose an application receives a call that has come through a PBX to a voice board. Using a table, the application determines that the voice board received the call on port 3, and that the call came from extension 105 on the PBX. Using the code described in the previous examples, the application creates an object for the address number 105 on the PBX. The application also obtains the called ID of the current call and stores the ID in a global session variable.

At this point the application can perform several telephony operations. For example, a call center or T1-based application can use the PBX rather than the voice board to transfer the call to an agent, if necessary. After the call is disconnected, the application can use its post-call page to keep track of the call as it moves through the PBX from one agent to another.

The application calls the Abandon method only when the call finally leaves the PBX. For more information, see Disconnecting a Call.


Retrieving the Called ID

If your telephony system uses a PBX that supports Dialed Number Information Service (DNIS), your application can use TAPI to retrieve the called ID associated with the current call. The called ID identifies the called party, and is usually a telephone number.

The following JScript example shows how to retrieve the called ID:

IIDCallInfo = "{350F85D1-1227-11D3-83D4-00C04FB6809F}";
IIDTapi = "{B1EFC382-9355-11d0-835C-00AA003CCABD}";
myDispMapper = new ActiveXObject("DispatchMapper.DispatchMapper.1");
myBasicCallControl = window.external.ITBasicCallControl;
myCallInfo = myDispMapper.QueryDispatchInterface(IIDCallInfo, myBasicCallControl);
calledID = myCallInfo.CalledIDNumber;


Controlling Media Transport during a Call

A TAPI 3.0 device supports a component called the media service provider (MSP) that controls the media stream for the device. The MSP provides a programming interface consisting of a set of COM objects that applications can use to control media transport during a call. You can access these objects from a WTE application by using scripts. For more information about the MSP, see Microsoft Telephony Overview.

An MSP object that is particularly useful in a WTE application is the Stream object. An application can use this object to retrieve information about a media stream, to start, pause, or stop the stream, and to select or unselect terminals on a stream. A WTE application can retrieve a collection of all currently available Stream objects by following these steps:

To retrieve the Stream collection

  1. Retrieve an instance of the DispatchMapper object.
  2. Use the DispatchMapper.QueryDispatchInterface method to retrieve an instance of the StreamControl object supported by the MSP. When calling QueryDispatchInterface, you must specify the GUID of the StreamControl object and a reference to the ITBasicCallControl object.
  3. Use the StreamControl.Streams property to retrieve a collection of all media streams that are currently available.

The following example shows how to use VBScript to get the stream collection:

IIDStreamControl = "{EE3BD604-3868-11D2-A045-00C04FB6809F}"
Set myDispMapper = CreateObject("DispatchMapper.DispatchMapper.1")
Set myBasicCallControl = window.external.ITBasicCallControl
Set myStreamControl = myDispMapper.QueryDispatchInterface(IIDStreamControl,
  myBasicCallControl)
Set myAllStreams=myStreamControl.Streams
For Each pITStream in myAllStreams
    stringOutput = "Found Stream: " & pITStream.MediaType
    MsgBox stringOutput
    window.external.LogCustomField.DefaultValue = stringOutput
    window.external.log()
    window.external.LogCustomField.DefaultValue = ""
    pITStream.StopStream
Next

The following example shows how to use JScript to get the stream collection:

IIDStreamControl = "{EE3BD604-3868-11D2-A045-00C04FB6809F}";
myDispMapper = new ActiveXObject("DispatchMapper.DispatchMapper.1");
myBasicCallControl = window.external.ITBasicCallControl;
myStreamControl = yDispMapper.QueryDispatchInterface(IIDStreamControl,
  myBasicCallControl);
myAllStreams=myStreamControl.Streams;
for (i = 1; i <= myAllStreams.Count; i++) {
    pITStream = myAllStreams.Item(i);
    stringOutput = "Stream is "+ typeof(pITStream);
    window.external.LogCustomField.DefaultValue=stringOutput;
    window.external.log();
    window.external.LogCustomField.DefaultValue = "";
    stringOutput = "Found Stream: " + pITStream.MediaType;
    window.external.LogCustomField.DefaultValue = stringOutput;
    window.external.log();
    window.external.LogCustomField.DefaultValue = "";
}


Speaking to the Caller

A Web telephony application can use text-to-speech (TTS) or wave files to "speak" the text content of HTML pages to the caller. This section explains how to choose between TTS and wave files in a given situation. It also describes style properties that affect the way the TTS-rendered text sounds to the caller. For information about specific topics, see the following sections.

  • Choosing Text-to-Speech or Wave Files
  • Using Wave Files
  • Text-to-Speech Style Properties


Choosing Text-to-Speech or Wave Files

Speech generated by some TTS engines can sound a bit unnatural and may be difficult to understand—many people prefer the natural-sounding voice provided by a wave audio (.wav) file. For this reason, most applications use wave files whenever possible and minimize the use of TTS. Applications typically use TTS to render information that cannot be determined beforehand, such as account balances in an online banking application.

The WTEApplication object includes a configuration property called RenderTTS that enables or disables TTS for a Web telephony application. When disabled, your application cannot render any TTS over the telephone. Disabling TTS is useful if you use wave files throughout your application and have no need for TTS. Alternatively, you might want to use only TTS and not supply any wave files for the application. In this case, of course, you would enable the RenderTTS property.

You can change the setting of the RenderTTS property at any point in your application by using a script. You might start your application with a greeting recorded as a wave file, then enable TTS when your application needs to render the person's checking account balance.

The following example enables TTS by setting the RenderTTS property to TRUE:

window.external.configuration.RenderTTS=true


Using Wave Files

The WTE can use TTS to "speak" the text content of your application's HTML pages to the caller. Alternatively, you can use the VOICEFILE attribute to associate a wave file with individual HTML elements. When the WTE encounters such an element, it plays the wave file and ignores any text associated with the element. In a dual-access application, telephone callers would hear the wave file when the element is rendered, and users of graphical Web browsers would see the text.

The words recorded in the wave file don't need to match exactly the text displayed in the browser. For example, a Web page might include an anchor element containing the words "Driving Instruction" that provides a link to another topic. To the user of a graphical Web browser, "Driving Instruction" would appear underlined and in blue text, indicating a link that the user could click. A telephone caller, however, would need fuller instructions, such as "press two for driving instruction." To provide fuller instructions, you create a wave file that contains the instructions, and use the VOICEFILE attribute to associate the file with the anchor element. For example:

<A HREF="drive.html" VOICEFILE="drive.wav" ACCESSKEY=2>Driving Instruction</A>


Text-to-Speech Style Properties

The aural cascading style sheet (CSS) is part of the CSS2 standard defined by the World Wide Web Consortium (W3C). The WTE supports a number of properties specified in the aural CSS. The properties related to text to speech (TTS) include volume, speech rate, and pitch. The TTS engine uses these properties when rendering HTML text to a caller. You can set any of these properties in a style sheet or on a particular HTML element. The following example shows how to set CSS properties in a style sheet:

<STYLE>
    body {
        pitch:190;
        volume:medium;
        speech-rate:180;
    }
</STYLE>

This example shows how to set CSS properties on an HTML element:

<BODY STYLE="pitch:190; volume:medium; speech-rate:180;">

For more information about the aural CSS supported by the WTE, see CSS Properties. For more information about CSS, see the Web Workshop on the Microsoft Developer Network (MSDN) Web site.


Playing Background Music

An application may need to perform an operation, such as a database request, that can take several seconds or longer to complete. For lengthy operations that involve navigation, Web telephony can play background music or make regular announcements to let callers know that they haven't been forgotten. The NavigationAnnouncement property on the WTEApplication object provides this capability. The property specifies either a text string or wave file that Web telephony plays repeatedly until the navigation ends. You can set the NavigationAnnouncement property either programmatically or through the WTE administration tool.

Most lengthy operations involve some sort of navigation. For example, to perform a database request, an application typically uses an HTML page that contains a <FORM> element for gathering request data. The application then submits the data to an ASP page that performs the request and later returns with the answer. If the application's NavigationAnnouncement property is set, Web telephony starts playing the specified text string or wave file when navigating to the ASP page, and stops when the page returns with the requested item, ending the navigation.


Getting Input from the Caller

This section describes how to get input from the caller. For information about specific topics, see the following sections:

  • Types of Caller Input
  • Ways a Caller Enters Digits and Speech Input
  • Getting Text Input from the Caller
  • Handling Time-outs and Non-valid Keys
  • Ignoring Navigation Operations during Input
  • Terminating Input
  • Using European Telephones


Types of Caller Input

A caller can enter several types of input into a WTE application, including menu selections, text, and recorded messages.

Menus

A menu is a predefined list of items that an application presents to the caller. A menu can include items for navigation or information-gathering purposes. A navigation menu item is associated with another location in the application—either an HTML page or a particular location within an HTML page. When the caller selects the item, WTE navigates to the corresponding page or location. Following are examples of navigation menu items:

"To leave a message, press 1"
"To send a fax, press 2."
"To disconnect, press *."

Information-gathering menu items are associated with an actual piece of information. When the caller selects an item, the corresponding piece of information is entered into the application. Following are examples of information-gathering menu items:

"Please select your favorite beverage:"
"For soda, press 1."
"For coffee, press 2."
"For juice, press 3."

Implementing a menu in a WTE application involves using the A, BUTTON, or SELECT element, or the INPUT element of type BUTTON, RADIO, or CHECKBOX. It also involves using the cue, cue-before, cue-after, and cut-through CSS style properties. For more information about how to implement a menu, see Using Menus.

Text

Text consists of numbers and words that you gather from the caller by using entry fields in your application. You use entry fields to get pieces of information that cannot be included in a menu, such as the caller's credit card number, account number, and so on. Implementing entry fields involves using the TEXTAREA element or the TEXT type of INPUT element to create an entry field in your WTE application. For more information, see Getting Text Input from the Caller.

Recorded Messages

A recorded message is voice input from the caller that is stored in a wave audio file on the computer. For example, a call center application would use this form of input to take a message when the intended call recipient is not available. Recording a message from the caller involves using the TEXTAREA element or the TEXT type of INPUT element with the VOICEFILE attribute. For more information, see Recording a Spoken Message.


Ways a Caller Enters Digits and Speech Input

A caller enters input by pressing the DTMF keys on the telephone. The WTE receives the tones generated by each keystroke, translates them into the corresponding digits, and passes the digits to the application.

If a SAPI 4.0a SR engine is installed on the computer and enabled in the application, the caller can enter input by speaking as well as by pressing DTMF keys. When the caller speaks, the SR engine translates the speech into text and passes it to the application. For more information about SR, see Getting Spoken Input from the Caller.


Getting Text Input from the Caller

A WTE application gets text input from the caller by using entry fields. You should use entry fields to get pieces of information that you cannot get using a menu; that is, pieces of information that cannot feasibly be included in a list of menu items. For example, you would use entry fields to get the caller's account number, address, credit card number, and so on.

You create an entry field by using the TEXTAREA element or the INPUT element with the TYPE=text attribute. An entry field should be preceded by an introductory phrase, usually created by using the P element, that describes the type of data that the caller should enter. Also, entry fields are typically used inside a FORM element and are posted to and processed by an Active Server Pages (ASP) file or Common Gateway Interface (CGI) script. The following example shows an entry field that gets a seven-digit account number which is later posted to an ASP file called Customer.asp:

<FORM METHOD=post ACTION=customer.asp ID=custinfo>
<P VOICEFILE="enteraccount.wav">Please enter your account number followed by the pound key.
<INPUT TYPE="text" NAME="account number" SIZE="7" MAXLENGTH="7"></INPUT>
    .
    .
    .
</FORM>

The WTE renders the TEXTAREA element and text-type INPUT element in the same way. That is, when the engine reaches the element, the engine stops and waits for the caller's input, and then continues rendering the application after getting the input. The caller enters input by pressing telephony keys and, optionally, by speaking. For more information about using SR to enter text, see Taking Dictation.


Handling Time-outs and Non-valid Keys

Callers can make two types of errors while responding to a menu or entering data in an entry field. They can press a non-valid key, or they can cause a time-out error to occur by waiting too long before selecting a menu item or entering data. Whenever the WTE detects an error—either a time-out or non-valid key—it clears and ignores all the caller input gathered thus far for the menu or entry field, including the digit that caused an input error.

The WTEApplication object includes a number of configuration properties that specify how your application responds when the caller commits an error. The object also includes configuration properties that specify the time-out durations for your application's menus and entry fields.

The FirstTimeoutInterval property specifies the maximum amount of time that the WTE will wait for the caller to select a menu item or to begin entering data into an entry field. The InterTimeoutInterval property specifies the maximum amount of time that the WTE will wait for the caller to enter each successive digit into a multidigit entry field, or to select a menu item that was assigned a multidigit access key by the WTE (see Assigning Dual Tone Multi-Frequency Digits to Menu Items).

Default Error Handling

By default, whenever the time-out interval specified by FirstTimeoutInterval or InterTimeoutInterval expires, the WTE increments an internal error counter and then plays the text or wave file specified by the TimeoutAnnouncement property. Similarly, whenever the caller presses a non-valid key, the WTE increments the counter and then plays the text or wave file specified by the InvalidKeyAnnouncement property. After playing the TimeoutAnnouncement or InvalidKeyAnnouncement announcement, the WTE repeats the menu or re-introduces the entry field, giving the caller another chance to select an item or enter data. When the WTE detects an error—either a time-out or non-valid key—it clears and ignores all the caller input gathered thus far for the menu or entry field, including the digit that caused an input error.

When the caller successfully selects a menu item or satisfies the entry field, the internal error counter is reset to zero and the engine continues rendering the application.

The MaxRetries property specifies the maximum number of errors (time-outs and non-valid keys) that the caller is allowed to make. If the caller makes more than the specified number of errors, the WTE navigates to the application's recurring-error page, which is specified by the RecurringErrorPage property. If no recurring-error page is specified, the WTE disconnects the call.

Custom Error Handling

You can override the WTE's default error-handling procedure by including handlers for the onselectiontimeout and onselectionerror events. The engine fires these events after an error occurs, but before playing the text or wave files associated with the TimeoutAnnouncement and InvalidKeyAnnouncement properties. Your event handlers can prevent the engine from performing its default error handling procedure by setting the window.external.event.returnValue property to FALSE or by navigating to another location.

The following example shows a handler for the onselectiontimeout event. The handler sets two configuration parameters for the application before navigating to the HTML page called Timeout.htm.

<SCRIPT LANGUAGE="VBSCRIPT" FOR="account" EVENT="onselectiontimeout">
window.External.Configuration.OfferItems = TRUE
window.External.Configuration.UseSR = FALSE
window.navigate("Timeout.htm")
</SCRIPT>


Ignoring Navigation Operations During Input

The WTE supports three navigation operations: back, home, and operator. The caller can use these operations to navigate backward through an application, navigate to the beginning of the application, and transfer the call to the operator. To invoke a navigation operation, the caller enters a DTMF digit specified in the BackKey, HomeKey, or OperatorKey property.

WTE applications typically need to ignore navigation operations while the caller is entering data into an entry field. Ignoring the navigation operations allows the caller to use the DTMF digits specified in the BackKey, HomeKey, and OperatorKey properties to enter data, and prevents an inadvertent navigation operation from occurring while the caller is entering data. To ignore navigation operations, set the IgnoreNavigationKeysTillTermination property to TRUE. This property applies only to entry fields created by the TEXTAREA element or text-type INPUT element.


Terminating Input

The WTEApplication object includes a property called InputTerminator. This property is associated with all TEXTAREA elements and text-type INPUT elements in an application. It defines a string that the caller enters when finished entering data into a data-entry field. The string signals the WTE that the entry field has been satisfied and that it can continue rendering the application. A typical input terminator is the pound key (#). An application often specifies the input terminator before each entry field. For example, an application might say, "Please enter your age followed by the pound key".

For a text-type INPUT element, you can use the MAXLENGTH attribute to set the maximum number of characters for the element's entry field. Caller input into the entry field terminates as soon as the user enters the last character. The MAXLENGTH attribute is useful for getting data items of a predetermined length, such as a credit card number. Note that setting the MAXLENGTH attribute does not disable the role of the InputTerminator property. The caller can still end data input by entering the input terminator before entering the maximum number of characters.

An empty string is allowed for the InputTerminator property. However, Web telephony logs an authoring warning when the termination string is empty and there is no way out of an entry field without the help of scripts; for example, if there is no input terminator and no MAXLENGTH attribute.

You can use time-out intervals to terminate caller input into an entry field. For example, you could set the InterTimeoutInterval property to a small value. When the caller stops entering digits and the time-out interval expires, the WTE fires the onselectiontimeout event. Your handler for this event could ask the caller if they are finished entering data. For more information about how to handle time-outs, see Handling Time-outs and Non-valid Keys.

Finally, you can use event handlers to terminate input to an entry field. For example, an auto-attendant application might tell the caller to enter an extension number, or press 1 for sales, 2 for support, and so on. The application could include an event handler for the onchange event to check each digit that the caller enters into the entry field. If the event handler detects a 1 or 2, the handler would navigate to the sales or support page. Otherwise, the application would wait for the caller to fill the entry field to the maximum number of digits for extension numbers, and then transfer the call to the given extension.


Using European Telephones

In many European countries, it is common for telephones to have four additional keys, labeled A, B, C, and D. Additional DTMF tones are defined for these keys, extending the set of DTMF tones from 12 to 16 in Europe.

If your application will be accessed only from countries where these additional keys are available, you can take advantage of them by setting your application's WTEApplication.DetectABCD property to TRUE. Setting this property to TRUE causes the WTE to treat the A, B, C, and D keys as additional DTMF tones.

You should set DetectABCD to FALSE if your application will be accessed from countries where the additional keys may not be available. When DetectABCD is FALSE, the WTE ignores the DTMF tones generated by the additional keys.

The DetectABCD property also influences mnemonic menus. For example, you might want to let the caller use the letters on the phone to select menu items:

For Australia press A.
For Denmark press D.

In this case, if DetectABCD is TRUE, the A and D keys generate the additional DTMF tones. If it is FALSE, the caller would need to use the 2 and 3 keys, on which the letters A and D are printed.


Getting Spoken Input from the Caller

An application can capture caller input and menu selections using SR as an alternative to or in addition to using DTMF digits over the telephone. This section describes how to use SR in your application. For information about specific topics, see the following topics:

  • Guidelines for Using Speech Recognition
  • Taking Dictation
  • Using the GRAMMAR Attribute
  • Recording a Spoken Message


Guidelines for Using Speech Recognition

The role of a speech-recognition (SR) engine is to "listen" to the words that a caller speaks, translate them into text, and provide the text to the WTE. Using SR can be a convenient and natural way for the caller to enter data into a WTE application. For example, instead of requiring the caller to press a DTMF digit, you can use SR to let the user speak "one", "two", or any DTMF digit. You can also allow callers to speak the item they wish to select, such as "the shoe department" or "toys".

You may want to use SR for menus that include many possible choices. For example, suppose you wanted the caller to select the name of a city from a menu containing 50 different city names. Without SR, the caller would have to listen as Web telephony "speaks" each city's name and the corresponding action to take to select the city. With SR, your application could direct the caller to speak the name of the desired city. The SR engine would then try to match the caller's spoken city with one of the 50 possibilities.

The requirement to use SR is to have a SAPI 4.0a-compliant SR engine installed on the computer along with Web telephony. Also, speech recognition must be enabled for the application by setting the WTEApplication.UseSR configuration parameter to TRUE. You can enable SR for an entire application or only for specific menus or entry fields. Note that when SR is enabled, the caller can still select menu items and enter data into entry fields by pressing DTMF digits.

SR engines have two basic modes of operation that you can use in a WTE application: menu mode and free-dictation mode. In menu mode, the application prompts the caller to select from a predefined list of menu items. When the caller speaks, the SR engine attempts to match the speech to one of the items in the menu. In free-dictation mode, there is no predefined list of items. Instead, the SR engine attempts to translate the caller's words into text as the caller speaks them.

SR engines are most accurate in menu mode, when the choices the user can make are well known and limited. Although free-dictation mode tends to be less accurate, it is useful for getting small pieces of information that you cannot know in advance, or when a list of menu items would be too large to be practical. For example, you would use free-dictation mode to get the caller's age, address, telephone number, account number, and so on. For more information, see Taking Dictation.

If your application needs to gather large amounts of spoken input, such as spoken messages, from the caller, you should consider recording the input in a wave file instead of using SR. For more information, see Recording a Spoken Message.

Few SR engines can accurately recognize all speech all the time. For this reason, it is important to ask the caller to confirm each result returned by the SR engine. The WTE provides a default method for confirming results. For more information, see Confirming the Selection.


Taking Dictation

A Web telephony application can let the caller enter text by speaking into the telephone. This is called taking dictation, and is useful for getting small amounts of information from the caller.

Taking dictation involves enabling SR by setting the application's WTEApplication.UseSR property to TRUE. When SR is enabled, the caller can speak into any entry field created by the TEXTAREA element, or by the INPUT element with the TYPE=text attribute. The SR engine does its best to recognize the speech and translate it into text, which the WTE then enters into the entry field.

You can improve the recognition accuracy of the SR engine by associating a grammar file (.cfg) with the TEXTAREA or INPUT element. The grammar file specifies the words that you expect the caller to say. For more information, see Using the GRAMMAR Attribute. Using the TEXTAREA or text-type INPUT element requires that you also specify an input termination string by using the InputTerminator property. Callers enter this string to signal that they have finished entering dictation. You can use the MAXLENGTH attribute with the INPUT element to specify the maximum number of characters for the entry field. Dictation terminates when the caller enters the last character. For more information, see Terminating Input.


Using the GRAMMAR Attribute

You can use the GRAMMAR attribute on HTML elements that create menu items (such as A, BUTTON, and OPTION) and on elements that create entry fields for taking dictation (such as TEXTAREA and INPUT TYPE=text). On a menu item, the GRAMMAR attribute specifies a set of words and phrases, allowing the caller to select the menu item by speaking any word or phrase in the set. In the following example, the GRAMMAR attributes give the caller several ways to say the name of the person for whom to leave a message:

<P VOICEFILE="speakname.wav">For whom do you wish to leave a message?
<SELECT NAME="recipients" SIZE=10 onchange="SaveName();">
    <OPTION GRAMMAR="'Mister Smith' 'Robert' 'Bob' 'Bob Smith' 'Smitty'"
        VALUE="Robert Smith" VOICEFILE="smith.wav">Robert Smith
    <OPTION GRAMMAR="'Misses Doe' 'Jane' 'Janie'" VALUE="Jane Doe"
        VOICEFILE="doe.wav">Jane Doe
    .
    .
    .
</SELECT>

On TEXTAREA and INPUT TYPE=text controls, the GRAMMAR attribute can point to a SAPI 4.0a-compliant grammar file (.cfg) in Unicode format. The grammar file provides a hint to the engine about what the caller is expected to say. It replaces the default grammar file that the SR engine uses in dictation. The default grammar file does not provide any hint to the engine. For the complete syntax of grammar files, see the SAPI 4.0a documentation.

The following example shows how to specify the GRAMMAR attribute on an INPUT element:

<INPUT TYPE=text GRAMMAR=url(time.cfg)>

The .cfg file, Time.cfg, might contain the following information:

[Grammar]
Type=cf
LangID=1033

[(Commands)]
1=the time is "Time=" <time>

In this case, if the caller says "the time is ten fifteen", the text entered to the text control will be "Time=10:15".

For more information, see Taking Dictation.


Recording a Spoken Message

An application can record a spoken message from the caller into a wave file. Recording a spoken message involves using the VOICEFILE attribute on either the TEXTAREA or INPUT TYPE=text element. When used with these elements, the VOICEFILE attribute specifies the name and location of the wave file in which the WTE is to record the caller's message.

The following example records a caller's message into a wave file called message.wav:

<P>Please leave your message now. When you are finished, press the pound key.
<TEXTAREA VOICEFILE="message.wav"></TEXTAREA>

Note that in the previous example, the message.wav file is hard-coded and would be overwritten by each subsequent message. To prevent this, you could use scripting or an ActiveX control to generate unique file names for each caller at run time.

If the VOICEFILE attribute specifies the path to the wave file in Hypertext Transfer Protocol (HTTP) or Hypertext Transfer Protocol Secure (HTTPS), the file is uploaded to the given server and saved there in the specified location. The virtual directory in the server must have "write" permission.

The WTEApplication object includes several properties that control the duration of a recorded message. The RecordStopOnAnyKey property specifies a Boolean value that, if TRUE, causes recording to stop when the caller presses any DTMF key. If this property is FALSE, the caller can stop recording by pressing the string of DTMF keys specified in the InputTerminator property.

The MaxRecordTime property specifies the maximum duration of a spoken message. Recording automatically stops when the specified duration has elapsed. The RecordStopSilenceTime property specifies the period of silence that can elapse before recording automatically stops.

The InputWaveFormat property determines the format of the wave files in which recorded messages are stored.


Using Menus

This section describes how to create menus in a Web telephony application. For information about specific topics, see the following sections.

  • HTML Elements for Menus
  • Menu Owners
  • Offering Menus to the Caller
  • Assigning Dual Tone Multi-Frequency Digits to Menu Items
  • Using the %1 and %2 Notation
  • Organizing Anchor Elements
  • Receiving a Selection from the Caller
  • Using Speech Recognition to Receive a Selection
  • Confirming the Selection
  • Handling Errors
  • Multiple Menu Stations on a Single Page


HTML Elements for Menus

A menu lets the caller select from a list of items. WTE renders a menu by reading the menu items to the caller and then waiting for the caller to make a selection. A Web telephony application can use the following HTML elements to offer a menu:

  • One or more anchor (A) elements that include the HREF attribute.
  • A checkbox (INPUT TYPE=checkbox).
  • A group of radio controls (INPUT TYPE=radio) whose NAME attributes all share that same value.
  • One or more buttons (BUTTON or INPUT TYPE=button) inside a FIELDSET element.
  • One or more OPTION elements inside a SELECT element.
  • An image (IMG) whose USEMAP attribute specifies a client-side image map. The WTE treats the AREA elements within the specified MAP element as menu items.


Menu Owners

Each menu in a Web telephony application must have a menu owner. The elements BODY, FIELDSET, P, MENU, DIR, UL, DL, and OL can serve as menu owners for anchor elements (A).

BUTTON elements are considered menu items only if they are contained in a FIELDSET element. In this case, the FIELDSET element is the menu owner. If the FIELDSET element appears inside an existing menu, any buttons in the FIELDSET element are joined to the existing menu.

The FORM element serves as a menu owner for all the INPUT elements inside it.

For areas inside an image map, the IMG element serves as the menu owner. If there is already a menu owner, the areas are joined with that owner.

Radio controls do not have a menu owner. The whole radio group is offered once when the WTE encounters any INPUT TYPE=radio element from the group for the first time.

The owner of a menu defines the scope of the menu. That is, a menu begins at the owner's start tag and ends at the owner's end tag. The WTE gathers all items within the menu's scope and offers them to the caller. The offering of a menu to the caller is known as the menu announcement.

For intrinsic controls, the menu announcement consists of items starting from the parent FORM element, the previous control, or another menu (the closest to the intrinsic control). For a menu created by INPUT TYPE=(button, submit, reset, or image) element, the menu announcement consists of items starting from the parent FORM element, the previous control that is not an item of this menu, or another menu. The menu announcement concludes at the end of the parent FORM element, the next control that is not an item of this menu, or another menu. For more information, see INPUT.


Offering Menus to the Caller

If TTS rendering is enabled for an application, the WTE offers a menu to the caller by using TTS to render the text associated with all HTML elements within the menu's scope. If an element has a VOICEFILE attribute, the WTE plays the voice file instead of rendering the text associated with the element.

When offering a menu item, Web telephony combines the text or voice file found within the scope of the menu-item element with the prefix or suffix defined by the cue, cue-before, and cue-after CSS properties, if any of these are present on the element. The WTE offers the parts of a menu item in the following order:

  1. The cue-before property.
  2. The cue property.
  3. The text for the element, or the voice file specified by the element's VOICEFILE attribute, if present.
  4. The cue property.
  5. The cue-after property.

A prefix or suffix specified by the cue, cue-before, or cue-after property can be either a text string or a wave file. To specify a wave file, wrap the name and location of the file using 'URL()'. For example: "cue-before:URL(waves\ifyouwant.wav)".

The following example shows how to use menu-item prefixes and suffixes:

<P>Please select the type of vehicle you want.
<SELECT NAME="vehicle" SIZE=1 onchange="RecordSelection()">
    <OPTION VALUE="Sedan" STYLE="cue-before:'If you want a'; cue-after:', press 1'">Sedan
    <OPTION VALUE="Sport Utility" STYLE="cue-before:' If you want a'; cue-after:', press 2'">Sport Utility
    <OPTION VALUE="Minivan" STYLE="cue-before:' If you want a'; cue-after:', press 3'">Minivan
</SELECT>

The WTE would render the preceding menu as follows:

"Please select the type of vehicle you want. If you want a sedan, press 1. If you want a sport utility, press 2. If you want a minivan, press 3."


Assigning Dual Tone Multi-Frequency Digits to Menu Items

The Web telephony engine automatically assigns Dual Tone Multi-Frequency (DTMF) digits to each item in a menu, allowing the caller to select a menu item by entering the item's assigned digit. The menu items are assigned consecutive digits beginning with the digit specified by the WTEApplication.InitialAutoNumber property.

WTE assigns digits using the minimum number of digits possible, depending on the number of items in the menu. For example, if the menu has nine or fewer items, the WTE assigns single-digit access-key values. If the menu has from 10 to 99 items, it assigns two-digit values, and so on.

If the InitialAutoNumber property is an empty string, the WTE assigns access-key values beginning with the number 1, 10, 100, or 1000, depending on the number of items in the menu.

The number of items to which WTE assigns single-digit access-key values depends on the values already assigned to other keys. For example, if the home key is 1, the back key is 2, and the operator key is 3, the WTE assigns only the digits 4 through 9 to items in a menu that has fewer than 10 items. By using the ACCESSKEY attribute, you can assign DTMF digits to one or more menu items. In this case, the WTE assigns digits only to items that do not have the ACCESSKEY attribute, and uses only those digits that are not already assigned to other menu items.

The menu announcement for a menu item usually mentions the DTMF digit that the caller must press to select the item. For example:

"For account balance, press 1."
"For transaction history, press 2."


Using the %1 and %2 Notation

The WTE provides a convenient way for you to include the DTMF digit in the announcements for menu items. It involves using the %1 notation in the VOICEFILE attribute and the cue, cue-before, and cue-after style properties.

TTS-Rendered Menu Items

For menus items to be rendered using TTS, you can include %1 wherever you want the DTMF digit to be mentioned. As the WTE renders the item, it replaces all occurrences of %1 with the item's assigned DTMF digit. Using the %1 notation frees you from having to keep track of the DTMF digits that WTE assigns to your menu items.

The following example shows how to use the %1 notation:

<A HREF="account.htm" STYLE="cue-before:For; cue-after:press %1">Account Balance</A>
<A HREF="xaction.htm" STYLE="cue-before:For; cue-after:press %1">Transaction History</A>

In the previous example, if the InitialAutoNumber property were to specify an empty string, the menu items would be assigned the DTMF digits 1 and 2. However, if InitialAutoNumber were to specify a value of, for example, 13, the menu items would be assigned the DTMF digits 13 and 14.

Menu Items with Wave Files

For menu items that have wave files associated with them, you can use the %1 notation in the names of the files specified in the VOICEFILE attribute and the cue, cue-before, and cue-after style properties. For example, consider the following menu:

<P VoiceFile = "Welcome.wav">
<A Voicefile = "ForBooks,wav" STYLE = "cue-after: 'URL(Press%1.wav)'">Books</A><BR>
<A Voicefile = "ForSales.wave" STYLE = "cue-after: 'URL(Press%1.wav)'">Sales</A><BR>
<A Voicefile = "ForInfo.wav" STYLE = "cue-after: 'URL(Press%1.wav)'">Information</A><BR>
</P>

The application author, not wanting to use TTS, created wave files named Press1.wav, Press2.wav, and so on. These wave files contain the phrases "Press 1", "Press 2", and so on. The WTE, when assigning the access keys for each item, substitutes the number of an item's access key for the %1 in the file name. The WTE performs this substitution for the VOICEFILE attribute and all cues properties. The WTE would render the previous example as follows:

"Welcome to our customer service line." (from Welcome.wav)
"For books" (from ForBooks.wav) "press 1" (from Press1.wav)
"For sales"(from ForSales.wav) "press 2" (from Press2.wav)
"For information" (from ForInfo.wav) "press 3" (from Press3.wav)

Using the %1 notation is especially useful when creating dynamic menus that have a variable number if items and you cannot know in advance what the assigned access key values will be. In this case, you would record in advance all the possible "Press" phrases, and use %1 in the VOICEFILE attributes and cues. In this way, you will get correct menu announcements without having to use TTS.

Check Boxes and Stand-alone Buttons

For check boxes and stand-alone buttons, you can use the %1 and %2 notation.

The WTE treats a check box as a menu that has two options, selected or cleared. The WTEApplication.SelectCheckBoxKey and ClearCheckBoxKey properties define the DTMF digits that the caller uses to select or clear a check box. In the VOICEFILE attribute or cue properties of a check box, you can use the %1 notation to refer to the select digit, and the %2 notation to refer to the clear digit.

For example, suppose the SelectCheckBoxKey property is "3", the ClearCheckBoxKey property is "4", and you create the following check box:

<INPUT STYLE = "cue-after: 'URL(Clear%2.wav)'" VoiceFile="Select%1.wav" TYPE = CHECKBOX OnClick="Function1();">

The announcement for this check box would consist of phrases from the files named Select3.wav and Clear4.wav.

A stand-alone button is a button created either by the BUTTON element, or by the INPUT TYPE=button element outside of a FORM element. Like check boxes, the WTE treats a stand-alone button as a menu that has two options. In the case of stand-alone buttons, the options are clicked and skipped.

The WTEApplication.ClickButtonKey and SkipButtonKey properties define the DTMF digits that the caller uses to click or skip a stand-alone button. In the VOICEFILE attribute or cue properties of a stand-alone button, you can use the %1 notation to refer to the clicked digit, and the %2 notation to refer to the skip digit.

For example, suppose the ClickButtonKey property is "5", the SkipButtonKey property is "7", and you create the following stand-alone button:

<BUTTON STYLE = "cue-before: 'For'; cue-after: 'Press %1, To Skip press %2'" OnClick="Function1()">Books</BUTTON>

The WTE would render the button using TTS as follows:

"For Books press 5, To Skip press 7"

Suppose you create the following stand-alone button, keeping the same digits for the click and skip buttons:

<INPUT VoiceFile="Press%1Skip%2.wav" TYPE=BUTTON VALUE="Perform Something" OnClick="Function1();">

The announcement for this button would consist of phrases from the file named Press5Skip7.wav.


Organizing Anchor Elements

Anchor elements may follow a segment of text or be included in a segment of text. The following example shows anchor elements following a segment of text:

<P>Jimmy Stewart was a popular movie star. His unforgettable performance in the movie "It's a Wonderful Life" won him a place in the history of entertainment. <BR>
<A HREF=Stewart.htm>Jimmy Stewart<A>
<A HREF=wonderful.htm>It's a Wonderful Life</A>

The following example shows anchor elements inside a segment of text:

<P> <A HREF=stewart.htm>Jimmy Stewart</A> was a popular movie star. His unforgettable performance in the movie <A HREF=wonderful.htm>It's a Wonderful Life</A> won him a place in the history of entertainment.
</P>

The WTE renders both situations in a similar fashion. Anchors are offered in the order they appear in the HTML text. It is your responsibility to properly use the cue-before and cue-after CSS properties in order for the TTS engine to correctly render the combined text.


Receiving a Selection from the Caller

After offering a menu, the WTE waits for the caller to select one of the menu items. The caller selects an item by pressing the DTMF digit assigned to the item. If SR is enabled, the caller can select an item by speaking (see Using Speech Recognition to Receive a Selection).

The WTE supports a CSS property called cut-through. Setting this property to 'yes' (the default setting) allows the caller to select an item before the WTE has finished announcing all the items in the menu. This lets frequent callers navigate quickly through your application. Setting the cut-through property to 'no' requires the caller to listen to the entire menu announcement before being able to make a selection. This is useful when menus have recently changed or when giving an important announcement. Any DTMF digits received while the cut-through property is 'no' are ignored. Note that the cut-through property does not work with SR.


Using Speech Recognition to Receive a Selection

When enabled by the UseSR property in the configuration, Web telephony accepts DTMF digits together with speech input. Using speech recognition (SR), Web telephony tries to detect whether the spoken input sounds like one of the phrases sent to the SR engine. Web telephony uses the SRParameters property in the configuration to load an SR engine.

The phrases sent to the SR engine for each menu item (regardless of TTS mode) are:

  • InnerText property for anchors created by the A element, or menu buttons created by the BUTTON and INPUT TYPE=button elements.
  • VALUE attribute for submit buttons created by the BUTTON TYPE=submit and the INPUT TYPE=submit elements.
  • ALT attribute for areas created by the AREA element.
  • Option text for OPTION elements inside a list created by using the SELECT element.
  • Label text for radio buttons created by the INPUT TYPE=radio element.

Each of these can have additional phrases if the GRAMMAR attribute is defined on them.

Phrases for stand-alone buttons and check boxes are taken only from the configuration.

If the WTEApplication.UseSR property is TRUE and the WTEApplication.OfferItems property is FALSE, WTE does not play the announcements inside a menu. However, WTE plays the announcement of the menu itself.


Confirming the Selection

When you use SR to get a caller's menu selection, the SR engine takes the caller's spoken input and attempts to match it to one of the items in the menu. Because SR engines are not always accurate, the caller should be given an opportunity to confirm a selection before the application proceeds.

The WTE includes built-in functionality for presenting a confirmation menu to the caller. The confirmation menu typically repeats the user's selection as the SR engine "understood" it, and asks the user to confirm that the understanding was correct. For example, the confirmation menu might say, "Please confirm your selection. If you said popcorn, press 1. If this is not correct, press 9."

By using the SuggestConfirmation property of the WTEApplication object, you can control whether the WTE presents the confirmation menu. If this property is FALSE (the default value), no confirmation menu is presented and the caller's chosen item (as the SR engine understood it) is immediately selected. If it is TRUE, the WTE presents the confirmation menu, as described in the following sections.

Custom Confirmation Menus

After the user makes a selection, Web telephony calls the onselectionerror event handler, if the HTML page includes one. The onselectionerror event allows the application to customize the confirmation menu. Typically, the event handler creates the confirmation menu based on the user's probable selection. An application can determine the probable selection by examining the phrases associated with the AlternativePhrases property of the ExOM object. For more information, see the AlternativePhrases property.

Before returning, the onselectionerror event handler should set the value of the External.Event.returnValue property to FALSE. This cancels the default operation of the Web telephony confirmation menu mechanism.

Default Confirmation Menus

If the application does not define an onselectionerror event handler, or if the handler does not set the External.Event.returnValue property to FALSE, Web telephony automatically constructs the confirmation menu.

First, Web telephony plays the text or wave file defined by the ConfirmationMenuAnnouncement property of the WTEApplication object. The phrase associated with the property can be something like "Please confirm your choice." Web telephony ignores the ConfirmationMenuAnnouncement property if it is empty.

Next, Web telephony plays the text or wave file associated with the ConfirmBefore property, followed by the text or wave file associated with the item detected by the SR engine (or the recognized phrase if a voice file is not found), and then plays the text or wave file associated with the ConfirmAfter property. Finally, Web telephony plays the text or wave file associated with the RepeatMenuAnnouncement property.

For example, suppose your application includes the following section of HTML code:

    <P>What would you like to drink: Coke, Pepsi, or Sprite?
    <select>
    <option>Coke
    <option>Pepsi
    <option>Sprite
    </select>

The default confirmation menu would be something like this:

    ConfirmationMenuAnnouncement: "Please confirm your choice"
    ConfirmBefore: "If you said"
    SR-detected phrase: "Pepsi"
    ConfirmAfter: "Press 1"
    RepeatMenuAnnouncement: "If not, press 9."

The RepeatMenuKey property specifies the key that the caller presses if the SR result is not correct. In the previous example, the RepeatMenuAnnouncement property uses the "9" key because the RepeatMenuKey property is set to "9". If the caller presses this key, Web telephony offers the entire selection again. Note that you must specify the value of the RepeatMenuKey property—you cannot use the %1 notation in the RepeatMenuAnnouncement property. For more information about the %1 notation, see Assigning Dual Tone Multi-Frequency Digits to Menu Items.


Multiple Menu Stations on a Single Page

It is possible to have multiple menu stations on the same page. When multiple stations exist, each station can offer a link to another station on the same page (or to an item in the same station) using the #name or #ID URL options. Upon entering a menu station you must choose one of the menu items offered, or one of the special keys.


Handling Errors

Your application must be able to cope with errors that can occur while the caller is responding to a menu. For information about how to handle errors, see Handling Time-outs and Non-valid Keys.


Controlling Navigation

This section explains how navigation occurs in a WTE application and describes the navigation-related properties supported by the extended object model. For detailed information, see the following topics.

  • Automatic Navigation
  • Navigation Operations
  • Application-Driven Navigation
  • Navigation Announcements


Automatic Navigation

The WTE automatically performs a navigation operation when a call comes on the line with which the application is associated, when a caller makes too many errors, when a caller hangs up, or when WTE disconnects the call.

When a call arrives, the WTE navigates to the application's home page as specified by the HomePage property. You can use the home page to initialize your application's variables or to perform telephony operations. For example, an application might check the caller ID of the incoming call to decide whether to answer the call, transfer it to another extension, and so on.

When the caller commits too many data-entry or time-out errors, the WTE automatically navigates to the application's recurring-error page, if one exists. Otherwise, the WTE disconnects the call. You can use the recurring-error page to explain the error to callers and give them the opportunity to try again or to disconnect. The RecurringErrorPage property specifies an application's recurring-error page, and the MaxRetries property specifies the maximum number of errors that the caller may make before the WTE navigates to that page. For more information, see Handling Time-outs and Non-valid Keys.

The WTE navigates to your application's post-call page after the call was disconnected. It is typically the last page in an application, and allows the application to process data collected from the caller during the call. You can set or retrieve the post-call page by using the PostCallPage property.


Navigation Operations

The WTE supports the home and back-navigation operations. The home operation lets the caller return to an application's home page, and the back operation lets the caller navigate backward through the application. You can assign DTMF digits to the home and back operations by using the HomeKey and BackKey properties. When you assign DTMF digits to navigation operations, you must ensure that the same digits are not already assigned to the OperatorKey, ClickButtonKey, SkipButtonKey, SelectCheckBoxKey, or ClearCheckBoxKey property.

WTE applications typically need to ignore navigation operations while the caller is entering data into an entry field. Ignoring navigation operations allows the caller to use the DTMF digits specified in the HomeKey and BackKey properties to enter data, and prevents an inadvertent navigation operation from occurring while the caller is entering data. For more information, see Ignoring Navigation Operations During Input.


Application-Driven Navigation

WTE applications use menus to control how the caller navigates through your application. A menu presents the caller with a set of items and, when the caller selects one, the application navigates to the location specified by the selected item. If a menu item is an anchor element, the HREF attribute on the anchor element specifies the location to which the WTE navigates. For more information, see Using Menus.

Another way to navigate is to use a script to call one of the navigation methods supported by the Internet Explorer object model, such as window.navigate. The following example creates a button that, when clicked, calls window.navigate to navigate to the application's HTML page called Home.htm:

<INPUT TYPE=button VALUE="Home" OnClick="navigate('Home.htm')">

For more information about the Internet Explorer object model, see the Web Workshop on the Microsoft Developer Network (MSDN™) Web site.


Navigation Announcements

The NavigationAnnouncement property lets you specify text or a wave file for the WTE to play while navigating. This is useful when an application navigates to a new page to perform a lengthy operation, such as an ASP page that performs a database query. You can use the NavigationAnnouncement property to play background music or make regular announcements to let callers know that they haven't been forgotten. For more information, see Playing Background Music.


Using HTML Elements

This section describes how the Web telephony engine renders various HTML elements. For information about specific topics, see:

  • Stand-Alone Buttons
  • Check Boxes
  • Forms
  • Frames
  • Graphics
  • List Boxes
  • Labels
  • Tables
  • Text Areas
  • Text Inputs


Stand-Alone Buttons

In a WTE application, a stand-alone button is useful for presenting a Boolean-type menu that the caller can either click or skip. You create a stand-alone button either by using the BUTTON element, or by using the INPUT TYPE=button element outside a FORM element.

To introduce a stand-alone button to the caller, precede the BUTTON or INPUT element with text or a voice file, include a voice file or cues on the BUTTON or INPUT element itself, or use the LABEL element.

The following example shows a stand-alone button that is introduced by the cue-before and cue-after style properties on the BUTTON element:

<BUTTON STYLE = "cue-before: 'For'; cue-after: 'Press 5, To Skip press 7'" OnClick="Function1()">Books</BUTTON>

The WTE renders a stand-alone button similarly to the way it renders other menus. If the BUTTON or INPUT element has a voice file or any cues associated with it, the WTE plays the voice file and cues and then waits for the caller to respond.

The WTEApplication object has two pairs of properties that specify the ways that the caller can click or skip a stand-alone button. The ClickButtonKey property specifies the DTMF key that the caller must press to click a button, and the SkipButtonKey property specifies the DTMF key for skipping a button.

When SR is enabled, the ClickButtonPhrases property specifies a set of words and phrases that the caller can speak in order to click a button. Similarly, the SkipButtonPhrases property specifies the words and phrases for skipping a button.

You can use the %1 and %2 notation in the VOICEFILE attribute and cue properties of a button to refer to the click and skip keys. For more information, see Using the %1 and %2 Notation.


Check Boxes

In a WTE application, a check box is useful for presenting a Boolean-type menu that elicits a positive or negative response from the caller. A check box has two possible states—checked or cleared. The checked state is associated with a positive response, and the cleared state is associated with a negative response.

You create a check box by using the INPUT TYPE=checkbox element either inside or outside a FORM element. To introduce the check box to the caller, precede the INPUT element with text or a voice file, include a voice file or cues on the INPUT element itself, or use the LABEL element.

The following example shows a check box that is introduced by a voice file on the preceding P element:

<FORM METHOD=post ACTION=Order.asp ID=OrderForm
    .
    .
    .
<P VOICEFILE="waves\Express.wav">Express shipping:</P>
    <INPUT TYPE="checkbox" NAME="express">
</FORM>

The WTE renders a check box similarly to the way it renders other menus. If the INPUT element has a voice file or any cues associated with it, the WTE plays the voice file and cues and then waits for the caller to respond.

The WTEApplication object has two pairs of properties that specify the ways that the caller can enter a positive or negative response to a check box. The SelectCheckBoxKey property specifies the DTMF key that the caller must press to enter a positive response, and the ClearCheckBoxKey property specifies the DTMF key for entering a negative response.

You can use the %1 and %2 notation in the VOICEFILE attribute and cue properties of a check box to refer to the select and clear keys. For more information, see Using the %1 and %2 Notation.

When SR is enabled, the SelectCheckBoxPhrases property specifies a set of words and phrases that the caller can speak in order to enter a positive response. Similarly, the ClearCheckBoxPhrases property specifies the words and phrases for entering a negative response.


Forms

HTML forms are a well-known convention for gathering data from the user of a graphical Web browser. You can group any number of HTML elements within a form, and submit all the data in the form by means of a submit button.

Forms are useful when you want to gather a series of related data, such as a person's name, address, and phone number.

Internet Explorer constructs an HTTP request from all the information in the form. It then sends that request to the location specified in the ACTION attribute on the FORM element. A Web telephony application can send an HTTP request using elements in a form or using the same elements without a form. This is because, either way, the WTE renders each element sequentially, waiting for the caller's response before rendering the next element.


Frames

In a graphical Web browser, frames allow a Web-page author to keep parts of the window area fixed while loading pages into the remaining part of the window. You can use frames in your Web telephony application to create pages that contain menus that remain fixed while you replace other content and nested menus on the page. In a dual-access application, you can use frames to enhance the navigation experience for users of graphical Web browsers while maintaining smooth access for telephone callers.

In HTML, frames can be nested in two ways:

  • By using a nested FRAMESET element inside another FRAMESET element. This approach is reflected only in the graphical appearance of the page, and has no impact on how the WTE renders the page.
  • By using pages containing FRAMESET elements as the source page of a FRAME element. This is referred to below as "nested frames" and the "level" of the frame.

The following rendering rules apply to pages that contain frames.

  • When first entering a FRAMESET page, the top-level frame collection is rendered first. For each level, the frames are rendered in the same order that they appear in the frames collection exposed by the WebBrowser object model (OM).
  • If one of the pages contains a FRAMESET, the FRAMESET is rendered according to the same rules applied to the top-level frame.
  • When a document in a collection has links or intrinsic controls, its index is declared as the static menu index. The index of the static menu page does not change even if the document itself changes. A FRAMESET page cannot be the static menu for its level.
  • When the user chooses a link in the static menu, and the menu is loaded in one of the other frames, this frame is rendered. When the rendering of the page loaded in the frame is completed, the rendering continues according to the usual rules.
  • When the static menu document is completely rendered, the level is completed. If this is the top level, all rendering is completed. If it is a lower level, the rendering of the previous level continues, as if the FRAMESET page contained a regular page whose rendering had completed.
  • When a page which is not in the static menu index is completed, the rendering continues with the next index. When the last index is completed the rendering returns to the static menu index if there is one, or the level is completed if this level does not contain a static menu.
  • Level state (the static menu index and the current index) is kept only for pages in the direct link between the current level and the top level. If the caller navigated from a frame that is not on the direct link between the current level and the top level and will return later to that FRAMESET level, the state is not kept and the frameset level is rendered as a new one.


Graphics

Images such as .jpg and .gif files are ignored by the WTE. However, if an application contains an image (IMG) whose USEMAP attribute specifies a client-side image map, the WTE treats the AREA elements within the specified MAP element as menu items. For more information, see Using Menus.


List Boxes

A list box presents a set of items from which the caller can select. You create a list box by using one or more OPTION elements inside a SELECT element.

The WTE renders a list box as a menu. That is, the WTE announces the list box and all its items, and then waits for the caller to make a selection by pressing the DTMF key associated with an item, or by speaking a word or phrase associated with an item.

You can create a multiselection list box by including the MULTIPLE attribute on the SELECT element. In this case, the caller is able to choose more than one item from the list. The announcement of a multiselection menu includes all audio items (either voice files or textual) gathered before the element, the cue-before CSS property and the VOICEFILE attribute on the SELECT element, the voice files and cues from all of the OPTION elements, and the cue-after CSS property on the SELECT element. When the caller makes a choice, the announcement of the menu starts from the item that is next to the one selected. If an error (either a time-out or a non-valid key) is detected, announcements of all menu items are rendered excluding those that were already chosen. Audio items on the SELECT control itself are always rendered.

For more information, see Using Menus.


Labels

A label is a string of text created by the LABEL element. Labels are used to associate text with controls that do not have scope and cannot encapsulate text; that is, controls created using the BUTTON and INPUT elements. Web telephony supports association of labels to controls using the FOR attribute on the LABEL element.

When a Web site is graphically rendered, the person looking at the Web page intuitively understands the association between INPUT or BUTTON element and the text describing the element.

A Web telephony application requires some semantic association between the text describing the INPUT or BUTTON element and the element itself. When the association exists, the application can use the text to describe the element and direct the caller to provide input.

When a label is associated with a control, the label is not rendered at its original place, but only when the control is rendered. If no control is associated with the label, the label is rendered when encountered.

When a control is rendered, the label associated to it is the lowest label wrapping the control if this label has the appropriate FOR attribute or is the first label with the appropriate FOR attribute in the document.

If the control is a child of its associated label, all audio items inside the label, including the audio items of the control, are added in the order in which they appear in the document. The relevant access keys are added on all cues inside the label, from the label's cue-before property through the label's cue-after property. If the label is not a child of the associated label, its audio items are added after all the label's audio items, just before the cue-after property of the label. Again, access keys are inserted in all cues from the label's cue-before property through the label's cue-after property.


Tables

The WTE can render tables as regular text or as tabular data, according to the value of the WTEApplication.RenderTablesAsTabularData property. If this property is FALSE, the WTE renders tables as regular text. That is, the WTE plays the text or voice files for each element in the table in the order in which the elements appear, from top to bottom and left to right. If RenderTablesAsTabularData is TRUE, the WTE renders tables as tabular data. This topic describes how the WTE renders tables as tabular data. For information about specific topics, see the following sections.

  • Associating Header Information with Data Cells
  • Rendering Order
  • Menu Items in a Table
  • Cells Spanning Several Rows or Columns


Associating Header Information with Data Cells

If the WTE is configured to render tables as tabular data, the WTE makes an association between header cells and data cells as follows:

  • For a given data cell, the HEADERS attribute lists the cells providing pertinent header information. For this purpose, each header cell must be named using the ID attribute. If the HTML element with the specified ID in the HEADERS attribute is outside the table, the WTE generates an authoring error and ignores this ID.
  • For a given header cell, the SCOPE attribute informs the user agent of the data cells for which this header provides information. The current version of the WTE does not support the SCOPE attribute.
  • The ABBR attribute specifies an abbreviated header for header cells.
  • Cells that have the HIDDEN attribute are ignored by the WTE.
  • THEAD, TBODY, TFOOT, COL and COLGROUP have no specific influence on the header association, but nonetheless can be containers for all kinds of properties.

In the absence of header information (HEADERS), the list of header cells associated with a data cell will be found with the following algorithm (assume a left-to-right table):

  1. Search left from the cell's position to find row header cells, and then search upward to find column header cells. The search in a given direction stops when the edge of the table is reached or when a data cell is found after a header cell.
  2. Row headers are inserted into the list in the order they appear in the table. For left-to-right tables, headers are inserted from left to right.
  3. Column headers are inserted after row headers, in the order they appear in the table, from top to bottom.
  4. If a header cell has the HEADERS attribute set, then the headers referenced by this attribute are inserted into the list and the search stops for the current direction.
  5. Table data cells created by the TD element with the AXIS attribute are also treated as header cells. The current version of the WTE does not support the AXIS attribute.


Rendering Order

The WTE renders the elements of a table in the following order:

  1. Renders the summary of the table. This can be an announcement or a voice file.
  2. Renders the caption, if present.
  3. For each data cell, row after row, renders all headers according to the header association rules described in Associating Header Information with Data Cells, and then renders the data cell.

For any table element that has a VOICEFILE attribute, the WTE plays the voice file and ignores any text associated with the element.


Menu Items in a Table

All menu items (anchors and buttons) inside a table are gathered when the table is parsed, and offered to the caller at the end of the table. A menu item is gathered only once, even if its cell is read more than once. The items are numbered with the usual numbering algorithm (see Assigning Dual Tone Multi-Frequency Digits to Menu Items).

Intrinsic controls inside a table that is rendered as tabular data are ignored.


Cells Spanning Several Rows or Columns

Data and header cells may span several rows or columns. The definition is:

  • A data cell that is column-spanned is rendered once, with the row headers as usual and column headers for all its columns, row by row.
  • A header cell that is column-spanned is rendered once for each column. If there is a data cell spanned on more then one of these columns, the header is rendered only once for all the columns.
  • A data cell that is row-spanned is rendered once for each row.
  • A header cell that is row-spanned is rendered once for each row as a row header. If this header cell is also a column header for a data cell, it is treated according to the usual rules and rendered once for the cell.
  • If a cell is spanned both from the former row and the column (overlapped), the cell is treated as row-spanned, and the data gathered is that of the previous row.


Text Areas

A text area is a multiline entry field created by using the TEXTAREA element. You can use a text area in a WTE application to DTMF digits or spoken input from the caller. A text area is especially useful for recording a spoken message from the caller. For more information, see Getting Input from the Caller and Getting Spoken Input from the Caller.


Text Inputs

A text input is a single-line entry field created by using the INPUT TYPE=text element. In a Web telephony application, a text input can accept DTMF digits or spoken input from the caller. Applications use text inputs to gather such items as the caller's name, credit card number, phone number, and so on.

You can set the maximum length of the text input and, when the caller has entered that many characters, the text input uses those characters as the caller's finished input. You can also set a termination character such as the pound sign (#). The text input accepts no more characters after the caller enters the termination character. The announcement you create for a text input might say "enter your ID, then press pound."

You can gather information in a text input using SR, but because the SR's choices are not limited as they are in a menu, the accuracy for a variety of speakers is very low. SR engines are much more accurate when choosing one of a few possible responses to items on a menu, rather than interpreting any words the caller might choose to speak. If you need free-form text input, you can record the caller's spoken input as a wave file. For more information, see Recording a Spoken Message.

For more information about using text inputs, see Getting Input from the Caller and Getting Spoken Input from the Caller.


Handling Events

This section describes how to handle events in a Web telephony application. For information about specific topics, see:

  • Event Objects
  • Standard Web Browser Events
  • Web Telephony Events
  • Text Input Events
  • Using Multiple Event Handlers


Event Objects

An event handler in a dual-access application can be called by both Internet Explorer and the WTE. When Internet Explorer calls an event handler, the handler uses the standard Internet Explorer event object to retrieve event-related information. When the WTE calls, the event handler uses the event object exposed through the WTE extended object model. The following example shows how to retrieve the appropriate event object:

<script language="VBScript" FOR=myControl EVENT="onchange">
    DIM  objEvent

    If UnderIVR Then
        Set objEvent = window.external.event
    Else
        Set objEvent = window.event
    End if
    .
    . // Process the event here.
    .
</script>

An application can determine if it is running under the WTE by checking the hostName property of the external object. For more information, see Determining Whether the Phone or Browser is Being Used.

The WTE delegates firing of the onclick event to the underlying WebBrowser control of Internet Explorer. This means that an event handler for the onclick event is always called by Internet Explorer, even when an application is running under the WTE. For this reason, an onclick event handler always uses window.event to retrieve event information. Similarly, because the onselectionerror and onselectiontimeout events are fired only by the WTE, the handlers for these events always use window.external.event to retrieve event information.


Standard Web Browser Events

A Web telephony application receives all the standard events fired by Internet Explorer . For example, the onunload event is fired automatically when a page is unloaded. In the event handler for this event you can write custom code, such as restoring configuration parameters when a page is loaded.

Note that the WTE may start rendering a page before firing the onload event. If you need a script to run before the WTE starts rendering a page, either use an immediate script or associate an event handler with an automatically clicked button placed at the beginning of the page.

When running under the WTE, an application should not use standard events related to user-interface (UI) behaviors of the graphical Web browser. These include events such as onfocus, onblur, onmouseover, and so on.

For more information about standard events, see the Web Workshop on the Microsoft Developer Network (MSDN) Web site.


Web Telephony Events

The onselectionerror and onselectiontimeout events are fired only by the WTE. They are not fired by Internet Explorer.

The onselectionerror event fires when a caller makes a data-entry error, such as pressing a non-valid DTMF key for a menu or control. The onselectiontimeout event fires when a caller waits too long to make a selection. The FirstTimeoutInterval and InterTimeoutInterval configuration properties determine the amount of time that a caller has to make a selection

For more information, see Handling Time-outs and Non-valid Keys and Confirming the Selection.


Text Input Events

The onkeypress and onchange events allow your application to respond to keystrokes and completed user input. For information about specific topics, see the following sections:

  • The onkeypress Event
  • The onchange Event


The onkeypress Event

The onkeypress event is fired each time the user enters data into the entry field created by a TEXTAREA element or by an INPUT element whose TYPE is text. The WTE fires the event each time the user presses a DTMF key. A graphical Web browser fires the event each time the user enters a character by means of the keyboard.

The onkeypress event gives you a chance to examine or change a character before it is entered into the entry field. For example, the onkeypress event handler for a credit-card number field might check each character and, if it is a digit, let it through unchanged. The handler could discard nondigits, such as the pound key (#).

You could also designate a special key, such as the star key (*), to have special meaning. For example, your application might say, "Enter your credit card number. If you press an incorrect digit, press the * key to cancel the previous digit." Your onkeypress event handler would check for the * and, when it arrives, edit the characters entered so far, deleting the last character that the caller entered.

An event handler for the onkeypress event can change the value of a key entry by using the Event object (External.Event). For example, suppose you wanted to change all star (*) keys to zero (0) characters. Your event handler can use the Keycode property of the Event object to find out the ASCII value of each key pressed and, if it is 42 (ASCII *), change the value of the Keycode property to 48 (ASCII 0). For example:

<script Language="VBScript" For="acctnum" Event="onKeyPress">
If External.Event.Keycode = 42 Then
    External.Event.Keycode = 48
End If
</script>

To have the WTE ignore the digit that was pressed, set the Keycode property to 0.


The onchange Event

The onchange event fires when the user finishes entering data into an entry field created by a TEXTAREA element or by an INPUT element whose TYPE is text. The user finishes either by entering the maximum number of characters for the field, or by entering the termination string. You set the maximum length for an INPUT element by using the MAXLENGTH attribute (the TEXTAREA element does not have this attribute). You set the termination string by using the InputTerminator property of the WTEApplication object.

Note that the onchange event fires only if the value of the entry field changed from its previous value. For example, suppose an HTML page includes a text INPUT element that has the VALUE attribute set to "123":

<input type="text" value="123"></input>

If the user enters the value "123", the onchange event is not fired.


Using Multiple Event Handlers

In an HTML document, there can be multiple event handlers for each event and element. In this case, events are fired according to the following rules:

  • For a given event, only one JScript and one VBScript handler can be executed. Other script languages are not supported.
  • JScript and JAVAScript are the same, VBS and VBScript are the same.
  • The JScript handler always executes first.
  • Handlers set with the FOR and EVENT attributes have the highest priority.
  • An inline Visual Basic handler has priority over a Visual Basic-style handler (sub_onchange).
  • If there are two elements with the same ID in the same scope, both fire events.
  • The default value for the LANGUAGE attribute is JScript.


Using Other Web Technologies

You can use many other Web technologies in your Web telephony applications besides HTML. This section describes these other technologies. For information about specific topics, see the following sections:

  • ActiveX Controls
  • Automation
  • Client-side Scripting
  • Dynamic HTML
  • ODBC Databases
  • Scriptlets
  • Server-side Scripting

ActiveX Controls

You can insert any ActiveX controls into your HTML pages to provide customized functionality. These ActiveX controls can be ones that you created or bought from a third-party vendor. For more information about ActiveX controls, see the MSDN library.

Automation

Any Automation object available to the WebBrowser control can be controlled in a Web telephony application. You might use Microsoft Excel, for example, to carry out some mathematical functions by launching it without displaying it, putting some numbers in some cells, and calling an Excel function to evaluate the results.

Set objExcelApp = CreateObject(Excel.Application)
Set objWks = objExcelApp.Open("Temp.XLS")
...
Set objExcelApp = Nothing

Some automation objects are not secure and may cause Internet Explorer to display a warning message. Before using an automation object in a WTE application, you should check that the object is secure by running it under Internet Explorer. Alternatively, you can check an automation object by running it under WTE while the WTE service is running in window mode (see Running the Web Telephony Service in Window Mode).

For more information about Automation, see the MSDN library.

Client-side Scripting

You can use scripts in VBScript or JScript (or both languages) on your HTML pages. For more information about scripting, see the MSDN library.

Dynamic HTML

You can use any dynamic HTML (DHTML) functionality in your Web telephony applications. For example, you can change the inner text of an element to provide lengthier descriptions to new users.

For more information about DHTML, see the Web Workshop on the MSDN Web site.

ODBC Databases

You can access any ODBC database from your Web telephony applications. You can use any Internet technology that you would normally use to access databases from an HTML page, such as Visual Database Tools or ActiveX Data Objects (ADO).

You use Automation scripting or ActiveX controls as you would with any Web page that accesses an ODBC database.

Set DB = CreateObject(ADO.CreateConnection)

Scriptlets

The WTE supports scriptlets. This section describes scriptlets and explains how to use them in an application. For information on specific topics, see the following sections:

  • Introducing Scriptlets
  • Advantages and Benefits
  • Scriptlets in Web Telephony Applications

Introducing Scriptlets

Scriptlets are a standard feature of Internet Explorer. They allow you to take a combination of HTML elements, encapsulate them as an object, and then use the object again as needed. For example, suppose you need to use the same menu in several places in your Web telephony application. You could define the elements for this menu on one page, encapsulate them as a scriptlet object, and use the object anywhere you needed the menu. You could also use scriptlets to keep a library of frequently used configuration settings for various applications, or to present special graphical user interface elements in a dual-access application.

You insert a scriptlet onto a page as an object of type "scriptlet", supplying the relative or absolute path to the HTML page that contains the scriptlet HTML code.

A scriptlet may or may not have a visual UI. If it does, you can define the size of the window for the UI when inserting a scriptlet into a page. A scriptlet might not have a UI if it contains only scripts and no visual elements.

Advantages and Benefits

A key advantage to using scriptlets is that you only need to write the HTML once. Another advantage is that if you need to make changes, you only need to edit one HTML page and any changes are reflected in all instances of the object.

The main benefit of scriptlets is that they can expose properties, methods, and events as if they where COM objects, making their capabilities easy to use inside the hosting document. A scriptlet's properties and methods can be called from scripts on any page where the scriptlet is inserted.

Scriptlets in Web Telephony Applications

The WTE fully supports scriptlets, but slightly differently than Internet Explorer. In general, the WTE treats HTML code in a scriptlet as an extension to the host document. This means that the code is rendered under the hosting OBJECT element as if it was cut and pasted there. This allows you to create rich menu items, buttons, and so on, and embed them into different documents. However, as in Internet Explorer, a scriptlet is a completely different document and does not inherit any property from its host. For example, if the host's text color is red, it does not influence the color of the text inside the scriptlet. In a Web telephony application, no TTS rendering, voice file, and so forth, in the host influences the scriptlet.

The following example contains a menu in which the second item is a scriptlet whose UI is defined by OtherItems.htm and with functionality accessible through public interfaces. Note that this scriptlet actually can contain several menu items that will be joined with "ITEM1" and "Akey4".

<BODY>
<A ID="ITEM1" HREF="#ID0">Item1 </A><BR>
<object data="OtherItems.htm" type="text/x-scriptlet"></object>
<A id="AKey4" HREF="#ID0">Last Item </A><BR>
</BODY>

For the WTE to render a scriptlet's HTML document, the scriptlet must expose the document through a property named WTEScriptletDocument. For example:

public_description = new MyScriptlet();
function MyScriptlet() {
    this.get_WTEScriptletDocument = DoGetDoc;
}
function DoGetDoc() {
    return document;
}

If the scriptlet does not expose the WTEScriptletDocument property, or exposes anything else through this property, it is ignored by the WTE. Also, because it does not support rendering a FRAMESET scriptlet, the WTE also ignores such a scriptlet and generates a log warning.

To access the WTE External object from a scriptlet, use the window.parent.external property. Alternatively, an application can pass the External object to the scriptlet by defining a special property such as "IVRExternal" that has a "put" method, and setting the External object from the host.

Server-side Scripting

You can use ASP pages to do server-side scripting.

If you want to verify a password, for example, you don't want to put the valid values into a client-side script that users could easily view.

Other examples of server-side scripting include getting dynamically requested information from a database and formatting this as a standard HTML table that is returned to the user in standard HTML elements.

For more information about server-side scripting, see the Web Workshop on the Microsoft Developer Network (MSDN) Web site.


Programming Administration and Configuration Tasks

The WTEApplication object is part of a larger object model that handles the default configuration and administration tasks for the user interface (UI) of the Web Telephony Engine (WTE). This same set of objects is exposed for you to use in customizing and securing the settings and other data of your WTE application.

You can access these objects from your setup program or a stand-alone administration program written in C++ or Microsoft® Visual Basic®. Alternatively, you can use the scripting hosts provided by Microsoft Internet Explorer (for executing scripts inside HTML pages) and Internet Information Services (IIS) (for executing scripts inside of Active Server Pages (ASP) to create a Web-based administration interface for your WTE application. These scripting hosts can execute scripts written in Visual Basic Scripting Edition (VBScript), Microsoft JScript®, or third-party scripting languages.

This section describes the WTE object model and several ways that you can use these objects to administer and configure your application, either through a setup or stand-alone administration program, or from scripts inside your WTE application. Topics include:

  • The Web Telephony Object Model
  • Creating the Root Web Telephony Object
  • Creating a WTE Application Object
  • Managing Collections
  • Managing Objects
  • Managing Dependent Objects
  • Saving and Refreshing Object Settings
  • Accessing Arrays
  • Listing Servers in the Array
  • Assigning Addresses to Applications
  • Creating Persistent Storage for Vendor-specific Data
  • Securing An Application's Configuration Parameters
  • Sending Notifications
  • Sample WTE Administration Scripts
  • Creating WTE Objects in Web Applications
  • Using Enumerated Types in Scripts


The Web Telephony Object Model

In the WTE object model, the root of the system is the WTEArrays collection object, which contains one or more WTEArray objects. Each array contains a collection of servers, a collection of applications, and a collection of address groups, in addition to a single WTELog object. Each WTE application is represented by an instance of the WTEApplication object. The following illustration shows the relationships among these objects.

Every collection object also contains a vendor data object, for storing a vendor's private data.


Creating the Root Web Telephony Object

The WTE objects are made available through a single root object. You must first create this root object, then use its properties to access subordinate objects in the object model.

To create this root object in VBScript, use the CreateObject function. To create this root object in JScript, use the ActiveXObject function. Use the class name "WTE.Root" as in these examples:

  • VBScript
    Set Root = CreateObject("WTE.Root")
  • JScript
    Root = new ActiveXObject("WTE.Root");

When creating the root object in Visual Basic, use the programmatic identifier "WTE," as in this example:

Dim Root As WTE
Set Root = New WTE


Creating a WTE Application Object

To create a WTEApplication object, which represents a single Web telephony application, first use the WTEArray.Applications property to create a WTEApplications collection object (if one does not already exist).

Use the WTEApplications.Count property to obtain the index of the newly created application object. Then use the WTEApplications.Item method to retrieve the new WTEApplication object.

For information on using the WTEApplication object to configure your application see Web Telephony Configuration Object.


Managing Collections

WTE object collections have the following methods and properties:

  • Add(Name, HomePage) method – Creates a new object in the collection, and returns a reference to it. The object must be identified by the application name, which must be unique to that array and the name of the application's start page. Note that in this initial implementation of WTE some collections hold only a single object. For example, WTE currently supports a single server on a single array and the corresponding object collections, WTEArrays and WTEServers, do not have Add methods.
  • Count property – Returns the number of items in the collection. Use this property to obtain the index of a newly created object. Then you can use this unique identifier (ID) to retrieve the object.
  • Item(index) property – Returns a specific object from the collection. The index is the value of the Count property after the object was created. This is the default method for identifying an object, if you omit the Item method name when requesting an object.
  • Remove(index) method – Removes a specific object (identified by its index) from the collection.
  • Save method – Writes the values of all the objects in the collection to persistent storage.
  • Refresh method – Reads the values of all the objects in the collection from the persistent storage.
  • VendorDataSets property – This property retrieves a reference to the collection of VendorDataSet subobjects that store and retrieve vendor-specific data for the parent object.


Managing Objects

Most WTE objects have these properties and methods in common:

  • Name property – A string that identifies the object by name. Note that the index of an object, as provided by the collection object, is guaranteed to be unique, while the Name property may not be.
  • Save method – Writes the object's information (properties) to persistent storage.
  • Refresh method – Reads the object's information (properties) from the persistent storage. Note that this method effectively discards any changes that were not saved.
  • VendorDataSets property – Retrieves a reference to the collection of VendorDataSet subobjects that store and retrieve the containing object's vendor-specific data.


Managing Dependent Objects

Only the root WTE object can be created externally. This means that you can create instances of it directly in scripting or other programming languages. Some WTE objects can be created by using the Add method on a collection object. For example, you can use the WTEApplications.Add method to create a new WTEApplication object.

Some objects contain a reference to other objects. For example, a WTEAddress object contains the name of its associated WTEApplication object.

There are specific considerations to keep in mind as you manage objects in your code:

  • When adding an object that contains a reference to another object or when modifying the name of the referenced object, WTE verifies the existence of the referenced object. If the referenced object cannot be verified, the operation fails.
  • When removing an object that is referenced by another object, WTE removes that reference.
  • If you try to save an object whose parent is a new object that has never been saved, you should first save the parent object; otherwise, the save operation will fail.


Saving and Refreshing Object Settings

Most WTE objects have methods you can use to save their settings to persistent storage or to refresh their settings from values in persistent storage. In this release, the storage method is determined at setup; it is the Active Directory™, if enabled on the server, the registry otherwise. The WTE application does not specify the type of storage when using a save operation; this is handled transparently by the run time.

Saving Objects

The Save method stores all settings of that object (and its subordinate objects) into persistent storage. Because the Save method writes all changes for an object as well as its subordinate objects, you can save all changes to all objects by saving the top-level object. However, it is more efficient to call Save on the relevant subobject when possible.

It is important to understand that no changes are saved unless the Save method is called. If you change the value of a property, for instance, you must explicitly save the changes to the object, or the change will not be written to persistent storage.

If Active Directory is enabled on the host computer, it is the repository for persistent storage. When Active Directory is not enabled, persistent storage is in the Registry. The underlying run time handles this transparently; scripts that use the Save method do not have to specify the location for storage.

Note Some objects do not have a Save method. To save these objects, invoke the Save method of a parent of the object in the hierarchy.

Refreshing Objects

The Refresh method reads the last saved values from persistent storage and applies them to the object and its subordinate objects.

The Refresh method retrieves the last-saved settings from persistent storage, and applies them to the object and to any subordinate objects. Use the Refresh method to be sure you have the current values for an object and its subordinate objects. This is useful when the object has been modified elsewhere and you need to retrieve the updated information. You can also use the Refresh method to abandon changes you've made to an object that have not yet been saved.


Accessing Arrays

An array is a set of WTE computers that have similar configurations and share resources in order to increase efficiency. For example, several telephony applications can be kept in the array and shared among several servers, with each server using different devices for the same applications.

Web telephony engine arrays are represented as WTEArray objects. The set of WTEArray objects is managed through the WTEArrays collection, which is available through the Arrays property of the root object. You can obtain a reference to a WTEArray object using either of two methods of the WTEArrays collection:

  • Item method
  • GetContainingArray method

The Item method of the WTEArrays collection returns a reference to any array you identify by index or name. Here are two VBScript examples:

Set objMyArray = Root.Arrays(1)
Set objAutoAttendendArray = Root.Arrays("Offshore Array")

The GetContainingArray method of the WTEArrays collection returns a reference to the containing array. (The containing array is the one to which the server running your WTE application belongs.) You can quickly obtain a reference to the containing array (also called the "current array") using code similar to this:

Set objCurArray = Root.Arrays.GetContainingArray

The WTEArray object has properties that provide access to other parts of the Web Telephony object model. The following table lists the properties that provide references to other objects and the objects returned.

Property | Returns a reference to
Applications | WTEApplications collection object
Log | WTELog object
Servers | WTEServers collection object
AddressGroups | WTEAddressGroups collection object
WTEVendorDataSets | WTEVendorDataSets collection object


Listing Servers in the Array

The following example shows how to use the WTE objects to generate a list of servers in the array.

Sub ListServers()
    Set WTE = CreateObject("WTE.Root")
    Set Arrays = WTE.Arrays

    arrayname = InputBox("Please enter the array name, or <ENTER> for the first array:")

    If arrayname = "" Then
        Set arr = Arrays(1)
    Else
        ' Look for the specified array
        On Error Resume Next
        Set arr = Arrays(arrayname)

        If Err.Number <> 0 Then
            MsgBox "The specified array was not found"
            Exit Sub
        End If
    End If

    Set servers = arr.servers
    output = "Servers in the array:" & vbCrLf
    For Each server In servers
        output = output & server.Name & vbCrLf
    Next
    MsgBox output
End Sub

ListServers


Assigning Addresses to Applications

The Web Telephony engine supports both simple addressing, which maps each device to a single telephone number, and Dialed Number Identification Service (DNIS).

DNIS is a telephone service that identifies, to the answering device, the number that the user dialed. For example, consider a WTE installation with multiple incoming telephone lines and multiple WTE applications. DNIS identifies the touch-tone digits — Dual Tone Multi-Frequency (DTMF) or multi-frequency (MF) — and maps the called ID to the appropriate application. The call can then be transferred to any idle device, rather than the device associated with the actual number.

To use either addressing mode in your configuration/administration application:

  1. Create a WTEAddress object for each TAPI device on the server.
  2. Set the WTEAddress.Name property to the name of the device.
  3. Use the WTEAddress.Description property to provide a description of the device.
  4. If the device supports called IDs (which allow a call to be transferred or forwarded to another line) set the WTEAddress.SupportsCalledID property to TRUE.
  5. Use the WTEAddress.AssignedApplication property to assign the device address to an application.
  6. If the device supports DNIS, set the WTEAddress.AssignedGroup property to the name of the Address Group to which the device belongs.

To support DNIS, each WTEArray object (not the individual WTEServer object) contains a collection of WTEAddressGroups collection objects. To enable DNIS:

  1. Create a WTEAddressGroup object and add it to the WTEAddressGroups collection.
  2. For each incoming phone line in the address group, create a WTEDNIS object and add it to the WTEDNISes collection.
  3. Set the WTEDNIS.DialedNumberIdentifer to the called ID.
  4. Set the WTEDNIS.AssignedApplication to the name of the application you want to associate with that line.

When an incoming call's address is identified as belonging to an address group, the DNIS connects the called ID to its assigned application and forwards the call to an available device.


Creating Persistent Storage for Vendor-specific Data

Many WTE objects contain a subobject, WTEVendorDataSets, that allows you to provide persistent storage of vendor-specific information for that object. For example, consider an application that retrieves data from a particular SQL server and has a user interface allowing the administrator to configure the name of the database. This name can be stored in a WTEVendorDataSet object. Then, when the application starts, it can retrieve the name of the database from the associated WTEVendorDataSet object.

The WTEVendorDataSets collection contains an array of WTEVendorDataSet objects, each holding a particular vendor's private information for the parent object. The collection can use the same collection methods found in all other WTE objects, as described in Managing Collections.

Using the WTEVendorDataSet Object

Whenever you add a WTEVendorDataSet object to the WTEVendorDataSets collection, call the Count property immediately thereafter. The value of this property is also the index of the newly created object .The application can use this number at any time to retrieve a WTEVendorDataSet it created earlier; for example, during setup.

The WTEVendorDataSet object stores private data as predetermined name-value pairs. WTE holds this data in persistent storage and serves it to the vendor's application on request.

An administrator can access the WTEVendorDataSet object to retrieve the name of a data set, or all names in a data set, and to set and retrieve the value associated with a given name in the set. The following example sets the property "Name", with the value "Janine".

SetVDSName = Obj.VendorDataSet(NameOfMyDataSetObject).Name = "Janine"

The value can be of any Automation type: integer, string… . For example,

Set Obj.VendorDataSet.Name = 392476

is a valid setting.

Note that if you have set the WTEApplication.EnableFullConfiguration property to FALSE, as described in Securing An Application's Configuration Parameters, an administrator will not have access to this vendor data.


Securing An Application's Configuration Parameters

Typically, an application vendor provides a setup program to install a Web telephony application on the server. This setup program sets the initial configuration parameters for the application. By default, the configuration parameters are accessible through the Windows 2000 Computer Management tool, and an administrator can change an application's configuration parameters at any time. This can create problems if an application requires certain settings in order to work properly.

Your setup program can prevent an administrator from changing many of an application's configuration parameters by setting the WTEApplication.EnableFullConfiguration property to FALSE. When this property is FALSE, the WTE administration tool displays only the General and Addresses tabs in the application's property sheet.


Sending Notifications

Notifications are used to signal an application that the data in the persistent storage of an WTEVendorDataSet object has been modified.

COM-based programs typically use the Connection Point mechanism (the standard COM notifications mechanism) for a sink interface with a single method called OnChange.

The following example uses the onchange event to report the number of callers who received a busy signal. Notice the WithEvents statement that is used for an outgoing interface.

Dim WTE As New WTE
Dim WithEvents ps As WTEVendorDataSet
Set ps = WTE.Arrays(1).VendorsDataSets(NameOfMySet).Value(1)

Private Sub ps_OnChange()
    ps.Refresh
    MsgBox "BusySignal count is:" & ps("Statistics").Value("Busy Signal Count")
End Sub

The following example uses the WTEVendorDataSet.Name property to identify the current user.

Dim WTE As New WTE
Dim WithEvents pd As WTEVendorDataSet

Private Sub Start_Click()
    Set pd = WTE.Arrays(1).VendorDataSets(1).Name = "Adi"
    MsgBox "click - user is:" & pd("UserName")
    pd.Save
End Sub

Private Sub pd_OnChange()
    pd.Refresh
    MsgBox "pd_OnChange - user is:" & pd("UserName")
End Sub

C/C++ programmers who don't wish to write a COM sink interface, or don't have a message loop in their program, can use a simpler method for notifications. Pass the return value of the method WTEVendorDataSet.WaitForChanges to an event handle that is signaled whenever changes occur. You can also use the Microsoft Win32® API RegisterWaitForSingleObject function to wait for the event.

There are cases when it is better to use Connection Point, and cases where the WaitForChanges property works more efficiently. Here are some implementation details that may help you decide upon the best notification method for your purposes:

  • Connection Point uses an internal (to the WTE) thread pool.
  • Connection Point creates a window (in the context of the caller thread) for each call to the IConnectionPoint::Advise method.
  • Connection Point uses the IDispatch method to invoke the appropriate method.
  • When using Connection Point you must have a message loop in your caller thread.
  • The WaitForChanges method does not work over Distributed COM (DCOM).

For more information on using connection points, see IConnectionPoint.


Sample WTE Administration Scripts

The following sample script applications are located in the Samples folder on the Platform SDK CD-ROM:

Filename | Description | Language
ApplicationData | Shows basic data about all installed applications. | VBScript
ChangeAllApps | Changes a specific field to a fixed value in all installed applications. | VBScript, JScript
FindApplications | Finds application names for a given line addresses list. | VBScript
MoveApp | Moves a given line address from one application to another. | VBScript


Creating WTE Objects in Web Applications

Platform SDK: Web Telephony Engine

Using WTE Configuration and Administration Objects inside Web Applications

As mentioned earlier, you are not limited to using the WTE objects in a stand-alone application. You can create and embed the objects directly in an ordinary HTML application, or you can script the objects in an Active Server Pages (ASP) application.

To create an instance of a COM object in a Web page, you can use the HTML OBJECT tag. Alternatively, if your scripting language provides a native way to create COM objects, you can create an object instance using script.

The following example illustrates using the OBJECT tag to create and embed a WTEVendorDataSets collection containing a single WTEVendorDataSet object in a Web page. Note that the CLASSID is the UUID that is part of the object's interface definition. To find the UUID for any WTE object, see the mswtecom.idl file, which ships in the Platform SDK.

<OBJECT
  ID = ACMETelephonyProductsVendorData
  CLASSID = "UUID:B83E8318-336C-11D3-8657-0090272F9EEB"
  PARAM NAME = "Add" VALUE = "ACMEDatabaseName">
</OBJECT>

The syntax for creating a COM object in an ASP page is similar to that used in the embedding example above. You must first create an instance of that object by using the OBJECT tag as shown in the following example.

Note that the WTE object must run on the server in order to be used by ASP but, by default, the OBJECT tag creates an instance of the object on the client. Setting the RUNAT attribute to SERVER causes the object to be created on the server.

<OBJECT
RUNAT=SERVER
ID = ACMETelephonyProductsVendorData
  CLASSID = "UUID:B83E8318-336C-11D3-8657-0090272F9EEB"
  PARAM NAME = "Add" VALUE = "ACMEDatabaseName">
</OBJECT>

You can also create an instance of a COM object on an ASP page by calling the CreateObject method of the ASP Server object. Using Server.CreateObject is slower than creating the object using an OBJECT tag, but you do not have to provide a CLASSID. The Server object itself is exposed by ASP and does not need to be created. The following VBScript example shows how to add a new WTEVendorDataSet object, called ACMEIncomingLine to the existing collection of ACMETelephonyProductsVendorData objects, by calling Server.CreateObject.

<%
  Set ACMEIncomingLine = Server.CreateObject("ACMETelephonyProductsVendorData.Add")
%>

ASP allows you to work with many different types of scripting engines, each of which supports a different scripting language. VBScript and JScript scripting engines are provided with ASP, but you can also plug in scripting engines developed by other companies to support languages such as PerlScript, PScript, Python, and others.

If you do not explicitly set the scripting language for an ASP page, the default is VBScript. To specify a scripting language other than VBScript, include a line such as the following at the top of each ASP page.

<%@ LANGUAGE=PerlScript %>

Because calling the CreateObject method takes more time than using the OBJECT tag, you should use the OBJECT tag in applications where performance is critical.

Once you have created an instance of the COM object, you can access its methods and properties in scripts. The following VBScript example sets the Value property for the vendor data object created in the preceding example:

<% ACMEIncomingLine.Value = 18005551212 %>

For more information about using COM objects in Web applications, including examples in other scripting languages, see Scripting with COM Objects.


Using Enumerated Types in Scripts

Unlike Visual Basic or Microsoft Visual C++®, scripting languages, such as VBScript or JScript, do not support the use of enumeration constants. For the convenience of script authors, the Platform SDK provides a pair of script files that contain definitions of constants used with various properties of Web telephony engine objects.

MswteEnum.vbs contains constant definitions used with VBScript while MswteEnum.js contains the same definitions for use with JScript. Copy the declarations you need from these files and paste them into your scripts.


Using the Web Telephony Log

The Web Telephony Engine (WTE) service maintains a log where it records events that occur while it runs applications. This section describes the log and explains how to set configuration parameters for logging. For information about specific topics, see the following sections:

  • Introduction to Web Telephony Logging
  • Setting Configuration Parameters for Logging
  • Selecting Logging Events for an Application
  • Entering Log Data from an Application
  • Sample Log File
  • The Developer Log
  • WTE Performance Counters


Introduction to Web Telephony Logging

Logging information is useful in the development of WTE applications and in monitoring the functions of WTE applications. In addition, logging information is useful for accounting, billing, and reporting purposes.

When you are developing a new WTE application, you will find that any significant authoring error causes the application to terminate. For example, an application terminates if it specifies a wave file or HTML page that the WTE cannot find. Checking the log after the application terminates can help you learn why the application disconnected the call unexpectedly. For this reason, you should enable most or all of the WTE logging capabilities while you are developing a new WTE application.

Another use of the log file is to monitor how callers use a deployed WTE application. You can check in the logs for things such as:

  • Length of time users stay connected.
  • Selections from menus that users choose.
  • Places in the application where errors occur.
  • Places in the application were users often hang up.
  • Results returned by speech recognition (SR). You can compare these results to the caller's actual spoken utterances, which you can also capture in the log.

You can even log each Dual Tone Multi-Frequency (DTMF) digit that a caller enters, and each menu selection by a caller in a running WTE application. This can give you a detailed understanding of how callers interact with your application.


Setting Configuration Parameters for Logging

The WTE maintains a set of configuration parameters that control the logging behavior of all WTE applications in an array. The configuration parameters determine the name, format, and location of the log file, the frequency with which new log files are created, and the fields that get written to the log.

There are two ways to set the configuration parameters for WTE logging. An administrator can view and set the logging configuration parameters through the user interface (UI) provided by the WTE administration tool (see the documentation for the WTE administration tool). A third-party developer can access the configuration parameters programmatically through the WTELog object of the WTE administration object model. For more information about the administration object model, see Programming Administration and Configuration Tasks.

This section describes the configuration parameters for WTE logging. For information about specific topics, see:

  • Selecting the Type of Logging
  • Selecting the Log Fields


Selecting the Type of Logging

The WTE can write logging information to either a file or an ODBC database. The following topics explain the requirements for file and database logging, and describe the configuration parameters for each type of logging:

  • Writing Log Information to a File
  • Writing Log Information to a Database


Writing Log Information to a File

When file logging is selected, WTE creates the log file in shared-read mode, permitting the file to be read at all times. The configuration parameters for logging must specify a valid log-file directory if logging is to work. The log data is flushed to the file when the internal buffer is full, or every 30 seconds, whichever comes first. The log data is also flushed automatically after an authoring error occurs. To flush the log data to the file programmatically, pass the wteServiceFlushLog service-control value to the Microsoft® Win32® ControlService function. The wteServiceFlushLog service-control value is one of the enumerated values in PrivateWTEControlsType, defined in mswteenum.h.

To select file logging through the WTE administration object model, set the WTELog.LogType property to wteLogToFile.

When file logging is selected, the following parameters must also be specified:

Log File Directory
The directory under which the log files will be created. To specify the directory programmatically, use the WTELog.LogFileDirectory and WTELog.LogFileDirectoryType properties.
Log File Period
The period after which a new log file will be created. To specify the log period programmatically, use the WTELog.LogFilePeriod property.

The possible log file periods are:

Daily
A new file is created every day at midnight. The file name consists of the letters "WTE" followed by the date and the extension "log"; for example:
WTED19991231.log
Weekly
A new file is created every week. The file name consists of the letters "WTEW" followed by the year, month and week of the month; for example:
WTEW1999125.log
Monthly
A new file is created every month. The file name consists of the letters "WTEM" followed by the year and month; for example:
WTEM199912.log
Yearly
A new file is created every year. The file name consists of the letters "WTEY" followed by the year; for example:
WTEY1999.log
Log Files Compress
Windows NT®/Windows® 2000 permits the use of compressed files on NTFS file system partitions. Selecting this property will cause all new files to be generated as compressed files. If the compression fails, because the file system is not NTFS or for some other reason, the files are created as ordinary files without compression. To specify log-file compression programmatically, use the WTELog.LogFilesCompress property.


Writing Log Information to a Database

When database logging is selected, a database must exist and be installed as an ODBC database. The configuration must hold the database source name (DSN) and table name for that database if the logging is to work.

To select database logging through the WTE administration object model, set the WTELog.LogType property to wteLogToSql.

The following parameters determine the logging configuration when logging on to an ODBC database:

Database Source Name
The DSN is the name of the ODBC database source as installed on the computer. To specify the database source programmatically, use the WTELog.LogSqlDataSource property.
Table Name
The table name is the name of the table to which WTE writes the log. To specify the table name programmatically, use the WTELog.LogSqlTableName property.

Microsoft supplies two log databases that are ready to use with WTE, one for Access 97 and the other with Access 2000. These databases are located in the \Samples\odbc\access directory of the Platform SDK. You can import either of these databases into the SQL server.


Selecting the Log Fields

The log produced by WTE consists of a list of line entries. Each line entry is written to the log as a result of a certain event (for example, a new call starts). For a list of events and the procedure for selecting the events to be logged, see Selecting Logging Events for an Application.

Each line entry in the log consists of many fields, each containing a unique piece of information. Because you might not want to log all the fields, the WTE lets you choose the fields to log and those to ignore. Unselected fields appear in the log as a dash ("-"). All fields can be unselected or selected, except for the "Date and Time" field when logging to ODBC, which is always logged.

To select logging fields through the WTE administration object model, use the WTELog.LogFieldSelection property.

This topic discusses the log fields by the order in which they appear in a line entry in the log. If you are using a private database for WTE logging, be sure to use the following field names for the columns, but without any spaces between the words.

Session ID
A unique identifier (ID) for each session. Every call handled by WTE is assigned a new session ID. The WTE assigns session IDs in ascending order. Every log that concerns this call will have its session ID logged in this field. The identifier is a 15-digit number; for example:
001255769230291
Log Time
The date and time of the logging. The format is Date, Hour:Minute:Second; for example:
12/9/1999 17:51:51
Event Class
A description of the event that caused the logging; for example:
Call Available
Machine Name
The name of the machine running the WTE; for example:
WteTEL6
Address Group
In this release, WTE does not use this field. In the next version, this field will give the name of the address group, if the address belongs to an address group. This field applies only if DNIS is supported.
Address
The address through which the call is connected. This address is usually a phone number; for example, 5551212
Caller ID
The identifier of the caller party. This ID is usually a phone number; for example, 5551212
Called ID
The identifier of the called party. This ID is usually a phone number; for example, 5551212. This field applies only if DNIS is supported.
Reason
The reason the call was transferred to the WTE, usually for voice-mail purposes; for example, "Busy On Forward".
Application Name
The name of the WTE application connected to this call; for example, "Test".
Media
The media mode of the call; for example, "Automated Voice".
Page
The page that the application is currently using; for example, "http://wtel2/demo/demointroduction.htm"
DTMF Value
The value of the DTMF digit received; for example, "5".
Dest Address
The address to which the call is transferred; for example, 1111.
Hang Reason
The reason the call was disconnected; for example, "Disconnected - Rendering Error".
Transfer Type
The type of call transfer; for example, "BlindTransfer" or "SupervisedTransfer".
Error Type
When a log is written due to an authoring error, this field holds the error type; for example, "Error opening the requested URL".
Input Record File
Some events cause recorded audio (.wav) files to be saved. This field contains the recorded file names; for example, "C:\Program Files\Log\Recordings\IS001255769230291.log
Custom
Your WTE application can set this field through the extended object model (ExOM). For more information, see Setting the Custom Log Field.


Selecting Logging Events for an Application

The WTE supports a set of events. For each application, some or all of the events can be selected. Whenever a new call comes in on a line, the WTE reads the event-selection mask for the application associated with the line. When a selected event occurs, the WTE writes a line entry in the log. The Event Class field of the line entry identifies the event, and the Application Name field identifies the application associated with the event. WTE ignores all unselected events for an application.

To select the events for an application, use the Log page of the property sheet for the application. The property sheet is accessible through the WTE administration tool. You can select events programmatically by using the WTEApplication.LogEventSelection property of the WTE extended object.

The following topics provide a list of the events that can be selected for any given application, and describe the types of errors that can cause certain events to occur. For information about specific topics, see:

  • Logging Events
  • Authoring Errors
  • Initialization Errors
  • Run-Time Errors
  • Logging Of Voice Files


Logging Events

WTE logging is performed as a result of various events occurring in an application. Following is a list of events that can generate a log entry.

Authoring Error
An error in the WTE application generates this event. The error is explained in the Error Type field of the log.
Call Available
A call is available for WTE. Affected log fields: Caller ID, Called ID, Reason, Application Name, Media, Page.
Session Connection
A WTE application successfully connected to the call.
Navigate
A jump (navigation) occurred in the application. Affected log fields: Page.
Call Transfer
The call was transferred. Affected log fields: Destination Address, Transfer Type.
Call Hung Up
The call disconnected. Affected log fields: Hang Reason.
Session Ending
The session is ending. If a post-call page is defined, this event can occur long after the call disconnects.
Caller Time-out
A time-out event occurred while waiting for input from the caller. For more information, see Handling Time-outs and Non-valid Keys.
Call Information Changed
The call's TAPI information changed. Affected log fields: Caller ID, Called ID, Reason, Application Name, Media.
DTMF Input Error
A non-valid DTMF digit was received. For example, the user pressed a non-valid key. Affected log fields: DTMF Value.
No Application
A call was received on an address where the Called ID field has no application. This event cannot be configured from the WTE administration tool.
Custom Log
This event is generated by the ExOM. Your WTE application can call this event. Affected log fields: Custom Log.
DTMF Received
A DTMF digit was received by the application. Affected log fields: DTMF Value.
Speech Input Data
Speech input data was received by the application. Speech input data is spoken by the caller and processed by an SR engine. This event causes an audio (.wav) file to be saved. Affected log fields: Input Record File.
Speech Input Failure
Speech input was not recognized by the SR engine. The speech input is recorded to an audio (.wav) file. Affected log fields: Input Record File.
Recording
The caller is recording a message. The recorded audio (.wav) file is saved for logging. Affected log fields: Input Record File.
Record Failure
An attempt to record a message from the caller failed. Affected log fields: Input Record File.
Line Opened
The WTE service was started or an address that wasn't previously associated with any application is added. Also occurs when the call processing mechanism switched instances.


Authoring Errors

When an application fails because of an error in coding, the log records this as an Authoring Error event. The Error Type field in the log file contains more specific information that details the cause of the event. The Error Type field can contain one of the following messages:

  • File %S not found.
  • File %S corrupted.
  • Trying to set a read-only property.
  • Wrong call type in method.
  • Wrong number of parameters in method.
  • Wrong format of file %S.
  • Scopes in the page are not valid.
  • Illegal scopes in the page: tag %S (Index=%d) was closed before tag %S (Index=%d).
  • Illegal scopes in the page are not valid.
  • Error opening the requested URL.
  • Tried to play a voice file on address that lacks audio support.
  • Tried to record a voice file on address that lacks audio support.
  • Tried to gather DTMF on an address that lacks detection support.
  • Failed to load TTS engine.
  • Volume control is not supported on the TTS engine.
  • Speech control is not supported on the TTS engine.
  • Pitch control is not supported on the TTS engine.
  • Threshold control is not supported on the SR engine.
  • Failed to load SR engine.
  • A message box invoked.
  • Error 0x%8x encountered.
  • Too many menu items.
  • Access key is not valid.
  • Breaking the menu because of change in cut-through mode.
  • Cannot call External after Abandon().
  • Cannot call ITBasicCallControl property after drop.
  • Illegal value %S set on attribute %S.
  • No element with ID %S in table.
  • First element with ID %S in table is not a cell.
  • The frameset at %S is empty.
  • Calling from a wrong thread.
  • Ignores delay answering on a handed-off (answered) call.
  • Warning: Gathering text input with an empty termination string and no maximum length.
  • Warning: Offering multiple selection menu with an empty termination string.
  • Unknown property request: %S.
  • Script error: %S in %S line %D.
  • Could not finish transfer.
  • Abandoning the session because a script error occurred while the application was answering a call, or while WTE was processing the application's post-call page.
  • Failed to send data.
  • Terminal failure occurred.
  • Stream failure occurred.
  • Failed to process data.
  • Binding failure occurred.
  • Failed to write data.
  • Warning: Frameset as a scriptlet is not supported. Ignoring.
  • Trying to open a non-HTML document.
  • Protocol %s is not supported.
  • Abandoning the session because of a script error in delayed-answering or post-call page mode.
  • Grammar compilation failed. %S.
  • Grammar load failed.
  • Warning: A tag with the name %S appears before the body. Cannot start on this hash, starting from the body.
  • Warning: Access key %S on tag %S (Index=%d) will be ignored because the length of the WTEApplication.InitialAutoNumber property is greater then 1.
  • Warning: Access key %S on tag %S (Index=%d) is longer then 1 character. Only the first character on the access key is taken into account.
  • Grammar file %S is not in UNICODE format.
  • Frame is in a different security zone from that of its parent frame.


Initialization Errors

If the logging service fails to initialize, WTE does not start. The cause of such a failure is usually a problem in the log configuration. The event log holds an event under the Application Name field with WTE as the source, detailing the error.

The two most common errors are:

  • Log file directory does not exist.

Solution: Change the Log File Directory configuration property to point to an existing directory.

  • Error opening ODBC database.

Solution A: Ensure that the DSN is installed on the machine.

  1. Click Start, point to Programs, Administrative Tools, and then select Data Sources (ODBC).
  2. From the User DSN, click Add, select your data source, and then click Finish.
  3. On the setup dialog box, enter the name and description of your DNS, and then press select to choose the database.

Solution B: Check the table to be sure that the column headings are correct. They should be exactly the same as the log field names, except with no spaces between words. For example, if the log field name is "Transfer Type", the column heading should be "TransferType".


Run-Time Errors

Run-time errors cause the logging to fail. However, WTE will continue to work properly. Run-time failures also cause WTE to write line entries to the event viewer.


Logging Of Voice Files

Four logging events involve voice input. They are:

  • Speech Input Data
  • Speech Input Failed
  • Record Data
  • Record Failed

For these events, WTE saves the voice recordings in wave files. The files are saved in a subdirectory, named Recordings, of the log files directory. Each of these wave files has a unique name. When a wave file is saved in this directory (due to one of the events), a line entry is written to the log. The Input Record File field contains the name of the corresponding wave file.


Entering Log Data from an Application

You can use scripts in your WTE applications to set the contents of the custom log field and to enter records into the WTE log. For information about specific subjects, see the following sections:

  • Setting the Custom Log Field
  • Entering a Record into the Log


Setting the Custom Log Field

Each line entry in the log file includes the Custom Log field. This field is empty at the beginning of each call, but an application's scripts and Microsoft ActiveX® controls can set the contents of the field during the call. The Custom Log field consists of a default value and any number of name/value pairs. WTE supports multiple pairs in case several components need to use the Custom Log field simultaneously.

The syntax of the Custom Log field is as follows:

    <DefaultValue>;<Name1=Value1>;<Name2=Value2>&ldots;

By default, the Custom Log field is empty. To set the Custom Log field, an application must first use the LogCustomField property of the ExOM object to obtain an instance of the LogCustomField object. The application can then use the DefaultValue and Value properties of the LogCustomField object to set the contents of the Custom Log field. For example:

    <script LANGUAGE="VBScript">
    DIM objCustomLog
    Set objCustomLog = External.LogCustomField
    objCustomLog.DefaultValue="Step 1 completed"
    objCustomLog("callerID")="007"
        .
        .
        .
    </script>

WTE stores the Custom Log field strings internally, and constructs and adds the complete field to each subsequent line entry in the log. For instance, the script in the preceding example would cause the Custom Log field of all subsequent line entries to contain the following string:

    Step 1 completed;callerID=007

You can clear the default value or a named value by setting the value to an empty string.

Note that setting the DefaultValue or Value property does not cause a new line to be written to the log. To write a new line, use the External.Log method.


Entering a Record into the Log

The scripts and ActiveX controls of an application can use the Log method of the ExOM object to write a line entry into the log file or SQL database. The method produces a line entry containing the words "Custom Log" in the Event Class field. Note that the Log method does not take any parameters, meaning it cannot set the contents of any fields in the line entry. However, you can set the contents of the line entry's Custom Log field by using the LogCustomField object.

The following example shows the syntax of the Log method:

External.Log


Sample Log File

The following example shows the contents of a sample log file.

001255769230291, 12/9/98, 17:51:51, Call Available, WebTEL6, - , 490, - , - , Unavailable, Test, Automated Voice, http://webtel2/demo/demointroduction.htm, - , - , - , - , - , - , - , -
001255769230291, 12/9/98, 17:51:53, Session Connect, WebTEL6, - , 490, - , - , Unavailable, Test, Automated Voice, http://webtel2/demo/demointroduction.htm, - , - , - , - , - , - , - , -
001255769230291, 12/9/98, 17:52:02, Navigate, WebTEL6, - , 490, - , - , Unavailable, Test, Automated Voice, http://WebTE2iis/webtel2/Transfer.htm, - , - , - , - , - , - , - , -
001255769230291, 12/9/98, 17:52:18, Call Disconnect, WebTEL6, - , 490, - , - , Unavailable, Test, Automated Voice, http://webtel2/demo/Transfer.htm, - , - , - , Disconnected - Rendering Complete, - , - , - , -
001255769230291, 12/9/98, 17:52:19, Navigate, WebTEL6, - , 490, - , - , Unavailable, Test, Automated Voice, res://mswtesrv.exe/abandon.htm, - , - , - , - , - , - , - , -
001255769230291, 12/9/98, 17:52:19, Session Termination, WebTEL6, - , 490, - , - , Unavailable, Test, Automated Voice, res://mswtesrv.exe/abandon.htm, - , - , - , - , - , - , - , -
001255769230292, 12/9/98, 17:52:25, Call Available, WebTEL6, - , 490, - , - , Unavailable, Test, Automated Voice, http://webtel2/demo/demointroduction.htm, - , - , - , - , - , - , - , -
001255769230292, 12/9/98, 17:52:25, Session Connect, WebTEL6, - , 490, - , - , Unavailable, Test, Automated Voice, http://webtel2/demo/demointroduction.htm, - , - , - , - , - , - , - , -
001255769230292, 12/9/98, 17:52:28, Navigate, WebTEL6, - , 490, - , - , Unavailable, Test, Automated Voice, http://webtel2/demo/Transfer.htm, - , - , - , - , - , - , - , -


The Developer Log

You can choose to have WTE generate an additional log, called the developer log, which provides details about WTE events beyond those available from the WTE logging file. For example, the developer log tracks every event connected with the WTEActiveConnection debugging object. Other activities recorded in this log include:

  • Calls answered by WTE.
  • Any tag parsed by WTE.
  • Audio-items gathered by WTE.
  • Menus rendered.
  • DTMFs detected and used.
  • Any session variables that were edited and saved.

Each line in the developer log file has its session name as a prefix. Each session name is guaranteed to be unique on a particular server. Although events relating to two or more concurrent sessions may be interleaved in the log, you can identify the call associated with any event.

To enable developer logging on your WTE server, edit the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\
mswtesrv\Parameters\DevLogFile

Set the string value for this entry to the path and file name for the developer log (for example, "D:\WTElogs\SalesServer.log"). When WTE starts running, it checks for the DevLogFile registry key and, if it exists, automatically creates the specified developer log file.


WTE Performance Counters

WTE makes available several performance counters to monitor activity on your WTE server. These performance counters are defined in the system32 file WTEPERF.ini and are installed during WTE setup.

Name | Type | Description
Web Telephony Engine | Object | Web Telephony Engine server performance data
Addresses Serviced | Counter | The number of addresses serviced.
Active Sessions | Integer | The number of currently active sessions.
Average Session Duration | Integer | The average duration (in milliseconds) of all active sessions.
Maximum session duration | Counter | The maximum duration (in milliseconds) of a session since startup.
Offered Calls | Counter | The number of calls offered to Web Telephony Engine.
Average Offering Duration | Integer | The average duration (in milliseconds) of all calls currently in offering state.
Maximum Offering Duration | Counter | The maximum duration (in milliseconds) of offering state for all calls since startup.
Active Calls | Integer | The number of currently active calls.
Average Call Duration | Integer | The average duration (in milliseconds) of all currently active calls.
Maximum Call Duration | Counter | The maximum duration (in milliseconds) of all calls since startup.
Sessions In Post Call Page | Integer | The number of sessions in post call page.
Average Post Call Page Duration | Counter | Average duration (in milliseconds) of sessions in post call page.
Maximum Post Call Page Duration | Counter | The maximum duration (in milliseconds) of all sessions in post call page since startup.
Maximum Simultaneous Calls | Counter | The maximum number of simultaneous calls since startup.
Total Calls | Counter | Total calls handled by Web Telephony Engine since startup.

You can access the data in the performance counters in several ways, including:

  • Through the registry key HKEY_PEFORMANCE_DATA. Note that the data is not stored in the registry database. You must use the registry function RegQueryValueEx, with a handle to the HKEY_PEFORMANCE_DATA key to query WTE for the performance data.
  • Through the Win32 function PdhGetCounterInfo and other performance data handling functions. For a complete listing of this function library, see Performance Monitoring Functions.

For more information on using Performance Counters, see Performance Monitoring.


Developing a Debugging Application

The Web Telephony Engine (WTE) includes a debugging extension that allows third-party developers to create client applications that can trace and debug WTE applications. The debugging extension exposes the basic behavior and call flow of the WTE, allowing a debugging client application to implement sophisticated debugging features. For example, a client debugging application can check which HTML elements the WTE processes, examine configuration parameters, stop execution on a particular HTML element, and so on.

The debugging extension is available only when the WTE service is running in debugging mode and is not accessible from within a WTE application. It is intended to be used only to create debugging client applications.

For detailed information, see the following section Starting a Debugging Application.


Starting a Debugging Application

Starting a debugging application involves the following steps:

  • Creating the Web Telephony Engine Service
  • Getting the Active Connection
  • Connecting to Events


Creating the Web Telephony Engine Service

To start the WTE service in debug-extension mode, a debug application must call the CoCreateInstance function with the class identifier (CLSID) CLSID_WTEService, and context value CLSCTX_LOCAL_SERVER. The CoCreateInstance function starts the WTE service.

If the WTE service was already started using a previous call to CoCreateInstance, another pointer to the same WTEApplication object is returned.

The pointer returned from the call to CoCreateInstance is a pointer to an IWTEApplication interface.

If the WTE service was already started in a normal working mode, the CoCreateInstance call fails.


Getting the Active Connection

In normal mode, when the WTE service starts, it opens all the lines that are connected to an application. In debug-extension mode, the WTE service does not open any lines when starting. That is, it does not answer any of its applications.

To activate an application when in debug extension mode, call the GetActiveConnection function, specifying the application name. GetActiveConnection returns the WTEActiveConnection object.

The GetActiveConnection function can be called any number of times on each application, regardless of the number of lines connected to the application. A different WTEActiveConnection object is created on every call. Only one ActiveConnection object handles each incoming call, in random order.


Connecting to Events

After a pointer to a WTEActiveConnection object is received, it is possible to connect to the object's events. Connect in the regular COM way, to the DIID_IWTEConnectionEvents connection point. The events are fired to the pointer passed to the Advise method.

It is possible to connect to the connection point of each active application any number of times.


Web Telephony Engine Reference

This section contains reference pages for the following Microsoft® Web Telephony Engine (WTE) API objects and other WTE application programming components:

  • Objects
  • Debugging Objects
  • Error Codes
  • Enumerated Types
  • Events
  • HTML Elements and Attributes
  • CSS Properties


Objects

This section descibes the following objects, and their properties and methods:

  • ExOM Object
  • LogCustomField Object
  • Session Object
  • SRMode Object
  • TTSMode Object
  • WTE Object
  • WTEAddress Object
  • WTEAddresses Collection
  • WTEAddressGroup Object
  • WTEAddressGroups Collection
  • WTEApplication Object
  • WTEApplications Collection
  • WTEArray Object
  • WTEArrays Collection
  • WTEDNIS Object
  • WTEDNISes Collection
  • WTELog Object
  • WTEServer Object
  • WTEServers Collection
  • WTESRModes Collection
  • WTETTSModes Collection
  • WTEVendorDataSet Object
  • WTEVendorDataSets Collection

The reference pages for these objects show Microsoft Visual Basic® syntax; however, you can program to these objects in any language that supports COM. For detailed information on translating Visual Basic syntax into other languages, such as C++ and VBScript, see COM Language Translations.


ExOM Object

Description

WTE provides an extension to the Internet Explorer Object Model called the extended object model (ExOM). The purpose of this extension is to allow the author to dynamically change the application configuration, store and retrieve variables between pages, and gain access to the current Telephony Application Programming Interface (TAPI) Call object. In addition, the ExOM allows the author to control the operation of the Web telephony session that is handling the call.

An application accesses the extended object model by using a predefined instance of the ExOM object called the External object. The ExOM is accessible from Microsoft Visual Basic Scripting Edition (VBScript), JScript®, or ActiveX® controls.

Methods

Abandon, Log

Properties

AlternativePhrases, Configuration, Event, hostName, ITBasicCallControl, LogCustomField, Session, SRMode, TTSMode

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


ExOM.Abandon Method

The Abandon method causes WTE to disconnect the call, end the session, destroy the Session object, and free all other resources allocated for the call.

Syntax

ExOM.Abandon()

Example

Following is an example:

External.Abandon

Remarks

For more information about calls and sessions, see Handling a Call.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ExOM, Session


ExOM.AlternativePhrases Property

The AlternativePhrases property retrieves the alternative phrases from the speech-recognition (SR) engine.

Syntax

[ vPhrases = ] ExOM.AlternativePhrases

Possible Values

vPhrases
String specifying the alternative phrases.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ExOM


ExOM.Configuration Property

The Configuration property retrieves a WTEApplication object used to view and change the application's properties.

Syntax

[ oWTEApplication = ] ExOM.Configuration

Possible Values

oWTEApplication
Reference to the WTEApplication object.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ExOM, WTEApplication


ExOM.Event Property

The Event property retrieves the Event object, which represents the state of an event.

Syntax

[ oEvent = ] ExOM.Event

Possible Values

oEvent
Reference to the Event object.

This property is read-only.

Example

The following example cancels the behavior of the default error handler:

<script For=MenuOwner Event=OnSelectionError>
     External.Event.returnValue = False
</script>

Remarks

The Event object is available only during an event; that is, you can use it in event handlers but not in other code. Although all event properties are available to all event objects, some properties might not have meaningful values during some events.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ExOM


ExOM.hostName Property

The hostName property retrieves the name of the component that is currently hosting the Web telephony application. When WTE is hosting the application, the value of this property is "Microsoft Web Telephony Engine."

Syntax

[ sName = ] ExOM.hostName

Possible Values

sName
String specifying the host name.

This property is read-only.

Example

Following is an example:

On Error Resume Next

If External.hostName = "Microsoft Web Telephony Engine " Then
  ...
End If

Remarks

You can use this property in a dual-access Web telephony application to determine whether the application is running under WTE or under a graphical Web browser such as Microsoft Internet Explorer.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ExOM


ExOM.ITBasicCallControl Property

The ITBasicCallControl property exposes the TAPI 3.0 ITBasicCallControl object associated with the current call.

Syntax

[ oTBasicCallControl = ] ExOM.ITBasicCallControl

Possible Values

oTBasicCallControl
Reference to the ITBasicCallControl object.

This property is read-only.

Remarks

You can use the ITBasicCallControl object for basic call-control operations such as disconnect, hold, and transfer. You can also use it to reach other TAPI 3.0 objects. For more information, see TAPI version 3.0 documentation.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ExOM


ExOM.Log Method

The Log method allows scripts and Microsoft ActiveX® controls to submit entries to the Web telephony log.

Syntax

Log()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ExOM


ExOM.LogCustomField Property

The LogCustomField property retrieves an object used to configure the log custom field.

Syntax

[ oLogCustomField = ] ExOM.LogCustomField

Possible Values

oLogCustomField
Reference to that LogCustomField object.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ExOM, LogCustomField


ExOM.Session Property

The Session property retrieves the Session object.

Syntax

[ oSession = ] ExOM.Session

Possible Values

oSession
Reference to the Session object.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ExOM, Session


ExOM.SRMode Property

The SRMode property retrieves the SRMode object associated with this call. This object provides read-only access to the properties of the SR engine.

Syntax

[ oSRMode = ] ExOM.SRMode

Possible Values

oSRMode
Reference to the SRMode object.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ExOM, SRMode


ExOM.TTSMode Property

The TTSMode property retrieves the TTSMode object associated with this call. This object provides read-only access to the properties of the TTS engine.

Syntax

[ oTTSMode = ] ExOM.TTSMode

Possible Values

oTTSMode
Reference to the TTSMode object.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ExOM, TTSMode


LogCustomField Object

Description

A LogCustomField object represents the log custom field, which is a special field in each line entry of the Web telephony log. A Web telephony application can use this object to set the contents of the log custom field. For more information, see Setting the Custom Log Field.

Properties

DefaultValue, Value

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


LogCustomField.DefaultValue Property

The DefaultValue property sets the default value of the custom log field.

Syntax

LogCustomField.DefaultValue [ = sVal ]

Possible Values

sVal
String specifying the new default value.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

LogCustomField


LogCustomField.Value Property

TheValue property sets a name-value pair in the log custom field.

Syntax

LogCustomField.Value = sName, sVal

Possible Values

sName
String specifying the name of the field to set.
sVal
New value for the given field. If the new value is NULL, the name-value pair is erased from the log custom field.

Remarks

Setting the same name with a different value changes only the value in the custom log field and does not add another pair.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

LogCustomField


Session Object

Description

A Session object can be used by an application to store variables and objects. The scope of the stored objects and variables is the entire session; that is, until the session terminates. No information is retained between sessions.

The session table supports strings, numbers, and objects. In the case of objects, you must use "Set" to retrieve the object, or call the methods directly. This is a read-write property, although it is actually implemented as a collection.

WTE follows COM concepts of handling object interfaces; that is, reference counting. For example, the engine calls the AddRef method to increment the reference count before returning any interface. Before exiting, the engine clears the table and releases all object interfaces.

Web telephony suggests the model of a client-side session mainly to ease the work of the author. The client-side session allows the author to keep client-side objects that are used in the telephony application. Unlike regular Internet Explorer objects, where objects live only in one page, these objects have a wider scope, up to the entire session. These objects can be TAPI objects, MAPI objects, and other objects that run in the Internet Explorer client side (inside Web telephony). The author can also use the session object to keep track of the call, the pages the caller visited, the variables changed by the application at run time, and more. Note that there are no security problems associated with the Session object because the caller cannot browse through arbitrary sites on the Internet.

Properties

LastVisitedPage, LastVisitedTagID, ServerName, SessionName, SessionState, Value

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


Session.LastVisitedPage Property

The LastVisitedPage property retrieves the last-visited URL, which is the URL of the page before the navigation to the current page.

Syntax

[ sURL = ] Session.LastVisitedPage

Possible Values

sURL
String specifying the last-visited URL.

This property is read-only.

Remarks

The URL returned by this property is not necessarily the same URL to which Internet Explorer navigates when executing "history.back 1". This is because when navigating backward, the last visited URL is the URL accessed through "history.forward 1".

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

Session


Session.LastVisitedTagID Property

The LastVisitedTagID property retrieves the identifier (ID) of the element within which the last navigation was initiated.

Syntax

[ sID = ] Session.LastVisitedTagID

Possible Values

sID
String specifying the ID.

This property is read-only.

Remarks

If the navigation occurred in an element without an ID, the IDs of parent elements are retrieved until an element with ID is found or WTE reaches the start of the page. Note that the beginning of the HTML element hierarchy is the BODY element.

This parameter can be combined with the Session.LastVisitedPage property to compose a "unique" URL. The syntax of the last-visited element ID is as follows:

SPreviousID = External.Session.LastVisitedID

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

Session


Session.ServerName Property

The ServerName property retrieves a unique computer ID, which is the computer name, or the cluster name in a cluster.

Syntax

[ sName = ] Session.ServerName

Possible Values

sName
String specifying the computer or cluster name.

This property is read-only.

Remarks

The syntax of the computer name is as follows:

Machine = External.Session.ServerName

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

Session


Session.SessionName Property

The SessionName property retrieves a unique per-computer session ID.

Syntax

[ sID = ] Session.SessionName

Possible Values

sID
String specifying the session ID.

This property is read-only.

Remarks

WTE has a unique counter per machine which is used, among other things, to stamp each session log event. You should not allocate a globally unique identifier (GUID) because the counter allows sorting according to this value. The author can compose a globally unique session ID from the ServerName and SessionName properties.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

Session


Session.SessionState Property

The SessionState property retrieves the state of the current call.

Syntax

[ sState = ] Session.SessionState

Possible Values

sState
String specifying the state. Possible values of this string include:
"Answer Pending" (offering)
The call was offered to an application, but the application has not yet answered.
"Connected"
The call was connected.
"Disconnected"
The call was disconnected.
"Call Transferred"
The call was transferred as a result of the caller pressing the operator key.
"Disconnected - Rendering Error"
A rendering error caused the call to be disconnected.
"Disconnected - Recurring Error"
A recurring error on the part of the caller caused the call to be disconnected.
"Disconnected - Rendering Complete"
The call disconnected because WTE finished rendered all HTML pages of the application.

This property is read-only.

Remarks

The last four values are possible only while WTE is processing the post-call page of the application.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

Session


Session.Value Property

The Value property sets or retrieves the default property for the session. This property uses a name-value map to store all sorts of variables on the Internet Explorer side.

Syntax

Session.Value [ = vValue ]

Possible Values

vValue
Variant specifying the value of the session's default property. For example:
External.Session ("UserName") = "Mr. Smith"
UserName = External.Session ("UserName")
Set MySession = External.Session
Set MySession ("MapiSession") = CreateObject ("mapi.session")
Set MySession = External.Session ("MapiSession")
External.Session ("MapiSession").Logon

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

Session


SRMode Object

Description

An SRMode object provides information about the currently selected speech-recognition (SR) engine. All properties are read-only.

Properties

Dialect, EngineFeatures, EngineID, Features, Grammars, Interfaces, LanguageID, MaxWordsState, MaxWordsVocab, MfgName, ModeID, ModeName, ProductName, Sequencing

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


SRMode.Dialect Property

The Dialect property retrieves the name of the dialect specific to the language. For example, "Texas" or "New York City."

Syntax

[ sName = ] SRMode.Dialect

Possible Values

sName
String specifying the name of the dialect.

This property is read-only.

Remarks

Dialect strings can be anything. This member can be "Standard" (or its localized equivalent) for the dialect used by news media.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode


SRMode.EngineFeatures Property

The EngineFeatures property retrieves the features that are specific to the engine. These values are defined by the engine author.

Syntax

[ lFeatures = ] SRMode.EngineFeatures

Possible Values

lFeatures
Integer specifying the features.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode


SRMode.EngineID Property

The EngineID property retrieves the GUID that uniquely identifies the SR engine.

Syntax

[ sGUID = ] SRMode.EngineID

Possible Values

sGUID
String containing the GUID of the SR engine.

This property is read-only.

Remarks

It is possible for more than one mode to have the same engine ID. In this case, the engine is capable of recognizing the different languages or voices of the modes.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode


SRMode.Features Property

The Features property retrieves a set of flags that indicate the available SR features.

Syntax

[ lFeatures = ] SRMode.Features

Possible Values

lFeatures
Integer containing the set of feature flags, which can be a combination of these values:
SRFEATURE_ANYWORD
The engine can attempt to recognize any word.
SRFEATURE_FIXEDAUDIO
The audio source for the device is fixed, so an audio source object is not needed for the SELECT attribute. If an audio source is passed in, it will be ignored. Hardware devices, such as an external recognizer box, will support this.
SRFEATURE_GRAMLINK
The engine supports automatic links between grammars.
SRFEATURE_GRAMLIST
The grammars support recognition lists.
SRFEATURE_GRAMRECURSIVE
The engine accepts recursive, context-free grammars; otherwise, it cannot have recursive grammars.
SRFEATURE_INDEPMICROPHONE
The engine is microphone-independent (indifferent to background noise and a microphone) and does not require retraining if the microphone changes.
SRFEATURE_INDEPSPEAKER
The engine is speaker-independent and works well without training.
SRFEATURE_IPAUNICODE
The engine supports the International Phonetic Alphabet (IPA) in Unicode.
SRFEATURE_IPAWORD
Words can contain IPA pronunciations.
SRFEATURE_MULTILINGUAL
The engine can recognize speech in several languages at one time. This is necessary for systems that run two or more applications written for different languages.
SRFEATURE_PCOPTIMIZED
The voice is optimized to work over the PC.
SRFEATURE_PHONEOPTIMIZED
The voice is designed to work over the telephone and uses an 8-kilohertz (kHz) sampling rate.
SRFEATURE_SAPI4
Denotes that the engine is SAPI 4.0a-compliant. SAPI 4.0a-compliant means that WTE supports all the required interfaces defined in this document and can pass the SRFUNC test included in the SAPI documentation.
SRFEATURE_SINGLEINSTANCE
The engine is single instance, and so only one mode object can exist at one time. TTS engines that are .exe servers use this.
SRFEATURE_THREADSAFE
The engine is completely thread safe, and can be called from any thread.
SRFEATURE_TRAINPHONETIC
The speaker can train the engine on a preselected set of words and thereby train all the phonemes used for recognition. This is done in general training.
SRFEATURE_TRAINWORD
The speaker can train the engine on individual words.
SRFEATURE_WILDCARD
The engine supports wildcard characters in context-free grammars.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode


SRMode.Grammars Property

The Grammars property retrieves the types of grammar supported by the SR engine.

Syntax

[ lTypes = ] SRMode.Grammars

Possible Values

lTypes
Integer specifying the types of grammar supported. It can be a combination of these values:
SRGRAM_CFG
Context-free grammar.
SRGRAM_DICTATION
Dictation grammar.
SRGRAM_LIMITEDDOMAIN
Limited-domain grammar.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode


SRMode.Interfaces Property

The Interfaces property retrieves a set of flags that identify the interfaces supported by the SR engine.

Syntax

[ lFlags = ] SRMode.Interfaces

Possible Values

lFlags
Integer specifying the flags, which can be a combination of these values:
SRI_ILEXPRONOUNCE
ILexPronounce interface
SRI_ISRATTRIBUTES
ISRAttributes interface
SRI_ISRCENTRAL
ISRCentral interface
SRI_ISRDIALOGS
ISRDialogs interface
SRI_ISRGRAMCOMMON
ISRGramCommon interface
SRI_ISRGRAMCFG
ISRGramCFG interface
SRI_ISRGRAMDICTATION
ISRGramDictation interface
SRI_ISRGRAMINSERTIONGUI
ISRGramInsertionGUI interface
SRI_ISRESBASIC
ISRResBasic interface
SRI_ISRESMERGE
ISRResMerge interface
SRI_ISRESAUDIO
ISRResAudio interface
SRI_ISRESCORRECTION
ISRResCorrection interface
SRI_ISRESEVAL
ISRResEval interface
SRI_ISRESGRAPH
ISRResGraph interface
SRI_ISRESMEMORY
ISRResMemory interface
SRI_ISRESMODIFYGUI
ISRResModifyGUI interface
SRI_ISRESSPEAKER
ISRResSpeaker interface
SRI_ISRSPEAKER
ISRSpeaker interface
SRI_ISRESSCORES
ISRResScores interface

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode


SRMode.LanguageID Property

The LanguageID property retrieves a language identifier as specified for the Microsoft Win32® API. Bits 0 through 9 identify the primary language, such as English, French, or Spanish. Bits 10 through 15 identify the sublanguage, which is essentially a locale setting. For example, Portuguese has two sublanguages, Brazilian and Standard.

Syntax

[ lLangID = ] SRMode.LanguageID

Possible Values

lLangID
Integer specifying the language identifier.

This property is read-only.

Remarks

For a list of primary and sublanguage identifiers, see the documentation for the MAKELANGID macro in the Win32 API. Language ID codes are limited to the Win32 definition of LANGID.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode


SRMode.MaxWordsState Property

The MaxWordsState property retrieves the maximum number of words in any state of a grammar.

Syntax

[ lMaxWords = ] SRMode.MaxWordsState

Possible Values

lMaxWords
Integer specifying the maximum number of words.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode


SRMode.MaxWordsVocab Property

The MaxWordsVocab property retrieves the maximum number of words allowed in an active vocabulary at a given time.

Syntax

[ lMaxWords = ] SRMode.MaxWordsVocab

Possible Values

lMaxWords
Integer specifying the maximum number of words.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode


SRMode.MfgName Property

The MfgName property retrieves the name of the manufacturer of the SR engine. For example, "A. Datum Corporation."

Syntax

[ sName = ] SRMode.MfgName

Possible Values

sName
String specifying the name of the manufacturer.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode


SRMode.ModeID Property

The ModelID property retrieves the GUID that uniquely identifies the SR mode. These numbers are guaranteed to be unique, so it is not necessary to monitor and record them. In addition, the GUID is not stored or used directly by the COM run time, so you do not need to load it into the registry.

Syntax

[ sGUID = ] SRMode.ModeID

Possible Values

sGUID
String specifying the GUID of the mode.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode


SRMode.ModeName Property

The ModeName property retrieves the name of the SR mode.

Syntax

[ sName = ] SRMode.ModeName

Possible Values

sName
String specifying the name of the mode.

This property is read-only.

Remarks

SR mode names have the following form:

[Optional Engine Description], Language, [Optional Sampling Rate,] Manufacturer Engine Name [,Optional Version Number]

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode


SRMode.ProductName Property

The ProductName property retrieves the product name of the SR engine. For example, "The Listening Device."

Syntax

[ sProdName = ] SRMode.ProductName

Possible Values

sProdName
String specifying the product name.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode


SRMode.Sequencing Property

The Sequencing property retrieves a value that identifies the SR scheme.

Syntax

[ lScheme = ] SRMode.Sequencing

Possible Values

lScheme
Integer identifying the engine. It can have one of these values:
SRSEQUENCE_CONTINUOUS
Performs continuous recognition. Given a continuous utterance with no pauses between words, the engine can recognize the words that were spoken.
SRSEQUENCE_DISCRETE
Recognizes discrete utterances. Every word must be isolated by a pause before and after the word if the engine is to recognize it.
SRSEQUENCE_WORDSPOT
Performs word spotting. A series of words may be spoken in a continuous utterance, but the engine recognizes only selected words or phrases.
SRSEQUENCE_CONTCFGDISCDICT
Performs continuous recognition for context-free grammars. It also supports discrete dictation.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode


TTSMode Object

Description

A TTSMode object provides information about the currently selected text-to-speech (TTS) engine. All properties are read-only.

Properties

Age, Dialect, EngineFeatures, EngineID, Features, Gender, Interfaces, LanguageID, MfgName, ModeID, ModeName, ProductName, Speaker, Style

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


TTSMode.Age Property

The Age property retrieves a value that identifies the age of the voice.

Syntax

[ lAge = ] TTSMode.Age

Possible Values

lAge
Integer specifying the age. It can have one of these values:
TTSAGE_BABY
About 1 year old.
TTSAGE_TODDLER
About 3 years old.
TTSAGE_CHILD
About 6 years old.
TTSAGE_ADOLESCENT
About 14 years old.
TTSAGE_ADULT
Between 20 and 60 years old.
TTSAGE_ELDERLY
More than 60 years old.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode


TTSMode.Dialect Property

The Dialect property retrieves the name of the dialect specific to the language. For example, "Texas" or "New York City."

Syntax

[ sName = ] TTSMode.Dialect

Possible Values

sName
String specifying the name of the dialect.

This property is read-only.

Remarks

Dialect strings can be anything. This member can be "Standard" (or its localized equivalent) for the standard dialect used by the news media.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode


TTSMode.EngineFeatures Property

The EngineFeatures property retrieves a set of flag values identifying the features specific to a particular engine. These values are defined by the engine author.

Syntax

[ iFlags = ] TTSMode.EngineFeatures

Possible Values

iFlags
Integer specifying the flags.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode


TTSMode.EngineID Property

The EngineID property retrieves the GUID that uniquely identifies the TTS engine.

Syntax

[ sGUID = ] TTSMode.EngineID

Possible Values

sGUID
String containing the GUID of the engine.

This property is read-only.

Remarks

It is possible for more than one mode to have the same engine ID. In this case, the engine is capable of speaking the different languages or voices of the modes.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode


TTSMode.Features Property

The Features property retrieves a set of flags that identify the TTS features that are available.

Syntax

[ lFeatures = ] TTSMode.Features

Possible Values

lFeatures
Integer specifying the flags, which can have a combination of these values:
TTSFEATURE_ANYWORD
The engine can attempt to read any word.
TTSFEATURE_SAPI4
Denotes that the engine is SAPI 4.0a-compliant, meaning that it supports all of required interfaces and can pass the TTSFUNC test included in the SAPI Software Developer's Kit (SDK).
TTSFEATURE_FIXEDAUDIO
The audio destination for the device is fixed, so an audio destination object is not needed for SELECT. If an audio destination is given, it is ignored. Hardware devices, such as an external synthesizer box, support this.
TTSFEATURE_IPATEXTDATA
TextData supports IPA phonemes, so long as CHARSET_IPAPHONETIC is used. Applications can use this to identify TTS engines that can speak words solely from a pronunciation.
TTSFEATURE_IPAUNICODE
The engine's ITTSCentral::Phoneme function supports the CHARSET_IPAPHONETIC voice character set and will return phonemic representations using the IPA in Unicode. Note that the Unicode version of the Phoneme function must be called, even if this flag is set.
TTSFEATURE_PCOPTIMIZED
The voice is optimized to work over the computer, which provides better sound quality.
TTSFEATURE_PHONEOPTIMIZED
The voice is designed to work over the telephone and uses an 8-kHz sampling rate.
TTSFEATURE_PITCH
The engine can adjust the pitch of the voice while it is speaking.
TTSFEATURE_PREFERRED
The voice is one of the preferred voices from the TTS vendor's set, because of its realism and quality. The TTS engine's ITTSFind method will use preferred voices over nonpreferred, so long as they meet the application's search criteria.
TTSFEATURE_SINGLEINSTANCE
The engine is single instance, so only one mode object can exist at a time. TTS engines that are .exe servers use this.
TTSFEATURE_SPEED
The engine can adjust the speed of the voice while it is speaking.
TTSFEATURE_TAGGED
The engine can interpret tagged text to control the voice.
TTSFEATURE_THREADSAFE
The engine is completely thread safe, and can be called from any thread.
TTSFEATURE_TRANSPLANTED
Supports transplanted prosody.
TTSFEATURE_VISUAL
The engine can provide mouth-position information for the voice.
TTSFEATURE_VOLUME
The engine can adjust the volume of the voice.
TTSFEATURE_WORDPOSITION
The engine sends notification of word position.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode


TTSMode.Gender Property

The Gender property retrieves a value that identifies the gender of the voice.

Syntax

[ lGender = ]TTSMode.Gender

Possible Values

lGender
Integer specifying the gender. It can have one of these values:
GENDER_FEMALE
Female.
GENDER_MALE
Male.
GENDER_NEUTRAL
Not perceptibly male or female.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode


TTSMode.Interfaces Property

The Interfaces property retrieves a set of flags that identify the interfaces supported by the TTS engine.

Syntax

[ lFlags = ] TTSMode.Interfaces

Possible Values

lFlags
Integer specifying the flags, which can have a combination of these values:
TTSI_ILEXPRONOUNCE
ILexPronounce interface.
TTSI_ITTSATTRIBUTES
ITTSAttributes interface.
TTSI_ITTSCENTRAL
ITTSCentral interface.
TTSI_ITTSDIALOGS
ITTSDialogs interface.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode


TTSMode.LanguageID Property

The LanguageID property retrieves a language identifier as specified for the Win32 API. Bits 0 through 9 identify the primary language, such as English, French, and Spanish. Bits 10 through 15 identify the sublanguage, which is essentially a locale setting. For example, Portuguese has two sublanguages, Brazilian and Standard.

Syntax

[ lLangID = ] TTSMode.LanguageID

Possible Values

lLangID
Integer specifying the language identifier.

This property is read-only.

Remarks

For a list of primary and sublanguage identifiers, see the documentation for the MAKELANGID macro in the Win32 SDK. Language ID codes are limited to the Win32 definition of the LANGID macro.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode


TTSMode.MfgName Property

The MfgName property retrieves the name of the manufacturer of the TTS engine. For example, "A. Datum Corporation".

Syntax

[ sName = ] TTSMode.MfgName

Possible Values

sName
String specifying the name of the manufacturer.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode


TTSMode.ModeID Property

The ModeID property retrieves the GUID that uniquely identifies the TTS mode. These numbers are guaranteed to be unique, so you do not need to monitor or record them In addition, the GUID is not stored or used directly by the COM run time, so you do not need to load it into the registry.

Syntax

[ sGUID = ] TTSMode.ModeID

Possible Values

sGUID
String specifying the GUID of the mode.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode


TTSMode.ModeName Property

The ModeName property retrieves the name of the TTS mode.

Syntax

[ sName = ] TTSMode.ModeName

Possible Values

sName
String specifying the name of the mode.

This property is read-only.

Remarks

TTS mode names have the following form:

Voice Description (Age, gender, etc.), Language, [Optional Sampling Rate,] Manufacturer EngineName[, Optional Version Number]

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode


TTSMode.ProductName Property

The ProductName property retrieves the product name of the TTS engine. For example, "The Talking Telephone".

Syntax

[ sProdName = ] TTSMode.ProductName

Possible Values

sProdName
String specifying the product name.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode


TTSMode.Speaker Property

The Speaker property retrieves the name of the voice, or NULL if the name is not important.

Syntax

[ sName = ] TTSMode.Speaker

Possible Values

sName
String specifying the name of the voice.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode


TTSMode.Style Property

The Style property retrieves the name of the personality of the voice. For example: "Business", "Casual", "Computer", "Excited", and "Singsong".

Syntax

[ sName = ] TTSMode.Style

Possible Values

sName
String specifying the name of the personality.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode


WTE Object

Description

The WTE object is the root object in the WTE object model.

Methods

Refresh, Save

Properties

Arrays, VendorDataSets

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTE.Arrays Property

The Arrays property retrieves a collection of all WTE arrays.

Syntax

[ collWTEArrays = ] WTE.Arrays

Possible Values

collWTEArrays
Array of WTEArray objects.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTE, WTEArray, WTEArrays


WTE.Refresh Method

The Refresh method reads the object's configuration information from the persistent storage, discarding any changes to the current configuration that were not saved.

Syntax

WTE.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTE


WTE.Save Method

The Save method saves the configuration information to the persistent storage.

Syntax

WTE.Save( [ bSaveOnlyIfCurrent ] )

Parameters

bSaveOnlyIfCurrent
Optional. A Boolean expression. If TRUE, the save occurs only if the information is current. If FALSE, the save occurs regardless of whether the information is current. The default value for this parameter is FALSE.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTE


WTE.VendorDataSets Property

The VendorDataSets property retrieves a reference to an object for storing and loading custom data into the WTE object's storage.

Syntax

[ oWTEVendorDataSets = ] WTE.VendorDataSets

Possible Values

oWTEVendorDataSets
Reference to the WTEVendorDataSets collection object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTE, WTEVendorDataSets


WTEAddress Object

Description

This object is used to access a single WTEAddress object. It is a member of the WTEAddresses collection.

Methods

Refresh, Save

Properties

AssignedApplication, AssignedGroup, Description, DialableAddress, Name, SupportsCalledID, VendorDataSets

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEAddress.AssignedApplication Property

The AssignedApplication property sets or retrieves the name of the application associated with this line. This property is empty if no application is assigned to this line.

Syntax

WTEAddress.AssignedApplication [ = sApplication ]

Possible Values

sApplication
String specifying the application name.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddress


WTEAddress.AssignedGroup Property

The AssignedGroup property sets or retrieves the name of the group of which this address is a member. This property is empty if the address does not belong to any group.

Syntax

WTEAddress.AssignedGroup [ = sGroup ]

Possible Values

sGroup
String specifying the group name.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddress


WTEAddress.Description Property

The Description property returns a BSTR data type that contains the description of this TAPI device.

Syntax

[ sDescription ] = WTEAddress.Description

Parameters

sDescription
The textual description

Remarks

This property has read/write permissions.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddress


WTEAddress.DialableAddress Property

The DialableAddress property retrieves the TAPI dialable address.

Syntax

[ sAddress = ] WTEAddress.DialableAddress

Possible Values

sAddress
String specifying the TAPI dialable address.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddress


WTEAddress.Name Property

The Name property retrieves the name of the TAPI device.

Syntax

[ sName = ] WTEAddress.Name

Possible Values

sName
String specifying the TAPI device name.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddress


WTEAddress.Refresh Method

The Refresh method reads the object's information from the persistent storage, discarding any changes to the object that were not saved.

Syntax

WTEAddress.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddress


WTEAddress.Save Method

The Save method saves the object's configuration to the persistent storage.

Syntax

WTEAddress.Save( [ bSaveOnlyIfCurrent ] )

Parameters

bSaveOnlyIfCurrent
Optional. A Boolean expression. If TRUE, the save occurs only if the configuration is current. If FALSE, the save occurs regardless of whether the configuration is current. The default value for this parameter is FALSE.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddress


WTEAddress.SupportsCalledID Property

The SupportsCalledID property retrieves whether this line supports called identifier (ID).

Syntax

[ bSupported = ] WTEAddress.SupportsCalledID

Possible Values

bSupported
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | Supports called ID.
FALSE | Does not support called ID.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddress


WTEAddress.VendorDataSets Property

The VendorDataSets property retrieves a reference to an object for storing and loading custom data into the WTEAddress object's storage.

Syntax

[ oWTEVendorDataSets = ] WTEAddress.VendorDataSets

Possible Values

oWTEVendorDataSets
Reference to the WTEVendorDataSets collection object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddress, WTEVendorDataSets


WTEAddresses Collection

Description

This object provides access to the collection of WTEAddress objects. It is a property of the WTEServer object.

Methods

Item, Refresh, Save

Properties

Count, VendorDataSets

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEAddresses.Count Property

The Count property retrieves the number of WTEAddress objects in the collection.

Syntax

[ lCount = ] WTEAddresses.Count

Possible Values

lCount
Integer value specifying the number of WTEAddress objects.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddress, WTEAddresses


WTEAddresses.Item Method

The Item method retrieves a given WTEAddress object from the collection.

Syntax

[ vItem = ] WTEAddresses.Item( vIndex )

Parameters

vIndex
Required. One-based index of the object to retrieve.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddress, WTEAddresses


WTEAddresses.Refresh Method

The Refresh method reads all of the WTEAddress objects from the persistent storage, discarding any changes to the objects that were not saved.

Syntax

WTEAddresses.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddress, WTEAddresses


WTEAddresses.Save Method

The Save method saves the object's configuration to the persistent storage.

Syntax

WTEAddresses.Save( [ bSaveOnlyIfCurrent ] )

Parameters

bSaveOnlyIfCurrent
Optional. A Boolean expression. If TRUE, the save occurs only if the configuration is current. If FALSE, the save occurs regardless of whether the configuration is current. The default value for this parameter is FALSE.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddresses


WTEAddresses.VendorDataSets Property

The VendorDataSets property retrieves a reference to an object for storing and loading custom data into the WTEAddresses object's storage.

Syntax

[ oWTEVendorDataSets = ] WTEAddresses.VendorDataSets

Possible Values

oWTEVendorDataSets
Reference to the WTEVendorDataSets collection object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddresses, WTEVendorDataSets


WTEAddressGroup Object

Description

This object is used to group addresses.

Methods

Refresh, Save

Properties

Name, Description, DNISes, VendorDataSets

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEAddressGroup.Description Property

The Description property sets or retrieves the description of the object.

Syntax

WTEAddressGroup.Description [ = sDescription ]

Possible Values

sDescription
String specifying the group Description.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddressGroup


WTEAddressGroup.DNISes Property

The DNISes property retrieves the WTEDNISes subobject.

Syntax

[ oDNISes = ] WTEAddressGroup.DNISes

Possible Values

oDNISes
Reference to the WTEDNISes subobject.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddressGroup, WTEDNISes


WTEAddressGroup.Name Property

The Name property sets or retrieves the name of the object.

Syntax

WTEAddressGroup.Name [ = sName ]

Possible Values

sName
String specifying the group name.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddressGroup


WTEAddressGroup.Refresh Method

The Refresh method reads all the WTEDNISes objects from the persistent storage, discarding any changes to the objects that were not saved.

Syntax

WTEAddressGroup.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEDNISes, WTEAddressGroup


WTEAddressGroup.Save Method

The Save method saves the object's configuration to the persistent storage.

Syntax

WTEAddressGroup.Save( [ bSaveOnlyIfCurrent ] )

Parameters

bSaveOnlyIfCurrent
Optional. A Boolean expression. If TRUE, the save occurs only if the configuration is current. If FALSE, the save occurs regardless of whether the configuration is current. The default value for this parameter is FALSE.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddressGroup


WTEAddressGroup.VendorDataSets Property

The VendorDataSets property retrieves a reference to an object for storing and loading custom data into the WTEAddressGroup object's storage.

Syntax

[ oWTEVendorDataSets = ] WTEAddressGroup.VendorDataSets

Possible Values

oWTEVendorDataSets
Reference to the WTEVendorDataSets collection object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddressGroup, WTEVendorDataSets


WTEAddressGroups Collection

Description

This object provides access to the collection of WTEAddressGroup objects. It is a property of WTEArray object.

Methods

Item, Refresh, Save, Add, Remove

Properties

Count

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEAddressGroups.Add Method

The Add method creates a WTEAddressGroup object, inserts it into the collection, and returns a reference to it.

Syntax

[ oWTEAddressGroup ] WTEAddressGroups.Add( sName )

Parameters

sName
Required. String specifying the name of the new object.

Return Value

Returns a reference to the WTEAddressGroup object.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddressGroup, WTEAddressGroups


WTEAddressGroups.Count Property

The Count property retrieves the number of Group objects that are in the collection.

Syntax

[ lCount = ] WTEAddressGroups.Count

Possible Values

lCount
Integer value specifying the number of WTEAddressGroup objects.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddressGroup, WTEAddressGroups


WTEAddressGroups.Item Method

The Item method retrieves a given WTEAddressGroup object from the collection.

Syntax

[ vItem = ] WTEAddressGroups.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddressGroup, WTEAddressGroups


WTEAddressGroups.Refresh Method

The Refresh method reads all the WTEAddressGroup objects from the persistent storage, discarding any changes to the objects that were not saved.

Syntax

WTEAddressGroups.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddressGroup, WTEAddressGroups


WTEAddressGroups.Remove Method

The Remove method removes a WTEAddressGroup object from the collection.

Syntax

WTEAddressGroups.Remove( lIndex )

Parameters

lIndex
Required. Name or one-based index of the WTEAddressGroup object to remove.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddressGroup, WTEAddressGroups


WTEAddressGroups.Save Method

The Save method saves the object's configuration to the persistent storage.

Syntax

WTEAddressGroups.Save( [ bSaveOnlyIfCurrent ] )

Parameters

bSaveOnlyIfCurrent
Optional. A Boolean expression. If TRUE, the save occurs only if the configuration is current. If FALSE, the save occurs regardless of whether the configuration is current. The default value for this parameter is FALSE.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddressGroups


WTEAddressGroups.VendorDataSets Property

The VendorDataSets property retrieves a reference to an object for storing and loading custom data into the WTEAddressGroups collection object's storage.

Syntax

[ oWTEVendorDataSets = ] WTEAddressGroups.VendorDataSets

Possible Values

oWTEVendorDataSets
Reference to the WTEVendorDataSets collection object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddressGroups, WTEVendorDataSets


WTEApplication Object

Description

Represents a Web telephony application.

Methods

Refresh, Save

Properties

BackKey, ClearCheckBoxKey, ClearCheckBoxPhrases, ClickButtonKey, ClickButtonPhrases, ConfirmAfter, ConfirmationMenuAnnouncement, ConfirmBefore, DelayedAnswering, Description, DetectABCD, DownloadControlFlags, EnableFullConfiguration, FirstTimeoutInterval, HomeKey, HomePage, IgnoreNavigationKeysTillTermination, InitialAutoNumber, InputTerminator, InputWaveFormat, InterTimeoutInterval, InvalidKeyAnnouncement, LogEventSelection, MaxRecordTime, MaxRetries, Name, NavigationAnnouncement, OfferItems, OperatorExtension, OperatorKey, OperatorTransferType, PostCallPage, RecordStopOnAnyKey, RecordStopSilenceTime, RecurringErrorPage, RenderTablesAsTabularData, RenderTTS, RepeatMenuAnnouncement, RepeatMenuKey, SelectCheckBoxKey, SelectCheckBoxPhrases, ShutdownAnnouncement, ShutdownTime, SkipButtonKey, SkipButtonPhrases, SRParameters, SRThreshold, SuggestConfirmation, TimeoutAnnouncement, TTSParameters, TTSWaveFormat, UseSR, Vendor, VendorDataSets

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEApplication.BackKey Property

The BackKey property sets or retrieves the key to use to navigate backward through the WTE application.

Syntax

WTEApplication.BackKey [ = sKey ]

Possible Values

sKey
String specifying the name of the back key. This string may be empty. If the string contains more than one character, only the first is handled. The initial value of this property is "*".

This property is read-write.

Remarks

The back key should not conflict with the home key or the operator key. If the IgnoreNavigationKeysTillTermination property is FALSE, the BackKey property should also be different from the ClickButtonKey, SkipButtonKey, SelectCheckBoxKey and ClearCheckBoxKey properties.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ClearCheckBoxKey, ClickButtonKey, HomeKey, IgnoreNavigationKeysTillTermination, OperatorKey, SelectCheckBoxKey, SkipButtonKey, WTEApplication


WTEApplication.ClearCheckBoxKey Property

The ClearCheckBoxKey property sets or retrieves the key that the caller must use to clear a check box in an HTML page of a WTE application.

Syntax

WTEApplication.ClearCheckBoxKey [ = sKey ]

Parameters

sKey
String specifying the name of the key used to clear a check box. This string must not be empty. If the string contains more than one character, only the first character is handled. The initial value is "2".

This property is read-write.

Remarks

The ClearCheckBoxKey property should not conflict with the SelectCheckBoxKey property.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SelectCheckBoxKey, WTEApplication


WTEApplication.ClearCheckBoxPhrases Property

The ClearCheckBoxPhrases property sets or retrieves the phrases that the WTE plays for 'clear checkbox'.

Syntax

WTEApplication.ClearCheckBoxPhrases [ = sPhrases ]

Possible Values

sPhrases
String specifying the phrases to play. This string must not be empty.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.ClickButtonKey Property

The ClickButtonKey property sets or retrieves the key used to click a button in an HTML page of a WTE application.

Syntax

WTEApplication.ClickButtonKey [ = sKey ]

Possible Values

sKey
String specifying the name of the key to use to click a button. This string must not be empty. If the string contains more than one character, only the first character is handled. The initial value is "1".

This property is read-write.

Remarks

The ClickButtonKey property must not conflict with the SkipButtonKey property.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SkipButtonKey, WTEApplication


WTEApplication.ClickButtonPhrases Property

The ClickButtonPhrases sets or retrieves the phrases that WTE plays for 'click button'.

Syntax

WTEApplication.ClickButtonPhrases [ = sPhrases ]

Possible Values

sPhrases
String specifying the phrases to play. This string must not be empty.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.ConfirmAfter Property

The ConfirmAfter property sets or retrieves the phrase that WTE plays after an SR confirmation request.

Syntax

WTEApplication.ConfirmAfter [ = sPhrase ]

Parameters

sPhrase
String specifying the phrase to play.

This property is read-write.

Remarks

This property is ignored if the SuggestConfirmation property is FALSE or if the default confirmation menu is canceled. For more information, see Confirming the Selection.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ConfirmationMenuAnnouncement, ConfirmBefore, SuggestConfirmation, WTEApplication


WTEApplication.ConfirmationMenuAnnouncement Property

The ConfirmationMenuAnnouncement property sets or retrieves the wave file or text to play at the beginning of the confirmation menu.

Syntax

WTEApplication.ConfirmationMenuAnnouncement [ = sNameOrText

Possible Values

sNameOrText
String specifying either the name of a wave file or the actual text to play. Use the following format to specify a wave file: URL("filename.wav"). If the format is different, WTE assumes that the string contains text to be played using a TTS engine.

This property is read-write.

Remarks

This property is ignored if the SuggestConfirmation property is FALSE or if the default confirmation menu is canceled. For more information, see Confirming the Selection.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ConfirmAfter, ConfirmBefore, SuggestConfirmation, WTEApplication


WTEApplication.ConfirmBefore Property

The ConfirmBefore property sets or retrieves the phrase that the WTE plays before an SR confirmation request.

Syntax

WTEApplication.ConfirmBefore [ = sPhrase ]

Possible Values

sPhrase
String specifying the phrase to play.

This property is read-write.

Remarks

This property is ignored if the SuggestConfirmation property is FALSE or if the default confirmation menu is canceled. For more information, see Confirming the Selection.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ConfirmAfter, ConfirmBefore, SuggestConfirmation, WTEApplication


WTEApplication.DelayedAnswering Property

The DelayedAnswering property sets or retrieves whether the WTE starts the session without answering the telephony call.

Syntax

WTEApplication.DelayedAnswering [ = bDelayed ]

Possible Values

bDelayed
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | WTE starts the session without answering the telephony call. In this case, the home page should contain a code to answer or hand off the call.
FALSE | WTE answers the call before starting the session.

This property is read-write.

Return Values

DISP_E_MEMBERNOTFOUND
You can set this property only through COM, not through the ExOM object, because DelayedAnswering must be known when the call arrives. Changing the property later will have no effect on the call, nor will it affect subsequent calls.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.Description Property

The Description property sets or retrieves the description of the application.

Syntax

WTEApplication.Description [= sDescription ]

Possible Values

sDescription
String specifying the description of the application.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.DetectABCD Property

The DetectABCD property sets or retrieves whether to detect the A, B, C, and D keys as additional dual tone multi-frequency (DTMF) tones rather than a set of mnemonics (for European countries).

Syntax

WTEApplication.DetectABCD [ = bDetect ]

Possible Values

bDetect
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | Detect the A, B, C, and D keys as additional DTMF tones.
FALSE | Detect the A, B, C, and D keys as a set of mnemonics.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.DownloadControlFlags Property

The DownloadControlFlags property sets or retrieves a group of flags that control the download mode.

Syntax

WTEApplication.DownloadControlFlags [ = iFlags ]

Possible Values

iFlags
Integer values that control the download mode (for example, DLCTL_SILENT). For a list of the download-control flags, see the documentation in the MSDN library.

This property is read-write.

Remarks

When WTE is running as a service, it always includes the DLCTL_DOWNLOADONLY and DLCTL_SILENT flags. Also, these two flags are the default value of the DownloadControlFlags property.

When WTE is running as an executable, you must remove the DLCTL_DOWNLOADONLY flag from the mask in order to see images.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.EnableFullConfiguration Property

The EnableFullConfiguration property sets or retrieves whether WTE administration tool displays all application property pages or just the General and Devices pages.

Syntax

WTEApplication.EnableFullConfiguration [ = bShowAllPropertyPages ]

Possible Values

bShowAllPropertyPages
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | Show all property pages of the application in the administration tool.
FALSE | Show only the General and Devices property pages for this application.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.FirstTimeoutInterval Property

The FirstTimeoutInterval property sets or retrieves the interval of time available for a caller to enter a choice after listening to the announcements of menus or controls.

Syntax

WTEApplication.FirstTimeoutInterval [ = iInterval ]

Possible Values

iInterval
Integer specifying the time interval, in seconds, available for a caller to enter a choice. The MAX_WTE_FirstTimeoutInterval value defines the maximum time interval. A value of -1 means no time-out.

This property is read-write.

Remarks

When the time-out interval expires, WTE reacts as described in the section, Handling Time-outs and Non-valid Keys. This value is used in all cases except the following:

  1. Between consecutive digits of multi-digit access keys.
  2. Between consecutive digits that are treated as an input for a text control (INPUT TYPE=TEXT ) or a text area (TEXTAREA).

The InterTimeoutInterval property defines the time-out interval for the preceding two cases.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

InterTimeoutInterval, WTEApplication


WTEApplication.HomeKey Property

The HomeKey property sets or retrieves the key used to navigate back to the first station.

Syntax

WTEApplication.HomeKey [ = sKey ]

Possible Values

sKey
String specifying the name of the home key. This string may be empty. If the string contains more than one character, only the first character is handled. The initial value of this property is an empty string.

This property is read-write.

Remarks

The home key should not conflict with the back key or the operator key. If the IgnoreNavigationKeysTillTermination property is FALSE, the home key should also be different from the ClickButtonKey, SkipButtonKey, SelecttCheckBoxKey, and ClearCheckBoxKey properties.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

BackKey, ClearCheckBoxKey, ClickButtonKey, IgnoreNavigationKeysTillTermination, OperatorKey, SelectCheckBoxKey, SkipButtonKey, WTEApplication


WTEApplication.HomePage Property

The HomePage property sets or retrieves the URL of the home page of the application.

Syntax

WTEApplication.HomePage [ = sHomePage ]

Possible Values

sHomePage
String specifying the URL of the home page.

This property is read-write.

Remarks

A home-page URL is required — the string must not be empty.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.IgnoreNavigationKeysTillTermination Property

The IgnoreNavigationKeysTillTermination property sets or retrieves whether WTE ignores all navigation keys (BackKey, OperatorKey, and HomeKey properties) while receiving caller input for a text control (INPUT TYPE=TEXT) or a text area (TEXTAREA).

Syntax

WTEApplication.IgnoreNavigationKeysTillTermination [ = bIgnore ]

Possible Values

bIgnore
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | WTE ignores all navigation keys.
FALSE | WTE does not ignore navigation keys. This is the default value.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.InitialAutoNumber Property

The InitialAutoNumber property sets or retrieves the value that WTE starts with when automatically assigning access-key values to items in a menu.

Syntax

WTEApplication.InitialAutoNumber [ = sValue ]

Possible Values

sValue
String specifying the initial access-key value. By default, this property contains an empty string.

This property is read-write.

Remarks

WTE assigns access-key values using the minimum number of digits possible, depending on the number of items in the menu. For example, if the menu has up to nine items, WTE assigns single-digit access-key values. If the menu has up 99 items, it assigns two-digit values, and so on.

If the InitialAutoNumber property is an empty string, WTE assigns access-key values beginning with the number 1, 10, 100, or 1000, depending on the number of items in the menu.

The number of items to which WTE assigns single-digit access-key values depends on the values already assigned to other keys. For example, if the home key is 1, the back key is 2, and the operator key is 3, WTE assigns only the digits 4 through 9 to items in a menu that has fewer than 10 items.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.InputTerminator Property

The InputTerminator property sets or retrieves the termination string for the caller input (required by the INPUT element with the TYPE=TEXT attribute and the TEXTAREA element) and multiple selection menu (created by the SELECT element with the MULTIPLE attribute). A caller also uses this string to designate the end of the record operation.

Syntax

WTEApplication.InputTerminator [ = sInputTerminator ]

Possible Values

sInputTerminator
String specifying the input terminator. This string must not be empty. The maximum length is ten DTMF keys.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.InputWaveFormat Property

The InputWaveFormat property sets or retrieves the wave format to negotiate with the SR engine and to use for recordings.

Syntax

WTEApplication.InputWaveFormat [ = iFormat ]

Possible Values

iFormat
Value from the PCMWaveFormats enumeration. By default, this property has an initial value of wteDefaultWaveFormat.

This property is read-write.

Remarks

For SR, if this property specifies the wteDefaultWaveFormat value, the first wave format suggested by the SR engine is accepted. If this property specifies a value other than wteDefaultWaveFormat, only the specified format is accepted. If the SR engine does not support the specified format, the call is disconnected. Because there is no way to ask the SR engine to renegotiate the format, a new SR engine (or the same one) is loaded each time the value of the InputWaveFormat property is changed.

For recording, this property determines the wave format of the recorded files. If this property is set to wteDefaultWaveFormat, the format used for the recorded files is 8KHz, 16-bit, mono.

The only format supported by Microsoft's SR engine is 8KHz, 16 bit, mono.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

PCMWaveFormats, WTEApplication


WTEApplication.InterTimeoutInterval Property

The InterTimeoutInterval property sets or retrieves the interval of time that WTE uses between consecutive digits of multidigit access keys, and between consecutive digits that are treated as an input for a text control (INPUT TYPE=TEXT ) or a text area (TEXTAREA). In all other cases, the time-out interval is defined by the FirstTimeoutInterval property.

Syntax

WTEApplication.InterTimeoutInterval [ = iInterval ]

Possible Values

iInterval
Integer specifying the time interval, in seconds. The MAX_WTE_InterTimeoutInterval value defines the maximum time interval. A value of -1 means no time-out.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

FirstTimeoutInterval, WTEApplication


WTEApplication.InvalidKeyAnnouncement Property

The InvalidKeyAnnouncement property sets or retrieves the wave file or text for the WTE to play when the caller presses a key that is not a valid selection.

Syntax

WTEApplication.InvalidKeyAnnouncement [ = sNameOrText

Possible Values

sNameOrText
String specifying either the name of a wave file or the actual text to play. Use the following format to specify a wave file: URL("filename.wav"). If the format is different, the WTE assumes that the string contains text to be played using a TTS engine.

This property is read-write.

Remarks

The announcement is played only if the default action is not canceled.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.LogEventSelection Property

The LogEventSelection property sets or retrieves a group of flags that specify the types of events to log.

Syntax

WTEApplication.LogEventSelection [ = iFlags ]

Possible Values

iFlags
Integer values specifying the events to log. This parameter can be a combination of the following flags, as enumerated in LogEventType:
AUTHORING_ERROR = 1
An error in the Web telephony application generates this event. The error is explained in the Error Type field of the log.
CALL_AVAILABLE = 2
A call is available for WTE. Affected log fields: Caller ID, Called ID, Reason, Application Name, Media, URL.
APPLICATION_CONNECT = 4
A Web telephony application successfully connected to the call.
NAVIGATE = 8
Navigation in the application occurred. Affected log fields: URL.
CALL_FORWARD = 16
The call was transferred. Affected log fields: Destination Address, Transfer Reason.
CALL_DISCONNECT = 32
The call disconnected. Affected log fields: Disconnect Reason.
APPLICATION_TERMINATION = 64
The application terminated. This event can come long after the call disconnects if a post-call page is defined.
INPUT_TIMEOUT = 128
A time-out event occurred while waiting for input from the caller.
CALL_INFO_CHANGED = 256
The call information changed. Affected log fields: Caller ID, Called ID, Reason, Application Name, Media.
CALL_ANSWER = 512
WTE answered an incoming call.
DTMF_INPUT_ERROR = 1024
An invalid DTMF was received. For example, the caller pressed an unauthorized digit. Affected log fields: DTMF Value.
NO_APPLICATION = 2048
A call was received on a port that has no application.
CUSTOM_LOG = 4096
The extended object model (ExOM) generates this event. The author of a Web telephony application can call this event from the application. Affected log fields: Custom Log.
DTMF_RECEIVED = 8192
The Web telephony application received a DTMF digit. Affected log fields: DTMF Value.
SPEECH_INPUT_DATA = 16384
A Web telephony application received speech input data. This data is spoken by the caller and processed by a speech-recognition (SR) engine. This event causes a wave file to be saved as well as the normal logging. Affected log fields: Input Record File.
SPEECH_INPUT_FAILED = 32768
The SR engine failed to be recognize speech input. The speech input is recorded to a file as well. Affected log fields: Input Record File.
RECORD_DATA = 65536
A Web telephony application can record voice data from the caller. This event occurs when such a recording finishes. The recorded file will also be saved for logging. Affected log fields: Input Record File.
RECORD_FAILED = 131072
An attempt to record the caller failed. Affected log fields: Input Record File.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.MaxRecordTime Property

The MaxRecordTime property sets or retrieves the maximum duration of a recorded message.

Syntax

WTEApplication.MaxRecordTime [ = iMaxDuration ]

Possible Values

iMaxDuration
Integer value specifying the maximum duration of a recorded message, in seconds. The MAX_WTE_MaxRecordTime value defines the maximum value for this property. A value of -1 specifies an unlimited duration.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

RecordStopSilenceTime, WTEApplication


WTEApplication.MaxRetries Property

The MaxRetries property sets or retrieves the number of times WTE performs default error-handling actions due to a caller's mistakes before dropping the call or navigating to the RecurringErrorPage property. Mistakes include pressing an non-valid key or the occurrence of a time-out. When WTE navigates to another menu or control, the counter of caller errors is reset to zero.

Syntax

WTEApplication.MaxRetries [ = iRetries ]

Possible Values

iRetries
Integer specifying the maximum number of retries. The MAX_WTE_MaxRetries value defines the maximum number of retries. A value of -1 specifies unlimited retries.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

RecurringErrorPage, WTEApplication


WTEApplication.Name Property

The Name property sets or retrieves the name of the application. Each application must have a unique name.

Syntax

WTEApplication.Name [ = sName ]

Possible Values

sName
String specifying the application name.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.NavigationAnnouncement Property

The NavigationAnnouncement property sets or retrieves the wave file or text to play while navigating.

Syntax

WTEApplication.NavigationAnnouncement [ = sNameOrText ]

Possible Values

sNameOrText
String specifying either the name of a wave file or the actual text to play. Use the following format to specify a wave file: URL("filename.wav"). If the format is different, WTE assumes that the string contains text to be played using a TTS engine.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.OfferItems Property

Sets or retrieves whether audio items inside a menu will be gathered.

Syntax

WTEApplication.OfferItems [ = bGatherItems ]

Possible Values

bGatherItems
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | Gather audio items inside a menu.
FALSE | Do not gather audio items inside a menu.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.OperatorExtension Property

The OperatorExtension property sets or retrieves the operator extension to use when the caller presses the key specified in the OperatorKey property.

Syntax

WTEApplication.OperatorExtension [ = sExtension ]

Possible Values

sExtension
String specifying the operator extension. This string must not be empty if an operator key is defined. The initial value is "0".

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

OperatorKey, WTEApplication


WTEApplication.OperatorKey Property

The OperatorKey property sets or retrieves the key used to transfer the call to the operator.

Syntax

WTEApplication.OperatorKey [ = sKey ]

Possible Values

sKey
String specifying the name of the operator key. This string may be empty. If the string contains more than one character, only the first character is handled. The initial value is "0". The operator line address is defined in the OperatorExtension property.

This property is read-write.

Remarks

The operator key should not conflict with the back key and with the home key. If the IgnoreNavigationKeysTillTermination property is FALSE, the operator key should also be different from the ClickButtonKey, SkipButtonKey, SelectCheckBoxKey, and ClearCheckBoxKey properties.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

BackKey, ClearCheckBoxKey, ClickButtonKey, HomeKey, IgnoreNavigationKeysTillTermination, OperatorExtension, SelectCheckBoxKey, SkipButtonKey, WTEApplication


WTEApplication.OperatorTransferType Property

The OperatorTransferType property sets or retrieves the transfer type when transferring to the operator extension.

Syntax

WTEApplication.OperatorTransferType [ = iType ]

Possible Values

iType
Integer specifying the transfer type. It can be one of these values:

0 - Blind transfer.

1 - Supervised transfer.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.PostCallPage Property

The PostCallPage property sets or retrieves the URL to which WTE should navigate after the call is disconnected.

Syntax

WTEApplication.PostCallPage [ = sURL ]

Possible Values

sURL
String specifying the URL to which to navigate after disconnecting.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ExOM.Abandon, WTEApplication


WTEApplication.RecordStopOnAnyKey Property

The RecordStopOnAnyKey property sets or retrieves whether recording should stop when the caller presses any key.

Syntax

WTEApplication.RecordStopOnAnyKey [ = bRecordStopOnAnyKey ]

Possible Values

bRecordStopOnAnyKey
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | Any key causes recording to stop.
FALSE | Only the key specified by the InputTerminator property causes recording to stop.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.RecordStopSilenceTime Property

The WTEApplication.RecordStopSilenceTime property sets or retrieves the duration of silence after which recording stops.

Syntax

WTEApplication.RecordStopSilenceTime [ = iDuration ]

Possible Values

iDuration
Integer specifying the duration of silence, in seconds. The MAX_WTE_RecordStopSilenceTime value defines the maximum duration. The value -1 specifies an unlimited duration.

This property is read-write.

Remarks

This property is not yet implemented.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

MaxRecordTime, WTEApplication


WTEApplication.RecurringErrorPage Property

The RecurringErrorPage property sets or retrieves the page that WTE renders when the number of consecutive caller errors exceeds the value of the MaxRetries property.

Syntax

WTEApplication.RecurringErrorPage [ = sPage ]

Possible Values

sPage
String specifying the name of the recurring error page.

This property is read-write.

Remarks

If this property is not defined, WTE disconnects the call and sets the SessionState property of the Session object to "Disconnected - Recurring Error".

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

MaxRetries, WTEApplication


WTEApplication.Refresh Method

The Refresh method reads the object's configuration information from the persistent storage, discarding any changes to the current configuration that were not saved.

Syntax

WTEApplication.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.RenderTablesAsTabularData Property

The RenderTablesAsTabularData property sets or retrieves whether a table in the HTML page is rendered as a table or as regular text.

Syntax

WTEApplication.RenderTablesAsTabularData [ = bRenderAsTable ]

Possible Values

bRenderAsTable
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | Render as a table.
FALSE | Render as regular text.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.RenderTTS Property

The RenderTTS property sets or retrieves whether WTE plays text from the HTML page using a text-to-speech (TTS) engine.

Syntax

WTEApplication.RenderTTS [ = bTTS ]

Possible Values

bTTS
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | WTE uses a TTS engine.
FALSE | WTE does not use a TTS engine.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSParameters, WTEApplication


WTEApplication.RepeatMenuAnnouncement Property

The RepeatMenuAnnouncement property sets or retrieves the wave file or text for WTE to play at the end of the confirmation menu.

Syntax

WTEApplication.RepeatMenuAnnouncement [ = sNameOrText ]

Possible Values

sNameOrText
String specifying either the name of a wave file or the actual text to play. Use the following format to specify a wave file: URL("filename.wav"). If the format is different, WTE assumes that the string contains text to be played using a TTS engine.

This property is read-write.

Remarks

The announcement is played only if the default action is not canceled.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.RepeatMenuKey Property

The RepeatMenuKey property sets or retrieves a key that specifies that the caller did not say any of the phrases recognized by the SR engine.

Syntax

WTEApplication.RepeatMenuKey [ = sKey ]

Possible Values

sKey
String specifying the name of the key. If this string contains more than one character, only the first is handled. The initial value is empty.

This property is read-write.

Remarks

The confirm-none key should not conflict with the home key, the operator key, or the back key.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

BackKey, HomeKey, OperatorKey, WTEApplication


WTEApplication.Save Method

The Save method saves the configuration information to the persistent storage.

Syntax

WTEApplication.Save( [ bSaveOnlyIfCurrent ] )

Parameters

bSaveOnlyIfCurrent
Optional. A Boolean expression. If TRUE, the save occurs only if the information is current. If FALSE, the save operation occurs regardless of whether the information is current. The default value for this parameter is FALSE.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.SelectCheckBoxKey Property

The SelectCheckBoxKey property sets or retrieves the key used to select a check box in the HTML page.

Syntax

WTEApplication.SelectCheckBoxKey [ = sKey ]

Possible Values

sKey
String specifying the name of the key to use to select a check box. This string must not be empty. If the string contains more than one character, only the first character is handled. The initial value is "1".

This property is read-write.

Remarks

The SelectCheckBoxKey property should not conflict with the ClearCheckBoxKey property.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ClearCheckBoxKey, WTEApplication


WTEApplication.SelectCheckBoxPhrases Property

The SelectCheckBoxPhrases sets or retrieves the phrases that WTE plays for 'select check box'.

Syntax

WTEApplication.SelectCheckBoxPhrases [ = sPhrases ]

Possible Values

sPhrases
String specifying the phrases to play. This string must not be empty.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.ShutdownAnnouncement Property

The ShutdownAnnouncement property sets or retrieves the wave file or text that WTE plays when shutting down.

Syntax

WTEApplication.ShutdownAnnouncement [ = sNameOrText ]

Possible Values

sNameOrText
String specifying either the name of a wave file or the actual text to play. Use the following format to specify a wave file: URL("filename.wav"). If the format is different, the WTE assumes that the string contains text to be played using a TTS engine.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.ShutdownTime Property

The ShutdownTime property sets or retrieves the amount of time, in seconds, that elapses between a shutdown announcement and the actual termination of the session.

Syntax

WTEApplication.ShutdownTime [ = iSeconds ]

Possible Values

iSeconds
Integer specifying the shutdown time, in seconds.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.SkipButtonKey Property

The SkipButtonKey property sets or retrieves the key that the caller must use to skip a button in the HTML page.

Syntax

WTEApplication.SkipButtonKey [ = sKey ]

Possible Values

sKey
String specifying the name of the key used to skip a button. If the string contains more than one character, only the first character is handled. The initial value is "2".

This property is read-write.

Remarks

The SkipButtonKey property should not conflict with the ClickButtonKey property.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ClickButtonKey, WTEApplication


WTEApplication.SkipButtonPhrases Property

The SkipButtonPhrases property sets or retrieves the phrases that WTE plays for 'skip button'.

Syntax

WTEApplication.SkipButtonPhrases [ = sPhrases ]

Possible Values

sPhrases
String specifying the phrases to play. This string must not be empty.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.SRParameters Property

The SRParameters property sets or retrieves a string that encapsulates the SRMODEINFO and SRMODEINFORANK structures.

Syntax

WTEApplication.SRParameters [ = sParameters ]

Possible Values

sParameters
String specifying fields and corresponding values in the following format: "field1=value1;field2=value2;...". Not all fields should be specified. The ranking is determined by the field order in the string. Possible fields and values include:

EngineID - GUID

MfgName - String

ProductName - String

ModeID - GUID

ModeName - String

LanguageID - Number (WORD)

Dialect - String

Sequencing - Number (WORD)

MaxWordsVocab - Number (DWORD)

MaxWordsState - Number (DWORD)

Grammars - Number (DWORD)

Features - Number (DWORD)

Interfaces - Number (DWORD)

EngineFeatures - Number (DWORD)

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.SRThreshold Property

The SRThreshold property sets or retrieves the threshold of certainty with which the speech is considered to be recognized.

Syntax

WTEApplication.SRThreshold [ = iThreshold ]

Possible Values

iThreshold
Integer specifying the threshold.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.SuggestConfirmation Property

The SuggestConfirmation property sets or retrieves whether WTE is to suggest a confirmation menu after the caller selects a menu item by using speech recognition.

Syntax

WTEApplication.SuggestConfirmation [ = bSuggest ]

Possible Values

bSuggest
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | WTE suggests a confirmation menu.
FALSE | WTE Immediately chooses the recognized menu item without first suggesting a confirmation menu. This is the default value.

This property is read-write.

Remarks

If this property is FALSE, the ConfirmationMenuAnnouncement, ConfirmBefore, and ConfirmAfter properties are ignored. For more information, see Confirming the Selection.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ConfirmationMenuAnnouncement, ConfirmAfter, ConfirmBefore, MaxRecordTime, WTEApplication


WTEApplication.TimeoutAnnouncement Property

The TimeoutAnnouncement property sets or retrieves the wave file or text that WTE plays when a time-out has expired.

Syntax

WTEApplication.TimeoutAnnouncement [ = sNameOrText ]

Possible Values

sNameOrText
String specifying either the name of a wave file or the actual text to play. Use the following format to specify a wave file: URL("filename.wav"). If the format is different, WTE assumes that the string contains text to be played using a TTS engine.

This property is read-write.

Remarks

The announcement is played only if the default action is not canceled.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

FirstTimeoutInterval, InterTimeoutInterval, WTEApplication


WTEApplication.TTSParameters Property

The TTSParameters property sets or retrieves a string that encapsulates the TTSMODEINFO and TTSMODEINFORANK structures.

Syntax

WTEApplication.TTSParameters [ = sParameters ]

Possible Values

sParameters
String specifying fields and corresponding values in the following format: "field1=value1;field2=value2;...". Not all fields should be specified. The ranking is determined by the field order in the string. Possible fields and values include:

EngineID - GUID

MfgName - String

ProductName - String

ModeID - GUID

ModeName - String

LanguageID - Number (WORD)

Dialect - String

Speaker - String

Style - String

Gender - Number (WORD)

Age - Number (WORD)

Features - Number (DWORD)

Interfaces - Number (DWORD)

EngineFeatures - Number (DWORD)

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

RenderTTS, WTEApplication


WTEApplication.TTSWaveFormat Property

The TTSWaveFormat property sets or retrieves the wave format to negotiate with the TTS engine.

Syntax

WTEApplication.TTSWaveFormat [ = iFormat ]

Possible Values

iFormat
Value from the PCMWaveFormats enumeration. By default, this property has an initial value of wteDefaultWaveFormat.

This property is read-write.

Remarks

If this property specifies the wteDefaultWaveFormat value, the first wave format suggested by the TTS engine is accepted. If this property specifies a value other than wteDefaultWaveFormat, only the specified format is accepted. If the TTS engine does not support the specified format, the call is disconnected. Because there is no way to ask the TTS engine to renegotiate the format, a new TTS engine (or the same one) is loaded each time the value of the TTSWaveFormat property is changed. This property has no effect on wave files.

The Microsoft TTS engine supports the following formats:

  • 8KHz, 8-bit, mono
  • 8KHz, 16-bit, mono
  • 11.025KHz, 8-bit, mono
  • 11.025KHz, 16-bit, mono

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

PCMWaveFormats, WTEApplication


WTEApplication.UseSR Property

The UseSR property sets or retrieves whether the engine uses speech recognition (SR) in this application.

Syntax

WTEApplication.UseSR [ = bUseSR ]

Possible Values

bUseSR
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | WTE uses an SR engine.
FALSE | WTE does not use an SR engine.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.Vendor Property

The Vendor property sets or retrieves the application vendor information.

Syntax

WTEApplication.Vendor [= sVendor ]

Possible Values

sVendor
String specifying the vendor of the application.

This property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication


WTEApplication.VendorDataSets Property

The VendorDataSets property retrieves a reference to an object for storing and loading of custom data into the WTEApplication object's storage.

Syntax

[ oWTEVendorDatasets = ] WTEApplication.VendorDataSets

Possible Values

oWTEVendorDatasets
Reference to the WTEVendorDataSet collection.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication, WTEVendorDataSets


WTEApplications Collection

Description

Provides access to a collection of WTEApplication objects. The WTEApplication object permits an application to enumerate all Web telephony applications. There is one WTEApplication object for each application.

Methods

Add, Item, Refresh, Remove, Save

Properties

Count, VendorDataSets

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEApplications.Add Method

The Add method creates a new application object in the collection and returns a reference to the object. Use the Save method to persist the object.

Syntax

[ oWTEApplication = ] WTEApplications.Add( sName, sHomePage )

Parameters

sName
Required. String specifying the name of the new application.
sHomePage
Required. String specifying the home page of the new application.

Return Value

Returns a reference to the new WTEApplications object if successful; NULL otherwise.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication, Save, WTEApplications


WTEApplications.Count Property

The Count property retrieves the number of WTEApplication objects in the collection.

Syntax

[ lCount = ] WTEApplications.Count

Possible Values

lCount
Integer value specifying the number of application objects.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplications


WTEApplications.Item Method

The Item method retrieves the given (WTEApplication) object from the collection.

Syntax

[ vItem = ] WTEApplications.Item( vIndex )

Parameters

vIndex
Required. Name or 1-based index of the object to retrieve.

Return Value

Variant. Returns an object if successful; NULL otherwise.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication, WTEApplications


WTEApplications.Refresh Method

The Refresh method reads the object's configuration information from the persistent storage, discarding any changes to the current configuration that were not saved.

Syntax

WTEApplications.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplications


WTEApplications.Remove Method

The Remove method removes the given application object from the collection.

Syntax

WTEApplications.Remove( vIndex )

Parameters

vIndex
Required. Name or 1-based index of the application to remove.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication, WTEApplications


WTEApplications.Save Method

The Save method saves the configuration information to the persistent storage.

Syntax

WTEApplications.Save( [ bSaveOnlyIfCurrent ] )

Parameters

bSaveOnlyIfCurrent
Optional. A Boolean expression. If TRUE, the save occurs only if the information is current. If FALSE, the save occurs regardless of whether the information is current. The default value for this parameter is FALSE.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplications


WTEApplications.VendorDataSets Property

The VendorDataSets property retrieves a reference to an object for storing and loading of custom data into the WTEApplications object's storage.

Syntax

[ oWTEVendorDatasets = ] WTEApplications.VendorDataSets

Possible Values

oWTEVendorDatasets
Reference to the WTEVendorDataSets collection object.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplications, WTEVendorDataSets


WTEArray Object

Description

This object is used to access a single WTE array. It is a member of the WTEArrays collection object.

Methods

Refresh, Save

Properties

Applications, Description, Log, Name, Servers, VendorDataSets

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEArray.Applications Property

The Applications property retrieves a collection of all Web telephony applications in this array.

Syntax

[ collWTEApplications = ] WTEArray.Applications

Possible Values

collWTEApplications
Array of WTEApplication objects.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEApplication, WTEApplications, WTEArray


WTEArray.Description Property

The Description property sets or retrieves the description of the array.

Syntax

WTEArray.Description [ = sDescription ]

Possible Values

sDescription
String specifying the description of the array.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEArray


WTEArray.Log Property

The Log property retrieves an object holding all log configurations for this array.

Syntax

[ oWTELog = ] WTEArray.Log

Possible Values

oWTELog
Reference to a WTELog object.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEArray, WTELog


WTEArray.Name Property

The Name property sets or retrieves the name of the array.

Syntax

WTEArray.Name [ = sName ]

Possible Values

sName
String specifying the array name.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEArray


WTEArray.Refresh Method

The Refresh method reads the array's information from the persistent storage, discarding any changes to the current array that were not saved.

Syntax

WTEArray.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEArray


WTEArray.Save Method

The Save method saves the array configuration to the persistent storage.

Syntax

WTEArray.Save( [ bSaveOnlyIfCurrent ] )

Parameters

bSaveOnlyIfCurrent
Optional. A Boolean expression. If TRUE, the save occurs only if the configuration is current. If FALSE, the save occurs regardless of whether the configuration is current. The default value for this parameter is FALSE.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEArray


WTEArray.Servers Property

The Servers property retrieves a collection of all WTE servers in this array.

Syntax

[ collWTEServers = ] WTEArray.Servers

Possible Values

collWTEServers
Array of WTEServer objects.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEArray, WTEServer, WTEServers


WTEArray.VendorDataSets Property

The VendorDataSets property retrieves a reference to an object for storing and loading of custom data into a WTEArray object's storage.

Syntax

[ oWTEVendorDataSets = ] WTEArray.VendorDataSets

Possible Values

oWTEVendorDataSets
Reference to the WTEVendorDataSets collection object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEArray, WTEVendorDataSets


WTEArrays Collection

Description

Provides access to the collection of WTEArray objects. It is a property of the WTE object.

Methods

GetContainingArray, Item, Refresh, Remove, Save

Properties

Count, VendorDataSets

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEArrays.Count Property

The Count property retrieves the number of array objects in the collection.

Syntax

[ lCount = ] WTEArrays.Count

Possible Values

lCount
Integer value specifying the number of WTEArray objects.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEArrays


WTEArrays.GetContainingArray Method

The GetContainingArray method retrieves the array to which the current computer belongs.

Syntax

[ oWTEArray = ] WTEArrays.GetContainingArray()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEArrays


WTEArrays.Item Method

The Item method retrieves the given WTEArray object from the collection.

Syntax

[ vItem = ] WTEArrays.Item( vIndex )

Parameters

vIndex
Required. Name or 1-based index of the object to retrieve.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEArrays


WTEArrays.Refresh Method

The Refresh method reads all of the arrays from the persistent storage, discarding any changes to the current arrays that were not saved.

Syntax

WTEArrays.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEArrays


WTEArrays.Remove Method

The Remove method removes an array from the collection.

Syntax

WTEArrays.Remove( lIndex )

Parameters

lIndex
Required. Name or 1-based index of the WTEArray object to remove.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEArrays


WTEArrays.Save Method

The Save method saves the configuration of the arrays in the collection to the persistent storage.

Syntax

WTEArrays.Save( [ bSaveOnlyIfCurrent ] )

Parameters

bSaveOnlyIfCurrent
Optional. A Boolean expression. If TRUE, the save occurs only if the configuration is current. If FALSE, the save occurs regardless of whether the configuration is current. The default value for this parameter is FALSE.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEArrays


WTEArrays.VendorDataSets Property

The VendorDataSets property retrieves a reference to an object for storing and loading of custom data into the WTEArrays object's storage.

Syntax

[ oWTEVendorDataSets = ] WTEArrays.VendorDataSets

Possible Values

oWTEVendorDataSets
Reference to the WTEVendorDataSets collection object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEArrays, WTEVendorDataSets


WTEDNIS Object

Description

This object is used to define a single WTEDNIS object. This object is a member of the WTEDNISes collection.

Defined in: mswtecom.idl

Methods

Refresh, Save

Properties

AssignedApplication, Description, DialedNumberIdentification Name, VendorDataSets,

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEDNIS.AssignedApplication Property

The AssignedApplication property sets or retrieves the name of the application associated with this object. This property is empty if no application is assigned to this object.

Syntax

WTEDNIS.AssignedApplication [ = sApplication ]

Possible Values

sApplication
String specifying the application name.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEDNIS


WTEDNIS.Description Property

The Description property sets or retrieves the description of the object.

Syntax

WTEDNIS.Description [ = sDescription ]

Possible Values

sDescription
String specifying the description.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEDNIS


WTEDNIS.DialedNumberIdentification Property

The DialedNumberIdentification property sets or retrieves the dialed number identification.

Syntax

WTEDNIS.DialedNumberIdentification [ = sDialedNumberIdentification ]

Possible Values

sDialedNumberIdentification
String specifying the Dialed Number Identification (DNI).

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEDNIS


WTEDNIS.Name Property

The Name property sets or retrieves the name of the object.

Syntax

WTEDNIS.Name [ = sName ]

Possible Values

sName
String specifying the name.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEDNIS


WTEDNIS.Refresh Method

The Refresh method reads the object from the persistent storage, discarding any changes to the object that were not saved.

Syntax

WTEDNIS.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEDNIS


WTEDNIS.Save Method

The Save method saves the object's configuration to the persistent storage.

Syntax

WTEDNIS.Save( [ bSaveOnlyIfCurrent ] )

Parameters

bSaveOnlyIfCurrent
Optional. A Boolean expression. If TRUE, the save occurs only if the configuration is current. If FALSE, the save occurs regardless of whether the configuration is current. The default value for this parameter is FALSE.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEDNIS


WTEDNIS.VendorDataSets Property

The VendorDataSets property retrieves a reference to an object for storing and loading of custom data into the WTEDNIS object's storage.

Syntax

[ oWTEVendorDataSets = ] WTEDNIS.VendorDataSets

Possible Values

oWTEVendorDataSets
Reference to the WTEVendorDataSets collection object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEDNIS, WTEVendorDataSets


WTEDNISes Collection

Description

This object provides access to the collection of WTEDNIS objects. It is a property of WTEAddressGroup object.

Methods

Item, Refresh, Save, Add, Remove

Properties

Count

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEDNISes.Add Method

The Add method creates a WTEDNIS object, inserts it into the collection, and returns a reference to it.

Syntax

[ oWTEDNIS ] WTEDNISes.Add( sName, sDialedNumberIdentification )

Parameters

sName
Required. String specifying the name of the new object.
sDialedNumberIdentification
Required. String specifying the dialed number identification.

Return Value

Returns a reference to the WTEDNIS object.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEDNIS, WTEDNISes


WTEDNISes.Count Property

The Count property retrieves the number of WTEDNIS objects in the collection.

Syntax

[ lCount = ] WTEDNISes.Count

Possible Values

lCount
Integer value specifying the number of WTEDNIS objects.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEDNIS, WTEDNISes


WTEDNISes.Item Method

The Item method retrieves the given WTEDNIS object from the collection.

Syntax

[ vItem = ] WTEDNISes.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEDNIS, WTEDNISes


WTEDNISes.Refresh Method

The Refresh method reads all of the WTEDNIS objects from the persistent storage, discarding any changes to the objects that were not saved.

Syntax

WTEDNISes.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEDNIS, WTEDNISes


WTEDNISes.Remove Method

The Remove method removes a WTEDNIS object from the collection.

Syntax

WTEDNISes.Remove( lIndex )

Parameters

lIndex
Required. Name or one-based index of the WTEDNIS object to remove.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEDNIS, WTEDNISes


WTEDNISes.Save Method

The Save method saves the object's configuration to the persistent storage.

Syntax

WTEDNISes.Save( [ bSaveOnlyIfCurrent ] )

Parameters

bSaveOnlyIfCurrent
Optional. A Boolean expression. If TRUE, the save occurs only if the configuration is current. If FALSE, the save occurs regardless of whether the configuration is current. The default value for this parameter is FALSE.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEDNISes


WTEDNISes.VendorDataSets Property

The VendorDataSets property retrieves a reference to an object for storing and loading of custom data into the WTEDNISes object's storage.

Syntax

[ oWTEVendorDataSets = ] WTEDNISes.VendorDataSets

Possible Values

oWTEVendorDataSets
Reference to the WTEVendorDataSets collection object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEDNISes, WTEVendorDataSets


WTELog Object

Description

The WTELog object is used to set the logging configuration.

Methods

Refresh, Save

Properties

LogEnabled , LogFieldSelection, LogFileDirectory, LogFileDirectoryType, LogFilePeriod, LogFilesCompress, LogSqlDataSource, LogSqlTableName, LogType

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTELog.LogEnabled Property

The LogEnabled property enables or disables WTE logging.

Syntax

WTELog.LogEnabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | WTE logging is enabled.
FALSE | WTE logging is disabled.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTELog


WTELog.LogFieldSelection Property

The LogFieldSelection property sets or retrieves a bit field selection of logged columns.

Syntax

WTELog.LogFieldSelection[ = iSel ]

Possible Values

iSel
Bit field specifying the logged columns. This parameter can be a combination from the LogFieldType enumeration.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

LogFieldType, WTELog


WTELog.LogFileDirectory Property

The LogFileDirectory property sets or retrieves the directory containing the text log files.

Syntax

WTELog.LogFileDirectory [ = sDir ]

Possible Values

sDir
String specifying the directory.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTELog


WTELog.LogFileDirectoryType Property

The LogFileDirectoryType property sets or retrieves the type of the files logging directory.

Syntax

WTELog.LogFileDirectoryType [ = type ]

Possible Values

type
Value from the LogFileDirectoryType enumeration.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

LogFileDirectoryType, WTELog


WTELog.LogFilePeriod Property

The LogFilePeriod property sets or retrieves the period of time before starting a new text log file.

Syntax

WTELog.LogFilePeriod [ = period ]

Possible Values

period
Value from the LogPeriodType enumeration.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

LogPeriodType, WTELog


WTELog.LogFilesCompress Property

The LogFilesCompress property sets or retrieves whether text log files are compressed.

Syntax

WTELog.LogFilesCompress [ = bCompress ]

Possible Values

bCompress
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | Files are compressed.
FALSE | Files are not compressed.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTELog


WTELog.LogSqlDataSource Property

The LogSqlDataSource property sets or retrieves the name of the SQL data source.

Syntax

WTELog.LogSqlDataSource [ = sName ]

Possible Values

sName
String specifying the SQL data source name.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTELog


WTELog.LogSqlTableName Property

The LogSqlTableName property sets or retrieves the name of the SQL table.

Syntax

WTELog.LogSqlTableName [ = sName ]

Possible Values

sName
String specifying the SQL table name.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTELog


WTELog.LogType Property

The LogType property sets or retrieves the type of the logging method.

Syntax

WTELog.LogType [ = type ]

Possible Values

type
Value from the LogType enumeration.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

LogType, WTELog


WTELog.Refresh Method

The Refresh method reads the log configuration from the persistent storage.

Syntax

WTELog.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTELog


WTELog.Save Method

The Save method saves the log configuration to the persistent storage.

Syntax

WTELog.Save()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTELog


WTEServer Object

Description

This object is used to access the single WTE server. It is a member of the WTEServers collection.

Defined in: mswtecom.idl

Methods

Refresh, Save

Properties

Addresses, Description, Name, ProductVersion, SRModes, TTSModes, VendorDataSets

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEServer.Addresses Property

The Addresses property retrieves a collection of WTEAddress objects in this server.

Syntax

[ oWTEAddresses = ] WTEServer.Addresses

Possible Values

oWTEAddresses
Reference to the WTEAddresses collection object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEAddress, WTEAddresses, WTEServer


WTEServer.Description Property

The Description property sets or retrieves the description of the server.

Syntax

WTEServer.Description [ = sDescription ]

Possible Values

sDescription
String specifying the description of the server.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEServer


WTEServer.Name Property

The Name property retrieves the name of the server.

Syntax

[ sName = ] WTEServer.Name

Possible Values

sName
String specifying the server name.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEServer


WTEServer.ProductVersion Property

The ProductVersion property retrieves the version of the server.

Syntax

[ sVersion = ] WTEServer.ProductVersion

Possible Values

sVersion
String specifying the version of the server.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEServer


WTEServer.Refresh Method

The Refresh method reads the server's information from the persistent storage, discarding any changes to the server that were not saved.

Syntax

WTEServer.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEServer


WTEServer.Save Method

The Save method saves the server's configuration to the persistent storage.

Syntax

WTEServer.Save( [ bSaveOnlyIfCurrent ] )

Parameters

bSaveOnlyIfCurrent
Optional. A Boolean expression. If TRUE, the save occurs only if the configuration is current. If FALSE, the save occurs regardless of whether the configuration is current. The default value for this parameter is FALSE.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEServer


WTEServer.SRModes Property

The SRModes property retrieves a collection of SRMode objects in this server.

Syntax

[ oWTESRModes = ] WTEServer.SRModes

Possible Values

oWTESRModes
Reference to the WTESRModes object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode, WTEServer, WTESRModes


WTEServer.TTSModes Property

The TTSModes property retrieves a collection of TTSMode objects in this server.

Syntax

[ oWTETTSModes = ] WTEServer.TTSModes

Possible Values

oWTETTSModes
Reference to the TTSMode object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEServer, TTSMode, WTETTSModes


WTEServer.VendorDataSets Property

The VendorDataSets property retrieves a reference to an object for storing and loading of custom data into the WTEServer object's storage.

Syntax

[ oWTEVendorDataSets = ] WTEServer.VendorDataSets

Possible Values

oWTEVendorDataSets
Reference to the WTEVendorDataSets collection object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEServer, WTEVendorDataSets


WTEServers Collection

Description

This object provides access to the collection of WTEServer objects. It is a property of WTEArray object.

Note that this collection object holds only one server for this version of WTE. The server name is the same as the computer name on which WTE is running.

Methods

Item

Properties

Count, VendorDataSets

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEServers.Count Property

The Count property retrieves the number of server objects in the collection.

Syntax

[ lCount = ] WTEServers.Count

Possible Values

lCount
Integer value specifying the number of WTEServer objects.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEServer, WTEServers


WTEServers.Item Method

The Item method retrieves the given WTEServer object from the collection.

Syntax

[ vItem = ] WTEServers.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEServer, WTEServers


WTEServers.VendorDataSets Property

The VendorDataSets property retrieves a reference to an object for storing and loading of custom data into the WTEServers object's storage.

Syntax

[ oWTEVendorDataSets = ] WTEServers.VendorDataSets

Possible Values

oWTEVendorDataSets
Reference to the WTEVendorDataSets collection object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEServers, WTEVendorDataSets


WTESRModes Collection

Description

This object is used to access the collection of SRMode objects. It is a property of the WTEServer object.

Methods

Item, Refresh

Properties

Count, VendorDataSets

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTESRModes.Count Property

The Count property retrieves the number of SRMode objects in the collection.

Syntax

[ lCount = ] WTESRModes.Count

Possible Values

lCount
Integer value specifying the number of SRMode objects.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode, WTESRModes


WTESRModes.Item Method

The Item method retrieves the given SRMode object from the collection.

Syntax

[ vItem = ] WTESRModes.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode, WTESRModes


WTESRModes.Refresh Method

The Refresh method reads all of the SRMode objects from the persistent storage, discarding any changes to the objects that were not saved.

Syntax

WTESRModes.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

SRMode, WTESRModes


WTESRModes.VendorDataSets Property

The VendorDataSets property retrieves a reference to an object for storing and loading of custom data into the WTESRModes object's storage.

Syntax

[ oWTEVendorDataSets = ] WTESRModes.VendorDataSets

Possible Values

oWTEVendorDataSets
Reference to the WTEVendorDataSets collection object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTESRModes, WTEVendorDataSets


WTETTSModes Collection

Description

This object provides access to the collection of TTSMode objects. It is a property of the WTEServer object.

Methods

Item, Refresh

Properties

Count, VendorDataSets

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTETTSModes.Count Property

The Count property retrieves the number of TTSMode objects in the collection.

Syntax

[ lCount = ] WTETTSModes.Count

Possible Values

lCount
Integer value specifying the number of TTSMode objects.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode, WTETTSModes


WTETTSModes.Item Method

The Item method retrieves the given TTSMode object from the collection.

Syntax

[ vItem = ] WTETTSModes.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode, WTETTSModes


WTETTSModes.Refresh Method

The Refresh method reads all the TTSMode objects from the persistent storage, discarding any changes to the objects that were not saved.

Syntax

WTETTSModes.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

TTSMode, WTETTSModes


WTETTSModes.VendorDataSets Property

The VendorDataSets property retrieves a reference to an object for storing and loading of custom data into the WTETTSModes collection object's storage.

Syntax

[ oWTEVendorDataSets = ] WTETTSModes.VendorDataSets

Possible Values

oWTEVendorDataSets
Reference to the WTEVendorDataSets collection object.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTETTSModes, WTEVendorDataSets


WTEVendorDataChanges Object

Description

This object defines an event that is fired by the WTEVendorDataSet object.

Events

OnChange

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEVendorDataChanges.OnChange Event

The OnChange event is fired by WTE whenever the storage of the WTEVendorDataSet object changes.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEVendorDataSet Object

Description

This object is used to access vendor data.

Methods

Refresh, RemoveValue, Save, WaitForChanges

Properties

AllNames, Name, Value

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEVendorDataSet.AllNames Property

The AllNames property retrieves all the names of the data set.

Syntax

WTEVendorDataSet.AllNames [ = pItem ]

Possible Values

pItem
Variant safe array of BSTRs.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEVendorDataSet


WTEVendorDataSet.Name Property

The Name property retrieves the name of the data set.

Syntax

WTEVendorDataSet.Name [ = sName ]

Possible Values

sName
String specifying the set name.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEVendorDataSet


WTEVendorDataSet.Refresh Method

The Refresh method reads the object from the persistent storage, discarding any changes to the object that were not saved.

Syntax

WTEVendorDataSet.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEVendorDataSet


WTEVendorDataSet.RemoveValue Method

The RemoveValue method removes the given named value from the data set.

Syntax

WTEVendorDataSet.RemoveValue( sName )

Parameters

sName
String specifying the named value to remove.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEVendorDataSet


WTEVendorDataSet.Save Method

The Save method saves the vendor information to the persistent storage.

Syntax

WTEVendorDataSet.Save()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEVendorDataSet


WTEVendorDataSet.Value Property

The Value property sets or retrieves the value associated with the given name.

Syntax

WTEVendorDataSet.Value [ = sName ]

Possible Values

sName
String specifying the parameter name for which to retrieve the value.

The property is read-write.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEVendorDataSet


WTEVendorDataSet.WaitForChanges Method

The WaitForChanges method waits for the given event before making storage changes.

Syntax

WTEVendorDataSet.WaitForChanges( hEvent );

Possible Values

hEvent
Handle of the event to wait for.

Remarks

This method is exposed to C/C++ usage only. Do use this method when working with DCOM.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEVendorDataSet


WTEVendorDataSets Collection

Description

This object is used to access the collection of WTEVendorDataSet objects.

Methods

Add, Item, Refresh, Remove, Save

Properties

Count

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEVendorDataSets.Add Method

The Add method creates a WTEVendorDataSet object, inserts it into the collection, and returns a reference to it.

Syntax

[ oWTEVendorDataSet ] WTEVendorDataSets.Add( sName )

Parameters

sName
Required. String specifying the name of the new object.

Return Value

Returns a reference to the WTEVendorDataSet object.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEVendorDataSet, WTEVendorDataSets


WTEVendorDataSets.Count Property

The Count property retrieves the number of WTEVendorDataSet objects in the collection.

Syntax

[ lCount = ] WTEVendorDataSets.Count

Possible Values

lCount
Integer value specifying the number of WTEVendorDataSet objects.

The property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEVendorDataSet, WTEVendorDataSets


WTEVendorDataSets.Item Method

The Item method retrieves the given WTEVendorDataSet object from the collection.

Syntax

[ vItem = ] WTEVendorDataSets.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEVendorDataSet, WTEVendorDataSets


WTEVendorDataSets.Refresh Method

The Refresh method reads all of the WTEVendorDataSet objects from the persistent storage, discarding any changes to the current objects that were not saved.

Syntax

WTEVendorDataSets.Refresh()

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEVendorDataSet,WTEVendorDataSets


WTEVendorDataSets.Remove Method

The Remove method removes a WTEVendorDataSet object from the collection.

Syntax

WTEVendorDataSets.Remove( lIndex )

Parameters

lIndex
Required. Name or one-based index of the WTEVendorDataSet object to remove.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEVendorDataSet, WTEVendorDataSets


WTEVendorDataSets.Save Method

Saves the configuration of all WTEVendorDataSet objects to the persistent storage.

Syntax

WTEVendorDataSets.Save( [ bSaveOnlyIfCurrent ] )

Parameters

bSaveOnlyIfCurrent
Optional. A Boolean expression. If TRUE, the save occurs only if the configuration is current. If FALSE, the save occurs regardless of whether the configuration is current. The default value for this parameter is FALSE.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEVendorDataSet, WTEVendorDataSets


Debugging Objects

The objects in this section are for creating client debugging applications only. Web Telephony Engine (WTE) applications cannot use these objects.

This section describes the following objects and their properties and methods:

  • Step Object
  • StepConstrains Object
  • WTEActiveConnection Object
  • WTEConnectionEvents Object
  • WTEService Object


Step Object

Description

A Step object represents the current state of the current telephony step. All properties are read-only.

Methods

GetAudioItem, GetMenuItem

Properties

AudioItemsLength, CutThroughMode, IsRecordType, MenuItemsLength, SubmitMenu

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


Step.AudioItemsLength Property

The AudioItemsLength property retrieves the number of audio items.

Syntax

[ lLength = ] Step.AudioItemsLength

Possible Values

lLength
Integer specifying the number of audio items.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

Step


Step.CutThroughMode Property

The CutThroughMode property retrieves the cut-through mode of the telephony step. The cut-through mode determines whether WTE accepts the caller's input while playing the audio items for an element.

Syntax

[ bCutThrough = ] Step.CutThroughMode

Possible Values

bCutThrough
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | Accept input from the caller while playing audio items.
FALSE | Wait until all audio items are played to conclusion before accepting input from the caller.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

Step


Step.GetAudioItem Method

The GetAudioItem property retrieves the specified audio item.

Syntax

[ sItem = ] Step.GetAudioItem( lIndex )

Parameters

lIndex
Required. Index of the audio item.

Return Value

Returns a string specifying the audio item. If the audio item is a wave file, the file path is wrapped in URL(). For example, if the audio item is a voice file named "introduction.wav", the string returned is "URL(introduction.wav)". If the audio item is a text string, then the string is returned.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

Step


Step.GetMenuItem Method

The GetMenuItem method retrieves the IDispatch interface of the element of the specified menu item.

Syntax

[ IDispatch = ] Step.GetMenuItem( lIndex )

Parameters

lIndex
Required. Index of the menu item for which to retrieve the IDispatch interface.

Return Value

Returns the IDispatch interface.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

Step


Step.IsRecordType Property

The IsRecordType property retrieves whether the telephony step object records. Telephony steps record if they are finished because of a TEXTAREA or INPUT TYPE=TEXT intrinsic control that has a VOICEFILE attribute on it.

Syntax

[ bRecords = ] Step.IsRecordType

Possible Values

bRecords
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | The telephony step records.
FALSE | The telephony step does not record.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

Step


Step.MenuItemsLength Property

The MenuItemsLength property retrieves the number of menu items.

Syntax

[ lItems = ] Step.MenuItemsLength

Possible Values

lItems
Integer specifying the number of menu items.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

Step


Step.SubmitMenu Property

The SubmitMenu property retrieves whether the telephony step is a "submit type" menu; that is, a menu that consists of a FORM element containing INPUT elements of the following types: button, reset, or submit. If a "submit type" menu has only one item, it is clicked automatically without offering.

Syntax

[ bIsSubmit = ] Step.SubmitMenu

Possible Values

bIsSubmit
Boolean value that has one of the following settings:
Setting | Meaning
TRUE | Telephony step is a "submit type" menu.
FALSE | Telephony step is not a "submit type" menu.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

Step


StepConstrains Object

Description

The StepConstrains object is a structure returned in the OnStepEnd event, specifying the constraints set on the ending telephony step. All properties are read-only.

Properties

InitialNumber, LegalDigits, LowerBlocked, LowerBoundary, TerminationString, Type, UpperBlocked, UpperBoundary

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


StepConstrains.InitialNumber Property

The InitialNumber property retrieves the initial number used in the process of attaching numbers to menu items.

Syntax

[ sNumber = ] StepConstrains.InitialNumber

Possible Values

sNumber
String specifying the initial number.

This property is read-only.

Remarks

This value only influences menus for which at least the length of this value is needed. For example, if the value of the InitialNumber property is 15, only menus that need two or more digits are influenced, so a menu with 20 items will be attached with the numbers 15 through 34. If there is a menu with only three menu items, it is not influenced by this value, and is attached with the numbers 1, 2 and 3, if they are available. If the InitialNumber property is 0, menus with fewer than 10 items get numbers starting from 0 (0, 1, 2), menus with more items get numbers starting from 00 (00, 01, 02), and so on.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

StepConstrains


StepConstrains.LegalDigits Property

The LegalDigits property retrieves an array of legal digits, in case the type is "Legal digits". This is used in short menus in which there are enough digits for all menu items and in buttons and check boxes in which there are only two options.

Syntax

[ sDigits = ] StepConstrains.LegalDigits

Possible Values

sDigits
String specifying the array of legal digits.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

StepConstrains


StepConstrains.LowerBlocked Property

The LowerBlocked property retrieves the lower number blocked if the Type property has both ConsBoundaries and ConsTerminator values, and if there is a conflict among some numbers that lie between the LowerBoundary and the UpperBoundary properties. Numbers between the LowerBlocked and the UpperBlocked properties are not attached to any menu items. For example, if a menu has 20 items, and the TerminationString property is "2", its items get the numbers 10 through 19 and 30 through 39; thus, the LowerBlocked property is 20 and the UpperBlocked property is 29.

Syntax

[ lLower = ] StepConstrains.LowerBlocked

Possible Values

lLower
Integer specifying the lower number blocked.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

StepConstrains, Type


StepConstrains.LowerBoundary Property

The LowerBoundary property retrieves the lower boundary if the Type property is ConsBoundaries. This is the number attached to the first menu item.

Syntax

[ lLower = ] StepConstrains.LowerBoundary

Possible Values

lLower
Integer specifying the lower boundary.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

StepConstrains


StepConstrains.TerminationString Property

The TerminationString property retrieves the string used to fulfill the constraints. Used in text controls and multiple selection.

Syntax

[ sConstraints = ] StepConstrains.TerminationString

Possible Values

sConstraints
String used to fulfill the constraints.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

StepConstrains


StepConstrains.Type Property

The Type property retrieves the type of the constraints.

Syntax

[ lType = ] StepConstrains.Type

Possible Values

lType
Integer specifying the type of constraints. It can be a combination of these values:
ConsTerminator
Termination string, used in text fields (TEXTAREA and INPUT TYPE=TEXT). The constraint is fulfilled when the string is entered.
ConsLegalDigits
A list of legal digits, used in menus in which a selection option of one digit is associated with each menu item. The constraint is fulfilled when one of these digits is pressed.
ConsBoundaries
Boundaries (between lower and upper), used in menus in which more then one digit is associated with each menu item (for example, a menu with 15 items may have the numbers 10 through 24 associated with its menu items). The constraint is fulfilled when one of the numbers is entered.
ConsAny
Any key. Possible only with INPUT TYPE=TEXT or TEXTAREA controls while recording or at speech recognition.

This property is read-only.

Remarks

If the menu is a multiple items menu used in SELECT elements with the MULTIPLE attribute on them, the constraints on the menu include the ConsTerminator value.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

StepConstrains


StepConstrains.UpperBlocked Property

The UpperBlocked property retrieves the upper number blocked if the Type property has both ConsBoundaries and ConsTerminator values, and there is a conflict among some of the numbers between the LowerBoundary and UpperBoundary properties. Numbers between the LowerBlocked and the UpperBlocked properties are not attached to any of the menu items.

Syntax

[ lUpper = ] StepConstrains.UpperBlocked

Possible Values

lUpper
Integer specifying the upper number blocked.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

StepConstrains, Type


StepConstrains.UpperBoundary Property

Retrieves the upper boundary if the type is Boundaries. This is the number attached to the last menu item.

Syntax

[ lUpper = ] StepConstrains.UpperBoundary

Possible Values

lUpper
Integer specifying the upper boundary.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

StepConstrains


WTEActiveConnection Object

Description

The WTEActiveConnection object represents an active WTE application for the debug extension.

Properties

ExtendedObjectModel, Step

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEActiveConnection.ExtendedObjectModel Property

The ExtendedObjectModel property retrieves the ExOM object related to the current call, or retrieves NULL if there is no current active call for the application.

Syntax

[ oExOM = ] WTEActiveConnection.ExtendedObjectModel

Possible Values

oExOM
Reference to the ExOM object.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

ExOM, WTEActiveConnection


WTEActiveConnection.Step Property

The Step property retrieves the Step object related to the current call, or retrieves NULL if there is no current active call for the application.

Syntax

[ oStep = ] WTEActiveConnection.Step

Possible Values

oStep
Reference to the Step object.

This property is read-only.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

Step, WTEActiveConnection


WTEConnectionEvents Object

Description

The WTEConnectionEvents object is the outgoing interface of a WTEActiveConnection object.

Events

OnOffering
Fired when a new call is offered. From this event, it is possible to get all the interfaces related to the call.
OnConnected
Fired when the call gets to the connected state is received.
OnDisconnected
Fired when the call is disconnected. Event is received.
OnDigit
Fired when a digit is detected.

Parameters — bstrDigit : The detected digit.

OnBeforeNavigate
Fired when the BeforeNavigate event from the WebBrowser control is received.

Parameters — bstrURL : The URL.

OnNavigateComplete
Fired when the NavigateComplete event from the WebBrowser control is received.

Parameters — bstrURL : The URL.

OnDocumentComplete
Fired when the DocumentComplete event from the WebBrowser control is received.

Parameters — bstrURL : The URL.

OnTagBegin
Fired when WTE reaches a new element.

Parameters — pTagElement : The element.

OnTagEnd
Fired when WTE finishes to handle an element.

Parameters — pTagElement : The element.

OnStepEnd
Fired when WTE finishes rendering a telephony step, before any audio starts. At this point the Step object has all the data concerning the current telephony step.

Parameters — pTagElement : The element that caused WTE to end the telephony step. Reason : The reason the telephony step ended. pAppConstrains : The constraints of the offering.

OnSessionEnd
Fired when the current session ends. After the return from this event handler, all the objects concerning the call, including the ExtendedObjectModel and the Step are no longer valid.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEService Object

Description

The WTEService object represents an active WTE service.

Methods

GetActiveConnection

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.


WTEService.GetActiveConnection Method

The GetActiveConnection method retrieves an active connection.

Syntax

[ oWTEActiveConnection = ] WTEService.GetActiveConnection( sAppName )

Parameters

sAppName
String specifying the name of the application.

Return Value

Returns a reference to the WTEActiveConnection object.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswtecom.idl and Mswtecom.h.
Library: Use Mswtecom.lib.

See Also

WTEActiveConnection, WTEService


Error Codes

The following error codes are defined in mswteerror.h:

Constant | Meaning
E_WTE_CORRUPTED_OBJECT_DATA | Storage contains some corrupted data. Refer to the event viewer to see the exact object name.
E_WTE_CREATE_CHILD_INSTANCE_FAILED | Attempt to create a child object failed.
E_WTE_EMPTY_STRING | String supplied as parameter is empty.
E_WTE_INVALID_SERVER_NAME | The server name is invalid.
E_WTE_NO_STORAGE | Cannot save the object — probably it is a new object, and its parent was never saved.
E_WTE_OBJECT_INVALID | The object is invalid — probably because it was deleted.
E_WTE_STRING_CONTAINS_INVALID_CHARACTERS | The string supplied as parameter contains some invalid characters.
E_WTE_VALUE_TOO_LARGE | Argument value is above the allowed limit.
E_WTE_VALUE_TOO_SMALL | Argument value is below the allowed limit.


Enumerated Types

This section describes the enumerated types used by WTE COM objects. They are defined in mswteenum.h.

  • ConstrainsType
  • DispidApplicationEventType
  • LogEventType
  • LogFieldType
  • LogFileDirectoryType
  • LogPeriodType
  • LogType
  • PCMWaveFormats
  • PrivateWTEControlsType
  • TelephonyObjectEndReasonType


ConstrainsType

The ConstrainsType enumerated types specify the types of constraints that can be placed on a menu. The constraints apply when WTE is waiting for the caller to respond to the menu. The constraint values are used in the StepConstrains.Type property.

enum ConstrainsType {
  wteConsNone,
  wteConsTerminator,
  wteConsLegalDigits,
  wteConsBoundaries,
  wteConsAny
};

Elements

wteConsNone
wteConsTerminator
Termination string, indicating end of input in text fields (TextArea and input text). The constraint is fulfilled when the string is entered.
wteConsLegalDigits
A list of valid digits, used in menus. Each one-digit option is associated with a menu item. The constraint is fulfilled when a digit is selected.
wteConsBoundaries
Two numbers, with one or more digits, that signify the first and last numbers in a menu. Used in menus where more than one digit is associated with each menu item. For example, a 15-item menu can have options numbered 10 through 24. The constraint is fulfilled when one of the numbers is entered.
wteConsAny
Any key. Can be used only with text control or TEXTAREA attribute while recording or when rendering caller's speech.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswteenum.h.

See Also

StepConstrains.Type


DispidApplicationEventType

The DispidApplicationEventType enumerated types specify the type of event triggered by WTE. These values are passed with the events defined by the WTEConnectionEvents debugging object.

enum DispidApplicationEventType {
  wteDispidApplicationEventOnOffering,
  wteDispidApplicationEventOnConnected,
  wteDispidApplicationEventOnDisconnected,
  wteDispidApplicationEventOnDigit,
  wteDispidApplicationEventOnDigitsUsed,
  wteDispidApplicationEventOnBeforeNavigate,
  wteDispidApplicationEventOnNavigateComplete,
  wteDispidApplicationEventOnDocumentComplete,
  wteDispidApplicationEventOnTagBegin,
  wteDispidApplicationEventOnTagEnd,
  wteDispidApplicationEventOnSessionValue,
  wteDispidApplicationEventOnStepEnd,
  wteDispidApplicationEventOnSessionEnd
};

Elements

wteDispidApplicationEventOnOffering
An Offering event was received from TAPI. This is the first session event.
wteDispidApplicationEventOnConnected
A Connected event was received from TAPI.
wteDispidApplicationEventOnDisconnected
A Disconnected event was received from TAPI.
wteDispidApplicationEventOnDigit
A DTMF key was pressed.
wteDispidApplicationEventOnDigitsUsed
A DTMF key was pressed, to select an option or to input to a text input field.
wteDispidApplicationEventOnBeforeNavigate
A BeforeNavigate event was received from the WebBrowser control.
wteDispidApplicationEventOnNavigateComplete
A NavigateComplete event was received from the WebBrowser control.
wteDispidApplicationEventOnDocumentComplete
A DocumentComplete event was received from the WebBrowser control.
wteDispidApplicationEventOnTagBegin
WTE started handling a tag.
wteDispidApplicationEventOnTagEnd
WTE finished handling a tag.
wteDispidApplicationEventOnSessionValue
A session value was entered or changed.
wteDispidApplicationEventOnStepEnd
A Telephony step ended.
wteDispidApplicationEventOnSessionEnd
The Telephony session ended. This is the last session event.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswteenum.h.

See Also

WTEConnectionEvents


LogEventType

The LogEventType enumerated types specify the selected logging events. The values are used in the WTEApplication.LogEventSelection property.

enum LogEventType {
  wteSessionID,
  wteLogTime,
  wteEventClass,
  wteMachineName,
  wteAddressGroup,
  wteAddress,
  wteCallerID,
  wteCalledID,
  wteReason,
  wteApplicationName,
  wteMedia,
  wtePage,
  wteDTMFValue,
  wteDestAddress,
  wteHangReason,
  wteTransferType,
  wteErrorType,
  wteInputRecordFile,
  wteCustom
};

Elements

wteSessionID
SessionID
wteLogTime
LogTime
wteEventClass
EventClass
wteMachineName
MachineName
wteAddressGroup
AddressGroup
wteAddress
Address
wteCallerID
CallerID
wteCalledID
CalledID
wteReason
Reason
wteApplicationName
ApplicationName
wteMedia
Media
wtePage
Page
wteDTMFValue
DTMFValue
wteDestAddress
DestAddress
wteHangReason
HangReason
wteTransferType
TransferType
wteErrorType
ErrorType
wteInputRecordFile
InputRecordFile
wteCustom
Custom

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswteenum.h.

See Also

WTEApplication.LogEventSelection


LogFieldType

The LogFieldType enumerated types specify the selected logging fields. The values are used in the WTELog.LogFieldSelection property.

enum LogFieldType {
  wteSessionID,
  wteLogTime,
  wteEventClass,
  wteMachineName,
  wteAddressGroup,
  wteAddress,
  wteCallerID,
  wteCalledID,
  wteReason,
  wteApplicationName,
  wteMedia,
  wtePage,
  wteDTMFValue,
  wteDestAddress,
  wteHangReason,
  wteTransferType,
  wteErrorType,
  wteInputRecordFile,
  wteCustom
};

Elements

wteSessionID
SessionID
wteLogTime
LogTime
wteEventClass
EventClass
wteMachineName
MachineName
wteAddressGroup
AddressGroup
wteAddress
Address
wteCallerID
CallerID
wteCalledID
CalledID
wteReason
Reason
wteApplicationName
ApplicationName
wteMedia
Media
wtePage
Page
wteDTMFValue
DTMFValue
wteDestAddress
DestAddress
wteHangReason
HangReason
wteTransferType
TransferReason
wteErrorType
ErrorType
wteInputRecordFile
InputRecordFile
wteCustom
Custom

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswteenum.h.

See Also

WTELog.LogFieldSelection


LogFileDirectoryType

The LogFileDirectory enumerated types specify whether the log directory is identified by a full path, or by a path relative to the install directory. The values are used in the WTELog.LogFileDirectory property.

enum LogFileDirectoryType {
  wteLogFullPath,
  wteLogRelativePath
};

Elements

wteLogFullPath
The directory of the log files is given in full path.
wteLogRelativePath
The directory of the log files is relative to WTE install directory.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswteenum.h.

See Also

WTELog.LogFileDirectory


LogPeriodType

The LogPeriodType enumerated types specify the logging periods for text files. The values are used in the WTELog.LogFilePeriod property.

enum LogPeriodType {
  wteLogInvalidPeriod,
  wteLogNoPeriod,
  wteLogDaily,
  wteLogWeekly,
  wteLogMonthly,
  wteLogYearly
};

Elements

wteLogInvalidPeriod
Indicates invalid logging period.
wteLogNoPeriod
No logging period in use.
wteLogDaily
One file per day.
wteLogWeekly
One log file per week.
wteLogMonthly
One log file per month.
wteLogYearly
One log file per year.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswteenum.h.

See Also

WTELog.LogFilePeriod


LogType

The LogType enumerated types specify the logging methods. The values are used in the WTELog.LogType property.

enum LogType {
  wteLogToFile,
  wteLogToSql
};

Elements

wteLogToFile
Logging to text log files
wteLogToSql
Logging to ODBC log

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswteenum.h.

See Also

WTELog.LogType


PCMWaveFormats

The PCMWaveFormats enumerated types specify the valid wave formats in pulse code modulation (PCM) for text to speech (TTS) and voice recording. The values are used in the WTEApplication.InputWaveFormat and WTEApplication.TTSWaveFormat properties.

enum PCMWaveFormats {
  wteDefaultWaveFormat,
  wte8000Hz8BitMono,
  wte8000Hz16BitMono,
  wte8000Hz8BitStereo,
  wte8000Hz16BitStereo,
  wte11025Hz8BitMono,
  wte11025Hz16BitMono,
  wte11025Hz8BitStereo,
  wte11025Hz16BitStereo,
  wte12000Hz8BitMono,
  wte12000Hz16BitMono,
  wte12000Hz8BitStereo,
  wte12000Hz16BitStereo,
  wte16000Hz8BitMono,
  wte16000Hz16BitMono,
  wte16000Hz8BitStereo,
  wte16000Hz16BitStereo,
  wte22050Hz8BitMono,
  wte22050Hz16BitMono,
  wte22050Hz8BitStereo,
  wte22050Hz16BitStereo,
  wte24000Hz8BitMono,
  wte24000Hz16BitMono,
  wte24000Hz8BitStereo,
  wte24000Hz16BitStereo,
  wte32000Hz8BitMono,
  wte32000Hz16BitMono,
  wte32000Hz8BitStereo,
  wte32000Hz16BitStereo,
  wte44100Hz8BitMono,
  wte44100Hz16BitMono,
  wte44100Hz8BitStereo,
  wte44100Hz16BitStereo,
  wte48000Hz8BitMono,
  wte48000Hz16BitMono,
  wte48000Hz8BitStereo,
  wte48000Hz16BitStereo
};

Elements

wteDefaultWaveFormat
Use default format
wte8000Hz8BitMono
8KHz 8 Bit, mono
wte8000Hz16BitMono
8KHz 16 Bit, mono
wte8000Hz8BitStereo
8KHz 8 Bit, stereo
wte8000Hz16BitStereo
8KHz 16 Bit, stereo
wte11025Hz8BitMono
11.025KHz 8 Bit, mono
wte11025Hz16BitMono
11.025KHz 16 Bit, mono
wte11025Hz8BitStereo
11.025KHz 8 Bit, stereo
wte11025Hz16BitStereo
11.025KHz 16 Bit, stereo
wte12000Hz8BitMono
12KHz 8 Bit, mono
wte12000Hz16BitMono
12KHz 16 Bit, mono
wte12000Hz8BitStereo
12KHz 8 Bit, stereo
wte12000Hz16BitStereo
12KHz 16 Bit, stereo
wte16000Hz8BitMono
16KHz 8 Bit, mono
wte16000Hz16BitMono
16KHz 16 Bit, mono
wte16000Hz8BitStereo
16KHz 8 Bit, stereo
wte16000Hz16BitStereo
16KHz 16 Bit, stereo
wte22050Hz8BitMono
22.050KHz 8 Bit, mono
wte22050Hz16BitMono
22.050KHz 16 Bit, mono
wte22050Hz8BitStereo
22.050KHz 8 Bit, stereo
wte22050Hz16BitStereo
22.050KHz 16 Bit, stereo
wte24000Hz8BitMono
24KHz 8 Bit, mono
wte24000Hz16BitMono
24KHz 16 Bit, mono
wte24000Hz8BitStereo
24KHz 8 Bit, stereo
wte24000Hz16BitStereo
24KHz 16 Bit, stereo
wte32000Hz8BitMono
32KHz 8 Bit, mono
wte32000Hz16BitMono
32KHz 16 Bit, mono
wte32000Hz8BitStereo
32KHz 8 Bit, stereo
wte32000Hz16BitStereo
32KHz 16 Bit, stereo
wte44100Hz8BitMono
44.1KHz 8 Bit, mono
wte44100Hz16BitMono
44.1KHz 16 Bit, mono
wte44100Hz8BitStereo
44.1KHz 8 Bit, stereo
wte44100Hz16BitStereo
44.1KHz 16 Bit, stereo
wte48000Hz8BitMono
48KHz 8 Bit, mono
wte48000Hz16BitMono
48KHz 16 Bit, mono
wte48000Hz8BitStereo
48KHz 8 Bit, stereo
wte48000Hz16BitStereo
48KHz 16 Bit, stereo

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswteenum.h.

See Also

WTEApplication.InputWaveFormat, WTEApplication.TTSWaveFormat


PrivateWTEControlsType

The PrivateWTEControlsType enumerated types specify user-defined service-control codes. The range for these codes is 128 – 255. The enumerated types are used in the Win32 ControlService function.

enum PrivateWTEControlsType {
  wteServicePauseSoft,
  wteServiceStopSoft,
  wteServiceFlushLog,
  wteServiceRefreshStorage
};

Elements

wteServicePauseSoft
Does not accept new calls, but allows existing calls to continue before they are disconnected. Does not shut down the service.
wteServiceStopSoft
Refuses to accept new calls, but allows existing calls to continue for the specified amount of time before the service stops.
wteServiceFlushLog
Flushes all log data to disk.
wteServiceRefreshStorage
Synchronizes with changes in the configuration data — reads the configuration data from the storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswteenum.h.


TelephonyObjectEndReasonType

The TelephonyObjectEndReasonType enumerated types specify the reason why the current telephony object ended.

enum TelephonyObjectEndReasonType {
  wteEndReasonScopeEnd,
  wteEndReasonCutThroughChanged,
  wteEndReasonIntrinsicControl,
  wteEndReasonTable,
  wteEndReasonIncompatibleMenuItemType,
  wteEndReasonForm,
  wteEndReasonPageEnd,
  wteEndReasonSelectionTimeout,
  wteEndReasonSelectionError
};

Elements

wteEndReasonScopeEnd
Telephony object ended when the scope of the menu owner ended.
wteEndReasonCutThroughChanged
Telephony object ended when the cut-through mode changed.
wteEndReasonIntrinsicControl
Telephony object ended when an intrinsic control was offered to the caller.
wteEndReasonTable
Telephony object ended when a table rendering completed (when RenderTablesAsTabularData property is TRUE).
wteEndReasonIncompatibleMenuItemType
Telephony object ended when an incompatible menu item broke the menu.
wteEndReasonForm
Telephony object ended when the form ended.
wteEndReasonPageEnd
Telephony object ended when the page ended.
wteEndReasonSelectionTimeout
Telephony object ended when a time-out occurred.
wteEndReasonSelectionError
Telephony object ended when a selection error occurred.

Requirements

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Mswteenum.h.


Events

This section describes the events that are particularly important to a Web Telephony Engine (WTE) application:

  • onchange
  • onclick
  • onkeypress
  • onselectiontimeout
  • onselectionerror

In addition to these events, a WTE application also receives all the standard events fired by Internet Explorer. For more information about standard events, see the Web Workshop on the Microsoft Developer Network (MSDN™) Web site.

For more information about event handling in a WTE application, see Handling Events.


onchange

The onchange event fires when an intrinsic control's value is changed.

This event will not bubble.

The WTE supports events in all three modes supported by Microsoft® Internet Explorer — inline, using FOR and EVENT attributes, and Microsoft Visual Basic® style.

If the default scripting language in the document (specified by the first LANGUAGE attribute defined) is Visual Basic Scripting Edition (VBScript), the scripting language should be specified on the element containing the event handler.

Fired on

INPUT TYPE=text, SELECT, TEXTAREA


onclick

The onclick event fires when the caller chooses a menu item, clicks a button, or selects a check box, or when an automatically clicked button is clicked.

This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

Fired on

A, AREA, BUTTON, INPUT TYPE=[button | checkbox | image | reset | radio | submit]


onkeypress

The onkeypress event fires when a caller presses a key for the text controls. The ASCII code of the digit that the caller pressed can be found in the external.window.Event.keyCode property, and can be changed by this event handler. If the code is changed to 0, the digit is ignored.

This event will not bubble.

The WTE supports events in all three modes supported by Internet Explorer — inline, using FOR and EVENT attributes, and Visual Basic style.

If the default scripting language in the document (specified by the first LANGUAGE attribute defined) is VBScript, the scripting language should be specified on the element containing the event handler.

Fired on

INPUT TYPE=text, SELECT, TEXTAREA


onselectiontimeout

The onselectiontimeout event fires when the time-out event occurs on the menu owner or intrinsic control.

This event will not bubble.

The WTE supports events in all three modes supported by Internet Explorer — inline, using FOR and EVENT attributes, and Visual Basic style.

If the default scripting language in the document (specified by the first LANGUAGE attribute defined) is VBScript, the scripting language should be specified on the element containing the event handler.

A natural element for associating the onselectiontimeout handler is the menu owner or the control itself. For a radio-button menu (created by INPUT TYPE=radio) the error handler may be associated by the group name. Note that the handler of this event can change the window.external.event.returnValue property.

Fired on

BODY, DIR, FIELDSET, FORM, IMG, INPUT TYPE=[button | checkbox | image | radio | reset | submit], MENU, P, TEXTAREA

See Also

Handling Time-outs and Non-valid Keys


onselectionerror

The onselectionerror event fires when the user presses a non-valid Dual Tone Multi-Frequency (DTMF) key—one that cannot be used as input for the current menu or control.

This event will not bubble.

The WTE supports events in all three modes supported by Internet Explorer — inline, using FOR and EVENT attributes, and Visual Basic style.

If the default scripting language in the document (as specified by the first LANGUAGE attribute defined) is VBScript, the scripting language should be specified on the element containing the event handler.

A natural element for associating the onselectionerror handler is the menu owner or the control itself. For a radio-button menu (created by INPUT TYPE=radio) the error handler may be associated by the group name. Note that the handler of this event can change the window.external.event.returnValue property.

Fired on

BODY, DIR, FIELDSET, FORM, IMG, INPUT, MENU, P

See Also

onselectiontimeout


HTML Elements and Attributes

The WTE uses only standard HTML elements. However, Microsoft® has defined five items intended to optimize the use of HTML for aural browsers. Microsoft is working with the World Wide Web Consortium (W3C) to add the following items to the next version of HTML.

Attributes

GRAMMAR
When used with menu items, the GRAMMAR attribute specifies a set of alternative phrases that the caller can speak to select the item. When used with entry fields, it specifies a grammar file that hints at what the caller is expected to say. For more information, see Using the GRAMMAR Attribute.
VOICEFILE
The VOICEFILE attribute specifies a wave file that the WTE engine plays instead of using TTS to render the text associated with the given element. For more information, see Using Wave Files.

Events

onselectiontimeout
The onselectiontimeout event allows you to react with a script to a time-out event on caller input. For more information, see Handling Time-outs and Non-valid Keys.
onselectionerror
The onselectionerror event allows the author to react with a script to an error event on caller input. For more information, see Handling Time-outs and Non-valid Keys.

Cascading Style Sheet Properties

cut-through
The cascading style sheet (CSS) cut-through property allows you to determine whether the caller must listen to all menu announcements before selecting an item, or whether the caller can skip the announcements and select an item. For more information, see Receiving a Selection from the Caller.

This section contain descriptions of the following attributes:

  • A
  • AREA
  • BODY
  • BUTTON
  • CAPTION
  • DIR
  • FIELDSET
  • FORM
  • FRAME
  • FRAMESET
  • IMG
  • INPUT
  • LABEL
  • MAP
  • MENU
  • OPTION
  • P
  • SELECT
  • TABLE
  • TD
  • TH
  • TR
  • TEXTAREA


A

<A
ACCESSKEY=key
CLASS=classname
HREF=url
ID=value
NAME=name
STYLE=css1-properties
VOICEFILE=url
GRAMMAR=strings
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
event = script
>

Specifies an anchor element. If the element has the HREF attribute, the WTE treats the anchor as a menu item. Otherwise, the WTE treats the anchor as the destination of a link.

Attributes

ACCESSKEY= key
Specifies the key attached to the menu item. If the ACCESSKEY attribute is not defined or the ACCESSKEY defined cannot be associated with the menu item, the WTE automatically assigns an ACCESSKEY attribute. For more information, see Assigning Dual Tone Multi-Frequency Digits to Menu Items.
CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed cascading style sheet (CSS) with the element.
HREF= url
Specifies the destination URL or anchor point.
ID= value
An SGML identifier (ID) used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
NAME= name
Specifies the name of the anchor.
STYLE= css1-properties
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the voice file attached with this element.
GRAMMAR= strings
Specifies a set of alternative words or phrases for the menu item. The caller can select the menu item by speaking any word or phrase in the set. This attribute is ignored if SR is not enabled.
LANGUAGE= JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT
Specifies the language in which the current script is written and invokes the proper scripting engine. The default value is JAVASCRIPT.
Language | Description
JAVASCRIPT, JSCRIPT | The scripting language is written in Microsoft JScript®.
VBS, VBSCRIPT | The scripting language is written in Microsoft Visual Basic® Scripting Edition (VBScript).

event
Can be the onclick event or another event.

Remarks

No intrinsic controls are treated inside an anchor.

An anchor inside the BUTTON element is not a menu item.

Both the start and end tags are required.

Example

<P>
<A AccessKey="1" HREF="oredr.htm">Orders.</A>
<A AccessKey="2" HREF="more.htm">More items.</A>
</P>


AREA

ACCESSKEY=key
ALT=text
CLASS=classname
HREF=url
ID=value
NOHREF
STYLE=css1-properties
VOICEFILE=url
GRAMMAR=strings
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
event=script
>

Specifies a menu item inside a client-side image MAP if the map is specified as the USEMAP attribute of an IMG element.

Attributes

ACCESSKEY= key
Specifies the key attached to the menu item. If the ACCESSKEY attribute is not defined or the ACCESSKEY defined cannot be associated with the menu item, the WTE automatically assigns an ACCESSKEY attribute. For more information, see Assigning Dual Tone Multi-Frequency Digits to Menu Items.
ALT= text
The text associated with the menu item.
CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
HREF= url
Specifies the destination URL or anchor point.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
NOHREF
Indicates that this item is not a menu item.
STYLE= css1-properties
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the voice file attached with this element.
GRAMMAR= strings
Specifies a set of alternative words or phrases for the menu item. The caller can select the menu item by speaking any word or phrase in the set. This attribute is ignored if SR is not enabled. LANGUAGE= JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT
Specifies the language the in which current script is written and invokes the proper scripting engine. The default value is JAVASCRIPT.
Language | Description
JAVASCRIPT, JSCRIPT | The scripting language is written in JScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.

event

Can be the onclick event or another events. Under the WTE, when the caller chooses a menu item from a image map, the onclick event fires only on the AREA element and bubbles to its ancestors. It is not fired on the IMG element itself if the element is not an ancestor of the AREA element.

Remarks

This is an empty element and does not require a closing element.

Example

<MAP>
<AREA AccessKey="7" HREF="http://www.microsoft.com/ie/">
<AREA HREF="sample.htm">
<AREA NOHREF>
</MAP>


BODY

<BODY
CLASS=classname
ID=value
STYLE=css1-properties
VOICEFILE=url
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
event = script
>

Specifies beginning and end of document body. This element can be used as the default menu owner of menu items. The end tag is required.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can be referenced only by ordinal position.
STYLE= css1-properties
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the voice file attached with this element.
LANGUAGE= JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT
Specifies the language in which the current script is written and invokes the proper scripting engine. The default value is JAVASCRIPT.
Language | Description
JAVASCRIPT, JSCRIPT | The scripting language is written in JScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.

event
Can be one or more of these events:

onselectionerror

onselectiontimeout

Remarks

This element is a block element.


BUTTON

<BUTTON
ACCESSKEY=string
CLASS=classname
DISABLED
ID=value
STYLE=css1-properties
VOICEFILE=url
GRAMMAR=strings
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
event = script
>

Renders as a menu item if contained inside a FIELDSET attribute and no current menu owner is under FIELDSET. Renders as a stand-alone button otherwise.

Attributes

ACCESSKEY= key
Specifies the key attached to the menu item. If the ACCESSKEY attribute is not defined or the ACCESSKEY defined cannot be associated with the menu item, the WTE automatically assigns an ACCESSKEY attribute. For more information, see Assigning Dual Tone Multi-Frequency Digits to Menu Items.
CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
DISABLED
Used to disable an element. Does not affect whether the button breaks or begins a menu.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
STYLE= css1-properties
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the voice file attached with this element.
GRAMMAR= strings
Specifies a set of alternative words or phrases for the menu item. The caller can select the menu item by speaking any word or phrase in the set. This attribute is ignored if SR is not enabled.
LANGUAGE= JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT
Specifies the language in which the current script is written and invokes the proper scripting engine. The default value is JAVASCRIPT.
Language | Description
JAVASCRIPT, JSCRIPT | The scripting language is written in JScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.

event
Can be one or more of these events:

onclick

onselectionerror

onselectiontimeout

Remarks

This element is a block element.

Both the start and end tags are required.

A stand-alone button breaks any menu in which it is contained.

Intrinsic controls and anchors inside the button are not rendered as such.


CAPTION

<CAPTION
CLASS=classname
ID=value
STYLE=css1-properties
VOICEFILE=url
>

Specifies a caption for a TABLE attribute.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
STYLE= css1-properties
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the voice file attached with this element.

Remarks

This element is a block element.

Both the start and end tags are required.


DIR

<DIR
CLASS=classname
ID=value
STYLE=css1-properties
VOICEFILE=url
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
event = script
>

Serves as a menu owner if it is the lowest ancestor of a menu item. If so, this element's end tag closes the menu.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can be referenced only by ordinal position.
STYLE= css1-properties
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the voice file attached with this element.
LANGUAGE= JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT
Specifies the language in which the current script is written and invokes the proper scripting engine. The default value is JAVASCRIPT.
Language | Description
JAVASCRIPT, JSCRIPT | The scripting language is written in JScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.

event
Can be one or more of these events:

onselectionerror

onselectiontimeout

Remarks

This element is a block element.

Both the start and end tags are required.


FIELDSET

<FIELDSET
CLASS=classname
ID=value
STYLE=css1-properties
VOICEFILE=url
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
event = script
>

Serves as a menu owner if it is the lowest ancestor of a menu item. If so, this element's end tag closes the menu. For BUTTON elements, the FIELDSET element is the only legal menu owner. They will be treated as menu items only if they are contained in a FIELDSET element that is not an ancestor of an existing menu owner.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID names must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created and can be referenced only by ordinal position.
STYLE=
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the voice file attached with this element.
LANGUAGE= JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT
Specifies the language in which the current script is written and invokes the proper scripting engine. The default value is JAVASCRIPT.
Language | Description
JAVASCRIPT, JSCRIPT | The scripting language is written in JScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.

event
Can be one or more of these events:

onselectionerror

onselectiontimeout

Remarks

Both the start and end tags are required.


FORM

<FORM
ACTION=url
CLASS=classname
ENCTYPE=encoding
ID=value
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT
METHOD=GET | POST
NAME=name
STYLE=css1-properties
TARGET=window_name
| _blank | _parent | _search | _self | _top
TITLE=text
event = script
>

Serves as a menu owner of all the INPUT elements inside it.

Attributes

ACTION
Sets or retrieves the URL to which the FORM content is to be sent for processing.
CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
ENCTYPE
Sets or retrieves the MIME encoding for the form.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can be referenced only by ordinal position.
LANGUAGE= JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT
Specifies the language in which the current script is written and invokes the proper scripting engine. The default value is JAVASCRIPT.
Language | Description
JAVASCRIPT, JSCRIPT | The scripting language is written in JScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.

METHOD=GET | POST
Specifies how to send the form data to the server.
Value | Meaning
GET | Appends the arguments to the action URL and open it as if it were an anchor.
POST | Sends the data through an HTTP post transaction.

NAME
Specifies the name of the form.
STYLE
Specifies an inline style sheet for the element.
TARGET=window_name
| _blank | _parent | _search | _self | _top
Specifies the window or frame at which to target the contents. If no frame or window exists that matches the specified target, a new window is opened for the specified link. If no target is specified, the default is "_self" for a link within the same site or "_top" if the site is external. Special target values are listed here:
Value | Meaning
_blank | Specifies to load the link into a new unnamed window.
_parent | Specifies to load the link into the immediate parent of the document containing the link.
_self | Specifies to load the link into the same window in which the link was clicked.
_top | Specifies to load the link into the full body of the current window.

TITLE
Advisory information (a ToolTip) for the <FORM>.
event
Can be one or more of these events:

onclick

onselectionerror

onselectiontimeout

Remarks

Internet Explorer constructs an HTTP request from all the information in the form. It then sends that request to the location specified in the ACTION attribute on the FORM element. A Web telephony application can send an HTTP request using elements in a form or using the same elements without a form. This is because, either way, the WTE renders each element sequentially, waiting for the caller's response before rendering the next element.

See Also

INPUT


FRAME

<FRAME
CLASS=classname
ID=value
NAME=window_name
| _blank | _parent | _self | _top
SRC=url
>

Specifies an individual frame within a FRAMESET attribute.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
NAME= window_name
| _blank | _parent | _self | _top
Specifies the window or frame at which to target the contents. If no frame or window exists that matches the specified target, a new window is opened for the specified link. If no target is specified, the default is "_self" for a link within the same site or "_top" if the site is external. Special target values are listed here:
Value | Meaning
_blank | Specifies to load the link into a new unnamed window.
_parent | Specifies to load the link into the immediate parent of the document containing the link.
_self | Specifies to load the link into the same window in which the link was clicked.
_top | Specifies to load the link into the full body of the current window.

SRC= url
Specifies a URL for the associated file.

Remarks

This element is a block element.

See Also

FRAMESET, NOFRAMES, Frames


FRAMESET

<FRAMESET
CLASS=classname
COLS=col-widths
ID=value
ROWS=row-heights
>

Sets the number and size of vertical and horizontal frames for a compound document. Compound documents are rendered according to the frame-rendering rules described in Frames. Use the FRAME element within the FRAMESET attribute to define the content and properties of the individual frames. You can also nest FRAMESET elements to create frames within a frame.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
COLS= col-widths
A comma-delimited list of frames to create. Each item in the list contains the initial size of the column. You can specify the column dimensions by percentage (%), pixels, or a relative size (*)
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
ROWS= row-heights
A comma-delimited list of frames to create. Each item in the list contains the initial size of the row. You can specify the row dimensions by percentage (%), pixels, or a relative size (*).

Remarks

A FRAMESET element organizes multiple frames on the screen. Only frames and nested FRAMESET elements are valid within a frameset.

This element is a block element.

Both the start and end tags are required.

See Also

FRAME, NOFRAMES


IMG

<IMG
CLASS=classname
ID=value
STYLE=css1-properties
USEMAP=url
VOICEFILE=url
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
event = script
>

Serves as a menu owner if the USEMAP attribute is specified with a client-side map, with the AREA elements of the specified MAP attribute as menu items. If they are already inside a menu owner, the items are joined to the current menu.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can be referenced only by ordinal position.
STYLE= css1-properties
Specifies an inline style sheet for the element.
USEMAP= url.
Only client side maps, specified as #MapID are considered client side maps.
VOICEFILE= url
Specifies the voice file attached with this element.
LANGUAGE= JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT
Specifies the language in which the current script is written and invokes the proper scripting engine. The default value is JAVASCRIPT.
Language | Description
JAVASCRIPT, JSCRIPT | The scripting language is written in JScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.

event
Can be one or more of these events:

onselectionerror

onselectiontimeout

Remarks

When a caller chooses an item from an IMG menu, the WTE clicks on the corresponding AREA element. The onclick event is bubbled up to the containing MAP element, but is not bubbled to the IMG.

Example

<IMG USEMAP=#MyMap>


INPUT

<INPUT
ACCESSKEY=key
CLASS=classname
DISABLED
ID=value
MAXLENGTH=n
READONLY
STYLE=css1-properties
TYPE=BUTTON | CHECKBOX | FILE | HIDDEN | IMAGE | PASSWORD | RADIO | RESET | SUBMIT | TEXT
VALUE=value
VOICEFILE=url
GRAMMAR=url | strings
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
event = script
>

Specifies a form input control.

Attributes

ACCESSKEY= key
Specifies the key attached to the menu item. If the ACCESSKEY attribute is not defined or the ACCESSKEY defined cannot be associated with the menu item, the WTE automatically assigns an ACCESSKEY attribute. For more information, see Assigning Dual Tone Multi-Frequency Digits to Menu Items.
CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
DISABLED
Used to disable an element. Does not affect whether the element breaks or begins a menu.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can be referenced only by ordinal position.
MAXLENGTH= n
Indicates the maximum number of characters that can be entered into a text control. This attribute applies to INPUT elements that have the TYPE=text or TYPE=password attribute.
READONLY
Causes the element's contents to be read-only. Affects the control in the same way as disable does. This attribute applies to INPUT elements that have the TYPE=text or TYPE=password attribute.
STYLE= css1-properties
Specifies an inline style sheet for the element.
TYPE=[button | checkbox | file | hidden | image | password | radio | reset | submit | text
Specifies the type of intrinsic control. The default is text.
Type | Description
button | Inside a form, it is rendered as a form button. Otherwise rendered as a stand-alone button.
Checkbox | Used for Boolean menus. Rendered as a menu with two available through the SelectCheckBoxKey and ClearCheckBoxKey properties.
File | Breaks any menu, like a disabled control.
Hidden | This element is ignored .
image | Rendered as a form button.
Password | The same as the TEXT input type.
Radio | Rendered as a menu, with all radio elements with the same name and scope (inside or outside a FORM). Radio elements are rendered as menu items in the order they appear in the page, regardless of the first radio element actually found. Disabled radio elements are not rendered. Radio elements belonging to the current element group are not rendered again while the WTE is in their scope. That is, radio elements outside a form are not rendered again while in the same page, and radio elements inside a form are not rendered again unless the form is exited and re-entered, or the reset button is pressed. Outside a form, radio buttons are rendered whenever the Internet Explorer Reload or Refresh methods are invoked. Inside a form, re-rendering takes place just as it does during normal navigation, and is determined by the site whose URL is shown in the Internet Explorer Address list.
Reset | Rendered as a form button. If it is clicked when the cursor is inside a form, radio menus inside this form are re-rendered again whenever the WTE meets a radio element with a name that has already been rendered. Using OnReset = "return false;" to cancel the default behavior has no effect on the WTE.
Submit | Rendered as a form button.
Text | Used for a single-line text-entry field. All DTMF until the termination string or MAXLENGTH digits are entered as its value.

VALUE= value
Used as the text attached to form buttons in TTS rendering mode.
VOICEFILE= url
Specifies the voice file attached with this element.
GRAMMAR= url | strings
If the value of the TYPE attribute is text, the GRAMMAR attribute specifies the grammar (.cfg) file, in SAPI format, that provides a hint to the engine about what the caller is expected to say. The grammar file replaces the default grammar file that the SR engine uses in dictation. The default grammar file does not provide any hint to the engine. Use the format "url(filename.cfg)" to specify the .cfg file. Note that the WTE requires a grammar file to be in Unicode format. For the complete syntax of .cfg files, see the SAPI 4.0a documentation.

If the value of the TYPE attribute is not text, the GRAMMAR attribute specifies a set of alternative words or phrases for the menu item. The caller can select the menu item by speaking any word or phrase in the set. This attribute is ignored if SR is not enabled.

LANGUAGE= JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT
Specifies the language in which the current script is written and invokes the proper scripting engine. The default value is JAVASCRIPT.
Language | Description
JAVASCRIPT, JSCRIPT | The scripting language is written in JScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.

event
Can be one or more of these events:

onclick

onselectiontimeout

onselectionerror

onchange

Remarks

All form buttons (BUTTON, SUBMIT, RESET and IMAGE) are rendered alike—as menu items inside a form and as stand-alone buttons outside a form. Their impact on the document is not changed. A form button always breaks a non-form button menu, and no other menu items can join a form-button menu. If a form-button menu contains only a single item, the WTE will select it without offering it to the caller.

Any control that is not a form button will break any menu, even if it is disabled or read-only.

See Also

FORM


LABEL

<LABEL
CLASS=classname
FOR=ID
ID=value
STYLE=css1-properties
VOICEFILE=url>

Specifies a label for a control-like element, BUTTON or INPUT. The content between the start and end tags defines the label text. If the label is associated with a control, it is rendered according to the label rendering rules described in Labels.

LABEL attributes are used to associate a portion of text with an INPUT element. You can use the associated text along with cue-before and cue-after CSS properties to provide additional context to a caller.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
FOR= ID
Specifies the ID for the control-like element with which the label is associated. If the ID does not exist, the label is not associated with any control and is rendered as an unknown element.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can be referenced only by ordinal position.
STYLE= css1-properties
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the voice file attached with this element.

Remarks

Labels cannot be nested.

Both the start and end tags are required.


MAP

<MAP
CLASS=classname
ID=value
NAME=name
STYLE=css1-properties
VOICEFILE=url
GRAMMAR=strings
>

Specifies a collection of menu items for an IMG attribute that specified the map as its client-side map with the USEMAP attribute.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can be referenced only by ordinal position.
NAME= name
Specifies the name of the window.
STYLE= css1-properties
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the voice file attached with this element.
GRAMMAR= strings
Specifies a set of alternative words or phrases for the menu item. The caller can select the menu item by speaking any word or phrase in the set. This attribute is ignored if SR is not enabled.

Remarks

Both the start and end tags are required.


MENU

<MENU
CLASS=classname
ID=value
STYLE=css1-properties
VOICEFILE=url
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
event = script
>

Serves as a menu owner if it is the lowest ancestor of a menu item. If so, this element's end tag closes the menu.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
STYLE= css1-properties
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the voice file attached with this element.
LANGUAGE= JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT
Specifies the language in which the current script is written and invokes the proper scripting engine. The default value is JAVASCRIPT.
Language | Description
JAVASCRIPT, JSCRIPT | The scripting language is written in JScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.

event
Can be one or more of these events:

onselectionerror

onselectiontimeout

Remarks

This element is a block element.

Both the start and end tags are required.


OPTION

<OPTION
CLASS=classname
ID=value
SELECTED
VOICEFILE=url
GRAMMAR=strings
>

Denotes one menu item in a SELECT menu.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
SELECTED
Indicates that this item is the default. If not present, the first item is selected by default. In multiple select menus, this item is always one of the selected items.
VOICEFILE= url
Specifies the voice file attached with this element.
GRAMMAR= strings
Specifies a set of alternative words or phrases for the menu item. The caller can select the menu item by speaking any word or phrase in the set. This attribute is ignored if SR is not enabled.

Remarks

This element is a block element.

The start tag is required, and the end tag is optional.

The text in the option's line is the text associated with the menu item when rendered in TTS mode.


P

<P
CLASS=classname
ID=value
STYLE=css1-properties
VOICEFILE=url
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
event = script
>

Serves as a menu owner if it is the lowest ancestor of a menu item. If so, this element's end tag closes the menu.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
STYLE= css1-properties
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the voice file attached with this element.
LANGUAGE= JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT
Specifies the language in which the current script is written and invokes the proper scripting engine. The default value is JAVASCRIPT.
Language | Description
JAVASCRIPT, JSCRIPT | The scripting language is written in JScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.

event
Can be one or more of these events:

onselectionerror

onselectiontimeout

Remarks

This element is a block element.

The start tag is required, and the end tag is optional.


SELECT

<SELECT
CLASS=classname
DISABLED
ID=value
MULTIPLE
NAME=name
STYLE=css1-properties
VOICEFILE=url
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
event = script
>

Serves as a menu owner, with all the enclosed OPTION elements as menu items.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
DISABLED
Used to disable an element. Does not affect whether the SELECT breaks a menu.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can only be referenced only by ordinal position.
MULTIPLE
Indicates a multiple selection menu. Multiple-selection SELECT element starts their operation in a way similar to the single-selection SELECT element. Multiple selections can be made until the termination key is pressed.
NAME= name
Specifies the name of the control, bookmark, or applet.
STYLE= css1-properties
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the voice file attached with this element.
LANGUAGE= JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT
Specifies the language in which the current script is written and invokes the proper scripting engine. The default value is JAVASCRIPT.
Language | Description
JAVASCRIPT, JSCRIPT | The scripting language is written in JScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.

event
Can be one or more of these events:

onchange

onselectiontimeout

onselectionerror

Remarks

Both the start and end tags are required.

The announcement of the multiple-selection menu created by using the SELECT element with the MULTIPLE attribute includes all audio items (either voice files or textual) gathered before the element, the cue-before CSS property and the VOICEFILE attribute on the SELECT element, the voice files and cues from all of the OPTION elements, and finally, the cue-after CSS property on the SELECT element. When a caller makes a choice, the announcement of the menu starts from the item that is next to the chosen one. If an error (either a time-out or an non-valid key) is detected, announcements of all menu items are rendered excluding those that were already chosen. Audio items on the SELECT control itself are always rendered.


TABLE

<TABLE
CLASS=classname
ID=value
STYLE=css1-properties
SUMMARY=text/url
VOICEFILE=url
>

Plays tabular data to the caller if the RenderTablesAsTabularData property is TRUE, according to the table rendering rules described in Tables. Use the TR, TD, and TH elements in the container to create the rows, columns, and cells.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can be referenced only by ordinal position.
STYLE= css1-properties
Specifies an inline style sheet for the element.
SUMMARY= text/url
Used to provide the summary of the table. The summary is played after the voice file specified by the VOICEFILE attribute on the TABLE element. If wrapped with URL(), the summary is considered to be URL, otherwise as text.
VOICEFILE= url
Specifies the voice file attached with this element.

Remarks

Both the start and end tags are required.

See Also

TD, TR, TH Tables


TD

<TD
ABBR=text
CLASS=classname
COLSPAN=n
HEADERS=value-list
ID=value
ROWSPAN=n
STYLE=css1-properties
VOICEFILE=url
>

Specifies a cell in a table. This element is valid only within a row in a table. You must use a TR element before using TD. All attributes are optional.

Attributes

ABBR= text
Specifies an abbreviated form of the cells data. If exists, replaces all the content of the cell if in TTS mode.
CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
COLSPAN= n
Specifies how many columns in the TABLE this cell should span.
HEADERS= value-list
Specifies the list of header cells that provide header information for the current data cell. The value of the attribute is a space-separated list of cell ID attributes.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can be referenced only by ordinal position.
ROWSPAN= n
Specifies the number of rows that this cell should span in the TABLE.
STYLE= css1-properties
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the voice file attached with this element.

Remarks

This element is a block element.

Both the start and end tags are required.

See Also

TABLE, TH, TR


TH

<TH
ABBR=text
CLASS=classname
COLSPAN=n
HEADERS=value-list
ID=value
ROWSPAN=n
STYLE=css1-properties
VOICEFILE=url
>

Creates a row or column heading in a table. The element is similar to the TD element but emphasizes the text in the cell to distinguish it from text in TD cells. The end tag is optional.

Attributes

ABBR= text
Specifies an abbreviated form of the cells data. If the attribute exists, it replaces all the content of the cell if in TTS mode.
CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
COLSPAN= n
Specifies how many columns in the TABLE this cell should span.
HEADERS= value-list
Specifies the list of header cells that provide header information for the current header cell. The value of the attribute is a space-separated list of cell ID attributes.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can be referenced only by ordinal position.
ROWSPAN= n
Specifies the number of rows that this cell should span in the TABLE.
STYLE= css1-properties
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the voice file attached with this element.

Remarks

This element is a block element.

Both the start and end tags are required.


TR

<TR
CLASS=classname
ID=value
STYLE=css1-properties
VOICEFILE=url
>

Creates a row in a table.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can be referenced only by ordinal position.
STYLE= css1-properties
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the voice file attached with this element.

Within a row, the following elements are valid:

  • TD
  • TH

Remarks

This element is a block element.

Both the start and end tags are required.


TEXTAREA

<TEXTAREA
CLASS=classname
DISABLED
NAME=name
READONLY
STYLE=css1-properties
VOICEFILE=url
GRAMMAR=url
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
event = script
>

Records spoken input from the caller if the VOICEFILE attribute is specified. If not, this element collects DTMF digits and is similar to the INPUT element.

Attributes

CLASS= classname
Specifies the class of the element being defined. This is used to associate a subclassed style sheet with the element.
DISABLED
Used to disable an element. Does not affect whether the control breaks or begins a menu.
ID= value
An SGML ID used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore ("_") can be used in the ID name. The ID should be unique throughout the document. If more than one object with the same ID exists in a document, a collection of those named items is created that can be referenced only by ordinal position.
NAME= name
Specifies the name of the control, bookmark, or applet.
READONLY
Causes the element's contents to be read-only. This attribute affects the control in the same way as the DISABLE attribute.
STYLE= css1-properties
Specifies an inline style sheet for the element.
VOICEFILE= url
Specifies the destination file of the recording if present. The file is recorded in a format of 8Khz 16Bit Mono. If not specified the control is rendered the same as INPUT text does. If the path to the file is in HTTP or HTTPS, the file is uploaded to the server and saved there in the specified location. The virtual directory in the server must have "write" permission. Upload functionality requires the WININET.DLL version to be at least 5.622.
GRAMMAR= url
Specifies the grammar (.cfg) file, in SAPI format, that provides a hint to the engine about what the caller is expected to say. The grammar file replaces the default grammar file that the SR engine uses in dictation. The default grammar file does not provide any hint to the engine. Use the format "url(filename.cfg)" to specify the .cfg file. Note that the WTE requires a grammar file to be in Unicode format. For the complete syntax of .cfg files, see the SAPI 4.0a documentation.
LANGUAGE= JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT
Specifies the language in which the current script is written and invokes the proper scripting engine. The default value is JAVASCRIPT.
Language | Description
JAVASCRIPT, JSCRIPT | The scripting language is written in JScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.

event
Can be one or more of these events:

onchange

onselectiontimeout

Remarks

Both the start and end tags are required.


CSS Properties

The WTE supports the following cascading style sheet (CSS) properties:

  • cue, cue-before, cue-after
  • cut-through
  • display
  • media
  • pitch
  • speak-header-cell
  • speech-rate
  • volume


cue, cue-before, cue-after

Value: [URL | text | none]
Initial: none
Applies to: all elements
Inherited: no
Percentage values: N/A

The cue, cue-before, and cue-after CSS properties cause audio items to play before and/or after a given element. The cue property plays the same audio item before and after the element. The cue-before and cue-after properties let you specify separate audio items for before and/or after the element.

The value of these properties can be either the URL of a .wav file, or a text string for the TTS engine to render. The value is considered to be a URL if it is wrapped with 'URL( )', and as text otherwise.

The audio item specified by the cue or cue-before property is played before the item associated with the VOICEFILE attribute of the element. The cue-after property is played after all the audio items of the element and all its children. In other words, all cues on an element, either textual or voice files, are played independently of whether the VOICEFILE attribute is defined on the element. However, the VOICEFILE attribute on the parent element cancels playback of textual cues on child elements.

For information about how to use cue properties to wrap menu items and controls, see Offering Menus to the Caller.


cut-through

Value: [yes | no]
Initial: yes
Applies to: all elements
Inherited: yes
Percentage values: N/A

The cut-through CSS property determines whether the WTE accepts input from the caller while playing the audio items for a HTML element. If the cut-through property is set to 'no', the engine ignores the caller's speech input or DTMF digits until after playing all audio for the element to conclusion. If the cut-through property is set to 'yes', the WTE interrupts the audio to accept the caller's input.

This property is intended to be used with menus. Typically, you would set the cut-through property to 'yes' so that callers who are already familiar with the menu can select an item without having to listen to the whole menu. Occasionally, however, you may want to require the caller to listen. For example, you may want the caller to hear a special announcement before making a menu selection. In this case, you would set the cut-through property to 'no'.

You can apply the cut-through property to an HTML element. In this case, the property affects everything within the element.

The cut-through property for each item in a menu is always either 'yes' or 'no', and the first item in the menu defines the cut-through property for all subsequent menu items. The style of the menu owner does not play a special role. Changing the cut-through property in the middle of a menu or an announcement breaks it into two menus or announcements. This is treated as an authoring error and results in the addition of a new record to the log file.

When the WTE encounters an element that has the cut-through property set to 'no', the engine ignores and clears all previously gathered, but unused, caller input.

The cut-through property works only if the voice board's TAPI implementation supports full duplex operation.


display

Value: [none | block | inline | list-item]
Initial: block
Applies to: all elements
Inherited: yes
Percentage values: N/A

The display CSS property controls how an element appears when it is displayed. This property can have one of the following values.

  • Block — adds a line break before and after the element
  • Inline — no line break before and after the element
  • List-item — same as block except a list-item marker is added to the element
  • None — the element and any child elements are not displayed.

The None value of the display property is especially useful in dual-access WTE applications because it allows you to mark HTML elements as telephony-only or browser-only. For example, the following embedded CSS creates a paragraph element that a graphical Web browser will render, but the WTE will not render.

<style type="text/css" media=aural>
P.GraphicalOnly {display : none}
</style>

The WTE will render the paragraph element in the following embedded style but a graphical Web browser will not:

<style type="text/css" media=screen>
P. TelephonyOnly {display : none}
</style>

The media descriptors that are relevant to the WTE include 'all' and 'aural'.


media

Value: [all | aural | print | screen]
Initial:
Applies to: LINK, STYLE
Inherited: yes
Percentage values: N/A

The media CSS property specifies the type of media to which the output applies. This property can have one of the following values:

  • All — Output is intended for all devices.
  • Aural — Output is intended for aural browsers.
  • Print — Output is intended for printed material and for documents on screen viewed in Print Preview mode.
  • Screen — Output is intended for computer screens.


pitch

Value: [<frequency>]
Initial:
Applies to: all elements
Inherited: yes
Percentage values: N/A

The pitch CSS property sets the average pitch of the TTS engine's speaking voice, in hertz. The default pitch for the Microsoft Text-to-Speech (TTS) engine is 170 hertz (Hz).


speak-header-cell

Value: [once | always]
Initial: once
Applies to: header cells
Inherited: yes
Percentage values: N/A

The speak-header-cell CSS property defines how the TTS engine handles the header cells in a table when a table is rendered as tablular data (see Tables). If this property is set to 'always', the engine speaks the headers before every cell. If it is set to 'once', the engine speaks the headers before a cell only when that cell is associated with a header different from that of the previous cell.


speech-rate

Value: [<number>]
Initial:
Applies to: all elements
Inherited: yes
Percentage values: N/A

The speech-rate CSS property controls the speed at which the TTS engine talks, in words per minute. By default, the speech rate of the Microsoft TTS engine is 169 words per minute.


volume

Value: [<percentage> | silent | x-soft | soft | medium | loud | x-loud]
Initial: x-loud
Applies to: all elements
Inherited: yes
Percentage values: N/A

The volume CSS property sets the volume of the speaking voice of the TTS engine. The volume is expressed as a percentage of the maximum volume: 0 means silence, and 100 means maximum volume. This property also supports several additional values, including:

  • silent - 0% of maximum volume
  • x-soft - 25% of maximum volume
  • medium - 50% of maximum volume
  • loud - 75% of maximum volume
  • x-loud - 100% of maximum volume

By default, the volume CSS property of the Microsoft TTS engine is set to 100. Note that this differs from the range set through the control tags, which is 0-FFFF, for each channel (0 - silence, 0xFFFFFFFF - 100, 0x80008000 - 50).


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.