libei 1.3.0
A library for Emulated Input
|
Data Structures | |
struct | oeffis |
The main context to interact with liboeffis. More... | |
Enumerations | |
enum | oeffis_device { OEFFIS_DEVICE_ALL_DEVICES , OEFFIS_DEVICE_KEYBOARD , OEFFIS_DEVICE_POINTER , OEFFIS_DEVICE_TOUCHSCREEN } |
The bitmask of devices to request. More... | |
enum | oeffis_event_type { OEFFIS_EVENT_NONE , OEFFIS_EVENT_CONNECTED_TO_EIS , OEFFIS_EVENT_CLOSED , OEFFIS_EVENT_DISCONNECTED } |
Functions | |
struct oeffis * | oeffis_new (void *user_data) |
Create a new oeffis context. | |
struct oeffis * | oeffis_ref (struct oeffis *oeffis) |
Increase the refcount of this struct by one. | |
struct oeffis * | oeffis_unref (struct oeffis *oeffis) |
Decrease the refcount of this struct by one. | |
void | oeffis_set_user_data (struct oeffis *oeffis, void *user_data) |
Set a custom data pointer for this context. | |
void * | oeffis_get_user_data (struct oeffis *oeffis) |
Return the custom data pointer for this context. | |
int | oeffis_get_fd (struct oeffis *oeffis) |
liboeffis keeps a single file descriptor for all events. | |
int | oeffis_get_eis_fd (struct oeffis *oeffis) |
Get a dup() of the file descriptor. | |
void | oeffis_create_session (struct oeffis *oeffis, uint32_t devices) |
Connect this oeffis instance to a RemoteDesktop session with the given device mask selected. | |
void | oeffis_create_session_on_bus (struct oeffis *oeffis, const char *busname, uint32_t devices) |
See oeffis_create_session() but this function allows to specify the busname to connect to. | |
void | oeffis_dispatch (struct oeffis *oeffis) |
Process pending events. | |
enum oeffis_event_type | oeffis_get_event (struct oeffis *oeffis) |
Return the next available event, if any. | |
const char * | oeffis_get_error_message (struct oeffis *oeffis) |
If the session was OEFFIS_EVENT_DISCONNECTED, return the error message that caused the disconnection. | |
liboeffis is a helper library for applications that do not want to or cannot interact with the XDG RemoteDesktop DBus portal directly.
liboeffis will:
org.freedesktop.portal.Desktop
bus nameorg.freedesktop.portal.RemoteDesktop
session, select the devices and invoke RemoteDesktop.ConnectToEIS()
liboeffis is intentionally kept simple, any more complex needs should be handled by an application talking to DBus directly.
enum oeffis_device |
The bitmask of devices to request.
This bitmask matches the devices bitmask in the XDG RemoteDesktop portal.
enum oeffis_event_type |
void oeffis_create_session | ( | struct oeffis * | oeffis, |
uint32_t | devices ) |
Connect this oeffis instance to a RemoteDesktop session with the given device mask selected.
This initiates the DBus communication, starts a RemoteDesktop session and selects the devices. On success, the OEFFIS_EVENT_CONNECTED_TO_EIS event is created and the EIS fd can be retrieved with oeffis_get_eis_fd().
Any failure in the above process or any other DBus communication error once connected, including caller bugs, result in the oeffis context being disconnected and an OEFFIS_EVENT_DISCONNECTED event. Once disconnected, the context should be released with oeffis_unref(). An OEFFIS_EVENT_DISCONNECTED indicates a communication error and oeffis_get_error_message() is set with an appropriate error message.
If the RemoteDesktop session is closed by the compositor, an OEFFIS_EVENT_CLOSED event is created and the context should be released with oeffis_unref(). Unlike a disconnection, an OEFFIS_EVENT_CLOSED event signals intentional closure by the portal. For example, this may happen as a result of user interaction to terminate the RemoteDesktop session.
oeffis | A new oeffis context |
devices | A bitmask of oeffis_device |
void oeffis_create_session_on_bus | ( | struct oeffis * | oeffis, |
const char * | busname, | ||
uint32_t | devices ) |
See oeffis_create_session() but this function allows to specify the busname to connect to.
This function should only be used for testing.
void oeffis_dispatch | ( | struct oeffis * | oeffis | ) |
Process pending events.
This function must be called immediately after the file descriptor returned by oeffis_get_fd() signals data is available.
After oeffis_dispatch() completes, zero or more events may be available by oeffis_get_event().
int oeffis_get_eis_fd | ( | struct oeffis * | oeffis | ) |
Get a dup()
of the file descriptor.
This function should only be called after an event of type OEFFIS_EVENT_CONNECTED_TO_EIS. Otherwise, this function returns -1 and errno is set to the dup()
error. If this function is called when liboeffis is not connected to EIS, the errno is set to ENODEV
.
Repeated calls to this functions will return additional duplicated file descriptors. There is no need for a well-written application to call this function more than once.
The caller is responsible for closing the returned fd.
const char * oeffis_get_error_message | ( | struct oeffis * | oeffis | ) |
If the session was OEFFIS_EVENT_DISCONNECTED, return the error message that caused the disconnection.
The returned string is owned by the oeffis context.
enum oeffis_event_type oeffis_get_event | ( | struct oeffis * | oeffis | ) |
Return the next available event, if any.
If no event is currently available, OEFFIS_EVENT_NONE is returned.
Calling oeffis_dispatch() does not guarantee events are available to the caller. A single call oeffis_dispatch() may cause more than one event to be available.
int oeffis_get_fd | ( | struct oeffis * | oeffis | ) |
liboeffis 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 oeffis_dispatch() immediately to process the events.
void * oeffis_get_user_data | ( | struct oeffis * | oeffis | ) |
Return the custom data pointer for this context.
liboeffis will not look at or modify the pointer. Use oeffis_set_user_data() to change the user data.
struct oeffis * oeffis_new | ( | void * | user_data | ) |
Create a new oeffis context.
The context is refcounted and must be released with oeffis_unref().
Increase the refcount of this struct by one.
Use oeffis_unref() to decrease the refcount.
void oeffis_set_user_data | ( | struct oeffis * | oeffis, |
void * | user_data ) |
Set a custom data pointer for this context.
liboeffis will not look at or modify the pointer. Use oeffis_get_user_data() to retrieve a previously set user data.
Decrease the refcount of this struct by one.
When the refcount reaches zero, the context disconnects from DBus and all allocated resources are released.