Método IMbnInterface::GetPreferredProviders (mbnapi.h)

Importante

A partir de Windows 10, versão 1803, as APIs do Win32 descritas nesta seção são substituídas pelas APIs Windows Runtime no namespace Windows.Networking.Connectivity.

Obtém a lista de provedores preferenciais.

Sintaxe

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

Parâmetros

[out, retval] preferredProviders

Ponteiro para uma matriz de estruturas de MBN_PROVIDER que contém a lista de provedores preferenciais. Se esse método retornar qualquer valor diferente de S_OK, esse parâmetro será NULL. Quando GetPreferredProviders retorna S_OK, o aplicativo de chamada deve liberar a memória alocada chamando SafeArrayDestroy.

Retornar valor

Esse método pode retornar um desses valores.

Código de retorno	Descrição
S_OK	O método foi concluído com sucesso. preferredProviders contém valores válidos.
E_PENDING	As informações não estão disponíveis. O serviço de Banda Larga Móvel está atualmente investigando a lista de provedores preferenciais. O aplicativo de chamada pode ser notificado quando os dados estão disponíveis registrando-se para o método OnPreferredProvidersChange de IMbnInterfaceEvents.
E_MBN_PIN_REQUIRED	O dispositivo requer que um PIN seja inserido para essa operação.
E_MBN_SIM_NOT_INSERTED	O SIM não está inserido.
E_MBN_BAD_SIM	Um SIM incorreto é inserido no dispositivo.
HRESULT_FROM_WIN32(ERROR_READ_FAULT)	Não é possível ler a partir do SIM ou da memória do dispositivo. Por exemplo, o SIM não tem informações preferenciais do provedor provisionadas.
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	O dispositivo não dá suporte a essa operação. Os dispositivos CDMA sempre retornarão esse valor.

Comentários

GetPreferredProviders retorna a lista de provedores armazenados na lista de provedores preferenciais da interface.

Para os erros recuperáveis E_MBN_PIN_REQUIRED, E_MBN_SIM_NOT_INSERTED e E_MBN_BAD_SIM, o serviço de Banda Larga Móvel consultará o dispositivo novamente para a lista de provedores quando a condição de erro terminar. Por exemplo, se o dispositivo exigir que um PIN seja inserido para obter a lista de provedores, GetPreferredProviders retornará E_MBN_PIN_REQUIRED. Quando um aplicativo insere um PIN para desbloquear o dispositivo, o serviço de Banda Larga Móvel tentará novamente obter essas informações do dispositivo.

Quando o sistema operacional está consultando o dispositivo para obter a lista de provedores após um erro recuperável, GetPreferredProviders retorna imediatamente E_PENDING. Depois que a nova consulta for concluída, uma notificação será enviada ao aplicativo de chamada usando o método de retorno de chamada apropriado. Por exemplo, após uma operação de desbloqueio de PIN bem-sucedida, o método OnEnterComplete de IMbnPinEvents seria chamado. Após a recuperação de um erro de cartão sim, o método OnReadyStateChange de IMbnInterfaceEvents seria chamado.

O serviço de Banda Larga Móvel atualizará o aplicativo sobre o status de qualquer nova consulta chamando o método OnPreferredProvidersChange de IMbnInterfaceEvents.

Em alguns casos, a lista de provedores preferenciais do dispositivo pode ser atualizada por meio da rede por SMS ou OTA (atualização over-the-air). O sistema operacional notificará a aplicação de qualquer alteração na lista de provedores preferenciais chamando o método OnPreferredProvidersChange de IMbnInterfaceEvents.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 7 [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte	Nenhum compatível
Plataforma de Destino	Windows
Cabeçalho	mbnapi.h

Confira também

IMbnInterface