Compartir a través de


Función FindFirstFileExW (fileapi.h)

Busca en un directorio un archivo o subdirectorio con un nombre y atributos que coincidan con los especificados.

Para obtener la versión más básica de esta función, consulte FindFirstFile.

Para realizar esta operación como una operación de transacción, use la función FindFirstFileTransacted .

Sintaxis

HANDLE FindFirstFileExW(
  [in]  LPCWSTR            lpFileName,
  [in]  FINDEX_INFO_LEVELS fInfoLevelId,
  [out] LPVOID             lpFindFileData,
  [in]  FINDEX_SEARCH_OPS  fSearchOp,
        LPVOID             lpSearchFilter,
  [in]  DWORD              dwAdditionalFlags
);

Parámetros

[in] lpFileName

Directorio o ruta de acceso, y el nombre de archivo. El nombre de archivo puede incluir caracteres comodín, por ejemplo, un asterisco (*) o un signo de interrogación (?).

Este parámetro no debe ser NULL, una cadena no válida (por ejemplo, una cadena vacía o una cadena que falta el carácter nulo de terminación) o finalizar en una barra diagonal inversa final (\).

Si la cadena termina con un carácter comodín, un punto o un nombre de directorio, el usuario debe tener acceso a la raíz y a todos los subdirectorios de la ruta de acceso.

En la de esta función, el nombre se limita a MAX_PATH caracteres. Para ampliar este límite a aproximadamente 32 000 caracteres anchos, llame a la versión Unicode de la función (FindFirstFileExW) y anteponga "\\?\" a la ruta de acceso. Para obtener más información, consulte Nomenclatura de un archivo.

Propina A partir de Windows 10, versión 1607, para la versión unicode de esta función (FindFirstFileExW), puede optar por quitar la limitación de caracteres de MAX_PATH sin prepending "\\?\". Consulte la sección "Limitación máxima de rutas de acceso" de Nomenclatura de archivos, rutas de acceso y espacios de nombres para obtener más información.
 

[in] fInfoLevelId

Nivel de información de los datos devueltos.

Este parámetro es uno de los FINDEX_INFO_LEVELS valores de enumeración.

[out] lpFindFileData

Puntero al búfer que recibe los datos del archivo.

El tipo de puntero viene determinado por el nivel de información especificado en el parámetro fInfoLevelId .

[in] fSearchOp

El tipo de filtrado que se va a realizar es diferente de la coincidencia de caracteres comodín.

Este parámetro es uno de los FINDEX_SEARCH_OPS valores de enumeración.

lpSearchFilter

Puntero a los criterios de búsqueda si el fSearchOp especificado necesita información de búsqueda estructurada.

En este momento, ninguno de los valores de fSearchOp admitidos requiere información de búsqueda extendida. Por lo tanto, este puntero debe ser NULL.

[in] dwAdditionalFlags

Especifica marcas adicionales que controlan la búsqueda.

Value Significado
FIND_FIRST_EX_CASE_SENSITIVE
1
Las búsquedas distinguen mayúsculas de minúsculas.
FIND_FIRST_EX_LARGE_FETCH
2
Usa un búfer mayor para las consultas de directorio, lo que puede aumentar el rendimiento de la operación de búsqueda.

Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Este valor no se admite hasta Windows Server 2008 R2 y Windows 7.

FIND_FIRST_EX_ON_DISK_ENTRIES_ONLY
4
Limita los resultados a los archivos que están físicamente en el disco. Esta marca solo es relevante cuando hay un filtro de virtualización de archivos.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un identificador de búsqueda usado en una llamada posterior a FindNextFile o FindClose, y el parámetro lpFindFileData contiene información sobre el primer archivo o directorio encontrado.

Si se produce un error en la función o no se encuentra los archivos de la cadena de búsqueda en el parámetro lpFileName , el valor devuelto es INVALID_HANDLE_VALUE y el contenido de lpFindFileData es indeterminado. Para obtener información de error extendida, llame a la función GetLastError .

Observaciones

La función FindFirstFileEx abre un identificador de búsqueda y devuelve información sobre el primer archivo que el sistema de archivos encuentra con un nombre que coincida con el patrón especificado. Esto puede ser o no el primer archivo o directorio que aparece en una aplicación de lista de directorios (como el comando dir) cuando se le asigna el mismo patrón de cadena de nombre de archivo. Esto se debe a que FindFirstFileEx no realiza ninguna ordenación de los resultados de la búsqueda. Para obtener más información, vea FindNextFile.

