Struct bluez::client::BlueZClient

pub struct BlueZClient<'a> { /* fields omitted */ }

Methods

impl<'a> BlueZClient<'a>

pub async fn get_advertising_features<'_>(
    &'_ mut self,
    controller: Controller
) -> Result<AdvertisingFeaturesInfo>

This command is used to read the advertising features supported by the controller and stack. The max_adv_data_len and max_scan_rsp_len provides extra information about the maximum length of the data fields. For now this will always return the value 31. Different flags however might decrease the actual available length in these data fields.

pub async fn add_advertising<'_>(
    &'_ mut self,
    controller: Controller,
    info: AdvertisingParams
) -> Result<u8>

This command is used to configure an advertising instance that can be used to switch a Bluetooth Low Energy controller into advertising mode.

Added advertising information with this command will not be visible immediately if advertising is enabled via the Set Advertising command. The usage of the Set Advertising command takes precedence over this command. Instance information is stored and will be advertised once advertising via Set Advertising has been disabled.

The Instance identifier is a value between 1 and the number of supported instances. The value 0 is reserved. When the connectable flag is set, then the controller will use undirected connectable advertising. The value of the connectable setting can be overwritten this way. This is useful to switch a controller into connectable mode only for LE operation. This is similar to the mode 0x02 from the Set Advertising command.

Secondary channel flags can be used to advertise in secondary channel with the corresponding PHYs. These flag bits are mutually exclusive and setting multiple will result in Invalid Parameter error. Choosing either LE 1M or LE 2M will result in using extended advertising on the primary channel with LE 1M and the respectively LE 1M or LE 2M on the secondary channel. Choosing LE Coded will result in using extended advertising on the primary and secondary channels with LE Coded. Choosing none of these flags will result in legacy advertising.

If only one advertising Instance has been added, then the duration value will be ignored. It only applies for the case where multiple Instances are configured. In that case every Instance will be available for the duration time and after that it switches to the next one. This is a simple round-robin based approach.

When a timeout is provided, then the duration subtracts from the actual timeout value of that Instance. For example an Instance with timeout of 5 and duration of 2 will be scheduled exactly 3 times, twice with 2 seconds and once with one second. Other Instances have no influence on the timeout.

Re-adding an already existing instance (i.e. issuing the Add Advertising command with an Instance identifier of an existing instance) will update that instance's configuration.

An instance being added or changed while another instance is being advertised will not be visible immediately but only when the new/changed instance is being scheduled by the round robin advertising algorithm.

Changes to an instance that is currently being advertised will cancel that instance and switch to the next instance. The changes will be visible the next time the instance is scheduled for advertising. In case a single instance is active, this means that changes will be visible right away.

A pre-requisite is that LE is already enabled, otherwise this command will return a "rejected" response.

This command can be used when the controller is not powered and all settings will be programmed once powered.

pub async fn remove_advertising<'_>(
    &'_ mut self,
    controller: Controller,
    instance: u8
) -> Result<u8>

This command is used to remove an advertising instance that can be used to switch a Bluetooth Low Energy controller into advertising mode.

When the instance parameter is zero, then all previously added advertising Instances will be removed.

Removing advertising information with this command will not be visible as long as advertising is enabled via the Set Advertising command. The usage of the Set Advertising command takes precedence over this command. Changes to Instance information are stored and will be advertised once advertising via Set Advertising has been disabled.

Removing an instance while it is being advertised will immediately cancel the instance, even when it has been advertised less then its configured Timeout or Duration.

This command can be used when the controller is not powered and all settings will be programmed once powered.

pub async fn get_advertising_size<'_>(
    &'_ mut self,
    controller: Controller,
    instance: u8
) -> Result<AdvertisingSizeInfo>

The Read Advertising Features command returns the overall maximum size of advertising data and scan response data fields. That size is valid when no Flags are used. However when certain Flags are used, then the size might decrease. This command can be used to request detailed information about the maximum available size.

To get accurate information about the available size, the same flags values should be used with the Add Advertising command.

The max_adv_data_len and max_scan_rsp_len fields provide information about the maximum length of the data fields for the given flags values. When the flags field is zero, then these fields would contain the same values as Read Advertising Features.

impl<'a> BlueZClient<'a>

pub async fn set_device_class<'_>(
    &'_ mut self,
    controller: Controller,
    device_class: DeviceClass
) -> Result<(DeviceClass, ServiceClasses)>

This command is used to set the major and minor device class for BR/EDR capable controllers.

This command will also implicitly disable caching of pending CoD and EIR updates.

This command is only available for BR/EDR capable controllers (e.g. not for single-mode LE ones).

This command can be used when the controller is not powered and all settings will be programmed once powered.

In case the controller is powered off, Unknown will be returned for the class of device parameter. And after power on the new value will be announced via class of device changed event.

