ホーム › NetworkManagement.MobileBroadband › IMbnRegistration

IMbnRegistration

COM

📘 Microsoft Learn (日本語) · English

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

公式ドキュメント

ネットワーク登録データへのアクセスを提供します。

解説(Remarks)

アプリケーションは、IMbnInterface の QueryInterface メソッドを呼び出すことで、このインターフェイスを取得できます。

メソッド 10

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

vtbl 3 HRESULT GetRegisterState(MBN_REGISTER_STATE* registerState)

登録状態を取得します。

registerState

MBN_REGISTER_STATE*

out

デバイスの現在の登録状態を示す MBN_REGISTER_STATE 値へのポインター。この値はメソッドが S_OK を返した場合にのみ有効です。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_PENDING	登録状態は利用できません。モバイルブロードバンドサービスは現在、この情報についてデバイスを照会しています。登録状態が利用可能になると、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnRegisterStateChange メソッドを呼び出します。
E_MBN_PIN_REQUIRED	登録状態を取得するには PIN が必要です。

解説(Remarks)

GetRegisterState メソッドは、デバイスの現在のネットワーク登録状態を取得します。デバイスは、ネットワークに登録された状態、登録先ネットワークを検索している状態、または登録を拒否された状態のいずれかになります。

デバイスの登録状態は自動的に変化することがあります。たとえば、デバイスがネットワークのサービス提供エリア外に移動すると、登録状態が MBN_REGISTER_STATE_HOME から MBN_REGISTER_STATE_SEARCHING に変わります。

アプリケーションは、IMbnRegistrationEvents インターフェイスを接続することで、登録状態の変更通知を受け取るように登録できます。Windows は、これらの変更をアプリケーションに通知するために、IMbnRegistrationEvents の OnRegisterStateChange メソッドを呼び出します。

回復可能なエラー E_MBN_PIN_REQUIRED の場合、モバイルブロードバンドサービスは、エラー状態が解消されたとき(PIN が入力されたとき)に、この情報をデバイスから再度取得しようとします。その後、IMbnRegistrationEvents の OnRegisterStateChange メソッドを呼び出します。

vtbl 4 HRESULT GetRegisterMode(MBN_REGISTER_MODE* registerMode)

モバイルブロードバンドデバイスのネットワーク登録モードを取得します。

registerMode

MBN_REGISTER_MODE*

out

デバイスの現在のネットワーク登録モードを示す MBN_REGISTER_MODE 値へのポインター。この値はメソッドが S_OK を返した場合にのみ有効です。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_PENDING	登録モードは利用できません。モバイルブロードバンドサービスは現在、この情報についてデバイスを照会しています。登録モードが利用可能になると、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnRegisterModeAvailable メソッドを呼び出します。
E_MBN_PIN_REQUIRED	登録モードを取得するには PIN が必要です。
E_MBN_SIM_NOT_INSERTED	デバイスに SIM が挿入されていません。
E_MBN_BAD_SIM	デバイスに不良な SIM が挿入されています。

解説(Remarks)

指定可能な登録モードの詳細については、MBN_REGISTER_MODE を参照してください。

回復可能なエラー E_MBN_PIN_REQUIRED の場合、モバイルブロードバンドサービスは、エラー状態が解消されたとき(PIN が入力されたとき)に、この情報をデバイスから再度取得しようとします。その後、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnRegisterModeAvailable メソッドを呼び出します。

vtbl 5 HRESULT GetProviderID(LPWSTR* providerID)

現在登録されているネットワークのプロバイダー ID を取得します。

providerID

LPWSTR*

out

現在登録されているプロバイダーの ID を格納する文字列へのポインター。最大長は MBN_PROVIDERID_LEN 文字です。この文字列は、メソッドが成功して S_OK を返した場合にのみ格納されます。成功した場合、呼び出し側アプリケーションは SysFreeString を呼び出して、割り当てられたメモリを解放する必要があります。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_PENDING	プロバイダー ID は利用できません。モバイルブロードバンドサービスは現在、この情報についてデバイスを照会しています。プロバイダー ID が利用可能になると、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnRegisterModeAvailable メソッドを呼び出します。
E_MBN_PIN_REQUIRED	プロバイダー ID を取得するには PIN が必要です。
MBN_SIM_NOT_INSERTED	デバイスに SIM が挿入されていません。
E_MBN_BAD_SIM	デバイスに不良な SIM が挿入されています。

