pyatspi/loginhelper.py

   1 #Copyright (C) 2008 Codethink Ltd
   2
   3 #This library is free software; you can redistribute it and/or
   4 #modify it under the terms of the GNU Lesser General Public
   5 #License version 2 as published by the Free Software Foundation.
   6
   7 #This program is distributed in the hope that it will be useful,
   8 #but WITHOUT ANY WARRANTY; without even the implied warranty of
   9 #MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  10 #GNU General Public License for more details.
  11 #You should have received a copy of the GNU Lesser General Public License
  12 #along with this program; if not, write to the Free Software
  13 #Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  14
  15 import interfaces
  16 from base import BaseProxy, Enum
  17 from factory import add_accessible_class
  18
  19 __all__ = [
  20            "LoginHelper",
  21           ]
  22
  23 #------------------------------------------------------------------------------
  24
  25 class LoginHelper(BaseProxy):
  26     """
  27     An interface for use by assistive technologies by which they
  28     can access system information and services on a 'need to know'
  29     basis while the screen is locked, during user authentication,
  30     or during other sensitive operations.
  31     This interface is intended for use by assistive technologies
  32     and related user-enabling services, and by applications and utilities
  33     which may wish to restrict access to certain system devices and
  34     services during security-sensitive states, e.g. when the screen
  35     is locked or during authentication into some secure service.
  36     Such 'applications' (for instance, screen lock dialogs and security-enabled
  37     web browsers) use the LoginHelper client interfaces, and the
  38     bonobo-activation query service, to query for assistive technologies
  39     which advertise the LoginHelper service. The client then queries
  40     these assistive technologies for their device I/O requirements,
  41     via the getDeviceReqs call. The client may then issue the advisory
  42     request setSafe (TRUE), which requests that the LoginHelper -implementing
  43     service make a best-effort attempt to make itself more secure
  44     (for instance, an onscreen keyboard might turn off word prediction,
  45     and a screenreader may turn off keyboard echo via speech). The
  46     return value of setSafe is an advisory indication of whether
  47     this attempt was successful (no specific guarantees are implied).
  48     Once the 'security sensitive' state is exited, the client should
  49     call setSafe (FALSE).
  50     The return values from getDeviceReqs inform the client of which
  51     services the LoginHelper service (e. g. assistive technology)
  52     needs in order to do its job. The client may use this information
  53     to loosen any restrictions on access which it may currently have
  54     in place (for instance, keyboard grabs, etc.). If it does not
  55     do so, the likely outcome is that the end-user will experience
  56     loss of access to the system.
  57     """
  58
  59     def getDeviceReqs(self, *args, **kwargs):
  60         """
  61         getDeviceReqs:
  62         Query a LoginHelper for the types of device I/O it requires,
  63         in order to do its job. For instance, a LoginHelper which needs
  64         to receive keyboard events will include Accessibility_LoginHelper_CORE_KEYBOARD
  65         in this list.
  66         @return : A sequence of LoginHelper_DeviceReq indicating the
  67         device I/O required in order to facilitate end-user access to
  68         the system.
  69         """
  70         func = self.get_dbus_method("getDeviceReqs")
  71         return func(*args, **kwargs)
  72
  73     def getRaiseWindows(self, *args, **kwargs):
  74         """
  75         getRaiseWindows:
  76         Get a list of window IDs that need raising on login.
  77         @return : a sequence containing window IDS for toplevels which
  78         need to be raised/made visible during user authentication, in
  79         order for the LoginHelper to facilitate end-user access to the
  80         system.
  81         """
  82         func = self.get_dbus_method("getRaiseWindows")
  83         return func(*args, **kwargs)
  84
  85     def setSafe(self, *args, **kwargs):
  86         """
  87         setSafe:
  88         @param : safe_mode
  89         TRUE if the client is requesting that 'safe mode' be initiated,
  90         FALSE if the client is advising that 'safe mode' may be exited,
  91         i.e. normal operation may be resumed.
  92         Request a LoginHelper to enter "safe" mode, or inform LoginHelper
  93         that "safe" mode may be exited. If safe_mode is TRUE, but the
  94         return value is FALSE, the requesting client may wish to deny
  95         services to the LoginHelper, for instance avoid raising its toplevels.
  96         The return value is purely advisory, and no guarantees are intended
  97         about what the implementing LoginHelper will do to improve security
  98         when in "safe" mode.
  99         @return : whether the LoginHelper is now "safe" or not.
 100         """
 101         func = self.get_dbus_method("setSafe")
 102         return func(*args, **kwargs)
 103
 104     class DeviceReq(Enum):
 105         _enum_lookup = {
 106             0:'GUI_EVENTS',
 107             1:'CORE_KEYBOARD',
 108             2:'CORE_POINTER',
 109             3:'EXT_INPUT',
 110             4:'POST_WINDOWS',
 111             5:'AUDIO_OUT',
 112             6:'AUDIO_IN',
 113             7:'NETWORK',
 114             8:'LOCALHOST',
 115             9:'SERIAL_OUT',
 116             10:'SERIAL_IN',
 117         }
 118
 119     AUDIO_IN = DeviceReq(6)
 120
 121     AUDIO_OUT = DeviceReq(5)
 122
 123     CORE_KEYBOARD = DeviceReq(1)
 124
 125     CORE_POINTER = DeviceReq(2)
 126
 127     EXT_INPUT = DeviceReq(3)
 128
 129     GUI_EVENTS = DeviceReq(0)
 130
 131     LOCALHOST = DeviceReq(8)
 132
 133     NETWORK = DeviceReq(7)
 134
 135     POST_WINDOWS = DeviceReq(4)
 136
 137     SERIAL_IN = DeviceReq(10)
 138
 139     SERIAL_OUT = DeviceReq(9)
 140
 141     class WindowInfo(list):
 142         def __new__(cls, winID):
 143             list.__new__(cls, (winID))
 144         def __init__(self, winID):
 145             list.__init__(self, (winID))
 146
 147         def _get_winID(self):
 148             return self[0]
 149         def _set_winID(self, val):
 150             self[0] = val
 151         winID = property(fget=_get_winID, fset=_set_winID)
 152
 153 # ATTENTION - Register the Application class with the accessible factory.
 154 add_accessible_class(interfaces.ATSPI_LOGIN_HELPER, LoginHelper)
 155
 156 #END----------------------------------------------------------------------------