2.5.1.2 Phones
The Telephony SPI 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 SPI 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 SPI 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 SPI. 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 SPI.
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 SPI 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 SPI 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 SPI. 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 SPI allows the TAPI DLL to monitor and/or control elements of the phone device on behalf of its client applications. 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. The TAPI DLL determines a phone's device capabilities on behalf of an application via TSPI_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 applications via the SPI (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 SPI where the switch may temporarily suspend the SPI's control of a phone device (see further).