/* 
 * AT-SPI - Assistive Technology Service Provider Interface 
 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
 *
 * Copyright 2001 Sun Microsystems Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#include <Bonobo_Unknown.idl>

#ifndef _ACCESSIBILITY_LOGIN_HELPER_IDL_
#define _ACCESSIBILITY_LOGIN_HELPER_IDL_

module Accessibility {

    /**
     * @brief An interface for use by assistive technologies by which
     * they can access system information and services on a 'need to know'
     * basis while the screen is locked, during user authentication, or
     * during other sensitive operations.
     *
     * This interface is intended for use by assistive technologies
     * and related user-enabling services, and by applications and
     * utilities which may wish to restrict access to certain system 
     * devices and services during security-sensitive states, e.g. when 
     * the screen is locked or during authentication into some secure
     * service.
     *
     * Such 'applications' (for instance, screen lock dialogs and
     * security-enabled web browsers) use the ::LoginHelper client
     * interfaces, and the bonobo-activation query service, to
     * query for assistive technologies which advertise the ::LoginHelper
     * service.  The client then queries these assistive technologies 
     * for their device I/O requirements, via the ::getDeviceReqs call.
     * The client may then issue the advisory request ::setSafe (TRUE), 
     * which requests that the ::LoginHelper -implementing service make a
     * best-effort attempt to make itself more secure (for instance, 
     * an onscreen keyboard might turn off word prediction, and a
     * screenreader may turn off keyboard echo via speech).  The return
     * value of ::setSafe is an advisory indication of whether this attempt
     * was successful (no specific guarantees are implied).
     * Once the 'security sensitive' state is exited, the client should 
     * call ::setSafe (FALSE).
     * 
     * The return values from ::getDeviceReqs inform the client of which
     * services the ::LoginHelper service (e. g. assistive technology) needs
     * in order to do its job.  The client may use this information to
     * loosen any restrictions on access which it may currently have in 
     * place (for instance, keyboard grabs, etc.).  If it does not do so,
     * the likely outcome is that the end-user will experience loss
     * of access to the system.
     *
     **/
  interface LoginHelper : Bonobo::Unknown {

      /** 
       * A structure containing info about toplevel X windows that
       * the ::LoginHelper instance wishes to have raised.
       *
       * @param winID: The windowing-system-dependeny Window ID of the toplevel window.
       */
      struct WindowInfo {
	  /* string display; */
	  /* short screen; */
	  long winID;
      };

      typedef sequence<WindowInfo> WindowList;

      /*
       * DeviceReq:
       *
       * The system and device access and services which the LoginHelper-implementing 
       * assistive technology requires in order to enable the user to use the system.
       *
       */
      enum DeviceReq {
	  GUI_EVENTS, /*!<: Needs access to the GUI event subsystem (e.g. Xserver) */
	  CORE_KEYBOARD, /*!<: Needs access to the system keyboard events (read and write) */
	  CORE_POINTER, /*!<: Needs access to the onscreen pointer (e.g. mouse pointer) */
			  EXT_INPUT, /*!<: Reads XInput extended input devices */
	  POST_WINDOWS, /*!<: Posts Windows, and needs for toplevel windows to be visible */
	  AUDIO_OUT, /*!<: Writes to audio device */
	  AUDIO_IN, /*!<: Reads from audio device */
	  NETWORK, /*!<: Requires access to general network services, including remote access */
	  LOCALHOST, /*!<: Requires network services hosted on LOCALHOST only */
	  SERIAL_OUT, /*!<: Writes to a serial port */
	  SERIAL_IN /*!<: Reads from a serial port */
      };

      typedef sequence<DeviceReq> DeviceReqList;

  	/**
         * setSafe:
	 * @param safe_mode: \c TRUE if the client is requesting that 'safe mode' be 
	 *         initiated, \c FALSE if the client is advising that 'safe mode' may be
	 *         exited, i.e. normal operation may be resumed.
         * 
         * Request a LoginHelper to enter "safe" mode, or
	 *         inform LoginHelper that "safe" mode may be exited.
	 *         If \a safe_mode is \c TRUE, but the return value is \c FALSE,
	 *         the requesting client may wish to deny services to the 
	 *         ::LoginHelper, for instance avoid raising its toplevels.
	 *         The return value is purely advisory, and no guarantees are 
	 *         intended about what the implementing LoginHelper will do 
	 *         to improve security when in "safe" mode.
	 *
         * @returns: whether the ::LoginHelper is now "safe" or not.
	 **/
        boolean setSafe (in boolean safe_mode);

  	/**
         * getDeviceReqs:
         * 
         * Query a ::LoginHelper for the types of
	 *    device I/O it requires, in order to do its job.
	 *    For instance, a ::LoginHelper which needs to receive keyboard
	 *    events will include 
	 *    Accessibility_LoginHelper_CORE_KEYBOARD in this list.
	 *
         * @returns: A sequence of ::LoginHelper_DeviceReq indicating
	 *    the device I/O required in order to facilitate end-user access 
	 *    to the system.
	 **/
        DeviceReqList getDeviceReqs ();

  	/**
         * getRaiseWindows:
         *
         * Get a list of window IDs that need raising on login. 
         *
	 * @returns: a sequence containing window IDS for toplevels which
	 *          need to be raised/made visible during user authentication, in
	 *          order for the ::LoginHelper to facilitate end-user access to the 
	 *          system.
	 **/
        WindowList getRaiseWindows ();

	/**
	 * \cond
	 * unImplemented:
	 *
	 * placeholders for future expansion.
	 */
	void unImplemented ();
	void unImplemented2 ();
	void unImplemented3 ();
	void unImplemented4 ();
      /** \endcond */
    };

};

#endif