From 7aff9c3475989278bf0c3bc69e6be499e78d59e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C5=99emysl=20Janouch?= Date: Mon, 15 Oct 2018 19:29:17 +0200 Subject: Improve documentation --- demo-json-rpc-server.c | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/demo-json-rpc-server.c b/demo-json-rpc-server.c index 476187c..9658e91 100644 --- a/demo-json-rpc-server.c +++ b/demo-json-rpc-server.c @@ -546,7 +546,7 @@ struct ws_handler // Actually, calling push() could work pretty fine for this. void (*on_close) (void *user_data, int close_code, const char *reason); - // Method callbacks: + // Virtual method callbacks: /// Write a chunk of data to the stream void (*write_cb) (void *user_data, const void *data, size_t len); @@ -1464,11 +1464,12 @@ process_json_rpc (struct server_context *ctx, /// @defgroup Requests /// @{ +/// A generic CGI request abstraction, writing data indirectly through callbacks struct request { struct server_context *ctx; ///< Server context - struct request_handler *handler; ///< Current request handler + struct request_handler *handler; ///< Assigned request handler void *handler_data; ///< User data for the handler /// Callback to write some CGI response data to the output @@ -1481,20 +1482,25 @@ struct request void *user_data; ///< User data argument for callbacks }; +/// An interface to detect and handle specific kinds of CGI requests. +/// The server walks through a list of them until it finds one that can serve +/// a particular request. If unsuccessful, the remote client gets a 404 +/// (the default handling). struct request_handler { LIST_HEADER (struct request_handler) - /// Install ourselves as the handler for the request if applicable. - /// Set @a continue_ to false if further processing should be stopped. + /// Install ourselves as the handler for the request, if applicable. + /// Sets @a continue_ to false if further processing should be stopped, + /// meaning the request has already been handled. bool (*try_handle) (struct request *request, struct str_map *headers, bool *continue_); /// Handle incoming data. - /// Return false if further processing should be stopped. + /// Returns false if there is no more processing to be done. bool (*push_cb) (struct request *request, const void *data, size_t len); - /// Destroy the handler + /// Destroy the handler's data stored in the request object void (*destroy_cb) (struct request *request); }; @@ -1792,6 +1798,8 @@ struct request_handler g_request_handler_static = // --- Client communication handlers ------------------------------------------- +/// A virtual class for client connections coming either from the web server +/// or directly from the end-client, depending on the protocol in use struct client { LIST_HEADER (struct client) @@ -1808,6 +1816,7 @@ struct client struct client_vtable *vtable; ///< Client behaviour }; +/// The concrete behaviour to serve a particular client's requests struct client_vtable { /// Attempt a graceful shutdown -- cgit v1.2.3