Interface IBluetoothRemoteService

Namespace

Bluetooth.Abstractions.Scanning

Assembly

Bluetooth.Abstractions.Scanning.dll

Interface representing a Bluetooth service, providing properties and methods for interacting with it.

public interface IBluetoothRemoteService : INotifyPropertyChanged, IAsyncDisposable

Inherited Members

INotifyPropertyChanged.PropertyChanged

IAsyncDisposable.DisposeAsync()

Properties

Device

Gets the Bluetooth device associated with this service.

IBluetoothRemoteDevice Device { get; }

Property Value

IBluetoothRemoteDevice

Id

Gets the universally unique identifier (UUID) of the service.

Guid Id { get; }

Property Value

Guid

IsExploringCharacteristics

Gets a value indicating whether the service is exploring characteristics.

bool IsExploringCharacteristics { get; }

Property Value

bool

Name

The name of the Bluetooth service. This is typically used for debugging and logging purposes, and may not be available for all services. If the service is not recognized, this will default to "Unknown Service".

string Name { get; }

Property Value

string

Methods

ClearCharacteristicsAsync()

Resets the list of characteristics and descriptors, and stops all subscriptions and notifications.

ValueTask ClearCharacteristicsAsync()

Returns

ValueTask

ExploreCharacteristicsAsync(CharacteristicExplorationOptions?, TimeSpan?, CancellationToken)

Explores the characteristics of the service asynchronously.

ValueTask ExploreCharacteristicsAsync(CharacteristicExplorationOptions? options = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

options CharacteristicExplorationOptions

Optional exploration configuration. If null, uses default options (characteristics only, with caching enabled). Use CharacteristicsOnly for basic exploration, or Full to include descriptors. Set UseCache = false to force re-exploration even if characteristics were previously discovered.

timeout TimeSpan?

The timeout for this operation

cancellationToken CancellationToken

A cancellation token to cancel this operation.

Returns

ValueTask

A task that represents the asynchronous operation.

Remarks

Common Usage Patterns:

// Simple exploration (uses defaults: characteristics only, with caching):
await service.ExploreCharacteristicsAsync();

// Force re-exploration (ignore cache): await service.ExploreCharacteristicsAsync(new() { UseCache = false });

// Explore characteristics and descriptors: await service.ExploreCharacteristicsAsync(CharacteristicExplorationOptions.Full);

// Custom options with UUID filtering: await service.ExploreCharacteristicsAsync(new CharacteristicExplorationOptions { ExploreDescriptors = true, CharacteristicUuidFilter = uuid => uuid == myCharacteristicUuid, UseCache = false }); Caching Behavior: By default (options = null), caching is enabled (UseCache = true). This means if characteristics have already been explored, the method returns immediately without re-querying the device. To force re-exploration, explicitly set UseCache = false.

Exceptions

InvalidOperationException

Thrown when exploration is already in progress.

DeviceNotConnectedException

Thrown when the device is not connected.

TimeoutException

Thrown when the operation times out.

OperationCanceledException

Thrown when the operation is cancelled.

GetCharacteristic(Func<IBluetoothRemoteCharacteristic, bool>)

Gets the characteristic that matches the specified filter.

IBluetoothRemoteCharacteristic GetCharacteristic(Func<IBluetoothRemoteCharacteristic, bool> filter)

Parameters

filter Func<IBluetoothRemoteCharacteristic, bool>

The filter to apply to the characteristics.

Returns

IBluetoothRemoteCharacteristic

The characteristic that matches the filter.

Exceptions

CharacteristicNotFoundException

Thrown if no characteristic matches the specified filter.

MultipleCharacteristicsFoundException

Thrown if multiple characteristics match the specified filter.

GetCharacteristic(Guid)

Gets the characteristic with the specified ID.

IBluetoothRemoteCharacteristic GetCharacteristic(Guid id)

Parameters

id Guid

The ID of the characteristic to get.

Returns

IBluetoothRemoteCharacteristic

The characteristic with the specified ID.

Exceptions

CharacteristicNotFoundException

Thrown if no characteristic with the specified ID is found.

MultipleCharacteristicsFoundException

Thrown if multiple characteristics match the specified filter.

GetCharacteristicOrDefault(Func<IBluetoothRemoteCharacteristic, bool>)

Gets the characteristic that matches the specified filter.

IBluetoothRemoteCharacteristic? GetCharacteristicOrDefault(Func<IBluetoothRemoteCharacteristic, bool> filter)

Parameters

filter Func<IBluetoothRemoteCharacteristic, bool>

The filter to apply to the characteristics.

Returns

IBluetoothRemoteCharacteristic

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

Exceptions

MultipleCharacteristicsFoundException

Thrown if multiple characteristics match the specified filter.

GetCharacteristicOrDefault(Guid)

Gets the characteristic with the specified ID.

IBluetoothRemoteCharacteristic? GetCharacteristicOrDefault(Guid id)

Parameters

id Guid

The ID of the characteristic to get.

Returns

IBluetoothRemoteCharacteristic

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

Exceptions

MultipleCharacteristicsFoundException

Thrown if multiple characteristics match the specified ID.

GetCharacteristics(Func<IBluetoothRemoteCharacteristic, bool>?)

Gets the characteristics that match the specified filter.

IReadOnlyList<IBluetoothRemoteCharacteristic> GetCharacteristics(Func<IBluetoothRemoteCharacteristic, bool>? filter = null)

Parameters

filter Func<IBluetoothRemoteCharacteristic, bool>

The filter to apply to the characteristics.

Returns

IReadOnlyList<IBluetoothRemoteCharacteristic>

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

HasCharacteristic(Func<IBluetoothRemoteCharacteristic, bool>)

Checks if a characteristic that matches the specified filter exists.

bool HasCharacteristic(Func<IBluetoothRemoteCharacteristic, bool> filter)

Parameters

filter Func<IBluetoothRemoteCharacteristic, bool>

The filter to apply to the characteristics.

Returns

bool

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

HasCharacteristic(Guid)

Checks if a characteristic with the specified ID exists.

bool HasCharacteristic(Guid id)

Parameters

id Guid

The ID of the characteristic to check for.

Returns

bool

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

Events

CharacteristicListChanged

Occurs when the characteristic list changes.

event EventHandler<CharacteristicListChangedEventArgs>? CharacteristicListChanged

Event Type

EventHandler<CharacteristicListChangedEventArgs>

CharacteristicsAdded

Event triggered when characteristics are added.

event EventHandler<CharacteristicsAddedEventArgs>? CharacteristicsAdded

Event Type

EventHandler<CharacteristicsAddedEventArgs>

CharacteristicsRemoved

Event triggered when characteristics are removed.

event EventHandler<CharacteristicsRemovedEventArgs>? CharacteristicsRemoved

Event Type

EventHandler<CharacteristicsRemovedEventArgs>