libei/src/libeis.h

/*
 * Copyright © 2020 Red Hat, Inc.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice (including the next
 * paragraph) shall be included in all copies or substantial portions of the
 * Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */


#pragma once

#include <stddef.h>
#include <stdbool.h>
#include <stdint.h>

struct eis;
struct eis_client;
struct eis_device;
struct eis_event;

enum eis_device_capability {
	EIS_DEVICE_CAP_POINTER = 1,
	EIS_DEVICE_CAP_POINTER_ABSOLUTE,
	EIS_DEVICE_CAP_KEYBOARD,
	EIS_DEVICE_CAP_TOUCH,
};

enum eis_keymap_type {
	EIS_KEYMAP_TYPE_NONE = 0,
	EIS_KEYMAP_TYPE_XKB,
};

enum eis_event_type {
	/**
	 * A client has connected. This is the first event from any new
	 * client.
	 * The server is expected to either call eis_event_client_allow() or
	 * eis_event_client_deny().
	 */
	EIS_EVENT_CLIENT_CONNECT = 1,
	/**
	 * The client has disconnected, any pending requests for this client
	 * should be discarded.
	 */
	EIS_EVENT_CLIENT_DISCONNECT,

	/**
	 * The client requests creation of a device with a given set of
	 * capabilities. A client may create more than one device and more
	 * than one device with the same capabilities. The server may filter
	 * the capabilities or deny them altogether.
	 *
	 */
	EIS_EVENT_DEVICE_ADDED,
	/**
	 * The device created by the client was removed. The server must
	 * call eis_device_disconnect() in response to this device.
	 *
         * libeis guarantees this event is generated before
	 * @ref EIS_EVENT_CLIENT_DISCONNECT.
	 */
	EIS_EVENT_DEVICE_REMOVED,

	EIS_EVENT_POINTER_MOTION = 300,
	EIS_EVENT_POINTER_MOTION_ABSOLUTE,
	EIS_EVENT_POINTER_BUTTON,
	EIS_EVENT_POINTER_SCROLL,
	EIS_EVENT_POINTER_SCROLL_DISCRETE,

	EIS_EVENT_KEYBOARD_KEY = 400,

	EIS_EVENT_TOUCH_DOWN = 500,
	EIS_EVENT_TOUCH_UP,
	EIS_EVENT_TOUCH_MOTION,
};

/**
 * Create a new libeis context with a refcount of 1.
 */
struct eis *
eis_new(void *user_data);

enum eis_log_priority {
	EIS_LOG_PRIORITY_DEBUG = 10,
	EIS_LOG_PRIORITY_INFO = 20,
	EIS_LOG_PRIORITY_WARNING = 30,
	EIS_LOG_PRIORITY_ERROR = 40,
};

/**
 * The log handler for library logging. This handler is only called for
 * messages with a log level equal or greater than than the one set in
 * eis_log_set_priority().
 *
 * @param message The log message as a null-terminated string
 * @param is_continuation The message is a continuation of the previous
 * message. The caller should skip any per-line-based prefixes.
 */
typedef void (*eis_log_handler)(struct eis *eis,
				enum eis_log_priority priority,
				const char *message,
				bool is_continuation);
/**
 * Change the log handler for this context. If the log handler is NULL, the
 * built-in default log function is used.
 *
 * @param log_handler The log handler or NULL to use the default log
 * handler.
 */
void
eis_log_set_handler(struct eis *eis, eis_log_handler log_handler);

void
eis_log_set_priority(struct eis *eis, enum eis_log_priority priority);

enum eis_log_priority
eis_log_get_priority(const struct eis *eis);

struct eis *
eis_ref(struct eis *eis);

struct eis *
eis_unref(struct eis *eis);

void *
eis_get_user_data(struct eis *eis);

void
eis_set_user_data(struct eis *eis, void *user_data);

/**
 * Initialize the context with a UNIX socket name.
 * If the path does not start with / it is relative to $XDG_RUNTIME_DIR.
 */
int
eis_setup_backend_socket(struct eis *ctx, const char *path);

/**
 * Initialize the context that can take pre-configured sockets.
 */
int
eis_setup_backend_fd(struct eis *ctx);

/**
 * Add a new client to a context set up with eis_setup_backend_fd()
 */
