[ceph.git] / ceph / src / boost / libs / asio / doc / overview / windows.qbk

[/
 / 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 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_service, 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],
[link boost_asio.reference.windows__basic_stream_handle windows::basic_stream_handle],
[link boost_asio.reference.windows__stream_handle_service windows::stream_handle_service].

[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_service, 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],
[link boost_asio.reference.windows__basic_random_access_handle windows::basic_random_access_handle],
[link boost_asio.reference.windows__random_access_handle_service windows::random_access_handle_service].

[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_service, 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],
[link boost_asio.reference.windows__basic_object_handle windows::basic_object_handle],
[link boost_asio.reference.windows__object_handle_service windows::object_handle_service].

[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]
Commit	Line	Data
7c673cae FG	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]