função de retorno de chamada WMI_QUERY_REGINFO_CALLBACK (wmilib.h)

Artigo
08/08/2023

A rotina DpWmiQueryReginfo fornece informações sobre os blocos de dados e os blocos de eventos a serem registrados por um driver. Essa rotina é necessária.

Sintaxe

WMI_QUERY_REGINFO_CALLBACK WmiQueryReginfoCallback;

NTSTATUS WmiQueryReginfoCallback(
  [in]  PDEVICE_OBJECT DeviceObject,
  [out] PULONG RegFlags,
  [out] PUNICODE_STRING InstanceName,
  [out] PUNICODE_STRING *RegistryPath,
  [out] PUNICODE_STRING MofResourceName,
  [out] PDEVICE_OBJECT *Pdo
)
{...}

Parâmetros

[in] DeviceObject

Um ponteiro para a estrutura de DEVICE_OBJECT do WDM do driver.

[out] RegFlags

Esse parâmetro indica características comuns de todos os blocos que estão sendo registrados. Qualquer sinalizador definido em RegFlags é aplicado a todos os blocos. Um driver pode complementar RegFlags para um determinado bloco definindo Sinalizadores na estrutura WMIGUIDREGINFO do bloco. Por exemplo, um driver pode limpar WMIREG_FLAG_EXPENSIVE no RegFlags, mas defini-lo em Sinalizadores para registrar um determinado bloco como caro para coletar.

O driver define um dos seguintes sinalizadores em RegFlags:

WMIREG_FLAG_INSTANCE_BASENAME

Solicita que o WMI gere nomes de instância estática de um nome base fornecido pelo driver no InstanceName. O WMI gera nomes de instância acrescentando um contador ao nome base.

WMIREG_FLAG_INSTANCE_PDO

Solicita que o WMI gere nomes de instância estática da ID da instância do dispositivo para o PDO. Se o driver definir esse sinalizador, ele também deverá definir Pdo para o PDO passado para a rotina AddDevice do driver. O WMI gera nomes de instância do caminho da instância do dispositivo do PDO. Usar o caminho da instância do dispositivo como base para nomes de instância estática é eficiente porque esses nomes têm a garantia de serem exclusivos. O WMI fornece automaticamente um nome "amigável" para a instância como um item em um bloco de dados que pode ser consultado pelos consumidores de dados.

Um driver também pode definir um ou mais dos seguintes sinalizadores em RegFlags, mas, mais normalmente, os definiria em Sinalizadores da estrutura WMIGUIDREGINFO de um bloco:

WMIREG_FLAG_EVENT_ONLY_GUID

Os blocos podem ser habilitados ou desabilitados apenas como eventos e não podem ser consultados ou definidos. Se esse sinalizador estiver claro, os blocos também poderão ser consultados ou definidos.

WMIREG_FLAG_EXPENSIVE

Solicita que o WMI envie uma solicitação de IRP_MN_ENABLE_COLLECTION na primeira vez que um consumidor de dados abre um bloco de dados e uma solicitação de IRP_MN_DISABLE_COLLECTION quando o último consumidor de dados fecha o bloco de dados. Isso é recomendado se a coleta desses dados afetar o desempenho, pois um driver não precisa coletar os dados até que um consumidor de dados solicite explicitamente a ele abrindo o bloco.

WMIREG_FLAG_REMOVE_GUID

Solicita que o WMI remova o suporte para os blocos. Esse sinalizador é válido apenas em resposta a uma solicitação para atualizar as informações de registro (IRP_MN_REGINFO ou IRP_MN_REGINFO_EX com Parameters.WMI.DataPath definido como WMIUPDATE).

[out] InstanceName

Um ponteiro para uma única cadeia de caracteres Unicode contada que serve como o nome base para todas as instâncias de todos os blocos a serem registradas pelo driver. O WMI libera a cadeia de caracteres com ExFreePool. Se WMIREG_FLAG_INSTANCE_BASENAME estiver claro, InstanceName será ignorado.

[out] RegistryPath

Um ponteiro para um ponteiro para uma cadeia de caracteres Unicode contada que especifica o caminho do Registro passado para a rotina driverEntry do driver.

[out] MofResourceName

Um ponteiro para uma única cadeia de caracteres Unicode contada que indica o nome do recurso MOF anexado ao arquivo de imagem binária do driver. Normalmente, essa cadeia de caracteres seria uma estática definida pelo driver. O WMI faz uma cópia dessa cadeia de caracteres depois que o driver retorna dessa rotina. Essa cadeia de caracteres pode ser alocada dinamicamente pelo driver. No caso de uma cadeia de caracteres alocada, o driver é responsável por liberar a cadeia de caracteres que deve ser feita após o retorno de WmiSystemControl . Se o driver não tiver um recurso MOF anexado, ele poderá deixar MofResourceName inalterado.

[out] Pdo

Um ponteiro para o PDO (objeto de dispositivo físico) passado para a rotina AddDevice do driver. Se WMIREG_FLAG_INSTANCE_PDO estiver definido, o WMI usará o caminho da instância do dispositivo desse PDO como uma base da qual gerar nomes de instância estática. Se WMIREG_FLAG_INSTANCE_PDO estiver claro, o WMI ignorará Pdo.

Retornar valor

DpWmiQueryReginfo sempre retorna STATUS_SUCCESS.

Comentários

A WMI chama a rotina DpWmiQueryReginfo de um driver depois que o driver chama WmiSystemControl em resposta a uma solicitação de IRP_MN_REGINFO ou IRP_MN_REGINFO_EX . O driver deve colocar o endereço de sua rotina DpWmiQueryReginfo na estrutura WMILIB_CONTEXT que ele passa para WmiSystemControl.

O WMI envia o IRP depois que um driver chama IoWMIRegistrationControl com WMIREG_ACTION_REGISTER, WMIREG_ACTION_REREGISTER ou WMIREG_ACTION_UPDATE. O WMI lida de forma transparente com as diferenças entre IRP_MN_REGINFO e IRP_MN_REGINFO_EX em nome do driver.

O WMI não envia uma solicitação de IRP_MN_REGINFO ou IRP_MN_REGINFO_EX depois que um driver chama IoWMIRegistrationControl com WMIREG_ACTION_DEREGISTER, pois o WMI não requer mais informações do driver. Um driver normalmente desregistre seus blocos em resposta a uma solicitação de IRP_MN_REMOVE_DEVICE .

O driver fornece informações de registro novas ou atualizadas sobre blocos individuais ou indica blocos a serem removidos, na estrutura WMILIB_CONTEXT que ele passa para WmiSystemControl. Após a chamada inicial, que estabelece o caminho do registro do driver e o nome do recurso MOF, a rotina DpWmiQueryReginfo de um driver pode alterar sinalizadores comuns a todos os blocos de um driver, fornecer uma cadeia de caracteres de nome base diferente usada para gerar nomes de instância ou alterar a base para nomes de instância de uma cadeia de caracteres para o caminho da instância do dispositivo do PDO.

O driver não deve retornar STATUS_PENDING ou bloquear a solicitação. O driver não deve concluir a solicitação chamando WmiCompleteRequest de sua rotina DpWmiQueryReginfo ou chamando IoCompleteRequest após o retorno de WmiSystemControl .

Essa rotina pode ser paginável.

Para obter mais informações sobre como implementar essa rotina, consulte Chamando WmiSystemControl para lidar com IRPs WMI.