ホーム › NetworkManagement.MobileBroadband › IMbnInterface

IMbnInterface

COM

📘 Microsoft Learn (日本語) · English

IIDdcbbbab6-2001-4bbb-aaee-338e368af6fa継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

Mobile Broadband デバイスを表します。

解説(Remarks)

IMbnInterface オブジェクトは、 IMbnInterfaceManager インターフェイスの GetInterface メソッドおよび GetInterfaces メソッドの呼び出しによって提供されます。

メソッド 11

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

vtbl 3 HRESULT get_InterfaceID(LPWSTR* InterfaceID)

インターフェイス ID。

InterfaceID

LPWSTR*

out

モバイルブロードバンドインターフェイスを一意に識別するID文字列を受け取る出力ポインタ。呼び出し側が解放する。

vtbl 4 HRESULT GetInterfaceCapability(MBN_INTERFACE_CAPS* interfaceCaps)

デバイスの機能を取得します。

interfaceCaps

MBN_INTERFACE_CAPS*

out

インターフェイスの機能を格納する MBN_INTERFACE_CAPS 構造体へのポインター。このメソッドが S_OK 以外の値を返す場合、このパラメーターは NULL になります。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。interfaceCaps には有効な値が格納されます。
E_PENDING	情報は利用できません。Mobile Broadband サービスは現在、デバイスの機能を調べています。呼び出し元アプリケーションは、IMbnInterfaceEvents の OnInterfaceCapabilityAvailable メソッドに登録することで、デバイスの機能が利用可能になったときに通知を受け取ることができます。

解説(Remarks)

GetInterfaceCapability メソッドは、セルラー技術の種類、音声通話に対するサポートの種類、使用される SIM の種類、サポートされる周波数帯、SMS サポートの有無など、インターフェイスの機能を返します。また、デバイスの製造元名、モデル、ファームウェア名も返しますが、これらは省略可能であり、一部のデバイスでは設定されないことがあります。詳細については、MBN_INTERFACE_CAPS を参照してください。

vtbl 5 HRESULT GetSubscriberInformation(IMbnSubscriberInformation** subscriberInformation)

加入者情報を取得します。

subscriberInformation

IMbnSubscriberInformation**

out

デバイスの加入者情報を格納する IMbnSubscriberInformation インターフェイスのアドレスへのポインター。このメソッドが S_OK 以外の値を返す場合、このパラメーターは NULL になります。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。subscriberInformation には有効なインターフェイスが格納されます。
E_PENDING	情報は利用できません。Mobile Broadband サービスは現在、情報を調べています。呼び出し元アプリケーションは、IMbnInterfaceEvents の OnSubscriberInformationChange メソッドに登録することで、情報が利用可能になったときに通知を受け取ることができます。

解説(Remarks)

GetSubscriberInformation メソッドは、加入者 ID、SIM の国際回線カード番号、およびこのインターフェイスに関連付けられた電話番号など、加入者に関連する情報を返します。

このメソッドがモバイルオペレーター権限を持つ Windows ストアアプリから呼び出された場合は、SimIccID プロパティで定義される SIM の国際回線カード番号のみを返します。

加入者情報として返される値の一部は、IMbnInterface の GetReadyState メソッドによって報告される準備完了状態が MBN_READY_STATE_INITIALIZED の場合にのみ設定されます。Mobile Broadband デバイスに関連付けられた加入者情報に変更があるたびに、Mobile Broadband サービスは IMbnInterfaceEvents の OnSubscriberInformationChange メソッドを呼び出して、登録済みのアプリケーションに通知します。

デバイスの準備完了状態がいったん MBN_READY_STATE_INITIALIZED になると、そのデバイスの加入者情報は変化しません。

vtbl 6 HRESULT GetReadyState(MBN_READY_STATE* readyState)

準備完了状態を取得します。

readyState

MBN_READY_STATE*

out

