Win32 API 日本語リファレンス
ホーム › UI.Shell › IKnownFolder

IKnownFolder

COM
📘 Microsoft Learn (日本語) · English
IID3aa7af7e-9b36-420c-a8e3-f77d4674a488継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

アプリケーションが既知フォルダーのカテゴリ、種類、GUID、アイテム識別子リスト (PIDL) 値へのポインター、リダイレクト機能、および定義に関する情報を取得できるようにするメソッドを公開します。

解説(Remarks)

IKnownFolder オブジェクトは、IKnownFolderManager インターフェイスの IKnownFolderManager::GetFolder や IKnownFolderManager::FindFolderFromIDList などのいくつかのメソッドを通じて取得できます。

サードパーティは IKnownFolder を実装しません。提供されている実装を使用してください。

メソッド 9

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

vtbl 3 HRESULT GetId(GUID* pkfid)

選択されたフォルダーの ID を取得します。

pkfidGUID*outこのメソッドが返るとき、既知フォルダーの KNOWNFOLDERID 値を返します。KNOWNFOLDERID 値は GUID であることに注意してください。

戻り値

型: HRESULT

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

vtbl 4 HRESULT GetCategory(KF_CATEGORY* pCategory)

選択されたフォルダーのカテゴリ (仮想、固定、共通、またはユーザーごと) を取得します。

pCategoryKF_CATEGORY*outこのメソッドが返るとき、選択されたフォルダーの KF_CATEGORY へのポインターを格納します。

戻り値

型: HRESULT

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

vtbl 5 HRESULT GetShellItem(DWORD dwFlags, GUID* riid, void** ppv)

Shell 名前空間内の既知フォルダーの場所を、Shell アイテム (IShellItem または派生インターフェイス) の形式で取得します。

dwFlagsDWORDin特別な取得オプションを指定するフラグ。この値は 0 にすることができます。それ以外の場合は、1 つ以上の KNOWN_FOLDER_FLAG 値です。
riidGUID*in要求するインターフェイスの IID への参照。
ppvvoid**outこのメソッドが返るとき、riid で要求されたインターフェイスポインターを格納します。これは通常、IShellItem または IShellItem2 です。

戻り値

型: HRESULT

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

vtbl 6 HRESULT GetPath(DWORD dwFlags, LPWSTR* ppszPath)

既知フォルダーのパスを文字列として取得します。

dwFlagsDWORDin特別な取得オプションを指定するフラグ。この値は 0 にすることができます。それ以外の場合は、1 つ以上の KNOWN_FOLDER_FLAG 値です。
ppszPathLPWSTR*outこのメソッドが返るとき、パスを含む null 終端バッファーへのポインターのアドレスを格納します。呼び出し側アプリケーションは、このリソースが不要になったときに CoTaskMemFree を呼び出して解放する責任があります。

戻り値

型: HRESULT

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

解説(Remarks)

SHGetKnownFolderPath と同等です。

vtbl 7 HRESULT SetPath(DWORD dwFlags, LPWSTR pszPath)

既知フォルダーに新しいパスを割り当てます。

dwFlagsDWORDin

ゼロ、または次の値のいずれか:

KF_FLAG_DONT_UNEXPAND

環境文字列を含まない完全なパスを設定します。このフラグが設定されていない場合、pszPath のパスの一部が %USERPROFILE% などの環境文字列で表現されることがあります。

pszPathLPWSTRinフォルダーの新しいパスへのポインター。これは長さ MAX_PATH の null 終端 Unicode 文字列です。このパスは長さ 0 にすることはできません。この値が NULL の場合、IKnownFolder::SetPath はパスを既定値に設定します。

戻り値

型: HRESULT

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

解説(Remarks)

このメソッドは、KF_CATEGORY_FIXED または KF_CATEGORY_VIRTUAL 型のフォルダーに対しては呼び出すことができません。

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

このメソッドは SHSetKnownFolderPath と同等です。

vtbl 8 HRESULT GetIDList(DWORD dwFlags, ITEMIDLIST** ppidl)

Shell 名前空間フォルダーの場所を IDList (ITEMIDLIST) 形式で取得します。

dwFlagsDWORDin特別な取得オプションを指定するフラグ。この値は 0 にすることができます。それ以外の場合は、1 つ以上の KNOWN_FOLDER_FLAG 値です。
ppidlITEMIDLIST**outこのメソッドが返るとき、絶対 PIDL のアドレスを格納します。このパラメーターは初期化されずに渡されます。呼び出し側アプリケーションは、このリソースが不要になったときに解放する責任があります。

戻り値

型: HRESULT

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

解説(Remarks)

SHGetKnownFolderIDList と同等です。

vtbl 9 HRESULT GetFolderType(GUID* pftid)

フォルダーの種類を取得します。

pftidGUID*outこれが返るとき、既知フォルダーの種類を識別する FOLDERTYPEID (GUID) へのポインターを格納します。

戻り値

型: HRESULT

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

vtbl 10 HRESULT GetRedirectionCapabilities(DWORD* pCapabilities)

既知フォルダーのパスを新しい値に設定できるかどうか、またはそのリダイレクトに課される特定の制限や禁止事項を示す値を取得します。

pCapabilitiesDWORD*outこのメソッドが返るとき、このフォルダーのリダイレクト機能を示す KF_REDIRECTION_CAPABILITIES 値へのポインターを格納します。

戻り値

型: HRESULT

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

vtbl 11 HRESULT GetFolderDefinition(KNOWNFOLDER_DEFINITION* pKFD)

既知フォルダーの定義要素を含む構造体を取得します。これには、フォルダーのカテゴリ、名前、パス、説明、ツールチップ、アイコン、およびその他のプロパティが含まれます。

pKFDKNOWNFOLDER_DEFINITION*outこのメソッドが返るとき、KNOWNFOLDER_DEFINITION 構造体へのポインターを格納します。不要になったときは、呼び出し側アプリケーションが FreeKnownFolderDefinitionFields を呼び出してこのリソースを解放する責任があります。

戻り値

型: HRESULT

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

解説(Remarks)

サードパーティアプリケーションが独自の既知フォルダーを作成する場合、KNOWNFOLDER_DEFINITION 構造体でそれを定義し、システムに登録することで作成します。登録された既知フォルダーの定義情報 (システム提供またはアプリケーション作成) は、このメソッドを通じて取得できます。

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

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IKnownFolder "{3AA7AF7E-9B36-420C-A8E3-F77D4674A488}"
#usecom global IKnownFolder IID_IKnownFolder "{}"
#comfunc global IKnownFolder_GetId                       3 var
#comfunc global IKnownFolder_GetCategory                 4 var
#comfunc global IKnownFolder_GetShellItem                5 int,var,sptr
#comfunc global IKnownFolder_GetPath                     6 int,var
#comfunc global IKnownFolder_SetPath                     7 int,wstr
#comfunc global IKnownFolder_GetIDList                   8 int,var
#comfunc global IKnownFolder_GetFolderType               9 var
#comfunc global IKnownFolder_GetRedirectionCapabilities  10 var
#comfunc global IKnownFolder_GetFolderDefinition         11 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。