pub async fn add_uuid<'_>(
    &'_ mut self,
    controller: Controller,
    uuid: [u8; 16],
    svc_hint: ServiceClasses
) -> Result<(DeviceClass, ServiceClasses)>

This command is used to add a UUID to be published in EIR data. The accompanied SVC_Hint parameter is used to tell the kernel whether the service class bits of the Class of Device value need modifying due to this UUID.

This command can be used when the controller is not powered and all settings will be programmed once powered.

In case the controller is powered off, 0x000000 will be returned for the class of device parameter. And after power on the new value will be announced via class of device changed event.

pub async fn remove_uuid<'_>(
    &'_ mut self,
    controller: Controller,
    uuid: [u8; 16]
) -> Result<(DeviceClass, ServiceClasses)>

This command is used to remove a UUID previously added using the Add UUID command.

When the UUID parameter is an empty UUID (16 x 0x00), then all previously loaded UUIDs will be removed.

This command can be used when the controller is not powered and all settings will be programmed once powered.

In case the controller is powered off, 0x000000 will be returned for the class of device parameter. And after power on the new value will be announced via class of device changed event.

impl<'a> BlueZClient<'a>

pub async fn start_discovery<'_>(
    &'_ mut self,
    controller: Controller,
    address_types: BitFlags<AddressTypeFlag>
) -> Result<BitFlags<AddressTypeFlag>>

This command is used to start the process of discovering remote devices. A Device Found event will be sent for each discovered device.

Possible values for the address_type parameter are a bit-wise or of the following bits:

0 BR/EDR 1 LE Public 2 LE Random

By combining these e.g. the following values are possible:

1 BR/EDR 6 LE (public & random) 7 BR/EDR/LE (interleaved discovery)

This command can only be used when the controller is powered.

pub async fn stop_discovery<'_>(
    &'_ mut self,
    controller: Controller,
    address_types: BitFlags<AddressTypeFlag>
) -> Result<BitFlags<AddressTypeFlag>>

This command is used to stop the discovery process started using the Start Discovery command.

This command can only be used when the controller is powered.

pub async fn start_service_discovery<'_>(
    &'_ mut self,
    controller: Controller,
    address_types: BitFlags<AddressTypeFlag>,
    rssi_threshold: i8,
    uuids: Vec<[u8; 16]>
) -> Result<BitFlags<AddressTypeFlag>>

This command is used to start the process of discovering remote devices with a specific UUID. A Device Found event will be sent for each discovered device.

The service discovery uses active scanning for Low Energy scanning and will search for UUID in both advertising data and scan response data.

Found devices that have a RSSI value smaller than rssi_threshold are not reported via DeviceFound event. Setting a value of 127 will cause all devices to be reported.

The list of UUIDs identifies a logical OR. Only one of the UUIDs have to match to cause a DeviceFound event. Providing an empty list of UUIDs means that DeviceFound events are send out for all devices above the RSSI_Threshold.

In case rssi_threshold is set to 127 and uuids is empty, then this command behaves exactly the same as Start Discovery.

When the discovery procedure starts the Discovery event will notify this similar to Start Discovery.

This command can only be used when the controller is powered.

pub async fn start_limited_discovery<'_>(
    &'_ mut self,
    controller: Controller,
    address_types: BitFlags<AddressTypeFlag>
) -> Result<BitFlags<AddressTypeFlag>>

This command is used to start the process of discovering remote devices using the limited discovery procedure. A Device Found event will be sent for each discovered device.

The limited discovery uses active scanning for Low Energy scanning and will search for devices with the limited discoverability flag configured. On BR/EDR it uses LIAC and filters on the limited discoverability flag of the class of device.

When the discovery procedure starts the Discovery event will notify this similar to Start Discovery.

This command can only be used when the controller is powered.

impl<'a> BlueZClient<'a>

pub async fn confirm_name<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType,
    name_known: bool
) -> Result<(Address, AddressType)>

This command is only valid during device discovery and is expected for each Device Found event with the Confirm Name flag set.

The name_known parameter should be set to true if user space knows the name for the device and false if it doesn't. If set to false the kernel will perform a name resolving procedure for the device in question.

This command can only be used when the controller is powered.

pub async fn block_device<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType
) -> Result<(Address, AddressType)>

This command is used to add a device to the list of devices which should be blocked from being connected to the local controller.

For Low Energy devices, the blocking of a device takes precedence over auto-connection actions provided by Add Device. Blocked devices will not be auto-connected or even reported when found during background scanning. If the controller is connectable direct advertising from blocked devices will also be ignored.

Connections created from advertising of the controller will be dropped if the device is blocked.

This command can be used when the controller is not powered.

pub async fn unblock_device<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType
) -> Result<(Address, AddressType)>

This command is used to remove a device from the list of blocked devices (where it was added to using the Block Device command).

When the address parameter is 00:00:00:00:00:00, then all previously blocked devices will be unblocked.

This command can be used when the controller is not powered.

pub async fn disconnect<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType
) -> Result<(Address, AddressType)>

This command is used to force the disconnection of a currently connected device.

This command can only be used when the controller is powered.

pub async fn pin_code_reply<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType,
    pin_code: Option<Vec<u8>>
) -> Result<(Address, AddressType)>

This command is used to respond to a PIN Code request event. Pin code can be at most 16 bytes. Passing None will send a negative PIN code response. This command can only be used when the controller is powered.

pub async fn pair_device<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType,
    io_capability: IoCapability
) -> Result<(Address, AddressType)>

This command is used to trigger pairing with a remote device. The IO_Capability command parameter is used to temporarily (for this pairing event only) override the global IO Capability (set using the Set IO Capability command).

Passing a value 4 (KeyboardDisplay) will cause the kernel to convert it to 1 (DisplayYesNo) in the case of a BR/EDR connection (as KeyboardDisplay is specific to SMP).

The address and address_type of the return parameters will return the identity address if known. In case of resolvable random address given as command parameters and the remote provides an identity resolving key, the return parameters will provide the resolved address.

To allow tracking of which resolvable random address changed into which identity address, the New Identity Resolving Key event will be sent before receiving Command Complete event for this command.

This command can only be used when the controller is powered.

pub async fn cancel_pair_device<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType
) -> Result<(Address, AddressType)>

The address and address_type parameters should match what was given to a preceding Pair Device command.

This command can only be used when the controller is powered.

pub async fn unpair_device<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType,
    disconnect: bool
) -> Result<(Address, AddressType)>

Removes all keys associated with the remote device.

The disconnect parameter tells the kernel whether to forcefully disconnect any existing connections to the device. It should in practice always be true except for some special GAP qualification test-cases where a key removal without disconnecting is needed.

When unpairing a device its link key, long term key and if provided identity resolving key will be purged.

For devices using resolvable random addresses where the identity resolving key was available, after this command they will now no longer be resolved. The device will essentially become private again.

This command can only be used when the controller is powered.

pub async fn user_confirmation_reply<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType,
    reply: bool
) -> Result<(Address, AddressType)>

This command is used to respond to a User Confirmation Request event. This command can only be used when the controller is powered.

pub async fn user_passkey_reply<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType,
    passkey: Option<u32>
) -> Result<(Address, AddressType)>

This command is used to respond to a User Passkey Request event. Passing None for passkey will send a negative response. This command can only be used when the controller is powered.

pub async fn add_device<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType,
    action: AddDeviceAction
) -> Result<(Address, AddressType)>

This command is used to add a device to the action list. The action list allows scanning for devices and enables incoming connections from known devices.

With the BackgroundScan action, when the device is found, a new Device Found event will be sent indicating this device is available. This action is only valid for LE Public and LE Random address types.

With the AllowConnect action, the device is allowed to connect. For BR/EDR address type this means an incoming connection. For LE Public and LE Random address types, a connection will be established to devices using directed advertising. If successful a Device Connected event will be sent.

With the AutoConnect, when the device is found, it will be connected and if successful a Device Connected event will be sent. This action is only valid for LE Public and LE Random address types.

When a device is blocked using Block Device command, then it is valid to add the device here, but all actions will be ignored until the device is unblocked.

Devices added with AllowConnect are allowed to connect even if the connectable setting is off. This acts as list of known trusted devices.

This command can be used when the controller is not powered and all settings will be programmed once powered.

pub async fn remove_device<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType
) -> Result<(Address, AddressType)>

This command is used to remove a device from the action list previously added by using the Add Device command.

When the Address parameter is 00:00:00:00:00:00, then all previously added devices will be removed.

This command can be used when the controller is not powered and all settings will be programmed once powered.

impl<'a> BlueZClient<'a>

pub async fn load_link_keys<'_>(
    &'_ mut self,
    controller: Controller,
    keys: Vec<LinkKey>,
    debug: bool
) -> Result<()>

This command is used to feed the kernel with currently known link keys. The command does not need to be called again upon the receipt of New Link Key events since the kernel updates its list automatically.

The debug parameter is used to tell the kernel whether to accept the usage of debug keys or not. The allowed values for this parameter are 0x00 and 0x01. All other values will return an Invalid Parameters response.

Usage of the debug parameter is deprecated and has been replaced with the Set Debug Keys command. When setting the debug option via Load Link Keys command it has the same affect as setting it via Set Debug Keys and applies to all keys in the system.

pub async fn load_long_term_keys<'_>(
    &'_ mut self,
    controller: Controller,
    keys: Vec<LongTermKey>
) -> Result<()>

This command is used to feed the kernel with currently known (SMP) Long Term Keys. The command does not need to be called again upon the receipt of New Long Term Key events since the kernel updates its list automatically.

The provided address and address_type are the identity of a device. So either its public address or static random address.

Unresolvable random addresses and resolvable random addresses are not valid and will be rejected.

This command can be used when the controller is not powered.

pub async fn load_identity_resolving_keys<'_>(
    &'_ mut self,
    controller: Controller,
    keys: Vec<IdentityResolvingKey>
) -> Result<()>

This command is used to feed the kernel with currently known identity resolving keys. The command does not need to be called again upon the receipt of New Identity Resolving Key events since the kernel updates its list automatically.

The provided address and address_type are the identity of a device. So either its public address or static random address.

Unresolvable random addresses and resolvable random addresses are not valid and will be rejected.

This command can be used when the controller is not powered.

pub async fn load_connection_parameters<'_>(
    &'_ mut self,
    controller: Controller,
    connection_params: Vec<ConnectionParams>
) -> Result<()>

This command is used to load connection parameters from several devices into kernel. Currently this is only supported on controllers with Low Energy support.

The provided Address and Address_Type are the identity of a device. So either its public address or static random address.

The min_connection_interval, max_connection_interval, connection_latency and supervision_timeout parameters should be configured as described in Core 4.1 spec, Vol 2, 7.8.12.

This command can be used when the controller is not powered.

pub async fn load_blocked_keys<'_>(
    &'_ mut self,
    controller: Controller,
    keys: Vec<BlockedKey>
) -> Result<()>

This command is used to feed the kernel a list of keys that are known to be vulnerable.

If the pairing procedure produces any of these keys, they will be silently dropped and any attempt to enable encryption rejected.

This command can be used when the controller is not powered.

impl<'a> BlueZClient<'a>

pub async fn read_local_oob_data<'_>(
    &'_ mut self,
    controller: Controller
) -> Result<OutOfBandData>

This command is used to read the local Out of Band data.

This command can only be used when the controller is powered.

If Secure Connections support is enabled, then this command will return P-192 versions of hash and randomizer as well as P-256 versions of both.

Values returned by this command become invalid when the controller is powered down. After each power-cycle it is required to call this command again to get updated values.

pub async fn read_local_oob_ext_data<'_>(
    &'_ mut self,
    controller: Controller,
    address_types: BitFlags<AddressTypeFlag>
) -> Result<(BitFlags<AddressTypeFlag>, Bytes)>

pub async fn add_remote_oob_data<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType,
    data: OutOfBandData
) -> Result<(Address, AddressType)>

This command is used to provide Out of Band data for a remote device.

Provided Out Of Band data is persistent over power down/up toggles.

This command also accept optional P-256 versions of hash and randomizer. If they are not provided, then they are set to zero value.

The P-256 versions of both can also be provided when the support for Secure Connections is not enabled. However in that case they will never be used.

To only provide the P-256 versions of hash and randomizer, it is valid to leave both P-192 fields as zero values. If Secure Connections is disabled, then of course this is the same as not providing any data at all.

When providing data for remote LE devices, then the Hash_192 and and Randomizer_192 fields are not used and shell be set to zero.

The Hash_256 and Randomizer_256 fields can be used for LE secure connections Out Of Band data. If only LE secure connections data is provided the Hash_P192 and Randomizer_P192 fields can be set to zero. Currently there is no support for providing the Security Manager TK Value for LE legacy pairing.

If Secure Connections Only mode has been enabled, then providing Hash_P192 and Randomizer_P192 is not allowed. They are required to be set to zero values.

This command can be used when the controller is not powered and all settings will be programmed once powered.

pub async fn remove_remote_oob_data<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType
) -> Result<(Address, AddressType)>

This command is used to remove data added using the Add Remote Out Of Band Data command.

When the address parameter is 00:00:00:00:00:00, then all previously added data will be removed.

This command can be used when the controller is not powered and all settings will be programmed once powered.

impl<'a> BlueZClient<'a>

pub async fn get_mgmt_version<'_>(&'_ mut self) -> Result<ManagementVersion>

This command returns the Management version and revision. Besides, being informational the information can be used to determine whether certain behavior has changed or bugs fixed when interacting with the kernel.

pub async fn get_controller_list<'_>(&'_ mut self) -> Result<Vec<Controller>>

This command returns the list of currently known controllers. Controllers added or removed after calling this command can be monitored using the Index Added and Index Removed events.

pub async fn get_controller_info<'_>(
    &'_ mut self,
    controller: Controller
) -> Result<ControllerInfo>

This command is used to retrieve the current state and basic information of a controller. It is typically used right after getting the response to the Read Controller Index List command or an Index Added event.

The address parameter describes the controllers public address and it can be expected that it is set. However in case of single mode Low Energy only controllers it can be 00:00:00:00:00:00. To power on the controller in this case, it is required to configure a static address using Set Static address command first.

If the public address is set, then it will be used as identity address for the controller. If no public address is available, then the configured static address will be used as identity address.

