GetQueuedCompletionStatus, fonction (ioapiset.h)
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.
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 |
Voir aussi
Fonctions de gestion de fichiers
Fonctions
Rubriques de vue d’ensemble