GetQueuedCompletionStatusEx, fonction

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

Pour retirer les paquets de complétion d’E/S de la file d’attente un par un, utilisez la fonction GetQueuedCompletionStatus .

Syntaxe

BOOL WINAPI GetQueuedCompletionStatusEx(
  _In_  HANDLE             CompletionPort,
  _Out_ LPOVERLAPPED_ENTRY lpCompletionPortEntries,
  _In_  ULONG              ulCount,
  _Out_ PULONG             ulNumEntriesRemoved,
  _In_  DWORD              dwMilliseconds,
  _In_  BOOL               fAlertable
);

Paramètres

Port d’achèvement[in]

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

lpCompletionPortEntries[out]

En entrée, pointe vers un ensemble 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 du tableau est fourni par ulNumEntriesRemoved.

Le nombre d’octets transférés au cours de chaque E/S, la clé de complétion qui indique sur quel fichier chaque E/S a eu lieu et l’adresse de structure superposée utilisée dans chaque E/S d’origine sont tous renvoyés dans le tableau lpCompletionPortEntry .

ulCount[in]

Nombre maximal d’entrées à supprimer.

ulNumEntriesRemoved[out]

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

dwMillisecondes[in]

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

Si dwMilliseconds est INFINI (0xFFFFFFFF), la fonction n’expirera jamais. Si dwMilliseconds est égal à zéro et qu’il n’y a pas d’opération d’E/S à retirer 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. Par exemple, le délai d’expiration continue de compter à rebours 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. Par exemple, le délai d’expiration ne continue pas à compter pendant que l’ordinateur est en veille.

fAlertable[in]

Si ce paramètre est FALSE, la fonction ne retourne pas tant que le délai d’expiration n’est pas écoulé ou qu’une entrée n’est pas 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 est renvoyé lorsque le système met en file d’attente une routine de complétion d’E/S ou APC vers 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 lorsque vous appelez QueueUserAPC.

Valeur retournée

Renvoie une valeur non nulle TRUE en cas de réussite ou zéro FALSE dans le cas contraire.

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

Remarques

Cette fonction associe un thread au port de complétion spécifié. Un thread peut être associé à au plus un port de complétion.

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

Cette fonction renvoie FALSE lorsqu’aucune opération d’E/S n’a été retirée de la file d’attente. Cela signifie généralement qu’une erreur s’est produite lors du 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’erreur étendues.

Si un appel à GetQueuedCompletionStatusEx échoue parce que le descripteur qui lui est associé est fermé, la fonction est renvoyée FALSE et GetLastError renvoie 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 du premier entré, 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 et l’utilisation des ports de complétion d’E/S et les fonctions associées, consultez Ports de complétion d’E/S.

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

Spécifications

Voir aussi

Vue d’ensemble Rubriques

fonctions de gestion de fichiers

Ports de complétion d’E/S

Utilisation des en-têtes Windows

Fonctions

ConnectNamedPipe

CreateIoCompletionPort

DeviceIoControl

LockFileEx

readFile

PostQueuedCompletionStatus

TransactNamedPipe

WaitCommEvent

writeFile