[PATCH] parser: add DC_FIELD_DEVINFO field type for parse-time device information

[Linus Torvalds]

From: Linus Torvalds <torvalds at linux-foundation.org>
Date: Wed, 22 Oct 2014 11:23:09 -0700
Subject: parser: add DC_FIELD_DEVINFO field type for parse-time device information

This can be used to extend and override the device open-time DEVINFO
callback information at dive parse time.  If you leave the pointers
NULL, nothing happens, but you can choose to individually fill in the
fields as needed (or not).

NOTE: The caller is supposed to clear the structure so that the
divecomputer backends don't need to care about fields they don't
support.  So it's valid for a backend to just return DC_STATUS_SUCCESS
and not do anything else as a reply to DC_FIELD_DEVINFO, although
obviously that means that you won't be returning any new information
either.

Signed-off-by: Linus Torvalds <torvalds at linux-foundation.org>
---

This is actually "PATCH 6/7" in my current series to support the new 
Suunto EON Steel dive computer, but it stands on its own as preparatory 
infrastructure, and I thought I should send it out as such.

This simply implements the "DC_FIELD_DEVINFO" field, which allows a dive 
computer backend to - at parse time - give what amounts to a sanitized and 
extended version of the DC_EVENT_DEVINFO device event.

In particular, it differs from DEVINFO in that:

 - it contains all strings (expected to be utf8, because we're not 
   barbarians any more, but for Windows people you could
   just say "ASCII" to not confuse the poor souls)

 - it is expected to be called for each dive at parse time, and also thus 
   allows a "dive id" string to be filled in.

 - if the dive computer backend doesn't have anything to add to the 
   original DC_EVENT_DEVINFO, then the backend can just ignore this.

The basic premise is simply that (a) strings are good and (b) we may have 
more information at parse-time than at the original DC_EVENT time.. 

This is trivially usable by subsurface - or any other user of 
libdivecomputer - in *addition* to the old interface, and I'll post 
another patch to show how subsurface does it. It doesn't replace or remove 
the old DC_EVENT_DEVINFO interface, it really just is a seamless extension 
of it with a better interface.

As you can see, the patch itself is also really really trivial and small. 
So not only is this flexible and simple to use, the implementation really 
is trivial too.

Comments? Btw, I'm in no way married to the particular fields. They are 
not at all everything that the EON Steel returns, but they seem to be 
fairly generic and useful in general.

Side note: the "vendor/model" thing migth be too much repetition and I 
don't really use it for the EON Steel at all, but I added those because I 
think it might be useful for the case where the user doesn't specify the 
device very precisely, and one backend can handle many different models. 

In other words, this might be a good way to allow the back-end to give 
more precise information, without having the user having to care (ie if 
the backend can download from both a "Mares Icon" and a "Mares Icon HD", 
and the user doesn't need to specify *which* one it is, this would allow 
the dive log app to get the exact model name even if the user just said 
"Mares Icon".

Comments?

 include/libdivecomputer/parser.h | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/include/libdivecomputer/parser.h b/include/libdivecomputer/parser.h
index 65b18c9bb2fe..741803f4e256 100644
--- a/include/libdivecomputer/parser.h
+++ b/include/libdivecomputer/parser.h
@@ -53,9 +53,13 @@ typedef enum dc_field_type_t {
 	DC_FIELD_GASMIX_COUNT,
 	DC_FIELD_GASMIX,
 	DC_FIELD_SALINITY,
-	DC_FIELD_ATMOSPHERIC
+	DC_FIELD_ATMOSPHERIC,
+	DC_FIELD_DEVINFO,
 } dc_field_type_t;
 
+// Make it easy to test support compile-time with "#ifdef DC_FIELD_DEVINFO"
+#define DC_FIELD_DEVINFO DC_FIELD_DEVINFO
+
 typedef enum parser_sample_event_t {
 	SAMPLE_EVENT_NONE,
 	SAMPLE_EVENT_DECOSTOP,
@@ -128,6 +132,17 @@ typedef struct dc_gasmix_t {
 	double nitrogen;
 } dc_gasmix_t;
 
+// You don't have to fill all of these in, you can leave them NULL
+// but if you do fill them in, they override the device devinfo
+typedef struct dc_field_devinfo_t {
+	const char *vendor;
+	const char *model;
+	const char *serial;
+	const char *hw_version;
+	const char *fw_version;
+	const char *dive_id;
+} dc_field_devinfo_t;
+
 typedef union dc_sample_value_t {
 	unsigned int time;
 	double depth;
-- 
2.1.2.452.gd5ca7ae