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