idl/Accessibility_LoginHelper.idl

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001 Sun Microsystems Inc.
   6  *
   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.
  11  *
  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.
  16  *
  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.
  21  */
  22
  23 #include <Bonobo_Unknown.idl>
  24
  25 #ifndef _ACCESSIBILITY_LOGIN_HELPER_IDL_
  26 #define _ACCESSIBILITY_LOGIN_HELPER_IDL_
  27
  28 module Accessibility {
  29
  30     /**
  31      * LoginHelper:
  32      *
  33      * This interface is intended for use by assistive technologies
  34      * and related user-enabling services, and by applications and
  35      * utilities which may wish to restrict access to certain system
  36      * devices and services during security-sensitive states, e.g. when
  37      * the screen is locked or during authentication into some secure
  38      * service.
  39      *
  40      * Such 'applications' (for instance, screen lock dialogs and
  41      * security-enabled web browsers) use the @LoginHelper client
  42      * interfaces, and the bonobo-activation query service, to
  43      * query for assistive technologies which advertise the @LoginHelper
  44      * service.  The client then queries these assistive technologies
  45      * for their device I/O requirements, via the @getDeviceReqs call.
  46      * The client may then issue the advisory request @setSafe (TRUE),
  47      * which requests that the @LoginHelper-implementing service make a
  48      * best-effort attempt to make itself more secure (for instance,
  49      * an onscreen keyboard might turn off word prediction, and a
  50      * screenreader may turn off keyboard echo via speech).  The return
  51      * value of @setSafe is an advisory indication of whether this attempt
  52      * was successful (no specific guarantees are implied).
  53      * Once the 'security sensitive' state is exited, the client should
  54      * call @setSafe (FALSE).
  55      *
  56      * The return values from @getDeviceReqs inform the client of which
  57      * services the @LoginHelper service (e. g. assistive technology) needs
  58      * in order to do its job.  The client may use this information to
  59      * loosen any restrictions on access which it may currently have in
  60      * place (for instance, keyboard grabs, etc.).  If it does not do so,
  61      * the likely outcome is that the end-user will experience loss
  62      * of access to the system.
  63      *
  64      **/
  65   interface LoginHelper : Bonobo::Unknown {
  66
  67       /*
  68        * WindowInfo:
  69        * A structure containing info about toplevel X windows that
  70        * the @LoginHelper instance wishes to have raised.
  71        *
  72        * @winID: The windowing-system-dependeny Window ID of the toplevel window.
  73        */
  74       struct WindowInfo {
  75           long winID;
  76       };
  77
  78       typedef sequence<WindowInfo> WindowList;
  79
  80       /*
  81        * DeviceReq:
  82        * @Accessibility_LoginHelper_GUI_EVENTS: Needs access to the GUI event subsystem (e.g. Xserver).
  83        * @Accessibility_LoginHelper_CORE_KEYBOARD Needs access to the system keyboard events (read and write).
  84        * @Accessibility_LoginHelper_CORE_POINTER: Needs access to the onscreen pointer (e.g. mouse pointer).
  85        * @Accessibility_LoginHelper_EXT_INPUT: Reads XInput extended input devices.
  86        * @Accessibility_LoginHelper_POST_WINDOWS: Posts Windows, and needs for toplevel windows to be visible
  87        * @Accessibility_LoginHelper_AUDIO_OUT: Writes to audio device.
  88        * @Accessibility_LoginHelper_AUDIO_IN: Reads from audio device.
  89        * @Accessibility_LoginHelper_NETWORK: Requires access to general network services, including remote access.
  90        * @Accessibility_LoginHelper_LOCALHOST: Requires network services hosted on LOCALHOST only.
  91        * @Accessibility_LoginHelper_SERIAL_OUT: Writes to a serial port.
  92        * @Accessibility_LoginHelper_SERIAL_IN: Reads from a serial port.
  93        *
  94        * The system and device access and services which the @LoginHelper-implementing
  95        * assistive technology requires in order to enable the user to use the system.
  96        *
  97        */
  98       enum DeviceReq {
  99           GUI_EVENTS,
 100           CORE_KEYBOARD,
 101           CORE_POINTER,
 102           EXT_INPUT,
 103           POST_WINDOWS,
 104           AUDIO_OUT,
 105           AUDIO_IN,
 106           NETWORK,
 107           LOCALHOST,
 108           SERIAL_OUT,
 109           SERIAL_IN
 110       };
 111
 112       typedef sequence<DeviceReq> DeviceReqList;
 113
 114         /**
 115          * setSafe:
 116          *
 117          * Request a LoginHelper to enter "safe" mode, or
 118          *         inform LoginHelper that "safe" mode may be exited.
 119          *         If @safe_mode is %TRUE, but the return value is %FALSE,
 120          *         the requesting client may wish to deny services to the
 121          *         %LoginHelper, for instance avoid raising its toplevels.
 122          *         The return value is purely advisory, and no guarantees are
 123          *         intended about what the implementing LoginHelper will do
 124          *         to improve security when in "safe" mode.
 125          *
 126          * Returns: whether the %LoginHelper is now "safe" or not.
 127          **/
 128         boolean setSafe (in boolean safe_mode);
 129
 130         /**
 131          * getDeviceReqs:
 132          *
 133          * Query a @LoginHelper for the types of
 134          *    device I/O it requires, in order to do its job.
 135          *    For instance, a @LoginHelper which needs to receive keyboard
 136          *    events will include
 137          *    Accessibility_LoginHelper_CORE_KEYBOARD in this list.
 138          *
 139          * Returns: A sequence of @LoginHelper_DeviceFlags indicating
 140          *    the device I/O required in order to facilitate end-user access
 141          *    to the system.
 142          **/
 143         DeviceReqList getDeviceReqs ();
 144
 145         /**
 146          * getRaiseWindows:
 147          *
 148          * Get a list of window IDs that need raising on login.
 149          *
 150          * Returns: a sequence containing window IDS for toplevels which
 151          *          need to be raised/made visible during user authentication, in
 152          *          order for the @LoginHelper to facilitate end-user access to the
 153          *          system.
 154          **/
 155         WindowList getRaiseWindows ();
 156
 157         /**
 158          * unImplemented:
 159          *
 160          * placeholders for future expansion.
 161          */
 162         void unImplemented ();
 163         void unImplemented2 ();
 164         void unImplemented3 ();
 165         void unImplemented4 ();
 166     };
 167
 168 };
 169
 170 #endif