Phone API Initialization and Shutdown
An application that wants to use the phone abstraction of the Telephony API must first initialize its usage of the API by calling phoneInitialize. In this operation, the application provides its application callback function to the API and specifies whether it wants to be called back in interrupt handler context or in application thread context. Although the interrupt handler context provides faster response, the highly constrained interrupt environment severely limits what the callback function can perform. Conversely, the callback in the app's thread requires the interrupt handler activates the app's thread which is then forced to invoke its callback. Although this is a higher latency mechanism, it does allow the callback to operate without any of the interrupt context restrictions. Since telephony events do not typically require "immediate" response, application developers are strongly discouraged from selecting the interrupt context callback option.
The phoneInitialize function returns two pieces of information to the application: an application handle and the number of phone devices. The application handle represents the application's usage of the Telephony API. API functions that use phone handles (see further) do not require the application handle, as this handle is derived from the specified phone handle.
The second piece of information returned by phoneInitialize is the number of phone devices available to the application via the API. Phone devices are identified by their device identifier (device ID). Valid device IDs range from zero to the number of phone devices - 1. For example, if phoneInitialize reports that there are two phone devices in a system, then valid phone device IDs are zero and 1.
Once an application is finished using the phone abstraction of the Telephony API, it invokes phoneShutdown passing its application handle to shutdown its usage of the API. This allows the API to free any resources assigned to this application.
phoneInitialize
Initializes the Telephony API phone abstraction for use by the invoking application.
phoneShutdown
Shuts down the application's use of the Telephony API phone abstraction.
Both phoneInitialize and phoneShutdown operate fully synchronously; i.e., these functions either return a success or failure indication; they never return an asynchronous Request ID.
The Telephony API defines a device that supports the phone device class as one containing some or all of the following elements (or additional elements):
Hookswitch/Transducer - this is a means for audio input and output. The API recognizes that a phone device may have several transducers, which can be activated and deactivated (i.e., taken offhook, placed onhook) under application or manual user control. The Telephony API identifies three types of hookswitch devices common to many phone sets:
handset - is the traditional mouth-and-ear piece combination that must be manually lifted from a cradle and pressed against the user's ear.
speakerphone - enables the user to conduct calls hands-free. The hookswitch state of a speakerphone can usually be changed both manually and by the API. The speakerphone may be internal or external to the phone device. The speaker part of a speakerphone allows multiple listeners.
headset - enables the user to conduct calls hands-free. The hook switch state of a headset can usually be changed both manually and by the API.
A hookswitch must be offhook to allow audio data to be sent to and/or received by the corresponding transducer.
Volume Control/Gain Control/Mute - each hookswitch device is the pairing of a speaker and a mic component. The API provides for volume control/mute of speaker components and for gain control/mute of mic components.
Ringer - this is a means for alerting human users, usually a bell of sorts. A phone device may be able to ring in a variety of modes or patterns.
Display - this is a mechanism for visually presenting messages to the user. A phone display is characterized by its number of rows and columns.
Buttons - this is an array of buttons. Whenever the user presses a button on the phone set, the API reports that the corresponding button was pressed. Button/Lamp IDs identify a button and lamp pair. Of course, it is possible to have button/lamp pairs with either no button or no lamp. Button/lamp IDs are integer values that range from 0 to the maximum number of button/lamps available on the phone device, minus one. Each button belongs to a button class. Classes include call appearance buttons, feature buttons, keypad buttons, and local buttons.
Lamps - this is an array of lamps (such as LEDs) individually controllable from the API. Lamps can be lit in different modes by varying the on and off frequency. The button/lamp ID identifies the lamp.
Data Areas - these are memory areas in the phone device where instruction code or data can be downloaded to and/or uploaded from. The downloaded information would affect the behavior (or in other words, program) the phone device.
The Telephony API allows an application to monitor and/or control elements of the phone device. Probably the most useful elements for an application to use are the hookswitch devices (e.g., to use the phone set as an audio I/O device to the PC) with volume control, gain control and mute, the ringer (for alerting the user), the data areas (for programming the phone), and perhaps the display (the PC's display is certainly a lot more capable). The application writer is discouraged from directly controlling or using phone lamps or phone buttons, since lamp and button capabilities can vary widely among phone sets, and applications can quickly become tailored to specific phone sets.
There is no guaranteed core set of services supported by all phone devices as there is for line devices (i.e., basic telephony services). Therefore, before an application can use a phone device, the application must first determine the exact capabilities of the phone device. Telephony capability varies with the configuration (e.g., client versus client/server), the telephone hardware and service provider software. Applications should make no assumptions as to what telephony capabilities are available. An application determines a phone's device capabilities via phoneGetDevCaps.
phoneGetDevCaps
Returns the device capabilities of a phone device.
A phone's device capabilities indicate which of these elements exist for each phone device present in the system and what their capabilities are. Although strongly oriented towards real-life telephone sets, this abstraction can provide a meaningful implementation (or subset thereof) for other devices as well. Take as an example a separate headset directly connected and controllable from the PC and operated as a phone device. Hookswitch changes can be triggered by detection of voice energy (offhook) or a period of silence (onhook); ringing can be emulated by the generation of an audible signal into the headset; a display can be emulated via text-to-speech conversion.
Note that a phone device need not be realized in hardware, but can instead be emulated in software, using a mouse or keyboard driven graphical command interface and the PC's speaker or sound system. Such a "soft phone" can be an application of the Telephony API. It can also be a service provider, which can be listed as a phone device available to other applications via the API (i.e., it is assigned a phone device ID).
Depending on the environment and configuration, phone sets can be shared devices between the application and the switch. Some minor provision is made in the API where the switch may temporarily suspend the API's control of a phone device (see further).
Opening and Closing Phone Devices
After getting the capabilities of a phone device, an application must open the phone device before it can access functions on that phone. After a phone device has been successfully opened, the app is returned a handle representing the open phone. A phone device can be opened in different modes, thus providing a structured way of sharing a phone device, as describer later.
phoneOpen
Opens the specified phone device prior to providing access to functions on the phone.
phoneClose
Closes a specified phone device.
A phone device is identified to lineOpen by means of its device ID. The app can request one of two operating modes for the open. These modes reflect the privileges the app requests for the phone device. An app that opens a phone for monitor privileges can only determine the status of the phone device. Messages are sent to the app's callback when status changes on the phone device are detected.
An app that opens a phone device for owner privileges is allowed to use operations that modify the state of the phone device. Owner privilege automatically includes full monitor privileges as well. At any point in time, a given phone device can at most be opened once for owner privileges, but can be opened multiple times for monitor privileges. All phoneSet operations require owner privileges, while all phoneGet operations require only monitor privileges.
A handle to an open phone device is used in other operations to identify the open phone device. Note that the only functions on phone devices that take a phone device ID parameter are the phoneGetDevCaps and phoneOpen functions. All other functions take phone handles.
Given a phone handle, the phone's device ID can be retrieved via the function phoneGetID.
An application can obtain device IDs for various Windows device classes associated with an opened phone by invoking phoneGetID. This function takes a phone handle and a device class description. It returns the device ID for the device of the given device class that is associated with the open phone device. If the device class is phone, then the device ID of the phone device is returned. If the device class is mci waveaudio, then the device ID of an mci waveaudio device is returned (if supported) that allows the recording/playback etc. of audio over the phone.
phoneGetID
Retrieves the phone device ID from a open phone device handle.
To subsequently open a phone device for audio playback using the waveform API, an application calls the waveOutOpen function. The implementation of the waveOutOpen call is device-specific, and each implementation has a number of options for implementing this function. If the phone's handset is on hook when invoking the function, for example, the waveOutOpen driver may return an error code message to the application that is further mapped in a request (dialog box) to the user to "pick up the phone." This is similar to requesting a CD to play back audio when no compact disc is in the player, and the existing definition of the waveform APIs can deal with it.
In contrast with line devices where the basic line services provide the equivalent of POTS, no minimum guaranteed set of functions is defined for phone devices. While each phone device will at least provide the functions and messages listed in this section, these do not offer any true operations on the physical phone device.