/**
 * \fn int GUIAPI ShowCursor (BOOL fShow)
 * \brief Shows or hides cursor.
 *
 * This function shows or hides cursor according to the argument \a fShow.
 * Show cursor when \a fShow is TRUE, and hide cursor when \a fShow is FALSE.
 * MiniGUI maintains a showing count value. Calling \a ShowCursor once, the
 * count will increase when \a fShow is TRUE, or decrease one when FALSE.
 * When the count is less than 0, the cursor will disapear actually.
 *
 * \param fShow Indicates show or hide the cursor.
 *
 * \return Cursor showing count value.
 */
MG_EXPORT int GUIAPI ShowCursor (BOOL fShow);

/**
 * \fn int ClientRequest (const REQUEST* 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.
 *
 * This function is a simplified version of ClientRequestEx, i.e.
 * there is no extra data to be sent.
 *
 * \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-Processes.
 *
 * \sa ClientRequestEx, ServerSendReply
 */
static inline int ClientRequest (const REQUEST* request,
                void* result, int len_rslt)


/**
 * \fn int GUIAPI ServerSendReply (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 ClientRequest, RegisterRequestHandler
 */
MG_EXPORT int GUIAPI ServerSendReply (int clifd, const void* reply, int len);



/**
 * \fn int serv_listen (const char* name)
 * \brief Creates a listen socket.
 *
 * This function is used by the server to create a listening socket.
 * Any MiniGUI-Processes application can call this function to create a
 * listening socket. The server, i.e. \a mginit, of MiniGUI-Processes uses
 * this function to create its listening socket, and named the socket
 * to '/var/tmp/minigui'.
 *
 * \param name The path name of the listening socket.
 * \return The file discriptor of the listening socket created, -1 on error.
 *
 * \note As a convention, you should located the socket in '/var/tmp/'
 * directory.
 */
MG_EXPORT int serv_listen (const char* name);

/**
 * \fn int serv_accept (int listenfd, pid_t *pidptr, uid_t *uidptr)
 * \brief Waits for a client connection to arrive, and accept it.
 *
 * This function is used by the server to wait a connection and accept it.
 *
 * After creating a listening socket by calling \a serv_listen, you can
 * call this function to create a connection with a client. We also obtain
 * the client's PID and UID from the pathname that it must bind before
 * calling us.
 *
 * \param listenfd The fd of listen socket.
 * \param pidptr The client PID will be saved to this buffer when this
 *        function returns.
 * \param uidptr The client UID will be saved to this buffer when this
 *        function returns.
 *
 * \return The new connected fd if all OK, < 0 on error.
 *
 * \sa serv_listen, cli_conn
 */
MG_EXPORT int serv_accept (int listenfd, pid_t *pidptr, uid_t *uidptr);

/**
 * \fn int cli_conn (const char* name, char project)
 * \brief Used by clients to connect to a server.
 *
 * This function is used by clients to connect to a server.
 *
 * The created socket will be located at the directory '/var/tmp',
 * and with name of '/var/tmp/xxxxx-c', where 'xxxxx' is the pid of client.
 * and 'c' is a character to distinguish different projects.
 *
 * Note that MiniGUI itself uses 'a' as the project character to
 * create socket between 'mginit' and clients.
 *
 * \param name The name of the well-known listen socket (created by server).
 * \param project A character to distinguish different projects
 *        (Do \em NOT use 'a').
 * \return The new connected fd if all OK, < 0 on error.
 *
 * \sa serv_listen, serv_accept
 */
MG_EXPORT int cli_conn (const char* name, char project);

#define SOCKERR_IO          -1
#define SOCKERR_CLOSED      -2
#define SOCKERR_INVARG      -3
#define SOCKERR_TIMEOUT     -4
#define SOCKERR_OK          0

