Table of Contents

Class BluetoothBroadcaster

Namespace
Bluetooth.Maui
Assembly
Bluetooth.Maui.dll

Unified Bluetooth broadcaster facade providing cross-platform inheritance and extension points.

public class BluetoothBroadcaster : IBluetoothBroadcaster, IAsyncDisposable
Inheritance
BluetoothBroadcaster
Implements
Inherited Members

Remarks

This class wraps platform-specific broadcaster implementations and provides a unified API with virtual extension points for client customization.

Client Extensibility: Inherit from this class to add custom broadcasting logic: 

public class MyCustomBroadcaster : BluetoothBroadcaster
{
    public MyCustomBroadcaster(...) : base(...) { }

protected override ValueTask OnBroadcastStartingAsync(BroadcastingOptions? options, CancellationToken cancellationToken)
{
    // Custom pre-broadcast setup
    return base.OnBroadcastStartingAsync(options, cancellationToken);
}



}

Constructors

BluetoothBroadcaster(IBluetoothAdapter, ITicker, ILoggerFactory?)

Initializes a new instance of the BluetoothBroadcaster class.

[ActivatorUtilitiesConstructor]
public BluetoothBroadcaster(IBluetoothAdapter adapter, ITicker ticker, ILoggerFactory? loggerFactory = null)

Parameters

adapter IBluetoothAdapter

The Bluetooth adapter associated with this broadcaster.

ticker ITicker

The ticker for scheduling periodic refresh tasks.

loggerFactory ILoggerFactory

Optional logger factory for creating loggers.

Properties

Adapter

Gets the Bluetooth adapter associated with this broadcaster.

public IBluetoothAdapter Adapter { get; }

Property Value

IBluetoothAdapter

CurrentBroadcastingOptions

Gets the current broadcasting options being used by the Broadcaster.

public BroadcastingOptions CurrentBroadcastingOptions { get; }

Property Value

BroadcastingOptions

IsRunning

Gets a value indicating whether the Bluetooth activity is actively running.

public bool IsRunning { get; }

Property Value

bool

IsStarting

Gets a value indicating whether the Bluetooth activity is starting.

public bool IsStarting { get; }

Property Value

bool

IsStopping

Gets a value indicating whether the Broadcaster is stopping.

public bool IsStopping { get; }

Property Value

bool

LoggerFactory

Gets the logger factory for creating loggers within the Bluetooth broadcaster/server implementation.

public ILoggerFactory? LoggerFactory { get; }

Property Value

ILoggerFactory

PlatformBroadcaster

Gets the underlying platform-specific broadcaster implementation.

public IBluetoothBroadcaster PlatformBroadcaster { get; }

Property Value

IBluetoothBroadcaster

Remarks

Clients can access platform-specific APIs by casting this property using conditional compilation.

Methods

CreateServiceAsync(Guid, string?, bool, TimeSpan?, CancellationToken)

Adds a GATT service to be hosted by the broadcaster.

