Função FltWriteFile (fltkernel.h)

Artigo
11/16/2023

FltWriteFile é usado para gravar dados em um arquivo aberto, fluxo ou dispositivo.

Sintaxe

NTSTATUS FLTAPI FltWriteFile(
  [in]            PFLT_INSTANCE                    InitiatingInstance,
  [in]            PFILE_OBJECT                     FileObject,
  [in, optional]  PLARGE_INTEGER                   ByteOffset,
  [in]            ULONG                            Length,
  [in]            PVOID                            Buffer,
  [in]            FLT_IO_OPERATION_FLAGS           Flags,
  [out, optional] PULONG                           BytesWritten,
  [in, optional]  PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
  [in, optional]  PVOID                            CallbackContext
);

Parâmetros

[in] InitiatingInstance

Um ponteiro de instância opaco para a instância do driver de minifiltro para a qual a operação deve ser enviada. A instância deve ser anexada ao volume em que o arquivo reside. Esse parâmetro é necessário e não pode ser NULL.

[in] FileObject

Ponteiro para um FILE_OBJECT para o arquivo no qual os dados devem ser gravados. Esse objeto de arquivo deve estar aberto no momento. Chamar FltWriteFile quando o objeto de arquivo ainda não está aberto ou não está mais aberto (por exemplo, em uma rotina de retorno de chamada de pré-criação ou pós-limpeza) faz com que o sistema assert em um build verificado. Esse parâmetro é necessário e não pode ser NULL.

[in, optional] ByteOffset

Ponteiro para uma variável alocada pelo chamador que especifica o deslocamento de bytes inicial dentro do arquivo em que a operação de leitura deve começar.

Se ByteOffset for especificado, a E/S será executada nesse deslocamento, independentemente do valor atual do campo CurrentByteOffset do objeto de arquivo.

Se o arquivo tiver sido aberto para E/S síncrona (FO_SYNCHRONOUS_IO estiver definido no campo Flags do objeto de arquivo), o chamador poderá definir ByteOffset-LowPart> como FILE_USE_FILE_POINTER_POSITION e ByteOffset-HighPart> como -1 para que a E/S seja executada no campo CurrentByteOffset do objeto de arquivo. Se o arquivo não tiver sido aberto para E/S síncrona, usar FILE_USE_FILE_POINTER_POSITION será um erro.
O chamador pode definir ByteOffset-LowPart> como FILE_WRITE_TO_END_OF_FILE e ByteOffset-HighPart> como -1 para iniciar a gravação no final do arquivo (ou seja, executar uma gravação de acréscimo).

Se ByteOffset não for especificado:

Se o arquivo não foi aberto para E/S síncrona, isso é um erro.
Caso contrário, a E/S será executada no CurrentByteOffset do objeto de arquivo.

Se o objeto de arquivo tiver sido aberto para E/S síncrona, o campo CurrentByteOffset será atualizado, a menos que o chamador passe o sinalizador FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET.

Observação: o sistema de arquivos ainda atualiza CurrentByteOffset nesse caso. O Gerenciador de Filtros salva o valor CurrentByteOffset antes de enviar a E/S para baixo na pilha e restaura-a quando a E/S retorna. Da perspectiva do chamador de FltWriteFile (e filtros em altitudes mais altas), o CurrrentByteOffset não é atualizado. Mas os filtros abaixo do chamador veem o valor currentByteOffset atualizado em seus retornos de chamada pós-leitura/gravação.

Se o objeto de arquivo não tiver sido aberto para E/S síncrona, o campo CurrentByteOffset não será atualizado independentemente do estado do parâmetro ByteOffset .

Se o objeto de arquivo para o qual FileObject aponta foi aberto para E/S assíncrona, esse parâmetro é necessário e não pode ser NULL.

Antes de Windows 8, as constantes especiais FILE_WRITE_TO_END_OF_FILE e FILE_USE_FILE_POINTER_POSITION não têm suporte para esse parâmetro.

[in] Length

Tamanho, em bytes, do buffer para o qual o parâmetro Buffer aponta.

[in] Buffer

Ponteiro para um buffer que contém os dados a serem gravados no arquivo. Se o arquivo for aberto para E/S não armazenada em cache, esse buffer deverá ser alinhado de acordo com o requisito de alinhamento do dispositivo de armazenamento subjacente. Os drivers de minifiltro podem alocar esse buffer alinhado chamando FltAllocatePoolAlignedWithTag.

