module Accessibility {
+ /**
+ * @brief An interface for use by assistive technologies by which
+ * they can access system information and services on a 'need to know'
+ * basis while the screen is locked, during user authentication, or
+ * during other sensitive operations.
+ *
+ * This interface is intended for use by assistive technologies
+ * and related user-enabling services, and by applications and
+ * utilities which may wish to restrict access to certain system
+ * devices and services during security-sensitive states, e.g. when
+ * the screen is locked or during authentication into some secure
+ * service.
+ *
+ * Such 'applications' (for instance, screen lock dialogs and
+ * security-enabled web browsers) use the ::LoginHelper client
+ * interfaces, and the bonobo-activation query service, to
+ * query for assistive technologies which advertise the ::LoginHelper
+ * service. The client then queries these assistive technologies
+ * for their device I/O requirements, via the ::getDeviceReqs call.
+ * The client may then issue the advisory request ::setSafe (TRUE),
+ * which requests that the ::LoginHelper -implementing service make a
+ * best-effort attempt to make itself more secure (for instance,
+ * an onscreen keyboard might turn off word prediction, and a
+ * screenreader may turn off keyboard echo via speech). The return
+ * value of ::setSafe is an advisory indication of whether this attempt
+ * was successful (no specific guarantees are implied).
+ * Once the 'security sensitive' state is exited, the client should
+ * call ::setSafe (FALSE).
+ *
+ * The return values from ::getDeviceReqs inform the client of which
+ * services the ::LoginHelper service (e. g. assistive technology) needs
+ * in order to do its job. The client may use this information to
+ * loosen any restrictions on access which it may currently have in
+ * place (for instance, keyboard grabs, etc.). If it does not do so,
+ * the likely outcome is that the end-user will experience loss
+ * of access to the system.
+ *
+ **/
interface LoginHelper : Bonobo::Unknown {
+ /**
+ * A structure containing info about toplevel X windows that
+ * the ::LoginHelper instance wishes to have raised.
+ *
+ * @param winID: The windowing-system-dependeny Window ID of the toplevel window.
+ */
struct WindowInfo {
+ /* string display; */
+ /* short screen; */
long winID;
- };
+ };
typedef sequence<WindowInfo> WindowList;
+ /*
+ * DeviceReq:
+ *
+ * The system and device access and services which the LoginHelper-implementing
+ * assistive technology requires in order to enable the user to use the system.
+ *
+ */
enum DeviceReq {
- GUI_EVENTS,
- CORE_KEYBOARD,
- CORE_POINTER,
- EXT_INPUT,
- POST_WINDOWS,
- AUDIO_OUT,
- AUDIO_IN,
- NETWORK,
- LOCALHOST,
- SERIAL_OUT,
- SERIAL_IN
+ GUI_EVENTS, /*!<: Needs access to the GUI event subsystem (e.g. Xserver) */
+ CORE_KEYBOARD, /*!<: Needs access to the system keyboard events (read and write) */
+ CORE_POINTER, /*!<: Needs access to the onscreen pointer (e.g. mouse pointer) */
+ EXT_INPUT, /*!<: Reads XInput extended input devices */
+ POST_WINDOWS, /*!<: Posts Windows, and needs for toplevel windows to be visible */
+ AUDIO_OUT, /*!<: Writes to audio device */
+ AUDIO_IN, /*!<: Reads from audio device */
+ NETWORK, /*!<: Requires access to general network services, including remote access */
+ LOCALHOST, /*!<: Requires network services hosted on LOCALHOST only */
+ SERIAL_OUT, /*!<: Writes to a serial port */
+ SERIAL_IN /*!<: Reads from a serial port */
};
typedef sequence<DeviceReq> DeviceReqList;
/**
* setSafe:
+ * @param safe_mode: \c TRUE if the client is requesting that 'safe mode' be
+ * initiated, \c FALSE if the client is advising that 'safe mode' may be
+ * exited, i.e. normal operation may be resumed.
*
* Request a LoginHelper to enter "safe" mode, or
* inform LoginHelper that "safe" mode may be exited.
- * If @safe_mode is %TRUE, but the return value is %FALSE,
+ * If \a safe_mode is \c TRUE, but the return value is \c FALSE,
* the requesting client may wish to deny services to the
- * %LoginHelper, for instance avoid raising its toplevels.
+ * ::LoginHelper, for instance avoid raising its toplevels.
+ * The return value is purely advisory, and no guarantees are
+ * intended about what the implementing LoginHelper will do
+ * to improve security when in "safe" mode.
*
- * Returns: whether the %LoginHelper is now "safe" or not.
+ * @returns: whether the ::LoginHelper is now "safe" or not.
**/
boolean setSafe (in boolean safe_mode);
/**
* getDeviceReqs:
*
- * Query a @LoginHelper for the types of
+ * Query a ::LoginHelper for the types of
* device I/O it requires, in order to do its job.
- * For instance, a @LoginHelper which needs to receive keyboard
+ * For instance, a ::LoginHelper which needs to receive keyboard
* events will include
* Accessibility_LoginHelper_CORE_KEYBOARD in this list.
*
- * Returns: A sequence of @LoginHelper_DeviceFlags indicating
- * the device I/O required.
+ * @returns: A sequence of ::LoginHelper_DeviceReq indicating
+ * the device I/O required in order to facilitate end-user access
+ * to the system.
**/
DeviceReqList getDeviceReqs ();
*
* Get a list of window IDs that need raising on login.
*
- * Returns: a sequence containing window IDS for toplevels which
- * need to be raised/made visible during user authentication.
+ * @returns: a sequence containing window IDS for toplevels which
+ * need to be raised/made visible during user authentication, in
+ * order for the ::LoginHelper to facilitate end-user access to the
+ * system.
**/
WindowList getRaiseWindows ();
/**
+ * \cond
* unImplemented:
*
* placeholders for future expansion.
void unImplemented2 ();
void unImplemented3 ();
void unImplemented4 ();
+ /** \endcond */
};
};