minigui.h

这是ARM嵌入式系统的实验教程中的MINIGUI的实验源代码！

 * \param nr_clients The number of clients in the layer will be returned through this pointer.
 * \param is_topmost A boolean which indicates whether the layer is the topmost layer will be returned.
 * \param cli_active The identifier of the active client in the layer.
 * \return Returns the handle to the layer on success, INV_LAYER_HANDLE on error.
 *
 * \sa JoinLayer
 */
MG_EXPORT GHANDLE GUIAPI GetLayerInfo (const char* layer_name, RECT* max_rect, 
                int* nr_clients, BOOL* is_topmost, int* cli_active);

/** 
 * \fn BOOL GUIAPI BringLayer2Topmost (GHANDLE handle)
 * \brief Brings a layer to be the topmost one.
 *
 * This function brings the specified layer \a handle to be the topmost layer.
 *
 * \param handle The handle to the layer.
 * \return TRUE on success, otherwise FALSE.
 *
 * \sa SetActiveClient
 */
MG_EXPORT BOOL GUIAPI BringLayer2Topmost (GHANDLE handle);

/** 
 * \fn BOOL GUIAPI SetActiveClient (int active)
 * \brief Sets a client as the ative one.
 *
 * This function sets the specified client \a active to be the active one.
 * It also bring the layer in which the client lays to be the topmost as well.
 *
 * \param active The identifier of the client.
 * \return TRUE on success, otherwise FALSE.
 *
 * \sa BringLayer2Topmost
 */
MG_EXPORT BOOL GUIAPI SetActiveClient (int active);

    /** @} end of lite_layer_fns */

    /**
     * \defgroup lite_server_fns Server-only operations
     *
     * MiniGUI provides some server-only functions for you to create a
     * customized server for MiniGUI-Lite, i.e. \a mginit.
     *
     * Example:
     *
     * \include server_startup.c
     *
     * @{
     */

#define LCO_NEW_CLIENT      1
#define LCO_DEL_CLIENT      2

/**
 * \var typedef void (* ON_NEW_DEL_CLIENT) (int op, int cli)
 * \brief Client event callback.
 *
 * \sa OnNewDelClient, OnChangeLayer
 */
typedef void (* ON_NEW_DEL_CLIENT) (int op, int cli);

#define LCO_NEW_LAYER       1
#define LCO_DEL_LAYER       2
#define LCO_JOIN_CLIENT     3
#define LCO_REMOVE_CLIENT   4
#define LCO_TOPMOST_CHANGED 5
#define LCO_ACTIVE_CHANGED  6

/**
 * \var typedef void (* ON_CHANGE_LAYER) (int op, MG_Layer* layer, MG_Client* client)
 * \brief Layer event callback.
 *
 * \sa OnNewDelClient, OnChangeLayer
 */
typedef void (* ON_CHANGE_LAYER) (int op, MG_Layer* layer, MG_Client* client);

/**
 * \var ON_NEW_DEL_CLIENT OnNewDelClient
 * \brief Sets to a function to handle a comming in/going away connection of client.
 *
 * When a client is connecting to or disconnecting from the server, MiniGUI
 * will call this function to tell you the event and the client identifier. 
 * The event could be one of the following:
 *
 *  - LCO_NEW_CLIENT\n
 *    A new client is connecting to the server.
 *  - LCO_DEL_CLIENT\n
 *    A new client is disconnecting from the server.
 *
 * The event will be passed through the argument of \a op, and the client
 * identifier will be passed through the argument of \a cli.
 * You can get the information of the client by accessing \a mgClients with \a cli.
 *
 * \note Only available for the server of MiniGUI-Lite.
 * 
 * \sa ON_NEW_DEL_CLIENT, mgClients
 */
extern ON_NEW_DEL_CLIENT OnNewDelClient;

/**
 * \var ON_CHANGE_LAYER OnChangeLayer
 * \brief Sets to a function to handle events of layers.
 *
 * When a layer is changing, MiniGUI will call this function to tell 
 * you the event and the layer or the client which leads to the event.
 * The event could be one of the following:
 *
 *  - LCO_NEW_LAYER\n
 *    A new layer is creating.
 *  - LCO_DEL_LAYER\n
 *    A new layer is deleting.
 *  - LCO_JOIN_CLIENT\n
 *    A client is joining to the layer.
 *  - LCO_REMOVE_CLIENT\n
 *    A client is removing from the layer.
 *  - LCO_TOPMOST_CHANGED\n
 *    The topmost layer changed, the layer will be the topmost one.
 *  - LCO_ACTIVE_CHANGED\n
 *    The active client changed, the client will be the active one.
 *
 * The event will be passed through the argument of \a op, and the pointers to the relevant
 * layer and client will be passed through the argument of \a layer and \a client respectively.
 *
 * \note Only available for the server of MiniGUI-Lite.
 * 
 * \sa ON_NEW_DEL_CLIENT, mgClients
 */
