IMbnMultiCarrier：：GetPreferredProviders 方法 (mbnapi.h)
重要
從 Windows 10 1803 版開始，本節所述的 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來釋放配置的記憶體。
傳回值
這個方法可以傳回其中一個值。
| 傳回碼 | 描述 |
|---|---|
|
已成功完成命令。 preferredMultiCarrierProviders 包含有效值。 |
|
資訊無法使用。 行動寬頻服務目前正在探查慣用的提供者清單。 呼叫端應用程式可以藉由註冊IMbnMultiCarrierEvents的OnPreferredProvidersChange方法，在資料可用時收到通知。 |
|
裝置需要輸入 PIN 才能進行這項作業。 |
|
不會插入 SIM 卡。 |
|
在裝置中插入不正確的 SIM 卡。 |
|
無法從 SIM 卡或裝置記憶體讀取。 例如，SIM 沒有布建慣用的提供者資訊。 |
|
裝置不支援這項作業。 CDMA 裝置一律會傳回此值。 |
|
裝置不支援此作業。 這可由不支援多電信業者之裝置傳回。 |
備註
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方法，通知應用程式慣用提供者清單中的任何變更。
如果使用者有多個訂用帳戶 (至少一個) ，或裝置已預先布建慣用網路，且位於任何網路的涵蓋範圍區域中，則提供慣用的提供者清單。 即使使用者已訂閱多個網路，而且不在這些涵蓋範圍區域之外，此清單也可能是空的。 此清單將包含使用者已訂閱的所有目前可見網路，或裝置已預先布建，但目前已註冊的網路除外。
布建也會導致新的家庭提供者新增至多電信業者裝置上現有的慣用清單。 這是使用 SetHomeProvider完成的。
需求
| 最低支援的用戶端 | Windows 8 [僅限傳統型應用程式] |
| 最低支援的伺服器 | 都不支援 |
| 目標平台 | Windows |
| 標頭 | mbnapi.h |