Função FsRtlCopyWrite (ntifs.h)

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

Sintaxe

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

Parâmetros

[in] FileObject

Um ponteiro para um objeto de arquivo para o arquivo armazenado em cache no qual os dados devem ser gravados.

[in] FileOffset

Um ponteiro para uma variável que especifica o deslocamento de bytes inicial dentro do arquivo armazenado em cache.

[in] Length

O comprimento em bytes dos dados a serem gravados.

[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 sobrepor a outro intervalo que já está bloqueado com um bloqueio não existente ou se o intervalo a ser lido for um subintervalo de outro intervalo que já está bloqueado de forma inexistente, o valor nesse parâmetro deverá ser a chave para esse bloqueio não próximo O bloqueio deve ser mantido pelo processo pai do thread de chamada. Caso contrário, esse parâmetro não terá efeito.

[in] Buffer

Um ponteiro para o buffer do qual os dados devem ser copiados.

[out] IoStatus

Um 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

Um ponteiro para o objeto de dispositivo para o volume montado que contém os dados do arquivo.

Retornar valor

FsRtlCopyWrite 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 FsRtlCopyWrite 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 gravação em vez de chamar FsRtlCopyWrite.

Comentários

Em vez de implementar uma rotina de gravação 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 FsRtlCopyWrite como o ponto de entrada do sistema de arquivos para processar solicitações rápidas de gravação de E/S. Isso requer que a rotina DriverEntry do sistema de arquivos defina o ponto de entrada FastIoWrite como FsRtlCopyWrite na estrutura FAST_IO_DISPATCH do objeto de 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 de 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 paginado.

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 para 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, será garantido que FsRtlCopyWrite copie os dados e retorne 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 um estado de espera até que todas as páginas necessárias sejam residentes e os dados possam ser copiados.

Se Wait for FALSE, FsRtlCopyWrite 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 FsRtlFastCheckLockForWrite 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 da DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

Confira também

CcInitializeCacheMap

FsRtlCopyRead

FsRtlFastCheckLockForWrite