Edit

IWDFDevice::RetrieveDeviceInstanceId method (wudfddi.h)

  • Article

[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

[out, optional] Buffer

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.

[in, out] pdwSizeInChars

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

Requirement Value
End of support Unavailable in UMDF 2.0 and later.
Target Platform Desktop
Minimum UMDF version 1.5
Header wudfddi.h (include Wudfddi.h)
DLL WUDFx.dll

See also

IWDFDevice