Table of Contents

Class BaseBluetoothRemoteService

Namespace
Bluetooth.Core.Scanning
Assembly
Bluetooth.Core.Scanning.dll

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

public abstract class BaseBluetoothRemoteService : BaseBindableObject, IBluetoothRemoteService, INotifyPropertyChanged, IAsyncDisposable
Inheritance
BaseBluetoothRemoteService
Implements
Derived
Inherited Members

Constructors

BaseBluetoothRemoteService(IBluetoothRemoteDevice, BluetoothRemoteServiceFactorySpec, IBluetoothRemoteCharacteristicFactory, IBluetoothNameProvider?, ILogger<IBluetoothRemoteService>?)

Initializes a new instance using a factory spec.

protected BaseBluetoothRemoteService(IBluetoothRemoteDevice parentDevice, IBluetoothRemoteServiceFactory.BluetoothRemoteServiceFactorySpec spec, IBluetoothRemoteCharacteristicFactory characteristicFactory, IBluetoothNameProvider? nameProvider = null, ILogger<IBluetoothRemoteService>? logger = null)

Parameters

parentDevice IBluetoothRemoteDevice

The Bluetooth device associated with this service.

spec IBluetoothRemoteServiceFactory.BluetoothRemoteServiceFactorySpec

The factory spec containing service information.

characteristicFactory IBluetoothRemoteCharacteristicFactory

The factory for creating Bluetooth remote characteristics.

nameProvider IBluetoothNameProvider

An optional provider for service names, used to resolve the name based on the ID.

logger ILogger<IBluetoothRemoteService>

The logger instance to use for logging (optional).

BaseBluetoothRemoteService(IBluetoothRemoteDevice, Guid, IBluetoothNameProvider?, ILogger<IBluetoothRemoteService>?)

Initializes a new instance of the BaseBluetoothRemoteService class.

protected BaseBluetoothRemoteService(IBluetoothRemoteDevice parentDevice, Guid id, IBluetoothNameProvider? nameProvider = null, ILogger<IBluetoothRemoteService>? logger = null)

Parameters

parentDevice IBluetoothRemoteDevice

The Bluetooth device associated with this service.

id Guid

The unique identifier (UUID) of the service.

nameProvider IBluetoothNameProvider

An optional provider for service names, used to resolve the name based on the ID.

logger ILogger<IBluetoothRemoteService>

The logger instance to use for logging (optional).

Properties

CharacteristicFactory

Gets the factory for creating Bluetooth remote characteristics.

protected IBluetoothRemoteCharacteristicFactory? CharacteristicFactory { get; }

Property Value

IBluetoothRemoteCharacteristicFactory

Device

Gets the Bluetooth device associated with this service.

public IBluetoothRemoteDevice Device { get; }

Property Value

IBluetoothRemoteDevice

Id

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

public Guid Id { get; }

Property Value

Guid

IsExploringCharacteristics

Gets a value indicating whether characteristic exploration is currently in progress.

public 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".

public string Name { get; }

Property Value

string

Methods

ClearCharacteristicsAsync()

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

public ValueTask ClearCharacteristicsAsync()

Returns

ValueTask

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

DisposeAsyncCore()

Performs the core disposal logic for the service, including canceling pending operations and cleaning up resources.

protected virtual ValueTask DisposeAsyncCore()

Returns

ValueTask

A task that represents the asynchronous disposal operation.

ExploreCharacteristicsAsync(CharacteristicExplorationOptions?, TimeSpan?, CancellationToken)

Explores the characteristics of the service asynchronously.

public 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.

DeviceNotConnectedException

Thrown when the device is not connected.

GetCharacteristic(Func<IBluetoothRemoteCharacteristic, bool>)

Gets the characteristic that matches the specified filter.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

NativeCharacteristicsExplorationAsync(TimeSpan?, CancellationToken)

Platform-specific implementation to explore characteristics.

protected abstract ValueTask NativeCharacteristicsExplorationAsync(TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

timeout TimeSpan?

Optional timeout for the operation.

cancellationToken CancellationToken

Optional cancellation token for the operation.

Returns

ValueTask

A task that represents the asynchronous operation.

OnCharacteristicsExplorationFailed(Exception)

Called when characteristic exploration fails. Completes the exploration task with an exception or dispatches to the unhandled exception listener.

protected void OnCharacteristicsExplorationFailed(Exception e)

Parameters

e Exception

The exception that occurred during characteristic exploration.

Remarks

If the task completion source accepts the exception, it is propagated to waiting tasks. Otherwise, the exception is dispatched to the BluetoothUnhandledExceptionListener.

OnCharacteristicsExplorationSucceeded<TNativeCharacteristicType>(IList<TNativeCharacteristicType>, Func<TNativeCharacteristicType, IBluetoothRemoteCharacteristic, bool>, Func<TNativeCharacteristicType, IBluetoothRemoteCharacteristic>)

Called when characteristic exploration succeeds. Updates the Characteristics collection and completes the exploration task.

protected void OnCharacteristicsExplorationSucceeded<TNativeCharacteristicType>(IList<TNativeCharacteristicType> characteristics, Func<TNativeCharacteristicType, IBluetoothRemoteCharacteristic, bool> areRepresentingTheSameObject, Func<TNativeCharacteristicType, IBluetoothRemoteCharacteristic> fromInputTypeToOutputTypeConversion)

Parameters

characteristics IList<TNativeCharacteristicType>

The list of native characteristics discovered.

areRepresentingTheSameObject Func<TNativeCharacteristicType, IBluetoothRemoteCharacteristic, bool>

Function to determine if a native characteristic and IBluetoothCharacteristic represent the same object.

fromInputTypeToOutputTypeConversion Func<TNativeCharacteristicType, IBluetoothRemoteCharacteristic>

Function to convert from native characteristic type to IBluetoothCharacteristic.

Type Parameters

TNativeCharacteristicType

The platform-specific characteristic type.

Exceptions

UnexpectedCharacteristicExplorationException

Thrown when the task completion source is not in the expected state.

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

Events

CharacteristicListChanged

Occurs when the characteristic list changes.

public event EventHandler<CharacteristicListChangedEventArgs>? CharacteristicListChanged

Event Type

EventHandler<CharacteristicListChangedEventArgs>

CharacteristicsAdded

Event triggered when characteristics are added.

public event EventHandler<CharacteristicsAddedEventArgs>? CharacteristicsAdded

Event Type

EventHandler<CharacteristicsAddedEventArgs>

CharacteristicsRemoved

Event triggered when characteristics are removed.

public event EventHandler<CharacteristicsRemovedEventArgs>? CharacteristicsRemoved

Event Type

EventHandler<CharacteristicsRemovedEventArgs>