diff options
Diffstat (limited to 'web/module.hxx')
| -rw-r--r-- | web/module.hxx | 79 |
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 |