IRP_MN_EXECUTE_METHOD
Todos os drivers que dão suporte a métodos em blocos de dados devem lidar com esse IRP. Um driver pode lidar com IRPs WMI chamando WmiSystemControl ou manipulando o IRP em si, conforme descrito em Tratamento de Solicitações WMI.
Se um driver chamar WmiSystemControl para lidar com uma solicitação IRP_MN_EXECUTE_METHOD , a WMI, por sua vez, chamará a rotina DpWmiExecuteMethod desse driver.
Código principal
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 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.
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ãopagado em Parameters.WMI.Buffer , que deve ser >= sizeof(WNODE_METHOD_ITEM) mais o tamanho de qualquer dado 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 houver. Parameters.WMI.Buffer-> SizeDataBlock indica o tamanho em bytes do WNODE_METHOD_ITEM de entrada, 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 dados retornados pela rotina DpWmiExecuteMethod do driver.
Caso contrário, o driver preencherá a estrutura de WNODE_METHOD_ITEM para a qual Parameters.WMI.Buffer aponta da seguinte maneira:
Atualizações WnodeHeader.BufferSize com o tamanho do WNODE_METHOD_ITEM de saída, incluindo todos os dados de saída.
Atualizações 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 quaisquer dados de saída. Se o buffer não for grande o suficiente, o driver preencherá o tamanho necessário em uma estrutura 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 houver, sobre 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 definirá Irp-IoStatus.Status> e Irp-IoStatus.Information> no bloco de E/S status.
Caso contrário, o driver define Irp-IoStatus.Status> como STATUS_SUCCESS ou para um erro apropriado status como o seguinte:
STATUS_BUFFER_TOO_SMALL
STATUS_WMI_GUID_NOT_FOUND
STATUS_WMI_INSTANCE_NOT_FOUND
STATUS_WMI_ITEMID_NOT_FOUND
Com ê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 lidar com IRPs WMI chamando WmiSystemControl ou manipulando o IRP em si, conforme descrito em Tratamento de 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 apontar para o mesmo objeto de dispositivo que o ponteiro que o driver passou para IoWMIRegistrationControl. Caso contrário, o driver deve encaminhar a solicitação para o driver mais baixo.
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_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 compatível com o driver.
Verifique se o membro MethodId da estrutura WNODE_METHOD_ITEM está dentro do intervalo de identificadores de método com suporte do 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 de WNODE_METHOD_ITEM depois de ser atualizado com os dados de saída.
Não suponha que o contexto do thread seja o do aplicativo de modo de usuário iniciado – um driver de nível superior pode tê-lo alterado.
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.
Se o driver der suporte ao bloco de dados, ele verificará o WNODE_METHOD_ITEM de entrada em Parameters.WMI.Buffer para obter o 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_METHOD_ITEM 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 consultando 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 de entrada para determinar se ele é um método válido para esse bloco de dados. Caso contrário, o driver falhará no IRP e retornará STATUS_WMI_ITEMID_NOT_FOUND.
Se o método gerar saída, o driver deverá marcar 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 redefinir os contadores, o driver deverá marcar 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 reenviar a solicitação com segurança com um buffer maior.
Se a instância e a ID do método forem válidas e o buffer for adequado em tamanho, o driver executará o método . Se SizeDataBlock no WNODE_METHOD_ITEM de entrada 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 gravará os dados de saída no buffer começando em DataBlockOffset e definirá SizeDataBlock na saída WNODE_METHOD_ITEM para o número de bytes de dados de saída. Se o método não tiver dados de saída, o driver definirá 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 lidar com a solicitação, ele poderá retornar qualquer erro apropriado status.
Requisitos
parâmetro |
Wdm.h (inclua Wdm.h, Ntddk.h ou Ntifs.h) |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de