Table of Contents

Interface IBluetoothScanner

Namespace
Bluetooth.Abstractions.Scanning
Assembly
Bluetooth.Abstractions.Scanning.dll

Interface for managing and scanning Bluetooth devices.

public interface IBluetoothScanner : IAsyncDisposable
Inherited Members

Properties

AdvertisementFilter

Gets or sets the advertisement filter used to determine which Bluetooth advertisements should be processed.

Func<IBluetoothAdvertisement, bool>? AdvertisementFilter { get; set; }

Property Value

Func<IBluetoothAdvertisement, bool>

Remarks

When null (default), all advertisements are accepted. When set, only advertisements where the filter returns true are processed.

DeviceWrapper

Gets or sets an optional function that wraps a newly created device before it is added to the device list.

Func<IBluetoothRemoteDevice, IBluetoothAdvertisement, IBluetoothRemoteDevice?>? DeviceWrapper { get; set; }

Property Value

Func<IBluetoothRemoteDevice, IBluetoothAdvertisement, IBluetoothRemoteDevice>

Examples

scanner.DeviceWrapper = (device, advertisement) =>
    advertisement.Manufacturer == Manufacturer.Laerdal_Medical_AS
        ? new LaerdalDevice(device, advertisement)
        : null;

Remarks

Called once per new device, after the platform has created the raw IBluetoothRemoteDevice. Return a richer subtype (e.g. a product-specific device class) or null to keep the original device unchanged.

This follows the same pattern as AdvertisementFilter: set it once on the scanner instance, and the scanner calls it automatically for every new device.

IsRunning

Gets a value indicating whether the Bluetooth activity is actively running.

bool IsRunning { get; }

Property Value

bool

IsStarting

Gets a value indicating whether the Bluetooth activity is starting.

bool IsStarting { get; }

Property Value

bool

IsStopping

Gets a value indicating whether the Scanner is stopping.

bool IsStopping { get; }

Property Value

bool

Methods

CleanRestartScanningAsync(Func<IBluetoothAdvertisement, bool>?, ScanningOptions?, PermissionOptions?, TimeSpan?, CancellationToken)

Stops the scanner, discards every device in the scanner's registry, then starts scanning again.