In the case of a dual-mode controller with public address that is configured as Low Energy only device (BR/EDR switched off), the static address is used when set and public address otherwise.

If no short name is set the Short_Name parameter will be all zeroes.

pub async fn get_connections<'_>(
    &'_ mut self,
    controller: Controller
) -> Result<Vec<(Address, AddressType)>>

This command is used to retrieve a list of currently connected devices.

For devices using resolvable random addresses with a known identity resolving key, the address and address_type will contain the identity information.

This command can only be used when the controller is powered.

pub async fn get_connection_info<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType
) -> Result<ConnectionInfo>

This command is used to get connection information.

pub async fn get_clock_info<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address,
    address_type: AddressType
) -> Result<ClockInfo>

This command is used to get local and piconet clock information.

pub async fn get_unconfigured_controller_list<'_>(
    &'_ mut self
) -> Result<Vec<Controller>>

This command returns the list of currently unconfigured controllers. Unconfigured controllers added after calling this command can be monitored using the Unconfigured Index Added event.

An unconfigured controller can either move to a configured state by indicating Unconfigured Index Removed event followed by an Index Added event; or it can be removed from the system which would be indicated by the Unconfigured Index Removed event.

Only controllers that require configuration will be listed with this command. A controller that is fully configured will not be listed even if it supports configuration changes.

pub async fn get_controller_config_info<'_>(
    &'_ mut self,
    controller: Controller
) -> Result<ControllerConfigInfo>

This command is used to retrieve the supported configuration options of a controller and the missing configuration options.

The missing options are required to be configured before the controller is considered fully configured and ready for standard operation. The command is typically used right after getting the response to Read Unconfigured Controller Index List command or Unconfigured Index Added event.

Supported_Options and Missing_Options is a bitmask with currently the following available bits:

0 External configuration 1 Bluetooth public address configuration

It is valid to call this command on controllers that do not require any configuration. It is possible that a fully configured controller offers additional support for configuration.

For example a controller may contain a valid Bluetooth public device address, but also allows to configure it from the host stack. In this case the general support for configurations will be indicated by the Controller Configuration settings. For controllers where no configuration options are available that setting option will not be present.

When all configurations have been completed and as a result the Missing_Options mask would become empty, then the now ready controller will be announced via Index Added event.

pub async fn get_ext_controller_list<'_>(
    &'_ mut self
) -> Result<Vec<(Controller, ControllerType, ControllerBus)>>

This command returns the list of currently known controllers. It includes configured, unconfigured and alternate controllers.

Controllers added or removed after calling this command can be be monitored using the Extended Index Added and Extended Index Removed events.

The existing Index Added, Index Removed, Unconfigured Index Added and Unconfigured Index Removed are no longer sent after this command has been used at least once.

Instead of calling Read Controller Index List and Read Unconfigured Controller Index List, this command combines all the information and can be used to retrieve the controller list.

Controllers marked as RAW only operation are currently not listed by this command.

pub async fn get_ext_controller_info<'_>(
    &'_ mut self,
    controller: Controller
) -> Result<ControllerInfoExt>

This command is used to retrieve the current state and basic information of a controller. It is typically used right after getting the response to the Read Controller Index List command or an Index Added event (or its extended counterparts).

The Address parameter describes the controllers public address and it can be expected that it is set. However in case of single mode Low Energy only controllers it can be 00:00:00:00:00:00. To power on the controller in this case, it is required to configure a static address using Set Static Address command first.

If the public address is set, then it will be used as identity address for the controller. If no public address is available, then the configured static address will be used as identity address.

In the case of a dual-mode controller with public address that is configured as Low Energy only device (BR/EDR switched off), the static address is used when set and public address otherwise.

pub async fn get_phy_config<'_>(
    &'_ mut self,
    controller: Controller
) -> Result<PhyConfig>

If BR/EDR is supported, then BR 1M 1-Slot is supported by default and can also not be deselected. If LE is supported, then LE 1M TX and LE 1M RX are supported by default.

Disabling BR/EDR completely or respectively LE has no impact on the PHY configuration. It is remembered over power cycles.

impl<'a> BlueZClient<'a>

pub async fn set_local_name<'_, '_, '_>(
    &'_ mut self,
    controller: Controller,
    name: &'_ str,
    short_name: Option<&'_ str>
) -> Result<(CString, CString)>

This command is used to set the local name of a controller. The command parameters also include a short name which will be used in case the full name doesn't fit within EIR/AD data.

Name can be at most 248 bytes. Short name can be at most 10 bytes. This function returns a pair of OsStrings in the order (name, short_name).

This command can be used when the controller is not powered and all settings will be programmed once powered.

The values of name and short name will be remembered when switching the controller off and back on again. So the name and short name only have to be set once when a new controller is found and will stay until removed.

pub async fn set_powered<'_>(
    &'_ mut self,
    controller: Controller,
    powered: bool
) -> Result<ControllerSettings>

