ホーム › NetworkManagement.MobileBroadband › IMbnConnection

IMbnConnection

COM

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

公式ドキュメント

デバイスのネットワーク接続を表します。

解説(Remarks)

このインターフェースは、モバイルブロードバンドデバイスがネットワークに登録されているとき、またはデバイスが MBN_READY_STATE_DEVICE_LOCKED 状態のときにのみ使用できます。デバイスがネットワークから登録解除されると、この COM インターフェースは削除され、モバイルブロードバンドサービスは IMbnConnectionManagerEvents インターフェースの OnConnectionRemoval メソッドを呼び出します。

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

メソッド 7

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

vtbl 3 HRESULT get_ConnectionID(LPWSTR* ConnectionID)

接続の一意識別子を取得します。

ConnectionID

LPWSTR*

out

この接続を一意に識別する接続ID 文字列を受け取る LPWSTR ポインタである。

vtbl 4 HRESULT get_InterfaceID(LPWSTR* InterfaceID)

インターフェース識別子を取得します。

InterfaceID

LPWSTR*

out

接続が属するインターフェイスID 文字列を受け取る LPWSTR ポインタである。

vtbl 5 HRESULT Connect(MBN_CONNECTION_MODE connectionMode, LPWSTR strProfile, DWORD* requestID)

データ接続を確立します。

connectionMode	MBN_CONNECTION_MODE	in	接続のモードを指定する MBN_CONNECTION_MODE 値。
strProfile	LPWSTR	in	プロファイル指定子を格納します。
requestID	DWORD*	out	この非同期要求を識別するためにモバイルブロードバンドサービスによって返される、一意の要求 ID へのポインター。

戻り値

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

Return code	Description
S_OK	操作は成功しました。
HRESULT_FROM_WIN32(ERROR_SERVICE_NOT_ACTIVE)	モバイルブロードバンドサービスがこのシステムで実行されていません。
E_HANDLE	無効なインターフェースです。おそらくモバイルブロードバンドデバイスがシステムから取り外されています。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	無効なインターフェースです。おそらくモバイルブロードバンドデバイスがシステムから取り外されています。
E_INVALIDARG	無効なプロファイル名が指定されたか、strProfile 引数が XML プロファイルスキーマに準拠していません。
E_MBN_MAX_ACTIVATED_CONTEXTS	既にアクティブなモバイルブロードバンドコンテキストが存在します。複数のアクティブなコンテキストはサポートされていません。

解説(Remarks)

Connect メソッドは、デバイスの接続コンテキストをアクティブ化するために使用します。モバイルブロードバンドサービスは、現在最大 1 つのアクティブなコンテキストをサポートします。コンテキストのアクティブ化により、L2 接続も確立されます。同様に、コンテキストの非アクティブ化により、モバイルネットワークへの物理データ接続が切断されます。

この操作を呼び出した時点でデバイスがパケットアタッチ状態でない場合、モバイルブロードバンドサービスは、デバイスに接続要求を発行する前に、デバイスを暗黙的にパケットアタッチします。パケットサービスの状態変化があった場合、アプリケーションは IMbnRegistrationEvents インターフェースの OnPacketServiceStateChange メソッドの呼び出しによって通知されます。

connectionMode が MBN_CONNECTION_MODE_PROFILE に設定されている場合、strProfile はデバイスのプロファイル名を表します。MBN_CONNECTION_MODE_TMP_PROFILE に設定されている場合、strProfile はプロファイルの XML 表現を表します。呼び出し側アプリケーションは、IMbnConnectionProfileManager を使用して、デバイスに格納されている接続プロファイルの一覧を取得できます。

これは即座に戻る非同期操作です。このメソッドが正常に返された場合、操作が完了すると、モバイルブロードバンドサービスは IMbnConnectionEvents の OnConnectComplete メソッドを呼び出します。

Windows 8 以降の Windows: Windows ストアアプリは、MBN_CONNECTION_MODE_TMP_PROFILE の connectionMode と、プロファイルの XML 表現に設定された strProfile パラメーターのみを指定して Connect を使用できます。これは、接続が一時的な性質のものであり、システムが将来使用するために保存されないことを意味します。

vtbl 6 HRESULT Disconnect(DWORD* requestID)

データ接続を切断します。

requestID

DWORD*

out

この非同期要求を識別するためにモバイルブロードバンドサービスによって割り当てられる、一意の要求 ID へのポインター。

戻り値

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

Return code	Description
S_OK	メソッドは正常に完了しました。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	接続は既に切断されています。

解説(Remarks)

非アクティブ化により、L2 接続も切断されます。

これは即座に戻る非同期操作です。このメソッドが正常に返された場合、操作が完了すると、モバイルブロードバンドサービスは IMbnConnectionEvents の OnDisconnectComplete メソッドを呼び出します。

