korg/bluez
0
0
Fork 0
mirror of https://git.kernel.org/pub/scm/bluetooth/bluez.git synced 2024-12-20 09:23:29 +08:00
Code Issues Packages Projects Releases Wiki Activity

doc/gatt-api.txt: New ObjectManager requirements

Browse Source 
After some discussion it was decided to require an ObjectManager
interface implementation on a per-service basis to reduce the
overhead of heaving to process and cache potentially many non-GATT
related objects. This patch updates the documentation to reflect this.
This commit is contained in:
Arman Uguray 2015-02-27 00:16:26 -08:00 committed by Luiz Augusto von Dentz
parent d8fdaf7544
commit a46ef6105d
1 changed files with 61 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
doc/gatt-api.txt
View File

@ -8,7 +8,9 @@ application. Remote refers to GATT services exported by the peer.
BlueZ acts as a proxy, translating ATT operations to D-Bus method calls and
Properties (or the opposite). Support for D-Bus Object Manager is mandatory for
external services to allow seamless GATT declarations (Service, Characteristic
and Descriptors) discovery.
and Descriptors) discovery. Each GATT service tree is required to export a D-Bus
Object Manager at its root that is solely responsible for the objects that
belong to that service.
Releasing a registered GATT service is not defined yet. Any API extension
should avoid breaking the defined API, and if possible keep an unified GATT
@ -229,12 +231,63 @@ Methods void Release()
GATT Manager hierarchy
======================
GATT Manager allows external applications to register GATT based
services. Services must follow the API for Service and Characteristic
described above.
GATT Manager allows external applications to register GATT services and
profiles.
Local GATT services, characteristics and characteristic descriptors are
discovered automatically using the D-Bus Object Manager interface.
Registering a profile allows applications to subscribe to *remote* services.
These must implement the GattProfile1 interface defined above.
Registering a service allows applications to publish a *local* GATT service,
which then becomes available to remote devices. A GATT service is represented by
a D-Bus object hierarchy where the root node corresponds to a service and the
child nodes represent characteristics and descriptors that belong to that
service. Each node must implement one of GattService1, GattCharacteristic1,
or GattDescriptor1 interfaces described above, based on the attribute it
represents. Each node must also implement the standard D-Bus Properties
interface to expose their properties. These objects collectively represent a
GATT service definition.
To make service registration simple, BlueZ requires that all objects that belong
to a GATT service be grouped under a D-Bus Object Manager that solely manages
the objects of that service. Hence, the standard DBus.ObjectManager interface
must be available on the root service path. An example application hierarchy
containing two separate GATT services may look like this:
-> /com/example
|
-> /com/example/service0
| | - org.freedesktop.DBus.ObjectManager
| | - org.freedesktop.DBus.Properties
| | - org.bluez.GattService1
| |
| -> /com/example/service0/char0
| | - org.freedesktop.DBus.Properties
| | - org.bluez.GattCharacteristic1
| |
| -> /com/example/service0/char1
| | - org.freedesktop.DBus.Properties
| | - org.bluez.GattCharacteristic1
| |
| -> /com/example/service0/char1/desc0
| - org.freedesktop.DBus.Properties
| - org.bluez.GattDescriptor1
|
-> /com/example/service1
| - org.freedesktop.DBus.ObjectManager
| - org.freedesktop.DBus.Properties
| - org.bluez.GattService1
|
-> /com/example/service1/char0
- org.freedesktop.DBus.Properties
- org.bluez.GattCharacteristic1
When a service is registered, BlueZ will automatically obtain information about
all objects using the service's Object Manager. Once a service has been
registered, the objects of a service should not be removed. If BlueZ receives an
InterfacesRemoved signal from a service's Object Manager, it will immediately
unregister the service. Similarly, if the application disconnects from the bus,
all of its registered services will be automatically unregistered.
InterfacesAdded signals will be ignored.
Service org.bluez
Interface org.bluez.GattManager1 [Experimental]
@ -242,11 +295,8 @@ Object path [variable prefix]/{hci0,hci1,...}
Methods void RegisterService(object service, dict options)
Registers remote application service exported under
interface GattService1. Characteristic objects must
be hierarchical to their service and must use the
interface GattCharacteristic1. D-Bus Object Manager
is used to fetch the exported objects.
Registers a local GATT service hierarchy as described
above.
"service" object path together with the D-Bus system
bus connection ID define the identification of the