This command is used to power on or off a controller.

If discoverable setting is activated with a timeout, then switching the controller off will expire this timeout and disable discoverable.

Settings programmed via Set Advertising and Add/Remove Advertising while the controller was powered off will be activated when powering the controller on.

Switching the controller off will permanently cancel and remove all advertising instances with a timeout set, i.e. time limited advertising instances are not being remembered across power cycles. Advertising Removed events will be issued accordingly.

pub async fn set_discoverable<'_>(
    &'_ mut self,
    controller: Controller,
    discoverability: DiscoverableMode,
    timeout: Option<u16>
) -> Result<ControllerSettings>

This command is used to set the discoverable property of a controller.

Timeout is the time in seconds and is only meaningful when Discoverable is set to General or Limited. Providing a timeout with None returns Invalid Parameters. For Limited, the timeout is required.

This command is only available for BR/EDR capable controllers (e.g. not for single-mode LE ones). It will return Not Supported otherwise.

This command can be used when the controller is not powered and all settings will be programmed once powered, however using a timeout when the controller is not powered will return Not Powered error.

When switching discoverable on and the connectable setting is off it will return Rejected error.

pub async fn set_connectable<'_>(
    &'_ mut self,
    controller: Controller,
    connectable: bool
) -> Result<ControllerSettings>

This command is used to set the connectable property of a controller.

This command is available for BR/EDR, LE-only and also dual mode controllers. For BR/EDR is changes the page scan setting and for LE controllers it changes the advertising type. For dual mode controllers it affects both settings.

For LE capable controllers the connectable setting takes effect when advertising is enabled (peripheral) or when directed advertising events are received (central).

This command can be used when the controller is not powered and all settings will be programmed once powered.

When switching connectable off, it will also switch off the discoverable setting. Switching connectable back on will not restore a previous discoverable. It will stay off and needs to be manually switched back on.

When switching connectable off, it will expire a discoverable setting with a timeout.

This setting does not affect known devices from Add Device command. These devices are always allowed to connect.

pub async fn set_fast_connectable<'_>(
    &'_ mut self,
    controller: Controller,
    fast_connectable: bool
) -> Result<ControllerSettings>

This command is used to set the controller into a connectable state where the page scan parameters have been set in a way to favor faster connect times with the expense of higher power consumption.

This command is only available for BR/EDR capable controllers (e.g. not for single-mode LE ones). It will return Not Supported otherwise.

This command can be used when the controller is not powered and all settings will be programmed once powered.

The setting will be remembered during power down/up toggles.

pub async fn set_bondable<'_>(
    &'_ mut self,
    controller: Controller,
    bondable: bool
) -> Result<ControllerSettings>

This command is used to set the bondable (pairable) property of an controller.

This command can be used when the controller is not powered and all settings will be programmed once powered.

Turning bondable on will not automatically switch the controller into connectable mode. That needs to be done separately.

The setting will be remembered during power down/up toggles.

pub async fn set_link_security<'_>(
    &'_ mut self,
    controller: Controller,
    link_security: bool
) -> Result<ControllerSettings>

This command is used to either enable or disable link level security for an controller (also known as Security Mode 3).

This command is only available for BR/EDR capable controllers (e.g. not for single-mode LE ones). It will return Not Supported otherwise.

This command can be used when the controller is not powered and all settings will be programmed once powered.

pub async fn set_ssp<'_>(
    &'_ mut self,
    controller: Controller,
    ssp: bool
) -> Result<ControllerSettings>

This command is used to enable/disable Secure Simple Pairing support for a controller.

This command is only available for BR/EDR capable controllers supporting the core specification version 2.1 or greater (e.g. not for single-mode LE controllers or pre-2.1 ones).

This command can be used when the controller is not powered and all settings will be programmed once powered.

In case the controller does not support Secure Simple Pairing, the command will fail regardless with Not Supported error.

pub async fn set_high_speed<'_>(
    &'_ mut self,
    controller: Controller,
    high_speed: bool
) -> Result<ControllerSettings>

This command is used to enable/disable Bluetooth High Speed support for a controller.

This command is only available for BR/EDR capable controllers (e.g. not for single-mode LE ones).

This command can be used when the controller is not powered and all settings will be programmed once powered.

To enable High Speed support, it is required that Secure Simple Pairing support is enabled first. High Speed support is not possible for connections without Secure Simple Pairing.

When switching Secure Simple Pairing off, the support for High Speed will be switched off as well. Switching Secure Simple Pairing back on, will not re-enable High Speed support. That needs to be done manually.

pub async fn set_le<'_>(
    &'_ mut self,
    controller: Controller,
    le: bool
) -> Result<ControllerSettings>

This command is used to enable/disable Low Energy support for a controller.

This command is only available for LE capable controllers and will yield in a Not Supported error otherwise.

This command can be used when the controller is not powered and all settings will be programmed once powered.