public ValueTask<IBluetoothLocalService> CreateServiceAsync(Guid id, string? name = null, bool isPrimary = true, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

id Guid

The UUID of the service to add.

name string

An optional name for the service. If not provided, a default name may be assigned based on the UUID or other heuristics.

isPrimary bool

Indicates whether the service is a primary service. Defaults to true.

timeout TimeSpan?

The timeout for this operation

cancellationToken CancellationToken

A cancellation token to cancel this operation.

Returns

ValueTask<IBluetoothLocalService>

The added service.

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.

GetClientDevice(Func<IBluetoothConnectedDevice, bool>)

Returns the first Bluetooth device that matches the specified filter.

public IBluetoothConnectedDevice GetClientDevice(Func<IBluetoothConnectedDevice, bool> filter)

Parameters

filter Func<IBluetoothConnectedDevice, bool>

A function to filter devices. Should return true for matching devices.

Returns

IBluetoothConnectedDevice

The matching IBluetoothConnectedDevice.

Exceptions

ClientDeviceNotFoundException

Thrown when no device matches the specified filter.

MultipleClientDevicesFoundException

Thrown when multiple devices match the specified filter.

GetClientDevice(string)

Returns a Bluetooth device with the specified ID.

public IBluetoothConnectedDevice GetClientDevice(string id)

Parameters

id string

The ID of the device to retrieve.

Returns

IBluetoothConnectedDevice

The matching IBluetoothConnectedDevice.

Exceptions

ClientDeviceNotFoundException

Thrown when no device with the specified ID is found.

MultipleClientDevicesFoundException

Thrown when multiple devices with the specified ID are found.

GetClientDeviceOrDefault(Func<IBluetoothConnectedDevice, bool>)

Returns the first Bluetooth device that matches the specified filter.

public IBluetoothConnectedDevice? GetClientDeviceOrDefault(Func<IBluetoothConnectedDevice, bool> filter)

Parameters

filter Func<IBluetoothConnectedDevice, bool>

A function to filter devices. Should return true for matching devices.

Returns

IBluetoothConnectedDevice

The matching IBluetoothConnectedDevice, or null if none are found.

Exceptions

MultipleClientDevicesFoundException

Thrown when multiple devices match the specified filter.

GetClientDeviceOrDefault(string)

Returns a Bluetooth device with the specified ID.

public IBluetoothConnectedDevice? GetClientDeviceOrDefault(string id)

Parameters

id string

The ID of the device to retrieve.

Returns

IBluetoothConnectedDevice

The matching IBluetoothConnectedDevice, or null if none are found.

Exceptions

MultipleClientDevicesFoundException

Thrown when multiple devices with the specified ID are found.

GetClientDevices(Func<IBluetoothConnectedDevice, bool>?)

Returns all Bluetooth devices that match the specified filter.

public IReadOnlyList<IBluetoothConnectedDevice> GetClientDevices(Func<IBluetoothConnectedDevice, bool>? filter = null)

Parameters

filter Func<IBluetoothConnectedDevice, bool>

An optional function to filter devices. Defaults to null for all devices.

Returns

IReadOnlyList<IBluetoothConnectedDevice>

A read-only snapshot of connected client devices at the time of the call. This collection is immutable and will not be modified if devices connect or disconnect after the call returns. To get updated results, call this method again or subscribe to ClientDeviceListChanged event.

GetService(Func<IBluetoothLocalService, bool>)

Gets a hosted GATT service that matches the specified filter.

public IBluetoothLocalService GetService(Func<IBluetoothLocalService, bool> filter)

Parameters

filter Func<IBluetoothLocalService, bool>

A function to filter services. Should return true for the desired service.

Returns

IBluetoothLocalService

The matching service.

Exceptions

ServiceNotFoundException

Thrown if no service matches the specified filter.

MultipleServicesFoundException

Thrown if multiple services match the specified filter.

GetService(Guid)

Gets a hosted GATT service by its UUID.

public IBluetoothLocalService GetService(Guid id)

Parameters

id Guid

The UUID of the service to retrieve.

Returns

IBluetoothLocalService

The matching service.

Exceptions

ServiceNotFoundException

Thrown if no service matches the specified filter.

MultipleServicesFoundException

Thrown if multiple services match the specified filter.

GetServiceOrDefault(Func<IBluetoothLocalService, bool>)

Gets a hosted GATT service that matches the specified filter.

public IBluetoothLocalService? GetServiceOrDefault(Func<IBluetoothLocalService, bool> filter)

Parameters

filter Func<IBluetoothLocalService, bool>

A function to filter services. Should return true for the desired service.

Returns

IBluetoothLocalService

The matching service, or null if not found.

Exceptions

MultipleServicesFoundException

Thrown if multiple services match the specified filter.

GetServiceOrDefault(Guid)

Gets a hosted GATT service by its UUID.

public IBluetoothLocalService? GetServiceOrDefault(Guid id)

Parameters

id Guid

The UUID of the service to retrieve.

Returns

IBluetoothLocalService

The matching service, or null if not found.

Exceptions

MultipleServicesFoundException

Thrown if multiple services match the specified filter.

GetServices(Func<IBluetoothLocalService, bool>?)

Gets all hosted GATT services.

public IReadOnlyList<IBluetoothLocalService> GetServices(Func<IBluetoothLocalService, bool>? filter = null)

Parameters

filter Func<IBluetoothLocalService, bool>

An optional filter to apply to the services.

Returns

IReadOnlyList<IBluetoothLocalService>

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

HasBroadcasterPermissionsAsync()

Checks if the application has the necessary broadcaster permissions.

public ValueTask<bool> HasBroadcasterPermissionsAsync()

Returns

ValueTask<bool>

True if broadcaster permissions are granted, otherwise false.

Remarks

This is a read-only check. It does not trigger any permission requests.

Platform-specific behavior:

  • Android: Checks BLUETOOTH_ADVERTISE (API 31+) or location permissions (older)
  • iOS/macOS: Checks Bluetooth Always + Peripheral permissions
  • Windows: Checks adapter availability and peripheral role support

HasClientDevice(Func<IBluetoothConnectedDevice, bool>)

Determines if there is at least one connected client device that matches the specified filter.

public bool HasClientDevice(Func<IBluetoothConnectedDevice, bool> filter)

Parameters

filter Func<IBluetoothConnectedDevice, bool>

A function to filter devices. Should return true for matching devices.

Returns

bool

True if at least one matching device is found; otherwise, false.

HasClientDevice(string)

Determines if there is a connected client device with the specified ID.

public bool HasClientDevice(string id)

Parameters

id string

The ID of the device to check for.

Returns

bool

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

HasService(Func<IBluetoothLocalService, bool>)

Checks if a hosted GATT service that matches the specified filter exists.

public bool HasService(Func<IBluetoothLocalService, bool> filter)

Parameters

filter Func<IBluetoothLocalService, bool>

A function to filter services. Should return true for the desired service.

Returns

bool

True if a matching service exists, false otherwise.

HasService(Guid)

Checks if a hosted GATT service with the specified UUID exists.

public bool HasService(Guid id)

Parameters

id Guid

The UUID of the service to check for.

Returns

bool

True if a matching service exists, false otherwise.

OnBroadcastStartingAsync(BroadcastingOptions?, CancellationToken)

Virtual method called before broadcasting starts. Override this in client projects to add custom pre-broadcast logic.

protected virtual ValueTask OnBroadcastStartingAsync(BroadcastingOptions? options, CancellationToken cancellationToken)

Parameters

options BroadcastingOptions

The broadcasting options being used.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

ValueTask

A task representing the asynchronous operation.

Remarks

This method is called after permissions are checked but before the native platform broadcaster starts. Use this to perform setup, validation, or logging.

Example Use Cases:

  • Configure platform-specific broadcast settings
  • Initialize custom state or advertising data
  • Validate broadcasting prerequisites
  • Start performance monitoring

OnBroadcastStoppedAsync(CancellationToken)

Virtual method called after broadcasting stops. Override this in client projects to add custom post-broadcast cleanup logic.

protected virtual ValueTask OnBroadcastStoppedAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

ValueTask

A task representing the asynchronous operation.

Remarks

This method is called after the native platform broadcaster has stopped. Use this to perform cleanup, logging, or final processing.

Example Use Cases:

  • Flush cached advertising data
  • Log broadcast statistics
  • Clean up resources
  • Stop performance monitoring

OnClientDeviceListChanged(ClientDeviceListChangedEventArgs)

Virtual method called when the client device list changes. Override this in client projects to add custom list change handling logic.

protected virtual void OnClientDeviceListChanged(ClientDeviceListChangedEventArgs eventArgs)

Parameters

eventArgs ClientDeviceListChangedEventArgs

The event arguments containing list change details.

Remarks

This method is called on the platform's native thread/dispatcher. Use this to react to overall list changes beyond just additions/removals.

OnClientDevicesConnected(IReadOnlyList<IBluetoothConnectedDevice>)

Virtual method called when client devices connect to the broadcaster. Override this in client projects to add custom connection handling logic.

protected virtual void OnClientDevicesConnected(IReadOnlyList<IBluetoothConnectedDevice> devices)

Parameters

devices IReadOnlyList<IBluetoothConnectedDevice>

The connected client devices.

Remarks

This method is called on the platform's native thread/dispatcher. Use this to track connections, initialize per-device state, or trigger custom events.

Example Use Cases:

  • Track connected client IDs
  • Initialize per-device caches or state
  • Log connection events with device details
  • Trigger custom notifications to application layers

OnClientDevicesDisconnected(IReadOnlyList<IBluetoothConnectedDevice>)

Virtual method called when client devices disconnect from the broadcaster. Override this in client projects to add custom disconnection handling logic.

protected virtual void OnClientDevicesDisconnected(IReadOnlyList<IBluetoothConnectedDevice> devices)

Parameters

devices IReadOnlyList<IBluetoothConnectedDevice>

The disconnected client devices.

Remarks

This method is called on the platform's native thread/dispatcher. Use this to clean up per-device state or log disconnection events.

Example Use Cases:

  • Clean up per-device caches or resources
  • Log disconnection events with device details
  • Update UI or application state
  • Trigger custom reconnection logic if needed

RemoveAllServicesAsync(TimeSpan?, CancellationToken)

Removes all hosted services from the broadcaster.

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

RemoveServiceAsync(IBluetoothLocalService, TimeSpan?, CancellationToken)

Removes a hosted GATT service from the broadcaster.

public ValueTask RemoveServiceAsync(IBluetoothLocalService localService, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

localService IBluetoothLocalService

The service to remove.

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.

RemoveServiceAsync(Guid, TimeSpan?, CancellationToken)

Removes a hosted GATT service from the broadcaster.

public ValueTask RemoveServiceAsync(Guid id, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

id Guid

The UUID of the service to remove.

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.

RequestBroadcasterPermissionsAsync(CancellationToken)

Requests the necessary broadcaster permissions from the user.

public ValueTask RequestBroadcasterPermissionsAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token to cancel the permission request operation.

Returns

ValueTask

Task that completes when permissions are requested.

Remarks

Platform-specific behavior:

  • Android: Shows system permission dialog; can be requested multiple times
  • iOS/macOS: Requests both Bluetooth Always and Peripheral permissions
  • Windows: Checks adapter state and requests radio access if needed

Exceptions

BluetoothPermissionException

Thrown when permission request fails or is denied. Check InnerException for platform-specific details.

StartBroadcastingAsync(BroadcastingOptions?, PermissionOptions?, TimeSpan?, CancellationToken)

Asynchronously starts the Bluetooth activity with an optional timeout.

public ValueTask StartBroadcastingAsync(BroadcastingOptions? broadcastingOptions = null, PermissionOptions? permissionOptions = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

broadcastingOptions BroadcastingOptions

The broadcasting options to use when starting the broadcaster. If null, default options will be used.

permissionOptions PermissionOptions

The permission options to use when starting the broadcaster. If null, default options will be used.

timeout TimeSpan?

The timeout for this operation

cancellationToken CancellationToken

A cancellation token to cancel this operation.

Returns

ValueTask

A task that represents the asynchronous start operation.

Remarks

Ensures that the Bluetooth activity is initialized and ready for use.

Exceptions

InvalidOperationException

Thrown when broadcasting is already active.

PlatformNotSupportedException

Thrown when the platform doesn't support peripheral mode.

TimeoutException

Thrown when the operation times out.

OperationCanceledException

Thrown when the operation is cancelled.

StartBroadcastingIfNeededAsync(BroadcastingOptions?, PermissionOptions?, TimeSpan?, CancellationToken)

Asynchronously starts the Bluetooth activity if it is not already running, with an optional timeout.

public ValueTask StartBroadcastingIfNeededAsync(BroadcastingOptions? broadcastingOptions = null, PermissionOptions? permissionOptions = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

broadcastingOptions BroadcastingOptions

The broadcasting options to use when starting the broadcaster. If null, default options will be used.

permissionOptions PermissionOptions

The permission options to use when starting the broadcaster. If null, default options will be used.

timeout TimeSpan?

The timeout for this operation

cancellationToken CancellationToken

A cancellation token to cancel this operation.

Returns

ValueTask

A task that represents the asynchronous start operation.

Remarks

Checks if the Bluetooth activity is already running before attempting to start it.

StopBroadcastingAsync(TimeSpan?, CancellationToken)

Asynchronously stops the Broadcaster with an optional timeout.

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

Remarks

Ensures that the Broadcaster and its resources are safely released.

Exceptions

InvalidOperationException

Thrown when broadcasting is not active.

TimeoutException

Thrown when the operation times out.

OperationCanceledException

Thrown when the operation is cancelled.

StopBroadcastingIfNeededAsync(TimeSpan?, CancellationToken)

Asynchronously stops the Broadcaster if it is running, with an optional timeout.

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

Remarks

Checks if the Broadcaster is running before attempting to stop it.

Events

ClientDeviceListChanged

Event triggered when the list of connected client devices changes.

public event EventHandler<ClientDeviceListChangedEventArgs>? ClientDeviceListChanged

Event Type

EventHandler<ClientDeviceListChangedEventArgs>

ClientDevicesAdded

Event triggered when client devices connect.

public event EventHandler<ClientDevicesAddedEventArgs>? ClientDevicesAdded

Event Type

EventHandler<ClientDevicesAddedEventArgs>

ClientDevicesRemoved

Event triggered when client devices disconnect.

public event EventHandler<ClientDevicesRemovedEventArgs>? ClientDevicesRemoved

Event Type

EventHandler<ClientDevicesRemovedEventArgs>

RunningStateChanged

Occurs when the running state of the Bluetooth activity changes.

public event EventHandler? RunningStateChanged

Event Type

EventHandler

ServiceListChanged

Occurs when the service list changes.

public event EventHandler<ServiceListChangedEventArgs>? ServiceListChanged

Event Type

EventHandler<ServiceListChangedEventArgs>

ServicesAdded

Event triggered when services are added.

public event EventHandler<ServicesAddedEventArgs>? ServicesAdded

Event Type

EventHandler<ServicesAddedEventArgs>

ServicesRemoved

Event triggered when services are removed.

public event EventHandler<ServicesRemovedEventArgs>? ServicesRemoved

Event Type

EventHandler<ServicesRemovedEventArgs>

Started

Occurs when the Bluetooth activity has started.

public event EventHandler? Started

Event Type

EventHandler

Starting

Occurs when the Bluetooth activity is starting.

public event EventHandler? Starting

Event Type

EventHandler

Stopped

Occurs when the Broadcaster has stopped.

public event EventHandler? Stopped

Event Type

EventHandler

Stopping

Occurs when the Broadcaster is stopping.

public event EventHandler? Stopping

Event Type

EventHandler
Edit this page