IRP_MN_EXECUTE_METHOD

Todos os drivers que suportam métodos em blocos de dados devem lidar com esse IRP. Um driver pode manipular IRPs WMI chamando WmiSystemControl ou manipulando o próprio IRP, conforme descrito em Tratando solicitações WMI.

Se um driver chamar WmiSystemControl para manipular uma solicitação IRP_MN_EXECUTE_METHOD , o WMI, por sua vez, chamará a rotina DpWmiExecuteMethod desse driver.

Código principal

IRP_MJ_SYSTEM_CONTROL

Quando enviado

O WMI envia esse IRP para executar um método associado a um bloco de dados.

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

O WMI enviará um IRP_MN_QUERY_SINGLE_INSTANCE antes de enviar um IRP_MN_EXECUTE_METHOD. Se um driver dá suporte IRP_MN_EXECUTE_METHOD deve ter um manipulador IRP_MN_QUERY_SINGLE_INSTANCE para o mesmo bloco de dados cujo método está sendo executado.

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 associado ao método a ser executado.

Parameters.WMI.BufferSize indica o tamanho do buffer não papagado em Parameters.WMI.Buffer>, que deve ser = sizeof(WNODE_METHOD_ITEM) mais o tamanho de quaisquer dados de saída para o método.

Parameters.WMI.Buffer aponta para uma estrutura WNODE_METHOD_ITEM na qual MethodID indica o identificador do método a ser executado e DataBlockOffset indica o deslocamento em bytes do início da estrutura para o primeiro byte de dados de entrada, se algum. Parameters.WMI.Buffer-> SizeDataBlock indica o tamanho em bytes da entrada WNODE_METHOD_ITEM incluindo dados de entrada ou zero se não houver nenhuma entrada.

Parâmetros de saída

Se o driver manipular IRPs WMI chamando WmiSystemControl, o WMI preencherá o WNODE_METHOD_ITEM com os dados retornados pela rotina DpWmiExecuteMethod do driver.

Caso contrário, o driver preencherá a estrutura WNODE_METHOD_ITEM que Parameters.WMI.Buffer aponta da seguinte maneira:

  • Atualiza WnodeHeader.BufferSize com o tamanho da saída WNODE_METHOD_ITEM, incluindo quaisquer dados de saída.

  • Atualiza SizeDataBlock com o tamanho dos dados de saída ou zero se não houver dados de saída.

  • Verifica Parameters.WMI.Buffersize para determinar se o buffer é grande o suficiente para receber a saída WNODE_METHOD_ITEM incluindo dados de saída. Se o buffer não for grande o suficiente, o driver preencherá o tamanho necessário em uma estrutura de WNODE_TOO_SMALL apontada por Parameters.WMI.Buffer. Se o buffer for menor que sizeof(WNODE_TOO_SMALL), o driver falhará no IRP e retornará STATUS_BUFFER_TOO_SMALL.

  • Grava dados de saída, se algum, em dados de entrada começando em DataBlockOffset. O driver não deve alterar o valor de entrada de DataBlockOffset.

Bloco de status de E/S

Se o driver manipular o IRP chamando WmiSystemControl, o WMI define 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 com um status de erro apropriado, como o seguinte:

STATUS_BUFFER_TOO_SMALL

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_INSTANCE_NOT_FOUND

STATUS_WMI_ITEMID_NOT_FOUND

Em caso de êxito, um driver define Irp-IoStatus.Information> como o número de bytes gravados no buffer em Parameters.WMI.Buffer.

Operação

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

Se um driver manipular IRPs WMI chamando WmiSystemControl, essa rotina chamará a rotina DpWmiExecuteMethod do driver ou retornará STATUS_INVALID_DEVICE_REQUEST se o driver não definir a rotina.

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

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

  • Para nomes estáticos, verifique se o membro InstanceIndex da estrutura WNODE_METHOD_ITEM 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 com suporte pelo driver.

  • Verifique se o membro MethodId da estrutura WNODE_METHOD_ITEM está dentro do intervalo de identificadores de método com suporte pelo driver para o bloco de dados e se o chamador tem permissão para executar o método.

  • Verifique se os membros DataBlockOffset e SizeDataBlock da estrutura WNODE_METHOD_ITEM descrevem um buffer grande o suficiente para conter os parâmetros do método especificado e se os parâmetros são válidos para o método .

  • Verifique se Parameters.WMI.Buffersize especifica um buffer grande o suficiente para receber a estrutura WNODE_METHOD_ITEM depois que ele tiver sido atualizado com os dados de saída.

Não suponha que o contexto de thread seja o do aplicativo de modo de usuário que está iniciando – um driver de nível superior pode ter alterado.

Antes de manipular a solicitação, o driver deve determinar se Parameters.WMI.DataPath aponta para um GUID com suporte pelo driver. Caso não, o driver deverá falhar no IRP e retornar STATUS_WMI_GUID_NOT_FOUND.

Se o driver for compatível com o bloco de dados, ele verificará a WNODE_METHOD_ITEM emParameters.WMI.Buffer para o nome da instância, da seguinte forma:

  • 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 na entrada WNODE_METHOD_ITEM. 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.

Em seguida, o driver verifica a ID do método no WNODE_METHOD_ITEM para determinar se ele é um método válido para esse bloco de dados. Caso não seja, o driver falhará no IRP e retornará STATUS_WMI_ITEMID_NOT_FOUND.

Se o método gerar saída, o driver deverá verificar o tamanho do buffer de saída em Parameters.WMI.BufferSize antes de executar qualquer operação que possa ter efeitos colaterais ou que não deve ser executada duas vezes. Por exemplo, se um método retornar os valores de um grupo de contadores e, em seguida, redefinir os contadores, o driver deverá verificar o tamanho do buffer (e falhar o IRP se o buffer for muito pequeno) antes de redefinir os contadores. Isso garante que o WMI possa reendá-la com segurança com um buffer maior.

Se a instância e a ID do método são válidas e o buffer é adequado em tamanho, o driver executa o método . Se SizeDataBlock na entrada WNODE_METHOD_ITEM for diferente de zero, o driver usará os dados começando em DataBlockOffset como entrada para o método .

Se o método gerar saída, o driver grava os dados de saída no buffer começando em DataBlockOffset e define SizeDataBlock na saída WNODE_METHOD_ITEM o número de bytes de dados de saída. Se o método não tiver dados de saída, o driver define SizeDataBlock como zero. O driver não deve alterar o valor de entrada de DataBlockOffset.

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

Requisitos

Cabeçalho

Wdm.h (inclua Wdm.h, Ntddk.h ou Ntifs.h)

Confira também

DpWmiExecuteMethod

IoWMIRegistrationControl

WMILIB_CONTEXT

WmiSystemControl

WNODE_METHOD_ITEM