In case the kernel subsystem does not support Low Energy or the controller does not either, the command will fail regardless.

Disabling LE support will permanently disable and remove all advertising instances configured with the Add Advertising command. Advertising Removed events will be issued accordingly.

pub async fn set_advertising<'_>(
    &'_ mut self,
    controller: Controller,
    mode: LeAdvertisingMode
) -> Result<ControllerSettings>

This command is used to enable LE advertising on a controller that supports it.

The value Disabled disables advertising, the value WithConnectable enables advertising with considering of connectable setting and the value Enabled enables advertising in connectable mode.

Using value WithConnectable means that when connectable setting is disabled, the advertising happens with undirected non-connectable advertising packets and a non-resolvable random address is used. If connectable setting is enabled, then undirected connectable advertising packets and the identity address or resolvable private address are used.

LE Devices configured via Add Device command with Action 0x01 have no effect when using Advertising value 0x01 since only the connectable setting is taken into account.

To utilize undirected connectable advertising without changing the connectable setting, the value Enabled can be utilized. It makes the device connectable via LE without the requirement for being connectable on BR/EDR (and/or LE).

The value Enabled should be the preferred mode of operation when implementing peripheral mode.

Using this command will temporarily deactivate any configuration made by the Add Advertising command. This command takes precedence. Once a Set Advertising command with value Disabled is issued any previously made configurations via Add/Remove Advertising, including such changes made while Set Advertising was active, will be re- enabled.

A pre-requisite is that LE is already enabled, otherwise this command will return a "rejected" response.

pub async fn set_bredr<'_>(
    &'_ mut self,
    controller: Controller,
    enabled: bool
) -> Result<ControllerSettings>

This command is used to enable or disable BR/EDR support on a dual-mode controller.

A pre-requisite is that LE is already enabled, otherwise this command will return a "rejected" response. Enabling BR/EDR can be done both when powered on and powered off, however disabling it can only be done when powered off (otherwise the command will again return "rejected"). Disabling BR/EDR will automatically disable all other BR/EDR related settings.

pub async fn set_io_capability<'_>(
    &'_ mut self,
    controller: Controller,
    io_capability: IoCapability
) -> Result<()>

This command is used to set the IO Capability used for pairing. The command accepts both SSP and SMP values.

Passing KeyboardDisplay will cause the kernel to convert it to DisplayYesNo)in the case of a BR/EDR connection (as KeyboardDisplay is specific to SMP).

This command can be used when the controller is not powered.

pub async fn set_device_id<'_>(
    &'_ mut self,
    controller: Controller,
    source: u16,
    vendor: u16,
    product: u16,
    version: u16
) -> Result<()>

This command can be used when the controller is not powered and all settings will be programmed once powered.

The Source parameter selects the organization that assigned the Vendor parameter:

• 0x0000 Disable Device ID
• 0x0001 Bluetooth SIG
• 0x0002 USB Implementer's Forum

The information is put into the EIR data. If the controller does not support EIR or if SSP is disabled, this command will still succeed. The information is stored for later use and will survive toggling SSP on and off.

pub async fn set_scan_parameters<'_>(
    &'_ mut self,
    controller: Controller,
    interval: u16,
    window: u16
) -> Result<()>

This command allows for setting the Low Energy scan parameters used for connection establishment and passive scanning. It is only supported on controllers with LE support.

pub async fn set_static_address<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address
) -> Result<ControllerSettings>

This command allows for setting the static random address. It is only supported on controllers with LE support. The static random address is suppose to be valid for the lifetime of the controller or at least until the next power cycle. To ensure such behavior, setting of the address is limited to when the controller is powered off.

The Address::zero() (00:00:00:00:00:00) can be used to disable the static address.

When a controller has a public address (which is required for all dual-mode controllers), this address is not used. If a dual-mode controller is configured as Low Energy only devices (BR/EDR has been switched off), then the static address is used. Only when the controller information reports a zero address (00:00:00:00:00:00), it is required to configure a static address first.

If privacy mode is enabled and the controller is single mode LE only without a public address, the static random address is used as identity address.

The Static Address flag from the current settings can also be used to determine if the configured static address is in use or not.

pub async fn set_secure_connections_mode<'_>(
    &'_ mut self,
    controller: Controller,
    mode: SecureConnectionsMode
) -> Result<ControllerSettings>

This command is used to enable/disable Secure Connections support for a controller.

The value Disabled disables Secure Connections, the value Enabled enables Secure Connections and the value Only enables Secure Connections Only mode.

This command is only available for LE capable controllers as well as controllers supporting the core specification version 4.1 or greater.

This command can be used when the controller is not powered and all settings will be programmed once powered.

In case the controller does not support Secure Connections the command will fail regardless with Not Supported error.

pub async fn set_debug_mode<'_>(
    &'_ mut self,
    controller: Controller,
    mode: DebugKeysMode
) -> Result<ControllerSettings>

