WdfWmiProviderCreate function (wdfwmi.h)

Article
04/18/2022

[Applies to KMDF only]

The WdfWmiProviderCreate method creates a WMI provider object that represents a WMI data block.

Syntax

NTSTATUS WdfWmiProviderCreate(
  [in]           WDFDEVICE                Device,
  [in]           PWDF_WMI_PROVIDER_CONFIG WmiProviderConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES   ProviderAttributes,
  [out]          WDFWMIPROVIDER           *WmiProvider
);

Parameters

[in] Device

A handle to a framework device object that will be the new provider object's parent object. The device object cannot be a control device object.

[in] WmiProviderConfig

A pointer to a caller-initialized WDF_WMI_PROVIDER_CONFIG structure that contains configuration information about the WMI data block.

[in, optional] ProviderAttributes

A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that contains driver-supplied object attributes for the new WMI provider object. (The structure's ParentObject member must be NULL.) This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.

[out] WmiProvider

A pointer to a location that receives a handle to the new WMI provider object.

Return value

WdfWmiProviderCreate returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values:

Return code	Description
STATUS_INVALID_PARAMETER	An invalid parameter was detected.
STATUS_INFO_LENGTH_MISMATCH	The size of the WDF_WMI_PROVIDER_CONFIG structure that the WmiProviderConfig parameter pointed to was incorrect.
STATUS_INSUFFICIENT_RESOURCES	There was insufficient memory to complete the operation.
STATUS_OBJECT_NAME_EXISTS	The driver has already called WdfWmiProviderCreate for the specified device and WMI data block.

For a list of other return values that the WdfWmiProviderCreate 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

Your driver must call WdfWmiProviderCreate to create a WMI provider object if the driver will create multiple instances of the provider. If the driver will create only one instance of the provider, it can call WdfWmiInstanceCreate without first calling WdfWmiProviderCreate.

A driver can call WdfWmiProviderCreate at any time, but drivers typically call WdfWmiProviderCreate from within their EvtDriverDeviceAdd callback functions.

The parent of each WMI provider object is the device's framework device object. The driver cannot change this parent, and the ParentObject member or the WDF_OBJECT_ATTRIBUTES structure must be NULL.

After a driver calls WdfWmiProviderCreate, the driver can call WdfWmiProviderGetDevice to retrieve a handle to the provider object's parent device object.

After a driver creates a WMI provider object, the driver cannot delete the object. The framework deletes a device's WMI provider objects when it deletes the framework device object that represents the device. WMI provider objects use minimal system resources.

For more information about the WdfWmiProviderCreate method, see Supporting WMI in Framework-Based Drivers.

Examples

The following code example initializes a WDF_WMI_PROVIDER_CONFIG structure and calls WdfWmiProviderCreate.

WDF_WMI_PROVIDER_CONFIG config;
WDFWMIPROVIDER provider;
GUID providerGuid = MY_WMI_DATA_BLOCK_GUID;
NTSTATUS status;

WDF_WMI_PROVIDER_CONFIG_INIT(
                             &config,
                             providerGuid
                             );
config.Flags = WdfWmiProviderTracing;
config.EvtWmiProviderFunctionControl = MyProviderFunctionControl;

status = WdfWmiProviderCreate(
                              Device,
                              &config,
                              WDF_NO_OBJECT_ATTRIBUTES,
                              &provider
                              );

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)