 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
This function returns a device identifier for the given device class associated with the specified phone device.
Syntax
LONG TSPIAPI TSPI_phoneGetID( HDRVPHONE hdPhone, LPVARSTRING lpDeviceID, LPCWSTR lpszDeviceClass, HANDLE hTargetProcess ); |
Parameters
- hdPhone
-
Handle to the phone to be queried.
- lpDeviceID
-
Pointer to a data structure of type VARSTRINGwhere the device identifier is returned. The format of the returned information depends on the method used by the device class (API) for naming devices. Prior to calling TSPI_ phoneGetID, the application sets the dwTotalSizemember of this structure to indicate the amount of memory available to TAPI for returning information.
- lpszDeviceClass
-
Pointer to a null-terminated Unicode string that specifies the device class of the device whose identifier is requested.
- hTargetProcess
-
Process handle of the application on behalf of which the TSPI_ phoneGetIDfunction is being invoked. If the information being returned in the VARSTRINGstructure includes a handle for use by the application, the service provider creates or duplicates the handle for the process.
Return Value
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_INVALPHONEHANDLE |
The handle to the phone is invalid. |
|
PHONEERR_RESOURCEUNAVAIL |
The resource is unavailable. |
|
PHONEERR_INVALDEVICECLASS |
The device class is invalid. |
|
PHONEERR_OPERATIONFAILED |
The operation failed. |
|
PHONEERR_NOMEM |
Not enough memory is available. |
|
PHONEERR_OPERATIONUNAVAIL |
The operation is unavailable. |
Remarks
This operation can be used to retrieve a phone device identifier given a phone handle. It can also be used to obtain the device identifier of the media device (for device classes such as COM, wave, phone, line, and mciwave) associated with the opened phone device. This identifier can then be used with the appropriate media API (such as mci and wav) to select the corresponding device.
The service provider fills in all the members of the VARSTRINGdata structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSizemember.
The service provider does not need to be concerned with handling tapi/line and tapi/phone device classes because TAPI handles these for the service provider. Therefore, code for handling these device classes is optional.
Requirements
| Header | tapicomn.h |
| Library | coredll.lib |
| Windows Embedded CE | Windows CE 3.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |