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

Статья
11/20/2024

Устаревшие. Назначает новый путь к системной папке, определяемой его 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 или Юникод на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

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

См. также

IKnownFolder::SetPath

Поделиться через