IRP_MN_CHANGE_SINGLE_ITEM

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 IRP em si, conforme descrito em Tratamento de Solicitações WMI.

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

Código principal

IRP_MJ_SYSTEM_CONTROL

Quando enviado

O WMI envia esse IRP para alterar um único item de dados em uma única instância de um bloco de dados.

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 definido.

Parameters.WMI.BufferSize indica o tamanho do buffer nãopagado em Parameters.WMI.Buffer.

Parameters.WMI.Buffer aponta para uma estrutura WNODE_SINGLE_ITEM que identifica a instância do bloco de dados, a ID do item a ser definido e um novo valor de dados.

Parâmetros de saída

Nenhum.

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_WMI_INSTANCE_NOT_FOUND

STATUS_WMI_ITEMID_NOT_FOUND

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_READ_ONLY

STATUS_WMI_SET_FAILURE

Com êxito, um driver define Irp-IoStatus.Information> como zero.

Operação

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

Se um driver manipular IRP_MN_CHANGE_SINGLE_ITEM solicitações propriamente ditas, ele deverá fazê-lo 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.

Não implemente suporte para IRP_MN_CHANGE_SINGLE_ITEM a menos que você tenha certeza de que um componente de modo de usuário fornecido pelo sistema requer essa funcionalidade.

Antes de lidar com uma solicitação, o driver deve determinar se Parameters.WMI.DataPath aponta para um GUID compatível com o driver. Se isso não acontecer, o driver deverá falhar no IRP e retornar STATUS_WMI_GUID_NOT_FOUND.

Se o driver der suporte ao bloco de dados, ele deverá marcar a estrutura de WNODE_SINGLE_ITEM de entrada para a qual Parameters.WMI.Buffer aponta para 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 na estrutura de WNODE_SINGLE_ITEM de entrada. OffsetInstanceName é o deslocamento em bytes do início da estrutura para um comprimento do tamanho de USHORT da cadeia de caracteres de nome da instância em bytes (não caracteres). Esse comprimento inclui o terminador NULL, se presente, seguido pela cadeia de caracteres de nome da instância em Unicode.

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_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 ItemId da estrutura WNODE_SINGLE_ITEM está dentro do intervalo de identificadores de item com suporte do driver para o bloco de dados.
Verifique se os membros DataBlockOffset e SizeDataItem da estrutura WNODE_SINGLE_ITEM descrevem um bloco de dados de tamanho válido e se o conteúdo do buffer é válido para o item de dados.
Verifique se o item de dados especificado é aquele para o qual o driver permite modificações iniciadas pelo chamador. Em outras palavras, o driver não deve permitir modificações em itens de dados que você pretendia ser somente leitura.

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.

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.

Se o driver localizar a instância e puder lidar com a solicitação, ele definirá o item de dados na instância como o valor no WNODE_SINGLE_ITEM. Se o item de dados for somente leitura, o driver deixará o item inalterado, falhará no IRP e retornará STATUS_WMI_READ_ONLY.

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.