int
eis_backend_fd_add_fd(struct eis *ctx, int fd);

/**
 * libeis keeps a single file descriptor for all events. This fd should be
 * monitored for events by the caller's mainloop, e.g. using select(). When
 * events are available on this fd, call libeis_dispatch() immediately to
 * process.
 */
int
eis_get_fd(struct eis *eis);

/**
 * Main event dispatchment function. Reads events of the file descriptors
 * and processes them internally. Use libeis_get_event() to retrieve the
 * events.
 *
 * Dispatching does not necessarily queue events. This function
 * should be called immediately once data is available on the file
 * descriptor returned by libeis_get_fd().
 */
void
eis_dispatch(struct eis *eis);

/**
 * Returns the next event in the internal event queue (or NULL) and removes
 * it from the queue.
 *
 * The returned event is refcounted, use eis_event_unref() to drop the
 * reference.
 *
 * You must not call this function while holding a reference to an event
 * returned by eis_peek_event().
 */
struct eis_event *
eis_get_event(struct eis *eis);

/**
 * Returns the next event in the internal event queue (or NULL) without
 * removing that event from the queue, i.e. the next call to eis_get_event()
 * will return that same event.
 *
 * This call is useful for checking whether there is an event and/or what
 * type of event it is.
 *
 * Repeated calls to eis_peek_event() return the same event.
 *
 * The returned event is refcounted, use eis_event_unref() to drop the
 * reference.
 *
 * A caller must not call eis_get_event() while holding a ref to an event
 * returned by eis_peek_event().
 */
struct eis_event *
eis_peek_event(struct eis *eis);

/**
 * Release resources associated with this event. This function always
 * returns NULL.
 *
 * The caller cannot increase the refcount of an event. Events should be
 * considered transient data and not be held longer than required.
 * eis_event_unref() is provided for consistency (as opposed to, say,
 * eis_event_free()).
 */
struct eis_event *
eis_event_unref(struct eis_event *event);

struct eis_client *
eis_client_ref(struct eis_client *client);

struct eis_client *
eis_client_unref(struct eis_client *client);

/**
 * Return the name set by this client. The server is under no obligation to
 * use this name.
 */
const char *
eis_client_get_name(struct eis_client *client);

/**
 * Allow connection from the client. This can only be done once, further
 * calls to this functions are ignored.
 *
 * When receiving an event of type @ref EIS_EVENT_CLIENT_CONNECT, the server
 * should connect client as soon as possible to allow communication with the
 * server. If the client is not authorized to talk to the server, call
 * eis_client_disconnect().
 */
void
eis_client_connect(struct eis_client *client);

/**
 * Disconnect this client. Once disconnected the client may no longer talk
 * to this context, all resources associated with this client should be
 * released.
 *
 * It is not necessary to call this function when an @ref
 * EIS_EVENT_CLIENT_DISCONNECT event is received.
 */
void
eis_client_disconnect(struct eis_client *client);

enum eis_event_type
eis_event_get_type(struct eis_event *event);

struct eis_client *
eis_event_get_client(struct eis_event *event);

struct eis_client *
eis_device_get_client(struct eis_device *device);

struct eis_device *
eis_device_ref(struct eis_device *device);

struct eis_device *
eis_device_unref(struct eis_device *device);

void *
eis_device_get_user_data(struct eis_device *eis_device);

void
eis_device_set_user_data(struct eis_device *eis_device, void *user_data);

/**
 * Return the name of the device. The return value of this function may change after
 * eis_device_set_name(), a caller should keep a copy of it where required rather than the
 * pointer value.
 */
const char *
eis_device_get_name(struct eis_device *device);

/**
 * Set the name of the device. This function has no effect if called after
 * eis_device_connect()
 */
void
eis_device_set_name(struct eis_device *device, const char *name);

bool
eis_device_has_capability(struct eis_device *device,
			  enum eis_device_capability cap);

/**
 * Allow a capability on the device. This function must be called in
 * response to an @EIS_EVENT_DEVICE_ADDED and before eis_device_connect().
 *
 * This function has no effect if called for a capability the device does
 * not support.
 *
 * This function has no effect if called after eis_device_connect()
 */
void
eis_device_allow_capability(struct eis_device *device,
			    enum eis_device_capability cap);

