From 562e120da8c1ba84c1b7c82adb50a4bd04467126 Mon Sep 17 00:00:00 2001
From: Peter Hutterer <peter.hutterer@who-t.net>
Date: Thu, 16 Jul 2020 09:17:48 +1000
Subject: [PATCH] libei: change the device creation API a bit

Split into a _new() call and make the others setters, with a bit more
explanation of what the server does.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
---
 src/libei.h | 45 +++++++++++++++++++++++++++++++++++----------
 1 file changed, 35 insertions(+), 10 deletions(-)

diff --git a/src/libei.h b/src/libei.h
index 35a0067..93254c1 100644
--- a/src/libei.h
+++ b/src/libei.h
@@ -169,24 +169,49 @@ struct ei_device *
 ei_device_unref(struct ei_device *device);
 
 /**
- * Request the creation of a device with suggested capabilities and a
- * suggested name. Note that the server may ignore the name and may ignore
- * all capabilities.
- *
- * The device returned is a stub device maintained by the library and should
+ * Create a new device. This device is local to the client and should
  * only used for initial device configuration. It does not represent the
  * server-created device until the @ref EI_EVENT_DEVICE_ADDED for this
  * device has been received.
  *
- * This does not increase the refcount of the device. Use ei_device_ref() to
- * keep a reference beyond the immediate scope.
+ * Use the configure API (e.g. ei_device_configure_capability()) to set up
+ * the device, then call ei_device_add() to request creation of the device
+ * by the server.
+ *
+ * The refcount of the returned device is 1, use ei_device_unref() to
+ * release resources associated with this device..
  *
  * @param ei The context
- * @param capabilities A bitmask of @ref ei_device_capability
- * @param name A name suggestion for the device
  */
 struct ei_device *
-ei_create_device(struct ei_ctx *ei, uint32_t capabilities, const char *name);
+ei_device_new(struct ei_ctx *ei);
+
+/**
+ * Set the name for this device. This is a suggestion only, the server may
+ * the name and assign a different one (or none). Use ei_device_get_name()
+ * upon receiving @ref EI_EVENT_DEVICE_ADDED to get the server-assigned
+ * name.
+ *
+ * This function has no effect if called after ei_device_add()
+ *
+ * @param name A name suggestion for the device
+ */
+void
+ei_device_configure_name(struct ei_device *device, const char *name);
+
+/**
+ * Enable the given capability on this device. This is a suggestion only,
+ * the server may ignore this capability.
+ * Use ei_device_has_capability() upon receiving @ref EI_EVENT_DEVICE_ADDED
+ * to check for the actual capabilities of the device.
+ *
+ * This function has no effect if called after ei_device_add()
+ *
+ * @param cap The capability to enable
+ */
+void
+ei_device_configure_capability(struct ei_device *device,
+			       enum ei_device_capability cap);
 
 /**
  * Request that the device be added to the server.