SHSetFolderPathA 関数 (shlobj_core.h)

  • [アーティクル]

非推奨になりました。 CSIDL によって識別されるシステム フォルダーに新しいパスを割り当てます。

構文

HRESULT SHSetFolderPathA(
  [in] int    csidl,
  [in] HANDLE hToken,
  [in] DWORD  dwFlags,
  [in] LPCSTR pszPath
);

パラメーター

[in] csidl

型: int

パスが設定されるフォルダーを識別する CSIDL 値。 物理フォルダーのみが有効です。 仮想フォルダーを指定すると、この関数は失敗します。

CSIDL_FLAG_DONT_UNEXPAND値を CSIDL に追加して、指定されたとおりに文字列がレジストリに確実に書き込まれるようにします。 CSIDL_FLAG_DONT_UNEXPAND フラグが含まれていない場合は、パスの一部を 、%USERPROFILE% などの環境文字列に置き換えることができます。

[in] hToken

型: HANDLE

特定のユーザーを表すために使用できる アクセス トークン 。 通常、このパラメーターは NULL に設定されます。この場合、関数はフォルダーの現在のユーザーのインスタンスにアクセスしようとします。 ただし、複数のユーザーを持つことができますが、1 人のユーザーに属するフォルダーに対して hToken に値を割り当てる必要がある場合があります。 この種類の最も一般的に使用されるフォルダーは Documents です。

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

[in] dwFlags

型: DWORD

予約済み。 0 に設定する必要があります。

[in] pszPath

型: LPCTSTR

フォルダーの新しいパスを含む長さMAX_PATHの null で終わる文字列へのポインター。 この値を NULL にすることはできません。また、文字列の長さを 0 にすることはできません。

戻り値

種類: HRESULT

次のような標準 の HRESULT コードを返します。

リターン コード 説明
S_OK
 フォルダーのパスが正常に更新されました。
E_INVALIDARG
 いくつかのエラー条件により、次のようなこの値が返されます。
  • csidl 値が無効です。
  • csidl 値は仮想フォルダーを参照しません。
  • csidl 値はシステム フォルダーを参照しません。
  • csidl 値は、名前の変更や移動ができないフォルダーを参照します。
  • dwFlags 値は 0 (ゼロ) ではありません。
  • pszPath 値は NULL です。
  • pszPath 値が指す文字列は、長さ 0 の空の文字列 ("") です。

注釈

メモ Windows Vista の時点では、この関数は SHSetKnownFolderPath のラッパーにすぎません。 CSIDL 値は関連する KNOWNFOLDERID に変換され、 SHSetKnownFolderPath が呼び出されます。 新しいアプリケーションでは、旧バージョンの CSIDL システムではなく、既知のフォルダー システムを使用する必要があります。これは、下位互換性のためにのみサポートされています。
 
SHSetFolderPath は、Shell32.dll から名前によってエクスポートされません。 関数を使用するには、 GETProcAddress を呼び出し、 SHSetFolderPathA の場合は序数 231 (ANSI 文字列の場合)、関数ポインターを取得するには SHSetFolderPathW (Unicode 文字列の場合) の序数 232 を呼び出す必要があります。

フォルダー名には ANSI では表現できない Unicode 文字が含まれる可能性があるため、パスは Unicode 文字列として表すことが推奨されます。

注意

shlobj_core.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして SHSetFolderPath を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

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

こちらもご覧ください

IKnownFolder::SetPath