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

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

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

 

Синтаксис

SHFOLDERAPI SHGetFolderPathA(
  [in]  HWND   hwnd,
  [in]  int    csidl,
  [in]  HANDLE hToken,
  [in]  DWORD  dwFlags,
  [out] LPSTR  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

Тип: LPTSTR

Указатель на строку длиной, завершающуюся значением 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, ...);
}

Требования

Требование	Значение
Минимальная версия клиента	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