ホーム › System.Com › IConnectionPoint

IConnectionPoint

COM

📘 Microsoft Learn (日本語) · English

IIDb196b286-bab4-101a-b69c-00aa00341d07継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

接続可能オブジェクトの接続ポイントをサポートします。(IConnectionPoint)

解説(Remarks)

接続可能オブジェクトは、次の機能をサポートします。

イベントセットなどのアウトゴーイングインターフェイス
アウトゴーイングインターフェイスの IID を列挙する機能
それらのアウトゴーイング IID について、シンクをオブジェクトに接続および切断する機能
特定のアウトゴーイングインターフェイスに存在する接続を列挙する機能

メソッド 5

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

vtbl 3 HRESULT GetConnectionInterface(GUID* pIID)

この接続ポイントが管理するアウトゴーイングインターフェイスの IID を取得します。

pIID

GUID*

out

この接続ポイントが管理するアウトゴーイングインターフェイスの識別子へのポインター。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED のほか、次の値を返すことがあります。

戻り値コード	説明
S_OK	呼び出し元の変数 pIID に、この接続ポイントが管理するアウトゴーイングインターフェイスの識別子が格納されています。
E_POINTER	pIID のアドレスが無効です。たとえば、NULL である可能性があります。

解説(Remarks)

IEnumConnectionPoints インターフェイスを使用すると、クライアントは IConnectionPoint インターフェイスへのポインターを取得できます。そのポインターと GetConnectionInterface メソッドを使用して、クライアントは列挙された各接続ポイントの IID を判別できます。このメソッドが返す IID は、IConnectionPointContainer::FindConnectionPoint を通じて呼び出し元が同じ接続ポイントにアクセスできるようにする必要があります。

実装者への注意事項

このメソッドは、すべての接続ポイントで実装する必要があります。E_NOTIMPL は許容される戻り値ではありません。

vtbl 4 HRESULT GetConnectionPointContainer(IConnectionPointContainer** ppCPC)

親の接続可能オブジェクトの IConnectionPointContainer インターフェイスポインターを取得します。

ppCPC

IConnectionPointContainer**

out

IConnectionPointContainer インターフェイスポインターへのポインター。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED のほか、次の値を返すことがあります。

戻り値コード	説明
S_OK	IConnectionPointContainer ポインターが正常に返されました。
E_POINTER	ppCPC の値が有効なインターフェイスポインターではありません。たとえば、NULL である可能性があります。

解説(Remarks)

呼び出し元への注意事項

このメソッドは AddRef を呼び出します。呼び出し元は、使用が終わったらこのポインターを解放するために Release を呼び出す責任があります。

実装者への注意事項

このメソッドは、返す前に AddRef を呼び出す必要があります。

このメソッドは、すべての接続ポイントで実装する必要があります。E_NOTIMPL は許容される戻り値ではありません。

vtbl 5 HRESULT Advise(IUnknown* pUnkSink, DWORD* pdwCookie)

接続ポイントオブジェクトとクライアントのシンクの間に接続を確立します。

pUnkSink	IUnknown*	in	クライアントのアドバイズシンク上の IUnknown インターフェイスへのポインター。クライアントのシンクは、接続ポイントからのアウトゴーイング呼び出しを受け取ります。
pdwCookie	DWORD*	out	この接続を一意に識別する、返されるトークンへのポインター。呼び出し元は、後でこのトークンを IConnectionPoint::Unadvise メソッドに渡すことで、接続を削除するために使用します。接続が正常に確立されなかった場合、この値はゼロになります。

戻り値

このメソッドは、標準の戻り値 E_OUTOFMEMORY および E_UNEXPECTED のほか、次の値を返すことがあります。

戻り値コード	説明
S_OK	接続が確立され、*pdwCookie に接続トークンが格納されています。
E_POINTER	pUnkSink または pdwCookie の値が無効です。たとえば、いずれかのポインターが NULL である可能性があります。
CONNECT_E_ADVISELIMIT	接続ポイントは既に接続数の上限に達しており、これ以上受け入れることができません。
CONNECT_E_CANNOTCONNECT	シンクが、この接続ポイントで必要とされるインターフェイスをサポートしていません。

解説(Remarks)

Advise は、接続ポイントと、pUnkSink で識別される呼び出し元のシンクとの間に接続を確立します。

接続ポイントは、イベント発生時に呼び出す正しいアウトゴーイングインターフェイスポインターを取得するために、接続ポイントが管理するアウトゴーイングインターフェイスの IID を指定して QueryInterface を呼び出す必要があります。この IID を IConnectionPointContainer::FindConnectionPoint メソッドに渡すと、この同じ接続ポイントへのインターフェイスポインターが返されます。

実装者への注意事項

接続ポイントは、正しいアウトゴーイングインターフェイスを求めて pUnkSink ポインターに対してクエリを行う必要があります。このクエリが失敗した場合、このメソッドは CONNECT_E_CANNOTCONNECT を返す必要があります。

pdwCookie の値は、特定の接続ポイントインスタンスへの各接続ごとに一意である必要があります。

vtbl 6 HRESULT Unadvise(DWORD dwCookie)

接続ポイントオブジェクトとクライアントのシンクの間に以前確立されたアドバイザリ接続を終了します。

dwCookie

DWORD

以前に IConnectionPoint::Advise から返された接続トークン。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED のほか、次の値を返すことがあります。

戻り値コード	説明
S_OK	接続が正常に終了しました。
E_POINTER	dwCookie の値が有効な接続を表していません。

解説(Remarks)

アドバイザリ接続が終了すると、接続ポイントは、IConnectionPoint::Advise メソッドの実行中に接続のために保存されたポインターに対して Release メソッドを呼び出します。この Release は、接続ポイントがアドバイザリシンクの QueryInterface を呼び出した際に、Advise の実行中に行われた AddRef を打ち消します。

vtbl 7 HRESULT EnumConnections(IEnumConnections** ppEnum)

この接続ポイントの現在の接続を反復処理するための列挙子オブジェクトを作成します。

ppEnum

IEnumConnections**

out

新しく作成された列挙子を受け取る IEnumConnections インターフェイスポインターへのポインター。

戻り値

このメソッドは、標準の戻り値 E_OUTOFMEMORY および E_UNEXPECTED のほか、次の値を返すことがあります。

戻り値コード	説明
S_OK	列挙子オブジェクトが正常に作成されました。
E_POINTER	ppEnum のアドレスが無効です。たとえば、NULL である可能性があります。
E_NOTIMPL	接続ポイントは列挙をサポートしていません。

解説(Remarks)

呼び出し元は、列挙子が不要になったときに Release を呼び出す責任があります。

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