Função CancelIoEx

Marca todas as operações de E/S pendentes para o identificador de arquivo especificado. A função cancela apenas as operações de E/S no processo atual, independentemente de qual thread criou a operação de E/S.

Sintaxe

BOOL WINAPI CancelIoEx(
  _In_     HANDLE       hFile,
  _In_opt_ LPOVERLAPPED lpOverlapped
);

Parâmetros

hFile [in]

Um identificador para o arquivo.

lpOverlapped [in, opcional]

Um ponteiro para uma estrutura de dados OVERLAPPED que contém os dados usados para E/S assíncrona.

Se esse parâmetro for NULL, todas as solicitações de E/S para o parâmetro hFile serão canceladas.

Se esse parâmetro não for NULL, somente as solicitações de E/S específicas que foram emitidas para o arquivo com a estrutura sobreposta lpOverlapped especificada serão marcadas como canceladas, o que significa que você pode cancelar uma ou mais solicitações, enquanto a função CancelIo cancela todas as solicitações pendentes em um identificador de arquivo.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero. A operação de cancelamento de todas as operações de E/S pendentes emitidas pelo processo de chamada para o identificador de arquivo especificado foi solicitada com êxito. O aplicativo não deve liberar ou reutilizar a estrutura OVERLAPPED associada às operações de E/S canceladas até que elas tenham sido concluídas. O thread pode usar a função GetOverlappedResult para determinar quando as próprias operações de E/S foram concluídas.

Se a função falhar, o valor retornado será 0 (zero). Para obter informações de erro estendidas, chame a função GetLastError .

Se essa função não conseguir encontrar uma solicitação para cancelar, o valor retornado será 0 (zero) e GetLastError retornará ERROR_NOT_FOUND.

Comentários

A função CancelIoEx permite cancelar solicitações em threads diferentes do thread de chamada. A função CancelIo cancela apenas solicitações no mesmo thread que chamou a função CancelIo . CancelIoEx cancela apenas E/S pendente no identificador, não altera o estado do identificador; isso significa que você não pode confiar no estado do identificador porque não pode saber se a operação foi concluída com êxito ou cancelada.

Se houver operações de E/S pendentes em andamento para o identificador de arquivo especificado, a função CancelIoEx as marcará como cancelamento. A maioria dos tipos de operações pode ser cancelada imediatamente; outras operações podem continuar até a conclusão antes que elas sejam realmente canceladas e o chamador seja notificado. A função CancelIoEx não aguarda a conclusão de todas as operações canceladas.

Se o identificador de arquivo estiver associado a uma porta de conclusão, um pacote de conclusão de E/S não será enfileirado na porta se uma operação síncrona for cancelada com êxito. Para operações assíncronas ainda pendentes, a operação de cancelamento enfileirará um pacote de conclusão de E/S.

A operação que está sendo cancelada é concluída com um dos três status; você deve marcar a status de conclusão para determinar o estado de conclusão. Os três status são:

• A operação foi concluída normalmente. Isso pode ocorrer mesmo que a operação tenha sido cancelada, pois a solicitação de cancelamento pode não ter sido enviada a tempo de cancelar a operação.
• A operação foi cancelada. A função GetLastError retorna ERROR_OPERATION_ABORTED.
• A operação falhou com outro erro. A função GetLastError retorna o código de erro relevante.

Em Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Tecnologia	Com suporte
Protocolo SMB 3.0	Sim
TFO (Failover Transparente) do SMB 3.0	Sim
SMB 3.0 com compartilhamentos de arquivos de expansão (SO)	Sim
CsvFS (Sistema de Arquivos de Volume Compartilhado clusterizado)	Sim
ReFS (Sistema de Arquivos Resiliente)	Sim

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP]
Cabeçalho	IoAPI.h (inclua Windows.h); WinBase.h no Windows Server 2008 R2, Windows 7, Windows Server 2008 e Windows Vista (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll

Confira também

CancelIo

CancelSynchronousIo

Cancelando operações de E/S pendentes

Funções de gerenciamento de arquivos

E/S síncrona e assíncrona