ホーム › UI.Shell › IKnownFolderManager

IKnownFolderManager

COM

📘 Microsoft Learn (日本語) · English

IID8be2d872-86aa-4d47-b776-32cca40c7018継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

既存の既知のフォルダー(known folder)を作成、列挙、または管理するメソッドを公開します。

メソッド 10

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT FolderIdFromCsidl(INT nCsidl, GUID* pfid)

レガシーな CSIDL 値に相当する KNOWNFOLDERID を取得します。

nCsidl	INT	in	CSIDL 値。
pfid	GUID*	out	このメソッドが返るときに、KNOWNFOLDERID へのポインターが格納されます。このポインターは未初期化の状態で渡されます。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドを呼び出すには、呼び出し元が少なくとも User 権限を持っている必要があります。

vtbl 4 HRESULT FolderIdToCsidl(GUID* rfid, INT* pnCsidl)

指定した KNOWNFOLDERID に相当するレガシーな CSIDL 値を取得します。

rfid	GUID*	in	KNOWNFOLDERID への参照。
pnCsidl	INT*	out	このメソッドが返るときに、CSIDL 値へのポインターが格納されます。このポインターは未初期化の状態で渡されます。

戻り値

型: HRESULT

成功した場合は S_OK を返します。それ以外の場合は、以下を含むエラー値を返します。

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

戻り値

説明

E_INVALIDARG

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

解説(Remarks)

このメソッドを呼び出すには、呼び出し元が少なくとも User 権限を持っている必要があります。

vtbl 5 HRESULT GetFolderIds(GUID** ppKFId, DWORD* pCount)

登録されているすべての既知のフォルダー ID の配列を取得します。これはすべての既知のフォルダーを列挙する際に使用できます。

ppKFId	GUID**	out	このメソッドが返るときに、システムに登録されているすべての KNOWNFOLDERID 値の配列へのポインターが格納されます。これらのリソースが不要になったら、CoTaskMemFree を使用して解放してください。
pCount	DWORD*	inout	このメソッドが返るときに、ppKFId の配列に含まれる KNOWNFOLDERID 値の数へのポインターが格納されます。このパラメーターの [in] としての機能は使用されません。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドの呼び出し元は User 権限を持っている必要があります。

取得した KNOWNFOLDERID 値を文字列に変換するには、StringFromCLSID または StringFromGUID2 を使用できます。

vtbl 6 HRESULT GetFolder(GUID* rfid, IKnownFolder** ppkf)

KNOWNFOLDERID で識別される既知のフォルダーを表すオブジェクトを取得します。

rfid	GUID*	in	KNOWNFOLDERID への参照。
ppkf	IKnownFolder**	out	このメソッドが返るときに、そのフォルダーを表す IKnownFolder オブジェクトへのインターフェイスポインターが格納されます。

戻り値

型: HRESULT

成功した場合は S_OK を返します。それ以外の場合は、以下を含むエラー値を返します。

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

戻り値

説明

E_INVALIDARG

解説(Remarks)

このメソッドを呼び出すには、呼び出し元が少なくとも User 権限を持っている必要があります。

使用する場面

探している既知のフォルダーが正確に分かっており、それに直接アクセスしたい場合にこのメソッドを使用します。

vtbl 7 HRESULT GetFolderByName(LPWSTR pszCanonicalName, IKnownFolder** ppkf)

正規名(canonical name)で識別される既知のフォルダーを表すオブジェクトを取得します。

pszCanonicalName	LPWSTR	in	既知のフォルダーのローカライズされていない正規名へのポインターで、null 終端の Unicode 文字列として格納されます。このフォルダーが common(共通)フォルダーまたは per-user(ユーザーごと)フォルダーである場合、この値は "User Shell Folders" レジストリ設定の値の名前としても使用されます。この値は、フォルダーの KNOWNFOLDER_DEFINITION 構造体の pszName メンバーを通じて取得されます。
ppkf	IKnownFolder**	out	このメソッドが返るときに、その既知のフォルダーを表す IKnownFolder オブジェクトへのポインターのアドレスが格納されます。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

使用する場面

探している既知のフォルダーが正確に分かっており、それに直接アクセスしたい場合にこのメソッドを使用します。

