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 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 |
|---|---|
|
È stato rilevato un parametro non valido. |
|
Dimensioni della struttura 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 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) |
Vedi anche
WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG