Функция 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 в случае успешного выполнения или значение ошибки в противном случае, включая следующее:
| Код возврата | Описание |
|---|---|
|
Помимо прочего, это значение может указывать на то, что параметр радиочастотной идентификации ссылается на 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 или более поздняя) |