winbase.h


FindFirstFileEx

[Nuevo - Windows NT]

La función FindFirstFileEx busca en un directorio un fichero cuyo nombre y atributos coincidan con los especificados en la llamada a la función.

Sintaxis

HANDLE FindFirstFileEx(
    LPCTSTR lpFileName,               // puntero al nombre del fichero a buscar
    FINDEX_INFO_LEVELS fInfoLevelId,  // nivel de información de los datos devueltos
    LPVOID lpFindFileData,            // puntero a la información retornada
    FINDEX_SEARCH_OPS fSearchOp,      // tipo de filtrado a realizar
    LPVOID lpSearchFilter,            // puntero al criterio de búsqueda
    DWORD dwAdditionalFlags           // banderas de control de búsqueda adicionales
   );

Parámetros

lpFileName: apunta a una cadena terminada con cero que especifica un directorio válido o un camino y un nombre de fichero, que puede contener caracteres comodín (* y ?).

fInfoLevelId: especifica el nivel de información de los datos retornados. Si se usa la constante FindExInfoStandard, el puntero lpFindFileData es la estructura estándar WIN32_FIND_DATA usada con FindFirstFile. Hasta este momento, no están soportados otros niveles de información.

lpFindFileData: puntero a los datos del fichero. El tipo de puntero es determinado por el nivel de información especificado en el parámetro fInfoLevelId.

fSearchOp: especifica el tipo de filtrado a realizar además del de las coincidencias de los comodines. para más detalles, ver la sección de observaciones más adelante.

lpSearchFilter: si el valor especificado en fSearchOp necesita información estructurada de búsqueda, lpSearchFilter apunta al criterio de búsqueda. Hasta este momento, ninguno de los valores soportados para fSearchOp requiere información de búsqueda adicional. De modo que, este puntero debe ser NULL.

dwAdditionalFlags: especifica banderas adicionales para controlar la búsqueda. Se puede especificar la bandera FIND_FIRST_EX_CASE_SENSITIVE para búsquedas sensibles al tipo (case-sensitive). La búsqueda por defecto es insensible al tipo (case insensitive). Hasta este momento, no están definidas otras banderas.

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 FindFirstFileEx 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.

Se sigue un camino de filtrado diferente dependiendo del valor de fSearchOp. El parámetro fSearchOp puede tener uno de los siguientes valores:

ValorSignificado
FindExSearchNameMatchBusca un fichero que coincida con el nombre de fichero especificado. Tener en cuenta que lpSearchFilter debe ser NULL cuando se use esta operación de búsqueda.
FindExSearchLimitToDevicesSólo se devuelven nombres de disponsitivos. Los nombres de dispositivo generalmente son accesibles mediante la convención \\.\. El parámetro dwAdditionalFlags no puede ser FIND_FIRST_EX_CASE_SENSITIVE cuando se usa esta operación de búsqueda.
FindExSearchLimitToDirectoriesEs una bandera informativa.
Si el sistema de ficheros soporta filtrado de directorios, la función busca un fichero que coincida con el nombre de fichero especificado y que sea un directorio.
Si el sistema de ficheros no soporta filtrado de directorios, esta bandera sencillamente se ignora.
El parámetro lpSearchFilter debe ser NULL cuando se usa esta operación de busqueda.
Si se quiere un filtrado de directorios, usar esta bandera en todos los sistemas de ficheros, pero es necesario asegurarse de examinar los datos almacenados en *lpFindFileData para determinar si la función a devuelto efectivamente un manipulador de un directorio.

Si el sistema de ficheros subyacente no soporta un tipo particular de filtrado, a parte del filtrado de directorios, FindFirstFileEx fallará con el error ERROR_NOT_SUPPORTED. La aplicación debe usar el tipo FileExSearchNameMatch y realizar su propio filtrado.

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 patron de filtrado realizado. Cuando ya no se necesite el manipulador, debe ser cerrado usando la función FindClose.

La llamada:

FindFirstFileEx( lpFileName,  
                 FindExInfoStandard, 
                 lpFindData, 
                 FindExSearchNameMatch, 
                 NULL, 
                 0 );

es equivalente a la llamada:

FindFirstFile( lpFileName, lpFindData);