Table of Contents

Class BluetoothRemoteCharacteristic

Namespace
Bluetooth.Maui
Assembly
Bluetooth.Maui.dll

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

public class BluetoothRemoteCharacteristic : IBluetoothRemoteCharacteristic, INotifyPropertyChanged, IAsyncDisposable
Inheritance
BluetoothRemoteCharacteristic
Implements
Inherited Members

Constructors

BluetoothRemoteCharacteristic(IBluetoothRemoteCharacteristic, IBluetoothRemoteService)

Initializes a new instance of the BluetoothRemoteCharacteristic class.

public BluetoothRemoteCharacteristic(IBluetoothRemoteCharacteristic platformCharacteristic, IBluetoothRemoteService service)

Parameters

platformCharacteristic IBluetoothRemoteCharacteristic

The platform characteristic to wrap.

service IBluetoothRemoteService

The wrapped parent service.

Properties

CanListen

Gets a value indicating whether the characteristic supports notifications.

public bool CanListen { get; }

Property Value

bool

CanRead

Gets a value indicating whether the characteristic can be read.

public bool CanRead { get; }

Property Value

bool

CanWrite

Gets a value indicating whether the characteristic can be written to.

public bool CanWrite { get; }

Property Value

bool

Id

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

public Guid Id { get; }

Property Value

Guid

IsExploringDescriptors

Gets a value indicating whether the service is exploring descriptors.

public bool IsExploringDescriptors { get; }

Property Value

bool

IsListening

Gets a value indicating whether the characteristic is currently listening for notifications.

public bool IsListening { get; }

Property Value

bool

IsReading

Gets a value indicating whether the characteristic is currently reading its value.

public bool IsReading { get; }

Property Value

bool

IsWriting

Gets a value indicating whether the characteristic is currently writing its value.

public bool IsWriting { get; }

Property Value

bool

Name

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

public string Name { get; }

Property Value

string

PlatformCharacteristic

Gets the wrapped platform characteristic.

public IBluetoothRemoteCharacteristic PlatformCharacteristic { get; }

Property Value

IBluetoothRemoteCharacteristic

Service

Gets the Bluetooth service associated with this characteristic.

public IBluetoothRemoteService Service { get; }

Property Value

IBluetoothRemoteService

Value

Gets the value of the characteristic as a read-only memory segment. Useful for asynchronous operations.

public ReadOnlyMemory<byte> Value { get; }

Property Value

ReadOnlyMemory<byte>

ValueSpan

Gets the value of the characteristic as a read-only span. Useful for high-performance scenarios.

public ReadOnlySpan<byte> ValueSpan { get; }

Property Value

ReadOnlySpan<byte>

Methods

AbortReliableWriteAsync(TimeSpan?, CancellationToken)

Aborts the current reliable write transaction and discards all queued writes.

