ホーム › System.Com › IPersist

IPersist

COM

📘 Microsoft Learn (日本語) · English

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

公式ドキュメント

システムに永続的に格納できるオブジェクトの CLSID を提供します。マーシャリングの既定の実装で使用される際に、クライアントプロセス内でどのオブジェクトハンドラーを使用するかをオブジェクトが指定できるようにします。

メソッド 1

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

vtbl 3 HRESULT GetClassID(GUID* pClassID)

オブジェクトのクラス識別子 (CLSID) を取得します。

pClassID

GUID*

out

戻り時に CLSID を受け取る場所へのポインター。CLSID はグローバルに一意な識別子 (GUID) であり、オブジェクトのデータを操作できるコードを定義するオブジェクトクラスを一意に表します。

戻り値

メソッドが成功した場合、戻り値は S_OK です。それ以外の場合は E_FAIL です。

解説(Remarks)

GetClassID メソッドは、オブジェクトのクラス識別子 (CLSID) を取得します。この CLSID は、後続の操作でオブジェクト固有のコードを呼び出し元のコンテキストに読み込むために使用されます。

呼び出し元への注意

コンテナーアプリケーションは、別のクラスとして扱っているオブジェクトの元の CLSID を取得するためにこのメソッドを呼び出すことがあります。このような呼び出しは、ユーザーがオブジェクトの保存を必要とする編集操作を実行した場合に必要になります。コンテナーが treat-as CLSID を使用してオブジェクトを保存すると、元のアプリケーションはそのオブジェクトを編集できなくなります。通常この場合、コンテナーは必要なすべての手順を実行する OleSave ヘルパー関数を呼び出します。このため、ほとんどのコンテナーアプリケーションはこのメソッドを直接呼び出す必要はありません。

例外は、特定のオブジェクトに対してオブジェクトハンドラーを提供するコンテナーです。特に、コンテナーアプリケーションはオブジェクトの CLSID を取得し、それを使用してレジストリからクラス固有の情報を取得すべきではありません。代わりに、コンテナーは IOleObject および IDataObject インターフェイスを使用して、そのようなクラス固有の情報をオブジェクトから直接取得してください。

実装者への注意

通常、このメソッドの実装は、オブジェクトに対して単に定数の CLSID を提供します。ただし、エミュレーションをサポートするアプリケーションによってオブジェクトの TreatAs レジストリキーが設定されている場合 (つまり、オブジェクトを別のクラスのものとして扱っている場合)、GetClassID の呼び出しは TreatAs キーで指定された CLSID を提供する必要があります。エミュレーションの詳細については、CoTreatAsClass を参照してください。

オブジェクトが実行状態にある場合、既定のハンドラーは呼び出しをオブジェクト内の実装に委譲する GetClassID の実装を呼び出します。オブジェクトが実行されていない場合、既定のハンドラーは代わりに ReadClassStg 関数を呼び出して、オブジェクトのストレージに保存されている CLSID を読み取ります。

オブジェクト用のカスタムオブジェクトハンドラーを記述する場合は、このメソッドを既定のハンドラーの実装に単純に委譲するとよいでしょう (OleCreateDefaultHandler を参照)。

URL モニカーに関する注意

このメソッドは CLSID_StdURLMoniker を返します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IPersist "{0000010C-0000-0000-C000-000000000046}"
#usecom global IPersist IID_IPersist "{}"
#comfunc global IPersist_GetClassID  3 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IPersist "{0000010C-0000-0000-C000-000000000046}"
#usecom global IPersist IID_IPersist "{}"
#comfunc global IPersist_GetClassID  3 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。