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

Data Structures
struct	_REQUEST

Macros
#define	MAX_SYS_REQID 0x0023
	Maximal system reserved request identifier. More...

#define	MAX_REQID 0x0030
	Maximal request identifier. More...

Typedefs
typedef struct _REQUEST	REQUEST

typedef REQUEST *	PREQUEST

typedef int(*	REQ_HANDLER) (int cli, int clifd, void *buff, size_t len)
	The prototype of a request handler (version 0). More...

typedef int(*	REQ_HANDLER_V1) (int cli, int clifd, void *buff, size_t len, int fd_received)
	The prototype of an extended request handler (version 1). More...

Functions
static 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. More...

static int	ClientRequest (const REQUEST request, void result, int len_rslt)
	Sends a request to the server and wait reply. More...

MG_EXPORT int GUIAPI	GetSockFD2Server (void)
	Get the file descriptor of the socket connected to the server. More...

MG_EXPORT int GUIAPI	ServerSendReplyEx (int clifd, const void *reply, int len, int fd_to_send)
	Sends a reply to the client. More...

static int GUIAPI	ServerSendReply (int clifd, const void *reply, int len)
	Sends the reply to the client. More...

MG_EXPORT BOOL GUIAPI	RegisterRequestHandler (int req_id, REQ_HANDLER your_handler)
	Registers a customized request handler of version 0. More...

MG_EXPORT BOOL GUIAPI	RegisterRequestHandlerV1 (int req_id, REQ_HANDLER_V1 your_handler_v1)
	Registers a customized extended request handler of version 1. More...

MG_EXPORT REQ_HANDLER GUIAPI	GetRequestHandler (int req_id)
	Get the request handler by request identifier. More...

MG_EXPORT REQ_HANDLER_V1 GUIAPI	GetRequestHandlerV1 (int req_id)
	Get the extended request handler by a request identifier. More...

MG_EXPORT void *GUIAPI	GetRequestHandlerEx (int req_id, int *version)
	Get the request handler and the version by request identifier. More...

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

Macro Definition Documentation

◆ MAX_REQID

#define MAX_REQID 0x0030

Maximal request identifier.

See also: RegisterRequestHandler

Definition at line 1969 of file minigui.h.

◆ MAX_SYS_REQID

#define MAX_SYS_REQID 0x0023

Maximal system reserved request identifier.

See also: RegisterRequestHandler

Definition at line 1961 of file minigui.h.

Typedef Documentation

◆ PREQUEST

typedef REQUEST* PREQUEST

Data type of pointer to a REQUEST

Definition at line 1981 of file minigui.h.

◆ REQ_HANDLER

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

The prototype of a request handler (version 0).

See also: RegisterRequestHandler

Definition at line 2156 of file minigui.h.

◆ REQ_HANDLER_V1

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

The prototype of an extended request handler (version 1).

See also: RegisterRequestHandlerV1

Since 5.0.0

Definition at line 2167 of file minigui.h.

◆ REQUEST

typedef struct _REQUEST REQUEST

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

Function Documentation

◆ ClientRequest()

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

inlinestatic

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.; If the reply containes a file descriptor sent from the server, you should call ClientRequestEx2 instead.

See also: ClientRequestEx2, ClientRequestEx, ServerSendReply

Definition at line 2078 of file minigui.h.

References ClientRequestEx(), and NULL.

◆ ClientRequestEx()

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

inlinestatic

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.; If the reply containes a file descriptor sent from the server, you should call ClientRequestEx2 instead.

See also: ClientRequestEx2, ServerSendReply

Definition at line 2045 of file minigui.h.

Referenced by ClientRequest().

◆ GetRequestHandler()

REQ_HANDLER GUIAPI GetRequestHandler ( int req_id )

Get 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: If the registered request handler is an extended handler (version 1), The function returns NULL.; Only used by the server to retrieve the current request handler.; This function dose not return the request handler in different version. Please use GetRequestHandlerEx instead.

See also: RegisterRequestHandler

◆ GetRequestHandlerEx()

void *GUIAPI GetRequestHandlerEx	(	int	req_id,
		int *	version
	)

Get the request handler and the version by request identifier.

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

Parameters

req_id	The request identifier.
version	The pointer to an integer to store the version number of the request handler.

Returns: The pointer to the handler on success, NULL on error.

Note: Only used by the server to retrieve the current request handler.

See also: RegisterRequestHandler, RegisterRequestHandlerV1

Since 5.0.0

◆ GetRequestHandlerV1()

REQ_HANDLER_V1 GUIAPI GetRequestHandlerV1 ( int req_id )

Get the extended request handler by a 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: If the registered request handler is not an extended handler (version 1), The function returns NULL.; Only used by the server to retrieve the current request handler.; This function dose not return the request handler in different version. Please use GetRequestHandlerEx instead.

See also: RegisterRequestHandler

◆ GetSockFD2Server()

int GUIAPI GetSockFD2Server ( void )

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

◆ RegisterRequestHandler()

BOOL GUIAPI RegisterRequestHandler	(	int	req_id,
		REQ_HANDLER	your_handler
	)

Registers a customized request handler of version 0.

This function registers a request handler (version 0) to the server.

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

◆ RegisterRequestHandlerV1()

BOOL GUIAPI RegisterRequestHandlerV1	(	int	req_id,
		REQ_HANDLER_V1	your_handler_v1
	)

Registers a customized extended request handler of version 1.

This function registers an extended request handler (version 1) to the server.

Parameters

req_id	The identifier of the customized request.
your_handler_v1	The handler (version 1) 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 an extended 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

Since 5.0.0

◆ ServerSendReply()

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

inlinestatic

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.

Note: If there is a file descriptor to send along with the reply, you should call ServerSendReplyEx instead.

See also: ServerSendReplyEx, ClientRequestEx2, RegisterRequestHandler

Definition at line 2145 of file minigui.h.

◆ ServerSendReplyEx()

int GUIAPI ServerSendReplyEx	(	int	clifd,
		const void *	reply,
		int	len,
		int	fd_to_send
	)

Sends a reply to the client.

This function sends a replay pointed to by reply which is len bytes long to the client, as well as the file descriptor will be sent 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.
fd_to_send	The file descriptor which will be sent to the client; it will be ignored if it is less than 0.

Returns: Zero on success, no-zero on error.

See also: ClientRequest, RegisterRequestHandler

Since 5.0.0

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ MAX_REQID

◆ MAX_SYS_REQID

Typedef Documentation

◆ PREQUEST

◆ REQ_HANDLER

◆ REQ_HANDLER_V1

◆ REQUEST

Function Documentation

◆ ClientRequest()

◆ ClientRequestEx()

◆ GetRequestHandler()

◆ GetRequestHandlerEx()

◆ GetRequestHandlerV1()

◆ GetSockFD2Server()

◆ RegisterRequestHandler()

◆ RegisterRequestHandlerV1()

◆ ServerSendReply()

◆ ServerSendReplyEx()