Função ZwDeviceIoControlFile (ntifs.h)
A rotina de
Sintaxe
NTSYSAPI NTSTATUS ZwDeviceIoControlFile(
[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 de quais informações devem ser retornadas. O objeto de arquivo deve 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 do DASD (Direct Access to Storage Device).
[in, optional] Event
Manipular um evento criado por um 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
[in, optional] ApcRoutine
Endereço de uma rotina de APC opcional fornecida pelo chamador a ser chamada quando a operação solicitada for concluída. Esse parâmetro pode ser NULL. Ele deve 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. Deve ser NULL se de ApcRoutine estiver 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 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
[in] IoControlCode
IOCTL_código de XXX 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ário do InputBuffer e OutputBuffer, bem como quais dos seguintes pares de parâmetros são necessários. Para obter informações detalhadas sobre os códigos de XXX IOCTL_
[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 exija 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.
Valor de retorno
ZwDeviceIoControlFile retornará STATUS_SUCCESS se os driveres subjacentes realizarem com êxito a operação solicitada. Caso contrário, o valor retornado pode ser um código de status de erro propagado de um driver subjacente. Os códigos de status de erro possíveis incluem o seguinte:
Observações
ZwDeviceIoControlFile 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 dispositivo de especificar uma interface de comunicação.
Para obter mais informações sobre IOCTL_
Se o chamador abriu o arquivo para E/S assíncrona (sem FILE_SYNCHRONOUS_XXX conjunto de opções de criação/abertura), 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
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.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 2000. |
| da Plataforma de Destino |
Universal |
| cabeçalho | ntifs.h (include Ntifs.h, Ntddk.h) |
| biblioteca | NtosKrnl.lib |
| de DLL |
NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (consulte a seção Comentários) |
| regras de conformidade de DDI | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |
Consulte também
usando códigos de controle de E/S
usando versões Nt e Zw das rotinas de serviços do sistema nativo