DeviceWatcher DeviceWatcher DeviceWatcher DeviceWatcher Class

Definition

Enumerates devices dynamically, so that the app receives notifications if devices are added, removed, or changed after the initial enumeration is complete.

public : sealed class DeviceWatcher : IDeviceWatcher, IDeviceWatcher2
public sealed class DeviceWatcher : IDeviceWatcher, IDeviceWatcher2
Public NotInheritable Class DeviceWatcher Implements IDeviceWatcher, IDeviceWatcher2
// This class does not provide a public constructor.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Examples

For complete implementations in C#, C++, and JavaScript, see the Device enumeration and pairing sample.

This example incrementally enumerates devices, adding them to a list each time a device is found, and also handling removals and updates. The onAdded function that handles the added event takes a DeviceInformation object. Once enumeration is complete, the app prints a list of devices. The app also prints a message if devices are added, updated, or removed after the initial enumeration completes.


<!DOCTYPE html>
<html>
<head>
    <title>Device Enumeration Sample</title>
    <script>
   var watcher;
    var deviceArray = new Array(); // Saves the enumeration results.

    function WatchDevices() {
        try {
            output.innerHTML = ""; // Clears output field.

            watcher = 
                Windows.Devices.Enumeration.DeviceInformation.createWatcher();
            // Add event handlers
            watcher.addEventListener("added", onAdded);
            watcher.addEventListener("removed", onRemoved);
            watcher.addEventListener("updated", onUpdated);
            watcher.addEventListener("enumerationcompleted", 
                onEnumerationCompleted);
            watcher.addEventListener("stopped", onStopped);
            // Start enumerating and listening for events
            watcher.start();
        } catch (e) {
            document.getElementById("statusMessage").innerHTML = 
                "Failed to create watcher, error: " + e.message;
        }
    }

    function stopWatcher() {
        try {
            watcher.stop();
        }
        catch (e) {
            document.getElementById("statusMessage").innerHTML = 
                "Failed to stop watcher: " + e.message;
        }
    }

    function onAdded(devinfo) {
        document.getElementById("output").innerHTML += "<p>Device added: " + 
            devinfo.name + "</p>";
        deviceArray.push(devinfo);
    }

    function onUpdated(devUpdate) {
        document.getElementById("output").innerHTML += "<p>Device updated.</p>";
        for (var i = 0; i < deviceArray.length; i++) {
            if (deviceArray[i].id == devUpdate.id) {
                deviceArray[i].update(devUpdate);
            }
        }
    }

    function onRemoved(devupdate) {
        document.getElementById("output").innerHTML += "<p>Device removed.</p>";
        for (var i = 0; i < deviceArray.length; i++) {
            if (deviceArray[i].id == devupdate.id) {
                deviceArray[i].slice(devupdate);
            }
        }
    }

    function onEnumerationCompleted(obj) {
        document.getElementById("output").innerHTML += 
            "<p>Enumeration Completed.</p>";
        printDeviceArray(document.getElementById("output"));
    }

    function onStopped(obj) {
        document.getElementById("output").innerHTML += "<p>Stopped.</p>";
    }


    // Prints the friendly name of the device interface, 
    // its ID (device interface path), and whether it is enabled.
    function printDevice(deviceInterface, outputDestination) {
        outputDestination.innerHTML += "<p>Name: " + 
            deviceInterface.name + "<p/>"; 
        outputDestination.innerHTML += "<p>Interface ID: " + 
            deviceInterface.id + "<p/>";    
        outputDestination.innerHTML += "<p>Enabled: " + 
            deviceInterface.isEnabled + "<p/>";
        outputDestination.innerHTML += "<br/>";
    }

    function printDeviceArray(outputDestination) {
        for (var i = 0; i < deviceArray.length; i++) {
            printDevice(deviceArray[i], outputDestination);
        }
    }

    </script>
</head>
<body role="application">
    <h1>Device Enumeration Sample</h1>
    <h2 >Input</h2>
    <div >            
            <div >
            <p>This example incrementally enumerates devices, adding them to a list each time a device is found, and also watching for updates.
               Once enumeration is complete, the list of devices is printed.</p> 
                <input type="button" value="Watch(All Devices)" onclick="WatchDevices()"/>
                <br/><br/>

                <input type="button" value="Stop" onclick="stopWatcher()"/>
                <br/><br/>
            </div>
    </div>

    <h2 > Output</h2>
            <div id="statusMessage"></div>
            <!--  Output -->
            <div  id="output"></div>
</body>
</html>

Remarks

An app calls Start to begin the search for devices. During this intial enumeration, the DeviceWatcher raises an Added event for each device that's found, until all devices are found. The DeviceWatcher raises an EnumerationCompleted event when the initial enumeration is complete, and continues to raise events if a device is added, updated, or removed.

The following diagram shows how the DeviceWatcher transitions between the states represented by DeviceWatcherStatus enumeration.

state diagram of DeviceWatcher states

The Start method can only be called when the DeviceWatcher is in the Created, Stopped or Aborted state. The Status property indicates the DeviceWatcher state. When re-starting the watcher, wait for the Stopped event before calling Start.

Stop transitions the DeviceWatcher to the Stopping state and completes immediately. The watcher will transition to the Stopped state once all events that are already in the process of being raised have completed.

Apps may wait for the Stopped event if they need to know when the DeviceWatcher has stopped. Callers must wait for the Stopped event before they can call Start to restart the watcher. Callers may unsubscribe from events if they do not want to receive any additional events after Stop but do not want to wait for the Stopped event.

Note

An app must subscribe to all of the added, removed, and updated events to be notified when there are device additions, removals or updates. If an app handles only the added event, it will not receive an update if a device is added to the system after the initial device enumeration completes.

Properties

Status Status Status Status

The status of the DeviceWatcher.

public : DeviceWatcherStatus Status { get; }
public DeviceWatcherStatus Status { get; }
Public ReadOnly Property Status As DeviceWatcherStatus
var deviceWatcherStatus = deviceWatcher.status;

Methods

GetBackgroundTrigger(IIterable) GetBackgroundTrigger(IIterable) GetBackgroundTrigger(IIterable) GetBackgroundTrigger(IIterable)

Gets a DeviceWatcherTrigger object monitoring for changes to the list of devices.

public : DeviceWatcherTrigger GetBackgroundTrigger(IIterable<DeviceWatcherEventKind> requestedEventKinds)
public DeviceWatcherTrigger GetBackgroundTrigger(IEnumerable<DeviceWatcherEventKind> requestedEventKinds)
Public Function GetBackgroundTrigger(requestedEventKinds As IEnumerable<DeviceWatcherEventKind>) As DeviceWatcherTrigger
var deviceWatcherTrigger = deviceWatcher.getBackgroundTrigger(requestedEventKinds);
Parameters
requestedEventKinds
IIterable<DeviceWatcherEventKind> IEnumerable<DeviceWatcherEventKind> IEnumerable<DeviceWatcherEventKind> IEnumerable<DeviceWatcherEventKind>

A list of the specific updates you want to monitor.

Returns

The watcher trigger to monitor for the specified changes.

Start() Start() Start() Start()

Starts a search for devices, and subscribes to device enumeration events.

public : void Start()
public void Start()
Public Function Start() As void
deviceWatcher.start();

Remarks

An app calls Start to begin the search for devices. During this intial enumeration, the DeviceWatcher raises an Added event for each device that's found, until all devices are found. The DeviceWatcher raises an EnumerationCompleted event when the initial enumeration is complete, and continues to raise events if a device is added, updated, or removed.

The Start method can only be called when the DeviceWatcher is in the Created, Stopped or Aborted state. The Status property indicates the DeviceWatcher state. When re-starting the watcher, wait for the Stopped event before calling Start. The following diagram shows how the DeviceWatcher transitions between the states represented by DeviceWatcherStatus enumeration.

state diagram of DeviceWatcher states

Stop() Stop() Stop() Stop()

Stop raising the events that add, update and remove enumeration results.

public : void Stop()
public void Stop()
Public Function Stop() As void
deviceWatcher.stop();

Remarks

To stop a search for devices, an app calls Stop and enters the Stopping state. The Stopped event is raised when the Stop operation completes and the DeviceWatcher enters the Stopped state.

The following diagram shows how the DeviceWatcher transitions between the states represented by DeviceWatcherStatus enumeration.

state diagram of DeviceWatcher states

This call transitions the DeviceWatcher to the Stopping state and completes immediately. The watcher will transition to the Stopped state once all events that are already in the process of being raised have completed.

Callers may wait for the Stopped event if they need to know when the DeviceWatcher has stopped. Callers must wait for the Stopped event before they can call Start to restart the watcher. Callers may unsubscribe from events if they do not want to receive any additional events after Stop but do not want to wait for the Stopped event.

Events

Added Added Added Added

Event that is raised when a device is added to the collection enumerated by the DeviceWatcher.

public : event TypedEventHandler Added<DeviceWatcher,  DeviceInformation>
public event TypedEventHandler Added<DeviceWatcher,  DeviceInformation>
Public Event TypedEventHandler Added( Of ( Of DeviceWatcher ), ( Of  DeviceInformation ))
function onAdded(eventArgs){/* Your code */}


deviceWatcher.addEventListener("added", onAdded);
deviceWatcher.removeEventListener("added", onAdded);

Remarks

Note

An app must subscribe to all of the added, removed, and updated events to be notified when there are device additions, removals or updates. If an app handles only the added event, it will not receive an update if a device is added to the system after the initial device enumeration completes.

See Also

EnumerationCompleted EnumerationCompleted EnumerationCompleted EnumerationCompleted

Event that is raised when the enumeration of devices completes.

public : event TypedEventHandler EnumerationCompleted<DeviceWatcher,  object>
public event TypedEventHandler EnumerationCompleted<DeviceWatcher,  object>
Public Event TypedEventHandler EnumerationCompleted( Of ( Of DeviceWatcher ), ( Of  object ))
function onEnumerationCompleted(eventArgs){/* Your code */}


deviceWatcher.addEventListener("enumerationCompleted", onEnumerationCompleted);
deviceWatcher.removeEventListener("enumerationCompleted", onEnumerationCompleted);
See Also

Removed Removed Removed Removed

Event that is raised when a device is removed from the collection of enumerated devices.

public : event TypedEventHandler Removed<DeviceWatcher,  DeviceInformationUpdate>
public event TypedEventHandler Removed<DeviceWatcher,  DeviceInformationUpdate>
Public Event TypedEventHandler Removed( Of ( Of DeviceWatcher ), ( Of  DeviceInformationUpdate ))
function onRemoved(eventArgs){/* Your code */}


deviceWatcher.addEventListener("removed", onRemoved);
deviceWatcher.removeEventListener("removed", onRemoved);

Remarks

Note

An app must subscribe to all of the added, removed, and updated events to be notified when there are device additions, removals or updates. If an app handles only the added event, it will not receive an update if a device is added to the system after the initial device enumeration completes.

See Also

Stopped Stopped Stopped Stopped

Event that is raised when the enumeration operation has been stopped.

public : event TypedEventHandler Stopped<DeviceWatcher,  object>
public event TypedEventHandler Stopped<DeviceWatcher,  object>
Public Event TypedEventHandler Stopped( Of ( Of DeviceWatcher ), ( Of  object ))
function onStopped(eventArgs){/* Your code */}


deviceWatcher.addEventListener("stopped", onStopped);
deviceWatcher.removeEventListener("stopped", onStopped);

Updated Updated Updated Updated

Event that is raised when a device is updated in the collection of enumerated devices.

public : event TypedEventHandler Updated<DeviceWatcher,  DeviceInformationUpdate>
public event TypedEventHandler Updated<DeviceWatcher,  DeviceInformationUpdate>
Public Event TypedEventHandler Updated( Of ( Of DeviceWatcher ), ( Of  DeviceInformationUpdate ))
function onUpdated(eventArgs){/* Your code */}


deviceWatcher.addEventListener("updated", onUpdated);
deviceWatcher.removeEventListener("updated", onUpdated);

Remarks

Note

An app must subscribe to all of the added, removed, and updated events to be notified when there are device additions, removals or updates. If an app handles only the added event, it will not receive an update if a device is added to the system after the initial device enumeration completes.

See Also