ホーム › System.Com.StructuredStorage › IPropertySetStorage

IPropertySetStorage

COM

IID0000013a-0000-0000-c000-000000000046継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IPropertySetStorage インターフェイスは、IPropertyStorage インターフェイスのインスタンスをサポートするプロパティセットストレージの作成、オープン、削除、および列挙を行います。

解説(Remarks)

メモ上記には、DocumentSummaryInformation および UserDefined プロパティセットという例外があります。このプロパティセットは、単一の基になるストリーム内に 2 つのプロパティセットセクションを持つ場合がある点で特殊です。このプロパティセットについては、The DocumentSummaryInformation and UserDefined Property Sets で説明されています。最初のセクションは DocumentSummaryInformation プロパティセットです。2 番目のセクションは UserDefined プロパティセットです。各セクションは一意の形式識別子 (FMTID) によって識別されます。たとえば、FMTID_DocSummaryInformation と FMTID_UserDefined プロパティセットです。これら 2 つのプロパティセットが単一のストリーム内に存在し得るという事実は、IPropertySetStorage インターフェイスの動作に影響します。

UserDefined プロパティセットを作成するために IPropertySetStorage::Create が呼び出されると、最初のセクションが自動的に作成されます。FMTID_UserDefinedProperties が作成されると、FMTID_DocSummaryInformation を作成する必要はありませんが、IPropertySetStorage::Open の呼び出しでオープンできます。最初のセクションを作成しても、2 番目のセクションが自動的に作成されることはなく、両方のセクションを同時にオープンすることはできません。

最初のセクションを削除するために IPropertySetStorage::Delete を呼び出すと、両方のセクションが削除されます。言い換えると、FMTID_DocSummaryInformation を指定して IPropertySetStorage::Delete を呼び出すと、そのセクションと FMTID_UserDefinedProperties セクションの両方が削除されます。ただし、2 番目のセクションを削除しても、最初のセクションが自動的に削除されることはありません。

プロパティセットを列挙するために IPropertySetStorage::Enum を使用する場合、UserDefined プロパティセットは列挙されません。

メソッド 4

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

vtbl 3 HRESULT Create(GUID* rfmtid, GUID* pclsid, DWORD grfFlags, DWORD grfMode, IPropertyStorage** ppprstg)

プロパティセットストレージオブジェクト内に新しいプロパティセットを作成してオープンします。

rfmtid	GUID*	in	作成するプロパティセットの FMTID。Platform SDK で周知かつ事前定義されている FMTID については、 Predefined Property Set Format Identifiers を参照してください。
pclsid	GUID*	in	このプロパティセットの初期クラス識別子 CLSID へのポインター。NULL を指定でき、その場合はすべてゼロに設定されます。CLSID は、プロパティ値を表示する、またはプロパティ値へのプログラムによるアクセスを提供する、あるいはその両方を行うクラスの CLSID です。そのようなクラスが存在しない場合は、FMTID を使用することが推奨されます。
grfFlags	DWORD	in	PROPSETFLAG Constants の値。
grfMode	DWORD	in	新しく作成されるプロパティセットをオープンする際のアクセスモード。STGM_Constants の特定の値から取得します。詳細は後述の「解説」セクションで説明します。
ppprstg	IPropertyStorage**	out	IPropertyStorage インターフェイスポインターを受け取る出力変数へのポインター。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED に加えて、以下をサポートします。

解説(Remarks)

IPropertySetStorage::Create は、このプロパティセットストレージオブジェクトに含まれる、新しいプロパティセットサブオブジェクト ( IPropertyStorage インターフェイスをサポートする) を作成してオープンします。プロパティセットには、コードページとロケール ID のプロパティが自動的に含まれます。これらはそれぞれ Unicode と現在のユーザーの既定値に設定されます。

grfFlags パラメーターは、PROPSETFLAG Constants から取得した値の組み合わせです。この列挙型の PROPSETFLAG_ANSI 値を使用すると、コードページは Unicode ではなく現在のシステム既定値に設定されます。

grfMode パラメーターは、新しく作成されるセットをオープンする際のアクセスモードを指定します。このパラメーターの値は、 IPropertySetStorage::Open の grfMode パラメーターと同じですが、次の表に示す値が追加されます。

