First commit

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 566 insertions, 0 deletions

diff --git a/libgamepad.h b/libgamepad.h
new file mode 100644
index 0000000..627589a
--- /dev/null
+++ b/libgamepad.h
@@ -0,0 +1,566 @@
+/* See LICENSE file for copyright and license details. */
+#ifndef LIBGAMEPAD_H
+#define LIBGAMEPAD_H
+
+#include <errno.h>
+#include <fcntl.h>
+#include <stdint.h>
+#include <stddef.h>
+#include <time.h>
+
+#include <libevdev/libevdev.h>
+
+
+/**
+ * Opaque structure for monitoring device attachment changes
+ */
+typedef struct libgamepad_attachment_monitor LIBGAMEPAD_ATTACHMENT_MONITOR;
+
+
+/**
+ * Device attachment event type
+ */
+enum libgamepad_attachment_event_type {
+	/**
+	 * Device has been added
+	 */
+	LIBGAMEPAD_ADDED,
+
+	/**
+	 * Device has been removed
+	 */
+	LIBGAMEPAD_REMOVED
+};
+
+
+/**
+ * Device type
+ *
+ * A device can have any number of these applied to
+ * it, it may also have unknown types beyond these
+ */
+enum libgamepad_type {
+	/**
+	 * Gamepad, joystick, steering wheel, or similar
+	 */
+	LIBGAMEPAD_GAMEPAD = 0x0001,
+
+	/**
+	 * Computer mouse
+	 */
+	LIBGAMEPAD_MOUSE = 0x0002
+};
+
+
+/**
+ * Gamepad input type
+ */
+enum libgamepad_input_type {
+	/**
+	 * Button/key
+	 */
+	LIBGAMEPAD_BUTTON,
+
+	/**
+	 * Absolute axis
+	 */
+	LIBGAMEPAD_ABSOLUTE_AXIS,
+
+	/**
+	 * Relative axis
+	 */
+	LIBGAMEPAD_RELATIVE_AXIS
+};
+
+
+/**
+ * Subdevice input event structure
+ */
+struct libgamepad_input_event {
+	/**
+	 * The affect input type
+	 */
+	enum libgamepad_input_type type;
+
+	/**
+	 * Whether the event was polled in a
+	 * synchronisation read
+	 */
+	short int sync_event;
+
+	/**
+	 * The button/key or axis affect by the event
+	 */
+	uint16_t code;
+
+	/**
+	 * The new value on the button/key or axis,
+	 * or the delta if on a relative axis
+	 */
+	int32_t value;
+
+	/**
+	 * Event timestamp
+	 */
+	struct timeval time;
+};
+
+
+/**
+ * Subdevice on a device
+ * 
+ * For example a modern gamepad may be split into
+ * a gamepad, computer mouse, and motion sensor
+ *
+ * Structure is always deallocated by the library
+ * using free(3)
+ */
+struct libgamepad_subdevice {
+	/**
+	 * Device type
+	 */
+	enum libgamepad_type type;
+
+	/**
+	 * Device path
+	 */
+	char path[];
+};
+
+
+/**
+ * Physical device
+ * 
+ * Contents of structure is deallocated with
+ * `libgamepad_close_superdevice`
+ */
+struct libgamepad_superdevice {
+	/**
+	 * Device path in /sys
+	 */
+	char *syspath;
+
+	/**
+	 * Number of subdevices
+	 */
+	size_t ndevices;
+
+	/**
+	 * Subdevices
+	 */
+	struct libgamepad_subdevice **devices;
+
+	/**
+	 * Number of LEDs
+	 */
+	size_t nleds;
+
+	/**
+	 * Paths to LEDs
+	 */
+	char **leds;
+
+	/**
+	 * Number of power supplies (batteries)
+	 */
+	size_t npower_supplies;
+
+	/**
+	 * Paths of power supplies (batteries)
+	 */
+	char **power_supplies;
+};
+
+
+/**
+ * Subdevice structure for detailed information listening on input events
+ */
+struct libgamepad_device {
+	/**
+	 * File descriptor to the device, the application
+	 * may use it to poll for read-readyness
+	 */
+	int fd;
+
+	/**
+	 * Bus type the device is connect via, see BUS_-prefixed
+	 * constants in <linux/input.h>
+	 */
+	int bus_type;
+
+	/**
+	 * Vendor ID for the device (sub- or superdevice)
+	 */
+	int vendor;
+
+	/**
+	 * Product ID for the device (sub- or superdevice)
+	 */
+	int product;
+
+	/**
+	 * Product version ID for the device (sub- or superdevice)
+	 */
+	int version;
+
+	/**
+	 * FOR INTERNAL USE
+	 * 
+	 * Specifies whether `.fd` shall be closed with the device
+	 */
+	int close_fd;
+
+	/**
+	 * FOR INTERNAL USE
+	 * 
+	 * Whether the device must be synchronised
+	 */
+	int require_sync;
+
+	/**
+	 * Human-readable device (sub- or superdevice) name
+	 */
+	const char *name;
+
+	/**
+	 * ID that is supposted to be unique to the device
+	 * (sub- or superdevice)
+	 */
+	const char *unique_id;
+
+	/**
+	 * The location if the device
+	 */
+	const char *physical_location;
+
+	/**
+	 * libevdev instance for the device
+	 */
+	struct libevdev *dev;
+
+	/**
+	 * Number of (digital) buttons/keys present
+	 * on the device
+	 */
+	size_t nbuttons;
+
+	/**
+	 * Number of absolute axes present on the device
+	 */
+	size_t nabsolute_axes;
+
+	/**
+	 * Number of relative axes present on the device
+	 */
+	size_t nrelative_axes;
+
+	/**
+	 * Maps from button/key codes to button indices,
+	 * non-present buttons/keys map to -1, other
+	 * values are in [0, `.nbuttons`[.
+	 */
+	int16_t button_map[KEY_CNT];
+
+	/**
+	 * Maps from absolute axis codes to absolute axis
+	 * indices, non-present axes map to -1, other
+	 * values are in [0, `.nabsolute_axes`[.
+	 */
+	int16_t absolute_axis_map[ABS_CNT];
+
+	/**
+	 * Maps from relative axis codes to absolute axis
+	 * indices, non-present axes map to -1, other
+	 * values are in [0, `.nrelative_axes`[.
+	 */
+	int16_t relative_axis_map[REL_CNT];
+
+	/**
+	 * Map from button/key indices to button/key codes
+	 */
+	uint16_t *buttons;
+
+	/**
+	 * Map from absolute axis indices to absolute axis codes
+	 */
+	uint16_t *absolute_axes;
+
+	/**
+	 * Map from relative axis indices to relative axis codes
+	 */
+	uint16_t *relative_axes;
+};
+
+
+/**
+ * Get a list of all available physical devices
+ * 
+ * @param   devicesp   Output parameter for the list of devices
+ * @param   ndevicesp  Output parameter for the number of listed devices
+ * @return             0 on success, -1 on failure
+ * 
+ * This function may fail for any reason specified for
+ * realloc(3), open(3), fdopendir(3), or readdir(3)
+ */
+int libgamepad_list_superdevices(char ***, size_t *);
+
+/**
+ * Get information about a physical device
+ * 
+ * @param   devicep  Output parameter for the device information,
+ *                   allocated memory shall be deallocated with
+ *                   `libgamepad_close_superdevice(devicep)`
+ * @param   syspath  The path of the device, in /sys
+ * @return           0 on success, -1 on failure
+ * 
+ * This function may fail for any reason specified for
+ * realloc(3), openat(3), fdopendir(3), or readdir(3)
+ */
+int libgamepad_open_superdevice(struct libgamepad_superdevice *, const char *);
+
+/**
+ * Deallocate the contents of a `struct libgamepad_superdevice`
+ * 
+ * @param  device  The structure whose nested memory allocations
+ *                 shall be deallocated, may be `NULL`
+ */
+void libgamepad_close_superdevice(struct libgamepad_superdevice *);
+
+
+/**
+ * Create a device attachment monitor
+ * 
+ * The user shall poll the returned file descriptor
+ * for read-readiness, and whenever it is ready,
+ * call `libgamepad_get_attachment_event`
+ * 
+ * @param   monitorp  Output parameter for the monitor, shall deallocated with
+ *                    `libgamepad_destroy_attachment_monitor` when no longer used
+ * @return            A file descriptor on successful completion, -1 on failure
+ *
+ * This function may fail for any reason specified by
+ * malloc(3), udev_new(3), udev_monitor_new_from_netlink(3), or
+ * udev_monitor_enable_receiving(3)
+ */
+int libgamepad_create_attachment_monitor(LIBGAMEPAD_ATTACHMENT_MONITOR **);
+
+/**
+ * Deallocate a device attachment monitor
+ * 
+ * @param  monitor  The monitor to deallocate; the file descriptor returned
+ *                  with it will also be closed and become invalid, may be `NULL`
+ */
+void libgamepad_destroy_attachment_monitor(LIBGAMEPAD_ATTACHMENT_MONITOR *);
+
+/**
+ * Get the next device attachment event
+ * 
+ * @param   monitor   Monitor created with `libgamepad_create_attachment_monitor`
+ * @param   syspathp  Pointer to output buffer for the device's path in /sys;
+ *                    the buffer may be reallocated by the function
+ * @param   sizep     Pointer to the allocation size of `*syspath`; may be
+ *                    updated by the function
+ * @param   typep     Output parameter for the attachment event type; in the
+ *                    event that this value is set to `LIBGAMEPAD_REMOVED`, the
+ *                    device is not necessarily on supported by this library
+ * @return            1 on success, 0 if the received event was suppressed
+ *                    by the library, -1 on failure
+ * 
+ * This function may fail for any reason specified for
+ * realloc(3) or udev_monitor_receive_device(3); notable,
+ * this function may set `errno` to `EAGAIN` or `EINTR`
+ */
+int libgamepad_get_attachment_event(LIBGAMEPAD_ATTACHMENT_MONITOR *, char **, size_t *, enum libgamepad_attachment_event_type *);
+
+
+/**
+ * Open a subdevice
+ * 
+ * @param   devicep  Output parameter for the device information and handles;
+ *                   deallocated with `libgamepad_close_device`
+ * @param   dirfd    File descriptor to path that `path` is relative to
+ *                   (unless it is an absolute path), or `AT_FDCWD` for the
+ *                   current working directory
+ * @param   path     The path to the device, if `NULL` or empty, `dirfd`
+ *                   will be used as the file descriptor to the device,
+ *                   in which case the application must keep it open until
+ *                   the device is closed, and then close it manually, and
+ *                   `mode` is ignored
+ * @param   mode     Mode to open the device in, normally `O_RDONLY`,
+ *                   `O_RDONLY|O_NONBLOCK`, `O_RDWR`, or `O_RDWR|O_NONBLOCK`
+ * @return           0 on success, -1 on failure
+ * 
+ * This function may fail for any reason specified for
+ * malloc(3), openat(3) or libevdev_new_from_fd(3)
+ */
+int libgamepad_open_device(struct libgamepad_device *, int, const char *, int);
+
+/**
+ * Close a subdevice
+ * 
+ * @param  device  Device information and handles, may be `NULL`
+ */
+void libgamepad_close_device(struct libgamepad_device *);
+
+/**
+ * Get the next event on a subdevice
+ * 
+ * NB! events may be queued internally (by libevdev), therefore
+ * an application must either call this function in a loop in
+ * its own thread, or have the device opened in non-blocking
+ * mode and even the poll the device's file descriptor for
+ * read-readyness and when it is ready clal this function in
+ * a loop until it sets `errno` to `EAGAIN`.
+ * 
+ * @param   device  Device to read an event from
+ * @param   eventp  Output parameter for the event
+ * @return          1 if an event was returned,
+ *                  0 if no event was returned,
+ *                  -1 on failure
+ * 
+ * This function may fail for any reason specified for
+ * libevdev_next_event(3), including:
+ * -  EAGAIN  no more data currently available (non-blocking mode)
+ * -  EINTR   system call was interrupted, try again
+ * -  ENODEV  device has been unplugged
+ */
+int libgamepad_next_event(struct libgamepad_device *, struct libgamepad_input_event *);
+
+
+/**
+ * Get the name of a button/key
+ * 
+ * @param   code  The button/key
+ * @return        The button/key's name
+ */
+inline const char *
+libgamepad_get_button_name(unsigned int code)
+{
+	return libevdev_event_code_get_name(EV_KEY, code);
+}
+
+/**
+ * Get the name of an absolute axis
+ * 
+ * @param   code  The axis
+ * @return        The axis' name
+ */
+inline const char *
+libgamepad_get_absolute_axis_name(unsigned int code)
+{
+	return libevdev_event_code_get_name(EV_ABS, code);
+}
+
+/**
+ * Get the name of a relative axis
+ * 
+ * @param   code  The axis
+ * @return        The axis' name
+ */
+inline const char *
+libgamepad_get_relative_axis_name(unsigned int code)
+{
+	return libevdev_event_code_get_name(EV_REL, code);
+}
+
+/**
+ * Get whether a button/key is pressed down or not
+ *
+ * @param   device  The device to retrieve the information for
+ * @param   code    The button/key
+ * @return          1 if the button/key is pressed down,
+ *                  0 otherwise
+ */
+inline int
+libgamepad_get_button_is_pressed(struct libgamepad_device *device, unsigned int code)
+{
+	return libevdev_get_event_value(device->dev, EV_KEY, code);
+}
+
+/**
+ * Get information about an absolute axis
+ *
+ * @param   device  The device to retrieve the information for
+ * @param   code    The axis
+ * @return          Information about the axis
+ */
+inline const struct input_absinfo * /* `struct input_absinfo` is defined in <linux/input.h> */
+libgamepad_get_absolute_axis_info(struct libgamepad_device *device, unsigned int code)
+{
+	return libevdev_get_abs_info(device->dev, code);
+}
+
+
+/**
+ * Grab a subdevice, if not already grabbed
+ *
+ * This is supposed to block out clients from
+ * retrieving events for the device, but it
+ * does not necessarily stop them from reading
+ * the device state
+ * 
+ * @param   device  The device to grab
+ * @return          0 on success, -1 on failure
+ * 
+ * May fail for any reason specified for libevdev_grab(3)
+ * with LIBEVDEV_GRAB applied
+ * 
+ * In the event that the device is already grabbed by
+ * via another file descriptor (duplicates do not share
+ * grab), this function will return -1 and set `errno`
+ * to `EBUSY`
+ */
+inline int
+libgamepad_grab(struct libgamepad_device *device)
+{
+	int err = libevdev_grab(device->dev, LIBEVDEV_GRAB);
+	if (err < 0) {
+		errno = -err;
+		return -1;
+	}
+	return 0;
+}
+
+/**
+ * Ungrab a subdevice, unless not currently grabbed
+ * 
+ * @param   device  The device to ungrab
+ * @return          0 on success, -1 on failure
+ * 
+ * May fail for any reason specified for libevdev_grab(3)
+ * with LIBEVDEV_UNGRAB applied
+ */
+inline int
+libgamepad_ungrab(struct libgamepad_device *device)
+{
+	int err = libevdev_grab(device->dev, LIBEVDEV_UNGRAB);
+	if (err < 0) {
+		errno = -err;
+		return -1;
+	}
+	return 0;
+}
+
+
+/**
+ * Set the clock that event timestamps shall be reported in
+ * 
+ * @param   device   The device to configure
+ * @param   clockid  The clock to use on event timestamps
+ * @return           0 on success, -1 on failure
+ * 
+ * May fail for any reason specified for libevdev_set_clock_id(3)
+ */
+inline int
+libgamepad_set_clock(struct libgamepad_device *device, clockid_t clockid)
+{
+	int err = libevdev_set_clock_id(device->dev, clockid);
+	if (err < 0) {
+		errno = -err;
+		return -1;
+	}
+	return 0;
+}
+
+
+#endif