public ValueTask AbortReliableWriteAsync(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 operation.

Exceptions

InvalidOperationException

Thrown when no reliable write transaction is in progress.

TimeoutException

Thrown when the operation times out.

OperationCanceledException

Thrown when the operation is cancelled.

BeginReliableWriteAsync(TimeSpan?, CancellationToken)

Begins a reliable write transaction. Reliable write allows you to queue multiple writes and execute them atomically.

public ValueTask BeginReliableWriteAsync(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 operation.

Exceptions

InvalidOperationException

Thrown when a reliable write transaction is already in progress.

TimeoutException

Thrown when the operation times out.

OperationCanceledException

Thrown when the operation is cancelled.

ClearDescriptorsAsync()

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

public ValueTask ClearDescriptorsAsync()

Returns

ValueTask

CreateDescriptorFacade(IBluetoothRemoteDescriptor)

Creates a wrapped descriptor facade for a platform descriptor.

protected virtual IBluetoothRemoteDescriptor CreateDescriptorFacade(IBluetoothRemoteDescriptor platformDescriptor)

Parameters

platformDescriptor IBluetoothRemoteDescriptor

The platform descriptor to wrap.

Returns

IBluetoothRemoteDescriptor

The wrapped descriptor 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.

ExecuteReliableWriteAsync(TimeSpan?, CancellationToken)

Executes all writes queued in the current reliable write transaction.

public ValueTask ExecuteReliableWriteAsync(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 operation.

Exceptions

InvalidOperationException

Thrown when no reliable write transaction is in progress.

TimeoutException

Thrown when the operation times out.

OperationCanceledException

Thrown when the operation is cancelled.

ExploreDescriptorsAsync(DescriptorExplorationOptions?, TimeSpan?, CancellationToken)

Explores (discovers) the descriptors of this characteristic asynchronously.

public Task ExploreDescriptorsAsync(DescriptorExplorationOptions? options = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

options DescriptorExplorationOptions

Optional exploration configuration. If null, uses default options (with caching enabled). Set UseCache = false to force re-exploration even if descriptors were previously discovered. Use DescriptorUuidFilter to discover only specific descriptors by UUID.

timeout TimeSpan?

The timeout for this operation.

cancellationToken CancellationToken

A cancellation token to cancel this operation.

Returns

Task

A task that represents the asynchronous operation.

Remarks

Common Usage Patterns: 

// Simple exploration (uses defaults: all descriptors, with caching):
await characteristic.ExploreDescriptorsAsync();

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

// Filter by descriptor UUID (e.g., Client Characteristic Configuration): await characteristic.ExploreDescriptorsAsync(new DescriptorExplorationOptions { DescriptorUuidFilter = uuid => uuid == BluetoothUuids.ClientCharacteristicConfiguration }); Caching Behavior: By default (options = null), caching is enabled (UseCache = true). This means if descriptors have already been explored, the method returns immediately without re-querying the device. To force re-exploration, explicitly set UseCache = false.

GetDescriptor(Func<IBluetoothRemoteDescriptor, bool>)

Gets the descriptor that matches the specified filter.

public IBluetoothRemoteDescriptor GetDescriptor(Func<IBluetoothRemoteDescriptor, bool> filter)

Parameters

filter Func<IBluetoothRemoteDescriptor, bool>

The filter to apply to the descriptors.

Returns

IBluetoothRemoteDescriptor

The descriptor that matches the filter.

Exceptions

DescriptorNotFoundException

Thrown when no descriptor matches the specified filter.

MultipleDescriptorsFoundException

Thrown when multiple descriptors match the specified filter.

GetDescriptor(Guid)

Gets a descriptor by its ID.

public IBluetoothRemoteDescriptor GetDescriptor(Guid id)

Parameters

id Guid

The ID of the descriptor to get.

Returns

IBluetoothRemoteDescriptor

The descriptor with the specified ID.

Exceptions

DescriptorNotFoundException

Thrown when no descriptor with the specified ID is found.

MultipleDescriptorsFoundException

Thrown when multiple descriptors with the specified ID are found.

GetDescriptorOrDefault(Func<IBluetoothRemoteDescriptor, bool>)

Gets the descriptor that matches the specified filter.

public IBluetoothRemoteDescriptor? GetDescriptorOrDefault(Func<IBluetoothRemoteDescriptor, bool> filter)

Parameters

filter Func<IBluetoothRemoteDescriptor, bool>

The filter to apply to the descriptors.

Returns

IBluetoothRemoteDescriptor

The descriptor that matches the filter, or null if not found.

Exceptions

MultipleDescriptorsFoundException

Thrown if multiple descriptors match the specified filter.

GetDescriptorOrDefault(Guid)

Gets a descriptor by its ID.

public IBluetoothRemoteDescriptor? GetDescriptorOrDefault(Guid id)

Parameters

id Guid

The ID of the descriptor to get.

Returns

IBluetoothRemoteDescriptor

The descriptor with the specified ID, or null if not found.

Exceptions

MultipleDescriptorsFoundException

Thrown if multiple descriptors match the specified ID.

GetDescriptors(Func<IBluetoothRemoteDescriptor, bool>?)

Gets the descriptors that match the specified filter. 0-N

public IEnumerable<IBluetoothRemoteDescriptor> GetDescriptors(Func<IBluetoothRemoteDescriptor, bool>? filter = null)

Parameters

filter Func<IBluetoothRemoteDescriptor, bool>

The filter to apply to the descriptors.

Returns

IEnumerable<IBluetoothRemoteDescriptor>

The descriptors that match the filter, or all descriptors if the filter is null.

HasDescriptor(Func<IBluetoothRemoteDescriptor, bool>)

Gets a value indicating whether this characteristic has a descriptor that matches the specified filter.

public bool HasDescriptor(Func<IBluetoothRemoteDescriptor, bool> filter)

Parameters

filter Func<IBluetoothRemoteDescriptor, bool>

The filter to apply to the descriptors.

Returns

bool

True if a matching descriptor is found; otherwise, false.

HasDescriptor(Guid)

Gets a value indicating whether this characteristic has a descriptor with the specified ID.

public bool HasDescriptor(Guid id)

Parameters

id Guid

The ID of the descriptor to check for.

Returns

bool

True if a descriptor with the specified ID is found; otherwise, false.

OnAfterWriteValueAsync(ReadOnlyMemory<byte>, CancellationToken)

Called after writing characteristic value.

protected virtual ValueTask OnAfterWriteValueAsync(ReadOnlyMemory<byte> value, CancellationToken cancellationToken)

Parameters

value ReadOnlyMemory<byte>
cancellationToken CancellationToken

Returns

ValueTask

OnBeforeWriteValueAsync(ReadOnlyMemory<byte>, CancellationToken)

Called before writing characteristic value.

protected virtual ValueTask OnBeforeWriteValueAsync(ReadOnlyMemory<byte> value, CancellationToken cancellationToken)

Parameters

value ReadOnlyMemory<byte>
cancellationToken CancellationToken

Returns

ValueTask

ReadValueAsync(bool, TimeSpan?, CancellationToken)

Reads the value of the characteristic asynchronously.

public ValueTask<ReadOnlyMemory<byte>> ReadValueAsync(bool skipIfPreviouslyRead = false, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

skipIfPreviouslyRead bool

If true, skips reading if the value was previously read.

timeout TimeSpan?

The timeout for this operation

cancellationToken CancellationToken

A cancellation token to cancel this operation.

Returns

ValueTask<ReadOnlyMemory<byte>>

A task that represents the asynchronous read operation. The task result contains the value read.

Exceptions

DeviceNotConnectedException

Thrown when the device is not connected.

CharacteristicCantReadException

Thrown when the characteristic doesn't support read operations.

CharacteristicReadException

Thrown when the read operation fails.

TimeoutException

Thrown when the operation times out.

OperationCanceledException

Thrown when the operation is cancelled.

StartListeningAsync(TimeSpan?, CancellationToken)

Starts listening for notifications from the characteristic asynchronously.

public ValueTask StartListeningAsync(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 operation.

Exceptions

DeviceNotConnectedException

Thrown when the device is not connected.

CharacteristicCantListenException

Thrown when the characteristic doesn't support notifications.

CharacteristicAlreadyNotifyingException

Thrown when the characteristic is already listening for notifications.

CharacteristicNotifyException

Thrown when the notify operation fails.

TimeoutException

Thrown when the operation times out.

OperationCanceledException

Thrown when the operation is cancelled.

StopListeningAsync(TimeSpan?, CancellationToken)

Stops listening for notifications from the characteristic asynchronously.

public ValueTask StopListeningAsync(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 operation.

Exceptions

DeviceNotConnectedException

Thrown when the device is not connected.

CharacteristicCantListenException

Thrown when the characteristic doesn't support notifications.

CharacteristicAlreadyNotifyingException

Thrown when the characteristic is not currently listening.

CharacteristicNotifyException

Thrown when the notify operation fails.

TimeoutException

Thrown when the operation times out.

OperationCanceledException

Thrown when the operation is cancelled.

WaitForValueChangeAsync(Func<ReadOnlyMemory<byte>, bool>?, TimeSpan?, CancellationToken)

Waits for the value of the characteristic to change asynchronously.

public ValueTask<ReadOnlyMemory<byte>> WaitForValueChangeAsync(Func<ReadOnlyMemory<byte>, bool>? valueFilter = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

valueFilter Func<ReadOnlyMemory<byte>, bool>

An optional filter function to apply to the value changes. If provided, the task completes only when the filter returns true.

timeout TimeSpan?

The timeout for this operation

cancellationToken CancellationToken

A cancellation token to cancel this operation.

Returns

ValueTask<ReadOnlyMemory<byte>>

A task that represents the asynchronous operation. The task result contains the new value of the characteristic.

WriteValueAsync(ReadOnlyMemory<byte>, bool, TimeSpan?, CancellationToken)

Writes a value to the characteristic asynchronously.

public virtual ValueTask WriteValueAsync(ReadOnlyMemory<byte> value, bool skipIfOldValueMatchesNewValue = false, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

value ReadOnlyMemory<byte>

The value to write.

skipIfOldValueMatchesNewValue bool

If true, skips writing if the old value matches the new value.

timeout TimeSpan?

The timeout for this operation

cancellationToken CancellationToken

A cancellation token to cancel this operation.

Returns

ValueTask

A task that represents the asynchronous write operation.

Exceptions

ArgumentNullException

Thrown when value is null.

InvalidOperationException

Thrown when the characteristic doesn't support write operations.

TimeoutException

Thrown when the operation times out.

OperationCanceledException

Thrown when the operation is cancelled.

Events

DescriptorListChanged

Event triggered when the list of available descriptors changes.

public event EventHandler<DescriptorListChangedEventArgs>? DescriptorListChanged

Event Type

EventHandler<DescriptorListChangedEventArgs>

DescriptorsAdded

Event triggered when descriptors are added.

public event EventHandler<DescriptorsAddedEventArgs>? DescriptorsAdded

Event Type

EventHandler<DescriptorsAddedEventArgs>

DescriptorsRemoved

Event triggered when descriptors are removed.

public event EventHandler<DescriptorsRemovedEventArgs>? DescriptorsRemoved

Event Type

EventHandler<DescriptorsRemovedEventArgs>

PropertyChanged

Occurs when a property value changes.

public event PropertyChangedEventHandler? PropertyChanged

Event Type

PropertyChangedEventHandler

ValueUpdated

Event raised when the value of the characteristic is updated, only triggered when IsListening is true.

public event EventHandler<ValueUpdatedEventArgs> ValueUpdated

Event Type

EventHandler<ValueUpdatedEventArgs>
Edit this page