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

Статья
03/15/2023

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

Синтаксис

SHSTDAPI SHGetFolderLocation(
  [in]  HWND             hwnd,
  [in]  int              csidl,
  [in]  HANDLE           hToken,
  [in]  DWORD            dwFlags,
  [out] PIDLIST_ABSOLUTE *ppidl
);

Параметры

[in] hwnd

Тип: HWND

Зарезервировано.

[in] csidl

Тип: int

Значение CSIDL , определяющее расположенную папку. Папки, связанные с CSIDL, могут не существовать в определенной системе.

[in] hToken

Тип: HANDLE

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

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

[in] dwFlags

Тип: DWORD

[out] ppidl

Тип: PIDLIST_ABSOLUTE*

Адрес указателя на структуру списка идентификаторов элементов, которая указывает расположение папки относительно корня пространства имен (рабочего стола). Параметр ppidl имеет значение NULL при сбое. Вызывающее приложение отвечает за освобождение этого ресурса путем вызова ILFree.

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

Тип: HRESULT

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

Код возврата	Описание
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	CSIDL в nFolder является допустимым, но папка не существует.
E_INVALIDARG	Недопустимый CSIDL в nFolder.

Примечание В Windows Vista эта функция является просто оболочкой для SHGetKnownFolderIDList. Значение CSIDL преобразуется в связанный с ним KNOWNFOLDERID и вызывается SHGetKnownFolderIDList . Новые приложения должны использовать известную систему папок, а не старую систему CSIDL, которая поддерживается только для обеспечения обратной совместимости.

Функции SHGetFolderLocation, SHGetFolderPath, SHGetSpecialFolderLocation и SHGetSpecialFolderPath являются предпочтительными способами получения дескрипторов папок в системах, предшествующих Windows Vista. Такие функции, как ExpandEnvironmentStrings , которые используют имена переменных среды напрямую в виде %VariableName%, могут быть ненадежными.

Эта функция является надмножеством SHGetSpecialFolderLocation, включенной в более ранние версии оболочки.

Требования

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

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

IKnownFolder::GetIDList