Como recuperar informações de conexão de rede (HTML)

Artigo
12/12/2015

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Este tópico mostra como recuperar detalhes de conectividade e informações de uso para conexões de rede em um dispositivo usando classes no namespace Windows.Networking.Connectivity.

Pré-requisitos

Os exemplos a seguir usam JavaScript e se baseiam na Amostra de informações de rede. Para obter instruções sobre a criação de um aplicativo do Tempo de Execução do Windows em JavaScript, veja Criar seu primeiro aplicativo do Tempo de Execução do Windows em JavaScript.

O que é um perfil de conexão?

Um ConnectionProfile representa uma única conexão de rede estabelecida em um dispositivo. As informações acessadas de um ConnectionProfile podem ser usadas para determinar o nível da conectividade atual, acompanhar o uso de dados ou para identificar o adaptador de rede usado para manter a conexão. Ao se registrar para receber notificações de alterações nas propriedade de um ConnectionProfile, o aplicativo do Tempo de Execução do Windows conectado pode fazer as escolher certas para adaptar o comportamento às alterações feitas em um ambiente de rede. Para saber mais sobre como se registrar para essas notificações, veja Como gerenciar eventos de conexão de rede e mudanças na disponibilidade.

Para cenários mais especializados, como aplicativos conectados para dispositivos móveis que frequentemente usam perfil móvel e operam em redes limitadas, um ConnectionProfile oferece informações de custo e de plano de dados que podem ser usadas para impedir taxas inesperadas de serviço da operadora. Para saber mais, veja Como gerenciar restrições de custo em redes limitadas.

Cada ConnectionProfile fornece acesso às seguintes informações de conexão:

Dados	Fornecidos por	Descrição
Custo de conexão	ConnectionCost	Detalhes de custo, incluindo informações de limite de dados e de roaming.
Tipo de Custo	NetworkCostType	Tipo de custo da rede utilizada atualmente pela conexão.
Status e Utilização do Plano de Dados	DataPlanStatus, DataPlanUsage	Informações de utilização específicas para o plano de dados associado com a conexão.
Uso Local	NetworkUsage	Informações de uso da conexão local.
Adaptador de Rede	NetworkAdapter	Adaptador de rede que fornece conectividade para a conexão.
Propriedades da conexão WLAN e WWAN	WlanConnectionProfileDetails WwanConnectionProfileDetails	Apresenta mais detalhes específicos aos perfis de conexão WLAN e WWAN.

Recuperando perfis de conexão

Primeiro defina uma instância da classe NetworkInformation, que define os métodos que seu aplicativo utiliza para recuperar um ConnectionProfile. Depois defina uma instância da classe NetworkCostType, que define os tipos de custo de rede possíveis com um ConnectionProfile.

var networkInfo = Windows.Networking.Connectivity.NetworkInformation;
var networkCostInfo = Windows.Networking.Connectivity.NetworkCostType;

A classe NetworkInformation define dois métodos para recuperação de um ConnectionProfile. Caso só precise retornar o perfil associado à conexão de Internet, use o método getInternetConnectionProfile.

É necessário escrever um código para tratar exceções quando você chama a maioria dos métodos de rede assíncronos. Também os métodos no namespace Windows.Networking.Connectivity que recuperam um ConnectionProfile podem gerar exceções. Seu manipulador de exceção recupera informações mais detalhadas sobre a causa da exceção para entender melhor a falha e tomar as medidas adequadas. Para saber mais, veja Como manipular exceções em aplicativos de rede.

function displayInternetConnectionProfileInfo() {
    try {
        // get the ConnectionProfile that is currently used to connect to the Internet
        var internetProfile = networkInfo.getInternetConnectionProfile();
        mySample.displayStatus(GetConnectionProfileInfo(internetProfile));
    }
    catch (e) {
        mySample.displayError("Exception Caught: " + e + "\n\r");
    }
}

Caso queira recuperar perfis de todas as conexões (inclusive Internet), use o método getConnectionProfiles.

function displayConnectionProfileList() {
  var profileList = "";
  try {
      var ConnectionProfiles = networkInfo.getConnectionProfiles();
      if (ConnectionProfiles.length != 0) {
          for (var i = 0; i < ConnectionProfiles.length; i++) {

              //Display Connection profile info for each profile
              profileList += GetConnectionProfileInfo(ConnectionProfiles[i]);
              profileList += "-----------------------------------------\n\r";
          }
          mySample.displayStatus(profileList);
          }
          else {
              mySample.displayStatus("No profiles found");
          }
      }

      catch (e) {
         mySample.displayError("Exception Caught: " + e + "\n\r");
      }
}

