Funzione WdfWmiInstanceCreate (wdfwmi.h)
[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 per un oggetto dispositivo framework che rappresenta il dispositivo per cui viene creata l'istanza. L'oggetto dispositivo non può essere un oggetto 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 WDF_OBJECT_ATTRIBUTES allocata dal chiamante che contiene gli attributi dell'oggetto fornito 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 per il nuovo oggetto istanza WMI. Questo parametro è facoltativo e può essere NULL.
Valore restituito
WdfWmiInstanceCreare restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:
| Codice restituito | Descrizione |
|---|---|
|
È stato rilevato un parametro non valido. |
|
Dimensioni della struttura di WDF_WMI_INSTANCE_CONFIG a cui punta il parametro InstanceConfig non è corretto. |
|
Memoria insufficiente. |
|
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 potrebbero essere restituiti dal metodo WdfWmiInstanceCreate, vedere Framework Object Creation Errors.
Questo metodo potrebbe anche restituire altri valori NTSTATUS .
Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.
Osservazioni
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 posizionando l'handle in una struttura WDF_WMI_INSTANCE_CONFIG. Se il driver fornisce un handle di oggetto provider, il parametro device non viene usato e può essere NULL.)
Se il driver crea una singola istanza di un provider, non è necessario chiamare WdfWmiInstanceCreate prima di chiamare WdfWmiInstanceCreate. In questo caso, WdfWmiInstanceCreate crea anche un oggetto provider WMI. Pertanto, la struttura di 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 (PDO) del driver. Il framework non supporta i nomi di istanza statici impostati dai driver WdM (Windows Driver Model) in una struttura IRP_MN_REGINFO o IRP_MN_REGINFO_EX.
L'oggetto padre 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 per l'oggetto provider padre e WdfWmiInstanceGetDevice per ottenere un handle per il dispositivo del provider.
Per altre informazioni sul metodo WdfWmiInstanceCreate, vedere Supporto wmi in Framework-Based driver.
Se il membro Register della struttura di 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.
Esempi
L'esempio di codice seguente proviene dal driver di esempio PCIDRV. Questo esempio registra un nome di risorsa MOF per un dispositivo, inizializza una struttura di 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;
}
Fabbisogno
| Requisito | Valore |
|---|---|
| piattaforma di destinazione | Universale |
| versione minima di KMDF | 1.0 |
| intestazione | wdfwmi.h (include Wdf.h) |
| libreria | Wdf01000.sys (vedere Controllo delle versioni della libreria framework). |
| IRQL | <=DISPATCH_LEVEL |
| regole di conformità DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |
Vedere anche
WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG