Introduces another change id to hierarchy mutations

mojo/services/public/interfaces/view_manager/view_manager.mojom

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 module mojo.services.view_manager {
 
 struct INode {
   uint32 parent_id;
   uint32 node_id;
   uint32 view_id;
 };
 
-// Functions that mutate the hierarchy take a |change_id|. |change_id| is an
-// arbitrary value assigned by the client originating the change. It may be
-// used by the client originating the change to later identify the change in
-// an OnNodeHierarchyChanged callback. |change_id| is only passed to the client
-// that originated the change; all other clients get a value of 0.
+// Functions that mutate the hierarchy take two change ids:
+// |server_change_id|: this is an ever increasing integer used to identify the
+// change. Every hierarchy change increases this value. The server only accepts
+// changes where the supplied |server_change_id| matches the expected next
+// value. This ensures changes are made in a well defined order. The client is
+// told the |server_change_id| when the connection is initially established and
+// subsequentely in any changes.
 //
-// Nodes are identified by a uint32. The upper 16 bits are the connection id,
-// and the lower 16 the id assigned by the client. CreateNode() only takes a
-// uint16 as the connection id of the originating connection is used.
+// |client_change_id|: this id is for use by the client to further identify the
+// change. This value is supplied in the mutation notifications to clients.
+// Connections that did not originate the change get a value of 0.
+//
+// Nodes and Views are identified by a uint32. The upper 16 bits are the
+// connection id, and the lower 16 the id assigned by the client. Functions
+// that take a 16 bit value (such as CreateNode()) use the id of the current
+// connection.
 //
 // The root node is identified with a connection id of 0, and value of 1.
 [Client=IViewManagerClient]
 interface IViewManager {
   // Creates a new node with the specified id. It is up to the client to ensure
   // the id is unique to the connection (the id need not be globally unique).
   CreateNode(uint16 node_id) => (bool success);
 
   // Deletes a node. This does not recurse. Children are removed from the node
-  // before it is destroyed.
+  // before it is destroyed. Deletion is always allowed and implicitly advances
+  // the server_change_id.
   DeleteNode(uint32 node_id, uint32 change_id) => (bool success);
 
   // Reparents a node. See description above class for details of |change_id|.
-  AddNode(uint32 parent, uint32 child, uint32 change_id) => (bool success);
+  // This fails for any of the following reasons:
+  // . |server_change_id| is not the expected id.
+  // . |parent| or |child| does not identify a valid node.
+  // . |child| is an ancestor of |parent|.
+  // . |child| is already a child of |parent|.
+  AddNode(uint32 parent,
+          uint32 child,
+          uint32 server_change_id,
+          uint32 client_change_id) => (bool success);
 
-  // Removes a view from its current parent.  See description above class for
-  // details of |change_id|.
-  RemoveNodeFromParent(uint32 node_id, uint32 change_id) => (bool success);
+  // Removes a view from its current parent. See description above class for
+  // details of |change_id|. This fails if the node is not valid,
+  // |server_change_id| doesn't match, or the node already has no parent.
+  RemoveNodeFromParent(uint32 node_id,
+                       uint32 server_change_id,
+                       uint32 client_change_id) => (bool success);
 
   // Returns the nodes comprising the tree starting at |node_id|. |node_id| is 
   // the first result in the return value, unless |node_id| is invalid, in which
   // case an empty vector is returned. The nodes are visited using a depth first
   // search (pre-order).
   GetNodeTree(uint32 node_id) => (INode[] nodes);
 
   // Creates a new view with the specified id. It is up to the client to ensure
   // the id is unique to the connection (the id need not be globally unique).
   CreateView(uint16 view_id) => (bool success);
 
   // Deletes the view with the specified id.
   DeleteView(uint32 view_id, uint32 change_id) => (bool success);
 
   // Sets the view a node is showing.
   SetView(uint32 node_id, uint32 view_id, uint32 change_id) => (bool success);
 
   // Shows the specified image (png encoded) in the specified view.
   SetViewContents(uint32 view_id,
                   handle<shared_buffer> buffer,
                   uint32 buffer_size);
 };
 
 interface IViewManagerClient {
   // Invoked once the connection has been established. |connection_id| is the id
-  // used to uniquely identify the connection.
-  OnConnectionEstablished(uint16 connection_id);
+  // that uniquely identifies this connection. |next_server_change_id| is the
+  // id of the next change the server is expecting.
+  OnConnectionEstablished(uint16 connection_id,
+                          uint32 next_server_change_id);
 
   // Invoked when a change is done to the hierarchy. A value of 0 is used to
   // identify a null node. For example, if the old_parent is NULL, 0 is
-  // supplied. See description above ViewManager for details on |change_id|.
+  // supplied. See description above ViewManager for details on the change ids.
   OnNodeHierarchyChanged(uint32 node,
                          uint32 new_parent,
                          uint32 old_parent,
-                         uint32 change_id);
+                         uint32 server_change_id,
+                         uint32 client_change_id);
+
+  // Invoked when a node is deleted.
+  OnNodeDeleted(uint32 node,
+                uint32 server_change_id,
+                uint32 client_change_id);
+                
 
   // Invoked when the view associated with a node is replaced by another view.
   // 0 is used to identify a null view.
   OnNodeViewReplaced(uint32 node,
                      uint32 new_view_id,
                      uint32 old_view_id,
-                     uint32 change_id);
-
-  // Invoked when a node is deleted.
-  OnNodeDeleted(uint32 node, uint32 change_id);
+                     uint32 client_change_id);
 };
 
 }