Acessando informações de um perfil de conexão

O código de exemplo a seguir chama métodos no ConnectionProfile para recuperar estado de conexão de rede, custo e informações de uso.

function getConnectionProfileInfo(connectionProfile) {

    if (connectionProfile == null) {
        return "";
    }

    try {
        var returnString = "ProfileName: " + connectionProfile.profileName + "\n\r";

        switch (connectionProfile.getNetworkConnectivityLevel()) {
            case networkConnectivityInfo.none:
                returnString += "Connectivity Level: None\n\r";
                break;
            case networkConnectivityInfo.localAccess:
                returnString += "Connectivity Level: Local Access\n\r";
                break;
            case networkConnectivityInfo.constrainedInternetAccess:
                returnString += "Connectivity Level: Constrained Internet Access\n\r";
                break;
            case networkConnectivityInfo.internetAccess:
                returnString += "Connectivity Level: Internet Access\n\r";
                break;
        }

        //Display Connection cost info
        returnString += "Connection Cost Information:\n\r";
        returnString += "===============\n\r";
        var connectionCost = connectionProfile.getConnectionCost();
        returnString += "Cost Type: " + GetCostType(connectionCost.networkCostType) + "\n\r";
        returnString += "Roaming: " + connectionCost.roaming + "\n\r";
        returnString += "Over Datalimit: " + connectionCost.overDataLimit + "\n\r";
        returnString += "Approaching Datalimit: " + connectionCost.approachingDataLimit + "\n\r";

        //Display Dataplan status info
        returnString += "Dataplan Status Information:\n\r";
        returnString += "===============\n\r";
        var dataPlanStatus = connectionProfile.getDataPlanStatus();
        if (dataPlanStatus.dataPlanUsage != null) {
            returnString += "Usage In Megabytes: " + dataPlanStatus.dataPlanUsage.megabytesUsed + "\n\r";
            returnString += "Last Sync Time: " + dataPlanStatus.dataPlanUsage.lastSyncTime + "\n\r";
        }
        else {
            returnString += "Dataplan Usage: " + "Not Defined" + "\n\r";
        }

        if (dataPlanStatus.InboundBitsPerSecond != null) {
            returnString += "Inbound Bits Per Second: " + dataPlanStatus.InboundBitsPerSecond + "\n\r";
        }
        else {
            returnString += "Inbound Bits Per Second: " + "Not Defined" + "\n\r";
        }

        if (dataPlanStatus.OutboundBitsPerSecond != null) {
            returnString += "Outbound Bits Per Second: " + dataPlanStatus.OutboundBitsPerSecond + "\n\r";
        }
        else {
            returnString += "Outbound Bits Per Second: " + "Not Defined" + "\n\r";
        }

        if (dataPlanStatus.dataLimitInMegabytes != null) {
            returnString += "Data Limit In Megabytes: " + dataPlanStatus.dataLimitInMegabytes + "\n\r";
        }
        else {
            returnString += "Data Limit In Megabytes: " + "Not Defined" + "\n\r";
        }

        if (dataPlanStatus.nextBillingCycle != null) {
            returnString += "Next Billing Cycle: " + dataPlanStatus.nextBillingCycle + "\n\r";
        }
        else {
            returnString += "Next Billing Cycle: " + "Not Defined" + "\n\r";
        }

        if (dataPlanStatus.maxDownloadFileSizeInMegabytes != null) {
            returnString += "Maximum Download File Size in Megabytes: " + dataPlanStatus.maxDownloadFileSizeInMegabytes + "\n\r";
        }
        else {
            returnString += "Maximum Download File Size in Megabytes: " + "Not Defined" + "\n\r";
        }
            returnString += "Cost Based Suggestions: " + CostBasedSuggestions(connectionCost) + "\n\r";
        }

    catch (e) {
        mySample.displayError("Exception Caught: " + e + "\n\r");
    }

    return returnString;
}

Resumo

Neste tópico, revisamos como recuperar perfis de conexão, bem como as informações de conectividade que cada perfil contém. Usar essas informações para ajudar o aplicativo a fazer as escolhas certas é essencial para uma experiência de conexão confiável.

Para obter diretrizes adicionais e conhecer as práticas recomendadas para usar informações de conexão para orientar o comportamento do aplicativo conectado em rede, veja Como gerenciar eventos de conexão de rede e mudanças na disponibilidade.