GetQueuedCompletionStatusEx, fonction (ioapiset.h)

Article
08/24/2023

Récupère simultanément plusieurs entrées du port d’achèvement. Elle attend que les opérations d’E/S en attente associées au port d’achèvement spécifié se terminent.

Pour enlever de la file d’attente les paquets d’achèvement d’E/S un par un, utilisez la fonction GetQueuedCompletionStatus.

Syntaxe

BOOL GetQueuedCompletionStatusEx(
  [in]  HANDLE             CompletionPort,
  [out] LPOVERLAPPED_ENTRY lpCompletionPortEntries,
  [in]  ULONG              ulCount,
  [out] PULONG             ulNumEntriesRemoved,
  [in]  DWORD              dwMilliseconds,
  [in]  BOOL               fAlertable
);

Paramètres

[in] CompletionPort

Descripteur du port d’achèvement. Pour créer un port d’achèvement, utilisez la fonction CreateIoCompletionPort.

[out] lpCompletionPortEntries

En entrée, pointe vers un tableau pré-alloué des structures OVERLAPPED_ENTRY.

En sortie, reçoit un tableau des structures OVERLAPPED_ENTRY qui contiennent les entrées. Le nombre d’éléments du tableau est fourni par ulNumEntriesRemoved.

Le nombre d’octets transférés à chaque E/S, la clé d’achèvement qui indique sur quel fichier a eu lieu chaque E/S ainsi que l’adresse de la structure superposée utilisée dans chaque E/S d’origine sont les éléments retournés dans le tableau lpCompletionPortEntries.

[in] ulCount

Nombre maximal d’entrées à supprimer.

[out] ulNumEntriesRemoved

Pointeur vers une variable qui reçoit le nombre d’entrées réellement supprimées.

[in] dwMilliseconds

Nombre de millisecondes pendant lesquelles l’appelant accepte d’attendre qu’un paquet d’achèvement apparaisse sur le port d’achèvement. Si aucun paquet d’achèvement n’apparaît dans le délai spécifié, la fonction expire et retourne FALSE.

Si dwMilliseconds est défini sur INFINITE (0xFFFFFFFF), la fonction n’expire jamais. Si dwMilliseconds est égal à zéro et qu’il n’y a aucune opération d’E/S à enlever de la 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é 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] fAlertable

Si ce paramètre a la valeur FALSE, la fonction n’est pas retournée tant que le délai d’attente n’est pas écoulé ou qu’une entrée n’est pas récupérée.

Si le paramètre a la valeur TRUE et qu’aucune entrée n’est disponible, la fonction se met dans un état d’attente susceptible de déclencher une alerte. Le thread est retourné quand le système met en file d’attente une routine d’achèvement d’E/S ou un APC sur le thread et que le thread exécute la fonction.

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 est terminée, et que le thread appelant est le thread qui a lancé l’opération. Un APC est mis en file d’attente quand vous appelez QueueUserAPC.

Valeur retournée

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

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

Remarques

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

Cette fonction retourne TRUE quand au moins une E/S en attente est achevée, même si une ou plusieurs opérations d’E/S ont échoué. Notez qu’il incombe à l’utilisateur de cette fonction d’examiner la liste des entrées retournées dans le paramètre lpCompletionPortEntries pour déterminer laquelle de ces entrées correspond à une opération d’E/S ayant pu échouer. Pour cela, il doit vérifier l’état indiqué dans l’élément lpOverlapped de chaque OVERLAPPED_ENTRY.

Cette fonction retourne FALSE quand aucune opération d’E/S n’a été enlevée de la file d’attente. Cela signifie généralement qu’une erreur s’est produite durant le traitement des paramètres de cet appel, ou que le descripteur CompletionPort a été fermé ou n’est pas valide. La fonction GetLastError fournit des informations détaillées sur l’erreur.

Si un appel de GetQueuedCompletionStatusEx échoue en raison de la fermeture du descripteur qui lui est associé, la fonction retourne FALSE et GetLastError retourne ERROR_ABANDONED_WAIT_0.

Les applications serveur peuvent avoir plusieurs threads qui appellent la fonction GetQueuedCompletionStatusEx sur le même port d’achèvement. À mesure que des opérations d’E/S sont effectuées, elles sont mises en file d’attente sur ce port dans l’ordre premier entrant/premier sorti. Si un thread attend activement cet appel, une ou plusieurs requêtes mises en file d’attente traitent l’appel pour ce thread uniquement.

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

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

Technologie	Prise en charge
Protocole Server Message Block (SMB) 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
Système de fichiers du volume partagé de cluster (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

Configuration requise

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