Função FindNextFileA (fileapi.h)

Artigo
11/20/2024

Continua uma pesquisa de arquivo de uma chamada anterior para as funções FindFirstFile, FindFirstFileExou FindFirstFileTransacted.

Sintaxe

BOOL FindNextFileA(
  [in]  HANDLE             hFindFile,
  [out] LPWIN32_FIND_DATAA lpFindFileData
);

Parâmetros

[in] hFindFile

O identificador de pesquisa retornado por uma chamada anterior para a função FindFirstFile ou FindFirstFileEx.

[out] lpFindFileData

Um ponteiro para a estrutura WIN32_FIND_DATA que recebe informações sobre o arquivo encontrado ou o subdiretório.

Valor de retorno

Se a função for bem-sucedida, o valor retornado não será zero e o parâmetro lpFindFileData conterá informações sobre o próximo arquivo ou diretório encontrado.

Se a função falhar, o valor retornado será zero e o conteúdo de lpFindFileData serão indeterminados. Para obter informações de erro estendidas, chame a função GetLastError.

Se a função falhar porque não é possível encontrar mais arquivos correspondentes, a função GetLastError retornará ERROR_NO_MORE_FILES.

Observações

Essa função usa os mesmos filtros de pesquisa que foram usados para criar o identificador de pesquisa passado no parâmetro hFindFile. Para obter informações adicionais, consulte FindFirstFile e FindFirstFileEx.

A ordem na qual a pesquisa retorna os arquivos, como ordem alfabética, não é garantida e depende do sistema de arquivos. Se os dados precisarem ser classificados, o aplicativo deverá fazer a ordenação depois de obter todos os resultados.

Observação Em casos raros ou em um sistema fortemente carregado, as informações de atributo de arquivo em sistemas de arquivos NTFS podem não estar atuais no momento em que essa função é chamada. Para ter certeza de obter os atributos atuais de arquivo do sistema de arquivos NTFS, chame a função GetFileInformationByHandle.

A ordem na qual essa função retorna os nomes de arquivo depende do tipo do sistema de arquivos. Com o sistema de arquivos NTFS e os sistemas de arquivos CDFS, os nomes geralmente são retornados em ordem alfabética. Com os sistemas de arquivos FAT, os nomes geralmente são retornados na ordem em que os arquivos foram gravados no disco, que podem ou não estar em ordem alfabética. No entanto, conforme indicado anteriormente, esses comportamentos não são garantidos.

Se o caminho apontar para um link simbólico, o buffer de WIN32_FIND_DATA conterá informações sobre o link simbólico, não o destino.

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

Tecnologia	Suportado
Protocolo SMB (Bloco de Mensagens do Servidor) 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 de Cluster (CsvFS)	Sim
ReFS (Sistema de Arquivos Resiliente)	Sim

operações transacionadas

Se houver uma transação associada ao identificador de enumeração de arquivo, os arquivos retornados estarão sujeitos a regras de isolamento de transação.

Exemplos

Para obter um exemplo, consulte Listando os arquivos em um diretório.

Nota

O cabeçalho fileapi.h define FindNextFile como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	fileapi.h (inclua Windows.h)
biblioteca	Kernel32.lib
de DLL	Kernel32.dll