State that the event is defined for a SYN_DROPPED

All clients that want to handle SYN_DROPPED correctly need to pass an EV_SYN
through their own handlers before starting with the syn events. Rather than
letting them synthesize that, guarantee that the event is defined the first
time LIBEVDEV_READ_STATUS_SYNC is returned.

This does not change existing behavior, it merely documents it so we can rely
on it.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

diff --git a/libevdev/libevdev.h b/libevdev/libevdev.h
index 23d1b32..87f226c 100644 (file)
--- a/libevdev/libevdev.h
+++ b/libevdev/libevdev.h
@@ -657,7 +657,8 @@ enum libevdev_read_status {
  * time, it returns -EAGAIN and ev is undefined.
  *
  * If a SYN_DROPPED is read from the device, this function returns
- * LIBEVDEV_READ_STATUS_SYNC. The caller should now call this function with the
+ * LIBEVDEV_READ_STATUS_SYNC and ev is set to the EV_SYN event.
+ * The caller should now call this function with the
  * LIBEVDEV_READ_FLAG_SYNC flag set, to get the set of events that make up the
  * device state delta. This function returns LIBEVDEV_READ_STATUS_SYNC for
  * each event part of that delta, until it returns -EAGAIN once all events
@@ -673,10 +674,11 @@ enum libevdev_read_status {
  * set, the next event is read in sync mode.
  * @param ev On success, set to the current event.
  * @return On failure, a negative errno is returned.
- * @retval LIBEVDEV_READ_STATUS_SUCCESS One or more events where read of the device
+ * @retval LIBEVDEV_READ_STATUS_SUCCESS One or more events were read of the
+ * device and ev points to the next event in the queue
  * @retval -EAGAIN No events are currently available on the device
  * @retval LIBEVDEV_READ_STATUS_SYNC A SYN_DROPPED event was received, or a
- * synced event was returned.
+ * synced event was returned and ev points to the SYN_DROPPED event
  *
  * @note This function is signal-safe.
  */

diff --git a/test/test-libevdev-events.c b/test/test-libevdev-events.c
index 7903043..6340a58 100644 (file)
--- a/test/test-libevdev-events.c
+++ b/test/test-libevdev-events.c
@@ -108,6 +108,8 @@ START_TEST(test_syn_event)
        ck_assert_int_eq(ev.code, SYN_REPORT);
        rc = libevdev_next_event(dev, LIBEVDEV_READ_FLAG_NORMAL, &ev);
        ck_assert_int_eq(rc, LIBEVDEV_READ_STATUS_SYNC);
+       ck_assert_int_eq(ev.type, EV_SYN);
+       ck_assert_int_eq(ev.code, SYN_DROPPED);
 
        /* only check for the rc, nothing actually changed on the device */