Função CancelIoEx (ioapiset.h)
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 CancelIoEx(
[in] HANDLE hFile,
[in, optional] LPOVERLAPPED lpOverlapped
);
Parâmetros
[in] hFile
Um manipulador para o arquivo.
[in, optional] lpOverlapped
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 nem 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á zero (0). 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á zero (0) 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 as E/S pendentes no identificador, ela não altera o estado do identificador e isso significa que você não pode confiar no estado do identificador porque não sabe 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á para cancelamento. A maioria dos tipos de operações pode ser cancelada imediatamente, mas outras operações podem continuar até a conclusão antes de serem realmente canceladas e o chamador ser 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 e você deve verificar o 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 se a operação tiver 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.
| Tecnologia | Com suporte |
|---|---|
| Protocolo SMB (SMB) 3.0 | Sim |
| TFO (Failover transparente) do SMB 3.0 | Sim |
| SMB 3.0 com compartilhamentos de arquivos de expansão (SO) | Sim |
| Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS) | 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] |
| Plataforma de Destino | Windows |
| Cabeçalho | ioapiset.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |
Confira também
Cancelar operações de E/S pendentes