Go to the source code of this file.
Data Structures | |
| struct | evrpc |
| struct | evrpc_req_generic |
| struct | evrpc_request_wrapper |
| struct | evrpc_status |
| provides information about the completed RPC request. More... | |
Defines | |
| #define | EVRPC_GENERATE(rpcname, reqstruct, rplystruct) |
| Generates the code for receiving and sending an RPC message. | |
| #define | EVRPC_HEADER(rpcname, reqstruct, rplystruct) |
| Creates the definitions and prototypes for an RPC. | |
| #define | EVRPC_MAKE_REQUEST(name, pool, request, reply, cb, cbarg) evrpc_send_request_##name(pool, request, reply, cb, cbarg) |
| launches an RPC and sends it to the server | |
| #define | EVRPC_REGISTER(base, name, request, reply, callback, cbarg) |
| register RPCs with the HTTP Server | |
| #define | EVRPC_REGISTER_OBJECT(rpc, name, request, reply) |
| #define | EVRPC_REQUEST_DONE(rpc_req) |
| Creates the reply to an RPC request. | |
| #define | EVRPC_REQUEST_HTTP(rpc_req) (rpc_req)->http_req |
| Provides access to the HTTP request object underlying an RPC. | |
| #define | EVRPC_STATUS_ERR_BADPAYLOAD 2 |
| #define | EVRPC_STATUS_ERR_HOOKABORTED 4 |
| #define | EVRPC_STATUS_ERR_NONE 0 |
| #define | EVRPC_STATUS_ERR_TIMEOUT 1 |
| #define | EVRPC_STATUS_ERR_UNSTARTED 3 |
| #define | EVRPC_STRUCT(rpcname) struct evrpc_req__##rpcname |
| The type of a specific RPC Message. | |
| #define | EVRPC_UNREGISTER(base, name) evrpc_unregister_rpc(base, #name) |
| Unregisters an already registered RPC. | |
| #define | INPUT EVRPC_INPUT |
| Deprecated alias for EVRPC_INPUT. | |
| #define | OUTPUT EVRPC_OUTPUT |
| Deprecated alias for EVRPC_OUTPUT. | |
Enumerations | |
| enum | EVRPC_HOOK_TYPE { EVRPC_INPUT, EVRPC_OUTPUT } |
| Hooks for changing the input and output of RPCs; this can be used to implement compression, authentication, encryption, . More... | |
Functions | |
| void * | evrpc_add_hook (void *vbase, enum EVRPC_HOOK_TYPE hook_type, int(*cb)(struct evhttp_request *, struct evbuffer *, void *), void *cb_arg) |
| adds a processing hook to either an rpc base or rpc pool | |
| void | evrpc_free (struct evrpc_base *base) |
| Frees the evrpc base. | |
| struct evrpc_base * | evrpc_init (struct evhttp *server) |
| Creates a new rpc base from which RPC requests can be received. | |
| int | evrpc_make_request (struct evrpc_request_wrapper *) |
| void | evrpc_pool_add_connection (struct evrpc_pool *, struct evhttp_connection *) |
| void | evrpc_pool_free (struct evrpc_pool *pool) |
| frees an rpc connection pool | |
| struct evrpc_pool * | evrpc_pool_new (struct event_base *base) |
| creates an rpc connection pool | |
| void | evrpc_pool_set_timeout (struct evrpc_pool *pool, int timeout_in_secs) |
| Sets the timeout in secs after which a request has to complete. | |
| int | evrpc_register_rpc (struct evrpc_base *, struct evrpc *, void(*)(struct evrpc_req_generic *, void *), void *) |
| int | evrpc_remove_hook (void *vbase, enum EVRPC_HOOK_TYPE hook_type, void *handle) |
| removes a previously added hook | |
| int | evrpc_unregister_rpc (struct evrpc_base *base, const char *name) |
To support RPCs in a server, every supported RPC command needs to be defined and registered.
EVRPC_HEADER(SendCommand, Request, Reply);
SendCommand is the name of the RPC command. Request is the name of a structure generated by event_rpcgen.py. It contains all parameters relating to the SendCommand RPC. The server needs to fill in the Reply structure. Reply is the name of a structure generated by event_rpcgen.py. It contains the answer to the RPC.
To register an RPC with an HTTP server, you need to first create an RPC base with:
struct evrpc_base *base = evrpc_init(http);
A specific RPC can then be registered with
EVRPC_REGISTER(base, SendCommand, Request, Reply, FunctionCB, arg);
when the server receives an appropriately formatted RPC, the user callback is invokved. The callback needs to fill in the reply structure.
void FunctionCB(EVRPC_STRUCT(SendCommand)* rpc, void *arg);
To send the reply, call EVRPC_REQUEST_DONE(rpc);
See the regression test for an example.
| #define EVRPC_GENERATE | ( | rpcname, | |||
| reqstruct, | |||||
| rplystruct | ) |
Generates the code for receiving and sending an RPC message.
EVRPC_GENERATE is used to create the code corresponding to sending and receiving a particular RPC message
| rpcname | the name of the RPC | |
| reqstruct | the name of the RPC request structure | |
| replystruct | the name of the RPC reply structure |
| #define EVRPC_HEADER | ( | rpcname, | |||
| reqstruct, | |||||
| rplystruct | ) |
Value:
EVRPC_STRUCT(rpcname) { \ struct reqstruct* request; \ struct rplystruct* reply; \ struct evrpc* rpc; \ struct evhttp_request* http_req; \ void (*done)(struct evrpc_status *, \ struct evrpc* rpc, void *request, void *reply); \ }; \ int evrpc_send_request_##rpcname(struct evrpc_pool *, \ struct reqstruct *, struct rplystruct *, \ void (*)(struct evrpc_status *, \ struct reqstruct *, struct rplystruct *, void *cbarg), \ void *);
You need to use EVRPC_HEADER to create structures and function prototypes needed by the server and client implementation. The structures have to be defined in an .rpc file and converted to source code via event_rpcgen.py
| rpcname | the name of the RPC | |
| reqstruct | the name of the RPC request structure | |
| replystruct | the name of the RPC reply structure |
| #define EVRPC_MAKE_REQUEST | ( | name, | |||
| pool, | |||||
| request, | |||||
| reply, | |||||
| cb, | |||||
| cbarg | ) | evrpc_send_request_##name(pool, request, reply, cb, cbarg) |
launches an RPC and sends it to the server
EVRPC_MAKE_REQUEST() is used by the client to send an RPC to the server.
| name | the name of the RPC | |
| pool | the evrpc_pool that contains the connection objects over which the request should be sent. | |
| request | a pointer to the RPC request structure - it contains the data to be sent to the server. | |
| reply | a pointer to the RPC reply structure. It is going to be filled if the request was answered successfully | |
| cb | the callback to invoke when the RPC request has been answered | |
| cbarg | an additional argument to be passed to the client |
| #define EVRPC_REGISTER | ( | base, | |||
| name, | |||||
| request, | |||||
| reply, | |||||
| callback, | |||||
| cbarg | ) |
Value:
do { \ struct evrpc* rpc = (struct evrpc *)calloc(1, sizeof(struct evrpc)); \ EVRPC_REGISTER_OBJECT(rpc, name, request, reply); \ evrpc_register_rpc(base, rpc, \ (void (*)(struct evrpc_req_generic*, void *))callback, cbarg); \ } while (0)
registers a new RPC with the HTTP server, each RPC needs to have a unique name under which it can be identified.
| base | the evrpc_base structure in which the RPC should be registered. | |
| name | the name of the RPC | |
| request | the name of the RPC request structure | |
| reply | the name of the RPC reply structure | |
| callback | the callback that should be invoked when the RPC is received. The callback has the following prototype void (*callback)(EVRPC_STRUCT(Message)* rpc, void *arg) | |
| cbarg | an additional parameter that can be passed to the callback. The parameter can be used to carry around state. |
| #define EVRPC_REGISTER_OBJECT | ( | rpc, | |||
| name, | |||||
| request, | |||||
| reply | ) |
Value:
do { \ (rpc)->uri = strdup(#name); \ if ((rpc)->uri == NULL) { \ fprintf(stderr, "failed to register object\n"); \ exit(1); \ } \ (rpc)->request_new = (void *(*)(void))request##_new; \ (rpc)->request_free = (void (*)(void *))request##_free; \ (rpc)->request_unmarshal = (int (*)(void *, struct evbuffer *))request##_unmarshal; \ (rpc)->reply_new = (void *(*)(void))reply##_new; \ (rpc)->reply_free = (void (*)(void *))reply##_free; \ (rpc)->reply_complete = (int (*)(void *))reply##_complete; \ (rpc)->reply_marshal = (void (*)(struct evbuffer*, void *))reply##_marshal; \ } while (0)
| #define EVRPC_REQUEST_DONE | ( | rpc_req | ) |
Value:
do { \ struct evrpc_req_generic *_req = (struct evrpc_req_generic *)(rpc_req); \ _req->done(_req); \ } while (0)
EVRPC_REQUEST_DONE is used to answer a request; the reply is expected to have been filled in. The request and reply pointers become invalid after this call has finished.
| rpc_req | the rpc request structure provided to the server callback |
| #define EVRPC_REQUEST_HTTP | ( | rpc_req | ) | (rpc_req)->http_req |
Provides access to the HTTP request object underlying an RPC.
Access to the underlying http object; can be used to look at headers or for getting the remote ip address
| rpc_req | the rpc request structure provided to the server callback |
| #define EVRPC_STRUCT | ( | rpcname | ) | struct evrpc_req__##rpcname |
The type of a specific RPC Message.
| rpcname | the name of the RPC message |
| #define EVRPC_UNREGISTER | ( | base, | |||
| name | ) | evrpc_unregister_rpc(base, #name) |
Unregisters an already registered RPC.
| base | the evrpc_base object from which to unregister an RPC | |
| name | the name of the rpc to unregister |
| #define INPUT EVRPC_INPUT |
Deprecated alias for EVRPC_INPUT.
Not available on windows, where it conflicts with platform headers.
| #define OUTPUT EVRPC_OUTPUT |
Deprecated alias for EVRPC_OUTPUT.
Not available on windows, where it conflicts with platform headers.
| enum EVRPC_HOOK_TYPE |
| void* evrpc_add_hook | ( | void * | vbase, | |
| enum EVRPC_HOOK_TYPE | hook_type, | |||
| int(*)(struct evhttp_request *, struct evbuffer *, void *) | cb, | |||
| void * | cb_arg | |||
| ) |
adds a processing hook to either an rpc base or rpc pool
If a hook returns -1, the processing is aborted.
The add functions return handles that can be used for removing hooks.
| vbase | a pointer to either struct evrpc_base or struct evrpc_pool | |
| hook_type | either INPUT or OUTPUT | |
| cb | the callback to call when the hook is activated | |
| cb_arg | an additional argument for the callback |
| void evrpc_free | ( | struct evrpc_base * | base | ) |
Frees the evrpc base.
For now, you are responsible for making sure that no rpcs are ongoing.
| base | the evrpc_base object to be freed |
| struct evrpc_base* evrpc_init | ( | struct evhttp * | server | ) | [read] |
Creates a new rpc base from which RPC requests can be received.
| server | a pointer to an existing HTTP server |
| void evrpc_pool_free | ( | struct evrpc_pool * | pool | ) |
frees an rpc connection pool
| pool | a pointer to an evrpc_pool allocated via evrpc_pool_new() |
| struct evrpc_pool* evrpc_pool_new | ( | struct event_base * | base | ) | [read] |
creates an rpc connection pool
a pool has a number of connections associated with it. rpc requests are always made via a pool.
| base | a pointer to an struct event_based object; can be left NULL in singled-threaded applications |
| void evrpc_pool_set_timeout | ( | struct evrpc_pool * | pool, | |
| int | timeout_in_secs | |||
| ) |
Sets the timeout in secs after which a request has to complete.
The RPC is completely aborted if it does not complete by then. Setting the timeout to 0 means that it never timeouts and can be used to implement callback type RPCs.
Any connection already in the pool will be updated with the new timeout. Connections added to the pool after set_timeout has be called receive the pool timeout only if no timeout has been set for the connection itself.
| pool | a pointer to a struct evrpc_pool object | |
| timeout_in_secs | the number of seconds after which a request should timeout and a failure be returned to the callback. |
| int evrpc_remove_hook | ( | void * | vbase, | |
| enum EVRPC_HOOK_TYPE | hook_type, | |||
| void * | handle | |||
| ) |
removes a previously added hook
| vbase | a pointer to either struct evrpc_base or struct evrpc_pool | |
| hook_type | either INPUT or OUTPUT | |
| handle | a handle returned by evrpc_add_hook() |
1.5.7