解説(Remarks)

GetProviderID メソッドは、現在登録されているプロバイダーの ID を取得します。自動ネットワーク選択モードの場合、これはデバイスが現在登録されているネットワークの ID です。ネットワーク選択モードが手動の場合、このフィールドには、デバイスが登録を試みるネットワークのプロバイダー ID が格納されます。CDMA デバイスの場合、プロバイダー ID が不明なときは MBN_CDMA_DEFAULT_PROVIDER_ID が設定されます。

この情報は、モバイルブロードバンドデバイスがあるネットワークから別のネットワークに移動したときに変化することがあります。これには、ネットワーク登録状態が MBN_REGISTER_STATE_HOME から MBN_REGISTER_STATE_SEARCHING に変わる場合が含まれます。また、ネットワークが登録先をあるプロバイダーから別のプロバイダーに移すなど、登録されているネットワークに変更があった場合にも発生します。このような変更の後、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnRegisterStateChange メソッドを呼び出します。これが発生したとき、アプリケーションは GetProviderID を呼び出す必要があります。

回復可能なエラー E_MBN_PIN_REQUIRED の場合、モバイルブロードバンドサービスは、エラー状態が解消されたとき(PIN が入力されたとき)に、この情報をデバイスから再度取得しようとします。その後、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnPacketServiceStateChange メソッドを呼び出します。

vtbl 6 HRESULT GetProviderName(LPWSTR* providerName)

現在登録されているネットワークのプロバイダー名を取得します。

providerName

LPWSTR*

out

現在登録されているプロバイダーの名前を格納する文字列へのポインター。この文字列の最大長は MBN_PROVIDERNAME_LEN 文字です。この文字列は、メソッドが成功して S_OK を返した場合にのみ格納されます。成功した場合、呼び出し側アプリケーションは SysFreeString を呼び出して、割り当てられたメモリを解放する必要があります。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_PENDING	プロバイダー名は利用できません。モバイルブロードバンドサービスは現在、この情報についてデバイスを照会しています。プロバイダー名が利用可能になると、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnRegisterModeAvailable メソッドを呼び出します。
E_MBN_PIN_REQUIRED	プロバイダー名を取得するには PIN が必要です。
E_MBN_SIM_NOT_INSERTED	デバイスに SIM が挿入されていません。
E_MBN_BAD_SIM	デバイスに不良な SIM が挿入されています。

解説(Remarks)

プロバイダー名は、モバイルブロードバンドデバイスがあるネットワークから別のネットワークに移動したときに変化することがあります。これには、ネットワーク登録状態が MBN_REGISTER_STATE_HOME から MBN_REGISTER_STATE_SEARCHING に変わる場合が含まれます。また、ネットワークが登録先をあるプロバイダーから別のプロバイダーに変更するなど、登録されているネットワークに変更があった場合にも発生します。このような変更の後、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnRegisterStateChange メソッドを呼び出します。これが発生したとき、アプリケーションは GetProviderID を呼び出す必要があります。

回復可能なエラー E_MBN_PIN_REQUIRED の場合、モバイルブロードバンドサービスは、エラー状態が解消されたとき(PIN が入力されたとき)に、この情報をデバイスから再取得しようとします。その後、IMbnRegistrationEvents の OnRegisterStateChange メソッドを呼び出します。

vtbl 7 HRESULT GetRoamingText(LPWSTR* roamingText)

ローミングプロバイダーを説明するローミングテキストを取得します。

roamingText

LPWSTR*

out

デバイスがローミング中のネットワークに関する追加情報を格納する文字列へのポインター。最大長は MBN_ROAMTEXT_LEN 文字です。この文字列は、メソッドが成功して S_OK を返した場合にのみ格納されます。成功した場合、呼び出し側アプリケーションは SysFreeString を呼び出して、割り当てられたメモリを解放する必要があります。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_PENDING	ローミングテキストは利用できません。モバイルブロードバンドサービスは現在、この情報についてデバイスを照会しています。ローミングテキストが利用可能になると、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnRegisterModeAvailable メソッドを呼び出します。
E_MBN_PIN_REQUIRED	ローミングテキストを取得するには PIN が必要です。
E_MBN_SIM_NOT_INSERTED	デバイスに SIM が挿入されていません。
E_MBN_BAD_SIM	デバイスに不良な SIM が挿入されています。

