OVERLAPPED-Struktur (minwinbase.h)

Artikel
08/24/2023

Enthält Informationen, die in asynchronen (oder überlappenden) Eingaben und Ausgaben (E/A) verwendet werden.

Syntax

typedef struct _OVERLAPPED {
  ULONG_PTR Internal;
  ULONG_PTR InternalHigh;
  union {
    struct {
      DWORD Offset;
      DWORD OffsetHigh;
    } DUMMYSTRUCTNAME;
    PVOID Pointer;
  } DUMMYUNIONNAME;
  HANDLE    hEvent;
} OVERLAPPED, *LPOVERLAPPED;

Member

Internal

Der status Code für die E/A-Anforderung. Wenn die Anforderung ausgestellt wird, legt das System diesen Member auf STATUS_PENDING fest, um anzugeben, dass der Vorgang noch nicht gestartet wurde. Wenn die Anforderung abgeschlossen ist, legt das System diesen Member auf den status Code für die abgeschlossene Anforderung fest.

Das interne Element war ursprünglich für die Systemverwendung reserviert, und sein Verhalten kann sich ändern.

InternalHigh

Die Anzahl der für die E/A-Anforderung übertragenen Bytes. Das System legt diesen Member fest, wenn die Anforderung ohne Fehler abgeschlossen wird.

Der InternalHigh-Member war ursprünglich für die Systemverwendung reserviert, und sein Verhalten kann sich ändern.

DUMMYUNIONNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Offset

Der niedriggeordnete Teil der Dateiposition, an der die E/A-Anforderung gestartet werden soll, wie vom Benutzer angegeben.

Dieser Member ist nur nonzero, wenn E/A-Anforderungen auf einem suchenden Gerät ausgeführt werden, das das Konzept eines Offsets (auch als Dateizeigermechanismus bezeichnet) unterstützt, z. B. eine Datei. Andernfalls muss dieses Element 0 sein.

Weitere Informationen finden Sie unter Hinweise.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.OffsetHigh

Der hochgeordnete Teil der Dateiposition, an der die E/A-Anforderung gestartet werden soll, wie vom Benutzer angegeben.

Weitere Informationen finden Sie unter Hinweise.

DUMMYUNIONNAME.Pointer

Für die Systemnutzung reserviert; verwenden Sie nach der Initialisierung nicht auf null.

hEvent

Ein Handle für das Ereignis, das vom System auf einen signalierten Zustand festgelegt wird, wenn der Vorgang abgeschlossen ist. Der Benutzer muss diesen Member entweder auf Null oder ein gültiges Ereignishandle mithilfe der CreateEvent-Funktion initialisieren, bevor diese Struktur an überlappende Funktionen übergeben wird. Dieses Ereignis kann dann verwendet werden, um gleichzeitigE E/A-Anforderungen für ein Gerät zu synchronisieren. Weitere Informationen finden Sie unter Hinweise.

Funktionen wie ReadFile und WriteFile legen dieses Handle auf den nicht signalierten Zustand fest, bevor sie mit einem E/A-Vorgang beginnen. Wenn der Vorgang abgeschlossen ist, wird der Handle auf den Signalzustand festgelegt.

Funktionen wie GetOverlappedResult und die Synchronisierungswartefunktionen setzen Automatische Zurücksetzungsereignisse in den nicht signalierten Zustand zurück. Daher sollten Sie ein manuelles Zurücksetzungsereignis verwenden. wenn Sie ein Ereignis zum automatischen Zurücksetzen verwenden, kann Ihre Anwendung nicht mehr reagieren, wenn Sie warten, bis der Vorgang abgeschlossen ist, und dann GetOverlappedResult aufrufen, wobei der bWait-Parameter auf TRUE festgelegt ist.

Hinweise

Alle nicht verwendeten Member dieser Struktur sollten immer auf null initialisiert werden, bevor die Struktur in einem Funktionsaufruf verwendet wird. Andernfalls schlägt die Funktion möglicherweise fehl und gibt ERROR_INVALID_PARAMETER zurück.

Die Elemente Offset und OffsetHigh stellen zusammen eine 64-Bit-Dateiposition dar. Es ist ein Byteoffset vom Anfang der Datei oder des dateiähnlichen Geräts und wird vom Benutzer angegeben. diese Werte werden vom System nicht geändert. Der aufrufende Prozess muss diesen Member festlegen, bevor die OVERLAPPED-Struktur an Funktionen übergeben wird, die einen Offset verwenden, z. B. die Funktionen ReadFile oder WriteFile (und verwandte Funktionen).

Sie können das Makro HasOverlappedIoCompleted verwenden, um zu überprüfen, ob ein asynchroner E/A-Vorgang abgeschlossen wurde, wenn GetOverlappedResult für Ihre Anwendung zu umständlich ist.

Sie können die CancelIo-Funktion verwenden, um einen asynchronen E/A-Vorgang abzubrechen.

Ein häufiger Fehler besteht darin, eine OVERLAPPED-Struktur wiederzuverwenden, bevor der vorherige asynchrone Vorgang abgeschlossen wurde. Sie sollten für jede Anforderung eine separate Struktur verwenden. Sie sollten auch ein Ereignisobjekt für jeden Thread erstellen, der Daten verarbeitet. Wenn Sie die Ereignishandles in einem Array speichern, können Sie mit der WaitForMultipleObjects-Funktion problemlos warten, bis alle Ereignisse signalisiert werden.

Weitere Informationen und potenzielle Fallstricke der asynchronen E/A-Verwendung finden Sie unter CreateFile, ReadFile, WriteFile und zugehörige Funktionen.

Eine allgemeine Übersicht über die Synchronisierung und konzeptionelle Informationen zu überlappender Verwendung finden Sie unter Synchronisierung und überlappende Eingabe und Ausgabe und verwandte Themen.

Eine Datei-E/A-orientierte Übersicht über synchrone und asynchrone E/A finden Sie unter Synchrone und asynchrone E/A.

Beispiele

Ein Beispiel finden Sie unter Named Pipe Server Using Overlapped E/O.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Kopfzeile	minwinbase.h (einschließlich Windows.h unter Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)