GetQueuedCompletionStatusEx, fonction (ioapiset.h)

Article
11/08/2024

Récupère simultanément plusieurs entrées de port d’achèvement. Il attend que les opérations d’E/S en attente associées au port d’achèvement spécifié soient terminées.

Pour mettre en file d’attente les paquets 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

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

[out] lpCompletionPortEntries

Lors de l’entrée, pointe vers un tableau pré-alloué de structures OVERLAPPED_ENTRY.

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

Le nombre d’octets transférés pendant chaque E/S, la clé d’achèvement qui indique le fichier sur lequel chaque E/S s’est produite et l’adresse de structure superposée utilisée dans chaque E/S d’origine sont toutes retournées dans le tableau lpCompletionPortEntries tableau.

[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 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 et retourne FALSE.

Si dwMilliseconds est INFINITE (0xFFFFFFFF), 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.

[in] fAlertable

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

Si le paramètre est TRUE et qu’il n’y a pas d’entrées disponibles, la fonction effectue une attente alertable. Le thread retourne lorsque le système met en file d’attente une routine d’achèvement d’E/S ou d’APC sur le thread et que le thread exécute la fonction.

Une routine d’achèvement est mise en file d’attente lorsque l'ReadFileEx ou fonction WriteFileEx dans laquelle elle a été spécifiée a été terminée et que le thread appelant est le thread qui a lancé l’opération. Un APC est mis en file d’attente lorsque vous appelez QueueUserAPC.

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.

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.

Cette fonction retourne TRUE lorsqu’au moins une E/S en attente est terminée, mais il est possible qu’une ou plusieurs opérations d’E/S ont échoué. Notez qu’il incombe à l’utilisateur de cette fonction de vérifier la liste des entrées retournées dans le paramètre lpCompletionPortEntries pour déterminer lequel d’entre eux correspond à toutes les opérations d’E/S ayant échoué possibles en examinant l’état contenu dans le membre lpOverlapped dans chaque OVERLAPPED_ENTRY.

Cette fonction retourne FAUX quand aucune opération d’E/S n’a été mise en file d’attente. Cela signifie généralement qu’une erreur s’est produite lors du traitement des paramètres sur cet appel, ou que le handle CompletionPort a été fermé ou n’est pas valide. La fonction GetLastError fournit des informations d’erreur étendues.

Si un appel à GetQueuedCompletionStatusEx échoue, car le handle associé à celui-ci est fermé, la fonction retourne FALSE et GetLastError retourne ERROR_ABANDONED_WAIT_0.

Les applications serveur peuvent avoir plusieurs threads appelant la fonction GetQueuedCompletionStatusEx pour le même port d’achèvement. À mesure que les opérations d’E/S se terminent, elles sont mises en file d’attente vers ce port dans l’ordre de premier dans le premier sorti. Si un thread attend activement cet appel, une ou plusieurs demandes en file d’attente terminent l’appel pour ce thread uniquement.

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 Vista [applications de bureau \| Applications UWP]
serveur minimum pris en charge	Windows Server 2008 [applications de bureau \| Applications UWP]
plateforme cible	Windows
d’en-tête	ioapiset.h (include Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll