Função ZwFsControlFile (ntifs.h)

Artigo
07/11/2023

A rotina ZwFsControlFile envia um código de controle diretamente para um sistema de arquivos ou driver de filtro do sistema de arquivos especificado, fazendo com que o driver correspondente execute a ação especificada.

Sintaxe

NTSYSAPI NTSTATUS ZwFsControlFile(
  [in]            HANDLE           FileHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            FsControlCode,
  [in, optional]  PVOID            InputBuffer,
  [in]            ULONG            InputBufferLength,
  [out, optional] PVOID            OutputBuffer,
  [in]            ULONG            OutputBufferLength
);

Parâmetros

[in] FileHandle

Identificador retornado por ZwCreateFile ou ZwOpenFile para o objeto de arquivo que representa o arquivo ou diretório no qual a ação especificada deve ser executada. O objeto de arquivo deve ter sido aberto para E/S assíncrona se o chamador especificar um Evento, ApcRoutine e um contexto APC (em ApcContext) ou um contexto de conclusão (no ApcContext).

[in, optional] Event

Manipular para um evento criado pelo chamador. Se esse parâmetro for fornecido, o chamador será colocado em um estado de espera até que a operação solicitada seja concluída e o evento fornecido seja definido como o estado Sinalizado. Esse parâmetro é opcional e pode ser NULL. Ele deve ser NULL se o chamador aguardar que o FileHandle seja definido como o estado Sinalizado.

[in, optional] ApcRoutine

Endereço de uma rotina de APC fornecida pelo chamador a ser chamado quando a operação solicitada for concluída. Esse parâmetro é opcional e pode ser NULL. Ele deverá ser NULL se houver um objeto de conclusão de E/S associado ao objeto de arquivo.

[in, optional] ApcContext

Ponteiro para uma área de contexto determinada pelo chamador. Esse valor de parâmetro será usado como o contexto APC se o chamador fornecer um APC ou for usado como o contexto de conclusão se um objeto de conclusão de E/S tiver sido associado ao objeto de arquivo. Quando a operação for concluída, o contexto do APC será passado para o APC, se um tiver sido especificado, ou o contexto de conclusão será incluído como parte da mensagem de conclusão que o Gerenciador de E/S posta no objeto de conclusão de E/S associado.

Esse parâmetro é opcional e pode ser NULL. Ele deverá ser NULL se ApcRoutine for NULL e não houver nenhum objeto de conclusão de E/S associado ao objeto de arquivo.

[out] IoStatusBlock

Ponteiro para uma estrutura IO_STATUS_BLOCK que recebe o status de conclusão final e informações sobre a operação. Para chamadas bem-sucedidas que retornam dados, o número de bytes gravados no OutputBuffer é retornado no membro Informações dessa estrutura.

[in] FsControlCode

FSCTL_ códigoXXX que indica qual operação de controle do sistema de arquivos deve ser executada. O valor desse parâmetro determina os formatos e os comprimentos necessários de InputBuffer e OutputBuffer, bem como quais dos pares de parâmetros a seguir são necessários. Para obter informações detalhadas sobre os códigos FSCTL_XXX definidos pelo sistema, consulte a seção "Comentários" da entrada de referência para DeviceIoControl na documentação do SDK do Microsoft Windows.

[in, optional] InputBuffer

Ponteiro para um buffer de entrada alocado pelo chamador que contém informações específicas do dispositivo a serem fornecidas ao driver de destino. Se FsControlCode especificar uma operação que não requer dados de entrada, esse ponteiro será opcional e poderá ser NULL.

[in] InputBufferLength

Tamanho, em bytes, do buffer em InputBuffer. Esse valor será ignorado se InputBuffer for NULL.

[out, optional] OutputBuffer

Ponteiro para um buffer de saída alocado pelo chamador no qual as informações são retornadas do driver de destino. Se FsControlCode especificar uma operação que não produz dados de saída, esse ponteiro será opcional e poderá ser NULL.

[in] OutputBufferLength

Tamanho, em bytes, do buffer em OutputBuffer. Esse valor será ignorado se OutputBuffer for NULL.

Retornar valor

ZwFsControlFile retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes:

Comentários

ZwFsControlFile fornece uma exibição consistente dos dados de entrada e saída para o sistema e para drivers no modo kernel, ao mesmo tempo em que fornece aplicativos e drivers subjacentes com um método dependente do driver de especificar uma interface de comunicação.

Se o chamador abriu o arquivo para E/S assíncrona (sem nenhuma FILE_SYNCHRONOUS_XXX create/open option set), o evento especificado, se houver, será definido como o estado sinalizado quando a operação de controle do dispositivo for concluída. Caso contrário, o objeto de arquivo especificado por FileHandle será definido como o estado sinalizado. Se um ApcRoutine tiver sido especificado, ele será chamado com os ponteiros ApcContext e IoStatusBlock .

Os seguintes códigos FSCTL estão documentados atualmente para drivers no modo kernel:

FSCTL_DELETE_REPARSE_POINT

FSCTL_GET_REPARSE_POINT

FSCTL_OPBATCH_ACK_CLOSE_PENDING

FSCTL_OPLOCK_BREAK_ACK_NO_2

FSCTL_OPLOCK_BREAK_ACKNOWLEDGE

FSCTL_OPLOCK_BREAK_NOTIFY

FSCTL_REQUEST_BATCH_OPLOCK

FSCTL_REQUEST_FILTER_OPLOCK

FSCTL_REQUEST_OPLOCK_LEVEL_1

FSCTL_REQUEST_OPLOCK_LEVEL_2

FSCTL_SET_REPARSE_POINT

Para obter mais informações sobre códigos FSCTL_XXX definidos pelo sistema, consulte a seção "Comentários" da entrada de referência para DeviceIoControl na documentação do SDK do Microsoft Windows.

Para obter mais informações sobre códigos IOCTL_XXX definidos pelo sistema e sobre como definir valores de IOCTL_XXX ou FSCTL_XXX específicos do driver, consulte Usando códigos de controle de E/S no Guia de Arquitetura do Modo Kernel e Códigos de Controle de Entrada e Saída do Dispositivo na documentação do SDK do Windows.

Minifilters devem usar FltFsControlFile em vez de ZwFsControlFile.

Os chamadores de ZwFsControlFile devem estar em execução em IRQL = PASSIVE_LEVEL e com APCs de kernel especiais habilitadas.

Nota Se a chamada para a função ZwFsControlFile ocorrer no modo de usuário, você deverá usar o nome "NtFsControlFile" em vez de "ZwFsControlFile".

Para chamadas de drivers no modo kernel, as versões **Nt*Xxx*** e **Zw*Xxx*** de uma rotina dos Serviços do Sistema Nativo do Windows podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões **Nt*Xxx*** e **Zw*Xxx*** de uma rotina, consulte [Usando versões Nt e Zw das rotinas de serviços nativos do sistema](/windows-hardware/drivers/kernel/using-nt-and-zw-versions-of-the-native-system-services-routines).

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000.
Plataforma de Destino	Universal
Cabeçalho	ntifs.h (inclua Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte a seção Comentários)
Regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)