CancelIoEx, fonction (ioapiset.h)

Marque toutes les opérations d’E/S en cours pour le gestionnaire de fichiers spécifié. Cette fonction annule seulement les opérations d’E/S dans le processus actif, quel que soit le thread qui a créé l’opération d’E/S.

Syntaxe

BOOL CancelIoEx(
  [in]           HANDLE       hFile,
  [in, optional] LPOVERLAPPED lpOverlapped
);

Paramètres

[in] hFile

Descripteur du fichier.

[in, optional] lpOverlapped

Pointeur vers une structure de données OVERLAPPED qui contient les données utilisées pour les E/S asynchrones.

Si ce paramètre a la valeur NULL, toutes les demandes d’E/S pour le paramètre hFile sont annulées.

Si ce paramètre n’est pas NULL, seules les demandes d’E/S spécifiques qui ont été émises pour le fichier avec la structure superposée lpOverlapped spécifiée sont marquées comme annulées, ce qui signifie que vous pouvez annuler une ou plusieurs demandes, tandis que la fonction CancelIo annule toutes les demandes en suspens sur un descripteur de fichier.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro. L’opération d’annulation de toutes les opérations d’E/S en attente émises par le processus appelant pour le descripteur de fichier spécifié a été demandée avec succès. L’application ne doit pas libérer ou réutiliser la structure OVERLAPPED associée aux opérations d’E/S annulées tant qu’elles ne sont pas terminées. Le thread peut utiliser la fonction GetOverlappedResult pour déterminer quand les opérations d’E/S elles-mêmes ont été effectuées.

Si la fonction échoue, la valeur de retour est zéro (0). Pour obtenir des informations détaillées sur l’erreur, appelez la fonction GetLastError.

Si cette fonction ne trouve pas de demande à annuler, la valeur de retour est 0 (zéro) et GetLastError retourne ERROR_NOT_FOUND.

Notes

La fonction CancelIoEx vous permet d’annuler des demandes dans des threads autres que le thread appelant. La fonction CancelIo annule seulement les demandes dans le thread qui a appelé la fonction CancelIo. CancelIoEx annule seulement les E/S en attente sur le descripteur, et il ne modifie pas l’état du descripteur ; cela signifie que vous ne pouvez pas vous appuyer sur l’état du descripteur, car vous ne pouvez pas savoir si l’opération a été effectuée avec succès ou annulée.

S’il y a des opérations d’E/S en attente en cours pour le descripteur de fichier spécifié, la fonction CancelIoEx les marque pour annulation. La plupart des types d’opérations peuvent être annulées immédiatement ; d’autres opérations peuvent se poursuivre jusqu’à leur achèvement avant qu’elles soient réellement annulées et que l’appelant soit averti. La fonction CancelIoEx n’attend pas que toutes les opérations annulées se terminent.

Si le descripteur de fichier est associé à un port de terminaison, un paquet de terminaison d’E/S n’est pas mis en file d’attente sur le port si une opération synchrone est annulée avec succès. Pour les opérations asynchrones toujours en attente, l’opération d’annulation va mettre en file d’attente un paquet de terminaison d’E/S.

L’opération en cours d’annulation est achevée avec un des trois statuts suivants : vous devez vérifier le statut d’achèvement pour déterminer l’état d’achèvement. Les trois statuts sont :

• L’opération s’est terminée normalement. Ceci peut se produire même si l’opération a été annulée, car la demande d’annulation peut ne pas avoir été envoyée à temps pour annuler l’opération.
• L'opération a été annulée. La fonction GetLastError retourne ERROR_OPERATION_ABORTED.
• L’opération a échoué avec une autre erreur. La fonction GetLastError retourne le code d’erreur approprié.

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

Voir aussi

CancelIo

CancelSynchronousIo

Annulation des opérations d’E/S en attente

Fonctions de gestion des fichiers

E/S synchrones et asynchrones