ホーム › UI.Shell.PropertiesSystem › IPropertyStore

IPropertyStore

COM

📘 Microsoft Learn (日本語) · English

IID886d8eeb-8cf2-4446-8d02-cdba1dbdcf99継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

このインターフェイスは、プロパティ値を列挙および操作するために使用されるメソッドを公開します。

メソッド 5

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

vtbl 3 HRESULT GetCount(DWORD* cProps)

このメソッドは、ファイルに付加されているプロパティの数を返します。

cProps

DWORD*

out

プロパティ数を示す値へのポインターです。

戻り値

IpropertyStore::GetCount メソッドは、呼び出しが成功した場合、ファイルにプロパティが付加されていない場合でも S_OK の値を返します。それ以外に返されるコードはエラーコードです。

解説(Remarks)

IPropertyStore は、IPropertyStore::GetCount および IPropertyStore::GetAt メソッドを通じて、プロパティキーの配列に対する抽象化を提供します。この配列内のプロパティキーは、IPropertyStore によって現在格納されているプロパティを表します。

GetCount が成功すると、cProps が指す値は配列内のプロパティキーの数になります。呼び出し元は、cProps より小さい iProp の値に対して IPropertyStore::GetAt の呼び出しが成功することを期待できます。

E_OUTOFMEMORY などの失敗が発生した場合は、cProps を 0 に設定してください。エラーはプロパティストアの作成時または初期化時に検出されることが望ましいです。

vtbl 4 HRESULT GetAt(DWORD iProp, PROPERTYKEY* pkey)

項目のプロパティ配列からプロパティキーを取得します。

iProp	DWORD	in	PROPERTYKEY 構造体の配列内におけるプロパティキーのインデックスです。これは 0 から始まるインデックスです。
pkey	PROPERTYKEY*	out	TBD

戻り値

IPropertyStore::GetAt メソッドは、成功した場合に S_OK の値を返します。それ以外に返されるコードは、すべてエラーコードとみなす必要があります。

解説(Remarks)

なし

vtbl 5 HRESULT GetValue(PROPERTYKEY* key, PROPVARIANT* pv)

このメソッドは、特定のプロパティのデータを取得します。

key	PROPERTYKEY*	in	TBD
pv	PROPVARIANT*	out	`IPropertyStore::GetValue` メソッドが正常に返された後、このパラメーターはプロパティに関するデータを含む PROPVARIANT 構造体を指します。

戻り値

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

INPLACE_S_TRUNCATED は、返された PROPVARIANT がより正規化された形式に変換されたことを示すために返されます。たとえば、文字列値の先頭または末尾の空白を削除する場合に行われます。戻り値の確認には SUCCEEDED マクロを使用する必要があり、このマクロは INPLACE_S_TRUNCATED を成功コードとして扱います。SUCCEEDED マクロは Winerror.h ファイルで定義されています。

解説(Remarks)

key で参照される PROPERTYKEY がプロパティストアに存在しない場合、このメソッドは S_OK を返し、pv が指す構造体の vt メンバーは VT_EMPTY に設定されます。

vtbl 6 HRESULT SetValue(PROPERTYKEY* key, PROPVARIANT* propvar)

このメソッドは、プロパティ値を設定するか、既存の値を置換または削除します。

key	PROPERTYKEY*	in	TBD
propvar	PROPVARIANT*	in	TBD

戻り値

IPropertyStore::SetValue メソッドは、次のいずれかを返すことができます。

リターンコード	説明
S_OK	プロパティの変更に成功しました。
INPLACE_S_TRUNCATED	値は設定されましたが、切り詰められました。
STG_E_ACCESSDENIED	これはエラーコードです。プロパティストアが読み取り専用であったため、メソッドは値を設定できませんでした。

解説(Remarks)

IPropertyStore::SetValue は、現在のプロパティストアインスタンスにのみ影響します。プロパティハンドラーは、プロパティの変更をメモリ内のデータ構造に蓄積することで IPropertyStore::SetValue を実装します。プロパティの変更がストリームに書き込まれるのは、IPropertyStore::Commit が呼び出されたときのみです。

読み取り専用のプロパティストアに対して IPropertyStore::Commit が呼び出された場合、プロパティハンドラーはこれを判別して STG_E_ACCESSDENIED を返します。

SetValue の結果として値が追加または削除された場合、IPropertyStore::GetCount および IPropertyStore::GetAt による後続の列挙にはその変更が反映され、IPropertyStore::SetValue の後続の呼び出しには変更後の値が反映されます。

新しいプロパティの追加

key が指すプロパティ値がストアに存在しない場合、IPropertyStore::SetValue はその値をストアに追加します。

既存のプロパティ値の置換

key が指すプロパティ値がストアに既に存在する場合、格納されている値が置き換えられます。

既存のプロパティの削除

プロパティストアから値を削除するには、pv が指す構造体の vt メンバーを VT_EMPTY に設定します。その値が存在しない場合は何も行わず、メソッドは S_OK を返します。

vtbl 7 HRESULT Commit()

変更が行われた後、このメソッドはその変更を保存します。

戻り値

IPropertyStore::Commit メソッドは、次のいずれかを返します。

リターンコード	説明
S_OK	すべてのプロパティ変更がストリームまたはパスに正常に書き込まれました。これには、メソッドが呼び出された時点で保留中の変更がなく、何も書き込まれなかった場合も含まれます。
STG_E_ACCESSDENIED	ストリームまたはファイルが読み取り専用です。メソッドは値を設定できませんでした。
E_FAIL	一部またはすべての変更をファイルに書き込めませんでした。E_FAIL の代わりに、より説明的な別のエラーを使用することもできます。

解説(Remarks)

Commit メソッドは、返る前に、メソッドで使用するために初期化されたファイルストリームまたはパスを解放します。そのため、Commit が返った後は、IPropertyStore のどのメソッドも成功しません。その時点で、それらは E_FAIL を返します。

プロパティハンドラーは、Commit の処理が異常終了した場合やエラーが発生した場合でも、プロパティの変更が有効な出力先ファイルになるように保証する必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IPropertyStore "{886D8EEB-8CF2-4446-8D02-CDBA1DBDCF99}"
#usecom global IPropertyStore IID_IPropertyStore "{E4796550-DF61-448B-9193-13FC1341B163}"
#comfunc global IPropertyStore_GetCount  3 var
#comfunc global IPropertyStore_GetAt     4 int,var
#comfunc global IPropertyStore_GetValue  5 var,var
#comfunc global IPropertyStore_SetValue  6 var,var
#comfunc global IPropertyStore_Commit    7
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IPropertyStore "{886D8EEB-8CF2-4446-8D02-CDBA1DBDCF99}"
#usecom global IPropertyStore IID_IPropertyStore "{E4796550-DF61-448B-9193-13FC1341B163}"
#comfunc global IPropertyStore_GetCount  3 sptr
#comfunc global IPropertyStore_GetAt     4 int,sptr
#comfunc global IPropertyStore_GetValue  5 sptr,sptr
#comfunc global IPropertyStore_SetValue  6 sptr,sptr
#comfunc global IPropertyStore_Commit    7
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。