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

Устаревшие. Возвращает путь к папке, определяемой значением 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, определяющее папку, путь к которой требуется получить. Допустимы только реальные папки. Если указана виртуальная папка, эта функция завершается ошибкой. Вы можете принудительно создать папку, объединив CSI DL папки с CSIDL_FLAG_CREATE.

[in] hToken

Тип: HANDLE

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

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

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

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

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

[in] dwFlags

Тип: DWORD

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

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

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

Например, значение по умолчанию (SHGFP_TYPE_DEFAULT) для FOLDERID_Music (CSIDL_MYMUSIC) — "C:\Users\имя пользователя\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, ...);
}

Требования

См. также

IKnownFolder::GetPath