doc/mesh: Change API to deliver tokens via JoinComplete

If Application is not be able to reliably store the token, the daemon
will end up with a uncontrollable node in its database.

Let's fix the issue by always delivering tokens using JoinComplete call,
and expecting a reply - if the application return an error, daemon will
get rid of the node.

Change-Id: I82ed48f64b9bd8d6b77c99eb28d470fd58f97148
Signed-off-by: Abhay Agarwal <ay.agarwal@samsung.com>

diff --git a/doc/mesh-api.txt b/doc/mesh-api.txt
index 6ecb816..24cface 100644 (file)
--- a/doc/mesh-api.txt
+++ b/doc/mesh-api.txt
@@ -29,6 +29,10 @@ Methods:
                therefore attempting to call this function using already
                registered UUID results in an error.
 
+               When provisioning finishes, the daemon will call either
+               JoinComplete or JoinFailed method on object implementing
+               org.bluez.mesh.Application1 interface.
+
                PossibleErrors:
                        org.bluez.mesh.Error.InvalidArguments
                        org.bluez.mesh.Error.AlreadyExists,
@@ -123,7 +127,7 @@ Methods:
                PossibleErrors:
                        org.bluez.mesh.Error.InvalidArguments
 
-       uint64 token CreateNetwork(object app_root, array{byte}[16] uuid)
+       void CreateNetwork(object app_root, array{byte}[16] uuid)
 
                This is the first method that an application calls to become
                a Provisioner node, and a Configuration Client on a newly
@@ -144,22 +148,20 @@ Methods:
                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
-               the network as a mesh node by calling Attach() method or
-               permanently remove the identity of the mesh node by calling
-               Leave() method.
-
                The other information the bluetooth-meshd daemon will preserve
                about the initial node, is to give it the initial primary
                unicast address (0x0001), and create and assign a net_key as the
                primary network net_index (0x000).
 
+               Upon successful processing of Create() method, the daemon
+               will call JoinComplete method on object implementing
+               org.bluez.mesh.Application1.
+
                PossibleErrors:
                        org.bluez.mesh.Error.InvalidArguments
                        org.bluez.mesh.Error.AlreadyExists,
 
-       uint64 token Import(object app_root, array{byte}[16] uuid,
+       void Import(object app_root, array{byte}[16] uuid,
                                array{byte}[16] dev_key,
                                array{byte}[16] net_key, uint16 net_index,
                                dict flags, uint32 iv_index, uint16 unicast)
@@ -204,11 +206,9 @@ Methods:
                The unicast parameter is the primary unicast address of the
                imported node.
 
-               The returned token must be preserved by the application in
-               order to authenticate itself to the mesh daemon and attach to
-               the network as a mesh node by calling Attach() method or
-               permanently remove the identity of the mesh node by calling
-               Leave() method.
+               Upon successful processing of Import() method, the daemon will
+               call JoinComplete method on object implementing
+               org.bluez.mesh.Application1 interface.
 
                PossibleErrors:
                        org.bluez.mesh.Error.InvalidArguments,
@@ -758,6 +758,10 @@ Methods:
                permanently remove the identity of the mesh node by calling
                Leave() method.
 
+               If this method returns an error, the daemon will assume that the
+               application failed to preserve the token, and will remove the
+               freshly created node.
+
        void JoinFailed(string reason)
 
                This method is called when the node provisioning initiated by