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}/{service0, service1, ...}

Methods		array[(object, dict)] GetCharacteristics()

			Array of tuples with object path as identifier. An
			alternative is doing dict of dict since the object
			path is unique and the order of characteristics is
			irrelevant. However it might be good to actually
			present an order here.

			See Characteristics properties for dictionary details.

		RegisterCharacteristicsWatcher(object path)

			Register a watcher for changes in specific characteristics
			to monitor changes.

			A watcher will be registered for this service and will
			notifier about any changed characteristics in the service.
			This also notifies about any included characteristics.

			Method for the watch objects still need to be defined.

		UnregisterCharacteristicsWatcher(object path)

			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.

			string UUID
			string Name
			string Description
			struct Format (type, name, exponet etc.)

			array{byte} Value
			string Representation (of the binary Value)

			object Service (the original service in case of includes)

			At this point only GetProperties() method call should be
			supported for simplicity. Changing characteristics is up
			to future support.

			The object path of the characteristics might be split
			over multiple service objects, because of includes.


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.


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.