extern ON_CHANGE_LAYER OnChangeLayer;

/** 
 * \fn BOOL GUIAPI ServerStartup (void)
 * \brief Initializes the server of MiniGUI-Lite.
 *
 * This function initializes the server, i.e. \a mginit. It creates
 * the shared resource, the listening socket, and other internal objects.
 * Your costomized \a mginit program should call this function before calling
 * any other function.
 *
 * \return TRUE on success, otherwise FALSE.
 *
 * \note Server-only function, i.e. \em only can be called by \a mginit.
 */
MG_EXPORT BOOL GUIAPI ServerStartup (void);

/** 
 * \fn BOOL SetClientScreen (int lx, int ty, int rx, int by)
 * \brief Sets the screen rectangle can be used by clients.
 *
 * This function sets the screen rectangle can be used by clients.
 * All clients' drawing will be clipped out of the rectangle.
 *
 * The rectangle set by this function should be a subrectangle of
 * the server's exclusive rectangle defined by \a SetDesktopRect.
 *
 * \param lx lx,ty,rx,by: Specifies the screen rectangle.
 * \param ty lx,ty,rx,by: Specifies the screen rectangle.
 * \param rx lx,ty,rx,by: Specifies the screen rectangle.
 * \param by lx,ty,rx,by: Specifies the screen rectangle.
 * \return TRUE on success, otherwise FALSE.
 *
 * \note Server-only function, i.e. \em ONLY can be called by \a mginit.
 *
 * \note This function do nothing in MiniGUI v1.5.x and later.
 *
 * \sa JoinLayer
 */
static inline BOOL SetClientScreen (int lx, int ty, int rx, int by)
{
    return TRUE;
}

/** 
 * \fn BOOL GUIAPI OnlyMeCanDraw (void)
 * \brief Tells clients do not draw anything on screen.
 *
 * If the server want to output something out of its exclusive rectangle,
 * it can call this function to disable the clients' any drawing output.
 * When the server done, it can call \a ClientCanDrawNowEx function
 * to tell clients in the topmost layer to repaint themselves.
 *
 * Note that the clients is still running after the server calling 
 * this function.
 * 
 * \return TRUE on success, otherwise FALSE.
 *
 * \note Server-only function.
 *
 * \sa ClientCanDrawNowEx, ClientCanDrawNow
 */
MG_EXPORT BOOL GUIAPI OnlyMeCanDraw (void);

/** 
 * \fn BOOL GUIAPI ClientCanDrawNowEx (BOOL bRepaint, const RECT* invrc)
 * \brief Tells clients that they can output to screen now.
 *
 * \param bRepaint Whether to repaint the clients in the topmost layer.
 * \param invrc The invalid screen rect. It can be NULL, 
 *        indicates the whole desktop of clients should be repainted.
 * \return TRUE on success, otherwise FALSE.
 *
 * \note Server-only function.
 *
 * \sa OnlyMeCanDraw, ClientCanDrawNow
 */
MG_EXPORT BOOL GUIAPI ClientCanDrawNowEx (BOOL bRepaint, const RECT* invrc);

/** 
 * \def ClientCanDrawNow()
 * \brief Tells clients that they can output to screen now, and 
 *        notify clients to repaint the whole desktop.
 *
 * \return TRUE on success, otherwise FALSE.
 *
 * \note Server-only function, and defined as a macro 
 *       calling \a ClientCanDrawNowEx with \a bRepaint is TRUE and \a invrc is NULL.
 *
 * \sa ClientCanDrawNowEx
 */
#define ClientCanDrawNow()    ClientCanDrawNowEx (TRUE, NULL)

/**
 * \fn void GUIAPI UpdateTopmostLayer (const RECT* dirty_rc)
 * \brief Tells the clients in the topmost layer to update their windows.
 *
 * \param dirty_rc The dirty rectangle in screen coordinate system.
 *
 * \note Server-only function.
 *
 * \sa OnlyMeCanDraw, ClientCanDrawNowEx
 */
MG_EXPORT void GUIAPI UpdateTopmostLayer (const RECT* dirty_rc);

/** 
 * \fn BOOL GUIAPI SetTopMostClient (int cli)
 * \brief Sets topmost layer by a client identifier.
 *
 * This function sets the topmost layer by the specified client identifier \a cli.
 * It will bring the layer contains the client to be the topmost one.
 *
 * \param cli The identifier of the client.
 * \return TRUE on success, otherwise FALSE.
 *
 * \note Server-only function.
 *
 * \sa SetTopMostLayer, BringLayer2Topmost
 */
MG_EXPORT BOOL GUIAPI SetTopMostClient (int cli);

/** 
 * \fn BOOL GUIAPI SetTopMostLayer (MG_Layer* layer)
 * \brief Sets topmost layer.
 *
 * This functions sets the specified layer \a layer to be the topmost layer.
 *
 * \param layer The pointer to the layer.
 * \return TRUE on success, otherwise FALSE.
 *
 * \note Server-only function.
 *
 * \sa SetTopMostClient, BringLayer2Topmost
 */
