IUPnPAddressFamilyControl
COM公式ドキュメント
IUPnPAddressFamilyControl インターフェイスは、Device Finder オブジェクトのアドレスファミリフラグにアクセスします。
メソッド 2
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
SetAddressFamily メソッドは、Device Finder オブジェクトのアドレスファミリフラグを設定します。Device Finder オブジェクトは、このフラグを使用して検出されたデバイスをフィルターします。
| dwFlags | INT | in | Device Finder オブジェクトが検出されたデバイスをフィルターする際に使用するアドレスファミリを指定する整数 (4 バイト値) です。 次の値が有効です。
|
戻り値
メソッドが成功した場合、戻り値は S_OK です。それ以外の場合、メソッドは WinError.h で定義されている COM エラーコードのいずれかを返します。
解説(Remarks)
フラグの設定
検索に反映させるには、アドレスファミリフラグを適切なタイミングで設定する必要があります。
- 非同期検索の場合は、IUPnPDeviceFinder::CreateAsyncFind メソッドを呼び出す前にアドレスファミリフラグを設定します。
- 同期検索の場合は、IUPnPDeviceFinder::FindByUDN メソッドまたは IUPnPDeviceFinder::FindByType メソッドを呼び出す前にアドレスファミリフラグを設定します。
検出されたデバイスのフィルター
シナリオ 1: コントロールポイントアプリケーションがアドレスファミリフラグを UPNP_ADDRESSFAMILY_IPV4 に設定し、検索を開始した場合。
- Device Finder が IPv6 アドレスを持つデバイスを検出しても、そのデバイスをアプリケーションに通知しません。同じデバイスが後から IPv4 アドレスを取得した場合、Device Finder はそのデバイスをアプリケーションに通知し、IPv4 アドレスを提供します。
- Device Finder が IPv4 アドレスを持つデバイスを検出した場合、そのデバイスをアプリケーションに通知し、IPv4 アドレスを提供します。同じデバイスが後から IPv6 アドレスを取得しても、Device Finder はその追加アドレスをアプリケーションに通知しません。
- Device Finder が IPv4 と IPv6 の両方のアドレスを持つデバイスを検出した場合、そのデバイスをアプリケーションに通知しますが、提供するのは IPv4 アドレスのみです。
- アプリケーションが認識しているデバイスがアドレスの変更を通知した場合、Device Finder は新しいアドレスが IPv4 アドレスである場合にのみ、その変更をアプリケーションに通知します。
- アプリケーションが認識しているデバイスが IPv4 と IPv6 の両方のアドレスを持ち、Device Finder がそのデバイスの IPv6 アドレスから bye-bye メッセージを受信した場合、アプリケーションが IPv4 アドレスしか認識していなくても、Device Finder はアプリケーションに通知します。言い換えると、アプリケーションが認識しているデバイスがネットワークから離脱した場合、Device Finder はデバイスのアドレスに関係なくアプリケーションに通知します。
シナリオ 2: アプリケーションがアドレスファミリフラグを UPNP_ADDRESSFAMILY_IPV6 に設定し、検索を開始した場合。
- シナリオ 1 で説明したものと同様の規則が、反対のアドレスファミリに対して適用されます。
シナリオ 3: アプリケーションがアドレスファミリフラグを UPNP_ADDRESSFAMILY_BOTH に設定し、検索を開始した場合。
- Device Finder が IPv4 アドレスまたは IPv6 アドレスのいずれかを持つデバイスを検出した場合、そのデバイスをアプリケーションに通知し、そのアドレスを提供します。同じデバイスが後から異なるアドレスファミリのアドレスを取得しても、Device Finder はその追加アドレスをアプリケーションに通知しません。
- Device Finder が IPv4 と IPv6 の両方のアドレスを持つデバイスを検出した場合、そのデバイスをアプリケーションに通知しますが、提供するのはランダムに選択されたいずれか一方のアドレスのみです。
- アプリケーションが認識しているデバイスがアドレスの変更を通知した場合、Device Finder はその変更をアプリケーションに通知します。
- アプリケーションが認識しているデバイスがネットワークから離脱した場合、Device Finder はアプリケーションに通知します。
GetAddressFamily メソッドは、Device Finder オブジェクトのアドレスファミリフラグの現在の値を取得します。
| pdwFlags | INT* | out | アドレスファミリを示す整数 (4 バイト値) へのポインターです。 次の値が有効です。
|
戻り値
メソッドが成功した場合、戻り値は S_OK です。それ以外の場合、メソッドは WinError.h で定義されている COM エラーコードのいずれかを返します。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IUPnPAddressFamilyControl "{E3BF6178-694E-459F-A5A6-191EA0FFA1C7}" #usecom global IUPnPAddressFamilyControl IID_IUPnPAddressFamilyControl "{}" #comfunc global IUPnPAddressFamilyControl_SetAddressFamily 3 int #comfunc global IUPnPAddressFamilyControl_GetAddressFamily 4 var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IUPnPAddressFamilyControl "{E3BF6178-694E-459F-A5A6-191EA0FFA1C7}" #usecom global IUPnPAddressFamilyControl IID_IUPnPAddressFamilyControl "{}" #comfunc global IUPnPAddressFamilyControl_SetAddressFamily 3 int #comfunc global IUPnPAddressFamilyControl_GetAddressFamily 4 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。