/* 
 * 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 {

  interface LoginHelper : Bonobo::Unknown {

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

      typedef sequence<WindowInfo> WindowList;

      /*
       * DeviceReq:
       * @Accessibility_LoginHelper_GUI_EVENTS: Needs access to the GUI event subsystem (e.g. Xserver).
       * @Accessibility_LoginHelper_CORE_KEYBOARD Needs access to the system keyboard events (read and write).
       * @Accessibility_LoginHelper_CORE_POINTER: Needs access to the onscreen pointer (e.g. mouse pointer).
       * @Accessibility_LoginHelper_EXT_INPUT: Reads XInput extended input devices.
       * @Accessibility_LoginHelper_POST_WINDOWS: Posts Windows, and needs for toplevel windows to be visible
       * @Accessibility_LoginHelper_AUDIO_OUT: Writes to audio device.
       * @Accessibility_LoginHelper_AUDIO_IN: Reads from audio device.
       * @Accessibility_LoginHelper_NETWORK: Requires access to general network services, including remote access.
       * @Accessibility_LoginHelper_LOCALHOST: Requires network services hosted on LOCALHOST only.
       * @Accessibility_LoginHelper_SERIAL_OUT: Writes to a serial port.
       * @Accessibility_LoginHelper_SERIAL_IN: Reads from a serial port.
       *
       * 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,
	  CORE_KEYBOARD,
	  CORE_POINTER,
	  EXT_INPUT,
	  POST_WINDOWS,
	  AUDIO_OUT,
	  AUDIO_IN,
	  NETWORK,
	  LOCALHOST,
	  SERIAL_OUT,
	  SERIAL_IN
      };

      typedef sequence<DeviceReq> DeviceReqList;

  	/**
         * setSafe:
         * 
         * Request a LoginHelper to enter "safe" mode, or
	 *         inform LoginHelper that "safe" mode may be exited.
	 *         If @safe_mode is %TRUE, but the return value is %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_DeviceFlags 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 ();

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

};

#endif