summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/asio/src/doc/overview/windows.qbk
blob: da49a0b409e5d9ecd7473a77e996f558f8f5b252 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
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]