GetQueuedCompletionStatus, fonction (ioapiset.h)

Article
05/20/2023

Tente de mettre en file d’attente un paquet d’achèvement d’E/S à partir du port d’achèvement d’E/S spécifié. Si aucun paquet d’achèvement n’est mis en file d’attente, la fonction attend qu’une opération d’E/S en attente associée au port d’achèvement se termine.

Pour mettre en file d’attente plusieurs paquets d’achèvement d’E/S à la fois, utilisez la fonction GetQueuedCompletionStatusEx .

Syntaxe

BOOL GetQueuedCompletionStatus(
  [in]  HANDLE       CompletionPort,
        LPDWORD      lpNumberOfBytesTransferred,
  [out] PULONG_PTR   lpCompletionKey,
  [out] LPOVERLAPPED *lpOverlapped,
  [in]  DWORD        dwMilliseconds
);

Paramètres

[in] CompletionPort

Handle vers le port d’achèvement. Pour créer un port d’achèvement, utilisez la fonction CreateIoCompletionPort .

lpNumberOfBytesTransferred

Pointeur vers une variable qui reçoit le nombre d’octets transférés dans une opération d’E/S terminée.

[out] lpCompletionKey

Pointeur vers une variable qui reçoit la valeur de clé d’achèvement associée au handle de fichier dont l’opération d’E/S est terminée. Une clé d’achèvement est une clé par fichier spécifiée dans un appel à CreateIoCompletionPort.

[out] lpOverlapped

Pointeur vers une variable qui reçoit l’adresse de la structure OVERLAPPED spécifiée lors du démarrage de l’opération d’E/S terminée.

Même si vous avez passé à la fonction un handle de fichier associé à un port d’achèvement et à une structure CHEVAUCHEMENT VALIDE , une application peut empêcher la notification de port d’achèvement. Pour ce faire, spécifiez un handle d’événement valide pour le membre hEvent de la structure OVERLAPPED et définissez son bit d’ordre inférieur. Un handle d’événement valide dont le bit d’ordre faible est défini empêche l’achèvement des E/S superposées de mettre en file d’attente un paquet d’achèvement vers le port d’achèvement.

[in] dwMilliseconds

Nombre de millisecondes pendant lesquelles l’appelant est prêt à attendre qu’un paquet d’achèvement apparaisse sur le port d’achèvement. Si un paquet d’achèvement n’apparaît pas dans le délai spécifié, la fonction expire, retourne FALSE et définit *lpOverlapped surNULL.

Si dwMilliseconds est INFINITE, la fonction n’expire jamais. Si dwMilliseconds est égal à zéro et qu’il n’y a aucune opération d’E/S à mettre en file d’attente, la fonction expire immédiatement.

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é en basse consommation États. Par exemple, le délai d’expiration ne continue pas de compter à la baisse pendant que l’ordinateur est en veille.

Valeur renvoyée

Retourne une valeur différente de zéro (TRUE) en cas de réussite ou de zéro (FALSE) dans le cas contraire.

Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Pour plus d'informations, consultez la section Notes.

Notes

Cette fonction associe un thread au port d’achèvement spécifié. Un thread peut être associé à au plus un port d’achèvement.

Si un appel à GetQueuedCompletionStatus échoue, car le handle de port d’achèvement qui lui est associé est fermé alors que l’appel est en attente, la fonction retourne FALSE, *lpOverlapped est NULL et GetLastError retourne ERROR_ABANDONED_WAIT_0.

Windows Server 2003 et Windows XP : La fermeture du handle de port d’achèvement pendant qu’un appel est en attente n’entraîne pas le comportement indiqué précédemment. La fonction continue d’attendre qu’une entrée soit supprimée du port ou qu’un délai d’attente se produise, s’il est spécifié en tant que valeur autre que INFINITE.

Si la fonction GetQueuedCompletionStatus réussit, elle a supprimé la file d’attente d’un paquet d’achèvement pour une opération d’E/S réussie à partir du port d’achèvement et a stocké des informations dans les variables pointées par les paramètres suivants : lpNumberOfBytes, lpCompletionKey et lpOverlapped. En cas d’échec (la valeur de retour est FALSE), ces mêmes paramètres peuvent contenir des combinaisons de valeurs particulières comme suit :

Si *lpOverlapped a la valeur NULL, la fonction n’a pas retiré la file d’attente d’un paquet d’achèvement du port d’achèvement. Dans ce cas, la fonction ne stocke pas d’informations dans les variables pointées par les paramètres lpNumberOfBytes et lpCompletionKey , et leurs valeurs sont indéterminées.
Si *lpOverlapped n’a pas la valeur NULL et que la fonction met en file d’attente un paquet d’achèvement pour une opération d’E/S ayant échoué à partir du port d’achèvement, la fonction stocke des informations sur l’opération ayant échoué dans les variables pointées par lpNumberOfBytes, lpCompletionKey et lpOverlapped. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Pour plus d’informations sur la théorie des ports d’achèvement d’E/S, l’utilisation et les fonctions associées, consultez Ports d’achèvement d’E/S.

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie	Pris en charge
Protocole SMB (Server Message Block) 3.0	Oui
Basculement transparent SMB 3.0 (TFO)	Oui
SMB 3.0 avec partages de fichiers avec montée en puissance sortante (SO)	Oui
Cluster Shared Volume File System (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

Configuration requise


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]
Plateforme cible	Windows
En-tête	ioapiset.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll