libevent-2.1.12-stable
Loading...
Searching...
No Matches
rpc.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2006-2007 Niels Provos <provos@citi.umich.edu>
3 * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 * 1. Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 * 2. Redistributions in binary form must reproduce the above copyright
11 * notice, this list of conditions and the following disclaimer in the
12 * documentation and/or other materials provided with the distribution.
13 * 3. The name of the author may not be used to endorse or promote products
14 * derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27#ifndef EVENT2_RPC_H_INCLUDED_
28#define EVENT2_RPC_H_INCLUDED_
29
30/* For int types. */
31#include <event2/util.h>
32#include <event2/visibility.h>
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
80#define EVTAG_HAS(msg, member) \
81 ((msg)->member##_set == 1)
82
83#ifndef EVENT2_RPC_COMPAT_H_INCLUDED_
84
92#define EVTAG_ASSIGN(msg, member, value) \
93 (*(msg)->base->member##_assign)((msg), (value))
102#define EVTAG_ASSIGN_WITH_LEN(msg, member, value, len) \
103 (*(msg)->base->member##_assign)((msg), (value), (len))
112#define EVTAG_GET(msg, member, pvalue) \
113 (*(msg)->base->member##_get)((msg), (pvalue))
123#define EVTAG_GET_WITH_LEN(msg, member, pvalue, plen) \
124 (*(msg)->base->member##_get)((msg), (pvalue), (plen))
125
126#endif /* EVENT2_RPC_COMPAT_H_INCLUDED_ */
127
131#define EVTAG_ARRAY_ADD_VALUE(msg, member, value) \
132 (*(msg)->base->member##_add)((msg), (value))
136#define EVTAG_ARRAY_ADD(msg, member) \
137 (*(msg)->base->member##_add)(msg)
141#define EVTAG_ARRAY_GET(msg, member, offset, pvalue) \
142 (*(msg)->base->member##_get)((msg), (offset), (pvalue))
146#define EVTAG_ARRAY_LEN(msg, member) ((msg)->member##_length)
147
148
149struct evbuffer;
150struct event_base;
151struct evrpc_req_generic;
152struct evrpc_request_wrapper;
153struct evrpc;
154
159#define EVRPC_STRUCT(rpcname) struct evrpc_req__##rpcname
160
161struct evhttp_request;
162struct evrpc_status;
163struct evrpc_hook_meta;
164
176#define EVRPC_HEADER(rpcname, reqstruct, rplystruct) \
177EVRPC_STRUCT(rpcname) { \
178 struct evrpc_hook_meta *hook_meta; \
179 struct reqstruct* request; \
180 struct rplystruct* reply; \
181 struct evrpc* rpc; \
182 struct evhttp_request* http_req; \
183 struct evbuffer* rpc_data; \
184}; \
185EVENT2_EXPORT_SYMBOL \
186int evrpc_send_request_##rpcname(struct evrpc_pool *, \
187 struct reqstruct *, struct rplystruct *, \
188 void (*)(struct evrpc_status *, \
189 struct reqstruct *, struct rplystruct *, void *cbarg), \
190 void *);
191
192struct evrpc_pool;
193
195EVENT2_EXPORT_SYMBOL
196struct evrpc_request_wrapper *evrpc_make_request_ctx(
197 struct evrpc_pool *pool, void *request, void *reply,
198 const char *rpcname,
199 void (*req_marshal)(struct evbuffer*, void *),
200 void (*rpl_clear)(void *),
201 int (*rpl_unmarshal)(void *, struct evbuffer *),
202 void (*cb)(struct evrpc_status *, void *, void *, void *),
203 void *cbarg);
204
219#define EVRPC_MAKE_CTX(rpcname, reqstruct, rplystruct, \
220 pool, request, reply, cb, cbarg) \
221 evrpc_make_request_ctx(pool, request, reply, \
222 #rpcname, \
223 (void (*)(struct evbuffer *, void *))reqstruct##_marshal, \
224 (void (*)(void *))rplystruct##_clear, \
225 (int (*)(void *, struct evbuffer *))rplystruct##_unmarshal, \
226 (void (*)(struct evrpc_status *, void *, void *, void *))cb, \
227 cbarg)
228
239#define EVRPC_GENERATE(rpcname, reqstruct, rplystruct) \
240 int evrpc_send_request_##rpcname(struct evrpc_pool *pool, \
241 struct reqstruct *request, struct rplystruct *reply, \
242 void (*cb)(struct evrpc_status *, \
243 struct reqstruct *, struct rplystruct *, void *cbarg), \
244 void *cbarg) { \
245 return evrpc_send_request_generic(pool, request, reply, \
246 (void (*)(struct evrpc_status *, void *, void *, void *))cb, \
247 cbarg, \
248 #rpcname, \
249 (void (*)(struct evbuffer *, void *))reqstruct##_marshal, \
250 (void (*)(void *))rplystruct##_clear, \
251 (int (*)(void *, struct evbuffer *))rplystruct##_unmarshal); \
252}
253
263#define EVRPC_REQUEST_HTTP(rpc_req) (rpc_req)->http_req
264
266EVENT2_EXPORT_SYMBOL
267void evrpc_request_done(struct evrpc_req_generic *req);
268
270EVENT2_EXPORT_SYMBOL
271void *evrpc_get_request(struct evrpc_req_generic *req);
272EVENT2_EXPORT_SYMBOL
273void *evrpc_get_reply(struct evrpc_req_generic *req);
274
283#define EVRPC_REQUEST_DONE(rpc_req) do { \
284 struct evrpc_req_generic *req_ = (struct evrpc_req_generic *)(rpc_req); \
285 evrpc_request_done(req_); \
286} while (0)
287
288
289struct evrpc_base;
290struct evhttp;
291
292/* functions to start up the rpc system */
293
300EVENT2_EXPORT_SYMBOL
301struct evrpc_base *evrpc_init(struct evhttp *server);
302
311EVENT2_EXPORT_SYMBOL
312void evrpc_free(struct evrpc_base *base);
313
330#define EVRPC_REGISTER(base, name, request, reply, callback, cbarg) \
331 evrpc_register_generic(base, #name, \
332 (void (*)(struct evrpc_req_generic *, void *))callback, cbarg, \
333 (void *(*)(void *))request##_new_with_arg, NULL, \
334 (void (*)(void *))request##_free, \
335 (int (*)(void *, struct evbuffer *))request##_unmarshal, \
336 (void *(*)(void *))reply##_new_with_arg, NULL, \
337 (void (*)(void *))reply##_free, \
338 (int (*)(void *))reply##_complete, \
339 (void (*)(struct evbuffer *, void *))reply##_marshal)
340
348EVENT2_EXPORT_SYMBOL
349int evrpc_register_rpc(struct evrpc_base *, struct evrpc *,
350 void (*)(struct evrpc_req_generic*, void *), void *);
351
360#define EVRPC_UNREGISTER(base, name) evrpc_unregister_rpc((base), #name)
361
362EVENT2_EXPORT_SYMBOL
363int evrpc_unregister_rpc(struct evrpc_base *base, const char *name);
364
365/*
366 * Client-side RPC support
367 */
368
369struct evhttp_connection;
370struct evrpc_status;
371
387#define EVRPC_MAKE_REQUEST(name, pool, request, reply, cb, cbarg) \
388 evrpc_send_request_##name((pool), (request), (reply), (cb), (cbarg))
389
401EVENT2_EXPORT_SYMBOL
402int evrpc_make_request(struct evrpc_request_wrapper *ctx);
403
415EVENT2_EXPORT_SYMBOL
416struct evrpc_pool *evrpc_pool_new(struct event_base *base);
422EVENT2_EXPORT_SYMBOL
423void evrpc_pool_free(struct evrpc_pool *pool);
424
433EVENT2_EXPORT_SYMBOL
434void evrpc_pool_add_connection(struct evrpc_pool *pool,
435 struct evhttp_connection *evcon);
436
445EVENT2_EXPORT_SYMBOL
446void evrpc_pool_remove_connection(struct evrpc_pool *pool,
447 struct evhttp_connection *evcon);
448
464EVENT2_EXPORT_SYMBOL
465void evrpc_pool_set_timeout(struct evrpc_pool *pool, int timeout_in_secs);
466
476
477#ifndef _WIN32
480#define INPUT EVRPC_INPUT
483#define OUTPUT EVRPC_OUTPUT
484#endif
485
493 EVRPC_PAUSE = 1
495
512EVENT2_EXPORT_SYMBOL
513void *evrpc_add_hook(void *vbase,
514 enum EVRPC_HOOK_TYPE hook_type,
515 int (*cb)(void *, struct evhttp_request *, struct evbuffer *, void *),
516 void *cb_arg);
517
526EVENT2_EXPORT_SYMBOL
527int evrpc_remove_hook(void *vbase,
528 enum EVRPC_HOOK_TYPE hook_type,
529 void *handle);
530
536EVENT2_EXPORT_SYMBOL
537int evrpc_resume_request(void *vbase, void *ctx, enum EVRPC_HOOK_RESULT res);
538
550EVENT2_EXPORT_SYMBOL
551void evrpc_hook_add_meta(void *ctx, const char *key,
552 const void *data, size_t data_size);
553
564EVENT2_EXPORT_SYMBOL
565int evrpc_hook_find_meta(void *ctx, const char *key,
566 void **data, size_t *data_size);
567
575EVENT2_EXPORT_SYMBOL
576struct evhttp_connection *evrpc_hook_get_connection(void *ctx);
577
585EVENT2_EXPORT_SYMBOL
586int evrpc_send_request_generic(struct evrpc_pool *pool,
587 void *request, void *reply,
588 void (*cb)(struct evrpc_status *, void *, void *, void *),
589 void *cb_arg,
590 const char *rpcname,
591 void (*req_marshal)(struct evbuffer *, void *),
592 void (*rpl_clear)(void *),
593 int (*rpl_unmarshal)(void *, struct evbuffer *));
594
602EVENT2_EXPORT_SYMBOL
603int evrpc_register_generic(struct evrpc_base *base, const char *name,
604 void (*callback)(struct evrpc_req_generic *, void *), void *cbarg,
605 void *(*req_new)(void *), void *req_new_arg, void (*req_free)(void *),
606 int (*req_unmarshal)(void *, struct evbuffer *),
607 void *(*rpl_new)(void *), void *rpl_new_arg, void (*rpl_free)(void *),
608 int (*rpl_complete)(void *),
609 void (*rpl_marshal)(struct evbuffer *, void *));
610
612EVENT2_EXPORT_SYMBOL
613struct evrpc_pool* evrpc_request_get_pool(struct evrpc_request_wrapper *ctx);
614EVENT2_EXPORT_SYMBOL
615void evrpc_request_set_pool(struct evrpc_request_wrapper *ctx,
616 struct evrpc_pool *pool);
617EVENT2_EXPORT_SYMBOL
618void evrpc_request_set_cb(struct evrpc_request_wrapper *ctx,
619 void (*cb)(struct evrpc_status*, void *request, void *reply, void *arg),
620 void *cb_arg);
621
622#ifdef __cplusplus
623}
624#endif
625
626#endif /* EVENT2_RPC_H_INCLUDED_ */
EVENT2_EXPORT_SYMBOL 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.
EVENT2_EXPORT_SYMBOL struct evhttp_connection * evrpc_hook_get_connection(void *ctx)
returns the connection object associated with the request
EVENT2_EXPORT_SYMBOL struct evrpc_request_wrapper * evrpc_make_request_ctx(struct evrpc_pool *pool, void *request, void *reply, const char *rpcname, void(*req_marshal)(struct evbuffer *, void *), void(*rpl_clear)(void *), int(*rpl_unmarshal)(void *, struct evbuffer *), void(*cb)(struct evrpc_status *, void *, void *, void *), void *cbarg)
use EVRPC_GENERATE instead
EVENT2_EXPORT_SYMBOL int evrpc_make_request(struct evrpc_request_wrapper *ctx)
Makes an RPC request based on the provided context.
EVENT2_EXPORT_SYMBOL struct evrpc_pool * evrpc_pool_new(struct event_base *base)
creates an rpc connection pool
EVENT2_EXPORT_SYMBOL int evrpc_hook_find_meta(void *ctx, const char *key, void **data, size_t *data_size)
retrieves meta data previously associated
EVENT2_EXPORT_SYMBOL void evrpc_pool_remove_connection(struct evrpc_pool *pool, struct evhttp_connection *evcon)
Removes a connection from the pool.
EVRPC_HOOK_TYPE
Hooks for changing the input and output of RPCs; this can be used to implement compression,...
Definition: rpc.h:472
@ EVRPC_INPUT
apply the function to an input hook
Definition: rpc.h:473
@ EVRPC_OUTPUT
apply the function to an output hook
Definition: rpc.h:474
EVENT2_EXPORT_SYMBOL void evrpc_request_done(struct evrpc_req_generic *req)
completes the server response to an rpc request
EVENT2_EXPORT_SYMBOL void * evrpc_get_request(struct evrpc_req_generic *req)
accessors for request and reply
EVENT2_EXPORT_SYMBOL int evrpc_resume_request(void *vbase, void *ctx, enum EVRPC_HOOK_RESULT res)
resume a paused request
EVENT2_EXPORT_SYMBOL void * evrpc_add_hook(void *vbase, enum EVRPC_HOOK_TYPE hook_type, int(*cb)(void *, struct evhttp_request *, struct evbuffer *, void *), void *cb_arg)
adds a processing hook to either an rpc base or rpc pool
EVENT2_EXPORT_SYMBOL void evrpc_hook_add_meta(void *ctx, const char *key, const void *data, size_t data_size)
adds meta data to request
EVENT2_EXPORT_SYMBOL int evrpc_send_request_generic(struct evrpc_pool *pool, void *request, void *reply, void(*cb)(struct evrpc_status *, void *, void *, void *), void *cb_arg, const char *rpcname, void(*req_marshal)(struct evbuffer *, void *), void(*rpl_clear)(void *), int(*rpl_unmarshal)(void *, struct evbuffer *))
Function for sending a generic RPC request.
EVRPC_HOOK_RESULT
Return value from hook processing functions.
Definition: rpc.h:490
@ EVRPC_CONTINUE
continue processing the rpc
Definition: rpc.h:492
@ EVRPC_TERMINATE
indicates the rpc should be terminated
Definition: rpc.h:491
@ EVRPC_PAUSE
pause processing request until resumed
Definition: rpc.h:493
EVENT2_EXPORT_SYMBOL void evrpc_pool_add_connection(struct evrpc_pool *pool, struct evhttp_connection *evcon)
Adds a connection over which rpc can be dispatched to the pool.
EVENT2_EXPORT_SYMBOL struct evrpc_pool * evrpc_request_get_pool(struct evrpc_request_wrapper *ctx)
accessors for obscure and undocumented functionality
EVENT2_EXPORT_SYMBOL int evrpc_register_generic(struct evrpc_base *base, const char *name, void(*callback)(struct evrpc_req_generic *, void *), void *cbarg, void *(*req_new)(void *), void *req_new_arg, void(*req_free)(void *), int(*req_unmarshal)(void *, struct evbuffer *), void *(*rpl_new)(void *), void *rpl_new_arg, void(*rpl_free)(void *), int(*rpl_complete)(void *), void(*rpl_marshal)(struct evbuffer *, void *))
Function for registering a generic RPC with the RPC base.
EVENT2_EXPORT_SYMBOL int evrpc_remove_hook(void *vbase, enum EVRPC_HOOK_TYPE hook_type, void *handle)
removes a previously added hook
EVENT2_EXPORT_SYMBOL void evrpc_pool_free(struct evrpc_pool *pool)
frees an rpc connection pool
EVENT2_EXPORT_SYMBOL int evrpc_register_rpc(struct evrpc_base *, struct evrpc *, void(*)(struct evrpc_req_generic *, void *), void *)
Low level function for registering an RPC with a server.
EVENT2_EXPORT_SYMBOL void evrpc_free(struct evrpc_base *base)
Frees the evrpc base.
EVENT2_EXPORT_SYMBOL struct evrpc_base * evrpc_init(struct evhttp *server)
Creates a new rpc base from which RPC requests can be received.
An evbuffer is an opaque data type for efficiently buffering data to be sent or received on the netwo...
Definition: buffer.h:99
Structure to hold information and state for a Libevent dispatch loop.
Definition: event.h:219
Common convenience functions for cross-platform portability and related socket manipulations.