Windows 8 以降の Windows: Windows ストアアプリは、既存の MBN 接続がそのアプリによって Connect を使用して開始された場合にのみ Disconnect を使用できます。Disconnect は、ユーザーまたは Windows 接続マネージャーによって確立された接続を切断するために使用することはできません。

vtbl 7 HRESULT GetConnectionState(MBN_ACTIVATION_STATE* ConnectionState, LPWSTR* ProfileName)

デバイスの現在の接続状態を取得します。

ConnectionState	MBN_ACTIVATION_STATE*	out	接続の状態を格納する MBN_ACTIVATION_STATE 構造体へのポインター。
ProfileName	LPWSTR*	out	接続プロファイルの名前を格納する文字列へのポインター。このパラメーターは、ConnectionState が MBN_ACTIVATION_STATE_ACTIVATED の場合にのみ有効です。この文字列が NULL でない場合、呼び出し側アプリケーションは SysFreeString を呼び出してこの文字列を解放する必要があります。

戻り値

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

Return code	Description
S_OK	メソッドは正常に完了しました。注意このメソッドは、ProfileName が NULL のときに S_OK を返すことがあります。呼び出しが成功した場合でも、クライアントが NULL の ProfileName を処理できることを確認してください。
E_PENDING	アクティブ化状態が利用できません。モバイルブロードバンドサービスは、この情報についてデバイスを照会しています。呼び出し側アプリケーションは、IMbnConnectionEvents の OnConnectStateChange メソッドを登録することで、アクティブ化状態が利用可能になったときに通知を受け取ることができます。
E_MBN_PIN_REQUIRED	コール状態を取得するには PIN が必要です。
E_MBN_SIM_NOT_INSERTED	デバイスに SIM が挿入されていません。
E_MBN_BAD_SIM	デバイスに不正な SIM が挿入されています。

解説(Remarks)

このメソッドは、ProfileName が NULL のときに S_OK を返すことがあります。呼び出しが成功した場合でも、クライアントが NULL の ProfileName を処理できることを確認してください。

vtbl 8 HRESULT GetVoiceCallState(MBN_VOICE_CALL_STATE* voiceCallState)

デバイスの音声通話状態を取得します。

voiceCallState

MBN_VOICE_CALL_STATE*

out

音声通話状態を指定する MBN_VOICE_CALL_STATE 値へのポインター。メソッドが S_OK 以外を返した場合、このポインターの内容は設定されません。

戻り値

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

Return code	Description
S_OK	メソッドは正常に完了しました。
E_PENDING	コール状態が利用できません。モバイルブロードバンドサービスは、この情報についてデバイスを照会しています。呼び出し側アプリケーションは、IMbnConnectionEvents の OnVoiceCallStateChange メソッドを登録することで、コール状態が利用可能になったときに通知を受け取ることができます。
E_MBN_PIN_REQUIRED	コール状態を取得するには PIN が必要です。
E_MBN_SIM_NOT_INSERTED	デバイスに SIM が挿入されていません。
E_MBN_BAD_SIM	デバイスに不正な SIM が挿入されています。

解説(Remarks)

回復可能なエラー E_MBN_PIN_REQUIRED、E_MBN_SIM_NOT_INSERTED、E_MBN_BAD_SIM の場合、モバイルブロードバンドサービスは、エラー状態が解消された後に、この情報についてデバイスを再度照会します。たとえば、音声通話状態を取得するためにデバイスで PIN の入力が必要な場合は、E_MBN_PIN_REQUIRED が返されます。呼び出し側アプリケーションがデバイスのロックを解除するために PIN を入力すると、モバイルブロードバンドサービスは、デバイスから音声通話状態を再度取得しようとします。モバイルブロードバンドサービスは、IMbnConnectionEvents の OnVoiceCallStateChange メソッドを呼び出すことで、新しい照会の状態をアプリケーションに更新します。

vtbl 9 HRESULT GetActivationNetworkError(DWORD* networkError)

パケットデータプロトコル (PDP) コンテキストのアクティブ化失敗時に返されるネットワークエラーを取得します。

networkError

DWORD*

out

直前の接続コンテキストのアクティブ化操作でネットワークから返されたエラーコード。この値は、メソッドが S_OK を返した場合にのみ意味を持ちます。

戻り値

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

解説(Remarks)

GSM デバイスの場合、これらのエラーコードは 3GPP 仕様 24.008 で原因コードとして定義されています。CDMA デバイスの場合、デバイスおよびネットワーク固有のエラーコードが使用されます。

エラーコードは、コンテキストのアクティブ化操作が正常に完了するとクリアされます。ネットワークエラーがない場合やエラーが不明な場合、値は 0 に設定されます。

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

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