IMbnMultiCarrier::GetPreferredProviders method (mbnapi.h)

Gets the list of subscribed providers visible in the current area for a multi-carrier device minus the current registered provider.

Syntax

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

Parameters

[out, retval] preferredMulticarrierProviders

Pointer to an array of MBN_PROVIDER2 structures that contain the list of preferred providers. If this method returns any value other than S_OK, preferredMultiCarrierProviders is NULL. When GetPreferredProviders returns S_OK, the calling application must free the allocated memory by calling SafeArrayDestroy.

Return value

This method can return one of these values.

Remarks

GetPreferredProviders returns the list of providers that are stored in the interface's preferred provider list.

For the recoverable errors E_MBN_PIN_REQUIRED, E_MBN_SIM_NOT_INSERTED, and E_MBN_BAD_SIM, the Mobile Broadband service will query the device again for the provider list when the error condition is over. For example, if the device requires a PIN to be entered to get the provider list, then GetPreferredProviders will return E_MBN_PIN_REQUIRED. When an application enters a PIN to unlock the device, the Mobile Broadband service will again try to get this information from the device.

When Windows is querying the device to get the provider list after a recoverable error has occurred, GetPreferredProviders immediately returns E_PENDING. Once the new query has completed, a notification is sent to the calling application using the appropriate callback method. For example, after a successful PIN unlock operation, the OnEnterComplete method of IMbnPinEvents would be called.

The Mobile Broadband service will update the application about the status of any new query by calling the OnPreferredProvidersChange method of IMbnMultiCarrier.

In some cases, the device's preferred provider list can be updated through the network by SMS or OTA (over-the-air update). Windows will notify the application of any change in the preferred provider list by calling the OnPreferredProvidersChange method of IMbnMultiCarrier.

A preferred list of providers is available if the user has multiple subscriptions (at least more than one) or the device has pre-provisioned for preferred networks and is in the coverage area of any of the networks. This list may be empty even if the user has subscribed to multiple networks and is outside of those coverage areas. This list will contain all of the currently visible networks that the user has subscribed to or the device has pre-provisioned for except for the currently registered network.

Provisioning can also result in a new home provider being added to the existing preferred list on a multi-carrier device. This is accomplished using SetHomeProvider.

Requirements

See also

IMbnMultiCarrier