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

Не рекомендуется. Возвращает путь к папке, определяемой значением CSIDL .

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

 

Синтаксис

SHFOLDERAPI SHGetFolderPathW(
  [in]  HWND   hwnd,
  [in]  int    csidl,
  [in]  HANDLE hToken,
  [in]  DWORD  dwFlags,
  [out] LPWSTR pszPath
);

Параметры

[in] hwnd

Тип: HWND

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

[in] csidl

Тип: int

Значение CSIDL , определяющее папку, путь к которой требуется извлечь. Допустимы только реальные папки. Если указана виртуальная папка, эта функция завершается ошибкой. Вы можете принудительно создать папку, объединив CSIDL папки с CSIDL_FLAG_CREATE.

[in] hToken

Тип: HANDLE

Маркер доступа, который можно использовать для представления определенного пользователя.

Microsoft Windows 2000 и более ранние версии: Всегда присваивайте этому параметру значение NULL.

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

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

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

[in] dwFlags

Тип: DWORD

Флаги, указывающие возвращаемый путь. Это значение используется в случаях, когда пользователь или администратор может перемещать, переименовывать, перенаправлять или перемещать папку, связанную с KNOWNFOLDERID (или CSIDL).

Известная система папок, лежащая в основе SHGetFolderPath , позволяет пользователям или администраторам перенаправлять известную папку в расположение, которое соответствует их потребностям. Это достигается путем вызова IKnownFolderManager::Redirect, который задает текущее значение папки, связанной с флагом SHGFP_TYPE_CURRENT.

Значение по умолчанию папки, которое является расположением папки, если пользователь или администратор не перенаправлял ее в другое место, извлекается путем указания флага SHGFP_TYPE_DEFAULT. Это значение можно использовать для реализации функции восстановления по умолчанию для известной папки.

Например, значение по умолчанию (SHGFP_TYPE_DEFAULT) для FOLDERID_Music (CSIDL_MYMUSIC) — "C:\Users\user name\Music". Если папка была перенаправлена, текущим значением (SHGFP_TYPE_CURRENT) может быть "D:\Music". Если папка не была перенаправлена, SHGFP_TYPE_DEFAULT и SHGFP_TYPE_CURRENT получить тот же путь.

SHGFP_TYPE_CURRENT

Получите текущий путь к папке.

SHGFP_TYPE_DEFAULT

Получите путь по умолчанию к папке.

[out] pszPath

Тип: LPWSTR

Указатель на строку длиной, заканчивающуюся значением NULL, MAX_PATH которой будет получен путь. Если возникает ошибка или возвращается S_FALSE, эта строка будет пустой. Возвращаемый путь не включает обратную косую черту в конце. Например, возвращается "C:\Users", а не "C:\Users\".

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

Тип: HRESULT

Если эта функция выполняется успешно, она возвращает S_OK. В противном случае возвращается код ошибки HRESULT .

Комментарии

Эта функция является надмножеством SHGetSpecialFolderPath.

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

• CSIDL_ADMINTOOLS
• CSIDL_APPDATA
• CSIDL_COMMON_ADMINTOOLS
• CSIDL_COMMON_APPDATA
• CSIDL_COMMON_DOCUMENTS
• CSIDL_COOKIES
• CSIDL_FLAG_CREATE
• CSIDL_FLAG_DONT_VERIFY
• CSIDL_HISTORY
• CSIDL_INTERNET_CACHE
• CSIDL_LOCAL_APPDATA
• CSIDL_MYPICTURES
• CSIDL_PERSONAL
• CSIDL_PROGRAM_FILES
• CSIDL_PROGRAM_FILES_COMMON
• CSIDL_SYSTEM
• CSIDL_WINDOWS

Примеры

В следующем примере кода используется SHGetFolderPath , чтобы найти или создать папку, а затем создать в ней файл.

TCHAR szPath[MAX_PATH];

if(SUCCEEDED(SHGetFolderPath(NULL, 
                             CSIDL_PERSONAL|CSIDL_FLAG_CREATE, 
                             NULL, 
                             0, 
                             szPath))) 
{
    PathAppend(szPath, TEXT("New Doc.txt"));
    HANDLE hFile = CreateFile(szPath, ...);
}

Примечание

Заголовок shlobj_core.h определяет SHGetFolderPath в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

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

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

IKnownFolder::GetPath