IMbnMultiCarrier::GetPreferredProviders-Methode (mbnapi.h)
Wichtig
Ab Windows 10 Version 1803 werden die in diesem Abschnitt beschriebenen Win32-APIs durch die Windows-Runtime-APIs im Windows.Networking.Connectivity-Namespace ersetzt.
Ruft die Liste der abonnierten Anbieter ab, die im aktuellen Bereich für ein Gerät mit mehreren Trägern sichtbar sind, abzüglich des aktuellen registrierten Anbieters.
Syntax
HRESULT GetPreferredProviders(
[out, retval] SAFEARRAY **preferredMulticarrierProviders
);
Parameter
[out, retval] preferredMulticarrierProviders
Zeiger auf ein Array von MBN_PROVIDER2 Strukturen, die die Liste der bevorzugten Anbieter enthalten. Wenn diese Methode einen anderen Wert als S_OK zurückgibt, ist preferredMultiCarrierProvidersNULL. Wenn GetPreferredProvidersS_OK zurückgibt, muss die aufrufende Anwendung den zugewiesenen Arbeitsspeicher durch Aufrufen von SafeArrayDestroy freigeben.
Rückgabewert
Diese Methode kann einen dieser Werte zurückgeben.
| Rückgabecode | BESCHREIBUNG |
|---|---|
|
Die Methode wurde erfolgreich abgeschlossen. preferredMultiCarrierProviders enthält gültige Werte. |
|
Die Informationen sind nicht verfügbar. Der mobile Breitbanddienst sucht derzeit nach der Liste der bevorzugten Anbieter. Die aufrufende Anwendung kann benachrichtigt werden, wenn die Daten verfügbar sind, indem sie sich für die OnPreferredProvidersChange-Methode von IMbnMultiCarrierEvents registriert. |
|
Für das Gerät muss für diesen Vorgang eine PIN eingegeben werden. |
|
Die SIM-Karte wird nicht eingefügt. |
|
Eine ungültige SIM-Karte wird in das Gerät eingefügt. |
|
Aus der SIM-Karte oder dem Gerätespeicher kann nicht gelesen werden. Beispielsweise sind auf der SIM keine bevorzugten Anbieterinformationen bereitgestellt. |
|
Dieser Vorgang wird vom Gerät nicht unterstützt. CDMA-Geräte geben diesen Wert immer zurück. |
|
Der Vorgang wird vom Gerät nicht unterstützt. Dies kann von Geräten zurückgegeben werden, die multi-Carrier nicht unterstützen. |
Hinweise
GetPreferredProviders gibt die Liste der Anbieter zurück, die in der Liste der bevorzugten Anbieter der Schnittstelle gespeichert sind.
Für die wiederherstellbaren Fehler E_MBN_PIN_REQUIRED, E_MBN_SIM_NOT_INSERTED und E_MBN_BAD_SIM fragt der mobile Breitbanddienst das Gerät erneut nach der Anbieterliste ab, wenn die Fehlerbedingung abgelaufen ist. Wenn für das Gerät beispielsweise eine PIN eingegeben werden muss, um die Anbieterliste abzurufen, gibt GetPreferredProvidersE_MBN_PIN_REQUIRED zurück. Wenn eine Anwendung eine PIN eingibt, um das Gerät zu entsperren, versucht der mobile Breitbanddienst erneut, diese Informationen vom Gerät abzurufen.
Wenn Windows das Gerät fragt, um die Anbieterliste abzurufen, nachdem ein wiederherstellbarer Fehler aufgetreten ist, gibt GetPreferredProviders sofort E_PENDING zurück. Sobald die neue Abfrage abgeschlossen ist, wird eine Benachrichtigung mithilfe der entsprechenden Rückrufmethode an die aufrufende Anwendung gesendet. Beispielsweise würde nach einem erfolgreichen PIN-Entsperrvorgang die OnEnterComplete-Methode von IMbnPinEvents aufgerufen.
Der Mobile Broadband-Dienst aktualisiert die Anwendung über die status einer neuen Abfrage, indem die OnPreferredProvidersChange-Methode von IMbnMultiCarrier aufgerufen wird.
In einigen Fällen kann die Liste der bevorzugten Anbieter des Geräts über das Netzwerk per SMS oder OTA (Over-the-Air-Update) aktualisiert werden. Windows benachrichtigt die Anwendung über änderungen in der Liste des bevorzugten Anbieters, indem die OnPreferredProvidersChange-Methode von IMbnMultiCarrier aufgerufen wird.
Eine bevorzugte Liste von Anbietern ist verfügbar, wenn der Benutzer über mehrere Abonnements (mindestens mehrere) verfügt oder das Gerät für bevorzugte Netzwerke bereitgestellt wurde und sich im Abdeckungsbereich eines der Netzwerke befindet. Diese Liste kann leer sein, auch wenn der Benutzer mehrere Netzwerke abonniert hat und sich außerhalb dieser Abdeckungsbereiche befindet. Diese Liste enthält alle derzeit sichtbaren Netzwerke, die der Benutzer abonniert hat oder für die das Gerät vorab bereitgestellt wurde, mit Ausnahme des aktuell registrierten Netzwerks.
Die Bereitstellung kann auch dazu führen, dass der vorhandenen bevorzugten Liste auf einem Gerät mit mehreren Trägern ein neuer Heimanbieter hinzugefügt wird. Dies wird mithilfe von SetHomeProvider erreicht.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 8 [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Nicht unterstützt |
| Zielplattform | Windows |
| Kopfzeile | mbnapi.h |