home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / share / idl / at-spi-1.0 / Accessibility_LoginHelper.idl < prev    next >
Encoding:
Text File  |  2006-08-22  |  6.6 KB  |  169 lines
  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
  169.