TSPI_phoneGetID

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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 VARSTRING where 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 dwTotalSize member 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_phoneGetID function is being invoked. If the information being returned in the VARSTRING structure 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.

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 VARSTRING data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

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