IRP-Struktur (wdm.h)

  • Artikel

Die IRP-Struktur ist eine teilweise undurchsichtige Struktur, die ein E/A-Anforderungspaket darstellt. Nicht dokumentierte Member der IRP-Struktur werden reserviert und nur vom E/A-Manager oder in einigen Fällen von Dateisystemtreibern (FSDs) verwendet.

Syntax

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;

Member

Type

Reserviert für die interne Systemverwendung.

Size

Reserviert für die interne Systemverwendung.

MdlAddress

Zeiger auf eine MDL, die einen Benutzerpuffer beschreibt, wenn der Treiber direkte E/A verwendet und der IRP-Hauptfunktionscode einer der folgenden Ist:

  • IRP_MJ_READ

    Die MDL beschreibt einen leeren Puffer, den das Gerät oder der Treiber ausfüllt.

  • IRP_MJ_WRITE

    Die MDL beschreibt einen Puffer, der Daten für das Gerät oder den Treiber enthält.

  • IRP_MJ_DEVICE_CONTROL oder IRP_MJ_INTERNAL_DEVICE_CONTROL

    Wenn der IOCTL-Code den METHOD_IN_DIRECT Übertragungstyp angibt, beschreibt die MDL einen Puffer, der Daten für das Gerät oder den Treiber enthält.

Wenn der IOCTL-Code den METHOD_OUT_DIRECT Übertragungstyp angibt, beschreibt die MDL einen leeren Puffer, den das Gerät oder treiber ausfüllt.

Weitere Informationen zu den Puffern, die METHOD_IN_DIRECT und METHOD_OUT_DIRECT Übertragungstypen in IOCTL-Codes zugeordnet sind, finden Sie unter Pufferbeschreibungen für E/A-Steuercodes.

Wenn der Treiber keine direkte E/A verwendet, ist dieser Zeiger NULL.

Flags

Dateisystemtreiber verwenden dieses Feld, das für alle Treiber schreibgeschützt ist. Netzwerktreiber und möglicherweise Gerätetreiber der höchsten Ebene können dieses Feld ebenfalls lesen. Dieses Feld wird entweder auf null oder auf das bitweise OR eines oder mehrerer der folgenden systemdefinierten Flagbits festgelegt:

  • 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

Reserviert für die interne Systemverwendung.

AssociatedIrp.MasterIrp

Zeiger auf den master IRP in einem IRP, der durch den Aufruf eines Treibers der obersten Ebene an IoMakeAssociatedIrp erstellt wurde.

AssociatedIrp.IrpCount

Reserviert für die interne Systemverwendung.

AssociatedIrp.SystemBuffer

Zeiger auf einen Systemspeicherpuffer.

Wenn der Treiber gepufferte E/A verwendet, wird der Zweck des Puffers durch den IRP-Hauptfunktionscode wie folgt bestimmt:

  • SystemBuffer.IRP_MJ_READ

    Der Puffer empfängt Daten vom Gerät oder Treiber. Die Länge des Puffers wird durch Parameters.Read.Length in der IO_STACK_LOCATION-Struktur des Treibers angegeben.

  • SystemBuffer.IRP_MJ_WRITE

    Der Puffer stellt Daten für das Gerät oder den Treiber bereit. Die Länge des Puffers wird durch Parameters.Write.Length in der IO_STACK_LOCATION-Struktur des Treibers angegeben.

  • SystemBuffer.IRP_MJ_DEVICE_CONTROL oder IRP_MJ_INTERNAL_DEVICE_CONTROL

    Der Puffer stellt sowohl die Eingabe- als auch den Ausgabepuffer dar, die für DeviceIoControl und IoBuildDeviceIoControlRequest bereitgestellt werden. Ausgabedaten überschreiben Eingabedaten.

Für die Eingabe wird die Länge des Puffers durch Parameters.DeviceIoControl.InputBufferLength in der IO_STACK_LOCATION-Struktur des Treibers angegeben.

