Função IoBuildDeviceIoControlRequest (wdm.h)

Artigo
03/05/2024

A rotina IoBuildDeviceIoControlRequest aloca e configura um IRP para uma solicitação de controle de dispositivo processada de forma síncrona.

Sintaxe

__drv_aliasesMem PIRP IoBuildDeviceIoControlRequest(
  [in]            ULONG            IoControlCode,
  [in]            PDEVICE_OBJECT   DeviceObject,
  [in, optional]  PVOID            InputBuffer,
  [in]            ULONG            InputBufferLength,
  [out, optional] PVOID            OutputBuffer,
  [in]            ULONG            OutputBufferLength,
  [in]            BOOLEAN          InternalDeviceIoControl,
  [in, optional]  PKEVENT          Event,
  [out]           PIO_STATUS_BLOCK IoStatusBlock
);

Parâmetros

[in] IoControlCode

Fornece o IOCTL (código de controle de E/S) a ser usado na solicitação. Para obter informações sobre códigos de controle de E/S específicos do tipo de dispositivo, consulte seções específicas do tipo de dispositivo no WDK (Kit de Driver do Windows).

[in] DeviceObject

Fornece um ponteiro para a estrutura DEVICE_OBJECT para o objeto de dispositivo do driver mais baixo, que representa o dispositivo de destino.

[in, optional] InputBuffer

Fornece um ponteiro para um buffer de entrada a ser passado para o driver inferior ou NULL se a solicitação não passar dados de entrada para drivers inferiores.

[in] InputBufferLength

Fornece o comprimento, em bytes, do buffer de entrada. Se InputBuffer for NULL, InputBufferLength deverá ser zero.

[out, optional] OutputBuffer

Fornece um ponteiro para um buffer de saída no qual o driver inferior deve retornar dados ou NULL se a solicitação não exigir drivers inferiores para retornar dados.

[in] OutputBufferLength

Fornece o comprimento, em bytes, do buffer de saída. Se OutputBuffer for NULL, OutputBufferLength deverá ser zero.

[in] InternalDeviceIoControl

Se TRUE, a rotina define o código de função principal do IRP como IRP_MJ_INTERNAL_DEVICE_CONTROL. Caso contrário, a rotina define o código de função principal do IRP como IRP_MJ_DEVICE_CONTROL.

[in, optional] Event

Fornece um ponteiro para um objeto de evento alocado pelo chamador e inicializado. O gerenciador de E/S define o evento como o estado Sinalizado quando um driver de nível inferior conclui a operação solicitada. Depois de chamar IoCallDriver, o driver pode aguardar o objeto de evento. O parâmetro Event é opcional e pode ser definido como NULL. No entanto, se Event for NULL, o chamador deverá fornecer uma rotina IoCompletion para o IRP notificar o chamador quando a operação for concluída.

[out] IoStatusBlock

Especifica um bloco de E/S status a ser definido quando a solicitação é concluída por drivers inferiores.

Retornar valor

Se a operação for bem-sucedida, IoBuildDeviceIoControlRequest retornará um ponteiro para um IRP, com o local de pilha de E/S do driver mais baixo configurado a partir dos parâmetros fornecidos. Caso contrário, a rotina retornará NULL.

Comentários

Um driver pode chamar IoBuildDeviceIoControlRequest para configurar IRPs para solicitações de controle de dispositivo que ele envia de forma síncrona para drivers de nível inferior.

Depois de chamar IoBuildDeviceIoControlRequest para criar uma solicitação, o driver deve chamar IoCallDriver para enviar a solicitação para o driver mais baixo. Se IoCallDriver retornar STATUS_PENDING, o driver deverá aguardar a conclusão do IRP chamando KeWaitForSingleObject no Evento especificado. A maioria dos drivers não precisa definir uma rotina IoCompletion para o IRP.

Os IRPs criados por IoBuildDeviceIoControlRequest devem ser concluídos por uma chamada de driver para IoCompleteRequest. Um driver que chama IoBuildDeviceIoControlRequest não deve chamar IoFreeIrp, pois o gerente de E/S libera esses IRPs síncronos depois que IoCompleteRequest é chamado.

IoBuildDeviceIoControlRequest enfileira os IRPs que ele cria para uma fila IRP específica do thread atual. Se o thread for encerrado, o gerente de E/S cancelará o IRP.

Se o chamador fornecer um parâmetro InputBuffer ou OutputBuffer , esse parâmetro deverá apontar para um buffer que reside na memória do sistema. O chamador é responsável por validar os valores de parâmetro que copia no buffer de entrada de um buffer do modo de usuário. O buffer de entrada pode conter valores de parâmetro que são interpretados de forma diferente, dependendo se o originador da solicitação é um aplicativo de modo de usuário ou um driver de modo kernel. No IRP que IoBuildDeviceIoControlRequest retorna, o campo RequestorMode é sempre definido como KernelMode. Esse valor indica que a solicitação e todas as informações contidas na solicitação são de um componente confiável do modo kernel.

Se o chamador não puder validar os valores de parâmetro que copia de um buffer do modo de usuário para o buffer de entrada ou se esses valores não precisarem ser interpretados como provenientes de um componente do modo kernel, o chamador deverá definir o campo RequestorMode no IRP como UserMode. Essa configuração informa ao driver que manipula a solicitação de controle de E/S que o buffer contém dados não confiáveis do modo de usuário.

O método real pelo qual o conteúdo dos parâmetros InputBuffer e OutputBuffer são armazenados no IRP depende do valor TransferType para o IOCTL. Para obter mais informações sobre esse valor, consulte Descrições de buffer para códigos de controle de E/S.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 2000.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
Regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoBuildDeviceControlNoFree(wdm), IoBuildDeviceControlWait(wdm), IoBuildDeviceControlWaitTimeout(wdm), IoBuildDeviceIoControlSetEvent(wdm), IrqlIoPassive1(wdm), PowerIrpDDis(wdm), SignalEventInCompletion(wdm)