Guia de início rápido: enumerando dispositivos usados com frequência (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]

O namespace Windows.Devices.Enumeration oferece dois métodos para enumerar dispositivos: FindAllAsync e CreateWatcher. O FindAllAsync faz uma pesquisa única dos dispositivos disponíveis e é melhor para aplicativos que não precisam de atualizações quando o usuário adiciona, exclui ou modifica um dispositivo. O CreateWatcher enumera dispositivos e aciona eventos de notificação quando um usuário adiciona, exclui ou modifica um dispositivo depois que o sistema operacional conclui a enumeração inicial. Aqui, nós mostramos como realizar uma enumeração única dos dispositivos normalmente usados por meio do FindAllAsync.

Objetivo: Listar os dispositivos disponíveis em categorias de dispositivos comuns usando o namespace Windows.Devices.Enumeration.

Pré-requisitos

Nós supomos que você já esteja familiarizado com JavaScript e HTML.

Tempo para conclusão: 20 minutos.

Instruções

1. Abrir o Microsoft Visual Studio

Abra uma instância do Visual Studio.

2. Crie um novo projeto

Na caixa de diálogo Novo Projeto, selecione um aplicativo em branco nos tipos de projeto JavaScript.

3. Insira o HTML do aplicativo

Abra Default.html e copie esse código no arquivo, substituindo seu conteúdo.

Esse HTML oferece uma interface do usuário que permite aos usuários selecionarem sete tipos de dispositivos para enumerar: microfones, reprodução de áudio, webcams, armazenamentos removíveis, serviços de dispositivos MTP, dispositivos SMS e dispositivos de proximidade.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <script src="/js/default.js"></script>
</head>
<body data-design-activate="defaultPage.activated">
    <h1>Device Enumeration Sample</h1>

    <h2 >Input</h2>

    <div>            

        <div id="Input">
           <p>This scenario demonstrates using the device enumeration API
              to look for specific device interfaces. A device interface
              is the programmatic entry point for a device.</p>
           <p>Select a device interface class</p>
                <select id="SelectInterfaceClass" size="7" >
                    <option value="audioCapture">Audio Capture</option>
                    <option value="audioRender">Audio Playback</option>
                    <option value="videoCapture">Webcams</option>
                    <option value="portableStorageDevice">Portable Storage</option>
                    <option value="mtpService">MTP Device Service</option>
                    <option value="sms">SMS Device</option>
                    <option value="proximity">Proxmity Device</option>
                </select>
                <br />
                <p>Clicking the enumerate button will start a search for 
                 device interfaces that belong to the specified device interface class. 
                 The device interfaces will be listed below.</p>
          <input onclick="onEnumerateDeviceInterfaces()" type="button" value="Enumerate" />
                <br /><br />
            </div>
    </div>


    <h2> Output</h2>

            <div id="statusMessage"></div>

            <!-- Device Enumeration results are displayed in this element -->
            <div  id="Output"></div>
</body>
</html>

4. Insira o JavaScript do aplicativo

Abra o arquivo Default.js e insira este código.

De acordo com o tipo de dispositivo selecionado pelo usuário, a função onEnumerateDeviceInterface escolhe um valor de DeviceClass ou obtém uma cadeia de caracteres do seletor de uma função getDeviceSelector. O aplicativo passa então esse valor para FindAllAsync. A função successCallback imprime as informações do dispositivo quando a enumeração tem sucesso, e a função errorCallback imprime uma mensagem de erro quando a enumeração falha.

function onEnumerateDeviceInterfaces() {
    document.getElementById("Output").innerHTML = ""; // clear output
    try {
        var selection = document.getElementById("SelectInterfaceClass");
        var selectedDeviceClass = 
            selection.options[selection.selectedIndex].value;
        var deviceClass;
        var Enumeration = Windows.Devices.Enumeration;
        var selectorString = "";

        var mtpServiceDevice = Windows.Devices.Portable.ServiceDevice;
        var smsDevice = Windows.Devices.Sms.SmsDevice;
        var proximityDevice = Windows.Networking.Proximity.ProximityDevice;
        switch (selectedDeviceClass) {
            case "audioCapture":
                // same as:
                // var mediaDevice = Windows.Media.Devices.MediaDevice;
                // selectorString =  mediaDevice.getAudioCaptureSelector();
                deviceClass = Enumeration.DeviceClass.audioCapture;
                break;
            case "audioRender":
                // same as:
                // var mediaDevice = Windows.Media.Devices.MediaDevice;
                // selectorString =  mediaDevice.getAudioRenderSelector();
                deviceClass = Enumeration.DeviceClass.audioRender;
                break;
            case "portableStorageDevice":
                // same as: 
                // var storageDevice = Windows.Devices.Portable.StorageDevice;
                // selectorString = storageDevice.getDeviceSelector();
                deviceClass = Enumeration.DeviceClass.portableStorageDevice;
                break;
            case "videoCapture":
                // same as:
                // var mediaDevice = Windows.Media.Devices.MediaDevice;
                // selectorString =  mediaDevice.getVideoCaptureSelector();
                deviceClass = Enumeration.DeviceClass.videoCapture;
                break;
            case "mtpService":
            // Windows.Devices.Portable.ServiceDevice.getDeviceSelector
                selectorString = mtpServiceDevice.getDeviceSelector(Windows.Devices.Portable.ServiceDeviceType.calendarService);
                break;
            case "sms":
            // Windows.Devices.Sms.SmsDevice.getDeviceSelector
                selectorString = smsDevice.getDeviceSelector();
                break;
            case "proximity":
            // Windows.Networking.Proximity.ProximityDevice.getDeviceSelector
                selectorString = proximityDevice.getDeviceSelector();
                break;
            case "imageScanner":
            // same as:
            // var scannerDevice = Windows.Devices.Scanners.ImageScanner;
            // selectorString = scannerDevice.getDeviceSelector();
                deviceClass = Enumeration.DeviceClass.imageScanner;
                break;
            default: deviceClass = Enumeration.DeviceClass.all;
        }

        var DeviceInformation = Enumeration.DeviceInformation;
        if (selectorString == "") {
            DeviceInformation.findAllAsync(deviceClass).then(
                successCallback, 
                errorCallback
            );
        } else {
            DeviceInformation.findAllAsync(selectorString, null).then(
                successCallback, 
                errorCallback
            );
        }
    } catch (e) {
        document.getElementById("statusMessage").innerHTML = 
            "Failed to enumerate devices, error: " + e.message;
    }
}

// Handles successful completion of the findAllAsync method.
function successCallback(deviceInformationCollection) {
    var numDevices = deviceInformationCollection.length;
    document.getElementById("statusMessage").innerHTML = 
        numDevices + " device interface(s) found";
    if (numDevices) {
        for (var i = 0; i < numDevices; i++) {
            printFriendlyNameAndID(deviceInformationCollection[i], 
                document.getElementById("Output"));
        }
    } else {
        document.getElementById("statusMessage").innerHTML = "No devices found";
    }
}

// Handles an error completion of the findAllAsync method.
function errorCallback(e) {
    document.getElementById("statusMessage").innerHTML = 
        "Failed to find devices, error: " + e.message;
}

// Prints the friendly name of the device interface and its ID 
// The ID is the device interface path.
function printFriendlyNameAndID(deviceInterface, log) {

    // The name property is equivalent to System.ItemNameDisplay property
    log.innerHTML += "<h3>" + 
            deviceInterface.name + "<h3/>";
    log.innerHTML += "<p>Interface ID: " + deviceInterface.id;    
    log.innerHTML += "<p>Enabled: " + deviceInterface.isEnabled;
    
    log.innerHTML += "<br />";
}

Observação

Para as quatro primeiras opções, você pode passar um valor de enumeração de DeviceClass para FindAllAsync. Isso é o mesmo que obter uma cadeia de caracteres do seletor da API de Tempo de Execução do Windows associada ao tipo de dispositivo e passar o seletor para FindAllAsync. O código para usar a cadeia de caracteres do seletor em vez da enumeração de DeviceClass é comentado nos casos relevantes na instrução switch.

Para as três últimas opções, não há um valor de enumeração de DeviceClass, então é mostrada apenas a chamada à API para obter a cadeia de caracteres do seletor apropriada.

5. Compile o aplicativo

No menu Compilação, clique em Compilar Solução para compilar o projeto.

6. Teste o aplicativo

No menu Depurar, clique em Iniciar Depuração para testar a solução.
Escolha a classe de interface de dispositivo que deve ser enumerada.
Clique no botão Enumerar para começar uma pesquisa de interfaces de dispositivo que pertencem à classe de interface de dispositivo especificada. O aplicativo lista as interfaces de dispositivo na metade inferior da página criada.

7. Adicionar sua própria funcionalidade de dispositivo (opcional)

Para começar a acessar as funcionalidades do dispositivo em vez de apenas listar os dispositivos, passe a propriedade DeviceInformation.id de um dispositivo que você enumerou para a API de Tempo de Execução do Windows para usar o dispositivo. Por exemplo, você pode usar a identificação de uma webcam enumerada para definir a propriedade Windows.Media.Capture.MediaCaptureInitializationSettings.VideoDeviceId e especificar a webcam a ser usada para captura de vídeo.

Adicione os recursos que você precisa ao arquivo package.appxmanifest do projeto.
Comece passando a ID do dispositivo para uma API que você possa usar para interagir com o dispositivo. Estes são alguns métodos que usam a ID do dispositivo para iniciar um objeto para usar um dispositivo:
Para dispositivos WPD que usam um serviço de dispositivos MTP (enumerados usando Windows.Devices.Portable.ServiceDevice.GetDeviceSelector ou Windows.Devices.Portable.ServiceDevice.GetDeviceSelectorFromServiceId), você pode criar um objeto de Automação COM para trabalhar como o dispositivo, assim:

deviceFactory = new ActiveXObject("PortableDeviceAutomation.Factory");

var device = deviceFactory.getDeviceFromId(deviceId);

Resumo e próximas etapas

Você acabou de aprender como enumerar tipos de dispositivos comuns, passando um valor de enumeração de Windows.Device.Enumeration.DeviceClass ou uma cadeia de caracteres do seletor de um método getDeviceSelector para findAllAsync.

Quando a classe de interface de dispositivo desejada não está na enumeração de Windows.Device.Enumeration.DeviceClass e não existe uma API de Tempo de Execução do Windows para obter um seletor, você tem que compilar uma cadeia de caracteres AQS (Sintaxe de Consulta Avançada) e passá-la para findAllAsync.

Para compilar uma consulta por dispositivos disponíveis de determinado tipo, você tem que saber o GUID da classe do dispositivo. Este código inclui uma consulta por dispositivos disponíveis que pertencem a uma classe de interface de dispositivo especificada por um GUID que o usuário digitou em uma caixa de entrada. O GUID deve estar no formato "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}".

Observação Verifique se o GUID está entre aspas dentro da cadeia de caracteres do seletor. Por exemplo, var selectorString = "System.Devices.InterfaceClassGuid:=\"{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\"";.

        if (textinput.value != ""){
            var textDeviceInterfaceClassGUID = textinput.value;
            var selectorString = "System.Devices.InterfaceClassGuid:=\"" + 
                textDeviceInterfaceClassGUID + 
                "\" AND System.Devices.InterfaceEnabled:=true";
            var Enum = Windows.Devices.Enumeration;
            Enum.DeviceInformation.findAllAsync(selectorString, null).then(
                    successCallback, 
                    errorCallback
                );

// Handles successful completion of the findAllAsync method.
function successCallback(deviceInformationCollection) {
    // Add your code here for processing the enumerated device collection.
}

// Handles an error completion of the findAllAsync method.
function errorCallback(e) {
    // Add your error-handling code here.
}

Observação Esse exemplo fez uma enumeração única, mas isso não é suficiente para um aplicativo que precisa atualizar sua interface do usuário quando um usuário adiciona, remove ou modifica um dispositivo. O próximo tópico mostra como usar CreateWatcher para poder enumerar dispositivos e obter notificações deles.

Como enumerar dinamicamente