IMbnInterfaceEvents
COM公式ドキュメント
このインターフェイスは、非同期の IMbnInterface メソッド呼び出しや、デバイスの状態変化を処理するために使用される通知インターフェイスです。
解説(Remarks)
通知を登録する手順は次のとおりです。
- IMbnInterfaceManager オブジェクトに対して QueryInterface を呼び出して、IConnectionPointContainer インターフェイスを取得します。
- 返されたインターフェイスに対して FindConnectionPoint を呼び出し、riid に IID_IMbnInterfaceEvents を渡します。
- 返された接続ポイントに対して Advise を呼び出し、IMbnInterfaceEvents を実装するオブジェクトの IUnknown インターフェイスへのポインターを pUnk に渡します。
COM 通知を登録するコード例については、COM Connection Points の記事の Client セクションを参照してください。
メソッド 8
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
この通知メソッドは、インターフェイスの機能情報が利用可能になったことを示すために、モバイルブロードバンドサービスによって呼び出されます。
| newInterface | IMbnInterface* | in | 機能情報が利用可能になった IMbnInterface。 |
戻り値
このメソッドは S_OK を返す必要があります。
解説(Remarks)
アプリケーションは、渡された IMbnInterface の GetInterfaceCapability メソッドを実行して、利用可能な機能情報を取得できます。インターフェイス機能の一覧については、MBN_INTERFACE_CAPS を参照してください。
この通知メソッドは、デバイスの加入者情報が変更されたことを示すために、モバイルブロードバンドサービスによって呼び出されます。
| newInterface | IMbnInterface* | in | 加入者情報が変更されたデバイスを表す IMbnInterface。 |
戻り値
このメソッドは S_OK を返す必要があります。
解説(Remarks)
アプリケーションは、渡された IMbnInterface の GetSubscriberInformation メソッドを呼び出して、新しい加入者情報を取得できます。
この通知メソッドは、インターフェイスのレディ状態の変化を示すために、モバイルブロードバンドサービスによって呼び出されます。
| newInterface | IMbnInterface* | in | レディ状態が変更されたモバイルブロードバンドデバイスを表す IMbnInterface。 |
戻り値
このメソッドは S_OK を返す必要があります。
解説(Remarks)
アプリケーションは、渡された IMbnInterface の GetReadyState メソッドを呼び出して、デバイスの最新のレディ状態を取得できます。レディ状態の一覧については、MBN_READY_STATE を参照してください。
この通知メソッドは、緊急モードが変更されたことを示すために、モバイルブロードバンドサービスによって呼び出されます。
| newInterface | IMbnInterface* | in | 緊急モードが変更されたデバイスを表す IMbnInterface。 |
戻り値
このメソッドは S_OK を返す必要があります。
解説(Remarks)
アプリケーションは、渡された IMbnInterface の InEmergencyMode メソッドを呼び出して、デバイスの新しい緊急モードを取得できます。
この通知メソッドは、デバイスのホームプロバイダー情報が利用可能になったことを示すために、モバイルブロードバンドサービスによって呼び出されます。
| newInterface | IMbnInterface* | in | ホームプロバイダー情報が利用可能になったデバイスを表す IMbnInterface。 |
戻り値
このメソッドは S_OK を返す必要があります。
解説(Remarks)
アプリケーションは、渡された IMbnInterface の GetHomeProvider メソッドを呼び出して、利用可能なホームプロバイダー情報を取得できます。
この通知メソッドは、デバイスの優先プロバイダーリストの変化を示すために、モバイルブロードバンドサービスによって呼び出されます。
| newInterface | IMbnInterface* | in | 優先プロバイダーリストが変更されたモバイルブロードバンドデバイスを表す IMbnInterface。 |
戻り値
このメソッドは S_OK を返す必要があります。
解説(Remarks)
場合によっては、デバイスの優先プロバイダーリストが、SMS や OTA (Over The Air) 更新によってネットワークから更新されることがあります。モバイルブロードバンドサービスは、優先プロバイダーリストに変更があった場合、このメソッドを呼び出してアプリケーションに通知します。アプリケーションは、渡された IMbnInterface の GetPreferredProviders メソッドを呼び出して、更新された優先プロバイダーリストを取得できます。
IMbnInterface の SetPreferredProviders メソッドの呼び出しによって優先プロバイダーリストが変更された場合、この通知は呼び出されません。
この通知メソッドは、SetPreferredProviders 操作の完了を示すために、モバイルブロードバンドサービスによって呼び出されます。
| newInterface | IMbnInterface* | in | この操作が実行されたデバイスを表す IMbnInterface。 | ||||||||||||
| requestID | DWORD | in | この非同期操作に対してモバイルブロードバンドサービスによって割り当てられたリクエスト ID。 | ||||||||||||
| status | HRESULT | in | 操作の完了ステータス。 このステータスの有効な値を次の表に示します。
|
戻り値
このメソッドは S_OK を返す必要があります。
解説(Remarks)
操作が正常に完了した場合、つまり status が S_OK の場合、アプリケーションは、渡された IMbnInterface の GetPreferredProviders メソッドを呼び出して、更新された優先プロバイダーリストを取得できます。
複数のアプリケーションが通知を登録している場合、このメソッドは登録されているすべてのアプリケーションで呼び出されます。つまり、更新操作を開始していないアプリケーションも通知を受け取ります。
IMbnInterface の SetPreferredProviders メソッドの呼び出しによって優先プロバイダーリストが変更された場合、IMbnInterfaceEvents の OnPreferredProvidersChange メソッドは呼び出されません。
この通知メソッドは、ネットワークスキャンの完了を示すために、モバイルブロードバンドサービスによって呼び出されます。
| newInterface | IMbnInterface* | in | この操作が実行されたデバイスを表す IMbnInterface。 |
| requestID | DWORD | in | この通知に対してモバイルブロードバンドサービスによって割り当てられたリクエスト ID。 |
| status | HRESULT | in | 操作の完了ステータス。 呼び出し側のアプリケーションは、次のいずれかの値を想定できます。 操作は成功しました。 デバイスの無線がオフになっているため、可視ネットワークリストを取得できません。アプリケーションは、無線がオンになった通知を受け取ったときに、ネットワークスキャンリクエストを発行できます。 E_MBN_DEVICE_BUSY デバイスがビジー状態のため、現在ネットワークスキャン操作を実行できません。これは、データ接続が確立されているときにネットワークスキャン操作をサポートしないデバイスによって返されます。 E_MBN_ALREADY_ACTIVE ネットワークスキャン操作はすでに進行中です。 |
戻り値
このメソッドは S_OK を返す必要があります。
解説(Remarks)
操作が正常に完了した場合、つまり status が S_OK の場合、モバイルブロードバンドサービスはキャッシュされた可視プロバイダーリストの更新に成功しています。その後、アプリケーションは、渡された IMbnInterface の GetVisibleProviders メソッドを呼び出して、可視プロバイダーリストを取得できます。
複数のアプリケーションが通知を登録している場合、このメソッドは登録されているすべてのアプリケーションで呼び出されます。つまり、更新操作を開始していないアプリケーションも通知を受け取ります。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IMbnInterfaceEvents "{DCBBBAB6-2002-4BBB-AAEE-338E368AF6FA}"
#usecom global IMbnInterfaceEvents IID_IMbnInterfaceEvents "{}"
#comfunc global IMbnInterfaceEvents_OnInterfaceCapabilityAvailable 3 sptr
#comfunc global IMbnInterfaceEvents_OnSubscriberInformationChange 4 sptr
#comfunc global IMbnInterfaceEvents_OnReadyStateChange 5 sptr
#comfunc global IMbnInterfaceEvents_OnEmergencyModeChange 6 sptr
#comfunc global IMbnInterfaceEvents_OnHomeProviderAvailable 7 sptr
#comfunc global IMbnInterfaceEvents_OnPreferredProvidersChange 8 sptr
#comfunc global IMbnInterfaceEvents_OnSetPreferredProvidersComplete 9 sptr,int,int
#comfunc global IMbnInterfaceEvents_OnScanNetworkComplete 10 sptr,int,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。