MBN_READY_STATE 構造体へのポインター。このメソッドが S_OK 以外の値を返す場合、このパラメーターは NULL になります。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。readyState には有効な値が格納されます。
E_PENDING	情報は利用できません。Mobile Broadband サービスは現在、準備完了状態を調べています。呼び出し元アプリケーションは、IMbnInterfaceEvents の OnReadyStateChange メソッドに登録することで、準備完了状態が利用可能になったときに通知を受け取ることができます。

解説(Remarks)

準備完了状態は、インターフェイスが正常に初期化され、接続操作を実行する準備ができているかどうかを示します。SIM ベースのデバイスの場合、SIM がデバイスによって正常に初期化されると、デバイスは準備完了になります。デバイスを接続に使用できるのは、準備完了状態が MBN_READY_STATE_INITIALIZED の場合だけです。その他のデバイス状態の詳細については、MBN_READY_STATE を参照してください。

インターフェイスの準備完了状態は、ユーザーの操作の結果として変化することがあります。たとえば、ユーザーがデバイスに SIM を挿入すると、準備完了状態は MBN_READY_STATE_SIM_NOT_INSERTED から別の準備完了状態に変化します。準備完了状態は、アプリケーションが実行するその他の操作によっても変化することがあります。たとえば、PIN が入力されると、準備完了状態は MBN_READY_STATE_DEVICE_LOCKED から別の準備完了状態に変化することがあります。アプリケーションは、インターフェイスの準備完了状態に変更があるたびにイベント通知を受け取るように登録できます。準備完了状態の変更をアプリケーションに通知するために、IMbnInterfaceEvents の OnReadyStateChange メンバーが呼び出されます。

デバイスが MBN_READY_STATE_INITIALIZED を報告した時点では、デバイスの SMS サブシステムがまだ準備できていないことがあります。呼び出し元アプリケーションは、SMS サブシステムの準備が完了したことを示す、IMbnSmsEvents の OnSmsConfigurationChange メンバーの呼び出しを待つ必要があります。

vtbl 7 HRESULT InEmergencyMode(VARIANT_BOOL* emergencyMode)

デバイスが緊急モードであるかどうかを判定します。

emergencyMode

VARIANT_BOOL*

out

デバイスが緊急モードの場合は VARIANT_TRUE を、そうでない場合は VARIANT_FALSE を指します。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。
E_PENDING	情報は利用できません。Mobile Broadband サービスは現在、この情報を調べています。呼び出し元アプリケーションは、IMbnInterfaceEvents の OnEmergencyModeChange メソッドに登録することで、データが利用可能になったときに通知を受け取ることができます。

解説(Remarks)

デバイスが何らかの理由でネットワークに登録できない場合、デバイスは緊急モードで自動的にネットワークに登録することがあります。たとえば、SIM が挿入されていない、ユーザーのサブスクリプションの有効期限が切れている、またはユーザーに対してローミングが有効になっていない場合、デバイスはネットワークに登録できません。緊急モードでは、デバイスは緊急通報番号への音声通話に限定して使用できます。

vtbl 8 HRESULT GetHomeProvider(MBN_PROVIDER* homeProvider)

ホームプロバイダーを取得します。

homeProvider

MBN_PROVIDER*

out

ホームプロバイダーを表す MBN_PROVIDER 構造体へのポインター。このメソッドが S_OK 以外の値を返す場合、このパラメーターは NULL になります。完了後、呼び出し元アプリケーションは、SysFreeString を呼び出して、MBN_PROVIDER の providerID メンバーと providerName メンバーに割り当てられたメモリを解放する必要があります。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。homeProvider には有効な値が格納されます。
E_PENDING	情報は利用できません。Mobile Broadband サービスは現在、ホームプロバイダーを取得するために調べています。呼び出し元アプリケーションは、IMbnInterfaceEvents の OnHomeProviderAvailable メソッドに登録することで、ホームプロバイダーが利用可能になったときに通知を受け取ることができます。
E_MBN_PIN_REQUIRED	この操作を行うには、デバイスに PIN の入力が必要です。
E_MBN_SIM_NOT_INSERTED	SIM が挿入されていません。
E_MBN_BAD_SIM	不正な SIM がデバイスに挿入されています。
HRESULT_FROM_WIN32(ERROR_READ_FAULT)	SIM またはデバイスのメモリから読み取ることができません。たとえば、SIM にホームプロバイダー情報がプロビジョニングされていない場合などです。

