mirror of
https://git.kernel.org/pub/scm/bluetooth/bluez.git
synced 2024-12-02 08:34:26 +08:00
1333 lines
38 KiB
Plaintext
1333 lines
38 KiB
Plaintext
D-Bus API description for BlueZ
|
|
*******************************
|
|
|
|
Copyright (C) 2004-2006 Marcel Holtmann <marcel@holtmann.org>
|
|
Copyright (C) 2005-2006 Johan Hedberg <johan.hedberg@nokia.com>
|
|
Copyright (C) 2005-2006 Claudio Takahasi <claudio.takahasi@indt.org.br>
|
|
Copyright (C) 2005-2006 Eduardo Rocha <eduardo.rocha@indt.org.br>
|
|
|
|
|
|
Constant definitions
|
|
====================
|
|
|
|
The class of device definition from the Bluetooth specification divides into
|
|
three different parts. It the major class, the minor class and the service
|
|
classes. The D-Bus interface will always use string constants to identify
|
|
any of these classes.
|
|
|
|
Service classes positioning, networking, rendering, capturing,
|
|
object transfer, audio, telephony, information
|
|
|
|
Major classes miscellaneous, computer, phone, access point,
|
|
audio/video, peripheral, imaging, wearable, toy,
|
|
uncategorized
|
|
|
|
Minor classes computer uncategorized, desktop, server, laptop, handheld,
|
|
palm, wearable
|
|
|
|
Minor classes phone uncategorized, cellular, cordless, smart phone,
|
|
modem, isdn
|
|
|
|
Minor classes access point fully, 1-17 percent, 17-33 percent,
|
|
33-50 percent, 50-67 percent, 67-83 percent,
|
|
83-99 percent, not available
|
|
|
|
Minor classes audio video uncategorized, headset, handsfree,microphone,
|
|
loudspeaker, headphones, portable audio, car audio,
|
|
set-top box, hifi audio, vcr, video camera, camcorder,
|
|
video monitor, video display and loudspeaker,
|
|
video conferencing, gaming/toy, unknown
|
|
|
|
Minor classes peripheral uncategorized, keyboard, pointing, combo
|
|
|
|
Minor classes imaging display, camera, scanner, printer
|
|
|
|
Minor classes wearable wrist watch, pager, jacket, helmet, glasses
|
|
|
|
Minor classes toy robot, vehicle, doll, controller, game
|
|
|
|
Error hierarchy
|
|
===============
|
|
|
|
Interface org.bluez.Error
|
|
|
|
Errors Failed
|
|
|
|
An unknown error occured. The error messages is
|
|
taken from the strerror(errno) function.
|
|
|
|
InvalidArguments
|
|
|
|
Error returned when the argument list is invalid or
|
|
out of specification for the method.
|
|
|
|
NotAuthorized
|
|
|
|
Error returned when the caller of a method is not
|
|
authorized. This might happen if a caller tries to
|
|
terminate a connection that it hasn't created.
|
|
|
|
OutOfMemory
|
|
|
|
Error returned when a memory allocation via malloc()
|
|
fails. This error is similar to ENOMEM.
|
|
|
|
NoSuchAdapter
|
|
|
|
Error returned when the requested adapter doesn't
|
|
exists. This error is similar to ENODEV.
|
|
|
|
NotReady
|
|
|
|
Error returned when the adapter is DOWN.
|
|
|
|
NotAvailable
|
|
|
|
Error returned when a specified record is not
|
|
available.
|
|
|
|
NotConnected
|
|
|
|
Error returned when the remote device isn't connected
|
|
at the moment.
|
|
|
|
ConnectionAttemptFailed
|
|
|
|
AlreadyExists
|
|
|
|
Error returned if a record for a specific procedure
|
|
already exists and it has been tried create a new
|
|
one. The error message however should indicate the
|
|
procedure that fails. For example "Bonding already
|
|
exists"
|
|
|
|
DoesNotExist
|
|
|
|
Error returned if a record for a specifc procedure
|
|
doesn't exist. The error message however should
|
|
indicate the procedure that fails. For example
|
|
"Bonding does not exist".
|
|
|
|
InProgress
|
|
|
|
Error returned if an operation is in progress. Since
|
|
this is a generic error that can be used in various
|
|
situations, the error message should be more clear
|
|
about what is in progress. For example "Bonding in
|
|
progress".
|
|
|
|
NotSupported
|
|
The feature is not supported by the remote device
|
|
|
|
AuthenticationFailed
|
|
|
|
AuthenticationTimeout
|
|
|
|
AuthenticationRejected
|
|
|
|
AuthenticationCanceled
|
|
|
|
UnsupportedMajorClass
|
|
|
|
|
|
Manager hierarchy
|
|
=================
|
|
|
|
Service org.bluez
|
|
Interface org.bluez.Manager
|
|
Object path /org/bluez
|
|
|
|
Methods uint32 InterfaceVersion()
|
|
|
|
Returns the current interface version. At the moment
|
|
only version 0 is supported.
|
|
|
|
string DefaultAdapter()
|
|
|
|
Returns object path for the default adapter.
|
|
|
|
string FindAdapter(string pattern)
|
|
|
|
Returns object path for the specified adapter. Valid
|
|
patterns are "hci0" or "00:11:22:33:44:55".
|
|
|
|
array{string} ListAdapters()
|
|
|
|
Returns list of adapter object paths under /org/bluez
|
|
|
|
array{string} ListServices()
|
|
|
|
Returns list of object paths of registered
|
|
service agents.
|
|
|
|
void RegisterService(string path, string name,
|
|
string description)
|
|
|
|
This registers a new service agent.
|
|
|
|
The path parameter defines the object path of the
|
|
service agent that will be called when someone
|
|
requests information through org.bluez.Service
|
|
interface. The name and description parameters can
|
|
provide the name of the service and a description of
|
|
what it does or they can be empty strings.
|
|
|
|
void UnregisterService(string path)
|
|
|
|
This unregisters a service agent that has been
|
|
previously registered. The path parameter must
|
|
match the same value that has been used on
|
|
registration.
|
|
|
|
uint32 AddServiceRecord(string path, array{byte})
|
|
|
|
Add a new service record to the service agent
|
|
and returns the assigned handle.
|
|
|
|
The path parameter is the object path of the
|
|
service agent. The second parameter is the binary
|
|
representation of a service record. If the service
|
|
agent is running the service record will be automatically
|
|
registered, otherwise the record will be available
|
|
when the service agent Start method is called.
|
|
|
|
|
|
void RemoveServiceRecord(string path, uint32 handle)
|
|
|
|
Remove a service record from the service agent
|
|
records list.
|
|
|
|
The path parameter is the object path of the service
|
|
agent. The second parameter is service record handle.
|
|
|
|
Signals void AdapterAdded(string path)
|
|
|
|
Parameter is object path of added adapter.
|
|
|
|
void AdapterRemoved(string path)
|
|
|
|
Parameter is object path of removed adapter.
|
|
|
|
void DefaultAdapterChanged(string path)
|
|
|
|
Parameter is object path of the new default adapter.
|
|
|
|
void ServiceRegistered(string path)
|
|
|
|
Parameter is object path of registered service agent.
|
|
|
|
void ServiceUnregistered(string path)
|
|
|
|
Parameter is object path of unregistered service agent.
|
|
|
|
|
|
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
|
|
|
|
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 only.
|
|
|
|
Possible errors: org.bluez.Error.NotReady
|
|
org.bluez.Error.Failed
|
|
org.bluez.Error.NoSuchAdapter
|
|
org.bluez.Error.InvalidArguments
|
|
org.bluez.Error.NotConnected
|
|
|
|
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
|
|
|
|
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 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.
|
|
|
|
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
|
|
|
|
|
|
Security hierarchy
|
|
==================
|
|
|
|
Service org.bluez
|
|
Interface org.bluez.Security
|
|
Object path /org/bluez
|
|
/org/bluez/{hci0,hci1,...}
|
|
|
|
Methods void RegisterDefaultPasskeyAgent(string path)
|
|
|
|
This registers the default passkey agent. It can
|
|
register a passkey for all adapters or for a
|
|
specific device depending on with object path has
|
|
been used.
|
|
|
|
The path parameter defines the object path of the
|
|
passkey agent that will be called when a passkey
|
|
needs to be entered.
|
|
|
|
If an application disconnects from the bus all
|
|
registered passkey agent will be removed.
|
|
|
|
Possible errors: org.bluez.Error.AlreadyExists
|
|
|
|
void UnregisterDefaultPasskeyAgent(string path)
|
|
|
|
This unregisters a default passkey agent that has
|
|
been previously registered. The object path and
|
|
the path parameter must match the same values that
|
|
has been used on registration.
|
|
|
|
Possible errors: org.bluez.Error.DoesNotExist
|
|
|
|
void RegisterPasskeyAgent(string path, string address)
|
|
|
|
This registers the application passkey agent that
|
|
will be used for any application specific passkey
|
|
tasks.
|
|
|
|
The path parameter defines the object path of the
|
|
passkey agent that will be called when a passkey
|
|
needs to be entered. The address defines the remote
|
|
device that it will answer passkey requests for.
|
|
|
|
If an application disconnects from the bus all
|
|
registered passkey agent will be removed. It will
|
|
also be unregistered after a timeout and if the
|
|
pairing succeeds or fails. The application has to
|
|
take care of that it reregisters the passkey agent.
|
|
|
|
Possible errors: org.bluez.Error.AlreadyExists
|
|
|
|
void UnregisterPasskeyAgent(string path, string address)
|
|
|
|
This unregisters a passkey agent that has been
|
|
previously registered. The object path and the path
|
|
and address parameter must match the same values
|
|
that has been used on registration.
|
|
|
|
The method is actually only needed if an application
|
|
wants to removed the passkey agent and don't wanna
|
|
wait for the automatic timeout.
|
|
|
|
Possible errors: org.bluez.Error.DoesNotExist
|
|
|
|
void RegisterDefaultAuthorizationAgent(string path)
|
|
|
|
This registers the default authorization agent. It can
|
|
register an authorization agent for all adapters or
|
|
for a specific one depending on which object path has
|
|
been used.
|
|
|
|
The path parameter defines the object path of the
|
|
authorization agent that will be called when an
|
|
authorization request needs to be answered.
|
|
|
|
void UnregisterDefaultAuthorizationAgent(string path)
|
|
|
|
This unregisters a default authorization agent that has
|
|
been previously registered. The path parameter must
|
|
match the same value that has been used on
|
|
registration.
|
|
|
|
void AuthorizeService(string service_path, string address,
|
|
string action)
|
|
|
|
This method gets called when a service wants to check
|
|
if a remote device is authorized to perform some
|
|
action. The authorization request is forwarded to an
|
|
authorization agent.
|
|
|
|
The service_path parameter must be the object
|
|
path of the service. The address and action parameters
|
|
correspond to the remote device address and the action
|
|
the remote device is trying to perform.
|
|
|
|
void CancelAuthorizationProcess(string service_path,
|
|
string address, string action)
|
|
|
|
This method cancels an authorization process requested
|
|
by a previous call to AuthorizeService(). The
|
|
service_path, address and action parameters must match
|
|
the same values that have been used on registration.
|
|
|
|
|
|
Service hierarchy (experimental)
|
|
================================
|
|
|
|
Service org.bluez
|
|
Interface org.bluez.Service
|
|
Object path path from org.bluez.Manager.ListServices()
|
|
|
|
Methods string GetConnectionName()
|
|
|
|
This method returns the name of the connection to
|
|
the service agent.
|
|
|
|
string GetName()
|
|
|
|
This method returns the service name.
|
|
|
|
string GetDescription()
|
|
|
|
This method returns the service description.
|
|
|
|
void Start()
|
|
|
|
This method tells the service agent to actually
|
|
start the service.
|
|
|
|
void Stop()
|
|
|
|
This method tells the service agent to stop the
|
|
service.
|
|
|
|
boolean IsRunning()
|
|
|
|
Returns true if the service has been started and
|
|
is currently active. Otherwise, it returns false.
|
|
|
|
array{string} ListUsers()
|
|
|
|
Returns list of current users (device addresses)
|
|
of the service.
|
|
|
|
void RemoveUser(string address)
|
|
|
|
Removes a user of the service. The address parameter
|
|
must match one of the current users of the service.
|
|
|
|
void SetTrusted(string address)
|
|
|
|
Marks the user as trusted.
|
|
|
|
boolean IsTrusted(string address)
|
|
|
|
Returns true if the user is trusted or false otherwise.
|
|
The address parameter must match one of the
|
|
current users of the service.
|
|
|
|
void RemoveTrust(string address)
|
|
|
|
Marks the user as not trusted.
|
|
|
|
Signals void Started()
|
|
|
|
The object path of this signal contains which service
|
|
was started.
|
|
|
|
void Stopped()
|
|
|
|
The object path of this signal contains which service
|
|
was stopped.
|
|
|
|
|
|
PasskeyAgent hierarchy
|
|
======================
|
|
|
|
Service unique name
|
|
Interface org.bluez.PasskeyAgent
|
|
Object path freely definable
|
|
|
|
Methods string Request(string path, string address, boolean numeric)
|
|
|
|
This method gets called when the service daemon
|
|
needs to get the passkey for an authentication. The
|
|
return value is actual passkey.
|
|
|
|
The first argument contains the path of the local
|
|
adapter and the second one the remote address. The
|
|
third argument signals if a numeric PIN code is
|
|
expected or not. The default is a 1 to 16 byte PIN
|
|
code in UTF-8 format.
|
|
|
|
Possible errors: org.bluez.Error.Rejected
|
|
org.bluez.Error.Canceled
|
|
|
|
void Confirm(string path, string address, string value)
|
|
|
|
This method gets called when the service daemon
|
|
needs to verify a passkey. The verification is
|
|
done by showing the value to the passkey agent
|
|
and returning means a successful confirmation.
|
|
In case the values don't match an error must
|
|
be returned.
|
|
|
|
Possible errors: org.bluez.Error.Rejected
|
|
org.bluez.Error.Canceled
|
|
|
|
void Display(string path, string address, string value)
|
|
|
|
This method gets called when the service daemon
|
|
needs to display the passkey value. No return
|
|
value is needed. A successful paring will be
|
|
indicated by the Complete method and a failure
|
|
will be signaled with Cancel.
|
|
|
|
void Keypress(string path, string address)
|
|
|
|
This method indicates keypresses from the remote
|
|
device. This can happen when pairing with a keyboard.
|
|
|
|
void Complete(string path, string address)
|
|
|
|
This method gets called to indicate that the
|
|
authentication has been completed.
|
|
|
|
void Cancel(string path, string address)
|
|
|
|
This method gets called to indicate that the
|
|
authentication request failed before a reply was
|
|
returned by the Request method.
|
|
|
|
void Release()
|
|
|
|
This method gets called when the service daemon
|
|
unregisters a passkey agent. An agent can use
|
|
it to do cleanup tasks. There is no need to
|
|
unregister the agent, because when this method
|
|
gets called it has already been unregistered.
|
|
|
|
|
|
AuthorizationAgent hierarchy (experimental)
|
|
===========================================
|
|
|
|
Service unique name
|
|
Interface org.bluez.AuthorizationAgent
|
|
Object path freely definable
|
|
|
|
Methods void Authorize(string adapter_path, string address,
|
|
string service_path, string action)
|
|
|
|
This method gets called when the service daemon wants
|
|
to get an authorization for an action a remote device
|
|
is trying to perform. This method should return if the
|
|
remote user is authorized to perform that action and
|
|
an error otherwise.
|
|
|
|
The adapter_path parameter is the object path of the
|
|
local adapter. The address, service_path and action
|
|
parameters correspond to the remote device address,
|
|
the object path of the service and the action the
|
|
remote device is trying to perform.
|
|
|
|
Possible errors: org.bluez.Error.Rejected
|
|
org.bluez.Error.Canceled
|
|
|
|
void Cancel(string adapter_path, string address,
|
|
string service_path, string action)
|
|
|
|
This method cancels a previous authorization request.
|
|
The adapter_path, address, service_path and action
|
|
parameters must match the same values that have been
|
|
used when the Authorize() method was called.
|
|
|
|
void Release()
|
|
|
|
This method gets called when the service daemon
|
|
unregisters an authorization agent. An agent can
|
|
use it to do cleanup tasks. There is no need to
|
|
unregister the agent, because when this method
|
|
gets called it has already been unregistered.
|
|
|
|
|
|
ServiceAgent hierarchy (experimental)
|
|
=====================================
|
|
|
|
Service unique name
|
|
Interface org.bluez.ServiceAgent
|
|
Object path freely definable
|
|
|
|
Methods void Start()
|
|
|
|
This method gets called when the service daemon
|
|
wants to start the service provided by the agent.
|
|
|
|
void Stop()
|
|
|
|
This method gets called when the service daemon
|
|
wants to stop the service provided by the agent.
|
|
|
|
void Release()
|
|
|
|
This method gets called when the service daemon
|
|
unregisters a service agent. An agent can use
|
|
it to do cleanup tasks. There is no need to
|
|
unregister the agent, because when this method
|
|
gets called it has already been unregistered.
|
|
|
|
|
|
RFCOMM hierarchy (experimental)
|
|
===============================
|
|
|
|
Service org.bluez
|
|
Interface org.bluez.RFCOMM
|
|
Object path /org/bluez/{hci0,hci1,...}
|
|
|
|
Methods string Connect(string address, string service)
|
|
|
|
This creates a connection to a remote RFCOMM based
|
|
service. The service string can either be a UUID-128,
|
|
a service abbreviation or a record handle.
|
|
|
|
The return value will be the path of the newly
|
|
created RFCOMM TTY device (for example /dev/rfcomm0).
|
|
|
|
If the application disconnects from the D-Bus this
|
|
connection will be terminated.
|
|
|
|
Valid service values: "vcp", "map", "pbap", "sap",
|
|
"ftp", "bpp", "bip", "synch",
|
|
"dun", "opp", "fax", "spp"
|
|
|
|
void CancelConnect(string address, string service)
|
|
|
|
This method cancels a previous Connect method call.
|
|
|
|
string ConnectByChannel(string address, byte channel)
|
|
|
|
This creates a connection to a remote RFCOMM based
|
|
service. In contrast to Connect a channel number is
|
|
needed.
|
|
|
|
The return value will be the path of the newly
|
|
creates RFCOMM TTY device (for example /dev/rfcomm0).
|
|
|
|
If the application disconnects from the D-Bus this
|
|
connection will be terminated.
|
|
|
|
void CancelConnectByChannel(string address, byte channel)
|
|
|
|
This method cancels a previous ConnectByChannel
|
|
method call.
|
|
|
|
void Disconnect(string device)
|
|
|
|
This will disconnect a previously connected RFCOMM
|
|
service. The device parameter must be the return value
|
|
from a previous Connect or ConnectByChannel method
|
|
call (for example /dev/rfcomm0).
|
|
|
|
string Bind(string address, string service)
|
|
|
|
string BindByChannel(string address, byte channel)
|
|
|
|
void Release(string device)
|
|
|
|
array{string} ListBindings()
|