fdo-mirrors/libei
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libinput/libei.git synced 2026-05-05 07:48:01 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

libreis: update the API docs a bit

Browse source 
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer 2020-08-10 08:42:25 +10:00
parent 12a04fa657
commit 2631854dbb
1 changed files with 35 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
src/libreis.h
View file

@ -26,14 +26,14 @@
#include <libeis.h>
/**
* REIS is the Restrictions for EIS. This library is used by intermediaries
* between EI and EIS to reduce the capabilities that an EI client has
* available.
* REIS is the library for Restrictions for EIS. This library is used by
* intermediaries between EI and EIS to reduce the capabilities that an EI
* client has available.
*
* It is a helper library that does not initiate a full EI or EIS
* context but works on the file descriptor instead.
*
* Restricting capabilities is a one-way-road. The default EIS context has
* Restricting capabilities is a one-way-road. A default EIS context has
* full permissions, consecutive calls can only restrict the current
* permissions but not loosen them.
*/
@ -46,10 +46,19 @@ reis_new(void);
struct reis *
reis_unref(struct reis* reis);
/**
* Apply the currently configured set of restrictions to the EIS context at
* the other end of eisfd. The EIS context does not need to be in any
* specific state and no checking is done that there is indeed an EIS
* context at the other end of the fd.
*
* Once applied, the reis context should be released with reis_unref()
*
* @return zero on success or a negative errno otherwise
*/
int
reis_apply(struct reis *reis, int eisfd);
/**
* Set the name for the client on this connection.
*
@ -76,11 +85,11 @@ reis_set_cap_policy_allow(struct reis *reis);
/**
* Change the default policy for capabilities to "deny". Capabilities are
* allowed unless explicitly denied by reis_allow_cap().
* denied unless explicitly denied by reis_allow_cap().
*
* You **must** call reis_allow_cap() **before** calling this function, once
* the default deny policy is in place, the allowed capabilities cannot be
* expanded further.
* A caller must call reis_allow_cap() *before* calling
* reis_set_cap_policy_deny(), once the default deny policy is in place, the
* allowed capabilities cannot be expanded further.
*
* A capability is permitted if:
* - the policy is allow and the capability is not in the deny list
@ -92,12 +101,29 @@ reis_set_cap_policy_deny(struct reis *reis);
/**
* Explicitly allow the given capability.
*
* This function may be called multiple times before reis_apply() to create
* a set of allowed capabilities.
*
* Where reis_apply() is called multiple times with reis_allow_cap(), the
* final set of allowed capabilities is the intersection of all sets.
* In other words, calling reis_apply() once with pointer and keyboard caps
* and once with just keyboard caps results in just keyboard caps.
*/
int
reis_allow_cap(struct reis *reis, enum eis_device_capability cap);
/**
* Explicitly deny the given capability.
*
* This function may be called multiple times before reis_apply() to create
* a set of denied capabilities.
*
* Where reis_apply() is called multiple times with reis_deny_cap(), the
* final set of denied capabilities is the union of all sets.
* In other words, calling reis_apply() once with pointer caps denied
* and once with keyboard caps denied results in both pointer and keyboard
* caps denied.
*/
int
reis_deny_cap(struct reis *reis, enum eis_device_capability cap);