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:

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

See also

IRP_MN_REGINFO

WDF_OBJECT_ATTRIBUTES

WDF_WMI_INSTANCE_CONFIG

WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG

WDF_WMI_PROVIDER_CONFIG

WDF_WMI_PROVIDER_CONFIG_INIT

WdfDeviceAssignMofResourceName

WdfWmiInstanceGetDevice

WdfWmiInstanceGetProvider

WdfWmiProviderCreate