/**
 * \file minigui.h
 * \author Wei Yongming <ymwei@minigui.org>
 * \date 2002/01/06
 * 
 * This file includes global and miscellaneous interfaces of MiniGUI.
 *
 \verbatim
    Copyright (C) 1998-2002 Wei Yongming.
    Copyright (C) 2002-2004 Feynman Software.

    This file is part of MiniGUI, a compact cross-platform Graphics 
    User Interface (GUI) support system for real-time embedded systems.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program 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 General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 \endverbatim
 */

/*
 * $Id: minigui.h,v 1.91 2004/07/30 05:51:22 panweiguo Exp $
 * 
 *             MiniGUI for Linux/uClinux, eCos, uC/OS-II, and VxWorks version 1.6.x
 *             Copyright (C) 1998-2002 Wei Yongming.
 *             Copyright (C) 2002-2004 Feynman Software.
 */

#ifndef _MGUI_MINIGUI_H
  #define _MGUI_MINIGUI_H

#include <stdio.h>
#ifndef _LITE_VERSION
  #include <pthread.h>
  #include <semaphore.h>
#endif

#ifdef __cplusplus
extern "C" {
#endif  /* __cplusplus */

    /**
     * \addtogroup global_vars Global variables
     * @{
     */

    /**
     * \defgroup rect_vars Global Rectangles
     * @{
     */

/**
 * \var RECT g_rcScr
 * \brief Contains the rectangle of the whole screen.
 */
extern RECT g_rcScr;         /* The RECT of screen. */

#if defined(_LITE_VERSION) && !defined(_STAND_ALONE)

/**
 * \var RECT g_rcDesktop
 * \brief Contains the rectangle of desktop of the application.
 *
 * \note Only available for MiniGUI-Lite as an actual global variable.
 * And \a g_rcDesktop is defined as an alias (macro) of \a g_rcScr for MiniGUI-Threads.
 *
 * \sa g_rcScr
 */
extern RECT g_rcDesktop;     /* The RECT of desktop. */

#else
#define g_rcDesktop     g_rcScr
#endif

    /** @} end of rect_vars */

    /**
     * \defgroup lite_vars MiniGUI-Lite specific variables
     * @{
     */

#if defined(_LITE_VERSION) && !defined(_STAND_ALONE)

#include <sys/types.h>

/**
 * \var BOOL mgIsServer
 * \brief Indicates whether the process is the server or a client on MiniGUI-Lite.
 *
 * \note Only defined for MiniGUI-Lite.
 */
extern BOOL mgIsServer;      /* Is the server or a client. */

/**
 * \var void* mgSharedRes
 * \brief Contains the pointer to the shared resource of MiniGUI-Lite.
 *
 * \note Not defined for MiniGUI-Threads, and the shared resource is
 * read-only for all clients.
 *
 * \sa mgSizeRes
 */
extern void* mgSharedRes;    /* The pointer to shared resource. */

/**
 * \var void* mgSizeRes
 * \brief Contains the length of shared resource of MiniGUI-Lite.
 *
 * \note Only defined for MiniGUI-Lite. 
 *
 * \sa mgSharedRes
 */
extern size_t mgSizeRes;     /* The size of shared resource. */

#define LEN_LAYER_NAME      14
#define LEN_CLIENT_NAME     14

#define INV_LAYER_HANDLE    0

/* variables only available for the server */

struct MG_Layer;

/** Client information. */
typedef struct MG_Client
{
    /** The name of the client. */
    char    name [LEN_CLIENT_NAME + 1];

    /** PID of the client process. */
    pid_t   pid;
    /** UID of the client process. */
    uid_t   uid;
    /** The file descriptor of the socket connected to the client. */
    int     fd;

    /** The desktop rectangle of the client. */
    RECT    rc;
    /** The last active tick count of the client. */
    DWORD   last_live_time;
    /** The additional data of the client. */
    DWORD   dwAddData;

    /** The pointer to the next client in the same layer. */
    struct  MG_Client* next;
    /** The pointer to the previous client in the same layer. */
    struct  MG_Client* prev;

    /** The pointer to the layer on which the client lays. */
    struct  MG_Layer* layer;

    struct GlobalRes* global_res;
} MG_Client;

struct _CLIPRGN;

/** Layer information. */
typedef struct MG_Layer
{
    /** The name of the layer. */
    char    name [LEN_LAYER_NAME + 1];

    /** The pointer to the list of clients which lay on the layer. */
    MG_Client* cli_head;
    /** The pointer to the active client on the layer. */
    MG_Client* cli_active;
    /** The additional data of the layer. */
    DWORD   dwAddData;

    /** The pointer to the next layer. */
    struct MG_Layer* next;
    /** The pointer to the previous layer. */
    struct MG_Layer* prev;

    /** The pointer to the region contains the spare rectangles of the layer. */
    struct _CLIPRGN* spare_rects;
} MG_Layer;

/**
 * \var int mgClientSize
 * \brief The current size of the array \a mgClients.
 *
 * \sa mgClients
 */
extern int mgClientSize;

/**
 * \var MG_Client* mgClients
 * \brief The pointer to the array contains all clients' information.
 *
 * You can access the elements in \a mgClients as a normal array. If the 
 * field \a fd of one element is not less than zero, then the element
 * will be a vaild client.
 *
 * \sa MG_Client
 */
extern MG_Client* mgClients;

/**
 * \var MG_Layer* mgTopmostLayer
 * \brief The pointer to the topmost layer.
 *
 * \sa MG_Layer
 */
extern MG_Layer* mgTopmostLayer;

/**
 * \var MG_Layer* mgLayers
 * \brief The pointer to the list of layers.
 *
 * \sa MG_Layer
 */
extern MG_Layer* mgLayers;

#endif /* _LITE_VERSION && !_STAND_ALONE */

    /** @} end of lite_vars */

    /** @} end of global_vars */

#ifndef _LITE_VERSION
BOOL GUIAPI InitGUI (void);
void GUIAPI TerminateGUI (int rcByGUI);
void GUIAPI MiniGUIPanic (int exitcode);
#endif

    /**
     * \addtogroup fns Functions
     * @{
     */

    /**
     * \addtogroup global_fns Global/general functions
     * @{
     */

    /**
     * \defgroup lite_fns MiniGUI-Lite specific functions
     * @{
     */

#ifdef _LITE_VERSION

    /**
     * \defgroup lite_listenfd_fns Listening a file descriptor
     *
     * Register/Unregister a listen fd to MiniGUI.
     *
     * When you need to listen a file descriptor, you can use \a select(2)
     * system call. In MiniGUI, you can also register it to MiniGUI to 
     * be a listened fd, and when there is a read/write/except event on 
     * the registered fd , MiniGUI will sent a notification message to 
     * the registered window.
     *
     * Example:
     *
     * \include listenfd.c
     *
     * @{
     */

#define MAX_NR_LISTEN_FD   5

/** 
 * \fn BOOL GUIAPI RegisterListenFD (int fd, int type, HWND hwnd, void* context)
 * \brief Registers a listened file descriptor to MiniGUI-Lite.
 * This function registers the file desciptor \a fd to MiniGUI-Lite for listening.
 *
 * When there is a read/write/except event on this \a fd, MiniGUI
 * will post a MSG_FDEVENT message with wParam being equal to
 * MAKELONG (fd, type), and the lParam being set to \a context
 * to the target window.
 *
 * \param fd The file descriptor to be listened.
 * \param type The type of the event to be listened, can be POLLIN, POLLOUT, or POLLERR.
 * \param hwnd The handle to the window will receive MSG_FDEVENT message.
 * \param context The value will be passed to the window as lParam of MSG_FDEVENT message.
 * \return TRUE if all OK, and FALSE on error.
 *
 * \note Only available on MiniGUI-Lite.
 *
 * \sa UnregisterListenFD, system_msgs
 */
BOOL GUIAPI RegisterListenFD (int fd, int type, HWND hwnd, void* context);

/** 
 * \fn BOOL GUIAPI UnregisterListenFD (int fd)
 * \brief Unregisters a being listened file descriptor.
 *
 * This function unregisters the being listened file descriptor \a fd.
 *
 * \param fd The file descriptor to be unregistered, should be a being 
 *        listened file descriptor.
 * \return TRUE if all OK, and FALSE on error.
 *
 * \note Only available on MiniGUI-Lite.
 *
 * \sa RegisterListenFD
 */
BOOL GUIAPI UnregisterListenFD (int fd);

    /** @} end of lite_listenfd_fns */

#ifdef _STAND_ALONE

#define SetDesktopRect(lx, ty, rx, by) {}

#else

    /**
     * \defgroup lite_layer_fns Layer operations
     *
     * A client in MiniGUI-Lite can create a new layer or join an existed layer 
     * in order to get the visible desktop rectangle on the screen of it.
     *
     * Example:
     *
     * \include client_startup.c
     *
     * @{
     */

/** 
 * \fn GHANDLE GUIAPI JoinLayer (const char* layer_name, const char* client_name, int lx, int ty, int rx, int by)
 * \brief Joins to a layer.
 *
 * This function should be called by clients before calling any other MiniGUI
 * functions. You can call \a GetLayerInfo to get the layer information.
 * If the layer to be joined does not exist, the server, i.e. \a mginit, will
 * try to create a new one. If you passed a NULL pointer or a null string for 
 * \a layer_name, a new layer will be created as well.
 *
 * For the server of MiniGUI-Lite, this function will ignore the arguments of
 * \a layer_name and \a client_name. The rectangle defines a region in the 
 * screen, which is exclusively used by the server, no client can output
 * to this exclusive retangle.
 *
 * The server usually calls SetDesktopRect macro, which is defined as
 * the following:
 *
 * \code
 *
 * #define SetDesktopRect(lx, ty, rx, by) JoinLayer ("", "", lx, ty, rx, by)
 *
 * \endcode
 * 
 * Note that the server can define the exclusive retangle out of the actual
 * screen range.
 * 
 * \param layer_name The name of the layer.
 * \param client_name The name of the client.
 * \param lx lx,ty,rx,by: The expected desktop rect of the client.
 * \param ty lx,ty,rx,by: The expected desktop rect of the client.
 * \param rx lx,ty,rx,by: The expected desktop rect of the client.
 * \param by lx,ty,rx,by: The expected desktop rect of the client.
 * \return The handle to the layer on success, INV_LAYER_HANDLE on error.
 *
 * \sa GetLayerInfo, GetDesktopRect, ServerStartup
 */
GHANDLE GUIAPI JoinLayer (const char* layer_name, const char* client_name, 
                int lx, int ty, int rx, int by);

#define SetDesktopRect(lx, ty, rx, by) \
        JoinLayer ("", "", lx, ty, rx, by)

/** 
 * \fn void GUIAPI GetDesktopRect (int* lx, int* ty, int* rx, int* by)
 * \brief Gets the desktop rectangle.
 *
 * After joined to a layer, client can call this function to get the
 * actual desktop rect of itself. 
 *
 * \param lx lx,ty,rx,by: The desktop rect will be returned through these pointers.
 * \param ty lx,ty,rx,by: The desktop rect will be returned through these pointers.
 * \param rx lx,ty,rx,by: The desktop rect will be returned through these pointers.
 * \param by lx,ty,rx,by: The desktop rect will be returned through these pointers.
 *
 * \sa JoinLayer
 */
void GUIAPI GetDesktopRect (int* lx, int* ty, int* rx, int* by);

#define NAME_SELF_LAYER     ""

/** 
 * \fn GHANDLE GUIAPI GetLayerInfo (const char* layer_name, RECT* max_rect, int* nr_clients, BOOL* is_topmost, int* cli_active)
 * \brief Gets information of a layer.
 *
 * You can get the information of a layer through this function. 
 * The information will be returned through the pointer arguments