diff --git a/CHANGELOG.md b/CHANGELOG.md index 54e4fa72..5f3c1d04 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ Version 78: * Add span +* Documentation work HTTP: diff --git a/doc/1_intro.qbk b/doc/1_intro.qbk index e667f9b5..3927ebdd 100644 --- a/doc/1_intro.qbk +++ b/doc/1_intro.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section Introduction] +[section:intro Introduction] Beast is a C++ header-only library serving as a foundation for writing interoperable networking libraries by providing [*low-level HTTP/1, diff --git a/doc/2_examples.qbk b/doc/2_examples.qbk index f4a87325..88c5725b 100644 --- a/doc/2_examples.qbk +++ b/doc/2_examples.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section Quick Start] +[section:quickstart Quick Start] [block''''''] These complete programs are intended to quickly impress upon readers @@ -36,7 +36,7 @@ File: [repo_file example/websocket-client/websocket_client.cpp] -[section Examples] +[section:examples Examples] [block''''''] Source code and build scripts for these programs are located diff --git a/doc/3_0_core.qbk b/doc/3_0_core.qbk index 01a18d32..634c730e 100644 --- a/doc/3_0_core.qbk +++ b/doc/3_0_core.qbk @@ -5,14 +5,14 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section Using Networking] +[section:using_io Using I/O] -This library makes network primitives used by the implementation publicly +This library makes I/O primitives used by the implementation publicly available so users can take advantage of them in their own libraries. -These primitives include traits, buffers, buffer algorithms, and helpers -for implementing asynchronous operations compatible with __Asio__ and -described in __N3747__. This section lists these facilities by group, -with descriptions. +These primitives include traits, buffers, buffer algorithms, files, +and helpers for implementing asynchronous operations compatible with +__Asio__ and described in __N3747__. This section lists these facilities +by group, with descriptions. [important This documentation assumes familiarity with __Asio__. Sample @@ -26,7 +26,8 @@ with descriptions. [include 3_1_asio.qbk] [include 3_2_streams.qbk] [include 3_3_buffers.qbk] -[include 3_4_composed.qbk] -[include 3_5_detect_ssl.qbk] +[include 3_4_files.qbk] +[include 3_5_composed.qbk] +[include 3_6_detect_ssl.qbk] [endsect] diff --git a/doc/3_4_files.qbk b/doc/3_4_files.qbk new file mode 100644 index 00000000..020875f0 --- /dev/null +++ b/doc/3_4_files.qbk @@ -0,0 +1,38 @@ +[/ + 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:files Files] + +Often when implementing network algorithms such as servers, it is necessary +to interact with files on the system. Beast defines the __File__ concept +and several models to facilitate cross-platform interaction with the +underlying filesystem: + +[table File Types +[[Name][Description]] +[[ + [link beast.ref.beast__file_stdio `file_stdio`] +][ + This implementation of __File__ uses the C++ standard library + facilities obtained by including ``. +]] +[[ + [link beast.ref.beast__file_win32 `file_win32`] +][ + This implements a __File__ for the Win32 API. It provides low level + access to the native file handle when necessary. +]] +[[ + [link beast.ref.beast__file_posix `file_posix`] +][ + For POSIX systems, this class provides a suitable implementation + of __File__ which wraps the native file descriptor and provides + it if necessary. +]] +] + +[endsect] diff --git a/doc/3_4_composed.qbk b/doc/3_5_composed.qbk similarity index 100% rename from doc/3_4_composed.qbk rename to doc/3_5_composed.qbk diff --git a/doc/3_5_detect_ssl.qbk b/doc/3_6_detect_ssl.qbk similarity index 100% rename from doc/3_5_detect_ssl.qbk rename to doc/3_6_detect_ssl.qbk diff --git a/doc/quickref.xml b/doc/quickref.xml index 60ed05f9..0f3559a5 100644 --- a/doc/quickref.xml +++ b/doc/quickref.xml @@ -178,6 +178,7 @@ error_code error_condition file + file_mode diff --git a/include/beast/http/write.hpp b/include/beast/http/write.hpp index 3b1a3ec6..36fe0c00 100644 --- a/include/beast/http/write.hpp +++ b/include/beast/http/write.hpp @@ -44,11 +44,13 @@ namespace http { to the stream's `write_some` function. The amount of data actually transferred is controlled by the behavior - of the underlying stream, performing bounded work for each call. This - helps applications set reasonable timeouts. It also allows application-level - flow control to function correctly. For example when using a TCP/IP based + of the underlying stream, subject to the buffer size limit of the + serializer obtained or set through a call to @ref serializer::limit. + Setting a limit and performing bounded work helps applications set + reasonable timeouts. It also allows application-level flow control + to function correctly. For example when using a TCP/IP based stream. - + @param stream The stream to which the data is to be written. The type must support the @b SyncWriteStream concept. @@ -80,9 +82,11 @@ write_some(SyncWriteStream& stream, serializer< to the stream's `write_some` function. The amount of data actually transferred is controlled by the behavior - of the underlying stream, performing bounded work for each call. This - helps applications set reasonable timeouts. It also allows application-level - flow control to function correctly. For example when using a TCP/IP based + of the underlying stream, subject to the buffer size limit of the + serializer obtained or set through a call to @ref serializer::limit. + Setting a limit and performing bounded work helps applications set + reasonable timeouts. It also allows application-level flow control + to function correctly. For example when using a TCP/IP based stream. @param stream The stream to which the data is to be written. @@ -120,9 +124,11 @@ write_some(SyncWriteStream& stream, serializer< until this operation completes. The amount of data actually transferred is controlled by the behavior - of the underlying stream, performing bounded work for each call. This - helps applications set reasonable timeouts. It also allows application-level - flow control to function correctly. For example when using a TCP/IP based + of the underlying stream, subject to the buffer size limit of the + serializer obtained or set through a call to @ref serializer::limit. + Setting a limit and performing bounded work helps applications set + reasonable timeouts. It also allows application-level flow control + to function correctly. For example when using a TCP/IP based stream. @param stream The stream to which the data is to be written.