ceph/src/boost/libs/asio/doc/overview/windows.qbk

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