Für die Ausgabe wird die Länge des Puffers durch Parameters.DeviceIoControl.OutputBufferLength in der IO_STACK_LOCATION-Struktur des Treibers angegeben.

Weitere Informationen finden Sie unter Pufferbeschreibungen für E/A-Steuerungscodes.

Der Puffer stellt den Eingabepuffer dar, der für DeviceIoControl und IoBuildDeviceIoControlRequest bereitgestellt wird.

Die Länge des Puffers wird von Parameters.DeviceIoControl.InputBufferLength in der IO_STACK_LOCATION-Struktur des Treibers angegeben.

Weitere Informationen finden Sie unter Pufferbeschreibungen für E/A-Steuerungscodes.

Wenn der Treiber direkte E/A verwendet, wird der Zweck des Puffers durch den IRP-Hauptfunktionscode wie folgt bestimmt:

ThreadListEntry

Reserviert für die interne Systemverwendung.

IoStatus

Enthält die IO_STATUS_BLOCK-Struktur, in der ein Treiber status und Informationen vor dem Aufruf von IoCompleteRequest speichert.

RequestorMode

Gibt den Ausführungsmodus des ursprünglichen Anforderers des Vorgangs an, einen von UserMode oder KernelMode.

PendingReturned

Wenn dieser Wert auf TRUE festgelegt ist, hat ein Treiber das IRP als ausstehend markiert. Jede IoCompletion-Routine sollte den Wert dieses Flags überprüfen. Wenn das Flag TRUE ist und die IoCompletion-Routine nicht STATUS_MORE_PROCESSING_REQUIRED zurückgibt, sollte die Routine IoMarkIrpPending aufrufen, um die ausstehende status an Treiber darüber im Gerätestapel zu verteilen.

StackCount

Reserviert für die interne Systemverwendung.

CurrentLocation

Reserviert für die interne Systemverwendung.

Cancel

Wenn dieser Wert auf TRUE festgelegt ist, ist der IRP entweder oder sollte abgebrochen werden.

CancelIrql

Enthält die IRQL, an der ein Treiber ausgeführt wird, wenn IoAcquireCancelSpinLock aufgerufen wird.

ApcEnvironment

Reserviert für die interne Systemverwendung.

AllocationFlags

Reserviert für die interne Systemverwendung.

UserIosb

Reserviert für die interne Systemverwendung.

IoRingContext

Reserviert für die interne Systemverwendung.

UserEvent

Reserviert für die interne Systemverwendung.

Overlay

Reserviert für die interne Systemverwendung.

Overlay.AsynchronousParameters

Reserviert für die interne Systemverwendung.

Overlay.AsynchronousParameters.UserApcRoutine

Reserviert für die interne Systemverwendung.

Overlay.AsynchronousParameters.IssuingProcess

Reserviert für die interne Systemverwendung.

Overlay.AsynchronousParameters.UserApcContext

Reserviert für die interne Systemverwendung.

Overlay.AsynchronousParameters.IoRing

Reserviert für die interne Systemverwendung.

Overlay.AllocationSize

Reserviert für die interne Systemverwendung.

CancelRoutine

Enthält den Einstiegspunkt für eine vom Treiber bereitgestellte Cancel-Routine , die aufgerufen werden soll, wenn das IRP abgebrochen wird. NULL gibt an, dass der IRP derzeit nicht abgebrochen werden kann.

UserBuffer

Enthält die Adresse eines Ausgabepuffers, wenn beide der folgenden Bedingungen zutreffen:

Für METHOD_BUFFERED sollte der Treiber den Puffer verwenden, auf den Irp-AssociatedIrp.SystemBuffer> als Ausgabepuffer verweist. Wenn der Treiber die Anforderung abgeschlossen hat, kopiert der E/A-Manager den Inhalt dieses Puffers in den Ausgabepuffer, auf den Irp-UserBuffer> verweist. Der Treiber sollte nicht direkt in den Puffer schreiben, auf den Irp-UserBuffer> verweist. Weitere Informationen finden Sie unter Pufferbeschreibungen für E/A-Steuerungscodes.