値	意味
STGM_FAILIFTHERE	指定した fmtid パラメーターを持つ別のプロパティセットが存在する場合、呼び出しは失敗します。これが既定の動作です。つまり、STGM_CREATE が指定されない限り、STGM_FAILIFTHERE が暗黙的に指定されます。
STGM_CREATE	指定した fmtid パラメーターを持つ別のプロパティセットが既に存在する場合、それは削除され、この新しいものに置き換えられます。

作成されるプロパティセットは、既定では単純 (simple) ですが、呼び出し元は grfFlags パラメーターに PROPSETFLAG_NONSIMPLE 値を指定することで、非単純 (nonsimple) なプロパティセットを要求できます。単純および非単純のプロパティセットの詳細については、 Storage and Stream Objects for a Property Set を参照してください。

このメソッドは、基になる IStorage::CreateStream (単純なプロパティセットの場合) または IStorage::CreateStorage (非単純なプロパティセットの場合) の制約を受けます。たとえば、 IPropertySetStorage-Compound File Implementation を使用する場合は、IPropertySetStorage::Create の grfMode パラメーターに STGM_SHARE_EXCLUSIVE を指定します。逆に、 IPropertySetStorage-Stand-alone Implementation を使用する場合、IPropertySetStorage::Create は、呼び出し元が指定した IStorage に適用される制約を受けます。

vtbl 4 HRESULT Open(GUID* rfmtid, DWORD grfMode, IPropertyStorage** ppprstg)

プロパティセットストレージオブジェクトに含まれるプロパティセットをオープンします。

rfmtid	GUID*	in	オープンするプロパティセットの形式識別子 (FMTID)。Platform SDK で周知かつ事前定義されている FMTID の詳細については、 Predefined Property Set Format Identifiers を参照してください。
grfMode	DWORD	in	新しく作成されるプロパティセットをオープンする際のアクセスモード。これらのフラグは STGM Constants から取得します。使用できるフラグと、このメソッドのコンテキストにおけるそれらの意味は、後述の「解説」セクションで説明します。
ppprstg	IPropertyStorage**	out	要求されたプロパティストレージサブオブジェクトへのインターフェイスポインターを受け取る IPropertyStorage ポインター変数へのポインター。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED に加えて、以下をサポートします。

解説(Remarks)

プロパティセットをオープンするモードは、grfMode パラメーターで指定します。これらのフラグは STGM Constants から取得しますが、このメソッドの場合、有効な値とその意味は次のとおりです (これらのフラグ値の特定の組み合わせのみが有効です)。

値	意味
STGM_DIRECT	トランザクションの入れ子を追加せずにプロパティセットをオープンします。これが既定です (STGM_DIRECT と STGM_TRANSACTED のどちらも指定されない場合の動作)。
STGM_TRANSACTED	トランザクションの入れ子を追加して (このプロパティセットストレージオブジェクトに対するトランザクションがある場合は、それに加えて) プロパティセットをオープンします。トランザクションモードは非単純なプロパティセットでのみ使用できます。プロパティセットの変更は、このプロパティセットストレージに対するトランザクションから見えるようになる前に、IPropertyStorage::Commit の呼び出しでコミットする必要があります。
STGM_READ	読み取りアクセスでプロパティセットをオープンします。プロパティセットストレージに対する読み取りアクセス許可が必要です。
STGM_WRITE	書き込みアクセスでプロパティセットをオープンします。 IPropertyStorage のすべての実装がこのモードをサポートしているわけではありません。
STGM_READWRITE	読み取りおよび書き込みアクセスでプロパティセットをオープンします。このフラグは STGM_READ 値と STGM_WRITE 値のバイナリ OR ではないことに注意してください。
STGM_SHARE_DENY_NONE	このプロパティセットストレージからの以降のプロパティセットのオープンで、読み取りまたは書き込みアクセスが拒否されません。(すべての実装で使用できるわけではありません。)
STGM_SHARE_DENY_READ	このプロパティセットストレージからの以降のプロパティセットのオープンで、読み取りアクセスが拒否されます。すべての実装で使用できるわけではありません。
STGM_SHARE_DENY_WRITE	このプロパティセットストレージからの以降のプロパティセットのオープンで、書き込みアクセスが拒否されます。この値は通常、複数のユーザーがオープンしたオブジェクトの不要なコピーが作成されるのを防ぐために、トランザクションモードで使用されます。つまり、STGM_TRANSACTED が指定されていてもこの値が指定されていない場合、以降のオープンの有無にかかわらずスナップショットが作成されます。したがって、この値を指定することでパフォーマンスを向上させることができます。すべての実装で使用できるわけではありません。
STGM_SHARE_EXCLUSIVE	このプロパティセットストレージからの以降のプロパティセットのオープンはできません。この値は STGM_SHARE_DENY_READ 要素と STGM_SHARE_DENY_WRITE 要素の単純なバイナリ OR ではないことに注意してください。

