TSPI_phoneOpen (Windows CE 5.0)

Send Feedback

This function opens the phone device whose device identifier is given, returning the service provider's opaque handle for the device and retaining TAPI's opaque handle for the device for use in subsequent calls to the PHONEEVENT procedure.

LONG TSPIAPI TSPI_phoneOpen(DWORDdwDeviceID,HTAPIPHONEhtPhone,LPHDRVPHONElphdPhone,DWORDdwTSPIVersion,PHONEEVENTlpfnEventProc);

Parameters

  • dwDeviceID
    Phone device to be opened.
  • htPhone
    TAPI opaque handle for the phone device to be used in subsequent calls to the PHONEEVENT callback procedure to identify the device.
  • lphdPhone
    Pointer to a HDRVPHONE where the service provider writes its handle for the phone device to be used by TAPI in subsequent calls to identify the device.
  • dwTSPIVersion
    TSPI version negotiated through the TSPI_phoneNegotiateTSPIVersion function, under which the service provider can operate.
  • lpfnEventProc
    Pointer to the PHONEEVENT callback procedure supplied by TAPI that the service provider calls to report subsequent events on the phone.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. The following table shows the return values for this method.

Value Description
PHONEERR_ALLOCATED The specified resource is already allocated.
PHONEERR_NOMEM Not enough memory is available.
PHONEERR_INCOMPATIBLEAPIVERSION The API version is incompatible.
PHONEERR_RESOURCEUNAVAIL The resource is unavailable.
PHONEERR_NODRIVER The driver cannot be found.
PHONEERR_OPERATIONFAILED The operation failed.
PHONEERR_INUSE The phone is in use.
PHONEERR_OPERATIONUNAVAIL The operation is unavailable.
PHONEERR_INIFILECORRUPT The INI file is corrupted.

Remarks

Opening a phone entitles TAPI 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 nonsharable resources are required to manage the phone. For example, opening a phone accessed through a COM port and modem should result in opening the COM port, making it no longer available for use by other applications.

If the function succeeds, both TAPI and the service provider become committed to operating under the specified interface version number for this open device. Subsequent 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 TAPI closes the phone using the TSPI_phoneClose function or until 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.

Requirements

OS Versions: Windows CE 3.0 and later.
Header: Tapicomn.h.
Link Library: Coredll.lib.

See Also

PHONEEVENT | TSPI_phoneClose | TSPI_phoneNegotiateTSPIVersion

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.