libei/src/libei.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 <stdbool.h>
#include <stdint.h>

struct ei_ctx;
struct ei_device;
struct ei_event;
struct ei_event_client;
struct ei_event_pointer;
struct ei_event_keyboard;
struct ei_event_touch;

enum ei_device_capability {
	EI_DEVICE_CAP_POINTER,
	EI_DEVICE_CAP_POINTER_ABSOLUTE,
	EI_DEVICE_CAP_KEYBOARD,
	EI_DEVICE_CAP_TOUCH,
};

enum ei_keymap_type {
	EI_KEYMAP_TYPE_XKB = 1,
};

enum ei_event_type {
	/**
	 * No event ever has this type, this type exists only as potential
	 * return value for ei_next_event_type().
	 */
	EI_EVENT_NONE = 0,
	/**
	 * The server has approved the connection to this client.
	 */
	EI_EVENT_CONNECT,
	/**
	 * The server has disconnected this client - all resources left to
	 * reference this server are now obsolete. Once this event has been
	 * received, the @ref struct ei_ctx and all its associated resources
	 * should be released.
	 */
	EI_EVENT_DISCONNECT,

	/**
	 * The server has added a device for this client. The capabilities
	 * of the device may not match the requested capabilities - it is up
	 * to the client to verify the minimum required capabilities are
	 * indeed set.
	 */
	EI_EVENT_DEVICE_ADDED,
	/**
	 * The server has removed a device belonging to this client.
	 */
	EI_EVENT_DEVICE_REMOVED,


	/**
	 * The client may send events.
	 */
	EI_EVENT_POINTER_RESUME = 300,
	/**
	 * Any events sent will be discarded until the next resume.
	 */
	EI_EVENT_POINTER_SUSPEND,
	/**
	 * Update pointer ranges. This provides the client with the allowed
	 * axis ranges for absolute pointer motion. The axis ranges may not
	 * match the available screen ranges and the axis range may only map
	 * to a portion of the available screen size.
	 */
	EI_EVENT_POINTER_RANGES_CHANGED,

	/**
	 * The client may send events.
	 */
	EI_EVENT_KEYBOARD_RESUME = 400,
	/**
	 * Any events sent will be discarded until the next resume.
	 */
	EI_EVENT_KEYBOARD_SUSPEND,
	/**
	 * Notification of the keymap to be used by the client.
	 */
	EI_EVENT_KEYBOARD_KEYMAP,

	/**
	 * The client may send events.
	 */
	EI_EVENT_TOUCH_RESUME = 500,
	/**
	 * Any events sent will be discarded until the next resume.
	 */
	EI_EVENT_TOUCH_SUSPEND,
	/**
	 * Update touch ranges. This provides the client with the allowed
	 * axis ranges for absolute pointer motion. The axis ranges may not
	 * match the available screen ranges and the axis range may only map
	 * to a portion of the available screen size.
	 */
	EI_EVENT_TOUCH_RANGES_CHANGED,
};

struct ei_ctx *
ei_new(void);

struct ei_ctx *
ei_ref(struct ei_ctx *ctx);

struct ei_ctx *
ei_unref(struct ei_ctx *ei);

/**
 * Connect to the libeis server via the org.freedesktop.portal
 *
 * @return 0 on success or a negative errno on failure
 */
int
ei_portal_connect(struct ei_ctx *ei);

/**
 * Connect to the libeis server on the org.freedesktop.Ei bus name.
 *
 * @return 0 on success or a negative errno on failure
 */
int
ei_dbus_connect(struct ei_ctx *ei);

int
ei_get_fd(struct ei_ctx *ei);

void
ei_dispatch(struct ei_ctx *ei);

struct ei_event *
ei_get_event(struct ei_ctx *ei);

enum ei_event_type
ei_next_event_type(struct ei_ctx *ei);

struct ei_event *
ei_event_unref(struct ei_event *event);

struct ei_device *
ei_device_ref(struct ei_device *device);

struct ei_device *
ei_device_unref(struct ei_device *device);

/**
 * Request the creation of a device with suggested capabilities and a
 * suggested name. Note that the server may ignore the name and may ignore
 * all capabilities.
 *
 * The device returned is a stub device maintained by the library and should
 * only used for initial device configuration. It does not represent the
 * server-created device until the @ref EI_EVENT_DEVICE_ADDED for this
 * device has been received.
 *
 * This does not increase the refcount of the device. Use ei_device_ref() to
 * keep a reference beyond the immediate scope.
 *
 * @param ei The context
 * @param capabilities A bitmask of @ref ei_device_capability
 * @param name A name suggestion for the device
 */
struct ei_device *
ei_create_device(struct ei_ctx *ei, uint32_t capabilities, const char *name);

/**
 * Request that the device be added to the server.
 * The server will respond with an @ref EI_EVENT_DEVICE_ADDED or @ref
 * EI_EVENT_DEVICE_REMOVED event.
 */
void
ei_device_add(struct ei_device *device);

/**
 * Notify the server that the device is no longer required. The server will
 * reply with a @ref EI_EVENT_DEVICE_REMOVED event once the device has been
 * removed.
 *
 * This does not release any resources associated with this device, use
 * ei_device_unref() for any references held by the client.
 */
void
ei_device_remove(struct ei_device *device);


/**
 * @return the name of the device (if any) or NULL
 */
const char *
ei_device_get_name(struct ei_device *device);

bool
ei_device_has_capability(struct ei_device *device,
			 enum ei_device_capability cap);

struct ei_ctx *
ei_device_get_context(struct ei_device *device);

/**
 * Generate a relative motion event on a device with
 * the @ref EI_DEVICE_CAP_POINTER capability.
 *
 * @param x The x movement in 1/1000th of a logical pixel
 * @param y The y movement in 1/1000th of a logical pixel
 */
void
ei_device_pointer_motion(struct ei_device *device, int32_t x, int32_t y);

/**
 * Generate an absolute motion event on a device with
 * the @ref EI_DEVICE_CAP_POINTER_ABSOLUTE capability.
 *
 * The required conditions are:
 * - 0 <= x < width
 * - 0 <= y < height
 *
 * @param x The x position in 1/1000th of a logical pixel
 * @param y The y position in 1/1000th of a logical pixel
 */
void
ei_device_pointer_motion_absolute(struct ei_device *device,
				  uint32_t x, uint32_t y);

/**
 * Generate a button event on a device with
 * the @ref EI_DEVICE_CAP_POINTER_ABSOLUTE or
 * @ref EI_DEVICE_CAP_POINTER capability.
 *
 * Buttons are merely sequentially numbered. It is up to the server to map
 * button numbers into semantic button codes (if any). A server may silently
 * ignore button events outside meaningful ranges.
 *
 * @param button A sequentially numbered button, starting at index 1
 * @param is_press true for button press, false for button release
 */
void
ei_device_pointer_button(struct ei_device *device,
			 uint32_t button, bool is_press);

/**
 * Generate a scroll event on a device with
 * the @ref EI_DEVICE_CAP_POINTER_ABSOLUTE or
 * @ref EI_DEVICE_CAP_POINTER capability.
 *
 * The server emulates discrete scrolling based on the pixel value,
 * do not call ei_device_pointer_scroll_discrete() for the
 * same input event.
 *
 * @param x The x scroll distance in 1/1000th of a logical pixel
 * @param y The y scroll distance in 1/1000th of a logical pixel
 *
 * @see ei_device_pointer_scroll_discrete
 */
void
ei_device_pointer_scroll(struct ei_device *device, int32_t x, int32_t y);