/**
 * Connects the device.
 *
 * This function should be called in response to an @ref
 * EIS_EVENT_DEVICE_ADDED if the server accepts the device creation.
 * Any changes to the device, e.g. eis_device_set_name() and
 * eis_device_disable_capability() must be performed before connecting the
 * device.
 *
 * Calling eis_device_connect() on a device with all capabilities set to
 * zero is a bug.
 *
 * If the device is rejected, call eis_device_disconnect() instead.
 *
 * The device is suspended, use eis_device_resume() to enable events from
 * the client.
 */
void
eis_device_connect(struct eis_device *device);

/**
 * Disconnect the device.
 * This does not release any resources associated with this device, use
 * eils_device_unref() for any references held by the caller.
 */
void
eis_device_disconnect(struct eis_device *device);

/**
 * Notify the client that the device is suspended and that no events
 * from the client will be processed.
 *
 * The library filters events sent by the client **after** the suspend
 * notification has been processed by the client but this does not affect
 * events already in transit. In other words, the server may still receive
 * a number of events from a device after it has been suspended and must
 * update its internal state accordingly.
 *
 * @param device A connected device
 */
void
eis_device_suspend(struct eis_device *device);

/**
 * Notify the client that the capabilities are resumed and that events
 * from the device will be processed.
 *
 * @param device A connected device
 */
void
eis_device_resume(struct eis_device *device);

/**
 * Get the width of the absolute pointer device in logical
 * pixels. The allowable range for absolute pointer motion is
 * [0, max) for each axis, i.e. zero inclusive, max exclusive. Coordinates
 * outside this range may be discarded or clipped silently by the library.
 *
 * The pointer range is constant. Where the pointer range is no longer
 * applicable, the client needs to remove the device and create and add a
 * new device with the updated pointer range.
 *
 * The server may use this in mapping heuristics. For example, a pointer
 * device with a pixel range of 1920x1200 **may** be automatically mapped by
 * the server to the monitor with this range, or a pointer device with a
 * ratio of R **may** be mapped to the monitor with the same ratio. This is
 * not a guarantee, the mapping policy is a private implementation detail
 * in the server. It is assumed that the client has other communication
 * channels (e.g. Wayland) to obtain the pointer range it needs to emulate
 * input on a device and channels to notify the server of desired mappings
 * (e.g. gsettings).
 *
 * It is a client bug to send pointer values outside this range.
 *
 * It is a server bug to call this function on a device without the @ref
 * EIS_DEVICE_CAP_POINTER_ABSOLUTE capability.
 *
 * @return The new width in logical pixels
 */
uint32_t
eis_device_pointer_get_width(struct eis_device *device);

/**
 * @see eis_device_pointer_get_width
 */
uint32_t
eis_device_pointer_get_height(struct eis_device *device);

/**
 * @see eis_device_pointer_get_width
 */
uint32_t
eis_device_touch_get_width(struct eis_device *device);

/**
 * @see eis_device_touch_get_width
 */
uint32_t
eis_device_touch_get_height(struct eis_device *device);

/**
 * Return a memmap-able file descriptor pointing to the keymap used by the
 * device. The keymap is constant for the lifetime of the device and
 * assigned to this device individually.
 *
 * If this function returns -1, this device does not have
 * an individual keymap assigned.
 */
int
eis_device_keyboard_get_keymap(struct eis_device *device);

size_t
eis_device_keyboard_get_keymap_size(struct eis_device *device);

enum eis_keymap_type
eis_device_keyboard_get_keymap_type(struct eis_device *device);

/**
 * Set the keymap on the device. This overwrites the client's choice of
 * keyboard. Note that **not** calling this function when
 * eis_device_keyboard_get_keymap() returns a value other than -1 is equivalent to
 * accepting the client's choice of keymap.
 *
 * If the fd is not -1, it is a memmap-able file descriptor pointing to the
 * keymap used by the device. This keymap is constant for the lifetime of
 * the device and assigned to this device individually. Where the keymap has
 * to change, remove the device and wait for the client to create a new one.
 *
 * If the fd is -1, the device does not have an individual keymap assigned.
 * and keymap type argument is ignored. A server that does not handle
 * individual client keymaps must call this function with an fd of
 * -1.
 *
 * This function has no effect if called after eis_device_connect()
 *
 * @param type the type of the keymap
 * @param fd a memmap-able file descriptor to the keymap
 */
