SHGetKnownFolderItem 関数 (shlobj_core.h)

既知のフォルダーを表す IShellItem オブジェクトを取得します。

構文

HRESULT SHGetKnownFolderItem(
  [in]  REFKNOWNFOLDERID  rfid,
  [in]  KNOWN_FOLDER_FLAG flags,
  [in]  HANDLE            hToken,
  [in]  REFIID            riid,
  [out] void              **ppv
);

Parameters

[in] rfid

型: REFKNOWNFOLDERID

アイテムを含むフォルダーを識別する GUID である KNOWNFOLDERID への参照。

[in] flags

型: KNOWN_FOLDER_FLAG

既知のフォルダー IShellItem の取得に使用される特別なオプションを指定するフラグ。 この値は KF_FLAG_DEFAULTできます。それ以外の場合は、1 つ以上の KNOWN_FOLDER_FLAG 値。

[in] hToken

型: HANDLE

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

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

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

[in] riid

型: REFIID

項目を表すインターフェイスの IID への参照 (通常はIID_IShellItemまたはIID_IShellItem2)。

[out] ppv

型: void**

このメソッドが戻るときに、 riid で要求されたインターフェイス ポインターを格納します。

戻り値

型: HRESULT

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

注釈

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

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

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

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

Requirements

こちらも参照ください

IKnownFolder::GetPath

IKnownFolderManager::Redirect

既知のフォルダーのサンプル

SHCreateItemInKnownFolder

SHGetKnownFolderIDList

SHGetKnownFolderPath