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

Статья
03/15/2023

Перенаправляет известную папку в новое расположение.

Синтаксис

HRESULT SHSetKnownFolderPath(
  [in] REFKNOWNFOLDERID rfid,
  [in] DWORD            dwFlags,
  [in] HANDLE           hToken,
  [in] PCWSTR           pszPath
);

Параметры

[in] rfid

Тип: REFKNOWNFOLDERID

Идентификатор GUID, определяющий известную папку.

[in] dwFlags

Тип: DWORD

Либо 0, либо следующее значение.

KF_FLAG_DONT_UNEXPAND

Если этот флаг установлен, части пути, на которые ссылается pszPath, могут быть представлены строками среды, такими как %USERPROFILE%.

[in] hToken

Тип: HANDLE

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

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

Присвоение параметру hToken значения -1 указывает на пользователя по умолчанию. Это позволяет клиентам SHSetKnownFolderPath задавать расположения папок (например, папку Рабочего стола ) для пользователя по умолчанию. Профиль пользователя по умолчанию дублируется при создании новой учетной записи пользователя и включает специальные папки, такие как "Документы" и "Рабочий стол". Все элементы, добавленные в папку "Пользователь по умолчанию", также отображаются в любой новой учетной записи пользователя. Обратите внимание, что для доступа к папкам пользователей по умолчанию требуются права администратора.

[in] pszPath

Тип: PCWSTR

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

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

Тип: HRESULT

Возвращает S_OK в случае успешного выполнения или значение ошибки в противном случае, включая следующее:

Код возврата	Описание
E_INVALIDARG	Помимо прочего, это значение может указывать на то, что параметр радиочастотной идентификации ссылается на KNOWNFOLDERID , который отсутствует в системе. Не все значения KNOWNFOLDERID присутствуют во всех системах. Используйте IKnownFolderManager::GetFolderIds , чтобы получить набор значений KNOWNFOLDERID для текущей системы.

Код возврата

Описание

E_INVALIDARG

Помимо прочего, это значение может указывать на то, что параметр радиочастотной идентификации ссылается на KNOWNFOLDERID , который отсутствует в системе. Не все значения KNOWNFOLDERID присутствуют во всех системах. Используйте IKnownFolderManager::GetFolderIds , чтобы получить набор значений KNOWNFOLDERID для текущей системы.

Вызывающий объект этой функции должен иметь права администратора. Чтобы вызвать эту функцию в общедоступных известных папках, вызывающий объект должен иметь права администратора. Для известных папок для каждого пользователя вызывающей стороны требуются только привилегии пользователя.

Некоторые из известных папок, например Папки Документы , предназначены для каждого пользователя. У каждого пользователя есть свой путь к папке "Документы ". Если hToken имеет значение NULL, API пытается получить доступ к экземпляру папки вызывающего приложения, который является экземпляром текущего пользователя. Если hToken является допустимым маркером пользователя, API пытается олицетворить пользователя с помощью этого маркера и пытается получить доступ к экземпляру этого пользователя.

Эту функцию нельзя вызывать для папок типа KF_CATEGORY_FIXED и KF_CATEGORY_VIRTUAL.

Чтобы вызвать эту функцию в папке типа KF_CATEGORY_COMMON, вызывающее приложение должно выполняться с повышенными привилегиями.

Требования

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