| Platform SDK: TAPI |
After performing basic initialization and possibly retrieval of device capabilities, TAPI must open the phone device before it can access functions on that phone. After a phone device is successfully opened, TAPI is returned a handle representing the open phone. The function TSPI_phoneOpen opens the specified phone device prior to providing access to functions on the phone. TSPI_phoneClose closes a specified phone device.
A phone device is identified to TSPI_lineOpen by means of its device identifier. This function returns a handle to an open phone. A handle to an open phone device is used in other operations to identify the open phone device. The only functions on phone devices that take a phone device identifier parameter are the early initialization functions such as TSPI_phoneGetDevCaps, TSPI_phoneNegotiateTSPIVersion, TSPI_phoneNegotiateExtVersion, and TSPI_phoneOpen. All other functions take phone handles.
Given a phone handle, the phone's device identifier can be retrieved with the TSPI_phoneGetID function.
The TAPI client application can obtain device identifiers for various Win32 device classes associated with an opened phone by invoking TSPI_phoneGetID with the TAPI phoneGetID function. This function takes a phone handle and a device class description. It returns the device identifier for the device of the given device class that is associated with the open phone device. If the device class is tapi/phone, the device identifier of the phone device is returned. If the device class is mci/wave, the device identifier of an mci wave audio device (if supported) is returned that allows the manipulation (such as recording or playback) of audio over the phone.
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, for which the basic line services provide the equivalent of POTS, no minimum guaranteed set of functions is defined for phone devices. While each phone device provides at least the functions and messages listed in this section, these operations only provide a way for the software to refer to the phone; they do not offer any true operations on the physical phone device.