Table of Contents

Interface IBluetoothRemoteCharacteristic

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

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

public interface IBluetoothRemoteCharacteristic : INotifyPropertyChanged, IAsyncDisposable
Inherited Members

Properties

CanListen

Gets a value indicating whether the characteristic supports notifications.

bool CanListen { get; }

Property Value

bool

CanRead

Gets a value indicating whether the characteristic can be read.

bool CanRead { get; }

Property Value

bool

CanWrite

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

bool CanWrite { get; }

Property Value

bool

Id

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

Guid Id { get; }

Property Value

Guid

IsExploringDescriptors

Gets a value indicating whether the service is exploring descriptors.

bool IsExploringDescriptors { get; }

Property Value

bool

IsListening

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

bool IsListening { get; }

Property Value

bool

IsReading

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

bool IsReading { get; }

Property Value

bool

IsWriting

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

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

string Name { get; }

Property Value

string

Service

Gets the Bluetooth service associated with this characteristic.

IBluetoothRemoteService Service { get; }

Property Value

IBluetoothRemoteService

Value

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

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.

ReadOnlySpan<byte> ValueSpan { get; }

Property Value

ReadOnlySpan<byte>

Methods

AbortReliableWriteAsync(TimeSpan?, CancellationToken)

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

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.

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.

ValueTask ClearDescriptorsAsync()

Returns

ValueTask

ExecuteReliableWriteAsync(TimeSpan?, CancellationToken)

Executes all writes queued in the current reliable write transaction.

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.

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.

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.

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.

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.

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

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.

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.

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.

ReadValueAsync(bool, TimeSpan?, CancellationToken)

Reads the value of the characteristic asynchronously.

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.

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.

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.

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.

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.

event EventHandler<DescriptorListChangedEventArgs>? DescriptorListChanged

Event Type

EventHandler<DescriptorListChangedEventArgs>

DescriptorsAdded

Event triggered when descriptors are added.

event EventHandler<DescriptorsAddedEventArgs>? DescriptorsAdded

Event Type

EventHandler<DescriptorsAddedEventArgs>

DescriptorsRemoved

Event triggered when descriptors are removed.

event EventHandler<DescriptorsRemovedEventArgs>? DescriptorsRemoved

Event Type

EventHandler<DescriptorsRemovedEventArgs>

ValueUpdated

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

event EventHandler<ValueUpdatedEventArgs> ValueUpdated

Event Type

EventHandler<ValueUpdatedEventArgs>
Edit this page