MiniGUI V2.0.3 API Reference: Simple request/reply interfaces

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.

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_SYS_REQID 0x0014

Maximal system reserved request identifier.

See also:: RegisterRequestHandler

Definition at line 793 of file minigui.h.

Typedef Documentation

typedef struct _REQUEST REQUEST

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

Function Documentation

ClientRequest	(	PREQUEST	request,
		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.
	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

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

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

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

Data Structures

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation

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

Data Structures

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation

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