This command is used to tell the kernel whether to accept the usage of debug keys or not.

With a value of Discard any generated debug key will be discarded as soon as the connection terminates.

With a value of Persist generated debug keys will be kept and can be used for future connections. However debug keys are always marked as non persistent and should not be stored. This means a reboot or changing the value back to 0x00 will delete them.

With a value of PersistAndGenerate generated debug keys will be kept and can be used for future connections. This has the same affect as with value Persist. However in addition this value will also enter the controller mode to generate debug keys for each new pairing. Changing the value back to Persist or Discard will disable the controller mode for generating debug keys.

pub async fn set_privacy_mode<'_>(
    &'_ mut self,
    controller: Controller,
    mode: PrivacyMode,
    identity_resolving_key: [u8; 16]
) -> Result<ControllerSettings>

This command is used to enable Low Energy Privacy feature using resolvable private addresses.

The value Disabled disables privacy mode, the values Strict and Limited enable privacy mode.

With value Strict the kernel will always use the privacy mode. This means resolvable private address is used when the controller is discoverable and also when pairing is initiated.

With value Limited the kernel will use a limited privacy mode with a resolvable private address except when the controller is bondable and discoverable, in which case the identity address is used.

Exposing the identity address when bondable and discoverable or during initiated pairing can be a privacy issue. For dual-mode controllers this can be neglected since its public address will be exposed over BR/EDR anyway. The benefit of exposing the identity address for pairing purposes is that it makes matching up devices with dual-mode topology during device discovery now possible.

If the privacy value Limited is used, then also the GATT database should expose the Privacy Characteristic so that remote devices can determine if the privacy feature is in use or not.

When the controller has a public address (mandatory for dual-mode controllers) it is used as identity address. In case the controller is single mode LE only without a public address, it is required to configure a static random address first. The privacy mode can only be enabled when an identity address is available.

The identity_resolving_key is the local key assigned for the local resolvable private address.

pub async fn set_external_config<'_>(
    &'_ mut self,
    controller: Controller,
    config: bool
) -> Result<ControllerSettings>

This command allows to change external configuration option to indicate that a controller is now configured or unconfigured.

The value false sets unconfigured state and the value true sets configured state of the controller.

It is not mandatory that this configuration option is provided by a controller. If it is provided, the configuration has to happen externally using user channel operation or via vendor specific methods.

Setting this option and when Missing_Options returns zero, this means that the controller will switch to configured state and it can be expected that it will be announced via Index Added event.

Wrongly configured controllers might still cause an error when trying to power them via Set Powered command.

pub async fn set_public_address<'_>(
    &'_ mut self,
    controller: Controller,
    address: Address
) -> Result<ControllerSettings>

This command allows configuration of public address. Since a vendor specific procedure is required, this command might not be supported by all controllers. Actually most likely only a handful embedded controllers will offer support for this command.

When the support for Bluetooth public address configuration is indicated in the supported options mask, then this command can be used to configure the public address.

It is only possible to configure the public address when the controller is powered off.

For an unconfigured controller and when this function returns an empty mask, this means that a Index Added event for the now fully configured controller can be expected.

For a fully configured controller, the current controller index will become invalid and an Unconfigured Index Removed event will be sent. Once the address has been successfully changed an Index Added event will be sent. There is no guarantee that the controller index stays the same.

All previous configured parameters and settings are lost when this command succeeds. The controller has to be treated as new one. Use this command for a fully configured controller only when you really know what you are doing.

pub async fn set_appearance<'_>(
    &'_ mut self,
    controller: Controller,
    appearance: u16
) -> Result<()>

This command is used to set the appearance value of a controller.

This command can be used when the controller is not powered and all settings will be programmed once powered.

The value of appearance will be remembered when switching the controller off and back on again. So the appearance only have to be set once when a new controller is found and will stay until removed.

pub async fn set_phy_config<'_>(
    &'_ mut self,
    controller: Controller,
    selected_phys: BitFlags<PhyFlag>
) -> Result<()>

on the PHY configuration. It is remembered over power cycles.

impl<'a> BlueZClient<'a>

pub fn new() -> Result<Self>

pub fn new_with_handler<H: FnMut(Controller, &Event) + Send + 'a>(
    handler: H
) -> Result<Self>

pub fn set_handler<H: FnMut(Controller, &Event) + Send + 'a>(
    &mut self,
    handler: H
)

Sets a handler that will be called every time this client processes an event. CommandComplete and CommandStatus events will NOT reach this handler; instead their contents can be accessed as the return value of the method that you called.

pub fn clear_handler(&mut self)

Removes whatever handler is currently attached to this client.

pub async fn process<'_>(&'_ mut self) -> Result<Response>

Tells the client to check if any new data has been sent in by the kernel. If you do not call this method, you will not recieve any events except when you happen to issue a command.