xml/org.freedesktop.atspi.LoginHelper.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <node xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" name="/node">
   3 <interface name="org.freedesktop.atspi.LoginHelper">
   4   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
   5     <p>An interface for use by assistive technologies by which
   6       they can access system information and services on a 'need to know'
   7       basis while the screen is locked, during user authentication, or
   8       during other sensitive operations.  </p>
   9
  10     <p>This interface is intended for use by assistive technologies
  11       and related user-enabling services, and by applications and
  12       utilities which may wish to restrict access to certain system
  13       devices and services during security-sensitive states, e.g. when
  14       the screen is locked or during authentication into some secure
  15       service.  </p>
  16
  17     <p>Such 'applications' (for instance, screen lock dialogs and
  18       security-enabled web browsers) use the LoginHelper client
  19       interfaces, and the bonobo-activation query service, to
  20       query for assistive technologies which advertise the LoginHelper
  21       service.  The client then queries these assistive technologies
  22       for their device I/O requirements, via the getDeviceReqs call.
  23       The client may then issue the advisory request setSafe (TRUE),
  24       which requests that the LoginHelper -implementing service make a
  25       best-effort attempt to make itself more secure (for instance,
  26       an onscreen keyboard might turn off word prediction, and a
  27       screenreader may turn off keyboard echo via speech).  The return
  28       value of setSafe is an advisory indication of whether this attempt
  29       was successful (no specific guarantees are implied).
  30       Once the 'security sensitive' state is exited, the client should
  31       call setSafe (FALSE).  </p>
  32
  33     <p>The return values from getDeviceReqs inform the client of which
  34       services the LoginHelper service (e. g. assistive technology) needs
  35       in order to do its job.  The client may use this information to
  36       loosen any restrictions on access which it may currently have in
  37       place (for instance, keyboard grabs, etc.).  If it does not do so,
  38       the likely outcome is that the end-user will experience loss
  39       of access to the system.  </p>
  40   </tp:docstring>
  41   <tp:struct name="WindowInfo">
  42     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  43       <p>A structure containing info about toplevel X windows that
  44         the LoginHelper instance wishes to have raised.    </p>
  45     </tp:docstring>
  46     <tp:member type="i" tp:name="winID">
  47     </tp:member>
  48   </tp:struct>
  49   <tp:enum name="DeviceReq" type="u">
  50     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  51       <p>The system and device access and services which the LoginHelper-implementing
  52         assistive technology requires in order to enable the user to use the system.    </p>
  53     </tp:docstring>
  54     <tp:enumvalue suffix="GUI_EVENTS">
  55     <tp:docstring>
  56        Needs access to the GUI event subsystem (e.g. Xserver)
  57     </tp:docstring>
  58     </tp:enumvalue>
  59     <tp:enumvalue suffix="CORE_KEYBOARD" value="1">
  60     <tp:docstring>
  61       Needs access to the system keyboard events (read and write)
  62     </tp:docstring>
  63     </tp:enumvalue>
  64     <tp:enumvalue suffix="CORE_POINTER" value="2">
  65     <tp:docstring>
  66       Needs access to the onscreen pointer (e.g. mouse pointer)
  67     </tp:docstring>
  68     </tp:enumvalue>
  69     <tp:enumvalue suffix="EXT_INPUT" value="3">
  70     <tp:docstring>
  71       Reads XInput extended input devices
  72     </tp:docstring>
  73     </tp:enumvalue>
  74     <tp:enumvalue suffix="POST_WINDOWS" value="4">
  75     <tp:docstring>
  76       Posts Windows, and needs for toplevel windows to be visible
  77     </tp:docstring>
  78     </tp:enumvalue>
  79     <tp:enumvalue suffix="AUDIO_OUT" value="5">
  80     <tp:docstring>
  81       Writes to audio device
  82     </tp:docstring>
  83     </tp:enumvalue>
  84     <tp:enumvalue suffix="AUDIO_IN" value="6">
  85     <tp:docstring>
  86       Reads from audio device
  87     </tp:docstring>
  88     </tp:enumvalue>
  89     <tp:enumvalue suffix="NETWORK" value="7">
  90     <tp:docstring>
  91       Requires access to general network services, including remote access
  92     </tp:docstring>
  93     </tp:enumvalue>
  94     <tp:enumvalue suffix="LOCALHOST" value="8">
  95     <tp:docstring>
  96       Requires network services hosted on LOCALHOST only
  97     </tp:docstring>
  98     </tp:enumvalue>
  99     <tp:enumvalue suffix="SERIAL_OUT" value="9">
 100     <tp:docstring>
 101       Writes to a serial port
 102     </tp:docstring>
 103     </tp:enumvalue>
 104     <tp:enumvalue suffix="SERIAL_IN" value="10">
 105     <tp:docstring>
 106       !&lt;: Reads from a serial port
 107     </tp:docstring>
 108     </tp:enumvalue>
 109   </tp:enum>
 110   <method name="setSafe">
 111     <tp:docstring>
 112       setSafe:
 113     </tp:docstring>
 114     <arg direction="in" name="safe_mode" type="b" tp:type="boolean">
 115     <tp:docstring>
 116             <code>True</code> if the client is requesting that 'safe mode' be initiated.
 117             <code>False</code> if the client is advising that 'safe mode' may be
 118             exited. i.e. Normal operation may be resumed.
 119
 120             Request a LoginHelper to enter "safe" mode, orinform LoginHelper that "safe" mode may be exited.
 121             If safe_mode is <code>True</code>, but the return value is <code>False</code> ,the requesting
 122             client may wish to deny services to the LoginHelper, for instance avoid raising its toplevels.
 123             The return value is purely advisory, and no guarantees are intended about what the implementing
 124             LoginHelper will do to improve security when in "safe" mode.
 125     </tp:docstring>
 126     </arg>
 127     <arg direction="out" type="b" tp:type="boolean">
 128     <tp:docstring>
 129       whether the LoginHelper is now "safe" or not.
 130     </tp:docstring>
 131     </arg>
 132   </method>
 133   <method name="getDeviceReqs">
 134     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 135       <p>Query a LoginHelper for the types of
 136         device I/O it requires, in order to do its job.
 137         For instance, a LoginHelper which needs to receive keyboard
 138         events will include
 139         Accessibility_LoginHelper_CORE_KEYBOARD in this list.    </p>
 140     </tp:docstring>
 141     <arg direction="out" type="u" tp:type="DeviceReqList">
 142     <tp:docstring>
 143             A sequence of LoginHelper_DeviceReq indicatingthe device I/O required in order to facilitate end-user
 144             access to the system.
 145     </tp:docstring>
 146     </arg>
 147   </method>
 148   <method name="getRaiseWindows">
 149     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 150       <p>Get a list of window IDs that need raising on login.</p>
 151     </tp:docstring>
 152     <arg direction="out" type="ai" tp:type="WindowList">
 153     <tp:docstring>
 154             A sequence containing window IDS for toplevels whichneed to be raised/made
 155             visible during user authentication, inorder for the LoginHelper to facilitate
 156             end-user access to the system.
 157     </tp:docstring>
 158     </arg>
 159   </method>
 160 </interface>
 161 </node>