fdo-mirrors/libevdev
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libevdev/libevdev.git synced 2025-12-24 15:50:08 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Documentation fixes

Browse source 
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer 2013-06-22 19:44:03 +10:00
parent 479e16725d
commit 960dc91844
1 changed files with 76 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

122
libevdev/libevdev.h
View file

@ -79,17 +79,44 @@
* Abstraction functions to handle device capabilities, specificially
* device propeties such as the name of the device and the bits
* representing the events suppported by this device.
*
* The logical state returned may lag behind the physical state of the device.
* libevdev queries the device state on libevdev_set_fd() and then relies on
* the caller to parse events through libevdev_next_fd(). If a caller does not
* use libevdev_next_fd(), libevdev will not update the internal state of the
* device and thus returns outdated values.
*/
/**
* @defgroup mt Multi-touch related functions
* Functions for querying multi-touch-related capabilities.
* Functions for querying multi-touch-related capabilities. MT devices
* following the kernel protocol B (using ABS_MT_SLOT) provide multiple touch
* points through so-called slots on the same axis. The slots are enumerated,
* a client reading from the device will first get an ABS_MT_SLOT event, then
* the values of axes changed in this slot. Multiple slots may be provided in
* before an EV_SYN event.
*
* As with @ref bits, the logical state of the device as seen by the library
* depends on the caller using libevdev_next_event().
*/
/**
* @defgroup kernel Modifying the appearance or capabilities of the device
*
* Modifying the set of events reported by this device.
* Modifying the set of events reported by this device. By default, the
* libevdev device mirrors the kernel device, enabling only those bits
* exported by the kernel. This set of functions enable or disable bits as
* seen from the caller.
*
* Enabling an event type or code does not affect event reporting - a
* software-enabled event will not be generated by the physical hardware.
* Disabling an event will prevent libevdev from routing such events to the
* caller. Enabling and disabling event types and codes is at the library
* level and thus only affects the caller.
*
* If an event type or code is enabled at kernel-level, future users of this
* device will see this event enabled. Currently there is no option of
* disabling an event type or code at kernel-level.
*/
/**
@ -136,11 +163,11 @@ struct libevdev* libevdev_new(void);
*
* This is a shortcut for
*
* <pre>
* @code
* int err;
* struct libevdev *dev = libevdev_new();
* err = libevdev_set_fd(dev, fd);
* </pre>
* @endcode
*
* @param fd A file descriptor to the device in O_RDWR or O_RDONLY mode.
*
@ -176,7 +203,7 @@ typedef void (*libevdev_log_func_t)(const char *format, va_list args);
/**
* Set a printf-style logging handler for library-internal logging.
*
* @note This function may be called before libevdev_set_fd.
* @note This function may be called before libevdev_set_fd().
*/
void libevdev_set_log_handler(struct libevdev *dev, libevdev_log_func_t logfunc);
@ -251,7 +278,7 @@ int libevdev_change_fd(struct libevdev* dev, int fd);
/**
*
* @return The previously set fd, or -1 if none had been set previously.
* @note This function may be called before libevdev_set_fd.
* @note This function may be called before libevdev_set_fd().
*/
int libevdev_get_fd(const struct libevdev* dev);
@ -287,7 +314,8 @@ int libevdev_next_event(struct libevdev *dev, unsigned int flags, struct input_e
/**
* @ingroup bits
*
* @return The device name as read off the kernel device
* @return The device name as read off the kernel device. The name is never
* NULL but it may be the empty string.
*
* @note This function is signal-safe.
*/
@ -361,7 +389,7 @@ int libevdev_get_driver_version(const struct libevdev *dev);
/**
* @ingroup bits
*
* @return 1 if the device supports this event type, or 0 otherwise.
* @return 1 if the device provides this input property, or 0 otherwise.
*
* @note This function is signal-safe
*/
@ -379,7 +407,7 @@ int libevdev_has_event_type(const struct libevdev *dev, unsigned int type);
/**
* @ingroup bits
*
* @return 1 if the device supports this event type, or 0 otherwise.
* @return 1 if the device supports this event type and code, or 0 otherwise.
*
* @note This function is signal-safe.
*/
@ -434,7 +462,7 @@ const struct input_absinfo* libevdev_get_abs_info(const struct libevdev *dev, un
*
* @note This function is signal-safe.
* @note The value for ABS_MT_ events is undefined, use
* libevdev_get_slot_value instead
* libevdev_get_slot_value() instead
*
* @see libevdev_get_slot_value
*/
@ -445,17 +473,18 @@ int libevdev_get_event_value(const struct libevdev *dev, unsigned int type, unsi
*
* Fetch the current value of the event type. This is a shortcut for
*
* <pre>
* @code
* if (libevdev_has_event_type(dev, t) && libevdev_has_event_code(dev, t, c))
* val = libevdev_get_event_value(dev, t, c);
* </pre>
* @endcode
*
* @return non-zero if the device supports this event code, or zero
* otherwise. On return of zero, value is unmodified.
* @return If the device supports this event type and code, the return value is
* non-zero and value is set to the current value of this axis. Otherwise,
* zero is returned and value is unmodified.
*
* @note This function is signal-safe.
* @note The value for ABS_MT_ events is undefined, use
* libevdev_fetch_slot_value instead
* libevdev_fetch_slot_value() instead
*
* @see libevdev_fetch_slot_value
*/
@ -467,11 +496,12 @@ int libevdev_fetch_event_value(const struct libevdev *dev, unsigned int type, un
* Return the current value of the code for the given slot.
*
* The return value is undefined for a slot exceeding the available slots on
* the device, or for a device that does not have slots.
* the device, for a code that is not in the permitted ABS_MT range or for a
* device that does not have slots.
*
* @note This function is signal-safe.
* @note The value for events other than ABS_MT_ is undefined, use
* libevdev_fetch_value instead
* libevdev_fetch_value() instead
*
* @see libevdev_get_value
*/
@ -482,21 +512,19 @@ int libevdev_get_slot_value(const struct libevdev *dev, unsigned int slot, unsig
*
* Fetch the current value of the code for the given slot. This is a shortcut for
*
* <pre>
* @code
* if (libevdev_has_event_type(dev, EV_ABS) &&
* libevdev_has_event_code(dev, EV_ABS, c) &&
* slot < device->number_of_slots)
* val = libevdev_get_slot_value(dev, slot, c);
* </pre>
* @endcode
*
* @return non-zero if the device supports this event code, or zero
* otherwise. On return of zero, value is unmodified.
* @return If the device supports this event code, the return value is
* non-zero and value is set to the current value of this axis. Otherwise, or
* if the event code is not an ABS_MT_* event code, zero is returned and value
* is unmodified.
*
* @note This function is signal-safe.
* @note The value for ABS_MT_ events is undefined, use
* libevdev_fetch_slot_value instead
*
* @see libevdev_fetch_slot_value
*/
int libevdev_fetch_slot_value(const struct libevdev *dev, unsigned int slot, unsigned int code, int *value);
@ -508,7 +536,8 @@ int libevdev_fetch_slot_value(const struct libevdev *dev, unsigned int slot, uns
* Note that the slot offset may be non-zero, use libevdev_get_abs_min() or
* libevdev_get_abs_info() to get the minimum slot number.
*
* @return The number of slots supported, or -1
* @return The number of slots supported, or -1 if the device does not provide
* any slots
*/
int libevdev_get_num_slots(const struct libevdev *dev);
@ -530,9 +559,9 @@ int libevdev_get_current_slot(const struct libevdev *dev);
*
* Forcibly enable an event type on this device, even if the underlying
* device does not support it. While this cannot make the device actually
* report such events, it will now return true for libevdev_has_event_type.
* report such events, it will now return true for libevdev_has_event_type().
*
* This is a local modification only affecting only this process and only
* This is a local modification only affecting only this representation of
* this device.
*
* @param type The event type to enable (EV_ABS, EV_KEY, ...)
@ -549,15 +578,15 @@ int libevdev_enable_event_type(struct libevdev *dev, unsigned int type);
* Forcibly disable an event type on this device, even if the underlying
* device provides it, effectively muting all keys or axes. libevdev will
* filter any events matching this type and none will reach the caller.
* libevdev_has_event_type will return false for this type.
* libevdev_has_event_type() will return false for this type.
*
* In most cases, a caller likely only wants to disable a single code, not
* the whole type. Use libevdev_disable_event_code for that.
* the whole type. Use libevdev_disable_event_code() for that.
*
* This is a local modification only affecting only this process and only
* This is a local modification only affecting only this representation of
* this device.
*
* @param type The event type to enable (EV_ABS, EV_KEY, ...)
* @param type The event type to disable (EV_ABS, EV_KEY, ...)
*
* @return 0 on success or -1 otherwise
*
@ -571,16 +600,16 @@ int libevdev_disable_event_type(struct libevdev *dev, unsigned int type);
*
* Forcibly enable an event type on this device, even if the underlying
* device does not support it. While this cannot make the device actually
* report such events, it will now return true for libevdev_has_event_code.
* report such events, it will now return true for libevdev_has_event_code().
*
* The last argument depends on the type and code:
* - If type is EV_ABS, the vararg must be a pointer to a struct input_absinfo
* containing the data for this axis.
* - For all other types, the argument is ignored.
*
* This function calls libevdev_enable_event_type if necessary.
* This function calls libevdev_enable_event_type() if necessary.
*
* This is a local modification only affecting only this process and only
* This is a local modification only affecting only this representation of
* this device.
*
* @param type The event type to enable (EV_ABS, EV_KEY, ...)
@ -600,16 +629,16 @@ int libevdev_enable_event_code(struct libevdev *dev, unsigned int type, unsigned
* device provides it, effectively muting this key or axis. libevdev will
* filter any events matching this type and code and none will reach the
* caller.
* libevdev_has_event_code will return false for this code combination.
* libevdev_has_event_code() will return false for this code combination.
*
* Disabling all event codes for a given type will not disable the event
* type. Use libevdev_disable_event_type for that.
* type. Use libevdev_disable_event_type() for that.
*
* This is a local modification only affecting only this process and only
* This is a local modification only affecting only this representation of
* this device.
*
* @param type The event type to enable (EV_ABS, EV_KEY, ...)
* @param code The event code to enable (ABS_X, REL_X, etc.)
* @param type The event type to disable (EV_ABS, EV_KEY, ...)
* @param code The event code to disable (ABS_X, REL_X, etc.)
*
* @return 0 on success or -1 otherwise
*
@ -624,17 +653,16 @@ int libevdev_disable_event_code(struct libevdev *dev, unsigned int type, unsigne
*
* Forcibly enable an event type on this device, even if the underlying
* device does not support it. While this cannot make the device actually
* report such events, it will now return true for libevdev_has_event_code.
* report such events, it will now return true for libevdev_has_event_code().
*
* This will be written to the kernel.
*
* This cannot be undone, the kernel only allows to enable axes, not disable
* them.
*
* This function calls libevdev_kernel_enable_event_type if necessary.
* This function calls libevdev_kernel_enable_event_type() if necessary.
*
* @param type The event type to enable (EV_ABS, EV_KEY, ...)
* @param code The event code to enable (ABS_X, REL_X, etc.)
*/
int libevdev_kernel_enable_event_type(struct libevdev *dev, unsigned int type);
@ -643,14 +671,14 @@ int libevdev_kernel_enable_event_type(struct libevdev *dev, unsigned int type);
*
* Forcibly enable an event code on this device, even if the underlying
* device does not support it. While this cannot make the device actually
* report such events, it will now return true for libevdev_has_event_code.
* report such events, it will now return true for libevdev_has_event_code().
*
* This will be written to the kernel.
*
* This cannot be undone, the kernel only allows to enable axes, not disable
* them.
*
* This function calls libevdev_kernel_enable_event_type if necessary.
* This function calls libevdev_kernel_enable_event_type() if necessary.
*
* @param type The event type to enable (EV_ABS, EV_KEY, ...)
* @param code The event code to enable (ABS_X, REL_X, etc.)
@ -699,7 +727,7 @@ const char * libevdev_get_event_code_name(unsigned int type, unsigned int code);
* @note The list of names is compiled into libevdev. If the kernel adds new
* defines for new properties libevdev will not automatically pick these up.
* @note On older kernels input properties may not be defined and
* libevdev_get_input_prop_name will always return NULL
* libevdev_get_input_prop_name() will always return NULL
*/
const char * libevdev_get_input_prop_name(unsigned int prop);
@ -723,6 +751,8 @@ int libevdev_get_event_type_max(unsigned int type);
* @param period If not null, set to the repeat period value
*
* @return 0 on success, -1 if this device does not have repeat settings.
*
* @note This function is signal-safe
*/
int libevdev_get_repeat(struct libevdev *dev, int *delay, int *period);