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