Функция SHSetFolderPathA (shlobj_core.h)

Статья
08/26/2023

Не рекомендуется. Назначает новый путь к системной папке, определяемой по CSIDL.

Синтаксис

HRESULT SHSetFolderPathA(
  [in] int    csidl,
  [in] HANDLE hToken,
  [in] DWORD  dwFlags,
  [in] LPCSTR pszPath
);

Параметры

[in] csidl

Тип: int

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

Добавьте значение CSIDL_FLAG_DONT_UNEXPAND в CSIDL, чтобы убедиться, что строка записана в реестр точно так, как указано. Если флаг CSIDL_FLAG_DONT_UNEXPAND не включен, части пути могут быть заменены строками среды, такими как %USERPROFILE%.

[in] hToken

Тип: HANDLE

Маркер доступа, который можно использовать для представления определенного пользователя. Этот параметр обычно имеет значение NULL. В этом случае функция пытается получить доступ к экземпляру папки текущего пользователя. Однако может потребоваться присвоить значение hToken для тех папок, которые могут иметь несколько пользователей, но считаются принадлежащими одному пользователю. Наиболее часто используемая папка этого типа — Документы.

Вызывающее приложение отвечает за правильное олицетворение , если hToken не равно NULL. Он должен иметь соответствующие привилегии безопасности для конкретного пользователя, включая TOKEN_QUERY и TOKEN_IMPERSONATE, а куст реестра пользователя должен быть подключен в данный момент. Дополнительные сведения о проблемах управления доступом см. в контроль доступа.

[in] dwFlags

Тип: DWORD

Зарезервировано. Должен иметь значение 0.

[in] pszPath

Тип: LPCTSTR

Указатель на строку длиной, заканчивающуюся значением NULL, MAX_PATH, содержащую новый путь к папке. Это значение не может иметь значение NULL, а строка не может иметь нулевую длину.

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

Тип: HRESULT

Возвращает стандартные коды HRESULT , включая следующие:

Код возврата	Описание
S_OK	Путь к папке успешно обновлен.
E_INVALIDARG	Это значение возвращается из-за нескольких условий ошибок, в том числе: Недопустимое значение csidl . Значение csidl не ссылается на виртуальную папку. Значение csidl не ссылается на системную папку. Значение csidl относится к папке, которую нельзя переименовать или переместить. Значение dwFlags не равно 0 (ноль). Значение pszPath равно NULL. Строка, на которую указывает значение pszPath , представляет собой пустую строку ("") нулевой длины.

Код возврата

Описание

S_OK

Путь к папке успешно обновлен.

E_INVALIDARG

Это значение возвращается из-за нескольких условий ошибок, в том числе:

Недопустимое значение csidl .
Значение csidl не ссылается на виртуальную папку.
Значение csidl не ссылается на системную папку.
Значение csidl относится к папке, которую нельзя переименовать или переместить.
Значение dwFlags не равно 0 (ноль).
Значение pszPath равно NULL.
Строка, на которую указывает значение pszPath , представляет собой пустую строку ("") нулевой длины.

Примечание В Windows Vista эта функция является просто оболочкой для SHSetKnownFolderPath. Значение CSIDL преобразуется в связанное с ним значение KNOWNFOLDERID и вызывается SHSetKnownFolderPath . Новые приложения должны использовать известную систему папок, а не старую систему CSIDL, которая поддерживается только для обратной совместимости.

SHSetFolderPath не экспортируется по имени из Shell32.dll. Чтобы использовать функцию, необходимо вызвать Метод GetProcAddress с порядковым номером 231 для SHSetFolderPathA (для строк ANSI) или порядковый номер 232 для SHSetFolderPathW (для строк Юникода), чтобы получить указатель функции.

Рекомендуется, чтобы пути были выражены в виде строк Юникода, так как имена папок могут содержать символы Юникода, которые не могут быть выражены в ANSI.

Примечание

Заголовок shlobj_core.h определяет SHSetFolderPath в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	shlobj_core.h (включая Shlobj.h, Shlobj_core.h)
Библиотека	Shell32.lib
DLL	Shell32.dll (версия 5.0 или более поздняя)

См. также раздел

IKnownFolder::SetPath

Share via