* Re: [Bluez-devel] UPDATE: org.bluez.Adapter Methods/Signals
2008-04-08 18:56 ` Marcel Holtmann
@ 2008-04-08 23:07 ` David Stockwell
2008-04-08 23:36 ` Marcel Holtmann
0 siblings, 1 reply; 7+ messages in thread
From: David Stockwell @ 2008-04-08 23:07 UTC (permalink / raw)
To: Marcel Holtmann; +Cc: BlueZ development
[-- Attachment #1: Type: text/plain, Size: 2860 bytes --]
Marcel,
That "flame" was uncalled for. I have attached file bluez-utils-3.30/hcid/dbus-api.txt
The section describing the org.bluez.Adapter interface contains the following (emphasis added):
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 DiscoveryStarted
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
Note well: not "DeviceFound", but "RemoteDeviceFound".
The file I attached is the only dbus-api-txt found in the entire bluez-utils-3.30 tree. So, it appears the documentation is out of
date; after digging into the code at adapter.c, I found signals DeviceCreated, DeviceRemoved, and DeviceFound in the adapter_signals
table. I will implement "catches" for them, now, and expect that this problem will go away.
So, thanks in advance,
DS
----- Original Message -----
From: "Marcel Holtmann" <marcel@holtmann.org>
To: "David Stockwell" <dstockwell@frequency-one.com>
Cc: "BlueZ development" <bluez-devel@lists.sourceforge.net>
Sent: Tuesday, April 08, 2008 1:56 PM
Subject: Re: [Bluez-devel] UPDATE: org.bluez.Adapter Methods/Signals
Hi David,
> To be clear, I have registered the RemoteDeviceFound and
> RemoteNameUpdated signals against both "/org/bluez/hci0" AND "/
> hci0" (both
> with "org.bluez.Adapter" interface). Signals for these signals
> always come back against "/org/bluez/hci0", and NOT against "/hci0"
> (path retrieved with dbus_g_proxy_get_path).
why don't you actually read the API documentation. Nobody said that
you can expect RemoteDeviceFound and RemoteNameUpdated on /hci0 and
you really can't. They are not sent. You get a DeviceFound signal.
Regards
Marcel
[-- Attachment #2: dbus-api.txt --]
[-- Type: text/plain, Size: 41474 bytes --]
D-Bus API description for BlueZ
*******************************
Copyright (C) 2004-2007 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
Shared Errors (Can be thrown by hcid or any bluetooth service)
DeviceUnreachable
The remote device is either powered down or out of range.
AlreadyConnected
A connection request has been received on an already
connected device.
ConnectionAttemptFailed
An unexpected error (other than DeviceUnreachable) error
has occured while attempting a connection to a device.
NotConnected
The remote device is not connected, while the method call
would expect it to be, or is not in the expected state to
perform the action.
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".
InvalidArguments
The DBUS request does not contain the right number of
arguments with the right type, or the arguments are there
but their value is wrong, or does not makes sense in the
current context.
OutOfMemory
Error returned when a memory allocation via malloc()
fails. This error is similar to ENOMEM.
NotAvailable
Error returned when a specified record is not
available.
NotSupported
The remote device does not support the expected
feature.
AlreadyExists
One of the requested elements already exists
DoesNotExist
One of the requested elements does not exist
Canceled
The operation was canceled.
Failed
This is a the most generic error.
It is thrown when something unexpected happens.
Hcid specific Errors (Can be thrown by hcid only)
NotReady
Error returned when the adapter is DOWN.
UnknwownMethod
This is an experimental 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.
Rejected
NoSuchAdapter
Error returned when the requested adapter doesn't
exists. This error is similar to ENODEV.
NoSuchService
RequestDeferred
NotInProgress
UnsupportedMajorClass
AuthenticationCanceled
AuthenticationFailed
AuthenticationTimeout
AuthenticationRejected
RepeatedAttempts
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.
Possible errors: org.bluez.Error.InvalidArguments
string DefaultAdapter()
Returns object path for the default adapter.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NoSuchAdapter
string FindAdapter(string pattern)
Returns object path for the specified adapter. Valid
patterns are "hci0" or "00:11:22:33:44:55".
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NoSuchAdapter
array{string} ListAdapters()
Returns list of adapter object paths under /org/bluez
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.Failed
org.bluez.Error.OutOfMemory
string FindService(string pattern)
Returns object path for the specified service. Valid
patterns are the unqiue identifier or a bus name.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NoSuchService
array{string} ListServices()
Returns list of object paths of current services.
Possible errors: org.bluez.Error.InvalidArguments
string ActivateService(string pattern)
Returns the unqiue bus id of the specified service.
Valid patterns are the same as for FindService(). If
the service is not running it will be started.
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,
or an empty string if there is no available adapters.
void ServiceAdded(string path)
Parameter is object path of registered service agent.
void ServiceRemoved(string path)
Parameter is object path of unregistered service agent.
Database hierarchy
==================
Service org.bluez
Interface org.bluez.Database
Object path /org/bluez or /org/bluez/{hci0,hci1,...}
Methods void RegisterService(string identifier, string name, string description)
This method registers a new service specified by
its unique identifier. This is only needed for
services that are not started through the
Bluetooth daemon.
void UnregisterService(string identifier)
This method unregisters a service specified by
its unique identifier.
uint32 AddServiceRecord(array{byte})
Adds a new service record and returns the assigned
record handle.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.Failed
uint32 AddServiceRecordFromXML(string record)
Adds a new service record and returns the assigned
record handle.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.Failed
void UpdateServiceRecord(uint32 handle, array{byte})
Updates a given service record.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotAvailable
org.bluez.Error.Failed
void UpdateServiceRecordFromXML(uint32 handle, string record)
Updates a given service record provided in the
XML format.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotAvailable
org.bluez.Error.Failed
void RemoveServiceRecord(uint32 handle)
Remove a service record identified by its handle.
It is only possible to remove service records that
where added by the current connection.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotAuthorized
org.bluez.Error.DoesNotExist
org.bluez.Error.Failed
void RequestAuthorization(string address, string uuid)
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 address parameter is the Bluetooth address of the
remote device and the uuid is the identifier of the
profile requesting the authorization. This parameter
can also be left blank.
void CancelAuthorizationRequest(string address, string uuid)
This method cancels an authorization process requested
by a previous call to RequestAuthorization(). The
address and uuid parameters must match.
Adapter hierarchy
=================
Service org.bluez
Interface org.bluez.Adapter
Object path /org/bluez/{hci0,hci1,...}
Methods dict GetInfo()
Returns the properties of the local adapter.
Possible errors: org.bluez.Error.NotReady
string GetAddress()
Returns the device address for a given path.
Example: "00:11:22:33:44:55"
Possible errors: org.bluez.Error.NotReady
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
array{string} ListAvailableModes()
Returns a list of available modes the adapter can
be switched into.
string GetMode()
Returns the current mode of a adapter.
Valid modes: "off", "connectable", "discoverable",
"limited".
Possible errors: none
void SetMode(string mode)
Sets mode of the adapter. See GetMode for valid strings
for the mode parameter. In addition to the valid strings
for GetMode, this method also supports a special
parameter value "on" which will change the mode to the
previous non-off mode (or do nothing if the current
mode isn't "off").
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/limited 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/limited.
Changing this value doesn't set the adapter into
discoverable/limited 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/limited
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.InvalidArguments
org.bluez.Error.UnsupportedMajorClass
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.InvalidArguments
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.InvalidArguments
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.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.
dict GetRemoteInfo(string address)
Returns the properties for a remote device.
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 the remote device's name. This request returns always
a cached name. The service daemon is responsible for
updating the cache.
NotAvailable error is returned if the name is not in
the cache. But if there is a discovery running, then
this function will return RequestDeferred. In this
case the service daemon will queue the request and
it 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.NotAvailable
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 SetTrusted(string address)
Marks the remote device as trusted. Authorization
request will automatically succeed.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.AlreadyExists
boolean IsTrusted(string address)
Returns true if the user is trusted or false otherwise.
The address parameter must match one of the remote
devices of the service.
Possible errors: org.bluez.Error.InvalidArguments
void RemoveTrust(string address)
Marks the remote device as not trusted.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.DoesNotExist
array{string} ListTrusts()
Returns a list of remote devices that are trusted.
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 DiscoveryStarted
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.ConnectionAttemptFailed
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} GetRemoteServiceIdentifiers(string address)
This method will request the SDP database of a remote
device for all supported services. The identifiers are
returned in UUID 128 string format.
Possible errors: org.bluez.Error.InProgress
org.bluez.Error.Failed
void FinishRemoteServiceTransaction(string address)
This method will finish all SDP transaction for that
given address. In general this call is not needed,
but in cases of resources restricted devices it
is useful to call this to finish the SDP transaction
before proceeded with profile specific connections.
array{string} ListRemoteDevices()
List addresses of all known remote devices (bonded,
trusted and used).
Possible errors: none
array{string} ListRecentRemoteDevices(string date)
List addresses of all bonded, trusted, seen or used remote
devices since date. Bonded and trusted devices are always
included(the date informed is not applied).
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 PeriodicDiscoveryStarted()
This signal indicates that a periodic discovery
procedure has been started.
void PeriodicDiscoveryStopped()
This signal indicates that a periodic 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 RemoteIdentifiersUpdated(string address, array{string identifiers})
This signal is sent to indicate the provided services of a given
remote device. It will be sent after GetRemoteServiceIdentifiers
calls. This signal has at least one identifier and it does not
contain repeated entries.
void RemoteNameFailed(string address)
This signal will be sent every time the service daemon
tries to resolve a remote and this fails.
void RemoteNameRequested(string address)
This signal will be sent every time the service daemon
tries to resolve a remote name during discovery.
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.
void TrustAdded(string address)
Sent when SetTrusted() is called.
void TrustRemoved(string address)
Sent when RemoveTrust() is called.
Service hierarchy
=================
Service org.bluez
Interface org.bluez.Service
Object path path from org.bluez.Manager.ListServices()
Methods dict GetInfo()
Returns the service properties.
string GetIdentifier()
This method returns the service identifier.
string GetName()
This method returns the service name.
string GetDescription()
This method returns the service description.
string GetBusName() [experimental]
Returns the unique bus name of the service if it has
been started.
Possible errors: org.bluez.Error.NotAvailable
void Start()
This method tells the system to start the
service.
void Stop()
This method tells the system to stop the
service.
boolean IsRunning()
Returns true if the service has been started and
is currently active. Otherwise, it returns false.
boolean IsExternal()
Returns true if the service was registered using the
Database.RegisterService method instead of a .service
file. The Start and Stop methods are not applicable to
external services and will return an error.
array{string} ListTrusts() [experimental]
Returns a list of remote devices that are trusted
for the service.
void SetTrusted(string address) [experimental]
Marks the user as trusted.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.AlreadyExists
boolean IsTrusted(string address) [experimental]
Returns true if the user is trusted or false otherwise.
The address parameter must match one of the
current users of the service.
Possible errors: org.bluez.Error.InvalidArguments
void RemoveTrust(string address) [experimental]
Marks the user as not trusted.
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.DoesNotExist
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.
void TrustAdded(string address)
Sent when SetTrusted() is called.
void TrustRemoved(string address)
Sent when RemoveTrust() is called.
Security hierarchy
==================
Service org.bluez
Interface org.bluez.Security
Object path /org/bluez or /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.
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 uuid)
This method gets called when the service daemon wants
to get an authorization for accessing a service. This
method should return if the remote user is granted
access or 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 uuid of the
profile.
Possible errors: org.bluez.Error.Rejected
org.bluez.Error.Canceled
void Cancel(string adapter_path, string address,
string service_path, string uuid)
This method cancels a previous authorization request.
The adapter_path, address, service_path and uuid
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.
^ permalink raw reply [flat|nested] 7+ messages in thread