Adapter Interface
Description
The "Adapter" interface provides methods to setup the local adapter(s), search remote devices, pairing and search for services.
This interface is considered stable and no change is planned.
For each available adapter the hcid register an adapter object instance provided in the path "/org/bluez/hci{0, 1, 2, ...}".
org.bluez.Adapter
Adapter hierarchy
=================
Service org.bluez
Interface org.bluez.Adapter
Object path /org/bluez/{hci0,hci1,...}
Methods string GetAddress()
Returns the device address for a given path.
Example: "00:11:22:33:44:55"
Possible errors: none
string GetVersion()
Returns the version of the Bluetooth chip. This version
is compiled from the LMP version. In case of EDR the
features attribute must be checked.
Example: "Bluetooth 2.0 + EDR"
Possible errors: none
string GetRevision()
Returns the revision of the Bluetooth chip. This is a
vendor specific value and in most cases it represents
the firmware version. This might derive from the HCI
revision and LMP subversion values or via extra vendor
specific commands.
In case the revision of a chip is not available. This
method should return the LMP subversion value as a
string.
Example: "HCI 19.2"
Possible errors: org.bluez.Error.Failed
string GetManufacturer()
Returns the manufacturer of the Bluetooth chip. If
the company id is not know the sting "Company ID %d"
where %d should be replaced with the numeric value
from the manufacturer field.
Example: "Cambridge Silicon Radio"
Possible errors: org.bluez.Error.Failed
string GetCompany()
Returns the company name from the OUI database of the
Bluetooth device address. This function will need a
valid and up-to-date oui.txt from the IEEE. This value
will be different from the manufacturer string in the
most cases.
If the oui.txt file is not present or the OUI part of
the BD_ADDR is not listed, it should return the
string "OUI %s" where %s is the actual OUI.
Example: "Apple Computer"
Possible errors: org.bluez.Error.Failed
string GetMode()
Returns the current mode of a adapter.
Valid modes: "off", "connectable", "discoverable"
Possible errors: none
void SetMode(string mode)
Sets mode of the adapter. See GetMode for valid strings
for the mode parameter.
Possible errors: org.bluez.Error.NoSuchAdapter
org.bluez.Error.Failed
uint32 GetDiscoverableTimeout()
Returns the discoverable timeout in seconds. A value
of zero means that the timeout is disabled and it will
stay in discoverable mode forever.
The default value for the discoverable timeout should
be 180 seconds (3 minutes).
Possible errors: none
void SetDiscoverableTimeout(uint32 timeout)
Sets the discoverable timeout in seconds. A value of
zero disables the timeout and the adapter would be
always discoverable.
Changing this value doesn't set the adapter into
discoverable mode. The SetMode method must be used.
Possible errors: org.bluez.Error.NotReady
org.bluez.Error.InvalidArguments
boolean IsConnectable()
Returns true if the local adapter is connectable and
false if it is switched off.
It is also possible to use GetMode to retrieve this
information.
Possible errors: none
boolean IsDiscoverable()
Returns true if the local adapter is discoverable and
false if it is only connectable or switched off.
It is also possible to use GetMode to retrieve this
information.
Possible errors: none
boolean IsConnected(string address)
Return true if the local adapter is connected to
the remote device.
Possible errors: org.bluez.Error.InvalidArguments
array{string} ListConnections()
Returns a list with addresses of currently connected
remote devices.
Possible errors: none
string GetMajorClass()
Returns the current major class value for this
system. Currently, only "computer" is supported.
For the other values, unsupported major class
error is returned.
Possible errors: org.bluez.Error.NoSuchAdapter
org.bluez.Error.UnsupportedMajorClass
org.bluez.Error.Failed
array{string} ListAvailableMinorClasses()
Returns a list of available minor classes for the
currently used major class. At the moment this should
only return a list of minor classes if the major
class is set to "computer".
If the major class is not "computer" an error should
be returned.
Possible errors: org.bluez.Error.NotReady
org.bluez.Error.NoSuchAdapter
org.bluez.Error.Failed
org.bluez.Error.UnsupportedMajorClass
string GetMinorClass()
Returns the current minor class value for this
system where the default major class is "computer".
If the major class is not "computer" an error should
be returned.
Valid values: "uncategorized", "desktop", "server",
"laptop", "handheld", "palm", "wearable"
The default value is "uncategorized".
Possible errors: org.bluez.Error.NotReady
org.bluez.Error.NoSuchAdapter
org.bluez.Error.Failed
org.bluez.Error.UnsupportedMajorClass
void SetMinorClass(string minor)
Sets the local minor class and on success it sends
a MinorClassChanged signal.
If the major class is not "computer" an error should
be returned.
Possible errors: org.bluez.Error.NotReady
org.bluez.Error.InvalidArguments
org.bluez.Error.NoSuchAdapter
org.bluez.Error.Failed
org.bluez.Error.UnsupportedMajorClass
array{string} GetServiceClasses()
Returns the current set of service classes.
In the case no service classes are set (when no
service has been registered) an empty list should
be returned.
Valid values: "positioning", "networking", "rendering",
"capturing", "object transfer", "audio",
"telephony", "information"
Possible errors: org.bluez.Error.NotReady
org.bluez.Error.NoSuchAdapter
org.bluez.Error.Failed
string GetName()
Returns the local adapter name (friendly name) in UTF-8.
Possible errors: org.bluez.Error.NotReady
org.bluez.Error.Failed
void SetName(string name)
Sets the local adapter name. If EIR is supported by
the local hardware this modifies also the extended
response data value.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.Failed
Questions: What to do (in case of EIR) if one
low-level API call fails.
string GetRemoteVersion(string address)
Get the version info for a remote device. This request
returns always this information based on its cached
data. The base for this string is the LMP version
value and the features for EDR support.
Not available can be received if the remote device was
not contacted(connected) previously. Remote data is
automatically retrieved in the first connection.
Example: "Bluetooth 2.0 + EDR"
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotAvailable
string GetRemoteRevision(string address)
Get the revision of the Bluetooth chip. This is a
vendor specific value and in most cases it represents
the firmware version. This derives only from the LMP
subversion value.
Example: "HCI 19.2"
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotAvailable
string GetRemoteManufacturer(string address)
Get the manufacturer of the chip for a remote device.
Example: "Nokia Mobile Phones"
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotAvailable
string GetRemoteCompany(string address)
Get the company name from the OUI database of the
Bluetooth device address. This function will need a
valid and up-to-date oui.txt from the IEEE. This value
will be different from the manufacturer string in the
most cases.
Example: "Microsoft Corporation"
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotAvailable
string GetRemoteMajorClass(string address)
Get the major device class of the specified device.
Example: "computer"
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotAvailable
string GetRemoteMinorClass(string address)
Get the minor device class of the specified device.
Example: "laptop"
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotAvailable
array{string} GetRemoteServiceClasses(string address)
Get the service classes of the specified device.
Example: ["networking", "object transfer"]
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotAvailable
uint32 GetRemoteClass(string address)
Get the remote major, minor, and service classes
encoded as 32 bit integer.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotAvailable
array{byte} GetRemoteFeatures(string address)
Get the remote features encoded as bit mask.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotAvailable
string GetRemoteName(string address)
Get adapter name for a remote device. This request
returns always a cached name. The service daemon is
responsible for updating the cache.
If no remote name is available, then this function
will return RequestDeferred. In this case the service
daemon will try to resolve the name at the next
possible opportunity. On success a RemoteNameUpdated
signal will be send and if a failure happens it will
be indicated by a RemoteNameFailed signal.
If this is an empty string, the UI might want to
display the BD_ADDR instead.
Example: "00:11:22:33:44:55", "Nokia 770"
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotReady
org.bluez.Error.RequestDeferred
string GetRemoteAlias(string address)
Returns alias name for remote device. If this is
an empty string value, the UI should show the
remote name instead.
An alias should supersede the remote name.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotAvailable
void SetRemoteAlias(string address, string alias)
Sets alias name for remote device. If alias name is
empty, then no alias is set.
On success the SetRemoteAlias method will produce a
RemoteAliasChanged signal which applications can use
to update their current display of the remote device
name.
Possible errors: org.bluez.Error.Failed
org.bluez.Error.InvalidArguments
void ClearRemoteAlias(string address)
Resets alias name for remote device. If there is no
alias set for the device this method will silently
succeed, but no RemoteAliasCleared signal has to be
sent in this case.
On success the ClearRemoteAlias method will produce
a RemoteAliasCleared signal.
Possible errors: org.bluez.Error.Failed
org.bluez.Error.InvalidArguments
string LastSeen(string address)
Returns the date and time when the adapter has been
seen by a discover procedure.
Example: "2006-02-08 12:00:00 GMT"
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotAvailable
Question: Can we find a better name?
string LastUsed(string address)
Returns the date and time of the last time when the
adapter has been connected.
Example: "2006-02-08 12:00:00 GMT"
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotAvailable
Question: Can we find a better name?
void DisconnectRemoteDevice(string address)
This method disconnects a specific remote device by
terminating the low-level ACL connection. The use of
this method should be restricted to administrator
use.
A RemoteDeviceDisconnectRequested signal will be
sent and the actual disconnection will only happen 2
seconds later. This enables upper-level applications
to terminate their connections gracefully before the
ACL connection is terminated.
Possible errors: org.bluez.Error.NotReady
org.bluez.Error.Failed
org.bluez.Error.NoSuchAdapter
org.bluez.Error.InvalidArguments
org.bluez.Error.NotConnected
org.bluez.Error.InProgress
void CreateBonding(string address)
This method creates a bonding with a remote device.
If a link key for this adapter already exists, this
procedure should fail instead of trying to create a
new pairing.
If no connection to the remote device exists, a
low-level ACL connection must be created.
This function will block and the calling application
should take care of setting are higher timeout. This
might be needed in case of a page timeout from the
low-level HCI commands.
In case of success it will send a BondingCreated
signal.
Possible errors: org.bluez.Error.NotReady
org.bluez.Error.Failed
org.bluez.Error.InvalidArguments
org.bluez.Error.AlreadyExists
org.bluez.Error.InProgress
org.bluez.Error.NoSuchAdapter
org.bluez.Error.ConnectionAttemptFailed
org.bluez.Error.AuthenticationFailed
org.bluez.Error.AuthenticationTimeout
org.bluez.Error.AuthenticationRejected
org.bluez.Error.AuthenticationCanceled
void CancelBondingProcess(string address)
This method will cancel the CreateBonding process.
The CreateBonding method will return
AuthenticationCanceled to signal that an attempt to
create a bonding has been canceled.
Possible errors: org.bluez.Error.NotReady
org.bluez.Error.Failed
org.bluez.Error.InvalidArguments
org.bluez.Error.NotInProgress
org.bluez.Error.NotAuthorized
void RemoveBonding(string address)
This method removes the bonding with a remote device.
For security reasons this includes removing the actual
link key and also disconnecting any open connections
for the remote device.
If the link key was stored on the Bluetooth chip, it
must be removed from there, too.
After deleting the link key this method will send a
BondingRemoved signal.
Possible errors: org.bluez.Error.NotReady
org.bluez.Error.Failed
org.bluez.Error.InvalidArguments
org.bluez.Error.NoSuchAdapter
org.bluez.Error.DoesNotExist
boolean HasBonding(string address)
Returns true if the remote device is bonded and false
if no link key is available.
Possible errors: org.bluez.Error.InvalidArguments
array{string} ListBondings()
List device addresses of currently bonded adapter.
Possible errors: none
uint8 GetPinCodeLength(string address)
Returns the PIN code length that was used in the
pairing process.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.DoesNotExist
uint8 GetEncryptionKeySize(string address)
Returns the currently used encryption key size.
This method will fail if no connection to the address
has been established.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.Failed
void DiscoverDevices()
This method starts the device discovery procedure. This
includes an inquiry procedure and remote device name
resolving.
On start up this process will generate a DiscoveryStart
signal and then return RemoteDeviceFound and also
RemoteNameUpdated signals. If the procedure has been
finished an DiscoveryCompleted signal will be sent.
Possible errors: org.bluez.Error.NotReady
org.bluez.Error.Failed
org.bluez.Error.InProgress
org.bluez.Error.NoSuchAdapter
void DiscoverDevicesWithoutNameResolving()
This method starts the device discovery procedure. This
includes an inquiry and an optional remote device name
resolving. The remote names can be retrieved with
GetRemoteName and in the case a name doesn't exist it
will be queued for later resolving and GetRemoteName
will return an error.
While this procedure is running every found device
will be returned with RemoteDeviceFound. While
DiscoverDevices() automatically resolves unknown
devices names and sends RemoteNameUpdated in this
case it will only happen if GetRemoteName has been
called and no previously stored name is available.
Possible errors: org.bluez.Error.NotReady
org.bluez.Error.Failed
org.bluez.Error.InProgress
org.bluez.Error.NoSuchAdapter
void CancelDiscovery()
This method will cancel any previous DiscoverDevices
or DiscoverDevicesWithoutNameResolving actions.
Possible errors: org.bluez.Error.NotReady
org.bluez.Error.Failed
org.bluez.Error.NotAuthorized
org.bluez.Error.NoSuchAdapter
void StartPeriodicDiscovery()
This method starts a periodic discovery.
Possible errors: org.bluez.error.NotReady
org.bluez.Error.Failed
org.bluez.Error.InProgress
org.bluez.Error.NoSuchAdapter
void StopPeriodicDiscovery()
This method stops a periodic discovery. If the
adapter is not in the periodic inquiry mode an
error(not authorized) is returned. Everyone can
request exit from this mode, it is not restricted
to start requestor.
Possible errors: org.bluez.Error.NotReady
org.bluez.Error.Failed
org.bluez.Error.NotAuthorized
org.bluez.Error.NoSuchAdapter
boolean IsPeriodicDiscovery()
Returns true if the periodic inquiry is active and
false if it is switched off.
Possible errors: none
void SetPeriodicDiscoveryNameResolving(boolean resolve_names)
Enable or disable automatic remote name resolving for
periodic discovery.
Possible errors: org.bluez.Error.InvalidArguments
boolean GetPeriodicDiscoveryNameResolving()
Check if automatic remote name resolving is enabled or not
for periodic discovery.
Possible error: org.bluez.Error.InvalidArguments
array{uint32} GetRemoteServiceHandles(string address, string match)
This method will request the SDP database of a remote
device and retrieve the service record handles. To
request service browse send an empty match string.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.InProgress
org.bluez.Error.Failed
array{byte} GetRemoteServiceRecord(string address, uint32 handle)
This method will request the SDP database of a remote
device for a service record and return the binary
stream of it.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.InProgress
org.bluez.Error.Failed
string GetRemoteServiceRecordAsXML(string address, uint32 handle)
This method will request the SDP database of a remote
device for a service record and return its data in XML
format.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.InProgress
org.bluez.Error.Failed
array{string} ListRemoteDevices()
List addresses of all known remote devices (seen, used or bonded).
Possible errors: none
array{string} ListRecentRemoteDevices(string date)
List addresses of all used or bonded remote devices since date.
date format is "YYYY-MM-DD HH:MM:SS GMT"
Possible errors: none
Signals void ModeChanged(string mode)
If the current mode is changed with SetMode this signal
will inform about the new mode.
This signal can also be triggered by low-level HCI
commands.
void DiscoverableTimeoutChanged(uint32 timeout)
After changing the discoverable timeout this signal
provide the new timeout value.
void MinorClassChanged(string minor)
After changing the minor class with SetMinorClass this
signal will provide the new class value.
void NameChanged(string name)
After changing the local adapter name with SetName this
signal will provide the new name.
This signal can also be triggered by low-level HCI
commands.
void DiscoveryStarted()
This signal indicates that a device discovery
procedure has been started.
void DiscoveryCompleted()
This signal indicates that a device discovery
procedure has been completed.
void RemoteDeviceFound(string address, uint32 class, int16 rssi)
This signal will be send every time an inquiry result
has been found by the service daemon. In general they
only appear during a device discovery.
void RemoteDeviceDisappeared(string address)
This signal will be send when an inquiry session for
a periodic discovery finishes and previously found
devices are no longer in range or visible.
void RemoteClassUpdated(string address, uint32 class)
This signal will be send every time the remote class
of device has been changed. This happens for example
after a remote connection attempt. This signal will
not be send if the class of device hasn't changed
compared to cached one.
void RemoteNameUpdated(string address, string name)
This signal will be send every time the service daemon
detect a new name for a remote device.
void RemoteNameFailed(string address)
This signal will be sent every time the service daemon
tries to resolve a remote and this fails.
void RemoteAliasChanged(string address, string alias)
After changing an alias with SetRemoteAlias this
signal will indicate the new alias.
void RemoteAliasCleared(string address)
After removing an alias with ClearRemoteAlias this
signal will indicate that the alias is no longer
valid.
void RemoteDeviceConnected(string address)
This signal will be send if a low level connection
between two devices has been created.
void RemoteDeviceDisconnectRequested(string address)
This signal will be sent when a low level
disconnection to a remote device has been requested.
The actual disconnection will happen 2 seconds later.
void RemoteDeviceDisconnected(string address)
This signal will be send if a low level connection
between two devices has been terminated.
void BondingCreated(string address)
Signals that a successful bonding has been created.
void BondingRemoved(string address)
Signals that a bonding was removed.
Message Sequence Chart
The following figure shows how the discovery procedure works. Remote name resolving is hidden in the figure. This process is executed automatically when the HCI event("Inquiry Complete Event") arrives.
Graphical Client Example
Related documents
Manager: Default local adapter and service control/activation
HOWTO/DiscoveringDevices: Brief description/examples of discovery methods
HOWTO/DiscoveringServices: Brief description/examples of search/retrieve remote service records
HOWTO/Bonding: Brief description/examples of Bonding(pairing) methods
HOWTO/AdapterModes: Brief description/examples of how setup the local adapter visibility
Attachments
- Example-gbluezconf.png (54.7 kB) -
Client example: GBlueZConf
, added by cktakahasi on 02/27/07 15:16:20. - MessageChart-Discovery.png (42.3 kB) -
Message Chart: Device Discovery
, added by cktakahasi on 02/27/07 17:59:38.
