GetQueuedCompletionStatus, fonction (ioapiset.h)

Article
11/08/2024

Tente de mettre un paquet d’E/S en file d’attente à 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’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 l'structure SE CHEVAUCHER qui a été 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 SE CHEVAUCHER 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 de faible ordre. Un handle d’événement valide dont le bit de faible ordre est défini empêche l’achèvement des E/S superposées d’enquer un paquet d’achèvement vers le port d’achèvement.

[in] dwMilliseconds

Nombre de millisecondes que 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 FALSEet définit *lpOverlapped sur NULL.

Si dwMilliseconds est INFINITE, la fonction n’expire jamais. Si dwMilliseconds est égal à zéro et qu’il n’y a pas d’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 à faible alimentation. Par exemple, le délai d’expiration continue de compter pendant que l’ordinateur est endormi.

Windows 8 et versions ultérieures, Windows Server 2012 et versions ultérieures : La valeur dwMilliseconds n’inclut pas le temps passé dans les états à faible alimentation. Par exemple, le délai d’expiration ne continue pas à compter pendant que l’ordinateur est endormi.

Valeur de retour

Renvoie une valeur différente de zéro (TRUE) si elle réussit ou zéro (FALSE) sinon.

Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Pour plus d’informations, consultez la section Remarques.

Remarques

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 associé à celui-ci est fermé pendant que l’appel est en attente, la fonction retourne FALSE, *lpOverlapped sera NULLet GetLastError retournera ERROR_ABANDONED_WAIT_0.

Windows Server 2003 et Windows XP : fermeture du handle de port d’achèvement pendant qu’un appel 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 jusqu’à ce qu’un délai d’attente se produise, s’il est spécifié comme valeur autre que INFINITE.

Si la fonction GetQueuedCompletionStatus réussit, elle a supprimé 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, lpCompletionKeyet 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 est NULL, la fonction n’a pas mis en file d’attente un paquet d’achèvement à partir du port d’achèvement. Dans ce cas, la fonction ne stocke pas d’informations dans les variables pointées par les lpNumberOfBytes et paramètres lpCompletionKey, et leurs valeurs sont indéterminées.
Si *lpOverlapped n’est pas 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, lpCompletionKeyet lpOverlapped. Pour obtenir des informations d’erreur étendues, 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	Supporté
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 parallèle (SO)	Oui
Cluster Shared Volume File System (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau \| Applications UWP]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau \| Applications UWP]
plateforme cible	Windows
d’en-tête	ioapiset.h (include Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll