Documentation work

doc/2_examples.qbk

@@ -0,0 +1,146 @@
+[/
+    Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section:example Examples]
+
+These usage examples are intended to quickly impress upon readers the
+flavor of the library. They are complete programs which may be built
+and run. Source code and build scripts for these programs may be found
+in the examples directory.
+
+[heading HTTP GET]
+
+Use HTTP to request the root page from a website and print the response:
+
+```
+#include <beast/core.hpp>
+#include <beast/http.hpp>
+#include <boost/asio.hpp>
+#include <boost/lexical_cast.hpp>
+#include <iostream>
+#include <string>
+
+int main()
+{
+    // Normal boost::asio setup
+    std::string const host = "www.example.com";
+    boost::asio::io_service 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"}));
+
+    // Send HTTP request using beast
+    beast::http::request<beast::http::string_body> req;
+    req.method(beast::http::verb::get);
+    req.target("/");
+    req.version = 11;
+    req.fields.replace("Host", host + ":" +
+        boost::lexical_cast<std::string>(sock.remote_endpoint().port()));
+    req.fields.replace("User-Agent", "Beast");
+    beast::http::prepare(req);
+    beast::http::write(sock, req);
+
+    // Receive and print HTTP response using beast
+    beast::flat_buffer b;
+    beast::http::response<beast::http::dynamic_body> res;
+    beast::http::read(sock, b, res);
+    std::cout << res << std::endl;
+}
+```
+[heading WebSocket]
+
+Establish a WebSocket connection, send a message and receive the reply:
+```
+#include <beast/core.hpp>
+#include <beast/websocket.hpp>
+#include <boost/asio.hpp>
+#include <iostream>
+#include <string>
+
+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::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};
+    ws.handshake(host, "/");
+    ws.write(boost::asio::buffer(std::string("Hello, world!")));
+
+    // Receive WebSocket message, print and close using beast
+    beast::multi_buffer b;
+    beast::websocket::opcode op;
+    ws.read(op, b);
+    ws.close(beast::websocket::close_code::normal);
+    std::cout << beast::buffers(b.data()) << "\n";
+}
+```
+
+[heading WebSocket Echo Server]
+
+This example demonstrates both synchronous and asynchronous
+WebSocket server implementations.
+
+* [@examples/websocket_async_echo_server.hpp]
+* [@examples/websocket_sync_echo_server.hpp]
+* [@examples/websocket_echo.cpp]
+
+[heading Secure WebSocket]
+
+Establish a WebSocket connection over an encrypted TLS connection,
+send a message and receive the reply. Requires OpenSSL to build.
+
+* [@examples/websocket_ssl_example.cpp]
+
+[heading HTTPS GET]
+
+This example demonstrates sending and receiving HTTP messages
+over a TLS connection. Requires OpenSSL to build.
+
+* [@examples/http_ssl_example.cpp]
+
+[heading HTTP Crawl]
+
+This example retrieves the page at each of the most popular domains
+as measured by Alexa.
+
+* [@examples/http_crawl.cpp]
+
+[heading HTTP Server]
+
+This example demonstrates both synchronous and asynchronous server
+implementations. It also provides an example of implementing a [*Body]
+type, in `file_body`.
+
+* [@examples/file_body.hpp]
+* [@examples/http_async_server.hpp]
+* [@examples/http_sync_server.hpp]
+* [@examples/http_server.cpp]
+
+[heading Composed Operations]
+
+This program shows how to use Beast's core foundations to build a
+composable asynchronous initiation function with associated composed
+operation implementation. This is a complete, runnable version of
+the example described in the Core Foundations document section.
+
+* [@examples/echo_op.cpp]
+
+[heading Listings]
+
+These are stand-alone listings of the HTTP and WebSocket examples.
+
+* [@examples/http_example.cpp]
+* [@examples/websocket_example.cpp]
+
+[endsect]