BluetoothLEAdvertisementWatcherTrigger Class

Definition

Namespace:

Windows.ApplicationModel.Background

Represents a trigger that is registered to scan for Bluetooth LE advertisement in the background.

public ref class BluetoothLEAdvertisementWatcherTrigger sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class BluetoothLEAdvertisementWatcherTrigger final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class BluetoothLEAdvertisementWatcherTrigger

function BluetoothLEAdvertisementWatcherTrigger()

Public NotInheritable Class BluetoothLEAdvertisementWatcherTrigger

Inheritance

Object Platform::Object IInspectable BluetoothLEAdvertisementWatcherTrigger

Attributes

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implements

IBackgroundTrigger

Windows requirements

Device family	Windows 10 (introduced in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v1.0)

Remarks

A background task is launched when an advertisement is received.

This trigger works similarly to the BluetoothAdvertisementWatcher class, with the exception that it has more restrictions as it allows the app to receive advertisements in the background. Notably, exactly a single filter pattern is accepted in the background (not more, not less).

Once registered, the background watcher is serviced in a best effort manner. A background task will be launched to notify the app when an advertisement matching the filter configured through trigger is received. The app is also notified of failures or interruption of the background watcher through the trigger details provided in the background task context. To stop receiving the advertisements, the background task associated with this trigger must be unregistered.

The following advertisement types are not allowed to be filtered for in the background due to their generic nature

• Flags (0x01)
• Class of Device (0x0D)
• Security Manager Out-of-Band Flags (0x11)
• Appearance (0x19)
• LE Role (0x1C)

A background filter for a raw section of type manufacturer specific data (0xFF) that only matches for the second byte of the section with 0x00 will be rejected, as it corresponds to the most significant byte of the company identifier field. All SIG-assigned company identifiers currently have this byte set to 0x00 and performing a partial match with only a single byte can potentially result in an excess of received advertisements when in presence of multiple advertisers. This could significantly impact the battery life of the system.

Use of a BluetoothLEAdvertisementWatcherTrigger is limited by the hardware offload resources available. New Windows devices with HCI Extensions support in the local Bluetooth radio provide lower power advertisement scanning, improving battery life for long term scenarios such as beacons. The amount of hardware resources available is dependent on the radio and current system-wide usage, and attempts to register for this trigger will return BluetoothError.ResourceInUse when no more resources are available. Apps should use these resources sparingly to provide a focused, power efficient scenario in watching for the unique advertisement data for only the specific remote advertisers which are needed.

While many new Windows devices have HCI Extensions support, some may not, especially in cases of upgrades on older devices from older Windows versions. In these cases, Windows will emulate the hardware filtering in software, providing a maximum of 20 trigger conditions per device, across all apps on the system. When using this software emulation, attempts to register for trigger resources once the maximum has been reached will cause an exception to be thrown, with error ERROR_NO_SYSTEM_RESOURCES (0x800705AA).

Version history

Windows version	SDK version	Value added
2004	19041	AllowExtendedAdvertisements

Constructors

BluetoothLEAdvertisementWatcherTrigger()

Creates a new instance of the BluetoothLEAdvertisementWatcherTrigger class.

Properties

AdvertisementFilter	Gets or sets the configuration of Bluetooth LE advertisement filtering that uses payload section-based filtering.
AllowExtendedAdvertisements	Enables reception of advertisements using the Extended Advertising format. Defaults to False.
MaxOutOfRangeTimeout	Gets the maximum out of range timeout supported for the SignalStrengthFilter property of this trigger.
MaxSamplingInterval	Gets the maximum sampling interval supported for the SignalStrengthFilter property of this trigger. The maximum sampling interval is used to deactivate the sampling filter and only trigger received events based on the device coming in and out of range.
MinOutOfRangeTimeout	Gets the minimum out of range timeout supported for the SignalStrengthFilter property of this trigger.
MinSamplingInterval	Gets the minimum sampling interval supported for the SignalStrengthFilter property of this trigger. The minimum sampling interval for the background watcher cannot be zero unlike its foreground counterpart.
SignalStrengthFilter	Gets or sets the configuration of Bluetooth LE advertisement filtering that uses signal strength-based filtering.

See also

• IBackgroundTrigger