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