解説(Remarks)

GetHomeProvider は、デバイスのホームプロバイダー情報を返します。返される MBN_PROVIDER 構造体の dataClass フィールドは無視してください。

回復可能なエラーである E_MBN_PIN_REQUIRED、E_MBN_SIM_NOT_INSERTED、E_MBN_BAD_SIM の場合、Mobile Broadband サービスは、エラー状態が解消されたときにデバイスに対してホームプロバイダーを再度照会します。たとえば、この情報を取得するためにデバイスが PIN の入力を必要とする場合は、E_MBN_PIN_REQUIRED が返されます。アプリケーションがデバイスのロックを解除するために PIN を入力すると、Mobile Broadband サービスはデバイスからこの情報を再度取得しようとします。システムは、IMbnInterfaceEvents の OnHomeProviderAvailable メソッドを呼び出して、新しい照会の状態をアプリケーションに通知します。

登録された IMbnInterfaceEvents の OnHomeProviderAvailable メソッドは、ホームプロバイダー情報が利用可能になったとき、または新しい照会がエラーで完了したときのいずれかで呼び出されます。この関数がいったん成功を返すと、この情報は決して変化しません。

vtbl 9 HRESULT GetPreferredProviders(SAFEARRAY** preferredProviders)

優先プロバイダーの一覧を取得します。

preferredProviders

SAFEARRAY**

out

優先プロバイダーの一覧を格納する MBN_PROVIDER 構造体の配列へのポインター。このメソッドが S_OK 以外の値を返す場合、このパラメーターは NULL になります。GetPreferredProviders が S_OK を返した場合、呼び出し元アプリケーションは SafeArrayDestroy を呼び出して、割り当てられたメモリを解放する必要があります。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。preferredProviders には有効な値が格納されます。
E_PENDING	情報は利用できません。Mobile Broadband サービスは現在、優先プロバイダーの一覧を調べています。呼び出し元アプリケーションは、IMbnInterfaceEvents の OnPreferredProvidersChange メソッドに登録することで、データが利用可能になったときに通知を受け取ることができます。
E_MBN_PIN_REQUIRED	この操作を行うには、デバイスに PIN の入力が必要です。
E_MBN_SIM_NOT_INSERTED	SIM が挿入されていません。
E_MBN_BAD_SIM	不正な SIM がデバイスに挿入されています。
HRESULT_FROM_WIN32(ERROR_READ_FAULT)	SIM またはデバイスのメモリから読み取ることができません。たとえば、SIM に優先プロバイダー情報がプロビジョニングされていない場合などです。
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	デバイスはこの操作をサポートしていません。CDMA デバイスは常にこの値を返します。

解説(Remarks)

GetPreferredProviders は、インターフェイスの優先プロバイダー一覧に格納されているプロバイダーの一覧を返します。

回復可能なエラーである E_MBN_PIN_REQUIRED、E_MBN_SIM_NOT_INSERTED、E_MBN_BAD_SIM の場合、Mobile Broadband サービスは、エラー状態が解消されたときにデバイスに対してプロバイダー一覧を再度照会します。たとえば、プロバイダー一覧を取得するためにデバイスが PIN の入力を必要とする場合、GetPreferredProviders は E_MBN_PIN_REQUIRED を返します。アプリケーションがデバイスのロックを解除するために PIN を入力すると、Mobile Broadband サービスはデバイスからこの情報を再度取得しようとします。

回復可能なエラーが発生した後にオペレーティングシステムがプロバイダー一覧を取得するためにデバイスを照会している間、GetPreferredProviders はただちに E_PENDING を返します。新しい照会が完了すると、適切なコールバックメソッドを使用して呼び出し元アプリケーションに通知が送信されます。たとえば、PIN によるロック解除操作が成功した後は、IMbnPinEvents の OnEnterComplete メソッドが呼び出されます。SIM カードエラーからの回復後は、IMbnInterfaceEvents の OnReadyStateChange メソッドが呼び出されます。