En la lista siguiente se identifican otras características de búsqueda:

  • La búsqueda se realiza estrictamente en el nombre del archivo, no en ningún atributo como una fecha o un tipo de archivo.
  • La búsqueda incluye los nombres de archivo largos y cortos.
  • Siempre se produce un error al intentar abrir una búsqueda con una barra diagonal inversa final.
  • Pasar una cadena, NULL o una cadena vacía no válida para el parámetro lpFileName no es un uso válido de esta función. Los resultados en este caso no están definidos.
Nota En raras ocasiones o en un sistema muy cargado, es posible que la información del atributo de archivo en los sistemas de archivos NTFS no esté actualizada en el momento en que se llama a esta función. Para asegurarse de obtener los atributos de archivo del sistema de archivos NTFS actuales, llame a la función GetFileInformationByHandle .
 
Si el sistema de archivos subyacente no admite el tipo de filtrado especificado, aparte del filtrado de directorios, FindFirstFileEx produce un error ERROR_NOT_SUPPORTED. La aplicación debe usar FINDEX_SEARCH_OPS tipo FileExSearchNameMatch y realizar su propio filtrado.

Una vez establecido el identificador de búsqueda, úselo en la función FindNextFile para buscar otros archivos que coincidan con el mismo patrón con el mismo filtrado que se está realizando. Cuando no se necesite el identificador de búsqueda, debe cerrarse mediante la función FindClose .

Como se indicó anteriormente, no puede usar una barra diagonal inversa final (\) en la cadena de entrada lpFileName para FindFirstFileEx, por lo que puede no ser obvio cómo buscar directorios raíz. Si desea ver archivos u obtener los atributos de un directorio raíz, se aplicarán las siguientes opciones:

  • Para examinar los archivos de un directorio raíz, puede usar "C:\*" y recorrer el directorio mediante FindNextFile.
  • Para obtener los atributos de un directorio raíz, use la función GetFileAttributes .
Nota Prepending the string "\\\?\" does not allow access to the root directory.
 

En los recursos compartidos de red, puede usar un lpFileName en forma de lo siguiente: "\\server\service\*". Sin embargo, no puede usar un lpFileName que apunte al propio recurso compartido; Por ejemplo, "\\server\service" no es válido.

Para examinar un directorio que no es un directorio raíz, use la ruta de acceso a ese directorio, sin una barra diagonal inversa final. Por ejemplo, un argumento de "C:\Windows" devuelve información sobre el directorio "C:\Windows", no sobre un directorio o archivo en "C:\Windows". Para examinar los archivos y directorios en "C:\Windows", use un lpFileName de "C:\Windows\*".

La siguiente llamada:

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

Equivale a la siguiente llamada:

FindFirstFile( lpFileName, lpFindData );

Tenga en cuenta que algún otro subproceso o proceso podría crear o eliminar un archivo con este nombre entre el momento en que se consulta el resultado y el momento en que actúa sobre la información. Si se trata de una posible preocupación para la aplicación, una posible solución consiste en usar la función CreateFile con CREATE_NEW (lo que produce un error si el archivo existe) o OPEN_EXISTING (lo que produce un error si el archivo no existe).

Si está escribiendo una aplicación de 32 bits para enumerar todos los archivos de un directorio y la aplicación se puede ejecutar en un equipo de 64 bits, debe llamar a Wow64DisableWow64FsRedirection antes de llamar a FindFirstFileEx y llamar a Wow64RevertWow64FsRedirection después de la última llamada a FindNextFile. Para obtener más información, vea Redirector del sistema de archivos.

Si la ruta de acceso apunta a un vínculo simbólico, el búfer de WIN32_FIND_DATA contiene información sobre el vínculo simbólico, no el destino.

En Windows 8 y Windows Server 2012, esta función es compatible con las siguientes tecnologías.

Tecnología Compatible
Protocolo bloque de mensajes del servidor (SMB) 3.0
Conmutación por error transparente (TFO) de SMB 3.0
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)
Sistema de archivos de volumen compartido de clúster (CsvFS)
Sistema de archivos resistente a errores (ReFS)
 

Ejemplos

El código siguiente muestra un uso mínimo de FindFirstFileEx. Este programa es equivalente al ejemplo del tema 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);
   }
}

Nota:

El encabezado fileapi.h define FindFirstFileEx como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

   
Cliente mínimo compatible Windows XP [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2003 [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino Windows
Encabezado fileapi.h (incluye Windows.h)
Library Kernel32.lib
Archivo DLL Kernel32.dll

Vea también

FINDEX_INFO_LEVELS

FINDEX_SEARCH_OPS

Funciones de administración de archivos

FindClose

FindFirstFile

FindFirstFileTransacted

FindNextFile

GetFileAttributes

Asignar un nombre a un archivo

Vínculos simbólicos

Usar los encabezados de Windows

WIN32_FIND_DATA