解説(Remarks)

GetRoamingText メソッドは、登録状態が MBN_REGISTER_STATE_PARTNER または MBN_REGISTER_STATE_ROAMING のときに、ネットワークに関する追加情報を含むテキスト文字列を取得できます。

vtbl 8 HRESULT GetAvailableDataClasses(DWORD* availableDataClasses)

現在のネットワークで利用可能なデータクラスを取得します。

availableDataClasses

DWORD*

out

MBN_DATA_CLASS 値のビットごとの OR の組み合わせへのポインター。このパラメーターは、関数が S_OK を返した場合にのみ有効です。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_PENDING	データクラスは利用できません。モバイルブロードバンドサービスは現在、この情報についてデバイスを照会しています。データクラスが利用可能になると、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnPacketServiceStateChange メソッドを呼び出します。
E_MBN_PIN_REQUIRED	データクラスを取得するには PIN が必要です。

解説(Remarks)

GetAvailableDataClasses は、現在のネットワークで利用可能なデータクラスのセットを返します。値が不明な場合、これらの値は MBN_DATA_CLASS_NONE に設定されることがあります。

利用可能なデータクラスは、デバイスがあるセルから別のセルに移動する際に自動的に変化することがあります。このような変更が発生するたびに、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnPacketServiceStateChange メソッドを呼び出してアプリケーションに通知します。

vtbl 9 HRESULT GetCurrentDataClass(DWORD* currentDataClass)

現在のネットワークにおける現在のデータクラスを取得します。

currentDataClass

DWORD*

out

MBN_DATA_CLASS 値へのポインター。このパラメーターは、関数が S_OK を返した場合にのみ有効です。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_PENDING	データクラスは利用できません。モバイルブロードバンドサービスは現在、この情報についてデバイスを照会しています。データクラスが利用可能になると、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnPacketServiceStateChange メソッドを呼び出します。
E_MBN_PIN_REQUIRED	データクラスを取得するには PIN が必要です。
E_MBN_SIM_NOT_INSERTED	デバイスに SIM が挿入されていません。
E_MBN_BAD_SIM	デバイスに不良な SIM が挿入されています。

解説(Remarks)

GetCurrentDataClass メソッドは、現在のネットワークにおけるデータクラスを返します。値が不明な場合、この値は MBN_DATA_CLASS_NONE に設定されることがあります。

現在のデータクラスは、デバイスがあるセルラーネットワークから別のセルラーネットワークに移動する際に自動的に変化することがあります。このような変更が発生するたびに、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnPacketServiceStateChange メソッドを呼び出してアプリケーションに通知します。

vtbl 10 HRESULT GetRegistrationNetworkError(DWORD* registrationNetworkError)

登録操作からのネットワークエラーを取得します。

registrationNetworkError

DWORD*

out

最後に失敗したネットワーク登録操作によって返されたエラーコードへのポインター。エラーがない場合、またはエラーコードが不明な場合は 0 に設定されます。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

GSM デバイスの場合、エラーコードは 3GPP 仕様 24.008 で「原因コード(cause codes)」として定義されています。CDMA デバイスの場合、コードはデバイスおよびネットワークに固有です。

エラーコードは、パケットアタッチ操作が正常に完了するとクリアされます。

ネットワークエラー値に変更があるたびに、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnRegisterStateChange メソッドを呼び出します。

vtbl 11 HRESULT GetPacketAttachNetworkError(DWORD* packetAttachNetworkError)

パケットアタッチ操作からのネットワークエラーを取得します。

packetAttachNetworkError

DWORD*

out

最後に失敗したネットワークパケットアタッチ操作によって返されたエラーコードへのポインター。エラーがない場合、またはエラーコードが不明な場合は 0 に設定されます。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

エラーコードは、パケットアタッチ操作が正常に完了するとクリアされます。

ネットワークエラー値に変更があるたびに、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnPacketServiceStateChange メソッドを呼び出します。

vtbl 12 HRESULT SetRegisterMode(MBN_REGISTER_MODE registerMode, LPWSTR providerID, DWORD dataClass, DWORD* requestID)

デバイスの登録モードを設定します。

