2 * AT-SPI - Assistive Technology Service Provider Interface
3 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
5 * Copyright 2001 Sun Microsystems Inc.
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
23 #include <Bonobo_Unknown.idl>
25 #ifndef _ACCESSIBILITY_LOGIN_HELPER_IDL_
26 #define _ACCESSIBILITY_LOGIN_HELPER_IDL_
28 module Accessibility {
31 * @brief An interface for use by assistive technologies by which
32 * they can access system information and services on a 'need to know'
33 * basis while the screen is locked, during user authentication, or
34 * during other sensitive operations.
36 * This interface is intended for use by assistive technologies
37 * and related user-enabling services, and by applications and
38 * utilities which may wish to restrict access to certain system
39 * devices and services during security-sensitive states, e.g. when
40 * the screen is locked or during authentication into some secure
43 * Such 'applications' (for instance, screen lock dialogs and
44 * security-enabled web browsers) use the ::LoginHelper client
45 * interfaces, and the bonobo-activation query service, to
46 * query for assistive technologies which advertise the ::LoginHelper
47 * service. The client then queries these assistive technologies
48 * for their device I/O requirements, via the ::getDeviceReqs call.
49 * The client may then issue the advisory request ::setSafe (TRUE),
50 * which requests that the ::LoginHelper -implementing service make a
51 * best-effort attempt to make itself more secure (for instance,
52 * an onscreen keyboard might turn off word prediction, and a
53 * screenreader may turn off keyboard echo via speech). The return
54 * value of ::setSafe is an advisory indication of whether this attempt
55 * was successful (no specific guarantees are implied).
56 * Once the 'security sensitive' state is exited, the client should
57 * call ::setSafe (FALSE).
59 * The return values from ::getDeviceReqs inform the client of which
60 * services the ::LoginHelper service (e. g. assistive technology) needs
61 * in order to do its job. The client may use this information to
62 * loosen any restrictions on access which it may currently have in
63 * place (for instance, keyboard grabs, etc.). If it does not do so,
64 * the likely outcome is that the end-user will experience loss
65 * of access to the system.
68 interface LoginHelper : Bonobo::Unknown {
71 * A structure containing info about toplevel X windows that
72 * the ::LoginHelper instance wishes to have raised.
74 * @param winID: The windowing-system-dependeny Window ID of the toplevel window.
82 typedef sequence<WindowInfo> WindowList;
87 * The system and device access and services which the LoginHelper-implementing
88 * assistive technology requires in order to enable the user to use the system.
92 GUI_EVENTS, /*!<: Needs access to the GUI event subsystem (e.g. Xserver) */
93 CORE_KEYBOARD, /*!<: Needs access to the system keyboard events (read and write) */
94 CORE_POINTER, /*!<: Needs access to the onscreen pointer (e.g. mouse pointer) */
95 EXT_INPUT, /*!<: Reads XInput extended input devices */
96 POST_WINDOWS, /*!<: Posts Windows, and needs for toplevel windows to be visible */
97 AUDIO_OUT, /*!<: Writes to audio device */
98 AUDIO_IN, /*!<: Reads from audio device */
99 NETWORK, /*!<: Requires access to general network services, including remote access */
100 LOCALHOST, /*!<: Requires network services hosted on LOCALHOST only */
101 SERIAL_OUT, /*!<: Writes to a serial port */
102 SERIAL_IN /*!<: Reads from a serial port */
105 typedef sequence<DeviceReq> DeviceReqList;
109 * @param safe_mode: \c TRUE if the client is requesting that 'safe mode' be
110 * initiated, \c FALSE if the client is advising that 'safe mode' may be
111 * exited, i.e. normal operation may be resumed.
113 * Request a LoginHelper to enter "safe" mode, or
114 * inform LoginHelper that "safe" mode may be exited.
115 * If \a safe_mode is \c TRUE, but the return value is \c FALSE,
116 * the requesting client may wish to deny services to the
117 * ::LoginHelper, for instance avoid raising its toplevels.
118 * The return value is purely advisory, and no guarantees are
119 * intended about what the implementing LoginHelper will do
120 * to improve security when in "safe" mode.
122 * @returns: whether the ::LoginHelper is now "safe" or not.
124 boolean setSafe (in boolean safe_mode);
129 * Query a ::LoginHelper for the types of
130 * device I/O it requires, in order to do its job.
131 * For instance, a ::LoginHelper which needs to receive keyboard
132 * events will include
133 * Accessibility_LoginHelper_CORE_KEYBOARD in this list.
135 * @returns: A sequence of ::LoginHelper_DeviceReq indicating
136 * the device I/O required in order to facilitate end-user access
139 DeviceReqList getDeviceReqs ();
144 * Get a list of window IDs that need raising on login.
146 * @returns: a sequence containing window IDS for toplevels which
147 * need to be raised/made visible during user authentication, in
148 * order for the ::LoginHelper to facilitate end-user access to the
151 WindowList getRaiseWindows ();
157 * placeholders for future expansion.
159 void unImplemented ();
160 void unImplemented2 ();
161 void unImplemented3 ();
162 void unImplemented4 ();