Função FindFirstFileExA (fileapi.h)
Pesquisa um diretório para um arquivo ou subdiretório com um nome e atributos que correspondem aos especificados.
Para obter a versão mais básica dessa função, consulte FindFirstFile.
Para executar essa operação como uma operação transacionada, use a função FindFirstFileTransacted .
Sintaxe
HANDLE FindFirstFileExA(
[in] LPCSTR lpFileName,
[in] FINDEX_INFO_LEVELS fInfoLevelId,
[out] LPVOID lpFindFileData,
[in] FINDEX_SEARCH_OPS fSearchOp,
LPVOID lpSearchFilter,
[in] DWORD dwAdditionalFlags
);
Parâmetros
[in] lpFileName
O diretório ou caminho e o nome do arquivo. O nome do arquivo pode incluir caracteres curinga, por exemplo, um asterisco (*) ou um ponto de interrogação (?).
Esse parâmetro não deve ser NULL, uma cadeia de caracteres inválida (por exemplo, uma cadeia de caracteres vazia ou uma cadeia de caracteres que não tem o caractere nulo de terminação) ou terminar em uma barra invertida à direita (\).
Se a cadeia de caracteres terminar com um curinga, ponto ou nome de diretório, o usuário deverá ter acesso à raiz e a todos os subdiretórios no caminho.
Por padrão, o nome é limitado a caracteres MAX_PATH. Para estender esse limite para 32.767 caracteres largos, preencha "\\?\" para o caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.
Dica
A partir do Windows 10, versão 1607, você pode optar por remover a limitação de MAX_PATH sem acrescentar "\\?\". Consulte a seção "Limitação máxima de comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.
[in] fInfoLevelId
O nível de informações dos dados retornados.
Esse parâmetro é um dos valores de enumeração FINDEX_INFO_LEVELS .
[out] lpFindFileData
Um ponteiro para o buffer que recebe os dados do arquivo.
O tipo de ponteiro é determinado pelo nível de informações especificado no parâmetro fInfoLevelId .
[in] fSearchOp
O tipo de filtragem a ser executada que é diferente da correspondência curinga.
Esse parâmetro é um dos valores de enumeração FINDEX_SEARCH_OPS .
lpSearchFilter
Um ponteiro para os critérios de pesquisa se o fSearchOp especificado precisar de informações de pesquisa estruturadas.
No momento, nenhum dos valores fSearchOp com suporte exige informações de pesquisa estendidas. Portanto, esse ponteiro deve ser NULL.
[in] dwAdditionalFlags
Especifica sinalizadores adicionais que controlam a pesquisa.
Retornar valor
Se a função for bem-sucedida, o valor retornado será um identificador de pesquisa usado em uma chamada subsequente para FindNextFile ou FindClose, e o parâmetro lpFindFileData conterá informações sobre o primeiro arquivo ou diretório encontrado.
Se a função falhar ou falhar ao localizar arquivos da cadeia de caracteres de pesquisa no parâmetro lpFileName , o valor retornado será INVALID_HANDLE_VALUE e o conteúdo de lpFindFileData será indeterminado. Para obter informações de erro estendidas, chame a função GetLastError .
Comentários
A função FindFirstFileEx abre um identificador de pesquisa e retorna informações sobre o primeiro arquivo que o sistema de arquivos encontra com um nome que corresponde ao padrão especificado. Esse pode ou não ser o primeiro arquivo ou diretório que aparece em um aplicativo de listagem de diretórios (como o comando dir) quando fornecido o mesmo padrão de cadeia de caracteres de nome de arquivo. Isso ocorre porque FindFirstFileEx não classifica os resultados da pesquisa. Para obter mais informações, consulte FindNextFile.
A lista a seguir identifica algumas outras características de pesquisa:
- A pesquisa é executada estritamente no nome do arquivo, não em nenhum atributo, como uma data ou um tipo de arquivo.
- A pesquisa inclui os nomes de arquivo longos e curtos.
- Uma tentativa de abrir uma pesquisa com uma barra invertida à direita sempre falha.
- Passar uma cadeia de caracteres inválida, NULL ou uma cadeia de caracteres vazia para o parâmetro lpFileName não é um uso válido dessa função. Os resultados nesse caso são indefinidos.
Depois que o identificador de pesquisa for estabelecido, use-o na função FindNextFile para pesquisar outros arquivos que correspondam ao mesmo padrão com a mesma filtragem que está sendo executada. Quando o identificador de pesquisa não for necessário, ele deverá ser fechado usando a função FindClose .
Conforme indicado anteriormente, você não pode usar uma barra invertida à direita (\) na cadeia de caracteres de entrada lpFileName para FindFirstFileEx, portanto, pode não ser óbvio como pesquisar diretórios raiz. Se você quiser ver arquivos ou obter os atributos de um diretório raiz, as seguintes opções se aplicarão:
- Para examinar arquivos em um diretório raiz, você pode usar "C:\*" e percorrer o diretório usando FindNextFile.
- Para obter os atributos de um diretório raiz, use a função GetFileAttributes .
Em compartilhamentos de rede, você pode usar um lpFileName na forma do seguinte: "\\server\service\*". No entanto, você não pode usar um lpFileName que aponta para o compartilhamento em si; por exemplo, "\\server\service" não é válido.
Para examinar um diretório que não é um diretório raiz, use o caminho para esse diretório, sem uma barra invertida à direita. Por exemplo, um argumento de "C:\Windows" retorna informações sobre o diretório "C:\Windows", não sobre um diretório ou arquivo em "C:\Windows". Para examinar os arquivos e diretórios em "C:\Windows", use um lpFileName de "C:\Windows\*".
A seguinte chamada:
FindFirstFileEx( lpFileName,
FindExInfoStandard,
lpFindData,
FindExSearchNameMatch,
NULL,
0 );
É equivalente à seguinte chamada:
FindFirstFile( lpFileName, lpFindData );
Lembre-se de que algum outro thread ou processo pode criar ou excluir um arquivo com esse nome entre o tempo que você consulta o resultado e a hora em que você agir sobre as informações. Se essa for uma preocupação potencial para seu aplicativo, uma solução possível é usar a função CreateFile com CREATE_NEW (que falha se o arquivo existir) ou OPEN_EXISTING (que falha se o arquivo não existir).
Se você estiver escrevendo um aplicativo de 32 bits para listar todos os arquivos em um diretório e o aplicativo puder ser executado em um computador de 64 bits, você deverá chamar Wow64DisableWow64FsRedirection antes de chamar FindFirstFileEx e chamar Wow64RevertWow64FsRedirection após a última chamada para FindNextFile. Para obter mais informações, consulte Redirecionamento do Sistema de Arquivos.
Se o caminho apontar para um link simbólico, o buffer WIN32_FIND_DATA conterá informações sobre o link simbólico, não o destino.
Em Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.
| Tecnologia | Com suporte |
|---|---|
| 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 |
Exemplos
O código a seguir mostra um uso mínimo de FindFirstFileEx. Este programa é equivalente ao exemplo no tópico FindFirstFile .
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
void _tmain(int argc, TCHAR *argv[])
{
WIN32_FIND_DATA FindFileData;
HANDLE hFind;
if( argc != 2 )
{
_tprintf(TEXT("Usage: %s [target_file]\n"), argv[0]);
return;
}
_tprintf (TEXT("Target file is %s\n"), argv[1]);
hFind = FindFirstFileEx(argv[1], FindExInfoStandard, &FindFileData,
FindExSearchNameMatch, NULL, 0);
if (hFind == INVALID_HANDLE_VALUE)
{
printf ("FindFirstFileEx failed (%d)\n", GetLastError());
return;
}
else
{
_tprintf (TEXT("The first file found is %s\n"),
FindFileData.cFileName);
FindClose(hFind);
}
}
Observação
O cabeçalho fileapi.h define FindFirstFileEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | fileapi.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |
Confira também
Funções de gerenciamento de arquivos
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de