[RFC BlueZ] Introduce GattProfile1 D-Bus API

[RFC BlueZ] Introduce GattProfile1 D-Bus API

[Arman Uguray]

This is an RFC patch that introduces the GattProfile1 & GattProfileManager1 APIs
that we discussed earlier on the mailing list. This is by no means the final
form of the intended API, so I just went with the main features that I had in
mind to initiate the discussion.

Thanks!
Arman

Arman Uguray (1):
  doc/gatt-api.txt: Add GattProfile1 API

 doc/gatt-api.txt | 158 ++++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 132 insertions(+), 26 deletions(-)

-- 
2.2.0.rc0.207.ga3a616c

[RFC BlueZ] doc/gatt-api.txt: Add GattProfile1 API

[Arman Uguray]

This patch adds the definition for the GattProfile1 and
GattProfileManager1 D-Bus interfaces. This API allows applications to
publish local GATT services for the server-role and manage client-role
configurations and behavior, such as auto-connects, GATT connection
life-time, subscribing to notifications/indications, etc.

Change-Id: I26c20b6db9ad01c8dcf7ad3d2d03913117505963
---
 doc/gatt-api.txt | 158 ++++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 132 insertions(+), 26 deletions(-)

diff --git a/doc/gatt-api.txt b/doc/gatt-api.txt
index bfeaf6d..8a64467 100644
--- a/doc/gatt-api.txt
+++ b/doc/gatt-api.txt
@@ -205,41 +205,147 @@ Properties	string UUID [read-only]
 			which a PropertiesChanged signal will be emitted.
 
 
-Service Manager hierarchy
-=============================
+GATT Profile Manager hierarchy
+==============================
 
-Service Manager allows external applications to register GATT based
-services. Services must follow the API for Service and Characteristic
-described above.
-
-Local GATT services, characteristics and characteristic descriptors are
-discovered automatically using the D-Bus Object Manager interface.
+GATT Profile Manager allows external applications to implement a GATT-based
+profile. An application may choose to implement one or more GATT services and
+publish them in the local database in the server role or it may be interested in
+remote GATT services in the client role.
 
 Service		org.bluez
-Interface	org.bluez.GattManager1 [Experimental]
+Interface	org.bluez.GattProfileManager1 [Experimental]
 Object path	/org/bluez
 
-Methods		RegisterService(object service, dict options)
+Methods		void RegisterProfile(object profile, 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 profile implementation.
 
-			"service" object path together with the D-Bus system
-			bus connection ID define the identification of the
-			application registering a GATT based service.
+			If an application disconnects from the bus all of its
+			registered profiles will be removed.
 
-			Possible errors: org.bluez.Error.InvalidArguments
-					 org.bluez.Error.AlreadyExists
+			Available options:
+
+				string Role
+
+					Specifies which specific profile role
+					is implemented by the application.
+					The value of this option determines
+					which other options are mandatory.
+
+					Possible values: "client", "server"
+
+				object ObjectManager
+
+					Specifies the object path to the node
+					that implements the
+					org.freedesktop.DBus.ObjectManager
+					interface for this application. This
+					must be the object manager that manages
+					the GattService1 objects. This is used
+					by BlueZ to monitor when services get
+					added and removed.
+
+					Required for the "server" role. Not
+					allowed in "client" role.
+
+				array{object} Services
+
+					List of exported object paths that
+					implement the GattService1 interface
+					hierarchy. These services are
+					implemented by the application and will
+					be published in the local attribute
+					database.
+
+					Required for the "server" role. Not
+					allowed in "client" role.
+
+				array{string} UUIDs
+
+					List of remote service UUIDs that the
+					application wants to access. The
+					application will be notified for each
+					GATT service discovered on a remote
+					device that matches one of these UUIDs.
+
+					Required for the "client" role. Not
+					allowed in "server" role.
+
+				string AdvertisedUUID
+
+					The service UUID that should be
+					advertised when the local host is in
+					LE advertising mode while in the LE
+					peripheral role. This will be ignored,
+					if a sufficient number of UUIDs are
+					already set for advertising.
 
-		UnregisterService(object service)
+					Optional for the "server" role. Not
+					allowed in "client" role.
 
-			This unregisters the service that has been
-			previously registered. The object path parameter
-			must match the same value that has been used
-			on registration.
+				boolean AutoConnect
+
+					If a device is found that contains one
+					or more of the desired remote UUIDs, it
+					will be automatically connected to.
+
+					Optional for the "client" role. Not
+					allowed in "server" role.
+
+				array{string} NotifyUUIDs
+
+					List of GATT characteristic UUIDs that
+					the application is interested in
+					receiving notifications/indications
+					from. If any of these characteristics
+					are discovered in a remote device and
+					they support notifications/indications,
+					they will be immediately enabled.
+
+					Optional for the "client" role. Not
+					allowed in the "server" role.
 
 			Possible errors: org.bluez.Error.InvalidArguments
-					 org.bluez.Error.DoesNotExist
+			                 org.bluez.Error.AlreadyExists
+
+		void UnregisterProfile(object profile)
+
+			Unregister a profile that has been previously
+			registered. The object path parameter must match the
+			same value that has been used on registration. If the
+			profile is in the server role, all of its published GATT
+			services will be removed from the database.
+
+			Possible errors: org.bluez.Error.DoesNotExist
+
+
+GATT Profile hierarchy
+======================
+
+Represents a GATT-based profile implemented by an external application in either
+the server or client role. A profile can publish one or more local GATT services
+or may be interact with GATT services found on a remote device.
+
+Service		unique name
+Interface	org.bluez.GattProfile1 [Experimental]
+Object path	freely definable
+
+Methods		void NewClientConfiguration(object characteristic,
+							string device_address,
+							array{byte} value)
+
+			This method gets called when a remote device with BDADDR
+			|device_address| in the GATT client role writes to the
+			Client Characteristic Configuration descriptor of
+			the characteristic with object path |characteristic|,
+			which was exported by this profile.
+
+			The profile can use this to maintain a mapping of
+			clients that have configured the characteristic and
+			update its state based on the configuration value
+			|value|.
+
+			Possible errors: org.bluez.NotAuthorized
+					 org.bluez.NotPaired
+					 org.bluez.NotSupported
-- 
2.2.0.rc0.207.ga3a616c