FindFirstFile

La función FindFirstFile busca en un directorio un fichero cuyo nombre coincida con el nombre de fichero especificado. FindFirstFile examina los nombres de subdirectorio tanto como los de ficheros.

Sintaxis

HANDLE FindFirstFile(
    LPCTSTR lpFileName,               // puntero a un nombre de fichero a buscar  
    LPWIN32_FIND_DATA lpFindFileData  // puntero a la información retornada 
   );

Parámetros

lpFileName:

Windows 95: apunta a una cadena terminada en nulo que especifica un directorio o camino u directorio, que puede contener caracteres comodín (* y ?). Esta cadena no debe exceder de MAX_PATH caracteres.

Windows NT: apunta a una cadena terminada en nulo que especifica un directorio o camino u directorio, que puede contener caracteres comodín (* y ?).

Hay un límite de tamaño de cadena por defecto para caminos de MAX_PATH caracteres. Este límite está relacionado con el modo en que FindFirstFile analiza los caminos. Una aplicación puede sobrepasar este límite y enviar caminos de más de MAX_PATH caracteres llamando a la versión ancha (W) de FindFirstFile y anteponiendo "\\?\" al camino. El "\\?\" informa a la función para que desconecte el análisis de caminos; esto permite el uso de caminos de más de MAX_PATH caracteres con la función FindFirstFileW. Esto también funciona con nombres UNC. El "\\?\" se ignora como parte del camino. Por ejemplo, "\\?\C:\myworld\private" es tratado como "C:\myworld\private", y "\\?\UNC\bill_g_1\hotstuff\coolapps" es tratado como "\\bill_g_1\hotstuff\coolapps".

lpFindFileData: apunta a una estructura WIN32_FIND_DATA que recibirá información sobre el fichero o subdirectorio encontrado. La estructura puede ser usada en subsiguientes llamadas a la función FindNextFile o FindClose para referirse al fichero o al subdirectorio.

Valor de retorno

Si la función tiene éxito, el valor de retorno es un manipulador de búsqueda que puede ser usado en sucesivas llamadas a las funciones FindNextFile o FindClose.

Si la función falla, el valor de retorno es INVALID_HANDLE_VALUE. Para obtener información adicional sobre el error, llamar a GetLastError.

Observaciones

La función FindFirstFile se usa para abrir un manipulador de búsqueda y retornar información sobre el primer fichero cuyo nombre coincide con el patrón y atributos especificados.

Una vez establecida, se puede usar el manipulador de búsqueda en la función FindNextFile para buscar otros ficheros que coincidan con el mismo patrón de filtrado realizado. Cuando ya no se necesite el manipulador, debe ser cerrado usando la función FindClose.

Esta función busca ficheros sólo por el nombre; no puede ser usada para búsquedas basadas en atributos.