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

Статья
03/15/2023

Извлекает путь к известной папке в виде структуры ITEMIDLIST .

Синтаксис

HRESULT SHGetKnownFolderIDList(
  [in]  REFKNOWNFOLDERID rfid,
  [in]  DWORD            dwFlags,
  [in]  HANDLE           hToken,
  [out] PIDLIST_ABSOLUTE *ppidl
);

Параметры

[in] rfid

Тип: REFKNOWNFOLDERID

Ссылка на KNOWNFOLDERID , идентифицирующая папку. Папки, связанные с известными идентификаторами папок, могут не существовать в определенной системе.

[in] dwFlags

Тип: DWORD

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

[in] hToken

Тип: HANDLE

Маркер доступа, используемый для представления определенного пользователя. Этот параметр обычно имеет значение NULL, и в этом случае функция пытается получить доступ к экземпляру папки текущего пользователя. Однако может потребоваться присвоить значение hToken для папок, которые могут иметь несколько пользователей, но считаются принадлежащими одному пользователю. Наиболее часто используемая папка этого типа — Документы.

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

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

[out] ppidl

Тип: PIDLIST_ABSOLUTE*

При возврате этого метода содержит указатель на PIDL папки. Этот параметр передается неинициализированным. Вызывающий объект отвечает за освобождение возвращаемого PIDL, когда он больше не нужен путем вызова ILFree.

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

Тип: HRESULT

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

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

Код возврата

Описание

E_INVALIDARG

Среди прочего, это значение может указывать на то, что параметр rfid ссылается на KNOWNFOLDERID , отсутствующего в системе. Не все значения KNOWNFOLDERID присутствуют во всех системах. Используйте IKnownFolderManager::GetFolderIds , чтобы получить набор значений KNOWNFOLDERID для текущей системы.

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

Требования

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

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

IKnownFolder::GetPath

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

SHGetKnownFolderPath

SHSetKnownFolderPath