IMbnInterface::GetPreferredProviders method (mbnapi.h)

Gets the list of preferred providers.

Syntax

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

Parameters

[out, retval] preferredProviders

Pointer to an array of MBN_PROVIDER structures that contains the list of preferred providers. If this method returns any value other than S_OK, this parameter 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, then the Mobile Broadband service will again try to get this information from the device.

When the operating system 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. After recovering from a SIM card error, the OnReadyStateChange method of IMbnInterfaceEvents would be called.

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

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

Requirements

See also

IMbnInterface