Função ProbeForWrite (wdm.h)

Aviso

A função ProbeForWrite não é recomendada para uso no software atual e está incluída apenas para compatibilidade histórica. Em vez disso, use ProbeForRead ao validar buffers de usuário. Consulte Comentários para obter mais informações.

A rotina ProbeForWrite verifica se um buffer do modo de usuário realmente reside na parte do modo de usuário do espaço de endereço, é gravável e está alinhado corretamente.

Sintaxe

void ProbeForWrite(
  [in, out] volatile VOID *Address,
  [in]      SIZE_T        Length,
  [in]      ULONG         Alignment
);

Parâmetros

[in, out] Address

Especifica o início do buffer do modo de usuário.

[in] Length

Especifica o comprimento, em bytes, do buffer do modo de usuário. Consulte informações adicionais na seção Comentários.

[in] Alignment

Especifica o alinhamento necessário, em bytes, do início do buffer do modo de usuário.

Retornar valor

Nenhum

Comentários

Essa função normalmente não oferece nenhum benefício substancial sobre ProbeForRead porque um driver robusto deve estar sempre preparado para lidar com alterações de proteção no espaço de endereço virtual do modo de usuário, incluindo alterações de proteção que removem a permissão de gravação para um buffer passado para um driver após a execução de uma chamada ProbeForWrite . Como ProbeForWrite acessa cada página no buffer fornecido, o desempenho pode ser reduzido devido à sobrecarga de acesso a cada página, especialmente se o buffer fornecido descreve uma grande região de espaço de endereço virtual. Além disso, como ProbeForWrite grava em cada página, o mesmo buffer pode não ser usado com segurança com várias solicitações de driver simultâneas. Por esses motivos, o novo código de driver sempre deve usar ProbeForRead .

A tabela a seguir descreve as propriedades de cada rotina de investigação de buffer do modo kernel:

Comportamento	ProbeForRead	ProbeForWrite
Confirma se o buffer descreve uma região no espaço de endereço do modo de usuário, se o comprimento não for zero	x	x
Confirma que o endereço base e o comprimento do buffer não encapsulam o valor máximo do ponteiro	x	x
Confirma se o buffer está alinhado ao limite de alinhamento solicitado, se o comprimento não for zero	x	x
Confirma se o buffer é inicialmente gravável (pode ser alterado a qualquer momento se o aplicativo do modo de usuário proteger novamente seu espaço de endereço)		x
Acessa cada página no buffer (sobrecarga adicional)		x
Modifica cada página no buffer (pode causar um comportamento inesperado se o mesmo buffer for usado em paralelo com várias solicitações de driver)		x

Historicamente, em determinados processadores que não honravam as permissões somente leitura para o código do modo kernel, havia diferenças funcionais significativas entre ProbeForWrite e ProbeForRead. Nesses casos, o sistema operacional anteriormente se baseava em ProbeForWrite executando uma marcar de gravação de paginação explícita. Essa distinção não é mais significativa para processadores compatíveis com Windows NT 4.0 ou posterior.

Comentários herdados

Os drivers no modo kernel podem usar ProbeForWrite para validar o acesso de gravação a buffers alocados no espaço do usuário. É mais comumente usado durante METHOD_NEITHER E/S para validar o buffer de usuário apontado por Irp-UserBuffer>.

Se o intervalo de memória especificado não for um intervalo de endereços válido no modo de usuário ou não for gravável (sem acesso, somente leitura e assim por diante), ProbeForWrite gerará a exceção STATUS_ACCESS_VIOLATION. Se o início do intervalo de endereços não estiver alinhado no limite de bytes especificado por Alignment, ProbeForWrite gerará a exceção STATUS_DATATYPE_MISALIGNMENT.

Os drivers devem chamar ProbeForWrite dentro de um bloco try/except . Se a rotina gerar uma exceção, o driver deverá concluir o IRP com o erro apropriado. Observe que os acessos subsequentes do driver ao buffer do modo de usuário também devem ser encapsulados em um bloco try/except : um aplicativo mal-intencionado pode ter outro thread excluindo, substituindo ou alterando a proteção de intervalos de endereços do usuário a qualquer momento (mesmo após ou durante uma chamada para ProbeForRead ou ProbeForWrite). Para obter mais informações, consulte Tratamento de exceções.

Não use essa rotina em endereços no modo kernel; ele gerará uma exceção.

Se os campos Irp-RequestorMode> = KernelMode, os campos Irp-AssociatedIrp.SystemBuffer> e Irp-UserBuffer> não contiverem endereços de modo de usuário e uma chamada para ProbeForWrite para investigar um buffer apontado por ambos os campos gerará uma exceção.

Se Length = 0, ProbeForWrite não faz nenhuma verificação do endereço. Nesse caso, a rotina não gera uma exceção para um endereço desalinhado ou está fora do intervalo de endereços de usuário válidos.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 2000.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
Regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), IrqlExApcLte2(wdm)

Confira também

ProbeForRead