boostorg/beast
1
0
Fork 1
mirror of https://github.com/boostorg/beast.git synced 2025-08-04 07:14:32 +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
std::string const host = "echo.websocket.org";
boost::asio::io_service ios;
boost::asio::ip::tcp::resolver r(ios);
boost::asio::ip::tcp::socket sock(ios);
boost::asio::ip::tcp::resolver r{ios};
boost::asio::ip::tcp::socket sock{ios};
boost::asio::connect(sock,
r.resolve(boost::asio::ip::tcp::resolver::query{host, "80"}));
// 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.write(boost::asio::buffer("Hello, world!"));
@@ -87,8 +87,8 @@ int main()
// Normal boost::asio setup
std::string const host = "boost.org";
boost::asio::io_service ios;
boost::asio::ip::tcp::resolver r(ios);
boost::asio::ip::tcp::socket sock(ios);
boost::asio::ip::tcp::resolver r{ios};
boost::asio::ip::tcp::socket sock{ios};
boost::asio::connect(sock,
r.resolve(boost::asio::ip::tcp::resolver::query{host, "http"}));

2
doc/Jamfile
View File

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

10
doc/design.qbk
View File

@@ -192,9 +192,9 @@ start. Other design goals:
[websocketpp]
][
[```
template<class Streambuf>
template<class DynamicBuffer>
void
read(opcode& op, Streambuf& streambuf)
read(opcode& op, DynamicBuffer& dynabuf)
```]
[
/<not available>/
@@ -339,9 +339,9 @@ start. Other design goals:
[@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
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;
@@ -365,7 +365,7 @@ start. Other design goals:
][
[```
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};
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]
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
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
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::response<http::string_body> resp;
http::request_v1<http::string_body> req;
http::response_v1<http::string_body> resp;
```
[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
to the message type. These statements set all the members in each message:
```
http::request<http::string_body> req;
req.method = http::method_t::http_get;
http::request_v1<http::string_body> req;
req.method = "GET";
req.url = "/index.html";
req.version = 11; // HTTP/1.1
req.headers.insert("User-Agent", "hello_world");
req.body = "";
http::response<http::string_body> resp;
http::response_v1<http::string_body> resp;
resp.status = 404;
resp.reason = "Not Found";
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.";
```
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]
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:
```
template<class Body>
void set_fields(http::request<Body>& req)
void set_fields(http::request_v1<Body>& req)
{
if(! req.exists("User-Agent"))
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.
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
@@ -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
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);
resp.body = "Here is the data you requested";
```
@@ -197,7 +190,10 @@ functions:
```
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
...
@@ -213,7 +209,7 @@ An asynchronous interface is available:
```
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));
```
@@ -228,7 +224,7 @@ stored in the streambuf parameter for use in a subsequent call to read:
```
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
...
// Alternatively
@@ -245,7 +241,7 @@ called:
void handle_read(boost::system::error_code);
...
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));
```
@@ -257,7 +253,7 @@ An alternative to using a `boost::asio::streambuf` is to use a
void handle_read(boost::system::error_code);
...
beast::streambuf sb;
http::response<http::string_body> resp;
http::response_v1<http::string_body> 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)
mkdir -p ../bin/doc/xml
doxygen beast.dox
doxygen source.dox
cd ../bin/doc/xml
xsltproc combine.xslt index.xml > all.xml
cd ../../../doc

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

@@ -106,8 +106,8 @@ int main()
// Normal boost::asio setup
std::string const host = "boost.org";
boost::asio::io_service ios;
boost::asio::ip::tcp::resolver r(ios);
boost::asio::ip::tcp::socket sock(ios);
boost::asio::ip::tcp::resolver r{ios};
boost::asio::ip::tcp::socket sock{ios};
boost::asio::connect(sock,
r.resolve(boost::asio::ip::tcp::resolver::query{host, "http"}));
@@ -142,13 +142,13 @@ int main()
// Normal boost::asio setup
std::string const host = "echo.websocket.org";
boost::asio::io_service ios;
boost::asio::ip::tcp::resolver r(ios);
boost::asio::ip::tcp::socket sock(ios);
boost::asio::ip::tcp::resolver r{ios};
boost::asio::ip::tcp::socket sock{ios};
boost::asio::connect(sock,
r.resolve(boost::asio::ip::tcp::resolver::query{host, "80"}));
// 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.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
std::string const host = "boost.org";
boost::asio::io_service ios;
boost::asio::ip::tcp::resolver r(ios);
boost::asio::ip::tcp::socket sock(ios);
boost::asio::ip::tcp::resolver r{ios};
boost::asio::ip::tcp::socket sock{ios};
boost::asio::connect(sock,
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
std::string const host = "echo.websocket.org";
boost::asio::io_service ios;
boost::asio::ip::tcp::resolver r(ios);
boost::asio::ip::tcp::socket sock(ios);
boost::asio::ip::tcp::resolver r{ios};
boost::asio::ip::tcp::socket sock{ios};
boost::asio::connect(sock,
r.resolve(boost::asio::ip::tcp::resolver::query{host, "80"}));
// 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.write(boost::asio::buffer("Hello, world!"));