/*
 * \brief   Nitpicker server interface
 * \date    2007-04-24
 * \author  Norman Feske and David A. Wheeler
 */

/*
 * Copyright (C) 2002-2004  Norman Feske  <nf2@os.inf.tu-dresden.de>
 * Technische Universitaet Dresden, Operating Systems Research Group
 * Copyright (C) 2007 Institute for Defense Analyses
 *
 * This file is part of the Linpicker package, which is distributed under
 * the  terms  of the  GNU General Public Licence 2.  Please see the
 * COPYING file for details.
 *
 * Unlike the Nitpicker original, this IDL file is in standard CORBA format.
 */

// ??? DEBUG
const long SHARED_BUFFER_INFO_NAME_LENGTH = 64;
struct shared_buffer_info_t {
   char name[SHARED_BUFFER_INFO_NAME_LENGTH];
};

interface Nitevent {
};

interface nitpicker {

	// ??? Returns 1 if alive. This is a bogus function, primarily to
	// simply test the commo infrastructure.
	long alive();
        long kill_graphics();

	/*** DONATE MEMORY ***
	 *
	 * Donate memory for the storage of client-specific data structures
	 * inside nitpicker. When called a second time, nitpicker discards
	 * the previous donation including all views and buffers. If a client
	 * has to increase max_views or max_buffers later on, the client has
	 * to recover the old state by itself.
	 *
	 * To calculate the needed size for the dataspace to donate, use:
	 * size = sizeof(client)
	 *      + sizeof(view)   * max_views
	 *      + sizeof(buffer) * max_buffers
	 *
	 * \return  0 on success, or
	 *         -1 if supplied memory block is too small to store the
	 *            requested number of views and buffers, or
	 *         -2 dataspace is invalid
	 */
	long initialize_client(in unsigned short max_views, in unsigned short max_buffers);

	/*** REQUEST INFORMATION ABOUT PHYSICAL SCREEN ***/
	// WARNING: Note that in CORBA IDL, "out" doesn't include the *.
	void get_screen_info(out unsigned short w, out unsigned short h,
                             out unsigned short depth, out unsigned short mode);


	/*** INJECT NEW BUFFER ***/
	long import_buffer(in string ds, in unsigned short w, in unsigned short h);


	/*** REMOVE BUFFER ***/
	void remove_buffer(in long buf_id);


	/*** REFRESH GRAPHICAL REPRESENTATION OF THE NEW BUFFER ***/
	void refresh(in long buf_id, in unsigned short x, in unsigned short y, in unsigned short w, in unsigned short h);


	/*** CREATE A NEW VIEW AT A BUFFER ***
	 *
	 * \param buf_id    buffer that is displayed by the view
	 * \param token     private token to be associated with the view
	 * \param listener  receiver of events regarding the view
	 */
        /* TODO: We will temporarily NOT pass Nitevent.  This means there's
           no way to distinguish the listener, but we want to get through
           the single-client case before we handle X clients. */
	/* long new_view(in long buf_id, in Nitevent listener); */
	long new_view(in unsigned short buf_id);


	/*** CLOSE VIEW ***/
	void destroy_view(in unsigned short view_id);


	/*** DEFINE VIEWPORT ON THE BUFFER ***/
	long set_view_port(in unsigned short view_id, in unsigned short buf_x, in unsigned short buf_y,
	                  in unsigned short x, in unsigned short y, in unsigned short w, in unsigned short h,
	                  in short do_redraw);

	/*** POSITION VIEW IN VIEW STACK ***
	 *
	 * \param neighbor  neighbor view id or
	 *                 -1  top or bottom of view stack
	 * \param behind    0  insert view in front or
	 *                  1  behind the specified neightbor
	 *
	 * To insert a view at the top of the view stack, specify
	 * neighbor = -1 and behind = 1. To insert a view at the
	 * bottom of the view stack, specify neighbor = -1 and
	 * behind = 0.
	 */
	long stack_view(in unsigned short view_id, in short neighbor_id, in short behind, in short do_redraw);

	/*** SET TITLE INFORMATION OF A VIEW ***/
	long set_view_title(in unsigned short view_id, in string title);

	/*** DEFINE VIEW THAT IS USED AS DESKTOP BACKGROUND ***/
	long set_background(in unsigned short view_id);

	/*** CONFIGURE MOUSE BEHAVIOUR FOR A VIEW ***/
	long set_mousemode(in unsigned short view_id, in unsigned short mode);
};