Funzione WdfWmiInstanceCreate (wdfwmi.h)

Articolo
03/08/2023

[Si applica solo a KMDF]

Il metodo WdfWmiInstanceCreate crea un oggetto istanza WMI che rappresenta un'istanza di un provider di dati WMI.

Sintassi

NTSTATUS WdfWmiInstanceCreate(
  [in]            WDFDEVICE                Device,
  [in]            PWDF_WMI_INSTANCE_CONFIG InstanceConfig,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES   InstanceAttributes,
  [out, optional] WDFWMIINSTANCE           *Instance
);

Parametri

[in] Device

Handle a un oggetto dispositivo framework che rappresenta il dispositivo per cui viene creata l'istanza. L'oggetto dispositivo non può essere un oggetto del dispositivo di controllo.

[in] InstanceConfig

Puntatore a una struttura di WDF_WMI_INSTANCE_CONFIG inizializzata dal chiamante, che contiene informazioni di configurazione per un'istanza di un provider di dati WMI.

[in, optional] InstanceAttributes

Puntatore a una struttura di WDF_OBJECT_ATTRIBUTES allocata dal chiamante che contiene attributi di oggetto forniti dal driver per il nuovo oggetto istanza WMI. Il membro ParentObject della struttura deve essere NULL. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.

[out, optional] Instance

Puntatore a una posizione che riceve un handle al nuovo oggetto istanza WMI. Questo parametro è facoltativo e può essere NULL.

Valore restituito

WdfWmiInstanceCreate restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_INFO_LENGTH_MISMATCH	Dimensioni della struttura WDF_WMI_INSTANCE_CONFIG a cui punta il parametro InstanceConfig non è corretto.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente.
STATUS_INTEGER_OVERFLOW	Il driver imposta il membro UseContextForQuery della struttura WDF_WMI_INSTANCE_CONFIG su TRUE, ma specifica una dimensione dello spazio di contesto maggiore di ULONG_MAX nella struttura WDF_OBJECT_ATTRIBUTES del parametro InstanceAttributes.

Per un elenco di altri valori restituiti che il metodo WdfWmiInstanceCreate potrebbe restituire, vedere Errori di creazione dell'oggetto Framework.

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

Se un driver crea più istanze di un provider, il driver deve chiamare WdfWmiProviderCreate per creare un oggetto provider prima di chiamare WdfWmiInstanceCreate. Il driver passa l'handle dell'oggetto provider a WdfWmiInstanceCreate inserendo l'handle in una struttura di WDF_WMI_INSTANCE_CONFIG . Se il driver fornisce un handle di oggetti provider, il parametro Device non viene usato e può essere NULL.

Se il driver crea una singola istanza di un provider, non deve chiamare WdfWmiInstanceCreate prima di chiamare WdfWmiInstanceCreate. In questo caso , WdfWmiInstanceCreate crea anche un oggetto provider WMI. Pertanto, la struttura WDF_WMI_INSTANCE_CONFIG del driver deve includere un puntatore a una struttura WDF_WMI_PROVIDER_CONFIG che descrive il provider di dati WMI.

Il framework indica a WMI di creare un nome di istanza dinamica, che le applicazioni possono usare, dall'ID istanza del dispositivo dell'oggetto dispositivo fisico del driver (PDO). Il framework non supporta i nomi di istanza statici impostati dai driver Windows Driver Model (WDM) in una struttura IRP_MN_REGINFO o IRP_MN_REGINFO_EX .

Il padre dell'oggetto dell'istanza WMI è l'oggetto provider WMI. Il driver non può modificare questo elemento padre e il membro ParentObject o la struttura WDF_OBJECT_ATTRIBUTES deve essere NULL.

Dopo che il driver chiama WdfWmiInstanceCreate, può chiamare WdfWmiInstanceGetProvider per ottenere un handle all'oggetto provider padre e WdfWmiInstanceGetDevice per ottenere un handle per il dispositivo del provider.

Per altre informazioni sul metodo WdfWmiInstanceCreate , vedere Supporto di WMI in Framework-Based Driver.

Se il membro Register della struttura WDF_WMI_INSTANCE_CONFIG a cui InstanceConfig punta è TRUE, WdfWmiInstanceCreate registra l'istanza del provider in modo sincrono (ovvero prima di restituire) se questo metodo viene chiamato in IRQL = PASSIVE_LEVEL e in modo asincrono se viene chiamato in irQL > PASSIVE_LEVEL.

Esempio

L'esempio di codice seguente è dal driver di esempio PCIDRV . In questo esempio viene registrato un nome di risorsa MOF per un dispositivo, inizializza una struttura WDF_WMI_PROVIDER_CONFIG e una struttura WDF_WMI_INSTANCE_CONFIG e chiama 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;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1,0
Intestazione	wdfwmi.h (include Wdf.h)
Libreria	Wdf01000.sys (vedere Framework Library Versioning).
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)