Método IMbnMultiCarrier::GetPreferredProviders (mbnapi.h)
Importante
A partir do 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 inscritos visíveis na área atual para um dispositivo de várias operadoras menos o provedor registrado atual.
Sintaxe
HRESULT GetPreferredProviders(
[out, retval] SAFEARRAY **preferredMulticarrierProviders
);
Parâmetros
[out, retval] preferredMulticarrierProviders
Ponteiro para uma matriz de estruturas MBN_PROVIDER2 que contêm a lista de provedores preferenciais. Se esse método retornar qualquer valor diferente de S_OK, preferredMultiCarrierProviders será NULL. Quando GetPreferredProviders retorna S_OK, o aplicativo de chamada deve liberar a memória alocada chamando SafeArrayDestroy.
Valor retornado
Esse método pode retornar um desses valores.
| Código de retorno | Descrição |
|---|---|
|
O método foi concluído com sucesso. preferredMultiCarrierProviders contém valores válidos. |
|
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 IMbnMultiCarrierEvents. |
|
O dispositivo requer que um PIN seja inserido para essa operação. |
|
O SIM não está inserido. |
|
Um SIM inválido é inserido no dispositivo. |
|
Não é possível ler a partir da memória do SIM ou do dispositivo. Por exemplo, o SIM não tem informações de provedor preferenciais provisionadas. |
|
O dispositivo não dá suporte a essa operação. Os dispositivos CDMA sempre retornarão esse valor. |
|
A operação não é compatível com o dispositivo. Isso pode ser retornado por dispositivos que não dão suporte a várias operadoras. |
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 Windows 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.
O serviço de Banda Larga Móvel atualizará o aplicativo sobre o status de qualquer nova consulta chamando o método OnPreferredProvidersChange de IMbnMultiCarrier.
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 Windows notificará o aplicativo de qualquer alteração na lista de provedores preferenciais chamando o método OnPreferredProvidersChange de IMbnMultiCarrier.
Uma lista preferencial de provedores estará disponível se o usuário tiver várias assinaturas (pelo menos mais de uma) ou se o dispositivo tiver pré-provisionado para redes preferenciais e estiver na área de cobertura de qualquer uma das redes. Essa lista pode estar vazia mesmo que o usuário tenha se inscrito em várias redes e esteja fora dessas áreas de cobertura. Essa lista conterá todas as redes visíveis no momento que o usuário assinou ou o dispositivo foi pré-provisionado, exceto para a rede registrada no momento.
O provisionamento também pode resultar na adição de um novo provedor doméstico à lista preferencial existente em um dispositivo de várias operadoras. Isso é feito usando SetHomeProvider.
Requisitos
| Cliente mínimo com suporte | Windows 8 [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Nenhum compatível |
| Plataforma de Destino | Windows |
| Cabeçalho | mbnapi.h |