Estrutura IRP (wdm.h)

A estrutura IRP é uma estrutura parcialmente opaca que representa um pacote de solicitação de E/S. Os drivers podem usar os seguintes membros da estrutura IRP.

Sintaxe

typedef struct _IRP {
  CSHORT                    Type;
  USHORT                    Size;
  PMDL                      MdlAddress;
  ULONG                     Flags;
  union {
    struct _IRP     *MasterIrp;
    __volatile LONG IrpCount;
    PVOID           SystemBuffer;
  } AssociatedIrp;
  LIST_ENTRY                ThreadListEntry;
  IO_STATUS_BLOCK           IoStatus;
  KPROCESSOR_MODE           RequestorMode;
  BOOLEAN                   PendingReturned;
  CHAR                      StackCount;
  CHAR                      CurrentLocation;
  BOOLEAN                   Cancel;
  KIRQL                     CancelIrql;
  CCHAR                     ApcEnvironment;
  UCHAR                     AllocationFlags;
  union {
    PIO_STATUS_BLOCK UserIosb;
    PVOID            IoRingContext;
  };
  PKEVENT                   UserEvent;
  union {
    struct {
      union {
        PIO_APC_ROUTINE UserApcRoutine;
        PVOID           IssuingProcess;
      };
      union {
        PVOID                 UserApcContext;
#if ...
        _IORING_OBJECT        *IoRing;
#else
        struct _IORING_OBJECT *IoRing;
#endif
      };
    } AsynchronousParameters;
    LARGE_INTEGER AllocationSize;
  } Overlay;
  __volatile PDRIVER_CANCEL CancelRoutine;
  PVOID                     UserBuffer;
  union {
    struct {
      union {
        KDEVICE_QUEUE_ENTRY DeviceQueueEntry;
        struct {
          PVOID DriverContext[4];
        };
      };
      PETHREAD     Thread;
      PCHAR        AuxiliaryBuffer;
      struct {
        LIST_ENTRY ListEntry;
        union {
          struct _IO_STACK_LOCATION *CurrentStackLocation;
          ULONG                     PacketType;
        };
      };
      PFILE_OBJECT OriginalFileObject;
    } Overlay;
    KAPC  Apc;
    PVOID CompletionKey;
  } Tail;
} IRP;

Membros

Type

Size

MdlAddress

Ponteiro para um MDL que descreve um buffer de usuário, se o driver estiver usando E/S direta e o código de função principal IRP for um dos seguintes:

IRP_MJ_READ

O MDL descreve um buffer vazio que o dispositivo ou driver preenche.

IRP_MJ_WRITE

O MDL descreve um buffer que contém dados para o dispositivo ou driver.

IRP_MJ_DEVICE_CONTROL ou IRP_MJ_INTERNAL_DEVICE_CONTROL

Se o código IOCTL especificar o tipo de transferência METHOD_IN_DIRECT, o MDL descreverá um buffer que contém dados para o dispositivo ou driver.

Se o código IOCTL especificar o tipo de transferência METHOD_OUT_DIRECT, o MDL descreverá um buffer vazio que o dispositivo ou driver preenche.

Para obter mais informações sobre os buffers associados a tipos de transferência METHOD_IN_DIRECT e METHOD_OUT_DIRECT em códigos IOCTL, consulte Descrições de buffer para códigos de controle de E/S.

Se o driver não estiver usando E/S direta, esse ponteiro será NULL.

Flags

Os drivers do sistema de arquivos usam esse campo, que é somente leitura para todos os drivers. A rede e, possivelmente, os drivers de dispositivo de nível mais alto também podem ler esse campo. Esse campo é definido como zero ou para o bit a bit OR de um ou mais dos seguintes bits de sinalizador definidos pelo sistema:

IRP_NOCACHE

IRP_PAGING_IO

IRP_MOUNT_COMPLETION

IRP_SYNCHRONOUS_API

IRP_ASSOCIATED_IRP

IRP_BUFFERED_IO

IRP_DEALLOCATE_BUFFER

IRP_INPUT_OPERATION

IRP_SYNCHRONOUS_PAGING_IO

IRP_CREATE_OPERATION

IRP_READ_OPERATION

IRP_WRITE_OPERATION

IRP_CLOSE_OPERATION

IRP_DEFER_IO_COMPLETION

IRP_OB_QUERY_NAME

IRP_HOLD_DEVICE_QUEUE

IRP_UM_DRIVER_INITIATED_IO

AssociatedIrp

AssociatedIrp.MasterIrp

Ponteiro para o IRP mestre em um IRP que foi criado por uma chamada de driver de nível mais alto para IoMakeAssociatedIrp.

AssociatedIrp.IrpCount

AssociatedIrp.SystemBuffer

Ponteiro para um buffer de espaço do sistema.

Se o driver estiver usando E/S em buffer, a finalidade do buffer será determinada pelo código de função principal IRP, da seguinte maneira:

SystemBuffer.IRP_MJ_READ

O buffer recebe dados do dispositivo ou driver. O comprimento do buffer é especificado por Parameters.Read.Length na estrutura de IO_STACK_LOCATION do driver.

NULL.

SystemBuffer.IRP_MJ_WRITE

O buffer fornece dados para o dispositivo ou driver. O comprimento do buffer é especificado por Parameters.Write.Length na estrutura de IO_STACK_LOCATION do driver.

NULL.

SystemBuffer.IRP_MJ_DEVICE_CONTROL ou IRP_MJ_INTERNAL_DEVICE_CONTROL

O buffer representa os buffers de entrada e saída fornecidos para DeviceIoControl e IoBuildDeviceIoControlRequest. Os dados de saída substituem os dados de entrada.

Para entrada, o comprimento do buffer é especificado por Parameters.DeviceIoControl.InputBufferLength na estrutura IO_STACK_LOCATION do driver.