void
eis_device_keyboard_set_keymap(struct eis_device *device,
		      enum eis_keymap_type type,
		      int fd, size_t size);

/**
 * Return the device from this event.
 *
 * This does not increase the refcount of the device. Use eis_device_ref()
 * to keep a reference beyond the immediate scope.
 */
struct eis_device *
eis_event_get_device(struct eis_event *event);

/**
 * For an event of type @ref EIS_EVENT_POINTER_MOTION return the relative x
 * movement in logical pixels.
 */
double
eis_event_pointer_get_dx(struct eis_event *event);

/**
 * For an event of type @ref EIS_EVENT_POINTER_MOTION return the relative y
 * movement in logical pixels.
 */
double
eis_event_pointer_get_dy(struct eis_event *event);

/**
 * For an event of type @ref EIS_EVENT_POINTER_MOTION_ABSOLUTE return the x
 * position in logical pixels.
 */
double
eis_event_pointer_get_absolute_x(struct eis_event *event);

/**
 * For an event of type @ref EIS_EVENT_POINTER_MOTION_ABSOLUTE return the y
 * position in logical pixels.
 */
double
eis_event_pointer_get_absolute_y(struct eis_event *event);

/**
 * For an event of type @ref EIS_EVENT_POINTER_BUTTON return the button
 * code as defined in linux/input-event-codes.h
 */
uint32_t
eis_event_pointer_get_button(struct eis_event *event);

/**
 * For an event of type @ref EIS_EVENT_POINTER_BUTTON return true if the
 * event is a button press, false for a release.
 */
bool
eis_event_pointer_get_button_is_press(struct eis_event *event);

/**
 * For an event of type @ref EIS_EVENT_POINTER_SCROLL return the x scroll
 * distance in logical pixels.
 */
double
eis_event_pointer_get_scroll_x(struct eis_event *event);

/**
 * For an event of type @ref EIS_EVENT_POINTER_SCROLL return the y scroll
 * distance in logical pixels.
 */
double
eis_event_pointer_get_scroll_y(struct eis_event *event);

/**
 * For an event of type @ref EIS_EVENT_POINTER_SCROLL_DISCRETE return the x
 * scroll distance in fractions or multiples of 120.
 */
int32_t
eis_event_pointer_get_scroll_discrete_x(struct eis_event *event);

/**
 * For an event of type @ref EIS_EVENT_POINTER_SCROLL_DISCRETE return the y
 * scroll distance in fractions or multiples of 120.
 */
int32_t
eis_event_pointer_get_scroll_discrete_y(struct eis_event *event);

/**
 * For an event of type @ref EIS_EVENT_KEYBOARD_KEY return the key code (as
 * defined in include/linux/input-event-codes.h).
 */
uint32_t
eis_event_keyboard_get_key(struct eis_event *event);

/**
 * For an event of type @ref EIS_EVENT_KEYBOARD_KEY return true if the
 * event is a key down, false for a release.
 */
bool
eis_event_keyboard_get_key_is_press(struct eis_event *event);

/**
 * For an event of type @ref EIS_EVENT_TOUCH_DOWN, @ref
 * EIS_EVENT_TOUCH_MOTION, or @ref EIS_EVENT_TOUCH_UP, return the tracking
 * ID of the touch.
 *
 * The tracking ID is a unique identifier for a touch and is valid from
 * touch down through to touch up but may be re-used in the future.
 * The tracking ID is randomly assigned to a touch, a client
 * must not expect any specific value.
 */
uint32_t
eis_event_touch_get_id(struct eis_event *event);

/**
 * For an event of type @ref EIS_EVENT_TOUCH_DOWN, or @ref
 * EIS_EVENT_TOUCH_MOTION, return the x coordinate of the touch.
 */
double
eis_event_touch_get_x(struct eis_event *event);

/**
 * For an event of type @ref EIS_EVENT_TOUCH_DOWN, or @ref
 * EIS_EVENT_TOUCH_MOTION, return the y coordinate of the touch.
 */
double
eis_event_touch_get_y(struct eis_event *event);