IWDFDeviceInitialize::RetrieveDeviceInstanceId method

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 a 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 supplies is zero. The framework then returns the size, in characters, that is 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 was 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 is non-NULL and does 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

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

IWDFDeviceInitialize

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft