IMbnMultiCarrier::GetPreferredProviders メソッド (mbnapi.h)

  • [アーティクル]

重要

バージョン 1803 Windows 10以降、このセクションで説明する Win32 API は、Windows.Networking.Connectivity 名前空間のWindows 运行时 API に置き換えられます。

マルチキャリア デバイスの現在の領域に表示されるサブスクライブ済みプロバイダーの一覧から現在の登録済みプロバイダーを引いた値を取得します。

構文

HRESULT GetPreferredProviders(
  [out, retval] SAFEARRAY **preferredMulticarrierProviders
);

パラメーター

[out, retval] preferredMulticarrierProviders

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

戻り値

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

リターン コード 説明
S_OK
 メソッドは正常に完了しました。 preferredMultiCarrierProviders には有効な値が含まれています。
E_PENDING
 この情報は使用できません。 モバイル ブロードバンド サービスは現在、優先プロバイダーの一覧を探しています。 呼び出し元のアプリケーションは、IMbnMultiCarrierEvents の 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 デバイスは常にこの値を返します。
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)
 この操作は、デバイスではサポートされていません。 これは、マルチキャリアをサポートしていないデバイスによって返される場合があります。

解説

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

回復可能なエラー E_MBN_PIN_REQUIRED、 E_MBN_SIM_NOT_INSERTED、 およびE_MBN_BAD_SIMの場合、モバイル ブロードバンド サービスは、エラー条件が終わったら、プロバイダーの一覧に対してデバイスに対して再度クエリを実行します。 たとえば、プロバイダーの一覧を取得するためにデバイスに PIN を入力する必要がある場合、 GetPreferredProviders は E_MBN_PIN_REQUIREDを返します。 アプリケーションが PIN を入力してデバイスのロックを解除すると、モバイル ブロードバンド サービスはデバイスからこの情報を取得しようとします。

回復可能なエラーが発生した後、Windows がデバイスに対してクエリを実行してプロバイダーの一覧を取得すると、 GetPreferredProviders は 直ちにE_PENDINGを返します。 新しいクエリが完了すると、適切なコールバック メソッドを使用して呼び出し元アプリケーションに通知が送信されます。 たとえば、PIN ロック解除操作が成功した後、IMbnPinEvents の OnEnterComplete メソッドが呼び出されます。

モバイル ブロードバンド サービスは、IMbnMultiCarrier の OnPreferredProvidersChange メソッドを呼び出すことによって、新しいクエリの状態に関するアプリケーションを更新します。

場合によっては、デバイスの優先プロバイダーの一覧を SMS または OTA (空中更新) によってネットワーク経由で更新できます。 Windows は、IMbnMultiCarrier の OnPreferredProvidersChange メソッドを呼び出すことによって、優先プロバイダー リストの変更をアプリケーションに通知します。

ユーザーが複数のサブスクリプション (少なくとも 1 つ) を持っている場合、またはデバイスが優先ネットワーク用に事前にプロビジョニングされており、いずれかのネットワークのカバレッジ領域にある場合は、プロバイダーの優先リストを使用できます。 この一覧は、ユーザーが複数のネットワークにサブスクライブしていて、それらのカバレッジ領域の外部にある場合でも空になる可能性があります。 この一覧には、ユーザーがサブスクライブしている現在表示されているすべてのネットワーク、または現在登録されているネットワークを除き、デバイスが事前にプロビジョニングされているすべてのネットワークが含まれます。

プロビジョニングすると、マルチキャリア デバイス上の既存の優先リストに新しいホーム プロバイダーが追加される場合もあります。 これは 、SetHomeProvider を使用して行います。

要件

   
サポートされている最小のクライアント Windows 8 [デスクトップ アプリのみ]
サポートされている最小のサーバー サポートなし
対象プラットフォーム Windows
ヘッダー mbnapi.h

関連項目

IMbnMultiCarrier