minigui.h

2410开发板上的ucos开发实例

 * This function returns the request handler of the specified request identifier \a req_id.
 *
 * \param req_id The request identifier.
 * \return The handler on success, NULL on error.
 *
 * \note Only can be used by the server.
 *
 * \sa RegisterRequestHandler
 */
REQ_HANDLER GUIAPI GetRequestHandler (int req_id);

    /** @} end of lite_request_fns */

    /**
     * \defgroup lite_socket_fns General socket operations
     *
     * MiniGUI-Lite uses UNIX domain socket to build the communication
     * between the server and the clients.
     *
     * You can also use the underlay interfaces which MiniGUI uses to create
     * your own UNIX domain socket.
     *
     * Example:
     *
     * \include socket.c
     *
     * @{
     */

/**
 * \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-Lite application can call this function to create a 
 * listening socket. The server, i.e. \a mginit, of MiniGUI-Lite 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.
 */
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
 */
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.
 * 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
 */
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-Lite, i.e. \a mginit. 
 *
 * \sa sock_read_t
 */
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-Lite, i.e. \a mginit. 
 *
 * \sa sock_write_t
 */
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)

    /** @} end of lite_socket_fns */

    /** @} end of lite_fns */

#endif /* !_STAND_ALONE */
#endif /* LITE_VERSION */

    /**
     * \defgroup init_fns Initialization and termination functions
     *
     * Normally, the only entry of any MiniGUI application is \a MiniGUIMain.
     * The application will terminate when you call \a exit(3) or just return from
     * \a MiniGUIMain.
     *
     * Example 1:
     *
     * \include miniguimain.c
     *
     * Example 2:
     *
     * \include hello_world.c
     *
     * @{
     */

/**
 * \fn BOOL GUIAPI ReinitDesktopEx (BOOL init_sys_text)
 * \brief Re-initializes the desktop.
 *
 * When you changed the charset or the background picture of the desktop,
 * you should call this function to re-initialize the local system text
 * (when \a init_sys_text is TRUE), the background picture, and the desktop
 * menu.
 *
 * \param init_sys_text Indicates whether to initialize the local system text.
 *
 * \return TRUE on success, otherwise FALSE.
 *
 * \sa ReinitDesktop
 */
BOOL GUIAPI ReinitDesktopEx (BOOL init_sys_text);

/**
 * \def ReinitDesktop()
 * \brief Re-initializes the desktop including the local system text.
 *
 * \return TRUE on success, otherwise FALSE.
 *
 * \note This function defined as a macro calling \a ReinitDesktopEx with
 * \a init_sys_text set to TRUE.
 *
 * \sa ReinitDesktopEx
 */
#define ReinitDesktop()    ReinitDesktopEx (TRUE)

/*
 * We remove the SuspendGUI and ResumeGUI functions. 
 * Don't use these two functios any more.
 * void GUIAPI SuspendGUI (void);
 * BOOL GUIAPI ResumeGUI (void); 
 */

/**
 * \fn void GUIAPI ExitGUISafely (int exitcode)
 * \brief Exits your MiniGUI application safely.
 *
 * Calling this function will terminate your MiniGUI application. This
 * function will restore console attributes and call \a exit() function and 
 * pass \a exitcode to it.
 *
 * \param exitcode The exit status will be passed to exit(3) function.
 * \return This function does not return.
 *
 * \sa exit(3)
 */
void GUIAPI ExitGUISafely (int exitcode);

/**
 * \fn int MiniGUIMain (int args, const char* arg[])
 * \brief The main entry of all MiniGUI applications.
 *
 * This function should be defined by your application. MiniGUI defines \a main()
 * function in libminigui library for your application, and call \a MiniGUIMain() 
 * in this \a main() function. The \a main() defined by MiniGUI is responsible of 
 * initializing and terminating MiniGUI.
 *
 * \param args The number of arguments passed to \a main() by operating system.
 * \param arg The arguments passed to \a main() by operating system.
 * \return The exit status will be retured to the parent process.
 *
 */
int MiniGUIMain (int args, const char* arg[]);

#ifndef _LITE_VERSION
/*
 * NOTE: The following two functions is only valid for MiniGUI-Threads
 * since version 1.0.01.
 */
BOOL GUIAPI PreInitGUI (int args, const char* arg[], int* retp);
int GUIAPI PostTerminateGUI (int args, const char* arg[], int rcByGUI); 
#endif /* LITE_VERSION */

#define IDM_DTI_FIRST   (300)

#ifndef _LITE_VERSION
/*
 * NOTE: The following two functions is only valid for MiniGUI-Threads
 * since version 1.0.01.
 */
void GUIAPI CustomizeDesktopMenu (HMENU hDesktopMenu, int iPos);
int GUIAPI CustomDesktopCommand (int id);
#endif

    /** @} end of init_fns */

    /**
     * \defgroup about_dlg About MiniGUI dialog
     * @{
     */
