Função WdfWmiInstanceCreate (wdfwmi.h)
[Aplica-se somente ao KMDF]
O método WdfWmiInstanceCreate cria um objeto de instância WMI que representa uma instância de um provedor de dados WMI.
Sintaxe
NTSTATUS WdfWmiInstanceCreate(
[in] WDFDEVICE Device,
[in] PWDF_WMI_INSTANCE_CONFIG InstanceConfig,
[in, optional] PWDF_OBJECT_ATTRIBUTES InstanceAttributes,
[out, optional] WDFWMIINSTANCE *Instance
);
Parâmetros
[in] Device
Um identificador para um objeto de dispositivo de estrutura que representa o dispositivo para o qual a instância está sendo criada. O objeto do dispositivo não pode ser um objeto de dispositivo de controle .
[in] InstanceConfig
Um ponteiro para uma estrutura de WDF_WMI_INSTANCE_CONFIG inicializada pelo chamador, que contém informações de configuração para uma instância de um provedor de dados WMI.
[in, optional] InstanceAttributes
Um ponteiro para uma estrutura de WDF_OBJECT_ATTRIBUTES alocada pelo chamador que contém atributos de objeto fornecidos pelo driver para o novo objeto de instância WMI. (O membro ParentObject da estrutura deve ser NULL .) Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.
[out, optional] Instance
Um ponteiro para um local que recebe um identificador para o novo objeto de instância WMI. Esse parâmetro é opcional e pode ser NULL.
Valor de retorno
WdfWmiInstanceCreate retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método poderá retornar um dos seguintes valores:
| Código de retorno | Descrição |
|---|---|
|
Um parâmetro inválido foi detectado. |
|
O tamanho da estrutura de WDF_WMI_INSTANCE_CONFIG à qual o parâmetro InstanceConfig aponta estava incorreto. |
|
Não havia memória suficiente. |
|
O driver definiu o membro UseContextForQuery da estrutura WDF_WMI_INSTANCE_CONFIG para TRUE, mas especificou um tamanho de espaço de contexto maior que ULONG_MAX na estrutura de WDF_OBJECT_ATTRIBUTES do parâmetro InstanceAttributes. |
Para obter uma lista de outros valores retornados que o método WdfWmiInstanceCreate pode retornar, consulte Erros de Criação de Objeto da Estrutura.
Esse método também pode retornar outros valores NTSTATUS .
Uma verificação de bug ocorre se o driver fornece um identificador de objeto inválido.
Observações
Se um driver estiver criando várias instâncias de um provedor, o driver deverá chamar WdfWmiProviderCreate para criar um objeto de provedor antes de chamar WdfWmiInstanceCreate. O driver passa o identificador do objeto do provedor para WdfWmiInstanceCreate colocando o identificador em uma estrutura WDF_WMI_INSTANCE_CONFIG. (Se o driver fornecer um identificador de objeto do provedor, o parâmetro Device não será usado e poderá ser NULL .)
Se o driver estiver criando uma única instância de um provedor, ele não precisará chamar WdfWmiInstanceCreate antes de chamar WdfWmiInstanceCreate. Nesse caso, WdfWmiInstanceCreate também cria um objeto de provedor WMI. Portanto, a estrutura de WDF_WMI_INSTANCE_CONFIG do driver deve incluir um ponteiro para uma estrutura de WDF_WMI_PROVIDER_CONFIG que descreve o provedor de dados WMI.
A estrutura instrui o WMI a criar um nome de instância dinâmica, que os aplicativos podem usar, na ID da instância do dispositivo do objeto de dispositivo físico (PDO) do driver. (A estrutura não dá suporte a nomes de instâncias estáticas que os drivers WDM (Windows Driver Model) definem em uma estrutura IRP_MN_REGINFO ou IRP_MN_REGINFO_EX.)
O pai do objeto de instância WMI é o objeto do provedor WMI. O driver não pode alterar esse pai e o membro ParentObject ou a estrutura WDF_OBJECT_ATTRIBUTES deve ser NULL.
Depois que o driver chama WdfWmiInstanceCreate, ele pode chamar WdfWmiInstanceGetProvider para obter um identificador para o objeto do provedor pai e WdfWmiInstanceGetDevice para obter um identificador para o dispositivo do provedor.
Para obter mais informações sobre o método WdfWmiInstanceCreate, consulte Suporte à WMI em Framework-Based Drivers.
Se o Register membro da estrutura WDF_WMI_INSTANCE_CONFIG à qual InstanceConfig aponta for TRUE, WdfWmiInstanceCreate registrará a instância do provedor de forma síncrona (ou seja, antes de retornar) se esse método for chamado em IRQL = PASSIVE_LEVEL e de forma assíncrona se for chamado em > PASSIVE_LEVEL IRQL.
Exemplos
O exemplo de código a seguir é do driver de exemplo de PCIDRV. Este exemplo registra um nome de recurso MOF para um dispositivo, inicializa uma estrutura de WDF_WMI_PROVIDER_CONFIG e uma estrutura de WDF_WMI_INSTANCE_CONFIG e chama 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;
}
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino | Universal |
| versão mínima do KMDF | 1.0 |
| cabeçalho | wdfwmi.h (inclua Wdf.h) |
| biblioteca | Wdf01000.sys (consulte o Controle de Versão da Biblioteca da Estrutura.) |
| IRQL | <=DISPATCH_LEVEL |
| regras de conformidade de DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |
Consulte também
WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG