IRP_MN_CHANGE_SINGLE_INSTANCE

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 IRP_MN_CHANGE_SINGLE_INSTANCE , a WMI, por sua vez, chamará a rotina DpWmiSetDataBlock desse driver.

Código principal

IRP_MJ_SYSTEM_CONTROL

Quando enviado

O WMI envia esse IRP para alterar todos os itens 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 é encontrado 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 à instância a ser alterada.

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

Parameters.WMI.Buffer aponta para uma estrutura WNODE_SINGLE_INSTANCE que identifica a instância e especifica novos valores 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_GUID_NOT_FOUND

STATUS_WMI_READ_ONLY

STATUS_WMI_SET_FAILURE

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

Operação

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

Se um driver manipular uma solicitação IRP_MN_CHANGE_SINGLE_INSTANCE em si, ele o fará somente se o ponteiro do objeto do dispositivo em Parameters.WMI.ProviderId corresponder ao ponteiro passado pelo driver em sua chamada para IoWMIRegistrationControl. Caso contrário, o driver deve encaminhar a solicitação para o driver mais baixo.

Se o driver manipular a solicitação, ele deverá primeiro marcar o GUID em Parameters.WMI.DataPath para determinar se ele identifica um bloco de dados 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 deverá marcar a estrutura de WNODE_SINGLE_INSTANCE recebida em Parameters.WMI.Buffer 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 no WNODE_SINGLE_INSTANCE de entrada. OffsetInstanceName é o deslocamento em bytes do início da estrutura para um comprimento do tamanho USHORT 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.

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 os membros DataBlockOffset e SizeDataBlock da estrutura WNODE_SINGLE_INSTANCE descrevem um bloco de dados de tamanho válido, incluindo qualquer preenchimento existente entre itens de dados e se o conteúdo do buffer é válido para o bloco de dados.
Verifique se o bloco 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 blocos 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. Se a instância tiver um nome de instância dinâmica, esse status indicará 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á os itens de dados graváveis na instância para os valores na estrutura WNODE_SINGLE_INSTANCE , deixando todos os itens somente leitura inalterados. Se todo o bloco de dados for somente leitura, o driver deverá 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.