#ifdef _MISC_ABOUTDLG
#ifndef _LITE_VERSION
  void GUIAPI OpenAboutDialog (void);
#else

/**
 * \fn HWND GUIAPI OpenAboutDialog (HWND hHosting)
 * \brief Opens or actives the 'About MiniGUI' dialog.
 *
 * Calling this function will create a main window displaying 
 * copyright and license information of MiniGUI. When the about dialog 
 * is displaying, calling this function again will bring the dialog to be 
 * the topmost main window, not create a new one.
 *
 * \param hHosting The hosting main window of the about dialog.
 * \return The handle to the about dialog box.
 *
 * \note This function is available for MiniGUI-Lite and when _MISC_ABOUTDLG defined.
 * For MiniGUI-Threads, you should call 'void GUIAPI OpenAboutDialog (void)' function
 * instead.
 */
  HWND GUIAPI OpenAboutDialog (HWND hHosting);
#endif /* _LITE_VERSION */
#endif /* _MISC_ABOUTDLG */

    /** @} end of about_dlg */

    /**
     * \defgroup etc_fns Configuration file operations
     *
     * The configuration file used by MiniGUI have a similiar format as M$ Windows INI file,
     * i.e. the file consists of sections, and the section consists of key-value pairs, like this:
     *
     * \code
     * [system]
     * # GAL engine
     * gal_engine=fbcon
     *
     * # IAL engine
     * ial_engine=console
     *
     * mdev=/dev/mouse
     * mtype=PS2
     * 
     * [fbcon]
     * defaultmode=1024x768-16bpp
     * 
     * [qvfb]
     * defaultmode=640x480-16bpp
     * display=0
     * \endcode
     *
     * Assume that the configuration file named \a my.cfg, if you want get the value of \a mdev
     * in \a system section, you can call \a GetValueFromEtcFile in the following way:
     *
     * \code
     * char buffer [51];
     *
     * GetValueFromEtcFile ("my.cfg", "system", "mdev", buffer, 51);
     * \endcode
     *
     * Example:
     *
     * \include cfgfile.c
     *
     * @{
     */

#define ETC_MAXLINE             1024
#define ETC_FILENOTFOUND        -1
#define ETC_SECTIONNOTFOUND     -2
#define ETC_KEYNOTFOUND         -3
#define ETC_TMPFILEFAILED       -4
#define ETC_FILEIOFAILED        -5
#define ETC_INTCONV             -6
#define ETC_OK                  0

#ifndef _INCORE_RES

/**
 * \var char* ETCFILEPATH
 * \brief The path name of MiniGUI configuration file.
 *
 * By default, the configuration file of MiniGUI must be installed in /etc,
 * /usr/local/etc or your home directory. When you install it in your
 * home directory, the name should be ".MiniGUI.cfg".
 *
 * MiniGUI will try to use \a ~/.MiniGUI.cfg, then \a /usr/local/etc/MiniGUI.cfg, 
 * and \a /etc/MiniGUI.cfg last.
 *
 * If MiniGUI can not find any \a MiniGUI.cfg file, or find a bad formated configure
 * file, the initialzation of MiniGUI will be canceled.
 */
extern char ETCFILEPATH [];

#endif /* _INCORE_RES */

/**
 * \fn int GUIAPI GetValueFromEtcFile (const char* pEtcFile, const char* pSection, const char* pKey, char* pValue, int iLen)
 * \brief Gets value from a configuration file.
 *
 * This function gets the value of the key \a pKey in the section \a pSection 
 * of the configuration file \a pEtcFile, and saves the value to the buffer
 * pointed to by \a pValue. 
 *
 * \param pEtcFile The path name of the configuration file.
 * \param pSection The section name in which the value located.
 * \param pKey The key name of the value.
 * \param pValue The value will be saved in this buffer.
 * \param iLen The length in bytes of the buffer.
 * \return ETC_OK on success, < 0 on error.
 *
 * \retval ETC_OK               Gets value successfullly.
 * \retval ETC_FILENOTFOUND     Can not find the specified configuration file.
 * \retval ETC_SECTIONNOTFOUND  Can not find the specified section in the configuration file.
 * \retval ETC_KEYNOTFOUND      Can not find the specified key in the section.
 * \retval ETC_FILEIOFAILED     File I/O operation error occurred.
 *
 * \note MiniGUI use \a strncpy to copy actual value to \a pValue. Thus, if the length of 
 * the actual value is larger than \a iLen, the result copied to \a pValue 
 * will \em NOT be null-terminated.
 *
 * \sa GetIntValueFromEtcFile, SetValueToEtcFile, strncpy(3)
 */
int GUIAPI GetValueFromEtcFile (const char* pEtcFile, const char* pSection,