2.5.1.3 Opening and Closing Phone Devices
After having performed basic initialization and possibly having retrieved device capabilities, the TAPI DLL must open the phone device before it can access functions on that phone. After a phone device has been successfully opened, the TAPI DLL is returned a handle representing the open phone.
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 ID. 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. Note that the only functions on phone devices that take a phone device ID parameter are the early initialization functions such as TSPI_phoneGetDevCaps, TSPI_phoneNegotiateTSPIVersion, TSPI_phoneNegotiateExtVersion, TSPI_phoneSetDeviceIDBase, and TSPI_phoneOpen functions. All other functions take phone handles.
Given a phone handle, the phone's device ID can be retrieved via the function TSPI_phoneGetID.
The TAPI DLL's client application can obtain device IDs for various Windows device classes associated with an opened phone by invoking TSPI_phoneGetID via the TAPI function 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.
TSPI_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.