GetOverlappedResultEx, fonction (ioapiset.h)

Article
02/29/2024

Récupère les résultats d’une opération qui se chevauche sur le fichier, le canal nommé ou le périphérique de communication spécifié dans l’intervalle de délai d’attente spécifié. Le thread appelant peut effectuer une attente pouvant être alertable.

Syntaxe

BOOL GetOverlappedResultEx(
  [in]  HANDLE       hFile,
  [in]  LPOVERLAPPED lpOverlapped,
  [out] LPDWORD      lpNumberOfBytesTransferred,
  [in]  DWORD        dwMilliseconds,
  [in]  BOOL         bAlertable
);

Paramètres

[in] hFile

Handle du fichier, du canal nommé ou de l’appareil de communication. Il s’agit du même handle que celui qui a été spécifié lors du démarrage de l’opération chevauchée par un appel à la fonction ReadFile, WriteFile, ConnectNamedPipe, TransactNamedPipe, DeviceIoControl ou WaitCommEvent .

[in] lpOverlapped

Pointeur vers une structure OVERLAPPED qui a été spécifiée lors du démarrage de l’opération superposée.

[out] lpNumberOfBytesTransferred

Pointeur vers une variable qui reçoit le nombre d’octets réellement transférés par une opération de lecture ou d’écriture. Pour une opération TransactNamedPipe , il s’agit du nombre d’octets qui ont été lus à partir du canal. Pour une opération DeviceIoControl , il s’agit du nombre d’octets de données de sortie retournées par le pilote de périphérique. Pour une opération ConnectNamedPipe ou WaitCommEvent , cette valeur n’est pas définie.

[in] dwMilliseconds

Intervalle de délai d’attente, en millisecondes.

Si dwMilliseconds est égal à zéro et que l’opération est toujours en cours, la fonction retourne immédiatement et la fonction GetLastError retourne ERROR_IO_INCOMPLETE.

Si dwMilliseconds est différent de zéro et que l’opération est toujours en cours, la fonction attend que l’objet soit signalé, qu’une routine d’achèvement d’E/S ou un APC soit mis en file d’attente, ou que l’intervalle s’écoule avant le retour. Utilisez GetLastError pour obtenir des informations d’erreur étendues.

Si dwMilliseconds a la valeur INFINITE, la fonction retourne uniquement lorsque l’objet est signalé ou lorsqu’une routine d’achèvement d’E/S ou qu’APC est mis en file d’attente.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 et Windows Server 2008 R2 : La valeur dwMilliseconds inclut le temps passé dans les états de faible consommation d’énergie. Par exemple, le délai d’attente continue de compter à la baisse pendant que l’ordinateur est en veille.

Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 et Windows Server 2016 : la valeur dwMilliseconds n’inclut pas le temps passé dans les états de faible consommation d’énergie. Par exemple, le délai d’expiration ne continue pas de compter à la baisse pendant que l’ordinateur est en veille.

[in] bAlertable

Si ce paramètre a la valeur TRUE et que le thread appelant est dans l’état d’attente, la fonction retourne lorsque le système met en file d’attente une routine d’achèvement d’E/S ou UN APC. Le thread appelant exécute ensuite la routine ou la fonction. Sinon, la fonction ne retourne pas et la routine d’achèvement ou la fonction APC n’est pas exécutée.

Une routine d’achèvement est mise en file d’attente lorsque la fonction ReadFileEx ou WriteFileEx dans laquelle elle a été spécifiée s’est terminée. La fonction retourne et la routine d’achèvement est appelée uniquement si bAlertable a la valeur TRUE et si le thread appelant est le thread qui a lancé l’opération de lecture ou d’écriture. Un APC est mis en file d’attente quand vous appelez QueueUserAPC.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError. Les codes d’erreur courants sont les suivants :

Si dwMilliseconds est égal à zéro et que l’opération est toujours en cours, GetLastError retourne ERROR_IO_INCOMPLETE.
Si dwMilliseconds est différent de zéro et qu’une routine d’achèvement d’E/S ou un APC est mis en file d’attente, GetLastError retourne WAIT_IO_COMPLETION.
Si dwMilliseconds est différent de zéro et que l’intervalle de délai d’expiration spécifié s’écoule, GetLastError retourne WAIT_TIMEOUT.

Remarques

La fonction GetOverlappedResultEx diffère de GetOverlappedResult des manières suivantes : le paramètre dwMilliseconds peut spécifier un intervalle de délai d’attente pour l’opération, et le paramètre bAlertable peut spécifier que le thread appelant doit effectuer une attente pouvant être alertée.

Les résultats signalés par la fonction GetOverlappedResultEx sont ceux de la dernière opération superposée du handle spécifié à laquelle la structure OVERLAPPED spécifiée a été fournie et pour laquelle les résultats de l’opération étaient en attente. Une opération en attente est indiquée lorsque la fonction qui a démarré l’opération retourne FALSE et que la fonction GetLastError retourne ERROR_IO_PENDING. Lorsqu’une opération d’E/S est en attente, la fonction qui a démarré l’opération réinitialise le membre hEvent de la structure OVERLAPPED à l’état non signé. Ensuite, une fois l’opération en attente terminée, le système définit l’objet d’événement à l’état signalé.

Spécifiez un objet d’événement de réinitialisation manuelle dans la structure OVERLAPPED . Si un objet d’événement de réinitialisation automatique est utilisé, le handle d’événement ne doit pas être spécifié dans une autre opération d’attente dans l’intervalle entre le démarrage de l’opération qui se chevauche et l’appel à GetOverlappedResultEx. Par exemple, l’objet événement est parfois spécifié dans l’une des fonctions d’attente pour attendre la fin de l’opération. Lorsque la fonction wait retourne, le système définit l’état d’un événement de réinitialisation automatique sur non signé, et un appel ultérieur à GetOverlappedResultEx avec le paramètre dwMilliseconds défini sur INFINITE entraîne le blocage indéfini de la fonction.

Si le membre hEvent de la structure OVERLAPPED est NULL, le système utilise l’état du handle hFile pour signaler quand l’opération est terminée. L’utilisation de fichiers, de canaux nommés ou de handles de périphérique de communication à cet effet est déconseillée. Il est plus sûr d’utiliser un objet d’événement en raison de la confusion qui peut se produire lorsque plusieurs opérations simultanées se chevauchent sur le même fichier, le même canal nommé ou le même appareil de communication. Dans ce cas, il n’existe aucun moyen de savoir quelle opération a provoqué le signal de l’état de l’objet.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8 [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2012 [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	ioapiset.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll