Función SearchPathW (processenv.h)

Artículo
03/01/2024

Busca un archivo especificado en una ruta de acceso especificada.

Sintaxis

DWORD SearchPathW(
  [in, optional]  LPCWSTR lpPath,
  [in]            LPCWSTR lpFileName,
  [in, optional]  LPCWSTR lpExtension,
  [in]            DWORD   nBufferLength,
  [out]           LPWSTR  lpBuffer,
  [out, optional] LPWSTR  *lpFilePart
);

Parámetros

[in, optional] lpPath

Ruta de acceso en la que se va a buscar el archivo.

Si este parámetro es NULL, la función busca un archivo coincidente mediante una ruta de búsqueda del sistema dependiente del Registro. Para obtener más información, vea la sección Comentarios.

[in] lpFileName

Nombre del archivo que se va a buscar.

[in, optional] lpExtension

Extensión que se va a agregar al nombre de archivo al buscar el archivo. El primer carácter de la extensión de nombre de archivo debe ser un punto (.). La extensión solo se agrega si el nombre de archivo especificado no termina con una extensión.

Si no se requiere una extensión de nombre de archivo o si el nombre de archivo contiene una extensión, este parámetro puede ser NULL.

[in] nBufferLength

Tamaño del búfer que recibe la ruta de acceso y el nombre de archivo válidos (incluido el carácter NULO de terminación), en TCHAR.

[out] lpBuffer

Puntero al búfer para recibir la ruta de acceso y el nombre de archivo del archivo encontrado. La cadena es una cadena terminada en null.

[out, optional] lpFilePart

Puntero a la variable para recibir la dirección (dentro de lpBuffer) del último componente de la ruta de acceso y el nombre de archivo válidos, que es la dirección del carácter inmediatamente después de la barra diagonal inversa final (\) en la ruta de acceso.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es la longitud, en TCHAR, de la cadena que se copia en el búfer, sin incluir el carácter nulo de terminación. Si el valor devuelto es mayor que nBufferLength, el valor devuelto es el tamaño del búfer necesario para contener la ruta de acceso, incluido el carácter nulo de terminación.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Si el parámetro lpPath es NULL, SearchPath busca un archivo coincidente basado en el valor actual del siguiente valor del Registro:

HKEY_LOCAL_MACHINE\SISTEMA\Currentcontrolset\Control\Administrador de\ sesionesSafeProcessSearchMode

Cuando el valor de este REG_DWORD valor del Registro se establece en 1, SearchPath busca primero las carpetas especificadas en la ruta de acceso del sistema y, a continuación, busca en la carpeta de trabajo actual. Cuando el valor de este valor del Registro se establece en 0, el equipo busca primero en la carpeta de trabajo actual y, a continuación, busca en las carpetas especificadas en la ruta de acceso del sistema. El valor predeterminado del sistema para esta clave del Registro es 0.

El modo de búsqueda que usa la función SearchPath también se puede establecer por proceso mediante una llamada a la función SetSearchPathMode .

La función SearchPath no se recomienda como método para buscar un archivo .dll si el uso previsto de la salida está en una llamada a la función LoadLibrary . Esto puede dar lugar a la búsqueda del archivo de .dll incorrecto porque el orden de búsqueda de la función SearchPath difiere del orden de búsqueda usado por la función LoadLibrary . Si necesita buscar y cargar un archivo .dll, use la función LoadLibrary .

Propina A partir de Windows 10, versión 1607, para la versión unicode de esta función (SearchPathW), puede optar por quitar la limitación de MAX_PATH. Consulte la sección "Limitación máxima de longitud de ruta de acceso" de Nombres de archivos, rutas de acceso y espacios de nombres para obtener más información.

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

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

Nota

El encabezado processenv.h define SearchPath como un 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

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	processenv.h (incluir Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll