From 65c0b39c3ee6341d3bf2ce9ffbace8a76f93076c Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Mon, 15 Dec 2025 10:41:21 +1000 Subject: [PATCH] ei: match the EI_EVENT_DEVICE_PAUSED docs with the protocol This is a behavior break if we're looking at the documentation only but the protocol has required the logical reset of the device since libei 0.5 - this here is just stale documentation that didn't get updated. And keeping the state across paused/resume is too hard to get right anyway. Part-of: --- src/libei.h | 17 ++++++++++++++--- src/libeis.h | 11 ++++++----- 2 files changed, 20 insertions(+), 8 deletions(-) diff --git a/src/libei.h b/src/libei.h index 56b370c..3be0db7 100644 --- a/src/libei.h +++ b/src/libei.h @@ -396,13 +396,24 @@ enum ei_event_type { /** * Any events sent from this device will be discarded until the next - * resume. The state of a device is not expected to change between - * pause/resume - for any significant state changes the server is - * expected to remove the device instead. + * resume. + * + * Pausing a device resets the logical state of the device to neutral. + * This includes: + * - any buttons or keys logically down are released + * - any modifiers logically down are released + * - any touches logically down are released + * + * Sender clients must wait until @ref EI_EVENT_DEVICE_RESUMED + * before sending events. */ EI_EVENT_DEVICE_PAUSED, + /** * The client may send events. + * + * Once resumed, a sender client may call ei_device_start_emulating() + * and begin emulating events. */ EI_EVENT_DEVICE_RESUMED, diff --git a/src/libeis.h b/src/libeis.h index 267b6b2..3d5b4b6 100644 --- a/src/libeis.h +++ b/src/libeis.h @@ -1358,11 +1358,12 @@ eis_device_remove(struct eis_device *device); * a number of events from a device after it has been paused and must * update its internal state accordingly. * - * Pause/resume should only be used for short-term event delaying, a client - * will expect that the device's state has not changed between pause and - * resume. Where a device's state changes on the EIS implementation side (e.g. - * buttons or keys are forcibly released), the device should be removed and - * re-added as new device. + * Pausing a device resets the logical state of the device to neutral. + * This includes: + * - any buttons or keys logically down are released + * - any modifiers logically down are released + * - any touches logically down are released + * No events will be sent for these releases back to a neutral state. * * @param device A connected device */