Tail

Reserviert für die interne Systemverwendung.

Tail.Overlay

Reserviert für die interne Systemverwendung.

Tail.Overlay.DeviceQueueEntry

Wenn IRPs in der Gerätewarteschlange, die dem Geräteobjekt des Treibers zugeordnet ist, in die Warteschlange eingereiht werden, verknüpft dieses Feld IRPs in der Gerätewarteschlange. Diese Links können nur verwendet werden, während der Treiber die IRP verarbeitet.

Tail.Overlay.DriverContext[4]

Wenn IRPs nicht in der Gerätewarteschlange, die dem Geräteobjekt des Treibers zugeordnet ist, in die Warteschlange eingereiht werden, kann dieses Feld vom Treiber verwendet werden, um bis zu vier Zeiger zu speichern. Dieses Feld kann nur verwendet werden, während der Treiber die IRP besitzt.

Tail.Overlay.Thread

Ein Zeiger auf den Threadsteuerungsblock (THREAD Control Block, TCB) des Aufrufers. Bei Anforderungen, die aus dem Benutzermodus stammen, legt der E/A-Manager dieses Feld immer so fest, dass es auf den TCB des Threads verweist, der die Anforderung ausgestellt hat.

Tail.Overlay.AuxiliaryBuffer

Reserviert für die interne Systemverwendung.

Tail.Overlay.ListEntry

Wenn ein Treiber seine eigenen internen Warteschlangen von IRPs verwaltet, verwendet er dieses Feld, um eine IRP mit der nächsten zu verknüpfen. Diese Links können nur verwendet werden, wenn der Treiber das IRP in seiner Warteschlange hält oder die IRP verarbeitet.

Tail.Overlay.CurrentStackLocation

Reserviert für die interne Systemverwendung.

Tail.Overlay.PacketType

Reserviert für die interne Systemverwendung.

Tail.Overlay.OriginalFileObject

Reserviert für die interne Systemverwendung.

Tail.Apc

Reserviert für die interne Systemverwendung.

Tail.CompletionKey

Reserviert für die interne Systemverwendung.

Hinweise

Nicht dokumentierte Elemente der IRP-Struktur werden reserviert, die nur vom E/A-Manager oder in einigen Fällen von Dateisystemtreibern (FSDs) verwendet werden.

Ein IRP ist die grundlegende E/A-Manager-Struktur, die für die Kommunikation mit Treibern und die Kommunikation zwischen Treibern verwendet wird. Ein Paket besteht aus zwei verschiedenen Teilen:

  • Header oder fester Teil des Pakets: Dies wird vom E/A-Manager verwendet, um Informationen zur ursprünglichen Anforderung zu speichern, z. B. die geräteunabhängigen Parameter des Aufrufers, die Adresse des Geräteobjekts, auf dem eine Datei geöffnet ist usw. Es wird auch von Treibern verwendet, um Informationen wie die endgültige status der Anforderung zu speichern.

  • E/A-Stapelspeicherorte – Nach dem Header ist eine Reihe von E/A-Stapelspeicherorten enthalten, einer pro Treiber in der Kette von mehrschichtigen Treibern, für die die Anforderung gebunden ist. Jeder Stapelspeicherort enthält die Parameter, Funktionscodes und den Kontext, die vom entsprechenden Treiber verwendet werden, um zu bestimmen, was er tun soll. Weitere Informationen finden Sie in der IO_STACK_LOCATION-Struktur .

Während ein Treiber auf höherer Ebene möglicherweise den Wert von Boolean abbrechen in einem IRP überprüft, kann dieser Treiber nicht davon ausgehen, dass der IRP mit STATUS_CANCELLED von einem Treiber auf niedrigerer Ebene abgeschlossen wird, auch wenn der Wert TRUE ist.

Anforderungen

Anforderung Wert
Header wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)

Weitere Informationen