walkero
/
nghttp2
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

asio: Document public APIs

This commit is contained in:
Tatsuhiro Tsujikawa 2015-03-06 01:41:06 +09:00
parent 42c174e803
commit 529fc937dc
3 changed files with 93 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
src/includes/nghttp2/asio_http2.h
View File

@ -53,10 +53,16 @@ namespace nghttp2 {
namespace asio_http2 {
struct header_value {
// header field value
std::string value;
// true if the header field value is sensitive information, such as
// authorization information or short length secret cookies. If
// true, those header fields are not indexed by HPACK (but still
// huffman-encoded), which results in lesser compression.
bool sensitive;
};
// header fields. The header field name must be lower-cased.
using header_map = std::multimap<std::string, header_value>;
const boost::system::error_category &nghttp2_category() noexcept;
@ -64,9 +70,11 @@ const boost::system::error_category &nghttp2_category() noexcept;
struct uri_ref {
std::string scheme;
std::string host;
// percent-decoded form
// form after percent-encoding decoded
std::string path;
// original path, percent-encoded
std::string raw_path;
// original query, percent-encoded
std::string raw_query;
std::string fragment;
};
@ -76,9 +84,21 @@ struct uri_ref {
typedef std::function<void(const uint8_t *, std::size_t)> data_cb;
typedef std::function<void(void)> void_cb;
typedef std::function<void(const boost::system::error_code &ec)> error_cb;
// Callback function when request and response are finished. The
// parameter indicates the cause of closure.
typedef std::function<void(uint32_t)> close_cb;
// Callback function to generate response body. TBD
// Callback function to generate response body. This function has the
// same semantics with nghttp2_data_source_read_callback. Just source
// and user_data parameters are removed.
//
// Basically, write at most |len| bytes to |data| and returns the
// number of bytes written. If there is no data left to send, set
// NGHTTP2_DATA_FLAG_EOF to *data_flags (e.g., *data_flags |=
// NGHTTP2_DATA_FLAG_EOF). If there is still data to send but they
// are not available right now, return NGHTTP2_ERR_DEFERRED. In case
// of the error and request/response must be closed, return
// NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE.
typedef std::function<
ssize_t(uint8_t *buf, std::size_t len, uint32_t *data_flags)> read_cb;

50
src/includes/nghttp2/asio_http2_client.h
View File

@ -37,17 +37,25 @@ class response_impl;
class response {
public:
// Application must not call this directly.
response();
~response();
// Sets callback which is invoked when chunk of response body is
// received.
void on_data(data_cb cb) const;
// Returns status code.
int status_code() const;
// Returns content-length. -1 if it is unknown.
int64_t content_length() const;
// Returns the response header fields. The pusedo header fields,
// which start with colon (:), are exluced from this list.
const header_map &header() const;
// Application must not call this directly.
response_impl &impl() const;
private:
@ -65,24 +73,39 @@ class request_impl;
class request {
public:
// Application must not call this directly.
request();
~request();
// Sets callback which is invoked when response header is received.
void on_response(response_cb cb) const;
// Sets callback which is invoked when push request header is
// received.
void on_push(request_cb cb) const;
// Sets callback which is invoked when this request and response are
// finished. After the invocation of this callback, the application
// must not access request and response object.
void on_close(close_cb cb) const;
// Cancels this request and response with given error code.
void cancel(uint32_t error_code = NGHTTP2_INTERNAL_ERROR) const;
// Resumes deferred uploading.
void resume() const;
// Returns method (e.g., GET).
const std::string &method() const;
// Returns request URI, split into components.
const uri_ref &uri() const;
// Returns request header fields. The pusedo header fields, which
// start with colon (:), are exluced from this list.
const header_map &header() const;
// Application must not call this directly.
request_impl &impl() const;
private:
@ -93,26 +116,53 @@ class session_impl;
class session {
public:
// Starts HTTP/2 session by connecting to |host| and |service|
// (e.g., "80") using clear text TCP connection.
session(boost::asio::io_service &io_service, const std::string &host,
const std::string &service);
// Starts HTTP/2 session by connecting to |host| and |service|
// (e.g., "443") using encrypted SSL/TLS connection.
session(boost::asio::io_service &io_service,
boost::asio::ssl::context &tls_context, const std::string &host,
const std::string &service);
~session();
// Sets callback which is invoked after connection is established.
void on_connect(connect_cb cb) const;
// Sets callback which is invoked there is connection level error
// and session is terminated.
void on_error(error_cb cb) const;
// Shutdowns connection.
void shutdown() const;
// Returns underlying io_service object.
boost::asio::io_service &io_service() const;
// Submits request to server using |method| (e.g., "GET"), |uri|
// (e.g., "http://localhost/") and optionally additional header
// fields. This function returns pointer to request object if it
// succeeds, or nullptr and |ec| contains error message.
const request *submit(boost::system::error_code &ec,
const std::string &method, const std::string &uri,
header_map h = {}) const;
// Submits request to server using |method| (e.g., "GET"), |uri|
// (e.g., "http://localhost/") and optionally additional header
// fields. The |data| is request body. This function returns
// pointer to request object if it succeeds, or nullptr and |ec|
// contains error message.
const request *submit(boost::system::error_code &ec,
const std::string &method, const std::string &uri,
std::string data, header_map h = {}) const;
// Submits request to server using |method| (e.g., "GET"), |uri|
// (e.g., "http://localhost/") and optionally additional header
// fields. The |cb| is used to generate request body. This
// function returns pointer to request object if it succeeds, or
// nullptr and |ec| contains error message.
const request *submit(boost::system::error_code &ec,
const std::string &method, const std::string &uri,
read_cb cb, header_map h = {}) const;

32
src/includes/nghttp2/asio_http2_server.h
View File

@ -42,8 +42,8 @@ public:
request();
~request();
// Returns request headers. The pusedo headers, which start with
// colon (:), are exluced from this list.
// Returns request header fields. The pusedo header fields, which
// start with colon (:), are exluced from this list.
const header_map &header() const;
// Returns method (e.g., GET).
@ -52,7 +52,8 @@ public:
// Returns request URI, split into components.
const uri_ref &uri() const;
// Sets callback when chunk of request body is received.
// Sets callback which is invoked when chunk of request body is
// received.
void on_data(data_cb cb) const;
// Application must not call this directly.
@ -69,28 +70,33 @@ public:
~response();
// Write response header using |status_code| (e.g., 200) and
// additional headers in |h|.
// additional header fields in |h|.
void write_head(unsigned int status_code, header_map h = {}) const;
// Sends |data| as request body. No further call of end() is
// allowed.
void end(std::string data = "") const;
// Sets callback |cb| as a generator of the response body. No
// further call of end() is allowed.
// Sets callback as a generator of the response body. No further
// call of end() is allowed.
void end(read_cb cb) const;
// Sets callback which is invoked when this request and response are
// finished. After the invocation of this callback, the application
// must not access request and response object.
void on_close(close_cb cb) const;
// Cancels this request and response with given error code.
void cancel(uint32_t error_code = NGHTTP2_INTERNAL_ERROR) const;
// Resumes deferred response.
void resume() const;
// Pushes resource denoted by |raw_path_query| using |method|. The
// additional headers can be given in |h|. This function returns
// pointer to response object for promised stream, otherwise nullptr
// and error code is filled in |ec|.
// additional header fields can be given in |h|. This function
// returns pointer to response object for promised stream, otherwise
// nullptr and error code is filled in |ec|. Be aware that the
// header field name given in |h| must be lower-cased.
const response *push(boost::system::error_code &ec, std::string method,
std::string raw_path_query, header_map h = {}) const;
@ -108,7 +114,9 @@ private:
};
// This is so called request callback. Called every time request is
// received.
// received. The life time of |request| and |response| objects end
// when callback set by response::on_close() is called. After that,
// the application must not access to those objects.
typedef std::function<void(const request &, const response &)> request_cb;
class http2_impl;
@ -124,7 +132,9 @@ public:
// Registers request handler |cb| with path pattern |pattern|. This
// function will fail and returns false if same pattern has been
// already registered. Otherwise returns true.
// already registered or |pattern| is empty string. Otherwise
// returns true. The pattern match rule is the same as
// net/http/ServeMux in golang.
bool handle(std::string pattern, request_cb cb);
// Sets number of native threads to handle incoming HTTP request.