[in] Flags

Máscara de bits de sinalizadores especificando o tipo de operação de gravação a ser executada.

Sinalizador	Significado
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET	Os drivers de minifiltro podem definir esse sinalizador para especificar que FltWriteFile não atualizará o campo CurrentByteOffset do objeto de arquivo.
FLTFL_IO_OPERATION_NON_CACHED	Os drivers de minifiltro podem definir esse sinalizador para especificar uma gravação não em cache, mesmo que o objeto de arquivo não tenha sido aberto com FILE_NO_INTERMEDIATE_BUFFERING.
FLTFL_IO_OPERATION_PAGING	Os drivers de minifiltro podem definir esse sinalizador para especificar uma gravação de paginação.
FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING	Os drivers de minifiltro podem definir esse sinalizador para especificar uma gravação de E/S de paginação síncrona. Os drivers de minifiltro que definem esse sinalizador também devem definir o sinalizador FLTFL_IO_OPERATION_PAGING. Esse sinalizador está disponível a partir do Windows Vista.

[out, optional] BytesWritten

Ponteiro para uma variável alocada pelo chamador que recebe o número de bytes gravados no arquivo. Se CallbackRoutine não for NULL, esse parâmetro será ignorado. Caso contrário, esse parâmetro é opcional e pode ser NULL.

[in, optional] CallbackRoutine

Ponteiro para uma rotina de retorno de chamada com tipo PFLT_COMPLETED_ASYNC_IO_CALLBACK para chamar quando a operação de gravação for concluída. Esse parâmetro é opcional e pode ser NULL.

[in, optional] CallbackContext

Ponteiro de contexto a ser passado para a CallbackRoutine se houver um. Esse parâmetro é opcional e pode ser NULL. Se CallbackRoutine for NULL, esse parâmetro será ignorado.

Retornar valor

FltWriteFile retorna o valor NTSTATUS que foi retornado pelo sistema de arquivos.

Comentários

Um driver de minifiltro chama FltWriteFile para gravar dados em um arquivo aberto.

FltWriteFile faz com que uma solicitação de gravação seja enviada para as instâncias de driver de minifiltro anexadas abaixo da instância inicial e ao sistema de arquivos. A instância especificada e as instâncias anexadas acima dela não recebem a solicitação de gravação.

FltWriteFile executará E/S não armazenado em cache se uma das seguintes opções for verdadeira:

O chamador define o sinalizador FLTFL_IO_OPERATION_NON_CACHED no parâmetro Flags .
O objeto de arquivo foi aberto para E/S não armazenado em cache. Normalmente, isso é feito especificando o sinalizador FILE_NO_INTERMEDIATE_BUFFERING CreateOptions na chamada anterior para FltCreateFile, FltCreateFileEx ou ZwCreateFile.

A E/S não em cache impõe as seguintes restrições aos valores de parâmetro passados para FltWriteFile:

O buffer para o qual o parâmetro Buffer aponta deve ser alinhado de acordo com o requisito de alinhamento do dispositivo de armazenamento subjacente. Para alocar esse buffer alinhado, chame FltAllocatePoolAlignedWithTag.
O deslocamento de bytes para o qual o parâmetro ByteOffset aponta deve ser um múltiplo não negativo do tamanho do setor do volume.
O comprimento especificado no parâmetro Length deve ser um múltiplo não negativo do tamanho do setor do volume.

Se o valor do parâmetro CallbackRoutine não for NULL, a operação de gravação será executada de forma assíncrona.

Se o valor do parâmetro CallbackRoutine for NULL, a operação de gravação será executada de forma síncrona. Ou seja, FltWriteFile aguarda até que a operação de gravação seja concluída antes de retornar. Isso é verdadeiro mesmo se o objeto de arquivo para o qual FileObject aponta foi aberto para E/S assíncrona.

Se vários threads chamarem FltWriteFile para o mesmo objeto de arquivo e o objeto de arquivo tiver sido aberto para E/S síncrona, o Gerenciador de Filtros não tentará serializar a E/S no arquivo. Nesse sentido, FltWriteFile difere de ZwWriteFile.