[PATCH libevdev 2/4] Put a warning in the documentation about disabling/enabling event types/codes

[Peter Hutterer]

If a client disables a code halfway through an MT interaction the touch up
events are lost. If it re-enables a code it may get weird event sequences.
That's something the client has to deal with though because without getting
events a client cannot know the current state of a device.

Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
 libevdev/libevdev.h | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/libevdev/libevdev.h b/libevdev/libevdev.h
index 3edc3ae..856aeb9 100644
--- a/libevdev/libevdev.h
+++ b/libevdev/libevdev.h
@@ -1751,6 +1751,12 @@ void libevdev_set_abs_info(struct libevdev *dev, unsigned int code, const struct
  * This is a local modification only affecting only this representation of
  * this device.
  *
+ * @note If a caller has previously invoked libevdev_disable_event_code() or
+ * libevdev_disable_event_type(), re-enabling an event type may cause
+ * unexpected event sequences. For example, re-enabling an event type while a
+ * touch is down may cause a touch end to be passed to the caller without a
+ * preceding touch down event.
+ *
  * @param dev The evdev device, already initialized with libevdev_set_fd()
  * @param type The event type to enable (EV_ABS, EV_KEY, ...)
  *
@@ -1778,6 +1784,11 @@ int libevdev_enable_event_type(struct libevdev *dev, unsigned int type);
  * This is a local modification only affecting only this representation of
  * this device.
  *
+ * @note This function should only be invoked when the respective event type
+ * is in a neutral state. Otherwise, a caller may get unexpected event
+ * sequences. For example, disabling an event type while a touch is down may
+ * cause the touch end event to be discarded.
+ *
  * @param dev The evdev device, already initialized with libevdev_set_fd()
  * @param type The event type to disable (EV_ABS, EV_KEY, ...)
  *
@@ -1811,6 +1822,12 @@ int libevdev_disable_event_type(struct libevdev *dev, unsigned int type);
  * that already has the given event code enabled, the values in data
  * overwrite the previous values.
  *
+ * @note If a caller has previously invoked libevdev_disable_event_code() or
+ * libevdev_disable_event_type(), re-enabling an event code may cause
+ * unexpected event sequences. For example, re-enabling an event code while a
+ * touch is down may cause a touch end to be passed to the caller without a
+ * preceding touch down event.
+ *
  * @param dev The evdev device, already initialized with libevdev_set_fd()
  * @param type The event type to enable (EV_ABS, EV_KEY, ...)
  * @param code The event code to enable (ABS_X, REL_X, etc.)
@@ -1841,6 +1858,11 @@ int libevdev_enable_event_code(struct libevdev *dev, unsigned int type, unsigned
  * Disabling codes of type EV_SYN will not work. Don't shoot yourself in the
  * foot. It hurts.
  *
+ * @note This function should only be invoked when the respective event type
+ * is in a neutral state. Otherwise, a caller may get unexpected event
+ * sequences. For example, disabling an event code while a touch is down may
+ * cause the touch end event to be discarded.
+ *
  * @param dev The evdev device, already initialized with libevdev_set_fd()
  * @param type The event type to disable (EV_ABS, EV_KEY, ...)
  * @param code The event code to disable (ABS_X, REL_X, etc.)
-- 
2.7.3