Hotplug: D-Bus: API version 2

Use uint32s instead of int32s where practical, and add an API version
request.  Also, try to return all devices added, not just the first,
and box device arguments.

1 files changed, 11 insertions, 8 deletions

diff --git a/config/dbus-api b/config/dbus-api
index 654c22bec..018e98657 100644
--- a/config/dbus-api
+++ b/config/dbus-api
@@ -1,4 +1,4 @@
-D-BUS Configuration API v0.1
+D-BUS Configuration API v2
 ----------------------------
 
 The X server will register the bus name org.x.config.displayN, and the 
@@ -7,6 +7,9 @@ object /org/x/config/N, where N is the display number.
 Currently only hotplugging of input devices is supported.
 
 org.x.config.input:
+    org.x.config.input.version:
+        Returns one unsigned int32, which is the API version.
+
     org.x.config.input.add:
         Takes an argument of key/value option pairs in arrays, e.g.:
          [ss][ss][ss][ss]
@@ -15,18 +18,18 @@ org.x.config.input:
         Option names beginning with _ are not allowed; they are reserved
         for internal use.
 
-        Returns one signed int32, which is the device id of the new device.
-        If the return value is a negative number, it represents the X
-        Status, as defined in X.h. BadMatch will be returned if the options
+        Returns a number of signed int32s.  Positive integers are the
+        device IDs of new devices; negative numbers are X error codes,
+        as defined in X.h.  BadMatch will be returned if the options
         given do not match any device.  BadValue is returned for a malformed
-        message.  (Example: 8 is new device id 8. -8 is BadMatch.)
+        message.  (Example: 8 is new device ID 8; -8 is BadMatch.)
 
         Notably, BadAlloc is never returned: the server internally signals
         to D-BUS that the attempt failed for lack of memory.
 
     org.x.config.input.remove:
-        Takes one int32 argument, which is the device ID to remove, i.e.:
-         i
+        Takes one uint32 argument, which is the device ID to remove, i.e.:
+         u
         is the signature.
 
         Returns one signed int32 which represents an X status as defined in
@@ -34,4 +37,4 @@ org.x.config.input:
 
     org.x.config.input.listDevices:
         Lists the currently active devices. No argument. 
-        Return value is sequence of <id> <name> <id> <name> ...
+        Return value is sequence of [<id> <name>] [<id> <name>] ..., i.e. [us].