vtbl 8 HRESULT RegisterFolder(GUID* rfid, KNOWNFOLDER_DEFINITION* pKFD)

新しい既知のフォルダーをレジストリに追加します。特に、独立系ソフトウェアベンダー(ISV)が自身のフォルダーを既知のフォルダーシステムに追加する際に使用します。

rfid	GUID*	in	既知のフォルダーを表す GUID。
pKFD	KNOWNFOLDER_DEFINITION*	in	新しいフォルダーの詳細を提供する有効な KNOWNFOLDER_DEFINITION 構造体へのポインター。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

メモこのメソッドは HKEY_LOCAL_MACHINE を更新するため、管理者のコンテキストで実行する必要があります。セットアッププログラムが既知のフォルダーを登録または登録解除するには、管理者権限が必要です。

IKnownFolderManager::RegisterFolder は、新しい KNOWNFOLDERID が、既存の KNOWNFOLDERID が既に指し示しているファイルシステムパスを参照していないことを検証しようとします。新しい KNOWNFOLDERID がそのようなパスを指していることが判明した場合、このメソッドは失敗します。

同一のファイルシステムパスに対して複数の KNOWNFOLDERID 値が存在すると、Desktop.ini ファイルにおける競合など、いくつかの問題を引き起こす可能性があり、そのフォルダーに対してどの言語やプロパティを表示すべきかについての混乱につながります。また、複数の KNOWNFOLDERID 値は、Windows エクスプローラーにおけるアドレスバーのパスや、そのフォルダーに対して表示するタスクについての混乱を引き起こす可能性もあります。

既知のフォルダーのプロパティウィンドウの [カスタマイズ] ページの表示を抑制することができます。そのためには、次のレジストリ REG_DWORD 値を設定します。

HKEY_LOCAL_MACHINE
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  FolderDescriptions
                     Folder GUID
                        PropertyBag
                           NoCustomize = 0x00000001 (1)

vtbl 9 HRESULT UnregisterFolder(GUID* rfid)

既知のフォルダーをレジストリから削除し、既知のフォルダーシステムから認識されないようにします。このメソッドはフォルダー自体を削除するわけではありません。

rfid

GUID*

既知のフォルダーを表す GUID または KNOWNFOLDERID。

戻り値

型: HRESULT

成功した場合は S_OK を返します。それ以外の場合は、以下を含むエラー値を返します。

戻り値	説明
E_INVALIDARG	この値は、特に rfid パラメーターがシステムに存在しない KNOWNFOLDERID を参照していることを示す場合があります。すべての KNOWNFOLDERID 値がすべてのシステムに存在するわけではありません。現在のシステムが認識している KNOWNFOLDERID 値のセットを取得するには、IKnownFolderManager::GetFolderIds を使用してください。

戻り値

説明

E_INVALIDARG

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

解説(Remarks)

vtbl 10 HRESULT FindFolderFromPath(LPWSTR pszPath, FFFP_MODE mode, IKnownFolder** ppkf)

ファイルシステムパスに基づいて既知のフォルダーを表すオブジェクトを取得します。

pszPath

LPWSTR

既知のフォルダーへのパスを含む、長さ MAX_PATH の null 終端 Unicode 文字列へのポインター。

mode

FFFP_MODE

パスと既知のフォルダーの一致の精度を指定する、次のいずれかの値。

FFFP_EXACTMATCH

指定したファイルパスに対する特定の既知のフォルダーのみを取得します。

FFFP_NEARESTPARENTMATCH

指定したファイルパスに対して完全一致が見つからない場合、親ツリーを上にたどって、その親フォルダーのいずれかに一致する最初の既知のフォルダーを取得します。

ppkf

IKnownFolder**

out

このメソッドが返るときに、その既知のフォルダーを表す IKnownFolder オブジェクトへのポインターのアドレスが格納されます。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 11 HRESULT FindFolderFromIDList(ITEMIDLIST* pidl, IKnownFolder** ppkf)

IDList に基づいて既知のフォルダーを表すオブジェクトを取得します。このオブジェクトを使用すると、特定のフォルダープロパティの照会、フォルダーの現在のパスの取得、フォルダーの別の場所へのリダイレクト、および ITEMIDLIST としてのフォルダーのパスの取得が行えます。

