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


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

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

Синтаксис

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 для текущей системы.

Комментарии

Эта функция заменяет SHSetFolderPath. Эта старая функция теперь является просто оболочкой для SHSetKnownFolderPath.

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

Некоторые из известных папок, например Папки Документы , предназначены для каждого пользователя. У каждого пользователя есть свой путь к папке "Документы ". Если 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 или более поздняя)

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

IKnownFolder::GetPath

IKnownFolder::SetPath

IKnownFolderManager::Redirect

Пример: известные папки

SHGetKnownFolderIDList

SHGetKnownFolderPath