このメソッドは、基になる IStorage::OpenStream (単純なプロパティセットの場合) または IStorage::OpenStorage (非単純なプロパティセットの場合) の制約を受けます。単純および非単純のプロパティセットの詳細については、 Storage and Stream Objects for a Property Set を参照してください。たとえば、 IPropertySetStorage-Compound File Implementation を使用する場合は、IPropertySetStorage::Open の grfMode パラメーターに STGM_SHARE_EXCLUSIVE を指定する必要があります。逆に、 IPropertySetStorage-Stand-alone Implementation を使用する場合、IPropertySetStorage::Open は、呼び出し元が指定した IStorage に適用される制約を受けます。

vtbl 5 HRESULT Delete(GUID* rfmtid)

Delete メソッドは、プロパティセットストレージオブジェクトに含まれるプロパティセットの 1 つを削除します。

rfmtid

GUID*

削除するプロパティセットの FMTID。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED に加えて、以下をサポートします。

解説(Remarks)

IPropertySetStorage::Delete は、FMTID で指定されたプロパティセットを削除します。存在しないプロパティセットを指定すると、エラーが返されます。(ストレージ値またはストリーム値のプロパティのいずれかを通じて) オープンされているサブストレージおよびストリームは、復帰 (reverted) 状態になります。

vtbl 6 HRESULT Enum(IEnumSTATPROPSETSTG** ppenum)

Enum メソッドは、このプロパティセットストレージに格納されているプロパティセットに関する情報を含む列挙子オブジェクトを作成します。このメソッドは、戻り時に、列挙子オブジェクトの IEnumSTATPROPSETSTG ポインターへのポインターを提供します。

ppenum

IEnumSTATPROPSETSTG**

out

新しく作成された列挙子オブジェクトへのインターフェイスポインターを受け取る IEnumSTATPROPSETSTG ポインター変数へのポインター。

戻り値

このメソッドは、これらの値のいずれかを返すことができます。

解説(Remarks)

IPropertySetStorage::Enum は、 STATPROPSETSTG 構造体を反復処理するために使用できる列挙子オブジェクトを作成します。これらは、 IPropertySetStorage によって管理されているプロパティセットに関する情報を提供することがあります。このメソッドは、戻り時に、この列挙子オブジェクトの IEnumSTATPROPSETSTG インターフェイスへのポインターを提供します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IPropertySetStorage "{0000013A-0000-0000-C000-000000000046}"
#usecom global IPropertySetStorage IID_IPropertySetStorage "{}"
#comfunc global IPropertySetStorage_Create  3 var,var,int,int,sptr
#comfunc global IPropertySetStorage_Open    4 var,int,sptr
#comfunc global IPropertySetStorage_Delete  5 var
#comfunc global IPropertySetStorage_Enum    6 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IPropertySetStorage "{0000013A-0000-0000-C000-000000000046}"
#usecom global IPropertySetStorage IID_IPropertySetStorage "{}"
#comfunc global IPropertySetStorage_Create  3 sptr,sptr,int,int,sptr
#comfunc global IPropertySetStorage_Open    4 sptr,int,sptr
#comfunc global IPropertySetStorage_Delete  5 sptr
#comfunc global IPropertySetStorage_Enum    6 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。