IoWMISuggestInstanceName function (wdm.h)

Article
02/22/2024

The IoWMISuggestInstanceName routine is used to request that WMI suggest a base name which a driver can use to build WMI instance names for the device.

Syntax

NTSTATUS IoWMISuggestInstanceName(
  [in, optional] PDEVICE_OBJECT  PhysicalDeviceObject,
  [in, optional] PUNICODE_STRING SymbolicLinkName,
  [in]           BOOLEAN         CombineNames,
  [out]          PUNICODE_STRING SuggestedInstanceName
);

Parameters

[in, optional] PhysicalDeviceObject

If supplied, points to the driver's physical device object.

[in, optional] SymbolicLinkName

If supplied, points to the symbolic link name returned from IoRegisterDeviceInterface.

[in] CombineNames

If TRUE then the suggested names returned will combine the PhysicalDeviceObject and SymbolicLinkName information.

[out] SuggestedInstanceName

A pointer to a buffer which upon successful completion will contain a UNICODE_STRING which contains the suggested instance name. The caller is responsible for freeing this buffer when it is no longer needed.

Return value

IoWMISuggestInstanceName returns a status code from the following list:

Return code	Description
STATUS_SUCCESS	Indicates that WMI was able to successfully complete this function.
STATUS_UNSUCCESSFUL	Indicates that the WMI services are not available.
STATUS_INSUFFICIENT_RESOURCES	Indicates that insufficient resources were available to provide the caller with a buffer containing the Unicode string.
STATUS_NO_MEMORY	Indicates that insufficient resources were available to provide the caller with a buffer containing the Unicode string.

Remarks

If the CombineNames parameter is TRUE then both PhysicalDeviceObject and SymbolicLinkName must be specified. Otherwise, only one of them should be specified.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 2000.
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL