Функция SearchPathW (processenv.h)

Статья
11/20/2024

Выполняет поиск указанного файла в указанном пути.

Синтаксис

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

Параметры

[in, optional] lpPath

Путь для поиска файла.

Если этот параметр null, функция ищет соответствующий файл с помощью пути поиска в системе, зависящем от реестра. Дополнительные сведения см. в разделе "Примечания".

[in] lpFileName

Имя файла, для которого выполняется поиск.

[in, optional] lpExtension

Расширение, добавляемое в имя файла при поиске файла. Первый символ расширения имени файла должен быть периодом (.). Расширение добавляется только в том случае, если указанное имя файла не заканчивается расширением.

Если расширение имени файла не является обязательным или если имя файла содержит расширение, этот параметр может быть NULL.

[in] nBufferLength

Размер буфера, получающего допустимый путь и имя файла (включая конечный символ NULL), в TCHARs.

[out] lpBuffer

Указатель на буфер для получения пути и имени файла найденного файла. Строка является строкой, завершающейся значением NULL.

[out, optional] lpFilePart

Указатель на переменную для получения адреса (в lpBuffer) последнего компонента допустимого пути и имени файла, который является адресом символа сразу после окончательной обратной косой черты (\) в пути.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значением является длина TCHARs, строки, скопированной в буфер, не включая завершающий символ NULL. Если возвращаемое значение больше nBufferLength, возвращаемое значением является размер буфера, который требуется для хранения пути, включая завершающий символ NULL.

Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

Замечания

Если параметр lpPath имеет значение NULL, SearchPath выполняет поиск соответствующего файла на основе текущего значения реестра:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\SafeProcessSearchMode

Если для этого значения реестра REG_DWORD задано значение 1, SearchPath сначала выполняет поиск папок, указанных в системном пути, а затем выполняет поиск текущей рабочей папки. Если для этого значения реестра задано значение 0, компьютер сначала выполняет поиск текущей рабочей папки, а затем выполняет поиск папок, указанных в системном пути. Системное значение по умолчанию для этого раздела реестра равно 0.

Режим поиска, используемый функцией SearchPath , также можно задать для каждого процесса путем вызова функции SetSearchPathMode.

Функция SearchPath не рекомендуется в качестве метода поиска файла .dll, если предполагаемое использование выходных данных вызывает функцию LoadLibrary. Это может привести к поиску неправильного .dll файла, так как порядок поиска функции SearchPath отличается от порядка поиска, используемого функцией LoadLibrary. Если необходимо найти и загрузить файл .dll, используйте функцию LoadLibrary.

совет начиная с Windows 10 версии 1607 для версии юникода этой функции (SearchPathW), вы можете отказаться от ограничения MAX_PATH. Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" файлы именования, пути и пространства имен.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технологии	Поддержанный
Протокол SMB 3.0	Да
Отработка отказа SMB 3.0 (TFO)	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Отказоустойчивая файловая система (ReFS)	Да

Заметка

Заголовок processenv.h определяет SearchPath как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	processenv.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll