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

  • Статья

Извлекает полный путь к известной папке, определяемой известным идентификатором KNOWNFOLDERID папки.

Синтаксис

HRESULT SHGetKnownFolderPath(
  [in]           REFKNOWNFOLDERID rfid,
  [in]           DWORD            dwFlags,
  [in, optional] HANDLE           hToken,
  [out]          PWSTR            *ppszPath
);

Параметры

[in] rfid

Тип: REFKNOWNFOLDERID

Ссылка на KNOWNFOLDERID , идентифицирующая папку.

[in] dwFlags

Тип: DWORD

Флаги, указывающие специальные параметры извлечения. Это значение может быть равно 0; в противном случае одно или несколько значений KNOWN_FOLDER_FLAG .

[in, optional] hToken

Тип: HANDLE

Маркер доступа, представляющий конкретного пользователя. Если этот параметр имеет значение NULL, что является наиболее распространенным использованием, функция запрашивает известную папку для текущего пользователя.

Запросите папку определенного пользователя, передав hToken этого пользователя. Обычно это делается в контексте службы, которая имеет достаточные привилегии для получения маркера данного пользователя. Этот маркер должен быть открыт с правами TOKEN_QUERY и TOKEN_IMPERSONATE . В некоторых случаях также необходимо включить TOKEN_DUPLICATE. Помимо передачи hToken пользователя, необходимо подключить куст реестра этого конкретного пользователя. Дополнительные сведения о проблемах управления доступом см. в контроль доступа.

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

[out] ppszPath

Тип: PWSTR*

При возврате этого метода содержит адрес указателя на строку Юникода, завершающуюся null, которая указывает путь к известной папке. Процесс вызова отвечает за освобождение этого ресурса после того, как он больше не требуется, вызывая CoTaskMemFree, независимо от того, успешно ли выполняется shGetKnownFolderPath . Возвращаемый путь не включает обратную косую черту в конце. Например, возвращается "C:\Users", а не "C:\Users\".

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

Тип: HRESULT

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

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

Комментарии

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

Требования

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

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

IKnownFolder::GetPath

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

SHGetKnownFolderIDList

SHSetKnownFolderPath