SHGetFolderPath(A)

CSIDL 値から、対応するフォルダのパス名を取得します。

HRESULT SHGetFolderPathA(
    HWND   hwndOwner,
    int    nFolder,
    HANDLE hToken,
    DWORD  dwFlags,
    LPTSTR pszPath
);

SHELL32.DLL または SHFOLDER.DLL

引数

hwndOwner

オーナーウィンドウのハンドルを指定します。通常、このパラメータには 0 (NULL) が指定されます。このパラメータが 0 (NULL) でなく、かつ、フォルダへアクセスするのにダイアルアップ接続が必要な場合に、このウィンドウに対してユーザーインターフェースプロンプトが表示されます。

nFolder

パス名を取得するフォルダを識別する CSIDL 値を指定します。実フォルダのみが有効であり、仮想フォルダを指定した場合には関数は失敗します。フォルダの CSIDL 値に CSIDL_FLAG_CREATE を結合して指定することで、フォルダが存在しない場合に、自動的に対応するフォルダが作成されます。

hToken

特定のユーザーを表すのに使用されるアクセストークンを指定します。 Windows 2000 より前のシステムでは、このパラメータに 0 (NULL) を指定するべきです。それ以降のシステムにおいても、一般にこのパラメータには 0 (NULL) が指定されます。

dwFlags

どちらのパスが返されるかを指定するフラグを指定します。このパラメータは、 CSIDL 値に割り当てられているフォルダがユーザーによって移動されたり、名前を変更されるかもしれない場合に使用されます。

意味
0 (SHGFP_TYPE_CURRENT)

フォルダの現在のパス名を返します。

1 (SHGFP_TYPE_DEFAULT)

フォルダのデフォルトのパス名を返します。

pszPath

パス名を表わすヌル終端文字列を格納するバッファのアドレスを指定します。このバッファのサイズは少なくとも 260 (MAX_PATH) バイト(Unicode 版の場合は 260 (MAX_PATH) 文字)以上でなくてはなりません。関数が失敗するか、 (S_FALSE) を返した場合は、空文字列になります。

戻り値

HRESULT 型のコード(エラーの場合に最上位ビットがセットされる)が返ります。(ANSI版の場合は関数が失敗したときに、最上位ビットがセットされていない値 S_FALSE を返す場合があるので注意。) このコードは以下の値になる場合があります。

意味
0x00000001 (S_FALSE)

SHGetFolderPathA (ANSI版関数)のみ: nFolder パラメータの CSIDL 値は有効ですが、そのフォルダが存在しません。

0x80000008 (E_FAIL)

SHGetFolderPathW (Unicode版関数)のみ: nFolder パラメータの CSIDL 値は有効ですが、そのフォルダが存在しません。

0x80000003 (E_INVALIDARG)

nFolder パラメータに CSIDL 値として無効な値が指定されました。

解説

この関数は、以前のバージョンのシェルに含まれる SHGetSpecialFolderPath 関数のスーパーセットです。 Shell32.dll Version 5.0 (Windows Me/2000)よりも前のシステムでは、 SHGetFolderPath 関数は SHFolder.dll から提供されます。この DLL は、 Microsoft Internet Explorer 5.0 以降で配布されます。 SHFolder.dll は現在のプラットフォームのバージョンの関数を呼び出します。これに失敗すると、適切なふるまいを真似ようと試みます。この関数は現在 Shell32.dll に実装されていますが、互換性のため引き続き SHFolder.dll でサポートされます。

CSIDL 値のうち、以下のもののみがサポートされます。

対応情報

Shell32.dll Version 5.00 以降

Windows Me / 2000 以降

SHFolder.dll

Windows 98 SE 以降 / Windows NT 4.0 SP4 以降

Internet Explorer 5.0 以降をインストールした Windows 95 / 98 / NT 4.0