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

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

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\user name\Music" です。 フォルダーがリダイレクトされた場合、現在の値 (SHGFP_TYPE_CURRENT) は "D:\Music" である可能性があります。 フォルダーがリダイレクトされていない場合は、SHGFP_TYPE_DEFAULTし、同じパスを取得SHGFP_TYPE_CURRENT。

SHGFP_TYPE_CURRENT

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

SHGFP_TYPE_DEFAULT

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

[out] pszPath

種類: LPTSTR

パスを受け取る長さMAX_PATH の 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, ...);
}

要件

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

こちらもご覧ください

IKnownFolder::GetPath