Win32 API 日本語リファレンス
ホーム › Devices.Enumeration.Pnp › IUPnPDeviceFinderCallback

IUPnPDeviceFinderCallback

COM
📘 Microsoft Learn (日本語) · English
IID415a984a-88b3-49f3-92af-0508bedf0d6c継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IUPnPDeviceFinderCallback インターフェイスは、UPnP フレームワークが非同期検索の結果をアプリケーションに通知するために使用します。

メソッド 3

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

vtbl 3 HRESULT DeviceAdded(INT lFindData, IUPnPDevice* pDevice)

DeviceAdded メソッドは、デバイスがネットワークに追加されたことをアプリケーションに通知するために UPnP フレームワークによって呼び出されます。

lFindDataINTinUPnP フレームワークが結果を返している検索を指定します。lFindData の値は、 IUPnPDeviceFinder::CreateAsyncFind が呼び出し元に返した値です。
pDeviceIUPnPDevice*in新しいデバイスを含む IUPnPDevice オブジェクトへの参照です。

戻り値

UPnP フレームワークはアプリケーションが特定の値を返すことを想定していません。返された値はすべて UPnP フレームワークによって無視されます。

解説(Remarks)

デバイスがネットワークに追加されたことをアプリケーションに通知する際、UPnP フレームワークは DeviceAdded の代わりに IUPnPDeviceFinderAddCallbackWithInterface::DeviceAddedWithInterface メソッドを呼び出す場合があります。UPnP フレームワークは IUPnPDeviceFinderAddCallbackWithInterface インターフェイスが存在するかどうかを照会します。存在する場合、UPnP フレームワークは DeviceAddedWithInterface を呼び出します。それ以外の場合は DeviceAdded を呼び出します。

UPnP フレームワークは、同一のデバイスに対して 2 回以上コールバックを返すことがあります。これは、デバイスをいったんネットワークから削除して再度追加することなく、そのデバイスの IP アドレスが変更された場合に発生する可能性があります。この場合、アプリケーションは古いデバイスを破棄し、最後に返されたデバイスを使用してください。アプリケーションは UDN を比較することで重複したデバイスを確認できます。

vtbl 4 HRESULT DeviceRemoved(INT lFindData, LPWSTR bstrUDN)

DeviceRemoved メソッドは、デバイスがネットワークから削除されたことをアプリケーションに通知するために UPnP フレームワークによって呼び出されます。

lFindDataINTinUPnP フレームワークが結果を返している検索を指定します。lFindData の値は、 IUPnPDeviceFinder::CreateAsyncFind が呼び出し元に返した値です。
bstrUDNLPWSTRinネットワークから削除されたデバイスの UDN を指定します。

戻り値

アプリケーションは S_OK を返してください。

解説(Remarks)

UPnP フレームワークは、同一のデバイスに対して 2 回以上コールバックを返すことがあります。アプリケーションは 2 回目以降のデバイス削除コールバックを無視して構いません。

vtbl 5 HRESULT SearchComplete(INT lFindData)

SearchComplete メソッドは、ネットワークデバイスの初回検索が完了したことをアプリケーションに通知するために UPnP フレームワークによって呼び出されます。

lFindDataINTinUPnP フレームワークが結果を返している検索を指定します。lFindData の値は、 IUPnPDeviceFinder::CreateAsyncFind が呼び出し元に返した値です。

戻り値

アプリケーションは S_OK を返してください。

解説(Remarks)

このメソッドは単に情報を提供するものです。非同期検索が終了したことを示すものではなく、初回のプローブが完了したことを示します。非同期検索は、アプリケーションが IUPnPDeviceFinder::CancelAsyncFind を呼び出すまで、ネットワークへのデバイスの追加および削除を報告し続けます。

初回の検索は完了までに長い時間がかかることがあります。SearchComplete コールバックは、最後に見つかったデバイス (つまり、検索開始時点でネットワーク上に存在するとして最後に検出されたデバイス) の記述ドキュメントが読み込まれたか、読み込みに失敗した時点で呼び出されます。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IUPnPDeviceFinderCallback "{415A984A-88B3-49F3-92AF-0508BEDF0D6C}"
#usecom global IUPnPDeviceFinderCallback IID_IUPnPDeviceFinderCallback "{}"
#comfunc global IUPnPDeviceFinderCallback_DeviceAdded     3 int,sptr
#comfunc global IUPnPDeviceFinderCallback_DeviceRemoved   4 int,wstr
#comfunc global IUPnPDeviceFinderCallback_SearchComplete  5 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。