SHGetKnownFolderIDList 関数 (shlobj_core.h)

  • [アーティクル]

既知のフォルダーのパスを ITEMIDLIST 構造体として取得します。

構文

HRESULT SHGetKnownFolderIDList(
  [in]  REFKNOWNFOLDERID rfid,
  [in]  DWORD            dwFlags,
  [in]  HANDLE           hToken,
  [out] PIDLIST_ABSOLUTE *ppidl
);

パラメーター

[in] rfid

型: REFKNOWNFOLDERID

フォルダーを識別する KNOWNFOLDERID への参照。 既知のフォルダー ID に関連付けられているフォルダーは、特定のシステムに存在しない可能性があります。

[in] dwFlags

型: DWORD

特別な取得オプションを指定するフラグ。 この値は 0 にすることができます。それ以外の場合は、 KNOWN_FOLDER_FLAG 値の 1 つ以上です。

[in] hToken

型: HANDLE

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

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

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

[out] ppidl

種類: PIDLIST_ABSOLUTE*

このメソッドが戻るときに、 フォルダーの PIDL へのポインターを格納します。 このパラメーターは初期化せずに渡されます。 呼び出し元は、 ILFree を呼び出して不要になった場合に、返された PIDL を解放する必要があります。

戻り値

種類: HRESULT

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

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

注釈

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

この関数を使用する呼び出し元には、少なくともユーザー特権が必要です。

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

要件

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

こちらもご覧ください

IKnownFolder::GetPath

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

SHGetKnownFolderPath

SHSetKnownFolderPath