boostorg/beast
1
0
Fork 1
mirror of https://github.com/boostorg/beast.git synced 2025-08-04 15:24:31 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update HTTP documentation (fix #61, #60, #59)

Browse Source
This commit is contained in:
Vinnie Falco
2016-08-26 09:00:28 -04:00
parent c17f467601
commit 796f20314c
9 changed files with 46 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
README.md
View File

@@ -56,13 +56,13 @@ int main()
// Normal boost::asio setup // Normal boost::asio setup
std::string const host = "echo.websocket.org"; std::string const host = "echo.websocket.org";
boost::asio::io_service ios; boost::asio::io_service ios;
boost::asio::ip::tcp::resolver r(ios); boost::asio::ip::tcp::resolver r{ios};
boost::asio::ip::tcp::socket sock(ios); boost::asio::ip::tcp::socket sock{ios};
boost::asio::connect(sock, boost::asio::connect(sock,
r.resolve(boost::asio::ip::tcp::resolver::query{host, "80"})); r.resolve(boost::asio::ip::tcp::resolver::query{host, "80"}));
// WebSocket connect and send message using beast // WebSocket connect and send message using beast
beast::websocket::stream<boost::asio::ip::tcp::socket&> ws(sock); beast::websocket::stream<boost::asio::ip::tcp::socket&> ws{sock};
ws.handshake(host, "/"); ws.handshake(host, "/");
ws.write(boost::asio::buffer("Hello, world!")); ws.write(boost::asio::buffer("Hello, world!"));
@@ -87,8 +87,8 @@ int main()
// Normal boost::asio setup // Normal boost::asio setup
std::string const host = "boost.org"; std::string const host = "boost.org";
boost::asio::io_service ios; boost::asio::io_service ios;
boost::asio::ip::tcp::resolver r(ios); boost::asio::ip::tcp::resolver r{ios};
boost::asio::ip::tcp::socket sock(ios); boost::asio::ip::tcp::socket sock{ios};
boost::asio::connect(sock, boost::asio::connect(sock,
r.resolve(boost::asio::ip::tcp::resolver::query{host, "http"})); r.resolve(boost::asio::ip::tcp::resolver::query{host, "http"}));

2
doc/Jamfile
View File

@@ -15,7 +15,7 @@ using boostbook ;
using quickbook ; using quickbook ;
using doxygen ; using doxygen ;
xml beast_boostbook : beast.qbk ; xml beast_boostbook : master.qbk ;
path-constant out : . ; path-constant out : . ;

10
doc/design.qbk
View File

