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を に設定しますが、複数のユーザーを持つことができますが、1 人のユーザーに属していると見なされるフォルダーに対して hToken を するには、以外の NULL 値を割り当てる必要がある場合があります。 この種類の最も一般的に使用されるフォルダーは、ドキュメントです。

hToken が NULLでない場合、呼び出し元のプロセスは、正しい偽装を担当します。 呼び出し元のプロセスには、TOKEN_QUERYやTOKEN_IMPERSONATEなど、特定のユーザーに対する適切なセキュリティ特権が必要であり、ユーザーのレジストリ ハイブが現在マウントされている必要があります。 アクセス制御の問題の詳細については、アクセス制御の に関するページを参照してください。

hToken パラメーターに -1 の値を割り当てると、既定のユーザーが示されます。 これにより、SHGetFolderPath のクライアントは、既定のユーザーのフォルダーの場所 (デスクトップ フォルダーなど) を検索できます。 既定のユーザー ユーザー プロファイルは、新しいユーザー アカウントが作成されるときに複製され、個人用ドキュメントやデスクトップなどの特別なフォルダーが含まれます。 既定のユーザー フォルダーに追加されたすべての項目は、新しいユーザー アカウントにも表示されます。

[in] dwFlags

型: DWORD

返されるパスを指定するフラグ。 この値は、KNOWNFOLDERID (または CSIDL) に関連付けられているフォルダーを、ユーザーまたは管理者が言語間で移動、名前変更、リダイレクト、またはローミングできる場合に使用されます。

SHGetFolderPath 基になる既知のフォルダー システムを使用すると、ユーザーまたは管理者は、既知のフォルダーをニーズに合った場所にリダイレクトできます。 これは、SHGFP_TYPE_CURRENT フラグ 関連付けられたフォルダーの "現在の" 値を設定する IKnownFolderManager::Redirectを呼び出すことによって実現されます。

ユーザーまたは管理者が別の場所にリダイレクトしなかった場合のフォルダーの場所であるフォルダーの既定値は、SHGFP_TYPE_DEFAULT フラグを指定して取得されます。 この値を使用して、既知のフォルダーの "既定値の復元" 機能を実装できます。

たとえば、FOLDERID_Music (CSIDL_MYMUSIC) の既定値 (SHGFP_TYPE_DEFAULT) は "C:\Users\ユーザー名\Music" です。 フォルダーがリダイレクトされた場合、現在の値 (SHGFP_TYPE_CURRENT) は "D:\Music" である可能性があります。 フォルダーがリダイレクトされていない場合は、SHGFP_TYPE_DEFAULTし、同じパスを取得SHGFP_TYPE_CURRENT。

SHGFP_TYPE_CURRENT

フォルダーの現在のパスを取得します。

SHGFP_TYPE_DEFAULT

フォルダーの既定のパスを取得します。

[out] pszPath

型: LPWSTR

パスを受け取る長さMAX_PATH -terminated 文字列null へのポインター。 エラーが発生した場合、または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 ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして SHGetFolderPath を定義します。 エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「関数プロトタイプの 規則」を参照してください。

必要条件

要件	価値
サポートされる最小クライアント	Windows 2000 Professional、Windows XP [デスクトップ アプリのみ]
サポートされる最小サーバー	Windows 2000 Server [デスクトップ アプリのみ]
ターゲット プラットフォーム の	ウィンドウズ
ヘッダー	shlobj_core.h (Shlobj.h、Shlobj_core.h を含む)
ライブラリ	Shell32.lib
DLL	Shell32.dll (バージョン 5.0 以降)

関連項目

IKnownFolder::GetPath