SHSetKnownFolderPath 関数 (shlobj_core.h)

[アーティクル]
03/02/2024

既知のフォルダーを新しい場所にリダイレクトします。

構文

HRESULT SHSetKnownFolderPath(
  [in] REFKNOWNFOLDERID rfid,
  [in] DWORD            dwFlags,
  [in] HANDLE           hToken,
  [in] PCWSTR           pszPath
);

パラメーター

[in] rfid

型: REFKNOWNFOLDERID

既知のフォルダーを識別する GUID 。

[in] dwFlags

型: DWORD

0 または次の値のいずれか。

KF_FLAG_DONT_UNEXPAND

このフラグが設定されている場合、 pszPath によって参照されるパスの一部は、などの %USERPROFILE%環境文字列で表される場合があります。

[in] hToken

型: HANDLE

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

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

hToken パラメーターに -1 の値を割り当てると、既定のユーザーが示されます。これにより、 SHSetKnownFolderPath のクライアントは、既定のユーザーのフォルダーの場所 ( デスクトップ フォルダーなど) を設定できます。既定のユーザーユーザープロファイルは、新しいユーザーアカウントが作成されると複製され、 ドキュメント や デスクトップなどの特別なフォルダーが含まれます。 [既定のユーザー] フォルダーに追加されたすべての項目は、新しいユーザーアカウントにも表示されます。既定のユーザーフォルダーへのアクセスには管理者特権が必要であることに注意してください。

[in] pszPath

種類: PCWSTR

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

戻り値

種類: HRESULT

成功した場合はS_OKを返し、それ以外の場合は次のようなエラー値を返します。

リターンコード	説明
E_INVALIDARG	特に、この値は、rfid パラメーターがシステムに存在しない KNOWNFOLDERID を参照していることを示している可能性があります。すべての KNOWNFOLDERID 値がすべてのシステムに存在するわけではありません。現在のシステムの KNOWNFOLDERID 値のセットを取得するには、IKnownFolderManager::GetFolderIds を使用します。

リターンコード

説明

E_INVALIDARG

特に、この値は 、rfid パラメーターがシステムに存在しない KNOWNFOLDERID を参照していることを示している可能性があります。すべての KNOWNFOLDERID 値がすべてのシステムに存在するわけではありません。現在のシステムの KNOWNFOLDERID 値のセットを取得するには、IKnownFolderManager::GetFolderIds を使用します。

注釈

この関数は、SHSetFolderPath を置き換えます。その古い関数は、 単に SHSetKnownFolderPath のラッパーになりました。

この関数の呼び出し元には管理者特権が必要です。既知のパブリックフォルダーでこの関数を呼び出すには、呼び出し元に管理者特権が必要です。ユーザーごとの既知のフォルダーの場合、呼び出し元にはユーザー特権のみが必要です。

一部の既知のフォルダー ( ドキュメント フォルダーなど) は、ユーザーごとです。すべてのユーザーは、 ドキュメント フォルダーのパスが異なります。 hToken が NULL の場合、API は呼び出し元のアプリケーションのフォルダーのインスタンス (現在のユーザーのインスタンス) にアクセスしようとします。 hToken が有効なユーザートークンの場合、API はこのトークンを使用してユーザーの偽装を試み、そのユーザーのインスタンスへのアクセスを試みます。

この関数は、 KF_CATEGORY_FIXED 型と KF_CATEGORY_VIRTUALのフォルダーでは呼び出すことができません。

KF_CATEGORY_COMMON型のフォルダーでこの関数を呼び出すには、呼び出し元のアプリケーションが管理者特権で実行されている必要があります。

要件

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