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