Mobile Broadband サービスは、IMbnInterfaceEvents の OnPreferredProvidersChange メソッドを呼び出して、新しい照会の状態をアプリケーションに通知します。

場合によっては、デバイスの優先プロバイダー一覧は、SMS または OTA (over-the-air update) によってネットワーク経由で更新されることがあります。オペレーティングシステムは、IMbnInterfaceEvents の OnPreferredProvidersChange メソッドを呼び出して、優先プロバイダー一覧の変更をアプリケーションに通知します。

vtbl 10 HRESULT SetPreferredProviders(SAFEARRAY* preferredProviders, DWORD* requestID)

デバイスの優先プロバイダー一覧を更新します。

preferredProviders	SAFEARRAY*	in	優先プロバイダーの一覧を格納する MBN_PROVIDER 構造体の配列。
requestID	DWORD*	out	この要求に対してオペレーティングシステムが設定する要求 ID へのポインター。非同期応答には、この同じ requestID が含まれます。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。
HRESULT_FROM_WIN32(ERROR_SERVICE_NOT_ACTIVE)	このシステムで Mobile Broadband サービスが実行されていません。
E_HANDLE	インターフェイスが無効です。Mobile Broadband デバイスがシステムから取り外された可能性が高いです。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	インターフェイスが無効です。Mobile Broadband デバイスがシステムから取り外された可能性が高いです。

解説(Remarks)

SetPreferredProviders メソッドは、インターフェイスの優先プロバイダー一覧の更新を開始します。これは非同期操作であり、メソッド呼び出しはただちに戻ります。このメソッドが正常に (S_OK で) 戻った場合、オペレーティングシステムは、IMbnInterfaceEvents の OnSetPreferredProvidersComplete メソッドを呼び出して、この操作の完了状態を呼び出し元アプリケーションに通知します。

この操作が完了する前にデバイスがシステムから取り外された場合、完了通知が呼び出し元アプリケーションに届く保証はありません。

vtbl 11 HRESULT GetVisibleProviders(DWORD* age, SAFEARRAY** visibleProviders)

可視プロバイダーの一覧を取得します。

age	DWORD*	out	デバイスから可視プロバイダー一覧が最後に更新されてからの経過時間 (秒単位) へのポインター。
visibleProviders	SAFEARRAY**	out	インターフェイスのプロバイダー一覧を格納する MBN_PROVIDER 構造体の配列へのポインター。このメソッドが S_OK 以外の値を返す場合、このパラメーターは NULL になります。それ以外の場合、完了後、呼び出し元プログラムは SafeArrayDestroy を呼び出して、割り当てられたメモリを解放する必要があります。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。visibleProviders には有効な値が格納されます。情報の経過時間に基づいて、呼び出し元アプリケーションは ScanNetwork を新たに呼び出すかどうかを判断できます。
E_PENDING	情報は利用できません。アクティブなネットワークスキャンが進行中です。呼び出し元アプリケーションは、IMbnInterfaceEvents の OnScanNetworkComplete メソッドに登録することで、デバイスの機能が利用可能になったときに通知を受け取ることができます。
E_MBN_INVALID_CACHE	可視ネットワーク一覧の Mobile Broadband のキャッシュが無効です。呼び出し元アプリケーションは、ScanNetwork を呼び出してキャッシュを設定する必要があります。

解説(Remarks)

このメソッドは、現在可視のプロバイダーの一覧を返します。CDMA デバイスは、優先ローミング一覧 (PRL) 内のいずれかのネットワークが利用可能な場合、ホームプロバイダーのみを報告します。

頻繁なネットワークスキャン操作を避けるため、オペレーティングシステムは最近のスキャン操作の一覧を保持しており、プロバイダー一覧はキャッシュされた一覧から返されます。

