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      * @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.
  35      *
  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
  41      * service.
  42      *
  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).
  58      *
  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.
  66      *
  67      **/
  68   interface LoginHelper : Bonobo::Unknown {
  69
  70       /**
  71        * A structure containing info about toplevel X windows that
  72        * the ::LoginHelper instance wishes to have raised.
  73        *
  74        * @param winID: The windowing-system-dependeny Window ID of the toplevel window.
  75        */
  76       struct WindowInfo {
  77           /* string display; */
  78           /* short screen; */
  79           long winID;
  80       };
  81
  82       typedef sequence<WindowInfo> WindowList;
  83
  84       /*
  85        * DeviceReq:
  86        *
  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.
  89        *
  90        */
  91       enum DeviceReq {
  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 */
 103       };
 104
 105       typedef sequence<DeviceReq> DeviceReqList;
 106
 107         /**
 108          * setSafe:
 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.
 112          *
 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.
 121          *
 122          * @returns: whether the ::LoginHelper is now "safe" or not.
 123          **/
 124         boolean setSafe (in boolean safe_mode);
 125
 126         /**
 127          * getDeviceReqs:
 128          *
 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.
 134          *
 135          * @returns: A sequence of ::LoginHelper_DeviceReq indicating
 136          *    the device I/O required in order to facilitate end-user access
 137          *    to the system.
 138          **/
 139         DeviceReqList getDeviceReqs ();
 140
 141         /**
 142          * getRaiseWindows:
 143          *
 144          * Get a list of window IDs that need raising on login.
 145          *
 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
 149          *          system.
 150          **/
 151         WindowList getRaiseWindows ();
 152
 153         /**
 154          * \cond
 155          * unImplemented:
 156          *
 157          * placeholders for future expansion.
 158          */
 159         void unImplemented ();
 160         void unImplemented2 ();
 161         void unImplemented3 ();
 162         void unImplemented4 ();
 163       /** \endcond */
 164     };
 165
 166 };
 167
 168 #endif