summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/asio/src/doc/overview/windows.qbk
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/asio/src/doc/overview/windows.qbk')
-rw-r--r--3rdparty/asio/src/doc/overview/windows.qbk126
1 files changed, 126 insertions, 0 deletions
diff --git a/3rdparty/asio/src/doc/overview/windows.qbk b/3rdparty/asio/src/doc/overview/windows.qbk
new file mode 100644
index 00000000000..da49a0b409e
--- /dev/null
+++ b/3rdparty/asio/src/doc/overview/windows.qbk
@@ -0,0 +1,126 @@
+[/
+ / Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff 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:windows Windows-Specific Functionality]
+
+[link asio.overview.windows.stream_handle Stream-Oriented HANDLEs]
+
+[link asio.overview.windows.random_access_handle Random-Access HANDLEs]
+
+[link asio.overview.windows.object_handle Object HANDLEs]
+
+[section:stream_handle Stream-Oriented HANDLEs]
+
+Asio contains classes to allow asynchronous read and write operations to be
+performed on Windows `HANDLE`s, such as named pipes.
+
+For example, to perform asynchronous operations on a named pipe, the following
+object may be created:
+
+ HANDLE handle = ::CreateFile(...);
+ windows::stream_handle pipe(my_io_context, handle);
+
+These are then used as synchronous or asynchronous read and write streams. This
+means the objects can be used with any of the [link asio.reference.read
+read()], [link asio.reference.async_read async_read()], [link
+asio.reference.write write()], [link asio.reference.async_write
+async_write()], [link asio.reference.read_until read_until()] or [link
+asio.reference.async_read_until async_read_until()] free functions.
+
+The kernel object referred to by the `HANDLE` must support use with I/O
+completion ports (which means that named pipes are supported, but anonymous
+pipes and console streams are not).
+
+[heading See Also]
+
+[link asio.reference.windows__stream_handle windows::stream_handle].
+
+[heading Notes]
+
+Windows stream `HANDLE`s are only available at compile time when targeting
+Windows and only when the I/O completion port backend is used (which is the
+default). A program may test for the macro `ASIO_HAS_WINDOWS_STREAM_HANDLE` to
+determine whether they are supported.
+
+[endsect]
+
+[/-----------------------------------------------------------------------------]
+
+[section:random_access_handle Random-Access HANDLEs]
+
+Asio provides Windows-specific classes that permit asynchronous read and write
+operations to be performed on HANDLEs that refer to regular files.
+
+For example, to perform asynchronous operations on a file the following object
+may be created:
+
+ HANDLE handle = ::CreateFile(...);
+ windows::random_access_handle file(my_io_context, handle);
+
+Data may be read from or written to the handle using one of the
+`read_some_at()`, `async_read_some_at()`, `write_some_at()` or
+`async_write_some_at()` member functions. However, like the equivalent
+functions (`read_some()`, etc.) on streams, these functions are only required
+to transfer one or more bytes in a single operation. Therefore free functions
+called [link asio.reference.read_at read_at()], [link
+asio.reference.async_read_at async_read_at()], [link asio.reference.write_at
+write_at()] and [link asio.reference.async_write_at async_write_at()] have been
+created to repeatedly call the corresponding [^[**]_some_at()] function until
+all data has been transferred.
+
+[heading See Also]
+
+[link asio.reference.windows__random_access_handle windows::random_access_handle].
+
+[heading Notes]
+
+Windows random-access `HANDLE`s are only available at compile time when
+targeting Windows and only when the I/O completion port backend is used (which
+is the default). A program may test for the macro
+`ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE` to determine whether they are
+supported.
+
+[endsect]
+
+[/-----------------------------------------------------------------------------]
+
+[section:object_handle Object HANDLEs]
+
+Asio provides Windows-specific classes that permit asynchronous wait operations
+to be performed on HANDLEs to kernel objects of the following types:
+
+* Change notification
+* Console input
+* Event
+* Memory resource notification
+* Process
+* Semaphore
+* Thread
+* Waitable timer
+
+For example, to perform asynchronous operations on an event, the following
+object may be created:
+
+ HANDLE handle = ::CreateEvent(...);
+ windows::object_handle file(my_io_context, handle);
+
+The `wait()` and `async_wait()` member functions may then be used to wait until
+the kernel object is signalled.
+
+[heading See Also]
+
+[link asio.reference.windows__object_handle windows::object_handle].
+
+[heading Notes]
+
+Windows object `HANDLE`s are only available at compile time when targeting
+Windows. Programs may test for the macro `ASIO_HAS_WINDOWS_OBJECT_HANDLE` to
+determine whether they are supported.
+
+[endsect]
+
+[endsect]