Função FsRtlCopyRead (ntifs.h)

A rotina FsRtlCopyRead copia dados de um arquivo armazenado em cache para um buffer de usuário.

Sintaxe

BOOLEAN FsRtlCopyRead(
  [in]  PFILE_OBJECT     FileObject,
  [in]  PLARGE_INTEGER   FileOffset,
  [in]  ULONG            Length,
  [in]  BOOLEAN          Wait,
  [in]  ULONG            LockKey,
  [out] PVOID            Buffer,
  [out] PIO_STATUS_BLOCK IoStatus,
  [in]  PDEVICE_OBJECT   DeviceObject
);

Parâmetros

[in] FileObject

Ponteiro para um objeto de arquivo para o arquivo armazenado em cache do qual os dados devem ser lidos.

[in] FileOffset

Iniciando o deslocamento de bytes dentro do arquivo armazenado em cache.

[in] Length

Comprimento em bytes dos dados a serem lidos.

[in] Wait

Defina como TRUE se o chamador puder ser colocado em um estado de espera até que todos os dados sejam copiados, caso contrário, FALSE.

[in] LockKey

Um valor associado ao intervalo de bytes a ser bloqueado. Se o intervalo a ser bloqueado se sobrepõe a outro intervalo que já está bloqueado com um bloqueio nãoclusivo ou se o intervalo a ser lido for um subconjunto de outro intervalo que já está bloqueado de forma inexistente, o valor nesse parâmetro deve ser a chave para esse bloqueio nãoclusivo O bloqueio deve ser mantido pelo processo pai do thread de chamada. Caso contrário, esse parâmetro não terá efeito.

[out] Buffer

Ponteiro para um buffer no qual os dados devem ser copiados.

[out] IoStatus

Ponteiro para uma estrutura alocada pelo chamador que recebe a conclusão final status e informações sobre a operação. Se os dados forem copiados com êxito, IoStatus.Status conterá STATUS_SUCCESS. Se nem todos os dados forem copiados com êxito, IoStatus.Information conterá o número real de bytes que foram copiados.

[in] DeviceObject

O objeto de dispositivo para o dispositivo que contém os dados do arquivo.

Retornar valor

FsRtlCopyRead retornará TRUE se a solicitação de cópia tiver sido concluída, caso contrário, FALSE. Observe que um valor retornado de TRUE não significa necessariamente que a operação de cópia foi bem-sucedida.

Se FsRtlCopyRead retornar FALSE ou se o conteúdo de IoStatus indicar que a operação de cópia falhou, o chamador deverá alocar um IRP de leitura em vez de chamar FsRtlCopyRead.

Comentários

Em vez de implementar uma rotina de leitura rápida de E/S específica do sistema de arquivos, os desenvolvedores de sistemas de arquivos que dão suporte ao cache de arquivos devem considerar o uso de FsRtlCopyRead como o ponto de entrada do sistema de arquivos para processar solicitações de leitura rápidas de E/S. Isso requer que a rotina DriverEntry do sistema de arquivos defina o ponto de entrada FastIoRead como FsRtlCopyRead na estrutura FAST_IO_DISPATCH do objeto do driver do sistema de arquivos. Além disso, o sistema de arquivos deve fazer o seguinte:

1. Para cada arquivo no qual a E/S rápida pode ser executada, o sistema de arquivos deve alocar e inicializar uma estrutura FSRTL_COMMON_FCB_HEADER.

   Na maioria dos sistemas de arquivos, isso é feito incluindo a estrutura FSRTL_COMMON_FCB_HEADER em um FCB (bloco de controle de arquivo) ou estrutura comparável que é usada para manter o estado de um arquivo aberto.

   O armazenamento para a estrutura de FSRTL_COMMON_FCB_HEADER normalmente é alocado do pool de páginas.

2. Para cada arquivo no qual a E/S rápida pode ser executada, o sistema de arquivos deve vincular quaisquer objetos de arquivo para o arquivo à estrutura FSRTL_COMMON_FCB_HEADER. Isso é feito definindo o membro FsContext de cada objeto de arquivo para apontar para essa estrutura (ou o FCB ou outra estrutura que contém a estrutura FSRTL_COMMON_FCB_HEADER).

3. Ao armazenar em cache um arquivo, o sistema de arquivos deve definir o membro IsFastIoPossible da estrutura FSRTL_COMMON_FCB_HEADER do arquivo como um valor apropriado. Esse valor deve ser atualizado conforme necessário, desde que o arquivo permaneça armazenado em cache.

   Em particular, os sistemas de arquivos devem definir o membro IsFastIoPossible da estrutura FSRTL_COMMON_FCB_HEADER como FastIoIsQuestionable assim que existir qualquer bloqueio de intervalo de bytes exclusivo no arquivo armazenado em cache.

Se Wait for TRUE, FsRtlCopyRead tem a garantia de concluir a solicitação de cópia e retornar TRUE. Se as páginas necessárias do arquivo armazenado em cache já estiverem residentes na memória, os dados serão copiados imediatamente e nenhum bloqueio ocorrerá. Se as páginas necessárias não forem residentes, o chamador será colocado em estado de espera até que todas as páginas necessárias sejam residentes e os dados possam ser copiados.

Se Wait for FALSE, FsRtlCopyRead se recusará a bloquear e retornará FALSE, se não puder adquirir o recurso main do arquivo ou se as páginas necessárias do arquivo armazenado em cache ainda não estiverem residentes na memória.

A rotina FastIoCheckIfPossible do sistema de arquivos é responsável por garantir que o intervalo de bytes definido por FileOffset e Length não inclua nenhum intervalo de bytes bloqueado exclusivamente para o qual o chamador não passe o valor de LockKey apropriado. Se o sistema de arquivos usar as rotinas de suporte do FsRtlXxxLockYyy para gerenciar bloqueios de intervalo de bytes, isso poderá ser feito chamando FsRtlFastCheckLockForRead da rotina FastIoCheckIfPossible antes de chamar FsRtlCopyRead.

Para armazenar em cache um arquivo, use a rotina CcInitializeCacheMap .

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	ntifs.h (inclua Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade de DDI	PowerIrpDDis(wdm)

Confira também

CcInitializeCacheMap

FsRtlCopyWrite

FsRtlFastCheckLockForRead