Para saída, o comprimento do buffer é especificado por Parameters.DeviceIoControl.OutputBufferLength na estrutura IO_STACK_LOCATION do driver.

Para obter mais informações, consulte Descrições de buffer para códigos de controle de E/S.

O buffer representa o buffer de entrada fornecido para DeviceIoControl e IoBuildDeviceIoControlRequest.

O comprimento do buffer é especificado por Parameters.DeviceIoControl.InputBufferLength na estrutura IO_STACK_LOCATION do driver.

Para obter mais informações, consulte Descrições de buffer para códigos de controle de E/S.

Se o driver estiver usando E/S direta, a finalidade do buffer será determinada pelo código de função principal IRP, da seguinte maneira:

ThreadListEntry

IoStatus

Contém a estrutura IO_STATUS_BLOCK na qual um driver armazena status e informações antes de chamar IoCompleteRequest.

RequestorMode

Indica o modo de execução do solicitante original da operação, um de UserMode ou KernelMode.

PendingReturned

Se definido como TRUE, um driver marcou o IRP pendente. Cada rotina IoCompletion deve verificar o valor desse sinalizador. Se o sinalizador for TRUE e se a rotina IoCompletion não retornar STATUS_MORE_PROCESSING_REQUIRED, a rotina deverá chamar IoMarkIrpPending para propagar o status pendente para drivers acima dele na pilha do dispositivo.

StackCount

CurrentLocation

Cancel

Se definido como TRUE, o IRP será ou deverá ser cancelado.

CancelIrql

Contém o IRQL no qual um driver está em execução quando IoAcquireCancelSpinLock é chamado.

ApcEnvironment

AllocationFlags

UserIosb

IoRingContext

UserEvent

Overlay

Overlay.AsynchronousParameters

Overlay.AsynchronousParameters.UserApcRoutine

Overlay.AsynchronousParameters.IssuingProcess

Overlay.AsynchronousParameters.UserApcContext

Overlay.AsynchronousParameters.IoRing

Overlay.AllocationSize

CancelRoutine

Contém o ponto de entrada para uma rotina de cancelamento fornecida pelo driver a ser chamada se o IRP for cancelado. NULL indica que o IRP não está cancelável no momento.

UserBuffer

Contém o endereço de um buffer de saída se ambas as seguintes condições se aplicarem:

Para METHOD_BUFFERED, o driver deve usar o buffer apontado por Irp->AssociatedIrp.SystemBuffer como o buffer de saída. Quando o driver conclui a solicitação, o gerenciador de E/S copia o conteúdo desse buffer para o buffer de saída apontado pelo UserBuffer >Irp. O driver não deve gravar diretamente no buffer apontado por Irp->UserBuffer. Para obter mais informações, consulte Descrições de buffer para códigos de controle de E/S.

Tail

Tail.Overlay

Tail.Overlay.DeviceQueueEntry

Se os IRPs estiverem na fila do dispositivo associados ao objeto de dispositivo do driver, esse campo vinculará IRPs na fila do dispositivo. Esses links só podem ser usados enquanto o driver está processando o IRP.

Tail.Overlay.DriverContext[4]

Se os IRPs não estiverem na fila do dispositivo associado ao objeto de dispositivo do driver, esse campo poderá ser usado pelo driver para armazenar até quatro ponteiros. Esse campo só pode ser usado enquanto o driver possui o IRP.

Tail.Overlay.Thread

Um ponteiro para o TCB (bloco de controle de thread) do chamador. Para solicitações originadas no modo de usuário, o gerenciador de E/S sempre define esse campo para apontar para o TCB do thread que emitiu a solicitação.

Tail.Overlay.AuxiliaryBuffer

Tail.Overlay.ListEntry

Se um driver gerencia suas próprias filas internas de IRPs, ele usa esse campo para vincular um IRP ao próximo. Esses links só podem ser usados enquanto o driver estiver segurando o IRP em sua fila ou estiver processando o IRP.

Tail.Overlay.CurrentStackLocation

Tail.Overlay.PacketType

Tail.Overlay.OriginalFileObject

Tail.Apc

Tail.CompletionKey

Comentários

Membros não documentados da estrutura IRP são reservados, usados apenas pelo gerente de E/S ou, em alguns casos, por FSDs.

Um IRP é a estrutura básica do gerenciador de E/S usada para se comunicar com drivers e permitir que os drivers se comuniquem entre si. Um pacote consiste em duas partes diferentes:

  • Cabeçalho ou parte fixa do pacote: isso é usado pelo gerente de E/S para armazenar informações sobre a solicitação original, como os parâmetros independentes do dispositivo do chamador, o endereço do objeto do dispositivo no qual um arquivo está aberto e assim por diante. Ele também é usado por drivers para armazenar informações como o status final da solicitação.
  • Locais de pilha de E/S: após o cabeçalho há um conjunto de locais de pilha de E/S, um por driver na cadeia de drivers em camadas para o qual a solicitação está associada. Cada local de pilha contém os parâmetros, os códigos de função e o contexto usados pelo driver correspondente para determinar o que ele deveria estar fazendo. Para obter mais informações, consulte a estrutura IO_STACK_LOCATION .
Embora um driver de nível superior possa verificar o valor do Cancel Boolean em um IRP, esse driver não pode assumir que o IRP será concluído com STATUS_CANCELLED por um driver de nível inferior, mesmo que o valor seja TRUE.

Requisitos

   
Cabeçalho wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)

Confira também

IO_STACK_LOCATION

IO_STATUS_BLOCK

IoCreateDevice

IoGetCurrentIrpStackLocation

IoGetNextIrpStackLocation

IoSetCancelRoutine

IoSetNextIrpStackLocation