| Syntax | BOOL TSPI_phoneOpen(dwDeviceID, htPhone, lphdPhone, dwTSPIVersion, phoneEventProc) |
| This function opens the phone device whose device ID is given, returning the Service Provider's opaque handle for the device and retaining the TAPI DLL's opaque handle for the device for use in subsequent calls to the PHONEEVENT procedure. | |
| Parameters | DWORD dwDeviceID Identifies the phone device to be opened. |
| HTAPIPHONE htPhone Specifies the TAPI DLL's opaque handle for the phone device to be used in subsequent calls to the PHONEEVENT callback procedure to identify the device. | |
| LPHDRVPHONE lphdPhone A far pointer to a HDRVPHONE where the Service Provider fills in its opaque handle for the phone device to be used by the TAPI DLL in subsequent calls to identify the device. | |
| DWORD dwTSPIVersion The TSPI version negotiated through TSPI_phoneNegotiateTSPIVersion under which the Service Provider is willing to operate. | |
| PHONEEVENT phoneEventProc A far pointer to the PHONEEVENT callback procedure supplied by the TAPI DLL that the Service Provider will call to report subsequent events on the phone. | |
| Return Value | Returns TRUE if the procedure is successful, otherwise FALSE |
| Comments | Opening a phone entitles the TAPI DLL to make further requests on the phone. The phone becomes "active" in the sense that the Service Provider can report asynchronous events such as hookswitch changes or button presses. The Service Provider reserves whatever non-sharable resources are required to manage the phone. For example, opening a phone accessed through a comm port and modem should result in opening the comm port, making it no longer available for use by other applications. |
| If the function is successful, both the TAPI DLL and the Service Provider become committed to operating under the specified interface version number for this open device. Subsquent operations and events identified using the exchanged opaque phone handles conform to that interface version. This commitment and the validity of the handles remain in effect until the TAPI DLL closes the phone using the TSPI_phoneClose operation or the Service Provider reports the PHONE_CLOSE event. If the function is not successful, no such commitment is made and the handles are not valid. | |
| Comparison | This procedure does not correspond directly to any procedure at the TAPI level, at which the functions of enabling device-specific extensions and selecting different levels of event-reporting by means of a privilege level are included in the functionality defined by phoneOpen. At the TSPI level enabling device-specific extensions is separated out into TSPI_phoneNegotiateExtVersion, and the Service Provider relies on the TAPI DLL to filter evnets to applications appropriately. This procedure simply starts the "life cycle" of subsequent operations. |
| In addition, the TAPI procedure allows for asynchronous execution while this one does not. | |
| See Also | Functions: TSPI_phoneClose, TSPI_phoneNegotiateTSPIVersion, PHONEEVENT |
| Messages: PHONE_CLOSE |