WdfWmiInstanceCreate function (wdfwmi.h)
[Applies to KMDF only]
The WdfWmiInstanceCreate method creates a WMI instance object that represents an instance of a WMI data provider.
Syntax
NTSTATUS WdfWmiInstanceCreate(
[in] WDFDEVICE Device,
[in] PWDF_WMI_INSTANCE_CONFIG InstanceConfig,
[in, optional] PWDF_OBJECT_ATTRIBUTES InstanceAttributes,
[out, optional] WDFWMIINSTANCE *Instance
);
Parameters
[in] Device
A handle to a framework device object that represents the device that the instance is being created for. The device object cannot be a control device object.
[in] InstanceConfig
A pointer to a caller-initialized WDF_WMI_INSTANCE_CONFIG structure, which contains configuration information for an instance of a WMI data provider.
[in, optional] InstanceAttributes
A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that contains driver-supplied object attributes for the new WMI instance object. (The structure's ParentObject member must be NULL.) This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.
[out, optional] Instance
A pointer to a location that receives a handle to the new WMI instance object. This parameter is optional and can be NULL.
Return value
WdfWmiInstanceCreate returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values:
| Return code | Description |
|---|---|
|
An invalid parameter was detected. |
|
The size of the WDF_WMI_INSTANCE_CONFIG structure that the InstanceConfig parameter points to was incorrect. |
|
There was insufficient memory. |
|
The driver set the UseContextForQuery member of the WDF_WMI_INSTANCE_CONFIG structure to TRUE but specified a context space size that is larger than ULONG_MAX in the InstanceAttributes parameter's WDF_OBJECT_ATTRIBUTES structure. |
For a list of other return values that the WdfWmiInstanceCreate method might return, see Framework Object Creation Errors.
This method also might return other NTSTATUS values.
A bug check occurs if the driver supplies an invalid object handle.
Remarks
If a driver is creating multiple instances of a provider, the driver must call WdfWmiProviderCreate to create a provider object before calling WdfWmiInstanceCreate. The driver passes the provider object's handle to WdfWmiInstanceCreate by placing the handle in a WDF_WMI_INSTANCE_CONFIG structure. (If the driver supplies a provider object handle, the Device parameter is not used and can be NULL.)
If the driver is creating a single instance of a provider, it does not have to call WdfWmiInstanceCreate before calling WdfWmiInstanceCreate. In this case, WdfWmiInstanceCreate also creates a WMI provider object. Therefore, the driver's WDF_WMI_INSTANCE_CONFIG structure must include a pointer to a WDF_WMI_PROVIDER_CONFIG structure that describes the WMI data provider.
The framework instructs WMI to create a dynamic instance name, which applications can use, from the device instance ID of the driver's physical device object (PDO). (The framework does not support static instance names that Windows Driver Model (WDM) drivers set in an IRP_MN_REGINFO or IRP_MN_REGINFO_EX structure.)
The WMI instance object's parent is the WMI provider object. The driver cannot change this parent, and the ParentObject member or the WDF_OBJECT_ATTRIBUTES structure must be NULL.
After the driver calls WdfWmiInstanceCreate, it can call WdfWmiInstanceGetProvider to obtain a handle to the parent provider object and WdfWmiInstanceGetDevice to obtain a handle to the provider's device.
For more information about the WdfWmiInstanceCreate method, see Supporting WMI in Framework-Based Drivers.
If the Register member of the WDF_WMI_INSTANCE_CONFIG structure that InstanceConfig points to is TRUE, WdfWmiInstanceCreate registers the provider instance synchronously (that is, before returning) if this method is called at IRQL = PASSIVE_LEVEL and asynchronously if it is called at IRQL > PASSIVE_LEVEL.
Examples
The following code example is from the PCIDRV sample driver. This example registers a MOF resource name for a device, initializes a WDF_WMI_PROVIDER_CONFIG structure and a WDF_WMI_INSTANCE_CONFIG structure, and calls WdfWmiInstanceCreate.
NTSTATUS
PciDrvWmiRegistration(
WDFDEVICE Device
)
{
WDF_WMI_PROVIDER_CONFIG providerConfig;
WDF_WMI_INSTANCE_CONFIG instanceConfig;
NTSTATUS status;
DECLARE_CONST_UNICODE_STRING(mofRsrcName, MOFRESOURCENAME);
status = WdfDeviceAssignMofResourceName(
Device,
&mofRsrcName
);
if (!NT_SUCCESS(status)) {
return status;
}
WDF_WMI_PROVIDER_CONFIG_INIT(
&providerConfig,
&PCIDRV_WMI_STD_DATA_GUID
);
providerConfig.MinInstanceBufferSize = sizeof(PCIDRV_WMI_STD_DATA);
WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG(
&instanceConfig,
&providerConfig
);
instanceConfig.Register = TRUE;
instanceConfig.EvtWmiInstanceQueryInstance = EvtWmiDeviceInfoQueryInstance;
instanceConfig.EvtWmiInstanceSetInstance = EvtWmiDeviceInfoSetInstance;
status = WdfWmiInstanceCreate(
Device,
&instanceConfig,
WDF_NO_OBJECT_ATTRIBUTES,
WDF_NO_HANDLE
);
if (!NT_SUCCESS(status)) {
return status;
}
return status;
}
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Minimum KMDF version | 1.0 |
| Header | wdfwmi.h (include Wdf.h) |
| Library | Wdf01000.sys (see Framework Library Versioning.) |
| IRQL | <=DISPATCH_LEVEL |
| DDI compliance rules | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |
See also
WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG