libevent  2.2.1
Event notification library
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
35 extern "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))
94 
102 #define EVTAG_ASSIGN_WITH_LEN(msg, member, value, len) \
103  (*(msg)->base->member##_assign)((msg), (value), (len))
104 
112 #define EVTAG_GET(msg, member, pvalue) \
113  (*(msg)->base->member##_get)((msg), (pvalue))
114 
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))
133 
136 #define EVTAG_ARRAY_ADD(msg, member) \
137  (*(msg)->base->member##_add)(msg)
138 
141 #define EVTAG_ARRAY_GET(msg, member, offset, pvalue) \
142  (*(msg)->base->member##_get)((msg), (offset), (pvalue))
143 
146 #define EVTAG_ARRAY_LEN(msg, member) ((msg)->member##_length)
147 
148 
149 struct evbuffer;
150 struct event_base;
151 struct evrpc_req_generic;
152 struct evrpc_request_wrapper;
153 struct evrpc;
154 
159 #define EVRPC_STRUCT(rpcname) struct evrpc_req__##rpcname
160 
161 struct evhttp_request;
162 struct evrpc_status;
163 struct evrpc_hook_meta;
164 
176 #define EVRPC_HEADER(rpcname, reqstruct, rplystruct) \
177 EVRPC_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 }; \
185 EVENT2_EXPORT_SYMBOL \
186 int 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 
192 struct evrpc_pool;
193 
195 EVENT2_EXPORT_SYMBOL
196 struct 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 
266 EVENT2_EXPORT_SYMBOL
267 void evrpc_request_done(struct evrpc_req_generic *req);
268 
270 EVENT2_EXPORT_SYMBOL
271 void *evrpc_get_request(struct evrpc_req_generic *req);
272 EVENT2_EXPORT_SYMBOL
273 void *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 
289 struct evrpc_base;
290 struct evhttp;
291 
292 /* functions to start up the rpc system */
293 
300 EVENT2_EXPORT_SYMBOL
301 struct evrpc_base *evrpc_init(struct evhttp *server);
302 
311 EVENT2_EXPORT_SYMBOL
312 void 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 
348 EVENT2_EXPORT_SYMBOL
349 int 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 
362 EVENT2_EXPORT_SYMBOL
363 int evrpc_unregister_rpc(struct evrpc_base *base, const char *name);
364 
365 /*
366  * Client-side RPC support
367  */
368 
369 struct evhttp_connection;
370 struct 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 
401 EVENT2_EXPORT_SYMBOL
402 int evrpc_make_request(struct evrpc_request_wrapper *ctx);
403 
415 EVENT2_EXPORT_SYMBOL
416 struct evrpc_pool *evrpc_pool_new(struct event_base *base);
422 EVENT2_EXPORT_SYMBOL
423 void evrpc_pool_free(struct evrpc_pool *pool);
424 
433 EVENT2_EXPORT_SYMBOL
434 void evrpc_pool_add_connection(struct evrpc_pool *pool,
435  struct evhttp_connection *evcon);
436 
445 EVENT2_EXPORT_SYMBOL
446 void evrpc_pool_remove_connection(struct evrpc_pool *pool,
447  struct evhttp_connection *evcon);
448 
464 EVENT2_EXPORT_SYMBOL
465 void evrpc_pool_set_timeout(struct evrpc_pool *pool, int timeout_in_secs);
466 
475 };
476 
477 #ifndef _WIN32
478 
480 #define INPUT EVRPC_INPUT
481 
483 #define OUTPUT EVRPC_OUTPUT
484 #endif
485 
494 };
495 
512 EVENT2_EXPORT_SYMBOL
513 void *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 
526 EVENT2_EXPORT_SYMBOL
527 int evrpc_remove_hook(void *vbase,
528  enum EVRPC_HOOK_TYPE hook_type,
529  void *handle);
530 
536 EVENT2_EXPORT_SYMBOL
537 int evrpc_resume_request(void *vbase, void *ctx, enum EVRPC_HOOK_RESULT res);
538 
551 EVENT2_EXPORT_SYMBOL
552 int evrpc_hook_add_meta(void *ctx, const char *key,
553  const void *data, size_t data_size);
554 
565 EVENT2_EXPORT_SYMBOL
566 int evrpc_hook_find_meta(void *ctx, const char *key,
567  void **data, size_t *data_size);
568 
576 EVENT2_EXPORT_SYMBOL
577 struct evhttp_connection *evrpc_hook_get_connection(void *ctx);
578 
586 EVENT2_EXPORT_SYMBOL
587 int evrpc_send_request_generic(struct evrpc_pool *pool,
588  void *request, void *reply,
589  void (*cb)(struct evrpc_status *, void *, void *, void *),
590  void *cb_arg,
591  const char *rpcname,
592  void (*req_marshal)(struct evbuffer *, void *),
593  void (*rpl_clear)(void *),
594  int (*rpl_unmarshal)(void *, struct evbuffer *));
595 
603 EVENT2_EXPORT_SYMBOL
604 int evrpc_register_generic(struct evrpc_base *base, const char *name,
605  void (*callback)(struct evrpc_req_generic *, void *), void *cbarg,
606  void *(*req_new)(void *), void *req_new_arg, void (*req_free)(void *),
607  int (*req_unmarshal)(void *, struct evbuffer *),
608  void *(*rpl_new)(void *), void *rpl_new_arg, void (*rpl_free)(void *),
609  int (*rpl_complete)(void *),
610  void (*rpl_marshal)(struct evbuffer *, void *));
611 
613 EVENT2_EXPORT_SYMBOL
614 struct evrpc_pool* evrpc_request_get_pool(struct evrpc_request_wrapper *ctx);
615 EVENT2_EXPORT_SYMBOL
616 void evrpc_request_set_pool(struct evrpc_request_wrapper *ctx,
617  struct evrpc_pool *pool);
618 EVENT2_EXPORT_SYMBOL
619 void evrpc_request_set_cb(struct evrpc_request_wrapper *ctx,
620  void (*cb)(struct evrpc_status*, void *request, void *reply, void *arg),
621  void *cb_arg);
622 
623 #ifdef __cplusplus
624 }
625 #endif
626 
627 #endif /* EVENT2_RPC_H_INCLUDED_ */
EVRPC_TERMINATE
@ EVRPC_TERMINATE
indicates the rpc should be terminated
Definition: rpc.h:491
evrpc_request_done
EVENT2_EXPORT_SYMBOL void evrpc_request_done(struct evrpc_req_generic *req)
completes the server response to an rpc request
evrpc_pool_set_timeout
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.
EVRPC_INPUT
@ EVRPC_INPUT
apply the function to an input hook
Definition: rpc.h:473
evrpc_make_request_ctx
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
event_base
Structure to hold information and state for a Libevent dispatch loop.
Definition: event.h:219
evrpc_hook_find_meta
EVENT2_EXPORT_SYMBOL int evrpc_hook_find_meta(void *ctx, const char *key, void **data, size_t *data_size)
retrieves meta data previously associated
EVRPC_HOOK_RESULT
EVRPC_HOOK_RESULT
Return value from hook processing functions.
Definition: rpc.h:490
EVRPC_CONTINUE
@ EVRPC_CONTINUE
continue processing the rpc
Definition: rpc.h:492
evrpc_remove_hook
EVENT2_EXPORT_SYMBOL int evrpc_remove_hook(void *vbase, enum EVRPC_HOOK_TYPE hook_type, void *handle)
removes a previously added hook
evrpc_pool_remove_connection
EVENT2_EXPORT_SYMBOL void evrpc_pool_remove_connection(struct evrpc_pool *pool, struct evhttp_connection *evcon)
Removes a connection from the pool.
evrpc_register_generic
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.
evrpc_add_hook
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
evrpc_pool_free
EVENT2_EXPORT_SYMBOL void evrpc_pool_free(struct evrpc_pool *pool)
frees an rpc connection pool
evrpc_hook_add_meta
EVENT2_EXPORT_SYMBOL int evrpc_hook_add_meta(void *ctx, const char *key, const void *data, size_t data_size)
adds meta data to request
evbuffer
An evbuffer is an opaque data type for efficiently buffering data to be sent or received on the netwo...
Definition: buffer.h:97
evrpc_pool_new
EVENT2_EXPORT_SYMBOL struct evrpc_pool * evrpc_pool_new(struct event_base *base)
creates an rpc connection pool
evrpc_make_request
EVENT2_EXPORT_SYMBOL int evrpc_make_request(struct evrpc_request_wrapper *ctx)
Makes an RPC request based on the provided context.
evrpc_request_get_pool
EVENT2_EXPORT_SYMBOL struct evrpc_pool * evrpc_request_get_pool(struct evrpc_request_wrapper *ctx)
accessors for obscure and undocumented functionality
evrpc_free
EVENT2_EXPORT_SYMBOL void evrpc_free(struct evrpc_base *base)
Frees the evrpc base.
evrpc_resume_request
EVENT2_EXPORT_SYMBOL int evrpc_resume_request(void *vbase, void *ctx, enum EVRPC_HOOK_RESULT res)
resume a paused request
EVRPC_OUTPUT
@ EVRPC_OUTPUT
apply the function to an output hook
Definition: rpc.h:474
evrpc_send_request_generic
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_PAUSE
@ EVRPC_PAUSE
pause processing request until resumed
Definition: rpc.h:493
evrpc_hook_get_connection
EVENT2_EXPORT_SYMBOL struct evhttp_connection * evrpc_hook_get_connection(void *ctx)
returns the connection object associated with the request
evrpc_init
EVENT2_EXPORT_SYMBOL struct evrpc_base * evrpc_init(struct evhttp *server)
Creates a new rpc base from which RPC requests can be received.
evrpc_pool_add_connection
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.
evrpc_get_request
EVENT2_EXPORT_SYMBOL void * evrpc_get_request(struct evrpc_req_generic *req)
accessors for request and reply
evrpc_register_rpc
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.
util.h
Common convenience functions for cross-platform portability and related socket manipulations.
EVRPC_HOOK_TYPE
EVRPC_HOOK_TYPE
Hooks for changing the input and output of RPCs; this can be used to implement compression,...
Definition: rpc.h:472