pidl	ITEMIDLIST*	in	IDList へのポインター。
ppkf	IKnownFolder**	out	このメソッドが返るときに、その既知のフォルダーを表す IKnownFolder オブジェクトへのポインターのアドレスが格納されます。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 12 HRESULT Redirect(GUID* rfid, HWND hwnd, DWORD flags, LPWSTR pszTargetPath, DWORD cFolders, GUID* pExclusion, LPWSTR* ppszError)

common(共通)フォルダーおよび per-user(ユーザーごと)フォルダーに対するフォルダー要求をリダイレクトします。

rfid	GUID*	in	リダイレクトするフォルダーの KNOWNFOLDERID への参照。
hwnd	HWND	inoptional	flags パラメーターに KF_REDIRECT_WITH_UI が渡された場合に、コピーエンジンの進行状況 UI ダイアログを表示するために使用される親ウィンドウのハンドル。進行状況ダイアログが不要な場合、この値は NULL にできます。
flags	DWORD	in	リダイレクトに関する KF_REDIRECT_FLAGS オプション。
pszTargetPath	LPWSTR	inoptional	フォルダーの新しいパスへのポインター。これは null 終端の Unicode 文字列です。この値は NULL にできます。
cFolders	DWORD	in	pExclusion の配列に含まれる KNOWNFOLDERID 値の数。
pExclusion	GUID*	inoptional	リダイレクトから除外すべき rfid のサブフォルダーを参照する KNOWNFOLDERID 値の配列へのポインター。除外するサブフォルダーがない場合、この値は NULL にできます。
ppszError	LPWSTR*	outoptional	このメソッドが返るときに、エラーメッセージが生成された場合はそれを含む null 終端 Unicode 文字列へのポインターのアドレスが格納されます。この値は NULL にできます。

戻り値

型: HRESULT

成功した場合は S_OK を返します。それ以外の場合は、以下を含むエラー値を返します。

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

戻り値

説明

E_INVALIDARG

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IKnownFolderManager "{8BE2D872-86AA-4D47-B776-32CCA40C7018}"
#usecom global IKnownFolderManager IID_IKnownFolderManager "{4DF0C730-DF9D-4AE3-9153-AA6B82E9795A}"
#comfunc global IKnownFolderManager_FolderIdFromCsidl     3 int,var
#comfunc global IKnownFolderManager_FolderIdToCsidl       4 var,var
#comfunc global IKnownFolderManager_GetFolderIds          5 var,var
#comfunc global IKnownFolderManager_GetFolder             6 var,sptr
#comfunc global IKnownFolderManager_GetFolderByName       7 wstr,sptr
#comfunc global IKnownFolderManager_RegisterFolder        8 var,var
#comfunc global IKnownFolderManager_UnregisterFolder      9 var
#comfunc global IKnownFolderManager_FindFolderFromPath    10 wstr,int,sptr
#comfunc global IKnownFolderManager_FindFolderFromIDList  11 var,sptr
#comfunc global IKnownFolderManager_Redirect              12 var,sptr,int,wstr,int,var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IKnownFolderManager "{8BE2D872-86AA-4D47-B776-32CCA40C7018}"
#usecom global IKnownFolderManager IID_IKnownFolderManager "{4DF0C730-DF9D-4AE3-9153-AA6B82E9795A}"
#comfunc global IKnownFolderManager_FolderIdFromCsidl     3 int,sptr
#comfunc global IKnownFolderManager_FolderIdToCsidl       4 sptr,sptr
#comfunc global IKnownFolderManager_GetFolderIds          5 sptr,sptr
#comfunc global IKnownFolderManager_GetFolder             6 sptr,sptr
#comfunc global IKnownFolderManager_GetFolderByName       7 wstr,sptr
#comfunc global IKnownFolderManager_RegisterFolder        8 sptr,sptr
#comfunc global IKnownFolderManager_UnregisterFolder      9 sptr
#comfunc global IKnownFolderManager_FindFolderFromPath    10 wstr,int,sptr
#comfunc global IKnownFolderManager_FindFolderFromIDList  11 sptr,sptr
#comfunc global IKnownFolderManager_Redirect              12 sptr,sptr,int,wstr,int,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。