Task CleanRestartScanningAsync(Func<IBluetoothAdvertisement, bool>? newAdvertisementFilter = null, ScanningOptions? scanningOptions = null, PermissionOptions? permissionOptions = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

newAdvertisementFilter Func<IBluetoothAdvertisement, bool>

An optional replacement for AdvertisementFilter, applied while the scanner is stopped so it is already in effect when scanning resumes. When null the current filter is left untouched.

scanningOptions ScanningOptions

The options to restart with. When null the options of the scan session being restarted are reused, falling back to defaults if the scanner was not running.

permissionOptions PermissionOptions

The options for requesting permissions. If null, default options will be used.

timeout TimeSpan?

The timeout applied to the stop and the start leg individually. Does not bound the registry-clear step in between.

cancellationToken CancellationToken

A cancellation token to cancel this operation.

Returns

Task

A task that represents the asynchronous clean restart operation.

Remarks

Unlike StopScanningAsync(TimeSpan?, CancellationToken) followed by StartScanningAsync(ScanningOptions?, PermissionOptions?, TimeSpan?, CancellationToken), this also drops the device registry, so devices discovered before the restart are gone: every device is disconnected, removed and disposed. Hold on to device identifiers rather than IBluetoothRemoteDevice instances across a clean restart, and re-acquire the instance afterwards with WaitForDeviceToAppearAsync(string, TimeSpan?, CancellationToken).

The intended use case is a device that changes identity while the scanner is running - most notably a device rebooting into or out of firmware-update mode, where a stale registry entry and an in-flight scan session otherwise prevent it from being rediscovered under its new advertisement.

Restarting a scanner that is already stopped is valid: the stop leg is skipped and the registry is still dropped.

Exceptions

ScannerFailedToStopException

Thrown when the scanner fails to stop.

ScannerFailedToStartException

Thrown when the scanner fails to start again.

TimeoutException

Thrown when either leg of the operation times out.

OperationCanceledException

Thrown when the operation is cancelled.

ClearDeviceAsync(IBluetoothRemoteDevice?)

Clears resources associated with a specific Bluetooth device.

ValueTask ClearDeviceAsync(IBluetoothRemoteDevice? device)

Parameters

device IBluetoothRemoteDevice

The device to clear.

Returns

ValueTask

A Task representing the asynchronous operation.

ClearDeviceAsync(string)

Clears resources associated with a Bluetooth device by its ID.

ValueTask ClearDeviceAsync(string deviceId)

Parameters

deviceId string

The ID of the device to clear.

Returns

ValueTask

A Task representing the asynchronous operation.

ClearDevicesAsync(IEnumerable<IBluetoothRemoteDevice>?)

Clears resources associated with Bluetooth devices. If no devices are specified, it clears all devices.

ValueTask ClearDevicesAsync(IEnumerable<IBluetoothRemoteDevice>? devices = null)

Parameters

devices IEnumerable<IBluetoothRemoteDevice>

The devices to clear, or null to clear all devices.

Returns

ValueTask

A Task representing the asynchronous operation.

GetClosestDeviceOrDefault(Func<IBluetoothRemoteDevice, bool>?)

Returns the closest Bluetooth device currently available.

IBluetoothRemoteDevice? GetClosestDeviceOrDefault(Func<IBluetoothRemoteDevice, bool>? filter = null)

Parameters

filter Func<IBluetoothRemoteDevice, bool>

An optional function to filter devices. Defaults to null for all devices.

Returns

IBluetoothRemoteDevice

The closest IBluetoothRemoteDevice, or null if none are found.

GetDevice(Func<IBluetoothRemoteDevice, bool>)

Gets the device that matches the specified filter.

IBluetoothRemoteDevice GetDevice(Func<IBluetoothRemoteDevice, bool> filter)

Parameters

filter Func<IBluetoothRemoteDevice, bool>

The filter to apply to the devices.

Returns

IBluetoothRemoteDevice

The device that matches the filter.

Exceptions

DeviceNotFoundException

Thrown if no device matches the specified filter.

MultipleDevicesFoundException

Thrown if multiple devices match the specified filter.

GetDevice(string)

Gets the device with the specified ID.

IBluetoothRemoteDevice GetDevice(string id)

Parameters

id string

The ID of the device to get.

Returns

IBluetoothRemoteDevice

The device with the specified ID.

Exceptions

DeviceNotFoundException

Thrown if no device matches the specified ID.

MultipleDevicesFoundException

Thrown if multiple devices match the specified ID.

GetDeviceOrDefault(Func<IBluetoothRemoteDevice, bool>)

Gets the device that matches the specified filter.

IBluetoothRemoteDevice? GetDeviceOrDefault(Func<IBluetoothRemoteDevice, bool> filter)

Parameters

filter Func<IBluetoothRemoteDevice, bool>

The filter to apply to the devices.

Returns

IBluetoothRemoteDevice

The device that matches the filter, or null if no such device exists.

Exceptions

MultipleDevicesFoundException

Thrown if multiple devices match the specified filter.

GetDeviceOrDefault(string)

Gets the device with the specified ID.

IBluetoothRemoteDevice? GetDeviceOrDefault(string id)

Parameters

id string

The ID of the device to get.

Returns

IBluetoothRemoteDevice

The device with the specified ID, or null if no such device exists.

Exceptions

MultipleDevicesFoundException

Thrown if multiple devices match the specified ID.

GetDevices(Func<IBluetoothRemoteDevice, bool>?)

Returns all Bluetooth devices that match the specified filter.

IReadOnlyList<IBluetoothRemoteDevice> GetDevices(Func<IBluetoothRemoteDevice, bool>? filter = null)

Parameters

filter Func<IBluetoothRemoteDevice, bool>

An optional function to filter devices. Defaults to null for all devices.

Returns

IReadOnlyList<IBluetoothRemoteDevice>

A read-only snapshot of devices at the time of the call. This collection is immutable and will not be modified if devices are added or removed after the call returns. To get updated results, call this method again or subscribe to DeviceListChanged event.

HasDevice(Func<IBluetoothRemoteDevice, bool>)

Checks if a device that matches the specified filter exists.

bool HasDevice(Func<IBluetoothRemoteDevice, bool> filter)

Parameters

filter Func<IBluetoothRemoteDevice, bool>

The filter to apply to the devices.

Returns

bool

True if a device that matches the filter exists, false otherwise.

HasDevice(string)

Checks if a device with the specified ID exists.

bool HasDevice(string id)

Parameters

id string

The ID of the device to check for.

Returns

bool

True if a device with the specified ID exists, false otherwise.

HasScannerPermissionsAsync()

Checks if the application has the necessary scanner permissions.

ValueTask<bool> HasScannerPermissionsAsync()

Returns

ValueTask<bool>

True if scanner permissions are granted, otherwise false.

Remarks

This is a read-only check. It does not trigger any permission requests.

Platform-specific behavior:

  • Android: Checks BLUETOOTH_SCAN (API 31+) or location permissions (older)
  • iOS/macOS: Checks Bluetooth Always permission
  • Windows: Checks adapter availability and radio state

RequestScannerPermissionsAsync(bool, CancellationToken)

Requests the necessary scanner permissions from the user.

ValueTask RequestScannerPermissionsAsync(bool requireBackgroundLocation = false, CancellationToken cancellationToken = default)

Parameters

requireBackgroundLocation bool

Android-only: whether to request background location permission (API 29-30).

cancellationToken CancellationToken

Cancellation token to cancel the permission request operation.

Returns

ValueTask

Task that completes when permissions are requested.

Remarks

Platform-specific behavior:

  • Android: Shows system permission dialog; can be requested multiple times
  • iOS/macOS: Shows permission dialog on first call; subsequent denials require Settings
  • Windows: Checks adapter state and requests radio access if needed

Exceptions

BluetoothPermissionException

Thrown when permission request fails or is denied. Check InnerException for platform-specific details (COMException, SecurityException, etc.).

StartScanningAsync(ScanningOptions?, PermissionOptions?, TimeSpan?, CancellationToken)

Asynchronously starts the Bluetooth activity with an optional timeout.

Task StartScanningAsync(ScanningOptions? scanningOptions = null, PermissionOptions? permissionOptions = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

scanningOptions ScanningOptions

The options for starting the Bluetooth activity. If null, default options will be used.

permissionOptions PermissionOptions

The options for requesting permissions. If null, default options will be used.

timeout TimeSpan?

The timeout for this operation

cancellationToken CancellationToken

A cancellation token to cancel this operation.

Returns

Task

A task that represents the asynchronous start operation.

Remarks

Ensures that the Bluetooth activity is initialized and ready for use.

Exceptions

ScannerIsAlreadyStartedException

Thrown when the scanner is already running.

ScannerFailedToStartException

Thrown when the scanner fails to start.

ScannerUnexpectedStartException

Thrown when an unexpected error occurs during start.

TimeoutException

Thrown when the operation times out.

OperationCanceledException

Thrown when the operation is cancelled.

StartScanningIfNeededAsync(ScanningOptions?, PermissionOptions?, TimeSpan?, CancellationToken)

Asynchronously starts the Bluetooth activity if it is not already running, with an optional timeout.

ValueTask StartScanningIfNeededAsync(ScanningOptions? scanningOptions = null, PermissionOptions? permissionOptions = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

scanningOptions ScanningOptions

The options for starting the Bluetooth activity. If null, default options will be used.

permissionOptions PermissionOptions

The options for requesting permissions. If null, default options will be used.

timeout TimeSpan?

The timeout for this operation

cancellationToken CancellationToken

A cancellation token to cancel this operation.

Returns

ValueTask

A task that represents the asynchronous start operation.

Remarks

Checks if the Bluetooth activity is already running before attempting to start it.

StopScanningAsync(TimeSpan?, CancellationToken)

Asynchronously stops the Scanner with an optional timeout.

Task StopScanningAsync(TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

timeout TimeSpan?

The timeout for this operation

cancellationToken CancellationToken

A cancellation token to cancel this operation.

Returns

Task

A task that represents the asynchronous stop operation.

Remarks

Ensures that the Scanner and its resources are safely released.

Exceptions

ScannerIsAlreadyStoppedException

Thrown when the scanner is already stopped.

ScannerFailedToStopException

Thrown when the scanner fails to stop.

ScannerUnexpectedStopException

Thrown when an unexpected error occurs during stop.

TimeoutException

Thrown when the operation times out.

OperationCanceledException

Thrown when the operation is cancelled.

StopScanningIfNeededAsync(TimeSpan?, CancellationToken)

Asynchronously stops the Scanner if it is running, with an optional timeout.

ValueTask StopScanningIfNeededAsync(TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

timeout TimeSpan?

The timeout for this operation

cancellationToken CancellationToken

A cancellation token to cancel this operation.

Returns

ValueTask

A task that represents the asynchronous stop operation.

Remarks

Checks if the Scanner is running before attempting to stop it.

WaitForDeviceToAppearAsync(Func<IBluetoothRemoteDevice, bool>?, TimeSpan?, CancellationToken)

Waits for the first Bluetooth device that matches the specified filter to appear.

ValueTask<IBluetoothRemoteDevice> WaitForDeviceToAppearAsync(Func<IBluetoothRemoteDevice, bool>? filter = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

filter Func<IBluetoothRemoteDevice, bool>

A function to filter devices. Should return true for matching devices.

timeout TimeSpan?

The timeout for this operation

cancellationToken CancellationToken

A cancellation token to cancel this operation.

Returns

ValueTask<IBluetoothRemoteDevice>

The IBluetoothRemoteDevice that matches the filter when it appears.

WaitForDeviceToAppearAsync(string, TimeSpan?, CancellationToken)

Waits for a Bluetooth device with the specified ID to appear or returns it if already available.

ValueTask<IBluetoothRemoteDevice> WaitForDeviceToAppearAsync(string id, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

id string

The ID of the device to wait for.

timeout TimeSpan?

The timeout for this operation

cancellationToken CancellationToken

A cancellation token to cancel this operation.

Returns

ValueTask<IBluetoothRemoteDevice>

The IBluetoothRemoteDevice when it appears.

Events

AdvertisementReceived

Event triggered when a Bluetooth advertisement is received.

event EventHandler<AdvertisementReceivedEventArgs> AdvertisementReceived

Event Type

EventHandler<AdvertisementReceivedEventArgs>

DeviceListChanged

Event triggered when the list of available devices changes.

event EventHandler<DeviceListChangedEventArgs>? DeviceListChanged

Event Type

EventHandler<DeviceListChangedEventArgs>

DevicesAdded

Event triggered when devices are added.

event EventHandler<DevicesAddedEventArgs>? DevicesAdded

Event Type

EventHandler<DevicesAddedEventArgs>

DevicesRemoved

Event triggered when devices are removed.

event EventHandler<DevicesRemovedEventArgs>? DevicesRemoved

Event Type

EventHandler<DevicesRemovedEventArgs>

RunningStateChanged

Occurs when the running state of the Bluetooth activity changes.

event EventHandler? RunningStateChanged

Event Type

EventHandler

Started

Occurs when the Bluetooth activity has started.

event EventHandler Started

Event Type

EventHandler

Starting

Occurs when the Bluetooth activity is starting.

event EventHandler Starting

Event Type

EventHandler

Stopped

Occurs when the Scanner has stopped.

event EventHandler Stopped

Event Type

EventHandler

Stopping

Occurs when the Scanner is stopping.

event EventHandler Stopping

Event Type

EventHandler
Edit this page