Introduce a stable ABI

The current mtdev is not ABI stable, and the upcoming additions
to the kernel api will break ABI. This patch starts the process
of keeping binary compatibility with old programs, by moving the
abi-specific parts under a special flag, MTDEV_NO_LEGACY_API,
and makes sure the internal parts compiles with MTDEV_NO_LEGACY_API
set. This way, older programs will still work, old programs will
still compile, and new programs will be able to use the additions.

Signed-off-by: Henrik Rydberg <rydberg@euromail.se>

3 files changed, 114 insertions, 44 deletions

diff --git a/include/mtdev-mapping.h b/include/mtdev-mapping.h
index 0e47970..0cdb39d 100644
--- a/include/mtdev-mapping.h
+++ b/include/mtdev-mapping.h
@@ -37,6 +37,8 @@ extern "C" {
 
 #include <mtdev.h>
 
+#ifndef MTDEV_NO_LEGACY_API
+
 #define MTDEV_TOUCH_MAJOR       0
 #define MTDEV_TOUCH_MINOR       1
 #define MTDEV_WIDTH_MAJOR       2
@@ -80,6 +82,8 @@ static inline unsigned int mtdev_mt2abs(unsigned int mtcode)
         return mtdev_map_mt2abs[mtcode];
 }
 
+#endif
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mtdev-plumbing.h b/include/mtdev-plumbing.h
index cadc1f7..21ca708 100644
--- a/include/mtdev-plumbing.h
+++ b/include/mtdev-plumbing.h
@@ -36,6 +36,15 @@ extern "C" {
 #include <mtdev.h>
 
 /**
+ * mtdev_new - allocate a new mtdev
+ *
+ * Allocate a new mtdev.
+ *
+ * Returns zero in case of memory allocation failure.
+ */
+struct mtdev *mtdev_new(void);
+
+/**
  * mtdev_init - initialize mtdev converter
  * @dev: the mtdev to initialize
  *
@@ -46,6 +55,26 @@ extern "C" {
 int mtdev_init(struct mtdev *dev);
 
 /**
+ * mtdev_set_mt_event - set event type
+ * @dev: the mtdev in use
+ * @code: the ABS_MT code to set
+ * @value: boolean value
+ *
+ * Returns true if the given event code is present.
+ */
+void mtdev_set_mt_event(struct mtdev *dev, int code, int value);
+
+/**
+ * mtdev_set_abs_<property> - set abs event property
+ * @dev: the mtdev in use
+ * @code: the ABS_MT code to set
+ */
+void mtdev_set_abs_minimum(struct mtdev *dev, int code, int value);
+void mtdev_set_abs_maximum(struct mtdev *dev, int code, int value);
+void mtdev_set_abs_fuzz(struct mtdev *dev, int code, int value);
+void mtdev_set_abs_resolution(struct mtdev *dev, int code, int value);
+
+/**
  * mtdev_configure - configure the mtdev converter
  * @dev: the mtdev to configure
  * @fd: file descriptor of the kernel device
@@ -106,6 +135,14 @@ int mtdev_empty(struct mtdev *dev);
  */
 void mtdev_get_event(struct mtdev *dev, struct input_event* ev);
 
+/**
+ * mtdev_delete - free a previously allocated mtdev
+ *
+ * Frees the memory associated with the mtdev and invalidates the
+ * mtdev pointer.
+ */
+void mtdev_delete(struct mtdev *dev);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mtdev.h b/include/mtdev.h
index 15bc53b..df74e95 100644
--- a/include/mtdev.h
+++ b/include/mtdev.h
@@ -62,59 +62,23 @@ extern "C" {
 #ifndef ABS_MT_SLOT
 #define ABS_MT_SLOT             0x2f    /* MT slot being modified */
 #endif
-#ifndef MT_SLOT_ABS_EVENTS
-#define MT_SLOT_ABS_EVENTS {    \
-        ABS_MT_TOUCH_MAJOR,     \
-        ABS_MT_TOUCH_MINOR,     \
-        ABS_MT_WIDTH_MAJOR,     \
-        ABS_MT_WIDTH_MINOR,     \
-        ABS_MT_ORIENTATION,     \
-        ABS_MT_POSITION_X,      \
-        ABS_MT_POSITION_Y,      \
-        ABS_MT_TOOL_TYPE,       \
-        ABS_MT_BLOB_ID,         \
-        ABS_MT_TRACKING_ID,     \
-        ABS_MT_PRESSURE,        \
-}
-#endif
-
-#define MT_ABS_SIZE 11
 
 #define MT_ID_NULL      (-1)
 #define MT_ID_MIN       0
 #define MT_ID_MAX       65535
 
 /**
- * struct mt_caps - protocol capabilities of kernel device
- * @has_mtdata: true if the device has MT capabilities
- * @has_slot: true if the device sends MT slots
- * @slot: slot event properties
- * @abs: ABS_MT event properties
- */
-struct mtdev_caps {
-        int has_mtdata;
-        int has_slot;
-        int has_abs[MT_ABS_SIZE];
-        struct input_absinfo slot;
-        struct input_absinfo abs[MT_ABS_SIZE];
-};
-
-/**
- * struct mtdev - represents an input MT device
- * @caps: the kernel device protocol capabilities
- * @state: internal mtdev parsing state
+ * mtdev_new_open - create and open a new mtdev
+ * @fd: file descriptor of the kernel device
+ *
+ * Create a new mtdev and open the conversion.
  *
- * The mtdev structure represents a kernel MT device type B, emitting
- * MT slot events. The events put into mtdev may be from any MT
- * device, specifically type A without contact tracking, type A with
- * contact tracking, or type B with contact tracking. See the kernel
- * documentation for further details.
+ * Returns zero in case of failure.
  *
+ * This call combines the plumbing functions mtdev_new() and
+ * mtdev_open().
  */
-struct mtdev {
-        struct mtdev_caps caps;
-        struct mtdev_state *state;
-};
+struct mtdev *mtdev_new_open(int fd);
 
 /**
  * mtdev_open - open an mtdev converter
@@ -132,6 +96,27 @@ struct mtdev {
 int mtdev_open(struct mtdev *dev, int fd);
 
 /**
+ * mtdev_has_mt_event - check for event type
+ * @dev: the mtdev in use
+ * @code: the ABS_MT code to look for
+ *
+ * Returns true if the given event code is present.
+ */
+int mtdev_has_mt_event(const struct mtdev *dev, int code);
+
+/**
+ * mtdev_get_abs_<property> - get abs event property
+ * @dev: the mtdev in use
+ * @code: the ABS_MT code to look for
+ *
+ * Returns NULL if code is not a valid ABS_MT code.
+ */
+int mtdev_get_abs_minimum(const struct mtdev *dev, int code);
+int mtdev_get_abs_maximum(const struct mtdev *dev, int code);
+int mtdev_get_abs_fuzz(const struct mtdev *dev, int code);
+int mtdev_get_abs_resolution(const struct mtdev *dev, int code);
+
+/**
  * mtdev_idle - check state of kernel device
  * @dev: the mtdev in use
  * @fd: file descriptor of the kernel device
@@ -173,6 +158,50 @@ int mtdev_get(struct mtdev *dev, int fd, struct input_event* ev, int ev_max);
  */
 void mtdev_close(struct mtdev *dev);
 
+/**
+ * mtdev_close_delete - close conversion and delete mtdev
+ * @dev: the mtdev in use
+ *
+ * Flush pending buffers and deallocate all memory associated with
+ * mtdev. The device pointer is invalidated.  This call combines the
+ * plumbing functions mtdev_close() and mtdev_delete().
+ */
+void mtdev_close_delete(struct mtdev *dev);
+
+#ifndef MTDEV_NO_LEGACY_API
+
+#define MT_ABS_SIZE 11
+#ifndef MT_SLOT_ABS_EVENTS
+#define MT_SLOT_ABS_EVENTS {    \
+        ABS_MT_TOUCH_MAJOR,     \
+        ABS_MT_TOUCH_MINOR,     \
+        ABS_MT_WIDTH_MAJOR,     \
+        ABS_MT_WIDTH_MINOR,     \
+        ABS_MT_ORIENTATION,     \
+        ABS_MT_POSITION_X,      \
+        ABS_MT_POSITION_Y,      \
+        ABS_MT_TOOL_TYPE,       \
+        ABS_MT_BLOB_ID,         \
+        ABS_MT_TRACKING_ID,     \
+        ABS_MT_PRESSURE,        \
+}
+#endif
+
+struct mtdev_caps {
+        int has_mtdata;
+        int has_slot;
+        int has_abs[MT_ABS_SIZE];
+        struct input_absinfo slot;
+        struct input_absinfo abs[MT_ABS_SIZE];
+};
+
+struct mtdev {
+        struct mtdev_caps caps;
+        struct mtdev_state *state;
+};
+
+#endif
+
 #ifdef __cplusplus
 }
 #endif