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

Artigo
02/27/2024

A rotina DpWmiExecuteMethod executa um método associado a um bloco de dados. Essa rotina é opcional.

Sintaxe

WMI_EXECUTE_METHOD_CALLBACK WmiExecuteMethodCallback;

NTSTATUS WmiExecuteMethodCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG MethodId,
  [in]      ULONG InBufferSize,
  [in]      ULONG OutBufferSize,
  [in, out] PUCHAR Buffer
)
{...}

Parâmetros

[in] DeviceObject

Ponteiro para a estrutura de DEVICE_OBJECT do WDM do driver.

[in] Irp

Ponteiro para o IRP.

[in] GuidIndex

Especifica o bloco de dados fornecendo um índice baseado em zero na lista de GUIDs que o driver forneceu na estrutura WMILIB_CONTEXT passada para WmiSystemControl.

[in] InstanceIndex

Se o bloco especificado por GuidIndex tiver várias instâncias, InstanceIndex especificará um valor de índice baseado em zero que identifica a instância.

[in] MethodId

Especifica a ID do método a ser executado. O driver define a ID do método como um item em um bloco de dados.

[in] InBufferSize

Indica o tamanho em bytes dos dados de entrada. Se não houver dados de entrada, InBufferSize será zero.

[in] OutBufferSize

Indica o número de bytes disponíveis no buffer para dados de saída.

[in, out] Buffer

Ponteiro para um buffer que contém dados de entrada, se houver, e recebe dados de saída, se houver, para o método . Se o buffer for muito pequeno para receber todos os dados de saída, o driver retornará STATUS_BUFFER_TOO_SMALL e chamará WmiCompleteRequest com o tamanho necessário.

Retornar valor

DpWmiExecuteMethod retorna STATUS_SUCCESS ou um código de erro apropriado, como o seguinte:

Comentários

O WMI chama a rotina DpWmiExecuteMethod de um driver depois que o driver chama WmiSystemControl em resposta a uma solicitação de IRP_MN_EXECUTE_METHOD .

Se um driver implementar uma rotina DpWmiExecuteMethod , o driver deverá colocar o endereço da rotina no membro ExecuteWmiMethod da estrutura WMILIB_CONTEXT que ele passa para WmiSystemControl. Se um driver não implementar uma rotina DpWmiExecuteMethod , ele deverá definir ExecuteWmiMethod como NULL. No último caso, o WMI retorna STATUS_INVALID_DEVICE_REQUEST ao chamador em resposta a qualquer solicitação de IRP_MN_EXECUTE_METHOD .

O driver é responsável por validar todos os argumentos de entrada. Especificamente, o driver deve fazer o seguinte:

Verifique se o valor guidIndex está entre zero e GuidCount-1, com base no membro GuidCount da estrutura WMILIB_CONTEXT .
Verifique se o driver não sinalizou o bloco de dados especificado para remoção. Se o driver especificou recentemente o sinalizador WMIREG_FLAG_REMOVE_GUID em uma estrutura WMIGUIDREGINFO contida em uma estrutura WMILIB_CONTEXT , é possível que uma solicitação adicional chegue antes que a remoção ocorra.
Verifique se o valor InstanceIndex está dentro do intervalo de índices de instância com suporte do driver para o bloco de dados.
Verifique se o identificador de método fornecido por MethodId é um identificador válido para o bloco de dados especificado e se o chamador tem permissão para executar o método.
Verifique se Buffer e InBufferSize descrevem um buffer grande o suficiente para conter os parâmetros de entrada do método especificado, incluindo preenchimento, se necessário, e verifique se os parâmetros de entrada são válidos.
Verifique se Buffer e OutBufferSize descrevem um buffer grande o suficiente para receber os dados de saída do método especificado, incluindo preenchimento, se necessário.

Não suponha que o contexto de thread seja o do aplicativo de modo de usuário iniciador— um driver de nível superior pode tê-lo alterado.

Se o método especificado executar uma operação que cause perda de dados, como buscar e redefinir o conteúdo de um conjunto de contadores, o driver deverá validar o tamanho do buffer de saída antes de executar a operação. Dessa forma, o driver pode retornar STATUS_BUFFER_TOO_SMALL e permitir que o chamador reenvie a solicitação com um buffer maior, sem redefinir prematuramente os contadores.

Depois de executar o método e gravar quaisquer dados de saída no buffer, o driver chama WmiCompleteRequest para concluir a solicitação.

Essa rotina pode ser paginável.

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