Diff between 88abc9a17ed4f3e4e5efd84b220e608c95688ce5 and 04aca1550857e5ae2fa8d4fbd4dafed4651b1b0f

Changed Files

File Additions Deletions Status
doc/mesh-api.txt +48 -18 modified

Full Patch

diff --git a/doc/mesh-api.txt b/doc/mesh-api.txt
index 112990a..2a80046 100644
--- a/doc/mesh-api.txt
+++ b/doc/mesh-api.txt
@@ -24,10 +24,10 @@ Methods:
 		DBus.ObjectManager interface must be available on the
 		app_defined_root path.
 
-		The uuid parameter is a 16-byte array that contains Device UUID. This
-		UUID must be unique (at least from the daemon perspective), therefore
-		attempting to call this function using already registered UUID results
-		in an error.
+		The uuid parameter is a 16-byte array that contains Device UUID.
+		This UUID must be unique (at least from the daemon perspective),
+		therefore attempting to call this function using already
+		registered UUID results in an error.
 
 		PossibleErrors:
 			org.bluez.mesh.Error.InvalidArguments
@@ -131,10 +131,10 @@ Methods:
 		interface. The standard DBus.ObjectManager interface must be
 		available on the app_root path.
 
-		The uuid parameter is a 16-byte array that contains Device UUID. This
-		UUID must be unique (at least from the daemon perspective), therefore
-		attempting to call this function using already registered UUID results
-		in an error.
+		The uuid parameter is a 16-byte array that contains Device UUID.
+		This UUID must be unique (at least from the daemon perspective),
+		therefore attempting to call this function using already
+		registered UUID results in an error.
 
 		The returned token must be preserved by the application in
 		order to authenticate itself to the mesh daemon and attach to
@@ -168,8 +168,8 @@ Methods:
 		permanently remove the identity of the mesh node by calling
 		Leave() method.
 
-		It is an error to attempt importing a node with already registered
-		Device UUID.
+		It is an error to attempt importing a node with already
+		registered Device UUID.
 
 		PossibleErrors:
 			org.bluez.mesh.Error.InvalidArguments,
@@ -182,8 +182,8 @@ Mesh Node Hierarchy
 Service		org.bluez.mesh
 Interface	org.bluez.mesh.Node1
 Object path	/org/bluez/mesh/node<uuid>
