Função FltWriteFileEx (fltkernel.h)

FltWriteFileEx é usado para gravar dados em um arquivo aberto, fluxo ou dispositivo. Essa função estende FltWriteFile para permitir o uso opcional de um MDL para dados de gravação em vez de um endereço de buffer mapeado.

Sintaxe

NTSTATUS FLTAPI FltWriteFileEx(
  [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,
  [in, optional]  PULONG                           Key,
  [in, optional]  PMDL                             Mdl
);

Parâmetros

[in] InitiatingInstance

Um ponteiro de instância opaca 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

Um ponteiro para um objeto de arquivo para o arquivo no qual os dados devem ser gravados. Este objeto de arquivo deve estar aberto no momento. Chamar FltWriteFileEx 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 pré-criar ou pós-limpeza) faz com que o sistema asserte em um build verificado. Esse parâmetro é necessário e não pode ser NULL.

[in, optional] ByteOffset

Um ponteiro para uma variável alocada por chamador que especifica o deslocamento de bytes inicial dentro do arquivo em que a operação de gravação deve começar.

Se esse deslocamento for fornecido ou se o sinalizador FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET for especificado no parâmetro Flags , FltWriteFileEx não atualizará o campo CurrentByteOffset do objeto de arquivo.

Se o objeto de arquivo ao qual FileObject aponta foi aberto para E/S síncrona, o chamador de FltWriteFileEx poderá especificar que o deslocamento da posição do arquivo atual seja usado em vez de um valor byteOffset explícito definindo esse parâmetro como NULL. Se a posição do arquivo atual for usada, FltWriteFileEx atualizará o campo CurrentByteOffset do objeto de arquivo adicionando o número de bytes gravados quando concluir a operação de gravação.

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

Nota A função FltWriteFileEx não dá suporte ao sinalizador FILE_WRITE_TO_END_OF_FILE.
 

[in] Length

O tamanho, em bytes, do buffer para o qual o parâmetro Buffer aponta. Se um MDL for fornecido no Mdl, length será o tamanho dos dados que o MDL descreve.

[in] Buffer

Um 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.

Se um MDL for fornecido no Mdl, o Buffer deverá ser NULL.

[in] Flags

Uma máscara de bits de sinalizadores que especifica 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 FltWriteFileEx 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

Um ponteiro para uma variável alocada por 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

Um ponteiro para uma rotina de retorno de chamada 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

Um ponteiro de contexto a ser passado para a rotina em CallbackRoutine se um estiver presente. Esse parâmetro é opcional e pode ser NULL. Se CallbackRoutine for NULL, esse parâmetro será ignorado.

[in, optional] Key

Uma chave opcional associada a um bloqueio de objeto de arquivo.

[in, optional] Mdl

Um MDL opcional que descreve os dados a serem gravados. Se um buffer for fornecido no Buffer, o Mdl deverá ser NULL.

Valor retornado

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

Comentários

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

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

FltWriteFileEx executará E/S não em cache se um dos seguintes for verdadeiro:

  • 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. Normalmente, isso é feito especificando o sinalizador FILE_NO_INTERMEDIATE_BUFFERINGCreateOptions 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 FltWriteFileEx:
  • 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 um buffer alinhado, chame FltAllocatePoolAlignedWithTag.
  • O deslocamento de bytes para o qual o parâmetro ByteOffset aponta deve ser um múltiplo nãonegativo do tamanho do setor do volume.
  • O comprimento especificado no parâmetro Length deve ser um múltiplo nãonegativo 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, FltWriteFileEx aguarda até que a operação de gravação seja concluída antes de retornar. Isso é verdadeiro mesmo se o objeto de arquivo ao qual FileObject aponta foi aberto para E/S assíncrona.

Se vários threads chamarem FltWriteFileEx 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 E/S no arquivo. A esse respeito, FltWriteFileEx é diferente de ZwWriteFile.

O parâmetro Mdl é fornecido como uma conveniência quando um minifiltro já tem um MDL disponível. O MDL é usado diretamente e a etapa adicional de mapeamento de um endereço para Buffer pode ser evitada.

Requisitos

   
Cliente mínimo com suporte A função FltWriteFileEx está disponível começando com Windows 8.
Plataforma de Destino Universal
Cabeçalho fltkernel.h (include Fltkernel.h)
Biblioteca FltMgr.lib
DLL Fltmgr.sys
IRQL PASSIVE_LEVEL

Confira também

FltAllocatePoolAlignedWithTag

FltCreateFile

FltCreateFileEx

FltReadFile

FltReadFileEx

ObReferenceObjectByHandle

PFLT_COMPLETED_ASYNC_IO_CALLBACK

ZwWriteFile