123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126 |
- [/
- / Copyright (c) 2003-2019 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 boost_asio.overview.windows.stream_handle Stream-Oriented HANDLEs]
- [link boost_asio.overview.windows.random_access_handle Random-Access HANDLEs]
- [link boost_asio.overview.windows.object_handle Object HANDLEs]
- [section:stream_handle Stream-Oriented HANDLEs]
- Boost.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 boost_asio.reference.read
- read()], [link boost_asio.reference.async_read async_read()], [link
- boost_asio.reference.write write()], [link boost_asio.reference.async_write
- async_write()], [link boost_asio.reference.read_until read_until()] or [link
- boost_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 boost_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 `BOOST_ASIO_HAS_WINDOWS_STREAM_HANDLE` to
- determine whether they are supported.
- [endsect]
- [/-----------------------------------------------------------------------------]
- [section:random_access_handle Random-Access HANDLEs]
- Boost.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 boost_asio.reference.read_at read_at()], [link
- boost_asio.reference.async_read_at async_read_at()], [link boost_asio.reference.write_at
- write_at()] and [link boost_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 boost_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
- `BOOST_ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE` to determine whether they are
- supported.
- [endsect]
- [/-----------------------------------------------------------------------------]
- [section:object_handle Object HANDLEs]
- Boost.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 boost_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 `BOOST_ASIO_HAS_WINDOWS_OBJECT_HANDLE` to
- determine whether they are supported.
- [endsect]
- [endsect]
|