Compartilhar via


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
STATUS_INVALID_PARAMETER
Um parâmetro inválido foi detectado.
STATUS_INFO_LENGTH_MISMATCH
O tamanho da estrutura WDF_WMI_INSTANCE_CONFIG para a qual o parâmetro InstanceConfig aponta estava incorreto.
STATUS_INSUFFICIENT_RESOURCES
Não havia memória suficiente.
STATUS_INTEGER_OVERFLOW
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

IRP_MN_REGINFO

WDF_OBJECT_ATTRIBUTES

WDF_WMI_INSTANCE_CONFIG

WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG

WDF_WMI_PROVIDER_CONFIG

WDF_WMI_PROVIDER_CONFIG_INIT

WdfDeviceAssignMofResourceName

WdfWmiInstanceGetDevice

WdfWmiInstanceGetProvider

WdfWmiProviderCreate