アプリケーションは、ScanNetwork の完了時にこのメソッドを呼び出して、可視プロバイダーの一覧を取得できます。

vtbl 12 HRESULT ScanNetwork(DWORD* requestID)

可視プロバイダーの一覧を取得するために、ネットワークを非同期にスキャンします。

requestID

DWORD*

out

この要求に対してオペレーティングシステムが設定する要求 ID へのポインター。非同期応答には、この同じ requestID が含まれます。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。
HRESULT_FROM_WIN32(ERROR_SERVICE_NOT_ACTIVE)	このシステムで Mobile Broadband サービスが実行されていません。
E_HANDLE	インターフェイスが無効です。Mobile Broadband デバイスがシステムから取り外された可能性が高いです。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	インターフェイスが無効です。Mobile Broadband デバイスがシステムから取り外された可能性が高いです。

解説(Remarks)

このメソッドは、ネットワークスキャン操作を開始します。正常に完了すると、オペレーティングシステムの可視プロバイダーのキャッシュが設定され、アプリケーションは IMbnInterface の GetVisibleProviders メソッドを呼び出して、可視ネットワークの一覧を取得できます。

これは時間のかかる操作です。そのため、アプリケーションはまず GetVisibleProviders を呼び出し、キャッシュされた情報が古い場合にのみ ScanNetwork を呼び出す必要があります。

これは非同期操作であり、ScanNetwork はただちに戻ります。このメソッドが正常に (S_OK で) 戻った場合、スキャン操作の完了時に、オペレーティングシステムは IMbnInterfaceEvents の OnScanNetworkComplete メソッドを呼び出して、操作の完了をアプリケーションに通知します。

この操作が完了する前にデバイスがシステムから取り外された場合、完了通知がアプリケーションに届く保証はありません。

vtbl 13 HRESULT GetConnection(IMbnConnection** mbnConnection)

IMbnConnection オブジェクトを取得します。

mbnConnection

IMbnConnection**

out

IMbnConnection オブジェクト。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。mbnConnection には有効なオブジェクトが格納されます。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	利用可能な接続がないか、またはデバイスがネットワークに登録されていません。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IMbnInterface "{DCBBBAB6-2001-4BBB-AAEE-338E368AF6FA}"
#usecom global IMbnInterface IID_IMbnInterface "{}"
#comfunc global IMbnInterface_get_InterfaceID           3 var
#comfunc global IMbnInterface_GetInterfaceCapability    4 var
#comfunc global IMbnInterface_GetSubscriberInformation  5 sptr
#comfunc global IMbnInterface_GetReadyState             6 var
#comfunc global IMbnInterface_InEmergencyMode           7 var
#comfunc global IMbnInterface_GetHomeProvider           8 var
#comfunc global IMbnInterface_GetPreferredProviders     9 var
#comfunc global IMbnInterface_SetPreferredProviders     10 var,var
#comfunc global IMbnInterface_GetVisibleProviders       11 var,var
#comfunc global IMbnInterface_ScanNetwork               12 var
#comfunc global IMbnInterface_GetConnection             13 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IMbnInterface "{DCBBBAB6-2001-4BBB-AAEE-338E368AF6FA}"
#usecom global IMbnInterface IID_IMbnInterface "{}"
#comfunc global IMbnInterface_get_InterfaceID           3 sptr
#comfunc global IMbnInterface_GetInterfaceCapability    4 sptr
#comfunc global IMbnInterface_GetSubscriberInformation  5 sptr
#comfunc global IMbnInterface_GetReadyState             6 sptr
#comfunc global IMbnInterface_InEmergencyMode           7 sptr
#comfunc global IMbnInterface_GetHomeProvider           8 sptr
#comfunc global IMbnInterface_GetPreferredProviders     9 sptr
#comfunc global IMbnInterface_SetPreferredProviders     10 sptr,sptr
#comfunc global IMbnInterface_GetVisibleProviders       11 sptr,sptr
#comfunc global IMbnInterface_ScanNetwork               12 sptr
#comfunc global IMbnInterface_GetConnection             13 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。