@@ -192,9 +192,9 @@ start. Other design goals:
[websocketpp] [websocketpp]
][ ][
[``` [```
template<class Streambuf> template<class DynamicBuffer>
void void
read(opcode& op, Streambuf& streambuf) read(opcode& op, DynamicBuffer& dynabuf)
```] ```]
[ [
/<not available>/ /<not available>/
@@ -339,9 +339,9 @@ start. Other design goals:
[@https://github.com/zaphoyd/websocketpp/blob/378437aecdcb1dfe62096ffd5d944bf1f640ccc3/websocketpp/connection.hpp#L473 also]] [@https://github.com/zaphoyd/websocketpp/blob/378437aecdcb1dfe62096ffd5d944bf1f640ccc3/websocketpp/connection.hpp#L473 also]]
][ ][
[``` [```
template<class Streambuf, class ReadHandler> template<class DynamicBuffer, class ReadHandler>
typename async_completion<ReadHandler, void(error_code)>::result_type typename async_completion<ReadHandler, void(error_code)>::result_type
async_read(opcode& op, Streambuf& streambuf, ReadHandler&& handler); async_read(opcode& op, DynamicBuffer& dynabuf, ReadHandler&& handler);
```] ```]
[``` [```
typedef lib::function<void(connection_hdl,message_ptr)> message_handler; typedef lib::function<void(connection_hdl,message_ptr)> message_handler;
@@ -365,7 +365,7 @@ start. Other design goals:
][ ][
[``` [```
beast::async_completion<ReadHandler, void(error_code)> completion(handler); beast::async_completion<ReadHandler, void(error_code)> completion(handler);
read_op<Streambuf, decltype(completion.handler)>{ read_op<DynamicBuffer, decltype(completion.handler)>{
completion.handler, *this, op, streambuf}; completion.handler, *this, op, streambuf};
return completion.result.get(); return completion.result.get();
```] ```]

52
doc/http.qbk
View File

@@ -92,19 +92,20 @@ and its customization points in more depth, for advanced applications.
[heading Declarations] [heading Declarations]
To do anything, a message must be declared. The message class template To do anything, a message must be declared. The message class template
requires at mininum, a value indicating whether the message is a request requires at minimum, a value indicating whether the message is a request
(versus a response), and a `Body` type. The choice of `Body` determines the (versus a response), and a `Body` type. The choice of `Body` determines the
kind of container used to represent the message body. Here we will kind of container used to represent the message body. Here we will
declare a request that has a `std::string` for the body container: declare a HTTP/1 request that has a `std::string` for the body container:
``` ```
http::message<true, http::string_body> req; http::message_v1<true, http::string_body> req;
``` ```
Two type aliases are provided for notational convenience when declaring Two type aliases are provided for notational convenience when declaring
messages. These two statements declare a request and a response respectively: HTTP/1 messages. These two statements declare a request and a response
respectively:
``` ```
http::request<http::string_body> req; http::request_v1<http::string_body> req;
http::response<http::string_body> resp; http::response_v1<http::string_body> resp;
``` ```
[heading Members] [heading Members]
@@ -113,14 +114,14 @@ Message objects are default constructible, with public access to data members.
Request and response objects have some common members, and some members unique Request and response objects have some common members, and some members unique
to the message type. These statements set all the members in each message: to the message type. These statements set all the members in each message:
``` ```
http::request<http::string_body> req; http::request_v1<http::string_body> req;
req.method = http::method_t::http_get; req.method = "GET";
req.url = "/index.html"; req.url = "/index.html";
req.version = 11; // HTTP/1.1 req.version = 11; // HTTP/1.1
req.headers.insert("User-Agent", "hello_world"); req.headers.insert("User-Agent", "hello_world");
req.body = ""; req.body = "";
http::response<http::string_body> resp; http::response_v1<http::string_body> resp;
resp.status = 404; resp.status = 404;
resp.reason = "Not Found"; resp.reason = "Not Found";
resp.version = 10; // HTTP/1.0 resp.version = 10; // HTTP/1.0
@@ -128,17 +129,6 @@ to the message type. These statements set all the members in each message:
resp.body = "The requested resource was not found."; resp.body = "The requested resource was not found.";
``` ```
The following statements achieve the same effects as the statements above:
```
http::request<http::string_body> req({http::method_t::http_get, "/index.html", 11});
req.headers.insert("User-Agent", "hello_world");
req.body = "";
http::response<http::string_body> resp({404, "Not Found", 10});
resp.headers.insert("Server", "Beast.HTTP");
resp.body = "The requested resource was not found.";
```
[heading Headers] [heading Headers]
The `message::headers` member is a container for setting the field/value The `message::headers` member is a container for setting the field/value
@@ -146,7 +136,7 @@ pairs in the message. These statements change the values of the headers
in the message passed: in the message passed:
``` ```
template<class Body> template<class Body>
void set_fields(http::request<Body>& req) void set_fields(http::request_v1<Body>& req)
{ {
if(! req.exists("User-Agent")) if(! req.exists("User-Agent"))
req.insert("User-Agent", "myWebClient"); req.insert("User-Agent", "myWebClient");
@@ -168,7 +158,10 @@ following types, provided by the library, are suitable choices for the
* [link beast.ref.http__empty_body [*`empty_body`:]] An empty message body. * [link beast.ref.http__empty_body [*`empty_body`:]] An empty message body.
Used in GET requests where there is no message body. Example: Used in GET requests where there is no message body. Example:
``` ```
http::request<http::empty_body> req({http::method_t::http_get, "/index.html", 11}); http::request_v1<http::empty_body> req;
req.version = 11;
req.method = "GET";
req.url = "/index.html";
``` ```
* [link beast.ref.http__string_body [*`string_body`:]] A body with a * [link beast.ref.http__string_body [*`string_body`:]] A body with a
@@ -177,7 +170,7 @@ or response with simple text in the message body (such as an error message).
Has the same insertion complexity of `std::string`. This is the type of body Has the same insertion complexity of `std::string`. This is the type of body
used in the examples: used in the examples:
``` ```
http::response<http::string_body> resp; http::response_v1<http::string_body> resp;
static_assert(std::is_same<decltype(resp.body), std::string>::value); static_assert(std::is_same<decltype(resp.body), std::string>::value);
resp.body = "Here is the data you requested"; resp.body = "Here is the data you requested";
``` ```
@@ -197,7 +190,10 @@ functions:
``` ```
void send_request(boost::asio::ip::tcp::socket& sock) void send_request(boost::asio::ip::tcp::socket& sock)
{ {
http::request<http::empty_body> req({http::method_t::http_get, "/index.html", 11}); http::request<http::empty_body> req;
req.version = 11;
req.method = "GET";
req.url = "/index.html";
... ...
http::write(sock, req); // Throws exception on error http::write(sock, req); // Throws exception on error
... ...
@@ -213,7 +209,7 @@ An asynchronous interface is available:
``` ```
void handle_write(boost::system::error_code); void handle_write(boost::system::error_code);
... ...
http::request<http::empty_body> req; http::request_v1<http::empty_body> req;
... ...
http::async_write(sock, req, std::bind(&handle_write, std::placeholders::_1)); http::async_write(sock, req, std::bind(&handle_write, std::placeholders::_1));
``` ```
@@ -228,7 +224,7 @@ stored in the streambuf parameter for use in a subsequent call to read:
``` ```
boost::asio::streambuf sb; boost::asio::streambuf sb;
... ...
http::response<http::string_body> resp; http::response_v1<http::string_body> resp;
http::read(sock, sb, resp); // Throws exception on error http::read(sock, sb, resp); // Throws exception on error
... ...
// Alternatively // Alternatively
@@ -245,7 +241,7 @@ called:
void handle_read(boost::system::error_code); void handle_read(boost::system::error_code);
... ...
boost::asio::streambuf sb; boost::asio::streambuf sb;
http::response<http::string_body> resp; http::response_v1<http::string_body> resp;
... ...
http::async_read(sock, resp, std::bind(&handle_read, std::placeholders::_1)); http::async_read(sock, resp, std::bind(&handle_read, std::placeholders::_1));
``` ```
@@ -257,7 +253,7 @@ An alternative to using a `boost::asio::streambuf` is to use a
void handle_read(boost::system::error_code); void handle_read(boost::system::error_code);
... ...
beast::streambuf sb; beast::streambuf sb;
http::response<http::string_body> resp; http::response_v1<http::string_body> resp;
http::read(sock, sb, resp); http::read(sock, sb, resp);
``` ```

2
doc/makeqbk.sh
View File

@@ -6,7 +6,7 @@
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) # file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
mkdir -p ../bin/doc/xml mkdir -p ../bin/doc/xml
doxygen beast.dox doxygen source.dox
cd ../bin/doc/xml cd ../bin/doc/xml
xsltproc combine.xslt index.xml > all.xml xsltproc combine.xslt index.xml > all.xml
cd ../../../doc cd ../../../doc

10
doc/beast.qbk → doc/master.qbk
View File

@@ -106,8 +106,8 @@ int main()
// Normal boost::asio setup // Normal boost::asio setup
std::string const host = "boost.org"; std::string const host = "boost.org";
boost::asio::io_service ios; boost::asio::io_service ios;
boost::asio::ip::tcp::resolver r(ios); boost::asio::ip::tcp::resolver r{ios};
boost::asio::ip::tcp::socket sock(ios); boost::asio::ip::tcp::socket sock{ios};
boost::asio::connect(sock, boost::asio::connect(sock,
r.resolve(boost::asio::ip::tcp::resolver::query{host, "http"})); r.resolve(boost::asio::ip::tcp::resolver::query{host, "http"}));
@@ -142,13 +142,13 @@ int main()
// Normal boost::asio setup // Normal boost::asio setup
std::string const host = "echo.websocket.org"; std::string const host = "echo.websocket.org";
boost::asio::io_service ios; boost::asio::io_service ios;
boost::asio::ip::tcp::resolver r(ios); boost::asio::ip::tcp::resolver r{ios};
boost::asio::ip::tcp::socket sock(ios); boost::asio::ip::tcp::socket sock{ios};
boost::asio::connect(sock, boost::asio::connect(sock,
r.resolve(boost::asio::ip::tcp::resolver::query{host, "80"})); r.resolve(boost::asio::ip::tcp::resolver::query{host, "80"}));
// WebSocket connect and send message using beast // WebSocket connect and send message using beast
beast::websocket::stream<boost::asio::ip::tcp::socket&> ws(sock); beast::websocket::stream<boost::asio::ip::tcp::socket&> ws{sock};
ws.handshake(host, "/"); ws.handshake(host, "/");
ws.write(boost::asio::buffer("Hello, world!")); ws.write(boost::asio::buffer("Hello, world!"));

0
doc/beast.dox → doc/source.dox
View File

4
examples/http_example.cpp
View File

@@ -15,8 +15,8 @@ int main()
// Normal boost::asio setup // Normal boost::asio setup
std::string const host = "boost.org"; std::string const host = "boost.org";
boost::asio::io_service ios; boost::asio::io_service ios;
boost::asio::ip::tcp::resolver r(ios); boost::asio::ip::tcp::resolver r{ios};
boost::asio::ip::tcp::socket sock(ios); boost::asio::ip::tcp::socket sock{ios};
boost::asio::connect(sock, boost::asio::connect(sock,
r.resolve(boost::asio::ip::tcp::resolver::query{host, "http"})); r.resolve(boost::asio::ip::tcp::resolver::query{host, "http"}));

6
examples/websocket_example.cpp
View File

@@ -16,13 +16,13 @@ int main()
// Normal boost::asio setup // Normal boost::asio setup
std::string const host = "echo.websocket.org"; std::string const host = "echo.websocket.org";
boost::asio::io_service ios; boost::asio::io_service ios;
boost::asio::ip::tcp::resolver r(ios); boost::asio::ip::tcp::resolver r{ios};
boost::asio::ip::tcp::socket sock(ios); boost::asio::ip::tcp::socket sock{ios};
boost::asio::connect(sock, boost::asio::connect(sock,
r.resolve(boost::asio::ip::tcp::resolver::query{host, "80"})); r.resolve(boost::asio::ip::tcp::resolver::query{host, "80"}));
// WebSocket connect and send message using beast // WebSocket connect and send message using beast
beast::websocket::stream<boost::asio::ip::tcp::socket&> ws(sock); beast::websocket::stream<boost::asio::ip::tcp::socket&> ws{sock};
ws.handshake(host, "/"); ws.handshake(host, "/");
ws.write(boost::asio::buffer("Hello, world!")); ws.write(boost::asio::buffer("Hello, world!"));