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.
Retornar valor
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 WDF_WMI_INSTANCE_CONFIG para a 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 como TRUE, mas especificou um tamanho de espaço de contexto maior que ULONG_MAX na estrutura 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.
Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.
Comentários
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, a partir da ID da instância do dispositivo do PDO (objeto de dispositivo físico) do driver. (A estrutura não dá suporte a nomes de instância estáticos que os drivers do WDM (Modelo de Driver do Windows) definem em uma estrutura de 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 devem 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 Supporting WMI in Framework-Based Drivers.
Se o membro Register da estrutura WDF_WMI_INSTANCE_CONFIG para a 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 IRQL > PASSIVE_LEVEL.
Exemplos
O exemplo de código a seguir é do driver de exemplo PCIDRV . Este exemplo registra um nome de recurso MOF para um dispositivo, inicializa uma estrutura WDF_WMI_PROVIDER_CONFIG e uma estrutura 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 |
|---|---|
| Plataforma de Destino | Universal |
| Versão mínima do KMDF | 1.0 |
| Cabeçalho | wdfwmi.h (inclua Wdf.h) |
| Biblioteca | Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.) |
| IRQL | <=DISPATCH_LEVEL |
| Regras de conformidade de DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |
Confira também
WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG