Annotation of embedaddon/libevent/evrpc.h, revision 1.1
1.1 ! misho 1: /*
! 2: * Copyright (c) 2006 Niels Provos <provos@citi.umich.edu>
! 3: * All rights reserved.
! 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 _EVRPC_H_
! 28: #define _EVRPC_H_
! 29:
! 30: #ifdef __cplusplus
! 31: extern "C" {
! 32: #endif
! 33:
! 34: /** @file evrpc.h
! 35: *
! 36: * This header files provides basic support for an RPC server and client.
! 37: *
! 38: * To support RPCs in a server, every supported RPC command needs to be
! 39: * defined and registered.
! 40: *
! 41: * EVRPC_HEADER(SendCommand, Request, Reply);
! 42: *
! 43: * SendCommand is the name of the RPC command.
! 44: * Request is the name of a structure generated by event_rpcgen.py.
! 45: * It contains all parameters relating to the SendCommand RPC. The
! 46: * server needs to fill in the Reply structure.
! 47: * Reply is the name of a structure generated by event_rpcgen.py. It
! 48: * contains the answer to the RPC.
! 49: *
! 50: * To register an RPC with an HTTP server, you need to first create an RPC
! 51: * base with:
! 52: *
! 53: * struct evrpc_base *base = evrpc_init(http);
! 54: *
! 55: * A specific RPC can then be registered with
! 56: *
! 57: * EVRPC_REGISTER(base, SendCommand, Request, Reply, FunctionCB, arg);
! 58: *
! 59: * when the server receives an appropriately formatted RPC, the user callback
! 60: * is invokved. The callback needs to fill in the reply structure.
! 61: *
! 62: * void FunctionCB(EVRPC_STRUCT(SendCommand)* rpc, void *arg);
! 63: *
! 64: * To send the reply, call EVRPC_REQUEST_DONE(rpc);
! 65: *
! 66: * See the regression test for an example.
! 67: */
! 68:
! 69: struct evbuffer;
! 70: struct event_base;
! 71: struct evrpc_req_generic;
! 72:
! 73: /* Encapsulates a request */
! 74: struct evrpc {
! 75: TAILQ_ENTRY(evrpc) next;
! 76:
! 77: /* the URI at which the request handler lives */
! 78: const char* uri;
! 79:
! 80: /* creates a new request structure */
! 81: void *(*request_new)(void);
! 82:
! 83: /* frees the request structure */
! 84: void (*request_free)(void *);
! 85:
! 86: /* unmarshals the buffer into the proper request structure */
! 87: int (*request_unmarshal)(void *, struct evbuffer *);
! 88:
! 89: /* creates a new reply structure */
! 90: void *(*reply_new)(void);
! 91:
! 92: /* creates a new reply structure */
! 93: void (*reply_free)(void *);
! 94:
! 95: /* verifies that the reply is valid */
! 96: int (*reply_complete)(void *);
! 97:
! 98: /* marshals the reply into a buffer */
! 99: void (*reply_marshal)(struct evbuffer*, void *);
! 100:
! 101: /* the callback invoked for each received rpc */
! 102: void (*cb)(struct evrpc_req_generic *, void *);
! 103: void *cb_arg;
! 104:
! 105: /* reference for further configuration */
! 106: struct evrpc_base *base;
! 107: };
! 108:
! 109: /** The type of a specific RPC Message
! 110: *
! 111: * @param rpcname the name of the RPC message
! 112: */
! 113: #define EVRPC_STRUCT(rpcname) struct evrpc_req__##rpcname
! 114:
! 115: struct evhttp_request;
! 116: struct evrpc_status;
! 117:
! 118: /* We alias the RPC specific structs to this voided one */
! 119: struct evrpc_req_generic {
! 120: /* the unmarshaled request object */
! 121: void *request;
! 122:
! 123: /* the empty reply object that needs to be filled in */
! 124: void *reply;
! 125:
! 126: /*
! 127: * the static structure for this rpc; that can be used to
! 128: * automatically unmarshal and marshal the http buffers.
! 129: */
! 130: struct evrpc *rpc;
! 131:
! 132: /*
! 133: * the http request structure on which we need to answer.
! 134: */
! 135: struct evhttp_request* http_req;
! 136:
! 137: /*
! 138: * callback to reply and finish answering this rpc
! 139: */
! 140: void (*done)(struct evrpc_req_generic* rpc);
! 141: };
! 142:
! 143: /** Creates the definitions and prototypes for an RPC
! 144: *
! 145: * You need to use EVRPC_HEADER to create structures and function prototypes
! 146: * needed by the server and client implementation. The structures have to be
! 147: * defined in an .rpc file and converted to source code via event_rpcgen.py
! 148: *
! 149: * @param rpcname the name of the RPC
! 150: * @param reqstruct the name of the RPC request structure
! 151: * @param replystruct the name of the RPC reply structure
! 152: * @see EVRPC_GENERATE()
! 153: */
! 154: #define EVRPC_HEADER(rpcname, reqstruct, rplystruct) \
! 155: EVRPC_STRUCT(rpcname) { \
! 156: struct reqstruct* request; \
! 157: struct rplystruct* reply; \
! 158: struct evrpc* rpc; \
! 159: struct evhttp_request* http_req; \
! 160: void (*done)(struct evrpc_status *, \
! 161: struct evrpc* rpc, void *request, void *reply); \
! 162: }; \
! 163: int evrpc_send_request_##rpcname(struct evrpc_pool *, \
! 164: struct reqstruct *, struct rplystruct *, \
! 165: void (*)(struct evrpc_status *, \
! 166: struct reqstruct *, struct rplystruct *, void *cbarg), \
! 167: void *);
! 168:
! 169: /** Generates the code for receiving and sending an RPC message
! 170: *
! 171: * EVRPC_GENERATE is used to create the code corresponding to sending
! 172: * and receiving a particular RPC message
! 173: *
! 174: * @param rpcname the name of the RPC
! 175: * @param reqstruct the name of the RPC request structure
! 176: * @param replystruct the name of the RPC reply structure
! 177: * @see EVRPC_HEADER()
! 178: */
! 179: #define EVRPC_GENERATE(rpcname, reqstruct, rplystruct) \
! 180: int evrpc_send_request_##rpcname(struct evrpc_pool *pool, \
! 181: struct reqstruct *request, struct rplystruct *reply, \
! 182: void (*cb)(struct evrpc_status *, \
! 183: struct reqstruct *, struct rplystruct *, void *cbarg), \
! 184: void *cbarg) { \
! 185: struct evrpc_status status; \
! 186: struct evrpc_request_wrapper *ctx; \
! 187: ctx = (struct evrpc_request_wrapper *) \
! 188: malloc(sizeof(struct evrpc_request_wrapper)); \
! 189: if (ctx == NULL) \
! 190: goto error; \
! 191: ctx->pool = pool; \
! 192: ctx->evcon = NULL; \
! 193: ctx->name = strdup(#rpcname); \
! 194: if (ctx->name == NULL) { \
! 195: free(ctx); \
! 196: goto error; \
! 197: } \
! 198: ctx->cb = (void (*)(struct evrpc_status *, \
! 199: void *, void *, void *))cb; \
! 200: ctx->cb_arg = cbarg; \
! 201: ctx->request = (void *)request; \
! 202: ctx->reply = (void *)reply; \
! 203: ctx->request_marshal = (void (*)(struct evbuffer *, void *))reqstruct##_marshal; \
! 204: ctx->reply_clear = (void (*)(void *))rplystruct##_clear; \
! 205: ctx->reply_unmarshal = (int (*)(void *, struct evbuffer *))rplystruct##_unmarshal; \
! 206: return (evrpc_make_request(ctx)); \
! 207: error: \
! 208: memset(&status, 0, sizeof(status)); \
! 209: status.error = EVRPC_STATUS_ERR_UNSTARTED; \
! 210: (*(cb))(&status, request, reply, cbarg); \
! 211: return (-1); \
! 212: }
! 213:
! 214: /** Provides access to the HTTP request object underlying an RPC
! 215: *
! 216: * Access to the underlying http object; can be used to look at headers or
! 217: * for getting the remote ip address
! 218: *
! 219: * @param rpc_req the rpc request structure provided to the server callback
! 220: * @return an struct evhttp_request object that can be inspected for
! 221: * HTTP headers or sender information.
! 222: */
! 223: #define EVRPC_REQUEST_HTTP(rpc_req) (rpc_req)->http_req
! 224:
! 225: /** Creates the reply to an RPC request
! 226: *
! 227: * EVRPC_REQUEST_DONE is used to answer a request; the reply is expected
! 228: * to have been filled in. The request and reply pointers become invalid
! 229: * after this call has finished.
! 230: *
! 231: * @param rpc_req the rpc request structure provided to the server callback
! 232: */
! 233: #define EVRPC_REQUEST_DONE(rpc_req) do { \
! 234: struct evrpc_req_generic *_req = (struct evrpc_req_generic *)(rpc_req); \
! 235: _req->done(_req); \
! 236: } while (0)
! 237:
! 238:
! 239: /* Takes a request object and fills it in with the right magic */
! 240: #define EVRPC_REGISTER_OBJECT(rpc, name, request, reply) \
! 241: do { \
! 242: (rpc)->uri = strdup(#name); \
! 243: if ((rpc)->uri == NULL) { \
! 244: fprintf(stderr, "failed to register object\n"); \
! 245: exit(1); \
! 246: } \
! 247: (rpc)->request_new = (void *(*)(void))request##_new; \
! 248: (rpc)->request_free = (void (*)(void *))request##_free; \
! 249: (rpc)->request_unmarshal = (int (*)(void *, struct evbuffer *))request##_unmarshal; \
! 250: (rpc)->reply_new = (void *(*)(void))reply##_new; \
! 251: (rpc)->reply_free = (void (*)(void *))reply##_free; \
! 252: (rpc)->reply_complete = (int (*)(void *))reply##_complete; \
! 253: (rpc)->reply_marshal = (void (*)(struct evbuffer*, void *))reply##_marshal; \
! 254: } while (0)
! 255:
! 256: struct evrpc_base;
! 257: struct evhttp;
! 258:
! 259: /* functions to start up the rpc system */
! 260:
! 261: /** Creates a new rpc base from which RPC requests can be received
! 262: *
! 263: * @param server a pointer to an existing HTTP server
! 264: * @return a newly allocated evrpc_base struct
! 265: * @see evrpc_free()
! 266: */
! 267: struct evrpc_base *evrpc_init(struct evhttp *server);
! 268:
! 269: /**
! 270: * Frees the evrpc base
! 271: *
! 272: * For now, you are responsible for making sure that no rpcs are ongoing.
! 273: *
! 274: * @param base the evrpc_base object to be freed
! 275: * @see evrpc_init
! 276: */
! 277: void evrpc_free(struct evrpc_base *base);
! 278:
! 279: /** register RPCs with the HTTP Server
! 280: *
! 281: * registers a new RPC with the HTTP server, each RPC needs to have
! 282: * a unique name under which it can be identified.
! 283: *
! 284: * @param base the evrpc_base structure in which the RPC should be
! 285: * registered.
! 286: * @param name the name of the RPC
! 287: * @param request the name of the RPC request structure
! 288: * @param reply the name of the RPC reply structure
! 289: * @param callback the callback that should be invoked when the RPC
! 290: * is received. The callback has the following prototype
! 291: * void (*callback)(EVRPC_STRUCT(Message)* rpc, void *arg)
! 292: * @param cbarg an additional parameter that can be passed to the callback.
! 293: * The parameter can be used to carry around state.
! 294: */
! 295: #define EVRPC_REGISTER(base, name, request, reply, callback, cbarg) \
! 296: do { \
! 297: struct evrpc* rpc = (struct evrpc *)calloc(1, sizeof(struct evrpc)); \
! 298: EVRPC_REGISTER_OBJECT(rpc, name, request, reply); \
! 299: evrpc_register_rpc(base, rpc, \
! 300: (void (*)(struct evrpc_req_generic*, void *))callback, cbarg); \
! 301: } while (0)
! 302:
! 303: int evrpc_register_rpc(struct evrpc_base *, struct evrpc *,
! 304: void (*)(struct evrpc_req_generic*, void *), void *);
! 305:
! 306: /**
! 307: * Unregisters an already registered RPC
! 308: *
! 309: * @param base the evrpc_base object from which to unregister an RPC
! 310: * @param name the name of the rpc to unregister
! 311: * @return -1 on error or 0 when successful.
! 312: * @see EVRPC_REGISTER()
! 313: */
! 314: #define EVRPC_UNREGISTER(base, name) evrpc_unregister_rpc(base, #name)
! 315:
! 316: int evrpc_unregister_rpc(struct evrpc_base *base, const char *name);
! 317:
! 318: /*
! 319: * Client-side RPC support
! 320: */
! 321:
! 322: struct evrpc_pool;
! 323: struct evhttp_connection;
! 324:
! 325: /**
! 326: * provides information about the completed RPC request.
! 327: */
! 328: struct evrpc_status {
! 329: #define EVRPC_STATUS_ERR_NONE 0
! 330: #define EVRPC_STATUS_ERR_TIMEOUT 1
! 331: #define EVRPC_STATUS_ERR_BADPAYLOAD 2
! 332: #define EVRPC_STATUS_ERR_UNSTARTED 3
! 333: #define EVRPC_STATUS_ERR_HOOKABORTED 4
! 334: int error;
! 335:
! 336: /* for looking at headers or other information */
! 337: struct evhttp_request *http_req;
! 338: };
! 339:
! 340: struct evrpc_request_wrapper {
! 341: TAILQ_ENTRY(evrpc_request_wrapper) next;
! 342:
! 343: /* pool on which this rpc request is being made */
! 344: struct evrpc_pool *pool;
! 345:
! 346: /* connection on which the request is being sent */
! 347: struct evhttp_connection *evcon;
! 348:
! 349: /* event for implementing request timeouts */
! 350: struct event ev_timeout;
! 351:
! 352: /* the name of the rpc */
! 353: char *name;
! 354:
! 355: /* callback */
! 356: void (*cb)(struct evrpc_status*, void *request, void *reply, void *arg);
! 357: void *cb_arg;
! 358:
! 359: void *request;
! 360: void *reply;
! 361:
! 362: /* unmarshals the buffer into the proper request structure */
! 363: void (*request_marshal)(struct evbuffer *, void *);
! 364:
! 365: /* removes all stored state in the reply */
! 366: void (*reply_clear)(void *);
! 367:
! 368: /* marshals the reply into a buffer */
! 369: int (*reply_unmarshal)(void *, struct evbuffer*);
! 370: };
! 371:
! 372: /** launches an RPC and sends it to the server
! 373: *
! 374: * EVRPC_MAKE_REQUEST() is used by the client to send an RPC to the server.
! 375: *
! 376: * @param name the name of the RPC
! 377: * @param pool the evrpc_pool that contains the connection objects over which
! 378: * the request should be sent.
! 379: * @param request a pointer to the RPC request structure - it contains the
! 380: * data to be sent to the server.
! 381: * @param reply a pointer to the RPC reply structure. It is going to be filled
! 382: * if the request was answered successfully
! 383: * @param cb the callback to invoke when the RPC request has been answered
! 384: * @param cbarg an additional argument to be passed to the client
! 385: * @return 0 on success, -1 on failure
! 386: */
! 387: #define EVRPC_MAKE_REQUEST(name, pool, request, reply, cb, cbarg) \
! 388: evrpc_send_request_##name(pool, request, reply, cb, cbarg)
! 389:
! 390: int evrpc_make_request(struct evrpc_request_wrapper *);
! 391:
! 392: /** creates an rpc connection pool
! 393: *
! 394: * a pool has a number of connections associated with it.
! 395: * rpc requests are always made via a pool.
! 396: *
! 397: * @param base a pointer to an struct event_based object; can be left NULL
! 398: * in singled-threaded applications
! 399: * @return a newly allocated struct evrpc_pool object
! 400: * @see evrpc_pool_free()
! 401: */
! 402: struct evrpc_pool *evrpc_pool_new(struct event_base *base);
! 403: /** frees an rpc connection pool
! 404: *
! 405: * @param pool a pointer to an evrpc_pool allocated via evrpc_pool_new()
! 406: * @see evrpc_pool_new()
! 407: */
! 408: void evrpc_pool_free(struct evrpc_pool *pool);
! 409: /*
! 410: * adds a connection over which rpc can be dispatched. the connection
! 411: * object must have been newly created.
! 412: */
! 413: void evrpc_pool_add_connection(struct evrpc_pool *,
! 414: struct evhttp_connection *);
! 415:
! 416: /**
! 417: * Sets the timeout in secs after which a request has to complete. The
! 418: * RPC is completely aborted if it does not complete by then. Setting
! 419: * the timeout to 0 means that it never timeouts and can be used to
! 420: * implement callback type RPCs.
! 421: *
! 422: * Any connection already in the pool will be updated with the new
! 423: * timeout. Connections added to the pool after set_timeout has be
! 424: * called receive the pool timeout only if no timeout has been set
! 425: * for the connection itself.
! 426: *
! 427: * @param pool a pointer to a struct evrpc_pool object
! 428: * @param timeout_in_secs the number of seconds after which a request should
! 429: * timeout and a failure be returned to the callback.
! 430: */
! 431: void evrpc_pool_set_timeout(struct evrpc_pool *pool, int timeout_in_secs);
! 432:
! 433: /**
! 434: * Hooks for changing the input and output of RPCs; this can be used to
! 435: * implement compression, authentication, encryption, ...
! 436: */
! 437:
! 438: enum EVRPC_HOOK_TYPE {
! 439: EVRPC_INPUT, /**< apply the function to an input hook */
! 440: EVRPC_OUTPUT /**< apply the function to an output hook */
! 441: };
! 442:
! 443: #ifndef WIN32
! 444: /** Deprecated alias for EVRPC_INPUT. Not available on windows, where it
! 445: * conflicts with platform headers. */
! 446: #define INPUT EVRPC_INPUT
! 447: /** Deprecated alias for EVRPC_OUTPUT. Not available on windows, where it
! 448: * conflicts with platform headers. */
! 449: #define OUTPUT EVRPC_OUTPUT
! 450: #endif
! 451:
! 452: /** adds a processing hook to either an rpc base or rpc pool
! 453: *
! 454: * If a hook returns -1, the processing is aborted.
! 455: *
! 456: * The add functions return handles that can be used for removing hooks.
! 457: *
! 458: * @param vbase a pointer to either struct evrpc_base or struct evrpc_pool
! 459: * @param hook_type either INPUT or OUTPUT
! 460: * @param cb the callback to call when the hook is activated
! 461: * @param cb_arg an additional argument for the callback
! 462: * @return a handle to the hook so it can be removed later
! 463: * @see evrpc_remove_hook()
! 464: */
! 465: void *evrpc_add_hook(void *vbase,
! 466: enum EVRPC_HOOK_TYPE hook_type,
! 467: int (*cb)(struct evhttp_request *, struct evbuffer *, void *),
! 468: void *cb_arg);
! 469:
! 470: /** removes a previously added hook
! 471: *
! 472: * @param vbase a pointer to either struct evrpc_base or struct evrpc_pool
! 473: * @param hook_type either INPUT or OUTPUT
! 474: * @param handle a handle returned by evrpc_add_hook()
! 475: * @return 1 on success or 0 on failure
! 476: * @see evrpc_add_hook()
! 477: */
! 478: int evrpc_remove_hook(void *vbase,
! 479: enum EVRPC_HOOK_TYPE hook_type,
! 480: void *handle);
! 481:
! 482: #ifdef __cplusplus
! 483: }
! 484: #endif
! 485:
! 486: #endif /* _EVRPC_H_ */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to evrpc.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libevent