From dc2317f921f6d0041ae387cccdf7e0368f4920b0 Mon Sep 17 00:00:00 2001 From: Niels Provos Date: Sun, 4 Nov 2007 06:35:29 +0000 Subject: [PATCH] improve doxygen documentation svn:r473 --- Doxyfile | 2 +- event.h | 16 ++++-- evhttp.h | 13 +++-- evrpc.h | 161 +++++++++++++++++++++++++++++++++++++++++++++++-------- 4 files changed, 160 insertions(+), 32 deletions(-) diff --git a/Doxyfile b/Doxyfile index 08fcdae3..77f6de89 100644 --- a/Doxyfile +++ b/Doxyfile @@ -54,7 +54,7 @@ SORT_BRIEF_DOCS = YES # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = event.h evdns.h evhttp.h +INPUT = event.h evdns.h evhttp.h evrpc.h #--------------------------------------------------------------------------- # configuration options related to the HTML output diff --git a/event.h b/event.h index 14817722..0ff8fd5f 100644 --- a/event.h +++ b/event.h @@ -118,13 +118,18 @@ embedded in your program and used to service HTTP requests. To use this capability, you need to include the header in your - program. You create the server by calling evhttp_start() and providing the - address and port to listen on. You then register one or more callbacks to - handle incoming requests. Each URI can be assigned a callback via the - evhttp_set_cb() function. A generic callback function can also be + program. You create the server by calling evhttp_new(). Add addresses and + ports to listen on with evhttp_bind_socket(). You then register one or more + callbacks to handle incoming requests. Each URI can be assigned a callback + via the evhttp_set_cb() function. A generic callback function can also be registered via evhttp_set_gencb(); this callback will be invoked if no other callbacks have been registered for a given URI. + @section evrpc A framework for RPC servers and clients + + libevents provides a framework for creating RPC servers and clients. It + takes care of marshaling and unmarshaling all data structures. + @section api API Reference To browse the complete documentation of the libevent API, click on any of @@ -139,6 +144,9 @@ evhttp.h An embedded libevent-based HTTP server + evrpc.h + A framework for creating RPC servers and clients + */ /** @file event.h diff --git a/evhttp.h b/evhttp.h index 13cea8b2..fe16c6f5 100644 --- a/evhttp.h +++ b/evhttp.h @@ -124,7 +124,8 @@ void evhttp_set_timeout(struct evhttp *, int timeout_in_secs); * @param error the HTTP error code * @param reason a brief explanation of the error */ -void evhttp_send_error(struct evhttp_request *, int, const char *); +void evhttp_send_error(struct evhttp_request *req, int error, + const char *reason); /** * Send an HTML reply to the client. @@ -134,17 +135,21 @@ void evhttp_send_error(struct evhttp_request *, int, const char *); * @param reason a brief message to send with the response code * @param databuf the body of the response */ -void evhttp_send_reply(struct evhttp_request *, int, const char *, - struct evbuffer *); +void evhttp_send_reply(struct evhttp_request *req, int code, + const char *reason, struct evbuffer *databuf); /* Low-level response interface, for streaming/chunked replies */ void evhttp_send_reply_start(struct evhttp_request *, int, const char *); void evhttp_send_reply_chunk(struct evhttp_request *, struct evbuffer *); void evhttp_send_reply_end(struct evhttp_request *); -/* +/** * Start an HTTP server on the specified address and port * DEPRECATED: it does not allow an event base to be specified + * + * @param address the address to which the HTTP server should be bound + * @param port the port number on which the HTTP server should listen + * @return an struct evhttp object */ struct evhttp *evhttp_start(const char *address, u_short port); diff --git a/evrpc.h b/evrpc.h index 99b24b0a..45f684ac 100644 --- a/evrpc.h +++ b/evrpc.h @@ -31,7 +31,8 @@ extern "C" { #endif -/* +/** @file evrpc.h + * * This header files provides basic support for an RPC server and client. * * To support RPCs in a server, every supported RPC command needs to be @@ -105,6 +106,10 @@ struct evrpc { struct evrpc_base *base; }; +/** The type of a specific RPC Message + * + * @param rpcname the name of the RPC message + */ #define EVRPC_STRUCT(rpcname) struct evrpc_req__##rpcname struct evhttp_request; @@ -135,9 +140,16 @@ struct evrpc_req_generic { void (*done)(struct evrpc_req_generic* rpc); }; -/* +/** Creates the definitions and prototypes for an RPC + * * You need to use EVRPC_HEADER to create structures and function prototypes - * needed by the server and client implementation. + * 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 + * + * @param rpcname the name of the RPC + * @param reqstruct the name of the RPC request structure + * @param replystruct the name of the RPC reply structure + * @see EVRPC_GENERATE() */ #define EVRPC_HEADER(rpcname, reqstruct, rplystruct) \ EVRPC_STRUCT(rpcname) { \ @@ -154,6 +166,16 @@ int evrpc_send_request_##rpcname(struct evrpc_pool *, \ struct reqstruct *, struct rplystruct *, void *cbarg), \ void *); +/** 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 + * + * @param rpcname the name of the RPC + * @param reqstruct the name of the RPC request structure + * @param replystruct the name of the RPC reply structure + * @see EVRPC_HEADER() + */ #define EVRPC_GENERATE(rpcname, reqstruct, rplystruct) \ int evrpc_send_request_##rpcname(struct evrpc_pool *pool, \ struct reqstruct *request, struct rplystruct *reply, \ @@ -189,16 +211,24 @@ error: \ return (-1); \ } -/* +/** 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 + * + * @param rpc_req the rpc request structure provided to the server callback + * @return an struct evhttp_request object that can be inspected for + * HTTP headers or sender information. */ #define EVRPC_REQUEST_HTTP(rpc_req) (rpc_req)->http_req -/* +/** Creates the reply to an RPC request + * * 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. + * + * @param rpc_req the rpc request structure provided to the server callback */ #define EVRPC_REQUEST_DONE(rpc_req) do { \ struct evrpc_req_generic *_req = (struct evrpc_req_generic *)(rpc_req); \ @@ -227,12 +257,41 @@ struct evrpc_base; struct evhttp; /* functions to start up the rpc system */ + +/** Creates a new rpc base from which RPC requests can be received + * + * @param server a pointer to an existing HTTP server + * @return a newly allocated evrpc_base struct + * @see evrpc_free() + */ struct evrpc_base *evrpc_init(struct evhttp *server); -/* frees the base - for now, you are responsible for making sure that no rpcs are ongoing */ -void evrpc_free(struct evrpc_base *); +/** + * Frees the evrpc base + * + * For now, you are responsible for making sure that no rpcs are ongoing. + * + * @param base the evrpc_base object to be freed + * @see evrpc_init + */ +void evrpc_free(struct evrpc_base *base); -/* this macro is used to register RPCs with the HTTP Server */ +/** register RPCs with the HTTP Server + * + * registers a new RPC with the HTTP server, each RPC needs to have + * a unique name under which it can be identified. + * + * @param base the evrpc_base structure in which the RPC should be + * registered. + * @param name the name of the RPC + * @param request the name of the RPC request structure + * @param reply the name of the RPC reply structure + * @param 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) + * @param cbarg an additional parameter that can be passed to the callback. + * The parameter can be used to carry around state. + */ #define EVRPC_REGISTER(base, name, request, reply, callback, cbarg) \ do { \ struct evrpc* rpc = (struct evrpc *)calloc(1, sizeof(struct evrpc)); \ @@ -244,10 +303,17 @@ void evrpc_free(struct evrpc_base *); int evrpc_register_rpc(struct evrpc_base *, struct evrpc *, void (*)(struct evrpc_req_generic*, void *), void *); -/* Takes the named RPCs and tried to unregister it */ +/** + * Unregisters an already registered RPC + * + * @param base the evrpc_base object from which to unregister an RPC + * @param name the name of the rpc to unregister + * @return -1 on error or 0 when successful. + * @see EVRPC_REGISTER() + */ #define EVRPC_UNREGISTER(base, name) evrpc_unregister_rpc(base, #name) -int evrpc_unregister_rpc(struct evrpc_base *, const char *name); +int evrpc_unregister_rpc(struct evrpc_base *base, const char *name); /* * Client-side RPC support @@ -256,6 +322,9 @@ int evrpc_unregister_rpc(struct evrpc_base *, const char *name); struct evrpc_pool; struct evhttp_connection; +/** + * provides information about the completed RPC request. + */ struct evrpc_status { #define EVRPC_STATUS_ERR_NONE 0 #define EVRPC_STATUS_ERR_TIMEOUT 1 @@ -300,17 +369,43 @@ struct evrpc_request_wrapper { int (*reply_unmarshal)(void *, struct evbuffer*); }; +/** launches an RPC and sends it to the server + * + * EVRPC_MAKE_REQUEST() is used by the client to send an RPC to the server. + * + * @param name the name of the RPC + * @param pool the evrpc_pool that contains the connection objects over which + * the request should be sent. + * @param request a pointer to the RPC request structure - it contains the + * data to be sent to the server. + * @param reply a pointer to the RPC reply structure. It is going to be filled + * if the request was answered successfully + * @param cb the callback to invoke when the RPC request has been answered + * @param cbarg an additional argument to be passed to the client + * @return 0 on success, -1 on failure + */ #define EVRPC_MAKE_REQUEST(name, pool, request, reply, cb, cbarg) \ evrpc_send_request_##name(pool, request, reply, cb, cbarg) int evrpc_make_request(struct evrpc_request_wrapper *); -/* +/** creates an rpc connection pool + * * a pool has a number of connections associated with it. * rpc requests are always made via a pool. + * + * @param base a pointer to an struct event_based object; can be left NULL + * in singled-threaded applications + * @return a newly allocated struct evrpc_pool object + * @see evrpc_pool_free() */ -struct evrpc_pool *evrpc_pool_new(struct event_base *); -void evrpc_pool_free(struct evrpc_pool *); +struct evrpc_pool *evrpc_pool_new(struct event_base *base); +/** frees an rpc connection pool + * + * @param pool a pointer to an evrpc_pool allocated via evrpc_pool_new() + * @see evrpc_pool_new() + */ +void evrpc_pool_free(struct evrpc_pool *pool); /* * adds a connection over which rpc can be dispatched. the connection * object must have been newly created. @@ -318,7 +413,7 @@ void evrpc_pool_free(struct evrpc_pool *); void evrpc_pool_add_connection(struct evrpc_pool *, struct evhttp_connection *); -/* +/** * 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 @@ -328,29 +423,49 @@ void evrpc_pool_add_connection(struct evrpc_pool *, * 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. + * + * @param pool a pointer to a struct evrpc_pool object + * @param timeout_in_secs the number of seconds after which a request should + * timeout and a failure be returned to the callback. */ -void evrpc_pool_set_timeout(struct evrpc_pool *, int timeout_in_secs); +void evrpc_pool_set_timeout(struct evrpc_pool *pool, int timeout_in_secs); -/* +/** * Hooks for changing the input and output of RPCs; this can be used to * implement compression, authentication, encryption, ... - * - * vbase may either be a pointer to struct evrpc_base or to struct evrpc_pool - * - * If a hook returns -1, the processing is aborted. - * - * The add functions return handles that can be used for removing hooks. */ enum EVRPC_HOOK_TYPE { - INPUT, OUTPUT + INPUT, /**< apply the function to an input hook */ + OUTPUT /**< apply the function to an output hook */ }; +/** 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. + * + * @param vbase a pointer to either struct evrpc_base or struct evrpc_pool + * @param hook_type either INPUT or OUTPUT + * @param cb the callback to call when the hook is activated + * @param cb_arg an additional argument for the callback + * @return a handle to the hook so it can be removed later + * @see evrpc_remove_hook() + */ void *evrpc_add_hook(void *vbase, enum EVRPC_HOOK_TYPE hook_type, int (*cb)(struct evhttp_request *, struct evbuffer *, void *), void *cb_arg); +/** removes a previously added hook + * + * @param vbase a pointer to either struct evrpc_base or struct evrpc_pool + * @param hook_type either INPUT or OUTPUT + * @param handle a handle returned by evrpc_add_hook() + * @return 1 on success or 0 on failure + * @see evrpc_add_hook() + */ int evrpc_remove_hook(void *vbase, enum EVRPC_HOOK_TYPE hook_type, void *handle); -- 2.40.0