[Libdlo] Equivalent for $DISPLAY

[Phil Endecott]

Phil Endecott wrote:
> Dear All,
>
> libdlo provides a convenient function, dlo_claim_first_device(), to get 
> the first attached device.  This is great if you only have one device 
> connected.  But there's a danger that we'll end up with utilities that 
> call this and so cannot be made to work on systems with more than one 
> device attached.
>
> I'd like to propose that we remove dlo_claim_first_device() and instead 
> provide something like dlo_claim_default_device().  This will behave 
> like X applications and check for an environment variable or 
> command-line option that specifies the device to use, and will fall 
> back to the first unclaimed device if nothing else is specified.

Here is a proposal for discussion.  The command-line option is 
--dlo:display=serialnumber; this is inspired by the way that DirectFB apps 
take various --dfb:something options.  Like DirectFB we could add options 
for things like the screen mode, compression settings and so on.  Requiring 
that the serial number is joined to the option with an = rather than being 
a separate token makes it possible to skip all --dlo:* options without 
knowing whether they take an argument; on the other hand, it's less 
consistent with X's -display.  The environment variable is DLODISPLAY.

I haven't thought any more about how displays are identified; for now this 
just matches the serial number, but I believe we probably want something 
better than that.

I'm unsure how this should interact with the claimed/unclaimed stuff, i.e. 
if the specified display is already claimed should it fail or choose the next 
one?  This gets more complicated if the display spec is something that could 
match multiple devices.

Thoughts?

Phil.

---

index 12e6f33..1810cb5 100644
--- a/src/libdlo.c
+++ b/src/libdlo.c
@@ -467,8 +467,48 @@ error:
 }
 
 
-dlo_dev_t dlo_claim_first_device(const dlo_claim_t flags, const uint32_t timeout)
+static const char* parse_cmdline(int *argc_p, char *argv[])
 {
+  /* Scan the command line looking for --dlo:display.  Return the value found, if
+   * any, else return NULL.  Remove all --dlo:* options from argv.
+   */
+
+  const char *display = NULL;
+  int n;
+  int m = 1;
+
+  if (!argc_p) {
+    return NULL;
+  }
+
+  for (n=1; n<*argc_p; ++n) {
+    const char* arg = argv[n];
+    if (strncmp(arg,"--dlo:",6)==0) {
+      const char* dlo_arg = arg + 6;
+      if (strncmp(dlo_arg,"display=",8)==0) {
+        display = dlo_arg + 8;
+      }
+    } else {
+      argv[m] = arg;
+      ++m;
+    }
+  }
+  *argc_p = m;
+  return display;
+}
+
+dlo_dev_t dlo_claim_default_device(int *argc_p, char *argv[],
+                                   const dlo_claim_t flags, const uint32_t timeout)
+{
+  const char *display = parse_cmdline(argc_p, argv);
+  if (!display) {
+    display = getenv("DLODISPLAY");
+  }
+
+  // For now, assume that display is simply the serial number.  Some thought about 
+  // exactly what its format should be is needed.
+  const char *serial = display;
+
   dlo_devlist_t *node;
   dlo_devlist_t *next;
   dlo_dev_t      uid = 0;
@@ -481,7 +521,8 @@ dlo_dev_t dlo_claim_first_device(const dlo_claim_t flags, const uint32_t timeout
   {
     dlo_device_t *dev = (dlo_device_t *)node->dev.uid;
 
-    if (!uid && !dev->claimed)
+    if (!uid && !dev->claimed
+        && (!serial || strcmp(serial,dev->serial)==0))
     {
       uid = dlo_claim_device(node->dev.uid, flags, timeout);
     }
diff --git a/src/libdlo.h b/src/libdlo.h
index 1b8de1c..282fa8e 100644
--- a/src/libdlo.h
+++ b/src/libdlo.h
@@ -604,22 +604,31 @@ extern dlo_devlist_t *dlo_enumerate_devices(void);
 extern dlo_dev_t dlo_claim_device(const dlo_dev_t uid, const dlo_claim_t flags, const uint32_t timeout);
 
 
-/** Claim the first available (unclaimed) device.
+/** Claim the default device.
  *
+ *  @param  argc_p   Pointer to main program's argc.
+ *  @param  argv     Main program's argv.
  *  @param  flags    Flags word describing how the device is to be accessed.
  *  @param  timeout  Timeout in milliseconds (zero for infinite).
  *
  *  @return  Unique ID of the claimed device (or NULL if failed).
  *
- *  This call performs a very similar function to @c dlo_claim_device() except
- *  that it performs the enumeration of connected devices on behalf of the caller
- *  and returns the unique ID of the first available (unclaimed device). This
- *  device is claimed automatically.
+ *  This call enumerates the connected devices and returns the unique ID of the default 
+ *  device.  The default device is selected by the DLODISPLAY environment variable or the
+ *  --dlo:display command-line option; if neither is specified the first device found is
+ *  selected.  This selected device is claimed.
  *
- *  If no unclaimed devices are found, or if the claim operation itself fails in
- *  some way, the function will return a device handle of zero.
+ *  If no default device is found, or if the claim operation fails, the function will 
+ *  return a device handle of zero.
+ *
+ *  The main program should pass a pointer to argc and argv to this function so that any 
+ *  --dlo:display option can be found.  This function will update argc and argv to remove 
+ *  any --dlo:* options that it finds, so the main program need not worry about the 
+ *  presence of these options in the command line if it calls this function first.
+ *  Pass NULL as argc_p to disable command-line parsing.
  */
-extern dlo_dev_t dlo_claim_first_device(const dlo_claim_t flags, const uint32_t timeout);
+extern dlo_dev_t dlo_claim_default_device(int *argc_p, char *argv[],
+                                          const dlo_claim_t flags, const uint32_t timeout);
 
 
 /** Release the specified device.