/**
 * \fn int sock_write_t (int fd, const void* buff,\
                int count, unsigned int timeout)
 * \brief Writes data to socket.
 *
 * This function writes the data block pointed to by \a buff
 * which is \a count bytes long to the socket \a fd.
 *
 * \param fd The file descriptor of the socket.
 * \param buff The buffer contains the data.
 * \param count The length in bytes of the buffer.
 * \param timeout An upper bound on the amount of time elapsed before
 *        \a sock_write_t returns. When it is zero, \a sock_write_t can
 *        block indefinitely. The timeout value is in tick count, and
 *        tick count of MiniGUI is in unit of 10 milliseconds.
 * \return SOCKERR_OK if all OK, < 0 on error.
 *
 * \retval SOCKERR_OK       Read data successfully.
 * \retval SOCKERR_IO       There are some I/O errors occurred.
 * \retval SOCKERR_CLOSED   The socket has been closed by the peer.
 * \retval SOCKERR_INVARG   You passed invalid arguments.
 * \retval SOCKERR_TIMEOUT  Timeout.
 *
 * \note The \a timeout only goes into effect when this function called
 *       by the server of MiniGUI-Processes, i.e. \a mginit.
 *
 * \sa sock_read_t
 */
MG_EXPORT int sock_write_t (int fd, const void* buff,
                int count, unsigned int timeout);

/**
 * \fn int sock_read_t (int fd, void* buff, int count, unsigned int timeout)
 * \brief Reads data from socket.
 *
 * This function reads data which is \a count bytes long to the buffer \a buff
 * from the socket \a fd.
 *
 * \param fd The file descriptor of the socket.
 * \param buff The buffer used to save the data.
 * \param count The length in bytes of the buffer.
 * \param timeout An upper bound on the amount of time elapsed before
 *        \a sock_read_t returns. When it is zero, \a sock_read_t can
 *        block indefinitely. The timeout value is in the tick count of MiniGUI,
 *        and tick count of MiniGUI is in unit of 10 milliseconds.
 * \return SOCKERR_OK if all OK, < 0 on error.
 *
 * \retval SOCKERR_OK       Read data successfully.
 * \retval SOCKERR_IO       There are some I/O errors occurred.
 * \retval SOCKERR_CLOSED   The socket has been closed by the peer.
 * \retval SOCKERR_INVARG   You passed invalid arguments.
 * \retval SOCKERR_TIMEOUT  Timeout.
 *
 * \note The \a timeout only goes into effect when this function called
 *       by the server of MiniGUI-Processes, i.e. \a mginit.
 *
 * \sa sock_write_t
 */
MG_EXPORT int sock_read_t (int fd, void* buff, int count, unsigned int timeout);

/**
 * \def sock_write(fd, buff, count)
 * \brief The blocking version of \a sock_write_t function.
 *
 * \sa sock_write_t
 */
#define sock_write(fd, buff, count) sock_write_t(fd, buff, count, 0)

/**
 * \def sock_read(fd, buff, count)
 * \brief The blocking version of \a sock_read_t function.
 *
 * \sa sock_read_t
 */
#define sock_read(fd, buff, count) sock_read_t(fd, buff, count, 0)

/**
 * \fn BOOL GUIAPI SaveScreenRectContent (const RECT* rc, \
                const char* filename)
 * \brief Saves content of a rectangle in the screen to a file.
 *
 * This function saves the content of the rect \a rc to the image
 * file \a filename. MiniGUI uses the extension name of the file to
 * determine the format of the image file.
 *
 * \param rc The RECT object defined the rectangle in the screen.
 * \param filename The name of the image file.
 *
 * \return TRUE on success, otherwise FALSE.
 *
 * \note Only defined for _MGMISC_SAVESCREEN.
 *
 * \sa bmp_load_fns
 */
MG_EXPORT BOOL GUIAPI SaveScreenRectContent (const RECT* rcWin,
                const char* filename);

/**
 * \fn BOOL GUIAPI InvalidateRect (HWND hWnd, const RECT* prc, BOOL bEraseBkgnd)
 * \brief Makes a rectangle region in the client area of a window invalid.
 *
 * This function adds a rectangle pointed to by \a prc to the specified
 * window's update region. The update region represents the portion of
 * the window's client area that must be redrawn, and erase background
 * if argument \a bReaseBkgnd is set.
 *
 * \param hWnd The handle to the window.
 * \param prc The pointer to a RECT structure which defines the
 *        invalid rectangle.
 * \param bEraseBkgnd Indicates whether the background should be erased.
 *
 * \return TRUE on success, otherwise FALSE.
 *
 * \sa MSG_PAINT
 */
MG_EXPORT BOOL GUIAPI InvalidateRect (HWND hWnd,
                const RECT* prc, BOOL bEraseBkgnd);