Simple request/reply interfaces
[MiniGUI-Processes specific functions]

Data Structures

• struct _REQUEST

Defines

• #define MAX_SYS_REQID   0x0020

  Maximal system reserved request identifier.
  

• #define MAX_REQID   0x0030

  Maximal request identifier.
  

Typedefs

• typedef struct _REQUEST REQUEST
• typedef REQUEST * PREQUEST
• typedef int(* REQ_HANDLER )(int cli, int clifd, void *buff, size_t len)

  Request handler.
  

Functions

• MG_EXPORT int GUIAPI ClientRequestEx (const REQUEST *request, const void *ex_data, int ex_data_len, void *result, int len_rslt)

  Sends a request to the server and wait reply.
  

• static int ClientRequest (const REQUEST *request, void *result, int len_rslt)

  Sends a request to the server and wait reply.
  

• MG_EXPORT int GUIAPI GetSockFD2Server (void)

  Gets the file descriptor of the socket connected to the server.
  

• MG_EXPORT int GUIAPI ServerSendReply (int clifd, const void *reply, int len)

  Sends the reply to the client.
  

• MG_EXPORT BOOL GUIAPI RegisterRequestHandler (int req_id, REQ_HANDLER your_handler)

  Registers a customize request handler.
  

• MG_EXPORT REQ_HANDLER GUIAPI GetRequestHandler (int req_id)

  Gets the request handler by request identifier.
  

---

Detailed Description

You can register a customized request handler to extend your server, i.e. mginit, of MiniGUI-Processes.

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 ClientRequest 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 ServerSendReply 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:

typedef struct TEST_REQ
{
   int a, b;
} TEST_REQ;

/* 
 * In the server, we define the request handler
 * and register it.
 */
static int ServerSendReply (int clifd, void* reply, int len)
{
    MSG reply_msg = {HWND_INVALID, 0};

    /* 
     * Sending a null message to client in order to indicate this is
     * a reply of a request.
     */
    if (sock_write (clifd, &reply_msg, sizeof (MSG)) < 0)
        return SOCKERR_IO;

    /* Send the result to the client. */
    if (sock_write (clifd, reply, len) < 0)
        return SOCKERR_IO;

    return SOCKERR_OK;
}

/*
 * This handler adds two integers and returns the sum
 * to the client.
 */
static int test_request (int cli, int clifd, void* buff, size_t len)
{
    int ret_value = 0;
    TEST_REQ* test_req = (TEST_REQ*)buff;

    ret_value = test_req.a + test_req.b;

    return ServerSendReply (clifd, &ret_value, sizeof (int));
}

...
     RegisterRequestHandler (MAX_SYS_REQID + 1, test_request);
...


/*
 * In the client, we can send a request to the server
 * to get the sum of two integers.
 */

        REQUEST req;
        TEST_REQ test_req = {5, 10};
        int ret_value;

        req.id = MAX_SYS_REQID + 1;
        req.data = &rest_req;
        req.len_data = sizeof (TEST_REQ);

        ClientRequest (&req, &ret_value, sizeof (int));
        /* ret_value shoudl be 15. */
        printf ("the returned value: %d\n", ret_value);

---

Define Documentation

#define MAX_REQID   0x0030

Maximal request identifier.

See also:

RegisterRequestHandler

Definition at line 1063 of file minigui.h.

#define MAX_SYS_REQID   0x0020

Maximal system reserved request identifier.

See also:

RegisterRequestHandler

Definition at line 1055 of file minigui.h.

---

Typedef Documentation

typedef REQUEST* PREQUEST

Data type of pointer to a REQUEST

Definition at line 1075 of file minigui.h.

typedef int(* REQ_HANDLER)(int cli, int clifd, void *buff, size_t len)

Request handler.

See also:

RegisterRequestHandler

Definition at line 1168 of file minigui.h.

typedef struct _REQUEST REQUEST

A request will be sent to the server of MiniGUI-Processes.

---

Function Documentation

int ClientRequest	(	const REQUEST *	request,
		void *	result,
		int	len_rslt
	)			[inline, static]

Sends a request to the server and wait reply.

If result is NULL or 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.

Parameters:

	request	The pointer to REQUEST, which contains the data of the request.
	result	The buffer receives the reply.
	len_rslt	The lenght of the buffer.

Returns:

Zero on success, no-zero on error.

Note:

Only used by clients to send a request to the server of MiniGUI-Processes.

See also:

ClientRequestEx, ServerSendReply

Definition at line 1124 of file minigui.h.

References ClientRequestEx(), and NULL.

int ClientRequestEx	(	const REQUEST *	request,
		const void *	ex_data,
		int	ex_data_len,
		void *	result,
		int	len_rslt
	)

Sends a request to the server and wait reply.

If result is NULL or len_rslt is zero, the function will return immediately after sent the data to the server.

Parameters:

	request	The pointer to REQUEST, which contains the data of the request.
	ex_data	The pointer to extra data to be sent to the server.
	ex_data_len	The length of the extra data in bytes.
	result	The buffer receives the reply.
	len_rslt	The lenght of the buffer.

Returns:

Zero on success, no-zero on error.

Note:

Only used by clients to send a request to the server of MiniGUI-Processes.

See also:

ServerSendReply

Referenced by ClientRequest().

EQ_HANDLER GUIAPI GetRequestHandler

(

int

req_id

)

Gets the request handler by request identifier.

This function returns the request handler of the specified request identifier req_id.

Parameters:

req_id

The request identifier.

Returns:

The handler on success, NULL on error.

Note:

Only can be used by the server.

See also:

RegisterRequestHandler

int GUIAPI GetSockFD2Server

(

void

)

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. mginit.

Returns:

The file descriptor of the socket connected to the server.

Note:

Only used by clients, no meaning for the server.

BOOL GUIAPI RegisterRequestHandler	(	int	req_id,
		REQ_HANDLER	your_handler
	)

Registers a customize request handler.

This function registers a request handler to the server, i.e. mginit.

Parameters:

	req_id	The identifier of the customized request.
	your_handler	The handler of the request. Being NULL to unregister the request handler.

Returns:

TRUE on success, FALSE on error.

Note:

Only used by the server to register a request handler. And the identifier should be larger than MAX_SYS_REQID and less than or equal to MAX_REQID.

See also:

ClientRequest, ServerSendReply, MAX_SYS_REQID, MAX_REQID

int GUIAPI ServerSendReply	(	int	clifd,
		const void *	reply,
		int	len
	)

Sends the reply to the client.

This function sends a replay pointed to by reply which is 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.

Parameters:

	clifd	The fd connected to the client.
	reply	The buffer contains the reply data.
	len	The length of the reply data in bytes.

Returns:

Zero on success, no-zero on error.

See also:

ClientRequest, RegisterRequestHandler