/**
 * Generate a discrete scroll event on a device with
 * the @ref EI_DEVICE_CAP_POINTER_ABSOLUTE or
 * @ref EI_DEVICE_CAP_POINTER capability.
 *
 * A discrete scroll event is based logical scroll units (equivalent to one
 * mouse wheel click). The value for one scroll unit is 120, a fraction or
 * multiple thereof represents a fraction or multiple of a wheel click.
 *
 * The server emulates pixel-based scrolling based on the discrete value,
 * do not call ei_device_pointer_scroll() for the
 * same input event.
 *
 * @param x The x scroll distance in fractions or multiples of 120
 * @param y The y scroll distance in fractions or multiples of 120
 *
 * @see ei_device_pointer_scroll
 */
void
ei_device_pointer_scroll_discrete(struct ei_device *device, int32_t x, int32_t y);

/**
 * Generate a key event on a device with
 * the @ref EI_DEVICE_CAP_KEYBOARD capability.
 *
 * Keys use the evdev scan codes as defined in
 * linux/input-event-codes.h
 *
 * @param keycode The key code
 * @param is_press true for key down, false for key up
 */
void
ei_device_keyboard_key(struct ei_device *device, uint32_t keycode, bool is_press);


/**
 * Set the keymap on the device. This function has no effect if called
 * after ei_device_add(). The keymap for this device is a suggestion to
 * the server, the actual keymap used by this device is provided with
 * the @ref EI_EVENT_KEYBOARD_KEYMAP event.
 *
 * @param type the type of the keymap
 * @param fd a memmap-able file descriptor to the keymap
 */
void
ei_device_keyboard_set_keymap(struct ei_device *device,
			      enum ei_keymap_type type,
			      int fd);

/**
 * 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 ei_device *
ei_event_get_device(struct ei_event *event);


/**
 * @return the event time in microseconds
 */
uint64_t
ei_event_pointer_get_time(struct ei_event_pointer *event);

/**
 * For an event of type @ref EI_EVENT_POINTER_RANGES_CHANGED, this function
 * defines the allowable range for x - 0 (inclusive) to width (exclusive).
 *
 * The value is in 1/1000th of logical pixels, i.e. the value 1000 000
 * refers to 1000 pixels.
 *
 * It is a client bug to send pointer values outside this range.
 *
 * If the touch range changes at runtime, an event of @ref
 * EI_EVENT_POINTER_RANGES_CHANGED is generated.
 */
uint32_t
ei_event_pointer_get_width(struct ei_event_pointer *event);

/**
 * @see ei_event_pointer_get_width
 */
uint32_t
ei_event_pointer_get_height(struct ei_event_pointer *event);

/**
 * @return the event time in microseconds
 */
uint64_t
ei_event_keyboard_get_time(struct ei_event_keyboard *event);

/**
 * For an event of type @ref EI_EVENT_TOUCH_RANGES_CHANGED, this function
 * defines the allowable range for x - 0 (inclusive) to width (exclusive).
 *
 * The value is in 1/1000th of logical pixels, i.e. the value 1000 000
 * refers to 1000 pixels.
 *
 * It is a client bug to send touch values outside this range.
 *
 * If the touch range changes at runtime, an event of @ref
 * EI_EVENT_TOUCH_RANGES_CHANGED is generated.
 */
uint32_t
ei_event_touch_get_width(struct ei_event_touch *event);

/**
 * @see ei_event_touch_get_width
 */
uint32_t
ei_event_touch_get_height(struct ei_event_touch *event);

/**
 * @return the event time in microseconds
 */
uint64_t
ei_event_touch_get_time(struct ei_event_touch *event);

/**
 * For an event of type @ref EI_EVENT_KEYBOARD_KEYMAP return the
 * type of the keyamp.
 */
enum ei_keymap_type
ei_event_keyboard_get_keymap_type(struct ei_event_keyboard *kbdev);

/**
 * For an event of type @ref EI_EVENT_KEYBOARD_KEYMAP return the
 * memmap-able file descriptor to the keymap.
 */
int
ei_event_keyboard_get_keymap(struct ei_event_keyboard *kbdev);