moved: Add instructions, client API calls

README.moved

@@ -0,0 +1,34 @@
+
+Move Daemon Usage Instructions
+==============================
+
+You need to place a file "moved_hosts.txt" into the data directory of PS Move
+API (usually ~/.psmoveapi/, in Windows %APPDATA%/.psmoveapi/) with one IP
+address per line that points to a moved instance.
+
+Example moved_hosts.txt contents (between the "="):
+=============
+192.168.0.2
+=============
+
+This would try to use the moved running on 192.168.0.2. You can have multiple
+IPs listed there (one per line), the servers will be tried in order.
+
+After that, you can use the PS Move API just as you normally would, and after
+your locally-connected controllers, controllers connected to remote machines
+will be used (psmove_count_connected() and psmove_connect_by_id() will take
+the remote controllers into account).
+
+If you want to only use remotely-connected controllers (ignoring any
+controllers that are connected locally), or if you want to use moved running
+on localhost (where it will already provide the connected controllers to you),
+you should add the following API call at the beginning of your application to
+ensure that locally-connected devices are not used via hidapi:
+
+    psmove_set_remote_config(PSMove_OnlyRemote);
+
+Similarly, you can disable remote controllers via the following API call (in
+that case, no connections to moved are carred out, only hidapi is used):
+
+    psmove_set_remote_config(PSMove_OnlyLocal);
+

include/psmove.h

@@ -151,12 +151,37 @@ enum PSMove_Bool {
     PSMove_True = 1, /*!< True, Success, Enabled (depending on context) */
 };
 
+/*! Remote configuration options, for psmove_set_remote_config() */
+enum PSMove_RemoteConfig {
+    PSMove_LocalAndRemote = 0, /*!< Use both local (hidapi) and remote (moved) devices */
+    PSMove_OnlyLocal = 1, /*!< Use only local (hidapi) devices, ignore remote devices */
+    PSMove_OnlyRemote = 2, /*!< Use only remote (moved) devices, ignore local devices */
+};
+
 #ifndef SWIG
 struct _PSMove;
 typedef struct _PSMove PSMove; /*!< Handle to a PS Move Controller.
                                     Obtained via psmove_connect_by_id() */
 #endif
 
+/**
+ * \brief Enable or disable the usage of local or remote devices
+ *
+ * By default, both local (hidapi) and remote (moved) controllers will be
+ * used. If your application only wants to use locally-connected devices,
+ * and ignore any remote controllers, call this function with
+ * \ref PSMove_OnlyLocal - to use only remotely-connected devices, use
+ * \ref PSMove_OnlyRemote instead.
+ *
+ * This function must be called before any other PS Move API functions are
+ * used, as it changes the behavior of counting and connecting to devices.
+ *
+ * \param config \ref PSMove_LocalAndRemote, \ref PSMove_OnlyLocal or
+ *               \ref PSMove_OnlyRemote
+ **/
+ADDAPI void
+ADDCALL psmove_set_remote_config(enum PSMove_RemoteConfig config);
+
 /**
  * \brief Get the number of available controllers
  *

src/psmove.c

@@ -369,15 +369,10 @@ psmove_set_btaddr(PSMove *move, PSMove_Data_BTAddr *addr);
 
 
 void
-_psmove_disable_remote()
+psmove_set_remote_config(enum PSMove_RemoteConfig config)
 {
-    psmove_remote_disabled = 1;
-}
-
-void
-_psmove_disable_local()
-{
-    psmove_local_disabled = 1;
+    psmove_remote_disabled = (config == PSMove_OnlyLocal);
+    psmove_local_disabled = (config == PSMove_OnlyRemote);
 }
 
 void

src/psmove_private.h

@@ -116,24 +116,6 @@ ADDCALL _psmove_write_data(PSMove *move, unsigned char *data, int length);
 ADDAPI void
 ADDCALL _psmove_read_data(PSMove *move, unsigned char *data, int length);
 
-/**
- * [PRIVATE API] Disable the connection to remote servers
- *
- * This can only be called at the beginning, and will disable connections to
- * any remote "moved" servers.
- **/
-ADDAPI void
-ADDCALL _psmove_disable_remote();
-
-/**
- * [PRIVATE API] Disable local (hidapi-based) controllers
- *
- * This can only be called at the beginning, and will disable all local
- * controllers that are connected via hidapi.
- **/
-ADDAPI void
-ADDCALL _psmove_disable_local();
-
 /**
  * [PRIVATE API] Internal device open function (hidraw, Linux / for moved)
  **/

src/utils/moved.c

@@ -81,7 +81,7 @@ main(int argc, char *argv[])
 #endif
 
     /* Never act as a client in "moved" mode */
-    _psmove_disable_remote();
+    psmove_set_remote_config(PSMove_OnlyLocal);
 
     moved_dump_devices(moved);