Guia de início rápido: recuperando informações de conexão de rede (aplicativos da Windows Store em JavaScript e HTML)

Este tópico mostrará a você como recuperar detalhes de conectividade e informações de uso para conexões da rede em um dispositivo.

Pré-requisitos

Os exemplos a seguir usam JavaScript e se baseiam na Amostra de informações de rede. Para obter ajuda para criar seu primeiro aplicativo, consulte Criar seu primeiro aplicativo da Windows Store em JavaScript.

Para garantir que o aplicativo da Windows Store está pronto para a rede, defina a capacidade no arquivo Package.appxmanifest do projeto. Para obter uma definição de cada recurso de rede, veja Como configurar recursos de isolamento de rede.

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 do ConnectionProfile, o aplicativo da Windows Store 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 receber notificações sobre essas mudanças, veja Guia de início rápido: gerenciando eventos de conexão 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 Guia de início rápido: gerenciando restrições de custo em redes limitadas.

Recuperando perfis de conexão

Primeiro, definimos algumas variáveis, uma instância do NetworkInformation, que define os métodos usados pelo aplicativo para recuperar um ConnectionProfile. Em seguida, uma instância do NetworkCostType, que define os possíveis tipos de custo da rede expressos por um ConnectionProfile.

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

A classe NetworkInformation define dois métodos para recuperação do ConnectionProfile. O método GetInternetConnectionProfile retornará apenas o perfil associado à conexão com a Internet.

function DisplayInternetConnectionProfileInfo() {
    try {
        var internetProfile = networkInfo.getInternetConnectionProfile();
        mySample.displayStatus(GetConnectionProfileInfo(internetProfile));
    }
    catch (e) {
        mySample.displayError("Exception Caught: " + e + "\n\r");
    }
}

Chamar o método GetConnectionProfiles recupera perfis para todas as conexões estabelecidas atualmente no dispositivo, incluindo a conexão com a Internet.

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

                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

Em cada ConnectionProfile, as informações de conexão a seguir podem ser acessadas:

Quando um ConnectionProfile é transmitido, a seguinte função de exemplo chama os métodos definidos pelo objeto para recuperar informações de estado e uso da conexão.

function GetConnectionProfileInfo(connectionProfile) {

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

        var returnString = "ProfileName: " + connectionProfile.profileName + "\n\r";
        returnString += "Connected: " + connectionProfile.connected + "\n\r";

        //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 Guia de início rápido: gerenciando eventos de conexão e mudanças na disponibilidade.

Tópicos relacionados

Amostra de Informações da rede

Guia de início rápido: gerenciando eventos de conexão e mudanças na disponibilidade

Como recuperar dados de uso da conexão para um período específico

Como recuperar um adaptador de rede e informações de localidade