IRP_MN_QUERY_SINGLE_INSTANCE

Artigo
06/15/2023

Todos os drivers que dão suporte ao WMI devem lidar com esse IRP. Um driver pode lidar com IRPs WMI chamando WmiSystemControl ou manipulando o próprio IRP, conforme descrito em Manipulando solicitações WMI.

Se um driver chamar WmiSystemControl para lidar com uma solicitação de IRP_MN_QUERY_SINGLE_INSTANCE , o WMI, por sua vez, chamará a rotina DpWmiQueryDataBlock desse driver.

Código principal

IRP_MJ_SYSTEM_CONTROL

Quando enviado

O WMI envia esse IRP para consultar uma única instância de um determinado bloco de dados.

O WMI envia uma IRP_MN_QUERY_SINGLE_INSTANCE antes de enviar uma IRP_MN_EXECUTE_METHOD. Se um driver der suporte a IRP_MN_EXECUTE_METHOD, ele deverá ter um manipulador de IRP_MN_QUERY_SINGLE_INSTANCE para o mesmo bloco de dados cujo método está sendo executado.

O WMI envia esse IRP em IRQL = PASSIVE_LEVEL em um contexto de thread arbitrário.

Parâmetros de Entrada

Parameters.WMI.ProviderId aponta para o objeto de dispositivo do driver que deve responder à solicitação. Esse ponteiro está localizado no local da pilha de E/S do driver no IRP.

Parameters.WMI.DataPath aponta para um GUID que identifica o bloco de dados a ser consultado.

Parameters.WMI.BufferSize indica o tamanho máximo do buffer nãopagado em Parameters.WMI.Buffer, que aponta para uma estrutura WNODE_SINGLE_INSTANCE que identifica a instância a ser consultada.

Parâmetros de saída

Se o driver manipular IRPs WMI chamando WmiSystemControl, o WMI preencherá uma estrutura de WNODE_SINGLE_INSTANCE com dados fornecidos pela rotina DpWmiQueryDataBlock do driver.

Caso contrário, o driver preencherá a estrutura WNODE_SINGLE_INSTANCE em Parameters.WMI.Buffer da seguinte maneira:

Atualizações WnodeHeader.BufferSize com o tamanho, em bytes, da estrutura de WNODE_SINGLE_INSTANCE de saída, incluindo dados de instância. Esse valor deve incluir o comprimento do nome da instância (preenchido de modo que os dados da instância comecem em um limite de palavra quad), mesmo que a classe que está sendo consultada nome de instância estática registrada e o gravador de driver não forneça explicitamente o nome ao atender a esse IRP.
Define SizeDataBlock como o tamanho, em bytes, dos dados da instância. Se nomes de instância estática estiverem em uso, esse valor não deverá incluir o tamanho do nome da instância.
Grava os dados da instância em Parameters.WMI.Buffer começando em DataBlockOffset. O driver não deve alterar o valor de entrada de DataBlockOffset.

Se o buffer em Parameters.WMI.Buffer for muito pequeno para receber todos os dados, o driver preencherá o tamanho necessário em uma estrutura WNODE_TOO_SMALL em Parameters.WMI.Buffer. Se o buffer for menor que sizeof(WNODE_TOO_SMALL), o driver falhará no IRP e retornará STATUS_BUFFER_TOO_SMALL.

Bloco de Status de E/S

Se o driver manipular o IRP chamando WmiSystemControl, o WMI definirá Irp-IoStatus.Status> e Irp-IoStatus.Information> no bloco de status de E/S.

Caso contrário, o driver define Irp-IoStatus.Status> como STATUS_SUCCESS ou como um erro apropriado status como o seguinte:

STATUS_BUFFER_TOO_SMALL

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_INSTANCE_NOT_FOUND

Em caso de êxito, um driver define Irp-IoStatus.Information> como o valor inserido em WnodeHeader.BufferSize. Esse valor inclui o comprimento do nome da instância estática.

Operação

Um driver pode lidar com IRPs WMI chamando WmiSystemControl ou manipulando o próprio IRP, conforme descrito em Manipulando solicitações WMI.

Se um driver manipular IRPs WMI chamando WmiSystemControl, WmiSystemControl chamará a rotina DpWmiQueryDataBlock do driver.

Se um driver manipular uma solicitação IRP_MN_QUERY_SINGLE_INSTANCE em si, ele deverá fazer isso somente se Parameters.WMI.ProviderId apontar para o mesmo objeto de dispositivo que o ponteiro que o driver passou em sua chamada para IoWMIRegistrationControl. Caso contrário, o driver deve encaminhar a solicitação para o próximo driver inferior na pilha do dispositivo.

Antes de lidar com a solicitação, o driver deve determinar se Parameters.WMI.DataPath aponta para um GUID compatível com o driver. Caso contrário, o driver deve falhar no IRP e retornar STATUS_WMI_GUID_NOT_FOUND.

O driver é responsável por validar todos os valores de entrada. Especificamente, o driver deverá fazer o seguinte se manipular a solicitação IRP em si:

Para nomes estáticos, verifique se o membro InstanceIndex da estrutura WNODE_SINGLE_INSTANCE está dentro do intervalo de índices de instância com suporte do driver para o bloco de dados.
Para nomes dinâmicos, verifique se a cadeia de caracteres de nome da instância identifica uma instância de bloco de dados compatível com o driver.
Verifique se Parameters.WMI.BufferSize especifica um buffer grande o suficiente para receber todos os dados que o driver retornará.

Se o driver der suporte ao bloco de dados, ele verificará o WNODE_SINGLE_INSTANCE de entrada em Parameters.WMI.Buffer quanto ao nome da instância, da seguinte maneira:

Se WNODE_FLAG_STATIC_INSTANCE_NAMES for definido em WnodeHeader.Flags, o driver usará InstanceIndex como um índice na lista de nomes de instância estática do driver para esse bloco. O WMI obtém o índice dos dados de registro fornecidos pelo driver quando ele registrou o bloco.
Se WNODE_FLAG_STATIC_INSTANCE_NAMES estiver claro em WnodeHeader.Flags, o driver usará o deslocamento em OffsetInstanceName para localizar a cadeia de caracteres de nome da instância no WNODE_SINGLE_INSTANCE de entrada. OffsetInstanceName é o deslocamento, em bytes, do início da estrutura para um USHORT, que é o comprimento da cadeia de caracteres de nome da instância em bytes (não caracteres), incluindo o nulo de terminação, se presente, seguido pela cadeia de caracteres de nome da instância em Unicode.

Se o driver não puder localizar a instância especificada, ele deverá falhar no IRP e retornar STATUS_WMI_INSTANCE_NOT_FOUND. Para uma instância com um nome de instância dinâmica, esse status indica que o driver não dá suporte à instância. Portanto, o WMI pode continuar a consultar outros provedores de dados e retornar um erro apropriado ao consumidor de dados se outro provedor encontrar a instância, mas não puder lidar com a solicitação por algum outro motivo.

Se o driver localizar a instância e puder lidar com a solicitação, ele preencherá a estrutura WNODE_SINGLE_INSTANCE em Parameters.WMI.Buffer com dados para a instância.

Se a instância for válida, mas o driver não puder lidar com a solicitação, ela poderá retornar qualquer erro apropriado status.