mirror of
https://git.kernel.org/pub/scm/bluetooth/bluez.git
synced 2024-11-24 12:44:19 +08:00
50261df73c
This adds a pattern filter which can be used to filter devices by address or name prefix which is quite convenient on a crowded environment.
329 lines
9.4 KiB
Plaintext
329 lines
9.4 KiB
Plaintext
BlueZ D-Bus Adapter API description
|
|
***********************************
|
|
|
|
|
|
Adapter hierarchy
|
|
=================
|
|
|
|
Service org.bluez
|
|
Interface org.bluez.Adapter1
|
|
Object path [variable prefix]/{hci0,hci1,...}
|
|
|
|
Methods void StartDiscovery()
|
|
|
|
This method starts the device discovery session. This
|
|
includes an inquiry procedure and remote device name
|
|
resolving. Use StopDiscovery to release the sessions
|
|
acquired.
|
|
|
|
This process will start creating Device objects as
|
|
new devices are discovered.
|
|
|
|
During discovery RSSI delta-threshold is imposed.
|
|
|
|
Possible errors: org.bluez.Error.NotReady
|
|
org.bluez.Error.Failed
|
|
|
|
void StopDiscovery()
|
|
|
|
This method will cancel any previous StartDiscovery
|
|
transaction.
|
|
|
|
Note that a discovery procedure is shared between all
|
|
discovery sessions thus calling StopDiscovery will only
|
|
release a single session.
|
|
|
|
Possible errors: org.bluez.Error.NotReady
|
|
org.bluez.Error.Failed
|
|
org.bluez.Error.NotAuthorized
|
|
|
|
void RemoveDevice(object device)
|
|
|
|
This removes the remote device object at the given
|
|
path. It will remove also the pairing information.
|
|
|
|
Possible errors: org.bluez.Error.InvalidArguments
|
|
org.bluez.Error.Failed
|
|
|
|
void SetDiscoveryFilter(dict filter)
|
|
|
|
This method sets the device discovery filter for the
|
|
caller. When this method is called with no filter
|
|
parameter, filter is removed.
|
|
|
|
Parameters that may be set in the filter dictionary
|
|
include the following:
|
|
|
|
array{string} UUIDs
|
|
|
|
Filter by service UUIDs, empty means match
|
|
_any_ UUID.
|
|
|
|
When a remote device is found that advertises
|
|
any UUID from UUIDs, it will be reported if:
|
|
- Pathloss and RSSI are both empty.
|
|
- only Pathloss param is set, device advertise
|
|
TX pwer, and computed pathloss is less than
|
|
Pathloss param.
|
|
- only RSSI param is set, and received RSSI is
|
|
higher than RSSI param.
|
|
|
|
int16 RSSI
|
|
|
|
RSSI threshold value.
|
|
|
|
PropertiesChanged signals will be emitted
|
|
for already existing Device objects, with
|
|
updated RSSI value. If one or more discovery
|
|
filters have been set, the RSSI delta-threshold,
|
|
that is imposed by StartDiscovery by default,
|
|
will not be applied.
|
|
|
|
uint16 Pathloss
|
|
|
|
Pathloss threshold value.
|
|
|
|
PropertiesChanged signals will be emitted
|
|
for already existing Device objects, with
|
|
updated Pathloss value.
|
|
|
|
string Transport (Default "auto")
|
|
|
|
Transport parameter determines the type of
|
|
scan.
|
|
|
|
Possible values:
|
|
"auto" - interleaved scan
|
|
"bredr" - BR/EDR inquiry
|
|
"le" - LE scan only
|
|
|
|
If "le" or "bredr" Transport is requested,
|
|
and the controller doesn't support it,
|
|
org.bluez.Error.Failed error will be returned.
|
|
If "auto" transport is requested, scan will use
|
|
LE, BREDR, or both, depending on what's
|
|
currently enabled on the controller.
|
|
|
|
bool DuplicateData (Default: true)
|
|
|
|
Disables duplicate detection of advertisement
|
|
data.
|
|
|
|
When enabled PropertiesChanged signals will be
|
|
generated for either ManufacturerData and
|
|
ServiceData everytime they are discovered.
|
|
|
|
bool Discoverable (Default: false)
|
|
|
|
Make adapter discoverable while discovering,
|
|
if the adapter is already discoverable setting
|
|
this filter won't do anything.
|
|
|
|
string Pattern (Default: none)
|
|
|
|
Discover devices where the pattern matches
|
|
either the prefix of the address or
|
|
device name which is convenient way to limited
|
|
the number of device objects created during a
|
|
discovery.
|
|
|
|
When set disregards device discoverable flags.
|
|
|
|
Note: The pattern matching is ignored if there
|
|
are other client that don't set any pattern as
|
|
it work as a logical OR, also setting empty
|
|
string "" pattern will match any device found.
|
|
|
|
When discovery filter is set, Device objects will be
|
|
created as new devices with matching criteria are
|
|
discovered regardless of they are connectable or
|
|
discoverable which enables listening to
|
|
non-connectable and non-discoverable devices.
|
|
|
|
When multiple clients call SetDiscoveryFilter, their
|
|
filters are internally merged, and notifications about
|
|
new devices are sent to all clients. Therefore, each
|
|
client must check that device updates actually match
|
|
its filter.
|
|
|
|
When SetDiscoveryFilter is called multiple times by the
|
|
same client, last filter passed will be active for
|
|
given client.
|
|
|
|
SetDiscoveryFilter can be called before StartDiscovery.
|
|
It is useful when client will create first discovery
|
|
session, to ensure that proper scan will be started
|
|
right after call to StartDiscovery.
|
|
|
|
Possible errors: org.bluez.Error.NotReady
|
|
org.bluez.Error.NotSupported
|
|
org.bluez.Error.Failed
|
|
|
|
array{string} GetDiscoveryFilters()
|
|
|
|
Return available filters that can be given to
|
|
SetDiscoveryFilter.
|
|
|
|
Possible errors: None
|
|
|
|
object ConnectDevice(dict properties) [experimental]
|
|
|
|
This method connects to device without need of
|
|
performing General Discovery. Connection mechanism is
|
|
similar to Connect method from Device1 interface with
|
|
exception that this method returns success when physical
|
|
connection is established. After this method returns,
|
|
services discovery will continue and any supported
|
|
profile will be connected. There is no need for calling
|
|
Connect on Device1 after this call. If connection was
|
|
successful this method returns object path to created
|
|
device object.
|
|
|
|
Parameters that may be set in the filter dictionary
|
|
include the following:
|
|
|
|
string Address
|
|
|
|
The Bluetooth device address of the remote
|
|
device. This parameter is mandatory.
|
|
|
|
string AddressType
|
|
|
|
The Bluetooth device Address Type. This is
|
|
address type that should be used for initial
|
|
connection. If this parameter is not present
|
|
BR/EDR device is created.
|
|
|
|
Possible values:
|
|
"public" - Public address
|
|
"random" - Random address
|
|
|
|
Possible errors: org.bluez.Error.InvalidArguments
|
|
org.bluez.Error.AlreadyExists
|
|
org.bluez.Error.NotSupported
|
|
org.bluez.Error.NotReady
|
|
org.bluez.Error.Failed
|
|
|
|
Properties string Address [readonly]
|
|
|
|
The Bluetooth device address.
|
|
|
|
string AddressType [readonly]
|
|
|
|
The Bluetooth Address Type. For dual-mode and BR/EDR
|
|
only adapter this defaults to "public". Single mode LE
|
|
adapters may have either value. With privacy enabled
|
|
this contains type of Identity Address and not type of
|
|
address used for connection.
|
|
|
|
Possible values:
|
|
"public" - Public address
|
|
"random" - Random address
|
|
|
|
string Name [readonly]
|
|
|
|
The Bluetooth system name (pretty hostname).
|
|
|
|
This property is either a static system default
|
|
or controlled by an external daemon providing
|
|
access to the pretty hostname configuration.
|
|
|
|
string Alias [readwrite]
|
|
|
|
The Bluetooth friendly name. This value can be
|
|
changed.
|
|
|
|
In case no alias is set, it will return the system
|
|
provided name. Setting an empty string as alias will
|
|
convert it back to the system provided name.
|
|
|
|
When resetting the alias with an empty string, the
|
|
property will default back to system name.
|
|
|
|
On a well configured system, this property never
|
|
needs to be changed since it defaults to the system
|
|
name and provides the pretty hostname. Only if the
|
|
local name needs to be different from the pretty
|
|
hostname, this property should be used as last
|
|
resort.
|
|
|
|
uint32 Class [readonly]
|
|
|
|
The Bluetooth class of device.
|
|
|
|
This property represents the value that is either
|
|
automatically configured by DMI/ACPI information
|
|
or provided as static configuration.
|
|
|
|
boolean Powered [readwrite]
|
|
|
|
Switch an adapter on or off. This will also set the
|
|
appropriate connectable state of the controller.
|
|
|
|
The value of this property is not persistent. After
|
|
restart or unplugging of the adapter it will reset
|
|
back to false.
|
|
|
|
boolean Discoverable [readwrite]
|
|
|
|
Switch an adapter to discoverable or non-discoverable
|
|
to either make it visible or hide it. This is a global
|
|
setting and should only be used by the settings
|
|
application.
|
|
|
|
If the DiscoverableTimeout is set to a non-zero
|
|
value then the system will set this value back to
|
|
false after the timer expired.
|
|
|
|
In case the adapter is switched off, setting this
|
|
value will fail.
|
|
|
|
When changing the Powered property the new state of
|
|
this property will be updated via a PropertiesChanged
|
|
signal.
|
|
|
|
For any new adapter this settings defaults to false.
|
|
|
|
boolean Pairable [readwrite]
|
|
|
|
Switch an adapter to pairable or non-pairable. This is
|
|
a global setting and should only be used by the
|
|
settings application.
|
|
|
|
Note that this property only affects incoming pairing
|
|
requests.
|
|
|
|
For any new adapter this settings defaults to true.
|
|
|
|
uint32 PairableTimeout [readwrite]
|
|
|
|
The pairable timeout in seconds. A value of zero
|
|
means that the timeout is disabled and it will stay in
|
|
pairable mode forever.
|
|
|
|
The default value for pairable timeout should be
|
|
disabled (value 0).
|
|
|
|
uint32 DiscoverableTimeout [readwrite]
|
|
|
|
The discoverable timeout in seconds. A value of zero
|
|
means that the timeout is disabled and it will stay in
|
|
discoverable/limited mode forever.
|
|
|
|
The default value for the discoverable timeout should
|
|
be 180 seconds (3 minutes).
|
|
|
|
boolean Discovering [readonly]
|
|
|
|
Indicates that a device discovery procedure is active.
|
|
|
|
array{string} UUIDs [readonly]
|
|
|
|
List of 128-bit UUIDs that represents the available
|
|
local services.
|
|
|
|
string Modalias [readonly, optional]
|
|
|
|
Local Device ID information in modalias format
|
|
used by the kernel and udev.
|