diff options
Diffstat (limited to 'doc/attribute-api.txt')
| -rw-r--r-- | doc/attribute-api.txt | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/doc/attribute-api.txt b/doc/attribute-api.txt new file mode 100644 index 0000000..f2778f3 --- /dev/null +++ b/doc/attribute-api.txt @@ -0,0 +1,164 @@ +BlueZ D-Bus Attribute API description +************************************* + +Copyright (C) 2004-2010 Marcel Holtmann <marcel@holtmann.org> + +Service details +--------------- + +One service object path for every remote SDP record or service in the +attribute database. One service object path for every local SDP record +or service from attribute database. + +Local services are children of the adapter object path. Remote services +are children of the remote device object path. This doesn't solve the +problem where local atttributes can have different instances based on +the remote device. + +In general the idea is to also represent SDP records as services so that +new style application can just use the service interfaces to retrieve the +needed information. That way the usage of SDP and GATT would be mostly +fully transparent and a differentiation becomes unimportant in the future. + +A service consists of some generic service information and a set of +characteristics. All characteristic are presented as object path as well. + + +Local Service hierarchy +======================= + +Service org.bluez +Interface org.bluez.Service + org.bluez.Characteristic +Object path [prefix]/{hci0}/{service0, service1, ...} + +Methods + +Properties + + +Device Service hierarchy +======================== + +Service org.bluez +Interface org.bluez.Characteristic +Object path [prefix]/{hci0}/{device0}/{service0, service1, ...} + [prefix]/{hci0}/{device1}/{service0, service1, ...} + +Methods dict GetProperties() + + Returns all properties for the interface. See the + Properties section for the available properties. + + array{object} DiscoverCharacteristics() + + Discover all characteristics that belongs in this service. + When it returns all the characteristics paths will be + already registered. It will return the characteristics paths + as soon as they are discovered. After that it will try to + read all values. + + RegisterCharacteristicsWatcher(object agent) + + Register a watcher to monitor characteristic changes. + + A watcher will be registered for this service and will + notify about any changed characteristics in the service. + This also notifies about any included characteristics. + + UnregisterCharacteristicsWatcher(object agent) + + Unregister a watcher. + +Properties string Name (mandatory) [readonly] + + General name of service + + string Description (optional) [readonly] + + Description of service + + string UUID (mandatory) [readonly] + + UUID of service. Service class value for SDP and GATT + UUID for attribute based services. + + array{object} Characteristics [readonly] + + This list contains the characteristics owned by this + specific service and other characteristics from service + includes. That way no complicated service includes array + is needed. + + +Device Characteristic hierarchy +=============================== + +Service org.bluez +Interface org.bluez.Characteristic +Object path [prefix]/{hci0}/{device0}/{service0}/{characteristic0,...} + [prefix]/{hci0}/{device0}/{service1}/{characteristic0,...} + +Methods dict GetProperties() + + Returns all properties for the characteristic. See the + properties section for available properties. + + void SetProperty(string name, variant value) + + Changes the value of the specified property. Only + read-write properties can be changed. On success + this will emit a PropertyChanged signal. + + Possible Errors: org.bluez.Error.InvalidArguments + +Properties string UUID [readonly] + + UUID128 of this characteristic. + + string Name [readonly] + + Optional field containing a friendly name for the + Characteristic UUID. + + string Description [readonly] + + Textual optional characteristic descriptor describing + the Characteristic Value. + + struct Format [readonly] + + Optional Characteristic descriptor which defines the + format of the Characteristic Value. For numeric + values, the actual value can be value * 10^Exponent. + NameSpace and Description are defined on the Assigned + Number Specification. + + uint8 | Format: format of the value + uint8 | Exponent: Field to determine how the value is + | further formatted. + uint16 | Unit: unit of the characteristic + uint8 | NameSpace: Name space of description. + uint16 | Description: Description of the characteristic defined + | in a high layer profile. + + array{byte} Value [readwrite] + + Raw value of the Characteristic Value attribute. + + string Representation (of the binary Value) [readonly] + + Friendly representation of the Characteristic Value + based on the format attribute. + + +Characteristic Watcher hierarchy +=============================== + +Service unique name +Interface org.bluez.Watcher +Object path freely definable + +Methods void ValueChanged(object characteristic, array{byte}) + + New raw value of the Characteristic Value attribute. |