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

Статья
08/26/2023

Извлекает объект IShellItem , представляющий известную папку.

Синтаксис

HRESULT SHGetKnownFolderItem(
  [in]  REFKNOWNFOLDERID  rfid,
  [in]  KNOWN_FOLDER_FLAG flags,
  [in]  HANDLE            hToken,
  [in]  REFIID            riid,
  [out] void              **ppv
);

Параметры

[in] rfid

Тип: REFKNOWNFOLDERID

Ссылка на KNOWNFOLDERID, GUID , идентифицирующий папку, содержащую элемент.

[in] flags

Тип: KNOWN_FOLDER_FLAG

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

[in] hToken

Тип: HANDLE

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

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

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

[in] riid

Тип: REFIID

Ссылка на IID интерфейса, представляющего элемент, обычно IID_IShellItem или IID_IShellItem2.

[out] ppv

Тип: void**

При возврате этого метода содержит указатель интерфейса, запрошенный в riid.

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

Тип: HRESULT

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

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

Код возврата

Описание

E_INVALIDARG

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

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

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

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

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 7 [только классические приложения]
Минимальная версия сервера	Windows Server 2008 R2 [только классические приложения]
Целевая платформа	Windows
Header	shlobj_core.h (включая Shlobj.h)
Библиотека	Shell32.lib
DLL	Shell32.dll (версия 6.1 или более поздняя)
Набор API	ext-ms-win-shell-shell32-l1-2-1 (представлено в Windows 10 версии 10.0.10240)