-		where <uuid> is the Device UUID passed to Join(), CreateNetwork() or
-		ImportLocalNode()
+		where <uuid> is the Device UUID passed to Join(),
+		CreateNetwork() or ImportLocalNode()
 
 Methods:
 	void Send(object element_path, uint16 destination, uint16 key_index,
@@ -348,8 +348,8 @@ Mesh Provisioning Hierarchy
 Service		org.bluez.mesh
 Interface	org.bluez.mesh.Management1
 Object path	/org/bluez/mesh/node<uuid>
-		where <uuid> is the Device UUID passed to Join(), CreateNetwork() or
-		ImportLocalNode()
+		where <uuid> is the Device UUID passed to Join(),
+		CreateNetwork() or ImportLocalNode()
 
 Methods:
 	void UnprovisionedScan(uint16 seconds)
@@ -400,6 +400,7 @@ Methods:
 		This call affects the local bluetooth-meshd key database only.
 
 		PossibleErrors:
+			org.bluez.mesh.Error.Failed
 			org.bluez.mesh.Error.InvalidArguments
 			org.bluez.mesh.Error.AlreadyExists
 
@@ -417,6 +418,7 @@ Methods:
 		This call affects the local bluetooth-meshd key database only.
 
 		PossibleErrors:
+			org.bluez.mesh.Error.Failed
 			org.bluez.mesh.Error.InvalidArguments
 			org.bluez.mesh.Error.AlreadyExists
 
@@ -432,8 +434,10 @@ Methods:
 		This call affects the local bluetooth-meshd key database only.
 
 		PossibleErrors:
+			org.bluez.mesh.Error.Failed
 			org.bluez.mesh.Error.InvalidArguments
 			org.bluez.mesh.Error.DoesNotExist
+			org.bluez.mesh.Error.Busy
 
 	void DeleteSubnet(uint16 net_index)
 
@@ -447,11 +451,12 @@ Methods:
 
 		PossibleErrors:
 			org.bluez.mesh.Error.InvalidArguments
-			org.bluez.mesh.Error.DoesNotExist
 
 	void SetKeyPhase(uint16 net_index, uint8 phase)
 		This method is used to set the master key update phase of the
-		given subnet.
+		given subnet. When finalizing the procedure, it is important
+		to CompleteAppKeyUpdate() on all app keys that have been
+		updated during the procedure prior to setting phase 3.
 
 		The net_index parameter is a 12-bit value (0x000-0xFFF)
 		specifying which subnet phase to set.
@@ -472,6 +477,7 @@ Methods:
 		refresh phases per the Mesh Profile Specification.
 
 		PossibleErrors:
+			org.bluez.mesh.Error.Failed
 			org.bluez.mesh.Error.InvalidArguments
 			org.bluez.mesh.Error.DoesNotExist
 
@@ -489,8 +495,10 @@ Methods:
 		This call affects the local bluetooth-meshd key database only.
 
 		PossibleErrors:
+			org.bluez.mesh.Error.Failed
 			org.bluez.mesh.Error.InvalidArguments
 			org.bluez.mesh.Error.AlreadyExists
+			org.bluez.mesh.Error.DoesNotExist
 
 	void ImportAppKey(uint16 net_index, uint16 app_index,
 						array{byte}[16] app_key)
@@ -510,8 +518,10 @@ Methods:
 		This call affects the local bluetooth-meshd key database only.
 
 		PossibleErrors:
+			org.bluez.mesh.Error.Failed
 			org.bluez.mesh.Error.InvalidArguments
 			org.bluez.mesh.Error.AlreadyExists
+			org.bluez.mesh.Error.DoesNotExist
 
 	void UpdateAppKey(uint16 app_index)
 
@@ -525,6 +535,27 @@ Methods:
 		This call affects the local bluetooth-meshd key database only.
 
 		PossibleErrors:
+			org.bluez.mesh.Error.Failed
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.DoesNotExist
+			org.bluez.mesh.Error.Busy
+
+	void CompleteAppKeyUpdate(uint16 app_index)
+
+		This method is used by the application at the completion of
+		a Key Refresh Procedure.  This method should be called for each
+		app key being updated during the procedure, and must be
+		performed prior to changing the phase of the bound net key
+		to phase 3. (See SetKeyPhase() method).
+
+		The app_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which app key was updated. Note that the subnet that
+		the key is bound to must exist and be in Phase 2.
+
+		This call affects the local bluetooth-meshd key database only.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.Failed
 			org.bluez.mesh.Error.InvalidArguments
 			org.bluez.mesh.Error.DoesNotExist
 
@@ -540,7 +571,6 @@ Methods:
 
 		PossibleErrors:
 			org.bluez.mesh.Error.InvalidArguments
-			org.bluez.mesh.Error.DoesNotExist
 
 	void ImportRemoteNode(uint16 primary, uint8 count,
 					array{byte}[16] device_key)
@@ -560,6 +590,7 @@ Methods:
 		This call affects the local bluetooth-meshd key database only.
 
 		PossibleErrors:
+			org.bluez.mesh.Error.Failed
 			org.bluez.mesh.Error.InvalidArguments
 
 	void DeleteRemoteNode(uint16 primary, uint8 count)
@@ -577,7 +608,6 @@ Methods:
 
 		PossibleErrors:
 			org.bluez.mesh.Error.InvalidArguments
-			org.bluez.mesh.Error.DoesNotExist
 
 Properties:
 	dict Features [read-only]