Функция 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 для этих папок, которые могут иметь несколько пользователей, но рассматриваются как принадлежащие одному пользователю. Наиболее часто используемая папка этого типа — Documents.

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

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

[in] pszPath

Тип: PCWSTR

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

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

Тип: HRESULT

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

Замечания

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

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

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

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

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

Требования

См. также

IKnownFolder::GetPath

IKnownFolder::SetPath

IKnownFolderManager::Redirect

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

SHGetKnownFolderIDList

SHGetKnownFolderPath