MG_EXPORT BOOL GUIAPI SetTopMostLayer (MG_Layer* layer);

/** 
 * \fn int GUIAPI GetClientByPID (int pid)
 * \brief Returns the client identifier from PID of a client.
 *
 * This function gets the identifier of the sepcified client from the PID of it.
 *
 * \param pid The process ID of the client.
 * \return The client identifier on success, less than 0 on error.
 *
 * \note Server-only function.
 */
MG_EXPORT int GUIAPI GetClientByPID (int pid);

    /** @} end of lite_server_fns */

    /**
     * \defgroup lite_request_fns Simple request/reply interfaces
     * 
     * You can register a customized request handler to extend your server, i.e. 
     * \a mginit, of MiniGUI-Lite.
     *
     * A request consists of an identifier and the data associated with the request.
     * The identifier is used by MiniGUI to determine which handler should be called
     * when a request arrives. When MiniGUI finds one handler, it will call the handler
     * and pass the socket fd connected to the client, the data associated with the request,
     * and the length of the data. Eventually, the handler will sent the reply to
     * the client.
     *
     * After register a customized request handler in your server, you can call 
     * \a cli_request function in the client to send a request to 
     * the server and wait for the reply. On the other hand, the request handler in the server
     * will receive the request and call \a send_reply to send the reply to the client.
     * In this way, you can create a simple IPC (inter-process conmmunication) 
     * mechanism between clients and the server.
     *
     * Example:
     *
     * \include request.c
     *
     * @{
     */

/**
 * \def MAX_SYS_REQID
 * \brief Maximal system reserved request identifier.
 *
 * \sa RegisterRequestHandler
 */
#define MAX_SYS_REQID           0x0011

/**
 * \def MAX_REQID
 * \brief Maximal request identifier.
 *
 * \sa RegisterRequestHandler
 */
#define MAX_REQID               0x0018

/** A request will be sent to the server of MiniGUI-Lite. */
typedef struct _REQUEST {
    /** The identifier of the type of the request. */
    int id;
    /** The data will be sent to the server. */
    const void* data;
    /** The length of the data. */
    size_t len_data;
} REQUEST;
typedef REQUEST* PREQUEST;

/** 
 * \fn cli_request (PREQUEST request, void* result, int len_rslt)
 * \brief Sends a request to the server and wait reply.
 *
 * If \a result is NULL or \a len_rslt is zero, the function will return 
 * immediately after sent the data to the server.
 *
 * \param request The pointer to REQUEST, which contains the data of the request.
 * \param result The buffer receives the reply.
 * \param len_rslt The lenght of the buffer.
 * \return Zero on success, no-zero on error.
 *
 * \note Only used by clients to send a request to the server of MiniGUI-Lite.
 *
 * \sa send_reply
 */
int cli_request (PREQUEST request, void* result, int len_rslt);

/** 
 * \fn int get_sock_fd2srv (void)
 * \brief Gets the file descriptor of the socket connected to the server.
 *
 * This function returns the file descriptor of the socket connected to the server,
 * i.e. \a mginit.
 *
 * \return The file descriptor of the socket connected to the server.
 *
 * \note Only used by clients, no meaning for the server.
 */
int get_sock_fd2srv (void);

/** 
 * \fn send_reply (int clifd, const void* reply, int len)
 * \brief Sends the reply to the client.
 *
 * This function sends a replay pointed to by \a reply which is 
 * \a len bytes long to the client.
 *
 * \note Only used by the server to send the reply to the client.
 * This function typically called in your customized request handler.
 *
 * \param clifd The fd connected to the client.
 * \param reply The buffer contains the reply data.
 * \param len The length of the reply data in bytes.
 * \return Zero on success, no-zero on error.
 *
 * \sa cli_request, RegisterRequestHandler
 */
int send_reply (int clifd, const void* reply, int len);

/**
 * \var typedef int (* REQ_HANDLER)(int cli, int clifd, void* buff, size_t len)
 * \brief Request handler.
 *
 * \sa RegisterRequestHandler
 */
typedef int (* REQ_HANDLER) (int cli, int clifd, void* buff, size_t len);

/** 
 * \fn BOOL GUIAPI RegisterRequestHandler (int req_id, REQ_HANDLER your_handler)
 * \brief Registers a customize request handler.
 *
 * This function registers a request handler to the server, i.e. \a mginit.
 *
 * \param req_id The identifier of the customized request.
 * \param your_handler The handler of the request. Being NULL to unregister the request handler.
 * \return TRUE on success, FALSE on error.
 *
 * \note Only used by the server to register a request handler.
 *       And the identifier should be larger than \a MAX_SYS_REQID and 
 *       less than or equal to \a MAX_REQID.
 *
 * \sa cli_request, send_reply, MAX_SYS_REQID, MAX_REQID