Class BluetoothRemoteService

Namespace

Bluetooth.Maui

Assembly

Bluetooth.Maui.dll

Unified Bluetooth remote service facade providing extension points for client customization.

public class BluetoothRemoteService : IBluetoothRemoteService, INotifyPropertyChanged, IAsyncDisposable

Inheritance

object

BluetoothRemoteService

Implements

IBluetoothRemoteService

INotifyPropertyChanged

IAsyncDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

BluetoothRemoteService(IBluetoothRemoteService, IBluetoothRemoteDevice)

Initializes a new instance of the BluetoothRemoteService class.

public BluetoothRemoteService(IBluetoothRemoteService platformService, IBluetoothRemoteDevice device)

Parameters

platformService IBluetoothRemoteService

The platform service to wrap.

device IBluetoothRemoteDevice

The wrapped parent device.

Properties

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 the service is exploring characteristics.

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

PlatformService

Gets the wrapped platform service.

public IBluetoothRemoteService PlatformService { get; }

Property Value

IBluetoothRemoteService

Methods

ClearCharacteristicsAsync()

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

public ValueTask ClearCharacteristicsAsync()

Returns

ValueTask

CreateCharacteristicFacade(IBluetoothRemoteCharacteristic)

Creates a wrapped characteristic facade for a platform characteristic.

protected virtual IBluetoothRemoteCharacteristic CreateCharacteristicFacade(IBluetoothRemoteCharacteristic platformCharacteristic)

Parameters

platformCharacteristic IBluetoothRemoteCharacteristic

The platform characteristic to wrap.

Returns

IBluetoothRemoteCharacteristic

The wrapped characteristic facade.

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.

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.

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.

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>

PropertyChanged

Occurs when a property value changes.

public event PropertyChangedEventHandler? PropertyChanged

Event Type

PropertyChangedEventHandler