Structure CHEVAUCHEMENT (minwinbase.h)

Article
02/29/2024

Contient des informations utilisées dans les entrées et sorties asynchrones (ou qui se chevauchent).

Syntaxe

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

Membres

Internal

Code status pour la demande d’E/S. Lorsque la demande est émise, le système définit ce membre sur STATUS_PENDING pour indiquer que l’opération n’a pas encore démarré. Une fois la demande terminée, le système définit ce membre sur le code status de la demande terminée.

Le membre Interne était initialement réservé à l’utilisation du système et son comportement peut changer.

InternalHigh

Nombre d’octets transférés pour la demande d’E/S. Le système définit ce membre si la demande est effectuée sans erreurs.

Le membre InternalHigh était initialement réservé à l’utilisation du système et son comportement peut changer.

DUMMYUNIONNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Offset

Partie d’ordre inférieur de la position du fichier à laquelle démarrer la demande d’E/S, comme spécifié par l’utilisateur.

Ce membre est différent de zéro uniquement lors de l’exécution de demandes d’E/S sur un appareil de recherche qui prend en charge le concept de décalage (également appelé mécanisme de pointeur de fichier), tel qu’un fichier. Sinon, ce membre doit être égal à zéro.

Pour plus d’informations, consultez Remarques.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.OffsetHigh

Partie d’ordre élevé de la position du fichier à laquelle démarrer la demande d’E/S, comme spécifié par l’utilisateur.

Pour plus d’informations, consultez Remarques.

DUMMYUNIONNAME.Pointer

Réservé à l’utilisation du système ; n’utilisez pas à zéro après l’initialisation.

hEvent

Handle de l’événement qui sera défini sur un état signalé par le système une fois l’opération terminée. L’utilisateur doit initialiser ce membre à zéro ou à un handle d’événement valide à l’aide de la fonction CreateEvent avant de passer cette structure à toutes les fonctions qui se chevauchent. Cet événement peut ensuite être utilisé pour synchroniser des demandes d’E/S simultanées pour un appareil. Pour plus d’informations, consultez Remarques.

Les fonctions telles que ReadFile et WriteFile définissent ce handle à l’état non signé avant de commencer une opération d’E/S. Une fois l’opération terminée, le handle est défini sur l’état signalé.

Les fonctions telles que GetOverlappedResult et les fonctions d’attente de synchronisation réinitialisent les événements de réinitialisation automatique à l’état non signé. Par conséquent, vous devez utiliser un événement de réinitialisation manuelle ; si vous utilisez un événement de réinitialisation automatique, votre application peut cesser de répondre si vous attendez que l’opération se termine, puis appelez GetOverlappedResult avec le paramètre bWait défini sur TRUE.

Remarques

Tous les membres inutilisés de cette structure doivent toujours être initialisés à zéro avant que la structure ne soit utilisée dans un appel de fonction. Sinon, la fonction peut échouer et retourner ERROR_INVALID_PARAMETER.

Les membres Offset et OffsetHigh représentent ensemble une position de fichier 64 bits. Il s’agit d’un décalage d’octets par rapport au début du fichier ou de l’appareil de type fichier, et il est spécifié par l’utilisateur ; le système ne modifie pas ces valeurs. Le processus appelant doit définir ce membre avant de passer la structure CHEVAUCHEMENT AUX fonctions qui utilisent un décalage, telles que les fonctions ReadFile ou WriteFile (et les fonctions associées).

Vous pouvez utiliser la macro HasOverlappedIoCompleted pour case activée si une opération d’E/S asynchrone s’est terminée si GetOverlappedResult est trop fastidieux pour votre application.

Vous pouvez utiliser la fonction CancelIo pour annuler une opération d’E/S asynchrone.

Une erreur courante consiste à réutiliser une structure CHEVAUCHEMENT AVANT la fin de l’opération asynchrone précédente. Vous devez utiliser une structure distincte pour chaque requête. Vous devez également créer un objet d’événement pour chaque thread qui traite les données. Si vous stockez les descripteurs d’événements dans un tableau, vous pouvez facilement attendre que tous les événements soient signalés à l’aide de la fonction WaitForMultipleObjects .

Pour plus d’informations et pour connaître les pièges potentiels liés à l’utilisation asynchrone des E/S, consultez CreateFile, ReadFile, WriteFile et les fonctions associées.

Pour obtenir une vue d’ensemble générale de la synchronisation et des informations conceptuelles sur l’utilisation chevauchement, consultez Synchronisation et entrée et sortie superposées et rubriques associées.

Pour obtenir une vue d’ensemble des E/S synchrones et asynchrones orientées fichier, consultez E/S synchrones et asynchrones.

Exemples

Pour obtenir un exemple, consultez Serveur de canal nommé utilisant des E/S superposées.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
En-tête	minwinbase.h (inclure Windows.h sur Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)