aboutsummaryrefslogtreecommitdiff
path: root/web/module.hxx
diff options
context:
space:
mode:
Diffstat (limited to 'web/module.hxx')
-rw-r--r--web/module.hxx79
1 files changed, 56 insertions, 23 deletions
diff --git a/web/module.hxx b/web/module.hxx
index de534fb..dd98c29 100644
--- a/web/module.hxx
+++ b/web/module.hxx
@@ -62,7 +62,7 @@ namespace web
sequence_error (std::string d): std::runtime_error (std::move (d)) {}
};
- // Map of module configuration option names to the boolean flag indicating
+ // Map of handler configuration option names to the boolean flag indicating
// whether the value is expected for the option.
//
using option_descriptions = std::map<std::string, bool>;
@@ -90,9 +90,9 @@ namespace web
virtual
~request () = default;
- // Corresponds to abs_path portion of HTTP URL as described in
- // "3.2.2 HTTP URL" of http://tools.ietf.org/html/rfc2616.
- // Returns '/' if no abs_path is present in URL.
+ // Corresponds to abs_path portion of HTTP URL as described in "3.2.2 HTTP
+ // URL" of http://tools.ietf.org/html/rfc2616. Returns '/' if no abs_path
+ // is present in URL.
//
virtual const path_type&
path () = 0;
@@ -102,10 +102,43 @@ namespace web
// in name_values.
//@@ Maybe parameter_list() and parameter_map()?
//
- // Throw invalid_request if decoding of any name or value fails.
+ // Parse parameters from the URL query part and from the HTTP POST request
+ // body for the application/x-www-form-urlencoded or multipart/form-data
+ // content type. Optionally limit the amount of data read from the body
+ // (see the content() function for the semantics). Throw invalid_request
+ // if parameters decoding fails.
//
virtual const name_values&
- parameters () = 0;
+ parameters (std::size_t limit, bool url_only = false) = 0;
+
+ // Open the input stream for the upload corresponding to the specified
+ // parameter index. Must be called after the parameters() function is
+ // called, throw sequence_error if that's not the case. Throw
+ // invalid_argument if the index doesn't have an upload (for example,
+ // because the parameter is not <input type="file"/> form field).
+ //
+ // Note also that reopening the same upload (within the same retry)
+ // returns the same stream reference.
+ //
+ virtual std::istream&
+ open_upload (std::size_t index) = 0;
+
+ // As above but specify the parameter by name. Throw invalid_argument if
+ // there are multiple uploads for this parameter name.
+ //
+ virtual std::istream&
+ open_upload (const std::string& name) = 0;
+
+ // Request headers.
+ //
+ // The implementation may add custom pseudo-headers reflecting additional
+ // request options. Such headers should start with ':'. If possible, the
+ // implementation should add the following well-known pseudo-headers:
+ //
+ // :Client-IP - IP address of the connecting client.
+ //
+ virtual const name_values&
+ headers () = 0;
// Throw invalid_request if cookies are malformed.
//
@@ -126,7 +159,7 @@ namespace web
// sequence_error exception being thrown.
//
virtual std::istream&
- content (size_t limit = 0, size_t buffer = 0) = 0;
+ content (std::size_t limit, std::size_t buffer = 0) = 0;
};
class response
@@ -145,7 +178,7 @@ namespace web
// and the status code is changed, then the old content is
// discarded. If the content was not buffered and the status
// is changed, then the sequence_error exception is thrown.
- // If this exception leaves module::handle(), then the
+ // If this exception leaves handler::handle(), then the
// implementation shall terminate the response in a suitable
// but unspecified manner. In particular, there is no guarantee
// that the user will be notified of an error or observe the
@@ -176,11 +209,11 @@ namespace web
bool buffer = true) = 0;
};
- // A web server logging backend. The module can use it to log
+ // A web server logging backend. The handler can use it to log
// diagnostics that is meant for the web server operator rather
// than the user.
//
- // The module can cast this basic interface to the web server's
+ // The handler can cast this basic interface to the web server's
// specific implementation that may provide a richer interface.
//
class log
@@ -193,39 +226,39 @@ namespace web
write (const char* msg) = 0;
};
- // The web server creates a new module instance for each request
- // by copy-initializing it with the module exemplar. This way we
- // achieve two things: we can freely use module data members
+ // The web server creates a new handler instance for each request
+ // by copy-initializing it with the handler exemplar. This way we
+ // achieve two things: we can freely use handler data members
// without worrying about multi-threading issues and we
// automatically get started with the initial state for each
// request. If you really need to share some rw-data between
- // all the modules, use static data members with appropriate
+ // all the handlers, use static data members with appropriate
// locking. See the <service> header in one of the web server
// directories (e.g., apache/) if you need to see the code that
// does this.
//
- class module
+ class handler
{
public:
virtual
- ~module () = default;
+ ~handler () = default;
- // Description of configuration options supported by this module. Note:
+ // Description of configuration options supported by this handler. Note:
// should be callable during static initialization.
//
virtual option_descriptions
options () = 0;
- // During startup the web server calls this function on the module
- // exemplar to log the module version information. It is up to the web
- // server whether to call this function once per module implementation
+ // During startup the web server calls this function on the handler
+ // exemplar to log the handler version information. It is up to the web
+ // server whether to call this function once per handler implementation
// type. Therefore, it is expected that this function will log the same
- // information for all the module exemplars.
+ // information for all the handler exemplars.
//
virtual void
version (log&) = 0;
- // During startup the web server calls this function on the module
+ // During startup the web server calls this function on the handler
// exemplar passing a list of configuration options. The place these
// configuration options come from is implementation-specific (normally
// a configuration file). The web server guarantees that only options
@@ -242,7 +275,7 @@ namespace web
// unspecified manner.
//
// Throw retry if need to retry handling the request. The retry will
- // happen on the same instance of the module and the implementation is
+ // happen on the same instance of the handler and the implementation is
// expected to "rewind" the request and response objects to their initial
// state. This is only guaranteed to be possible if the relevant functions
// in the request and response objects were called in buffered mode (the