Struttura OVERLAPPED (minwinbase.h)

Articolo
02/29/2024

Contiene informazioni utilizzate nell'input e nell'output asincroni (o sovrapposti).

Sintassi

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

Members

Internal

Codice di stato per la richiesta di I/O. Quando viene eseguita la richiesta, il sistema imposta questo membro su STATUS_PENDING per indicare che l'operazione non è ancora stata avviata. Al termine della richiesta, il sistema imposta questo membro sul codice di stato per la richiesta completata.

Il membro interno è stato originariamente riservato per l'uso del sistema e il relativo comportamento può cambiare.

InternalHigh

Numero di byte trasferiti per la richiesta di I/O. Il sistema imposta questo membro se la richiesta viene completata senza errori.

Il membro InternalHigh è stato originariamente riservato per l'uso del sistema e il relativo comportamento può cambiare.

DUMMYUNIONNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Offset

Parte in ordine basso della posizione del file in corrispondenza della quale avviare la richiesta di I/O, come specificato dall'utente.

Questo membro è diverso da zero solo quando si eseguono richieste di I/O in un dispositivo di ricerca che supporta il concetto di offset (detto anche meccanismo di puntatore di file), ad esempio un file. In caso contrario, questo membro deve essere zero.

Per altre informazioni, vedere Osservazioni.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.OffsetHigh

Parte di ordine elevato della posizione del file in corrispondenza della quale avviare la richiesta di I/O, come specificato dall'utente.

Per altre informazioni, vedere Osservazioni.

DUMMYUNIONNAME.Pointer

Riservato per l'uso del sistema; non usare dopo l'inizializzazione su zero.

hEvent

Handle per l'evento che verrà impostato su uno stato segnalato dal sistema al termine dell'operazione. L'utente deve inizializzare questo membro su zero o un handle di evento valido usando la funzione CreateEvent prima di passare questa struttura a qualsiasi funzione sovrapposta. Questo evento può quindi essere usato per sincronizzare le richieste di I/O simultanee per un dispositivo. Per altre informazioni, vedere Osservazioni.

Funzioni come ReadFile e WriteFile impostano questo handle sullo stato non firmato prima di iniziare un'operazione di I/O. Al termine dell'operazione, l'handle viene impostato sullo stato segnalato.

Funzioni come GetOverlappedResult e le funzioni di attesa della sincronizzazione reimpostano gli eventi di reimpostazione automatica allo stato non assegnato. Pertanto, è consigliabile usare un evento di reimpostazione manuale; se si usa un evento di reimpostazione automatica, l'applicazione può smettere di rispondere se si attende il completamento dell'operazione e quindi chiamare GetOverlappedResult con il parametro bWait impostato su TRUE.

Commenti

Tutti i membri inutilizzati di questa struttura devono essere sempre inizializzati su zero prima che la struttura venga usata in una chiamata di funzione. In caso contrario, la funzione potrebbe non riuscire e restituire ERROR_INVALID_PARAMETER.

I membri Offset e OffsetHigh insieme rappresentano una posizione di file a 64 bit. Si tratta di un offset di byte dall'inizio del file o del dispositivo simile a un file e viene specificato dall'utente; il sistema non modificherà questi valori. Il processo chiamante deve impostare questo membro prima di passare la struttura OVERLAPPED alle funzioni che usano un offset, ad esempio le funzioni ReadFile o WriteFile (e correlate).

È possibile utilizzare la macro HasOverlappedIoCompleted per verificare se un'operazione di I/O asincrona è stata completata se GetOverlappedResult è troppo complessa per l'applicazione.

È possibile usare la funzione CancelIo per annullare un'operazione di I/O asincrona.

Un errore comune consiste nel riutilizzare una struttura OVERLAPPED prima del completamento dell'operazione asincrona precedente. È consigliabile usare una struttura separata per ogni richiesta. È anche necessario creare un oggetto evento per ogni thread che elabora i dati. Se si archivia gli handle di evento in una matrice, è possibile attendere facilmente che tutti gli eventi vengano segnalati usando la funzione WaitForMultipleObjects .

Per altre informazioni e potenziali problemi di utilizzo di I/O asincroni, vedere CreateFile, ReadFile, WriteFile e funzioni correlate.

Per una panoramica generale della sincronizzazione e informazioni sull'utilizzo di OVERLAPPED concettuali, vedere Gli argomenti relativi alla sincronizzazione e all'input e all'output sovrapposti .

Per una panoramica orientata all'I/O dei file di I/O sincrona e asincrona, vedere I/O sincrono e asincrono.

Esempio

Per un esempio, vedere Named Pipe Server using Overlapped I/O .For an example, see Named Pipe Server Using Overlapped I/O.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Intestazione	minwinbase.h (include Windows.h in Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)