1[/ 2 / Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) 3 / 4 / Distributed under the Boost Software License, Version 1.0. (See accompanying 5 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 /] 7 8[section:windows Windows-Specific Functionality] 9 10[link boost_asio.overview.windows.stream_handle Stream-Oriented HANDLEs] 11 12[link boost_asio.overview.windows.random_access_handle Random-Access HANDLEs] 13 14[link boost_asio.overview.windows.object_handle Object HANDLEs] 15 16[section:stream_handle Stream-Oriented HANDLEs] 17 18Boost.Asio contains classes to allow asynchronous read and write operations to be 19performed on Windows `HANDLE`s, such as named pipes. 20 21For example, to perform asynchronous operations on a named pipe, the following 22object may be created: 23 24 HANDLE handle = ::CreateFile(...); 25 windows::stream_handle pipe(my_io_context, handle); 26 27These are then used as synchronous or asynchronous read and write streams. This 28means the objects can be used with any of the [link boost_asio.reference.read 29read()], [link boost_asio.reference.async_read async_read()], [link 30boost_asio.reference.write write()], [link boost_asio.reference.async_write 31async_write()], [link boost_asio.reference.read_until read_until()] or [link 32boost_asio.reference.async_read_until async_read_until()] free functions. 33 34The kernel object referred to by the `HANDLE` must support use with I/O 35completion ports (which means that named pipes are supported, but anonymous 36pipes and console streams are not). 37 38[heading See Also] 39 40[link boost_asio.reference.windows__stream_handle windows::stream_handle]. 41 42[heading Notes] 43 44Windows stream `HANDLE`s are only available at compile time when targeting 45Windows and only when the I/O completion port backend is used (which is the 46default). A program may test for the macro `BOOST_ASIO_HAS_WINDOWS_STREAM_HANDLE` to 47determine whether they are supported. 48 49[endsect] 50 51[/-----------------------------------------------------------------------------] 52 53[section:random_access_handle Random-Access HANDLEs] 54 55Boost.Asio provides Windows-specific classes that permit asynchronous read and write 56operations to be performed on HANDLEs that refer to regular files. 57 58For example, to perform asynchronous operations on a file the following object 59may be created: 60 61 HANDLE handle = ::CreateFile(...); 62 windows::random_access_handle file(my_io_context, handle); 63 64Data may be read from or written to the handle using one of the 65`read_some_at()`, `async_read_some_at()`, `write_some_at()` or 66`async_write_some_at()` member functions. However, like the equivalent 67functions (`read_some()`, etc.) on streams, these functions are only required 68to transfer one or more bytes in a single operation. Therefore free functions 69called [link boost_asio.reference.read_at read_at()], [link 70boost_asio.reference.async_read_at async_read_at()], [link boost_asio.reference.write_at 71write_at()] and [link boost_asio.reference.async_write_at async_write_at()] have been 72created to repeatedly call the corresponding [^[**]_some_at()] function until 73all data has been transferred. 74 75[heading See Also] 76 77[link boost_asio.reference.windows__random_access_handle windows::random_access_handle]. 78 79[heading Notes] 80 81Windows random-access `HANDLE`s are only available at compile time when 82targeting Windows and only when the I/O completion port backend is used (which 83is the default). A program may test for the macro 84`BOOST_ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE` to determine whether they are 85supported. 86 87[endsect] 88 89[/-----------------------------------------------------------------------------] 90 91[section:object_handle Object HANDLEs] 92 93Boost.Asio provides Windows-specific classes that permit asynchronous wait operations 94to be performed on HANDLEs to kernel objects of the following types: 95 96* Change notification 97* Console input 98* Event 99* Memory resource notification 100* Process 101* Semaphore 102* Thread 103* Waitable timer 104 105For example, to perform asynchronous operations on an event, the following 106object may be created: 107 108 HANDLE handle = ::CreateEvent(...); 109 windows::object_handle file(my_io_context, handle); 110 111The `wait()` and `async_wait()` member functions may then be used to wait until 112the kernel object is signalled. 113 114[heading See Also] 115 116[link boost_asio.reference.windows__object_handle windows::object_handle]. 117 118[heading Notes] 119 120Windows object `HANDLE`s are only available at compile time when targeting 121Windows. Programs may test for the macro `BOOST_ASIO_HAS_WINDOWS_OBJECT_HANDLE` to 122determine whether they are supported. 123 124[endsect] 125 126[endsect] 127