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 accessible_factory
  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         AUDIO_OUT = DeviceReq(5)
 121         CORE_KEYBOARD = DeviceReq(1)
 122         CORE_POINTER = DeviceReq(2)
 123         EXT_INPUT = DeviceReq(3)
 124         GUI_EVENTS = DeviceReq(0)
 125         LOCALHOST = DeviceReq(8)
 126         NETWORK = DeviceReq(7)
 127         POST_WINDOWS = DeviceReq(4)
 128         SERIAL_IN = DeviceReq(10)
 129         SERIAL_OUT = DeviceReq(9)
 130
 131         class WindowInfo(list):
 132                 def __new__(cls, winID):
 133                         list.__new__(cls, (winID))
 134                 def __init__(self, winID):
 135                         list.__init__(self, (winID))
 136
 137                 def _get_winID(self):
 138                         return self[0]
 139                 def _set_winID(self, val):
 140                         self[0] = val
 141                 winID = property(fget=_get_winID, fset=_set_winID)
 142
 143 # Register the accessible class with the factory.
 144 accessible_factory.register_accessible_class(interfaces.ATSPI_LOGIN_HELPER, LoginHelper)
 145
 146 #END----------------------------------------------------------------------------