registerMode	MBN_REGISTER_MODE	in	新しい登録モードを指定する MBN_REGISTER_MODE 値。
providerID	LPWSTR	in	登録先のネットワークプロバイダーのプロバイダー ID を指定する文字列。registerMode が MBN_REGISTER_MODE_AUTOMATIC の場合は NULL でなければなりません。
dataClass	DWORD	in	接続に対して優先されるデータアクセス技術を指定する MBN_DATA_CLASS 値のビットごとの OR の組み合わせ。モバイルブロードバンドサービスは、このリストの中で利用可能な最も高いデータクラス技術に登録します。このリストのいずれのデータクラスにも登録できない場合、モバイルブロードバンドサービスは利用可能な最良のデータクラスに登録します。
requestID	DWORD*	out	この非同期要求を識別するためにモバイルブロードバンドサービスによって設定される要求 ID。

戻り値

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

戻り値	説明
S_OK	メソッドは正常に完了しました。
HRESULT_FROM_WIN32(ERROR_SERVICE_NOT_ACTIVE)	このシステムでモバイルブロードバンドサービスが実行されていません。
E_HANDLE	インターフェイスが無効です。おそらくモバイルブロードバンドデバイスがシステムから取り外されたためです。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	インターフェイスが無効です。おそらくモバイルブロードバンドデバイスがシステムから取り外されたためです。
HRESULT_FROM_WIN32(ERROR_INVALID_STATE)	既にアクティブなネットワーク接続があります。既に確立されたデータ接続がある間は、登録モードを変更できません。呼び出し側アプリケーションは、まず接続を切断してから登録モードの変更を試みる必要があります。デバイスが既に要求されたモードであり、要求されたプロバイダーに接続されている場合は、戻り値は S_OK になります。

解説(Remarks)

SetRegisterMode メソッドは、デバイスを自動または手動のネットワーク選択モードに設定するために使用できます。手動登録モードの場合、デバイスが登録すべきネットワーク ID は providerID で指定します。

手動登録モードのサポートは任意であり、アプリケーションは、IMbnInterface の GetInterfaceCapability メソッドによって設定される interfaceCaps パラメーターに MBN_CTRL_CAPS_REG_MANUAL が含まれているかどうかを確認して、デバイスが手動登録をサポートしていることを検証する必要があります。アプリケーションが手動登録モードを設定し、それがデバイスでサポートされていない場合、この呼び出しは HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) を返します。

SetRegisterMode は非同期であり、すぐに戻ります。エラーがない場合、操作の完了時に、モバイルブロードバンドサービスは IMbnRegistrationEvents の OnSetRegisterModeComplete メソッドを呼び出します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IMbnRegistration "{DCBBBAB6-2009-4BBB-AAEE-338E368AF6FA}"
#usecom global IMbnRegistration IID_IMbnRegistration "{}"
#comfunc global IMbnRegistration_GetRegisterState             3 var
#comfunc global IMbnRegistration_GetRegisterMode              4 var
#comfunc global IMbnRegistration_GetProviderID                5 var
#comfunc global IMbnRegistration_GetProviderName              6 var
#comfunc global IMbnRegistration_GetRoamingText               7 var
#comfunc global IMbnRegistration_GetAvailableDataClasses      8 var
#comfunc global IMbnRegistration_GetCurrentDataClass          9 var
#comfunc global IMbnRegistration_GetRegistrationNetworkError  10 var
#comfunc global IMbnRegistration_GetPacketAttachNetworkError  11 var
#comfunc global IMbnRegistration_SetRegisterMode              12 int,wstr,int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IMbnRegistration "{DCBBBAB6-2009-4BBB-AAEE-338E368AF6FA}"
#usecom global IMbnRegistration IID_IMbnRegistration "{}"
#comfunc global IMbnRegistration_GetRegisterState             3 sptr
#comfunc global IMbnRegistration_GetRegisterMode              4 sptr
#comfunc global IMbnRegistration_GetProviderID                5 sptr
#comfunc global IMbnRegistration_GetProviderName              6 sptr
#comfunc global IMbnRegistration_GetRoamingText               7 sptr
#comfunc global IMbnRegistration_GetAvailableDataClasses      8 sptr
#comfunc global IMbnRegistration_GetCurrentDataClass          9 sptr
#comfunc global IMbnRegistration_GetRegistrationNetworkError  10 sptr
#comfunc global IMbnRegistration_GetPacketAttachNetworkError  11 sptr
#comfunc global IMbnRegistration_SetRegisterMode              12 int,wstr,int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。