Função NtDeviceIoControlFile (ntifs.h)

Artigo
07/11/2023

A rotina ZwDeviceIoControlFile envia um código de controle diretamente para um driver de dispositivo especificado, fazendo com que o driver correspondente execute a operação especificada.

Sintaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtDeviceIoControlFile(
  [in]            HANDLE           FileHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            IoControlCode,
  [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 dispositivo ao qual as informações de controle devem ser fornecidas ou das quais as informações devem ser retornadas. O objeto de arquivo deverá ter sido aberto para E/S assíncrona se o chamador especificar um event, ApcRoutine e um contexto APC (em ApcContext) ou um contexto de conclusão (em ApcContext). Para e/S para um dispositivo de armazenamento em massa subjacente, o objeto de arquivo deve ter sido aberto para acesso direto ao DASD (Dispositivo de Armazenamento).

[in, optional] Event

Identificador 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 deverá ser NULL se o chamador aguardar que o FileHandle seja definido como o estado Sinalizado.

[in, optional] ApcRoutine

Endereço de uma rotina APC opcional fornecida pelo chamador a ser chamada quando a operação solicitada for concluída. Este parâmetro 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 de APC será passado para a APC, se uma tiver sido especificada, 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 variável que recebe a conclusão final status 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 .

[in] IoControlCode

IOCTL_códigoXxx que indica em qual operação de controle de E/S do dispositivo deve ser executada, geralmente pelo driver de dispositivo subjacente. O valor desse parâmetro determina o formato e o comprimento 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 IOCTL_Xxx definidos pelo sistema, específicos do tipo de dispositivo, consulte a seção específica da tecnologia do dispositivo da documentação do WDK (Microsoft Windows Driver Kit) e códigos de controle de entrada e saída do dispositivo.

[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 dispositivo de destino. Se IoControlCode especificar uma operação que não exige dados de entrada, esse ponteiro poderá ser NULL.

[in] InputBufferLength

Tamanho, em bytes, do buffer em InputBuffer. Se InputBuffer for NULL, defina InputBufferLength como zero.

[out, optional] OutputBuffer

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

[in] OutputBufferLength

Tamanho, em bytes, do buffer em OutputBuffer. Se OutputBuffer for NULL, defina OutputBufferLength como zero.

Retornar valor

ZwDeviceIoControlFile retornará STATUS_SUCCESS se os drivers subjacentes realizarem com êxito a operação solicitada. Caso contrário, o valor retornado pode ser um erro status código propagado de um driver subjacente. Possíveis códigos de status de erro incluem o seguinte:

Comentários

ZwDeviceIoControlFile fornece uma exibição consistente dos dados de entrada e saída para o sistema e para drivers de modo kernel, fornecendo aplicativos e drivers subjacentes com um método dependente de dispositivo de especificar uma interface de comunicação.

Para obter mais informações sobre códigos IOCTL_Xxx definidos pelo sistema e sobre como definir valores específicos do driver IOCTL_Xxx ou FSCTL_Xxx , consulte Usando códigos de controle de E/S e códigos de controle de entrada e saída do dispositivo.

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 de dispositivo for concluída. Caso contrário, o objeto de arquivo especificado por FileHandle será definido como o estado sinalizado. Se uma ApcRoutine tiver sido especificada, ela será chamada com os ponteiros ApcContext e IoStatusBlock .

Os minifiltros devem usar FltDeviceIoControlFile em vez de ZwDeviceIoControlFile.

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

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

Para chamadas de drivers de modo kernel, as versões NtXxx e ZwXxx de uma rotina do Windows Native System Services 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 NtXxx e ZwXxx de uma rotina, consulte 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, Ntddk.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte a seção Comentários)
Regras de conformidade da DDI	HwStorPortProhibitedDDIs, PowerIrpDDis