IWDFDevice::RetrieveDeviceInstanceId method

[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]

The RetrieveDeviceInstanceId method retrieves the identifier of an instance of a device.

Syntax


HRESULT RetrieveDeviceInstanceId(
  [out, optional] PWSTR Buffer,
  [in, out]       DWORD *pdwSizeInChars
);

Parameters

Buffer [out, optional]

A pointer to a buffer that receives a NULL-terminated string that represents the identifier of an instance of the device, if the supplied buffer is non-NULL and RetrieveDeviceInstanceId is successful.

pdwSizeInChars [in, out]

A pointer to a variable that receives the number of characters, including the NULL character, in the string that Buffer points to.

If Buffer is NULL, the value that the driver supplied is zero. The framework then returns the size, in characters, that are required for the identifier string.

If Buffer is non-NULL, the framework returns the size, in characters, of the identifier string.

Return value

RetrieveDeviceInstanceId returns S_OK for the following scenarios:

  • The buffer that the Buffer parameter pointed to was non-NULL and large enough to hold the identifier string, including the NULL character, and the framework successfully copied the string into the supplied buffer and set the variable that is pointed to by the pdwSizeInChars parameter to the number of characters in the string.
  • The buffer at Buffer was NULL, the driver preset the variable at pdwSizeInChars to 0, and the framework set the variable at pdwSizeInChars to the number of characters that are required for the string.
RetrieveDeviceInstanceId returns HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) to indicate that the supplied buffer was non-NULL and did not contain enough space to hold the identifier string. The framework sets the variable at pdwSizeInChars to the number of characters that are required for the string.

RetrieveDeviceInstanceId might also return other HRESULT values.

Requirements

Target platform

Desktop

End of support

Unavailable in UMDF 2.0 and later.

Minimum UMDF version

1.5

Header

Wudfddi.h (include Wudfddi.h)

DLL

WUDFx.dll

See also

IWDFDevice

 

 

Send comments about this topic to Microsoft

Show: