DeviceServicingTrigger class

Applies to Windows only

Represents an event that an application can trigger to initiate a long-running update (firmware or settings) of a device.

Windows 8.1 enables you to develop Windows Store apps for your peripheral devices that communicate over USB, HID, and Bluetooth. For example, a user might need to sync content on a PC to or from the device, or perform a long-running update to the device itself like settings or firmware updates. Windows 8.1 provides two background tasks and corresponding APIs that allow your device to sync and update in the background: DeviceServicingTrigger and DeviceUseTrigger. This topic provides API reference information for DeviceServicingTrigger - for info on using this trigger in the context of a device app, see Device sync and update for Windows Store device apps.

The DeviceServicingTrigger background task allows your Windows Store app that interacts with your peripheral device to perform long running device updates while your app is suspended, for example settings transfers or firmware updates. Updating your device in the background requires user approval each time the background task is used. Unlike the DeviceUseTrigger background task, the DeviceServicingTrigger background task allows for device reboot and disconnect and allows a maximum of 30 minutes of background activity.

Syntax


var deviceServicingTrigger = new Windows.ApplicationModel.Background.DeviceServicingTrigger();

Attributes

[MarshalingBehavior(Agile)]
[Threading(Both)]
[Version(0x06030000)]

Members

The DeviceServicingTrigger class has these types of members:

Constructors

The DeviceServicingTrigger class has these constructors.

ConstructorDescription
DeviceServicingTrigger Constructor for DeviceServicingTrigger. Takes no parameters.

 

Methods

The DeviceServicingTrigger class has these methods. With C#, Visual Basic, and C++, it also inherits methods from the Object class.

MethodDescription
RequestAsync(String,TimeSpan) Triggers the background task (settings or firmware update) and returns a DeviceTriggerResult indicating success or failure of the trigger request. Takes the DeviceInformation.ID string and an optional estimated time the background task will run.
RequestAsync(String,TimeSpan,String) Triggers the background task (settings or firmware update) and returns a DeviceTriggerResult indicating success or failure of the trigger request. Takes the DeviceInformation.ID string, an optional estimated time the background task will run, and an optional app-specific string passed to the background task identifying which device operation to perform.

 

Remarks

The device path passed to the RequestAsync method must match the device that will perform the background operation. The device path is used by Windows to ensure that policy requirements are met.

The optional TimeSpan parameter to the RequestAsync method takes an estimated time that the background device operation will run. If the time estimate parameter is provided, it will be displayed to the user in the system consent dialog when the task is triggered by your app. If you cannot determine an appropriate time estimate, provide zero as the estimated time.

Certain policies are enforced by Windows to ensure user consent when updating their peripheral devices. Additional polices are enforced to preserve user battery life when syncing and updating peripheral devices. The DeviceServicingTrigger background task is subject to the following policies:

  • The DeviceServicingTrigger background task requires user consent every time it's triggered.
  • Your device must be connected or paired with the PC and available when requesting the DeviceServicingTrigger.
  • Your app is allowed a maximum of 30 minutes (wall clock) of background activity for device updates with DeviceServicingTrigger
  • Your app is not allowed to request a DeviceServicingTrigger background task while your app is not in the foreground.
  • Your app can only run one DeviceServicingTrigger at a time. Attempting to create a second DeviceServicingTrigger will raise an exception.
  • The PC's battery must have more than 33% capacity remaining, or the PC must be on A/C power.
  • DeviceServicingTrigger background tasks may be canceled by Windows when these policy requirements are no longer met, including a maximum amount of wall clock background time.

Note  Windows Store apps that intend to use the DeviceServicingTrigger background task must also be a privileged app for the device. App privilege is specified in the device metadata for a peripheral device by the device manufacturer. When a Windows Store app attempts to trigger the DeviceServicingTrigger background task, Windows will validate that the calling app is the privileged app for the device it is attempting to update. If the app is not privileged for the device then Windows will not allow the background task to launch.

For detailed information about app privilege and the policy checks enforced by Windows for the DeviceServicingTrigger background task see Device sync and update for Windows Store device apps.

Requirements

Minimum supported client

Windows 8.1 [Windows Store apps only]

Minimum supported server

Windows Server 2012 R2 [Windows Store apps only]

Minimum supported phone

None supported

Namespace

Windows.ApplicationModel.Background
Windows::ApplicationModel::Background [C++]

Metadata

Windows.winmd

See also

Object
IBackgroundTrigger

 

 

Show:
© 2014 Microsoft