ocrm.bsky.social
the game where you go into mines and start crafting! but for consoles (forked directly from smartcmd's github)
1//
2// read.hpp
3// ~~~~~~~~
4//
5// Copyright (c) 2003-2012 Christopher M. Kohlhoff (chris at kohlhoff dot com)
6//
7// Distributed under the Boost Software License, Version 1.0. (See accompanying
8// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
9//
10
11#ifndef BOOST_ASIO_READ_HPP
12#define BOOST_ASIO_READ_HPP
13
14#if defined(_MSC_VER) && (_MSC_VER >= 1200)
15# pragma once
16#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
17
18#include <boost/asio/detail/config.hpp>
19#include <cstddef>
20#include <boost/asio/basic_streambuf_fwd.hpp>
21#include <boost/asio/error.hpp>
22
23#include <boost/asio/detail/push_options.hpp>
24
25namespace boost {
26namespace asio {
27
28/**
29 * @defgroup read boost::asio::read
30 *
31 * @brief Attempt to read a certain amount of data from a stream before
32 * returning.
33 */
34/*@{*/
35
36/// Attempt to read a certain amount of data from a stream before returning.
37/**
38 * This function is used to read a certain number of bytes of data from a
39 * stream. The call will block until one of the following conditions is true:
40 *
41 * @li The supplied buffers are full. That is, the bytes transferred is equal to
42 * the sum of the buffer sizes.
43 *
44 * @li An error occurred.
45 *
46 * This operation is implemented in terms of zero or more calls to the stream's
47 * read_some function.
48 *
49 * @param s The stream from which the data is to be read. The type must support
50 * the SyncReadStream concept.
51 *
52 * @param buffers One or more buffers into which the data will be read. The sum
53 * of the buffer sizes indicates the maximum number of bytes to read from the
54 * stream.
55 *
56 * @returns The number of bytes transferred.
57 *
58 * @throws boost::system::system_error Thrown on failure.
59 *
60 * @par Example
61 * To read into a single data buffer use the @ref buffer function as follows:
62 * @code boost::asio::read(s, boost::asio::buffer(data, size)); @endcode
63 * See the @ref buffer documentation for information on reading into multiple
64 * buffers in one go, and how to use it with arrays, boost::array or
65 * std::vector.
66 *
67 * @note This overload is equivalent to calling:
68 * @code boost::asio::read(
69 * s, buffers,
70 * boost::asio::transfer_all()); @endcode
71 */
72template <typename SyncReadStream, typename MutableBufferSequence>
73std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers);
74
75/// Attempt to read a certain amount of data from a stream before returning.
76/**
77 * This function is used to read a certain number of bytes of data from a
78 * stream. The call will block until one of the following conditions is true:
79 *
80 * @li The supplied buffers are full. That is, the bytes transferred is equal to
81 * the sum of the buffer sizes.
82 *
83 * @li An error occurred.
84 *
85 * This operation is implemented in terms of zero or more calls to the stream's
86 * read_some function.
87 *
88 * @param s The stream from which the data is to be read. The type must support
89 * the SyncReadStream concept.
90 *
91 * @param buffers One or more buffers into which the data will be read. The sum
92 * of the buffer sizes indicates the maximum number of bytes to read from the
93 * stream.
94 *
95 * @param ec Set to indicate what error occurred, if any.
96 *
97 * @returns The number of bytes transferred.
98 *
99 * @par Example
100 * To read into a single data buffer use the @ref buffer function as follows:
101 * @code boost::asio::read(s, boost::asio::buffer(data, size), ec); @endcode
102 * See the @ref buffer documentation for information on reading into multiple
103 * buffers in one go, and how to use it with arrays, boost::array or
104 * std::vector.
105 *
106 * @note This overload is equivalent to calling:
107 * @code boost::asio::read(
108 * s, buffers,
109 * boost::asio::transfer_all(), ec); @endcode
110 */
111template <typename SyncReadStream, typename MutableBufferSequence>
112std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
113 boost::system::error_code& ec);
114
115/// Attempt to read a certain amount of data from a stream before returning.
116/**
117 * This function is used to read a certain number of bytes of data from a
118 * stream. The call will block until one of the following conditions is true:
119 *
120 * @li The supplied buffers are full. That is, the bytes transferred is equal to
121 * the sum of the buffer sizes.
122 *
123 * @li The completion_condition function object returns 0.
124 *
125 * This operation is implemented in terms of zero or more calls to the stream's
126 * read_some function.
127 *
128 * @param s The stream from which the data is to be read. The type must support
129 * the SyncReadStream concept.
130 *
131 * @param buffers One or more buffers into which the data will be read. The sum
132 * of the buffer sizes indicates the maximum number of bytes to read from the
133 * stream.
134 *
135 * @param completion_condition The function object to be called to determine
136 * whether the read operation is complete. The signature of the function object
137 * must be:
138 * @code std::size_t completion_condition(
139 * // Result of latest read_some operation.
140 * const boost::system::error_code& error,
141 *
142 * // Number of bytes transferred so far.
143 * std::size_t bytes_transferred
144 * ); @endcode
145 * A return value of 0 indicates that the read operation is complete. A non-zero
146 * return value indicates the maximum number of bytes to be read on the next
147 * call to the stream's read_some function.
148 *
149 * @returns The number of bytes transferred.
150 *
151 * @throws boost::system::system_error Thrown on failure.
152 *
153 * @par Example
154 * To read into a single data buffer use the @ref buffer function as follows:
155 * @code boost::asio::read(s, boost::asio::buffer(data, size),
156 * boost::asio::transfer_at_least(32)); @endcode
157 * See the @ref buffer documentation for information on reading into multiple
158 * buffers in one go, and how to use it with arrays, boost::array or
159 * std::vector.
160 */
161template <typename SyncReadStream, typename MutableBufferSequence,
162 typename CompletionCondition>
163std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
164 CompletionCondition completion_condition);
165
166/// Attempt to read a certain amount of data from a stream before returning.
167/**
168 * This function is used to read a certain number of bytes of data from a
169 * stream. The call will block until one of the following conditions is true:
170 *
171 * @li The supplied buffers are full. That is, the bytes transferred is equal to
172 * the sum of the buffer sizes.
173 *
174 * @li The completion_condition function object returns 0.
175 *
176 * This operation is implemented in terms of zero or more calls to the stream's
177 * read_some function.
178 *
179 * @param s The stream from which the data is to be read. The type must support
180 * the SyncReadStream concept.
181 *
182 * @param buffers One or more buffers into which the data will be read. The sum
183 * of the buffer sizes indicates the maximum number of bytes to read from the
184 * stream.
185 *
186 * @param completion_condition The function object to be called to determine
187 * whether the read operation is complete. The signature of the function object
188 * must be:
189 * @code std::size_t completion_condition(
190 * // Result of latest read_some operation.
191 * const boost::system::error_code& error,
192 *
193 * // Number of bytes transferred so far.
194 * std::size_t bytes_transferred
195 * ); @endcode
196 * A return value of 0 indicates that the read operation is complete. A non-zero
197 * return value indicates the maximum number of bytes to be read on the next
198 * call to the stream's read_some function.
199 *
200 * @param ec Set to indicate what error occurred, if any.
201 *
202 * @returns The number of bytes read. If an error occurs, returns the total
203 * number of bytes successfully transferred prior to the error.
204 */
205template <typename SyncReadStream, typename MutableBufferSequence,
206 typename CompletionCondition>
207std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
208 CompletionCondition completion_condition, boost::system::error_code& ec);
209
210#if !defined(BOOST_NO_IOSTREAM)
211
212/// Attempt to read a certain amount of data from a stream before returning.
213/**
214 * This function is used to read a certain number of bytes of data from a
215 * stream. The call will block until one of the following conditions is true:
216 *
217 * @li The supplied buffer is full (that is, it has reached maximum size).
218 *
219 * @li An error occurred.
220 *
221 * This operation is implemented in terms of zero or more calls to the stream's
222 * read_some function.
223 *
224 * @param s The stream from which the data is to be read. The type must support
225 * the SyncReadStream concept.
226 *
227 * @param b The basic_streambuf object into which the data will be read.
228 *
229 * @returns The number of bytes transferred.
230 *
231 * @throws boost::system::system_error Thrown on failure.
232 *
233 * @note This overload is equivalent to calling:
234 * @code boost::asio::read(
235 * s, b,
236 * boost::asio::transfer_all()); @endcode
237 */
238template <typename SyncReadStream, typename Allocator>
239std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b);
240
241/// Attempt to read a certain amount of data from a stream before returning.
242/**
243 * This function is used to read a certain number of bytes of data from a
244 * stream. The call will block until one of the following conditions is true:
245 *
246 * @li The supplied buffer is full (that is, it has reached maximum size).
247 *
248 * @li An error occurred.
249 *
250 * This operation is implemented in terms of zero or more calls to the stream's
251 * read_some function.
252 *
253 * @param s The stream from which the data is to be read. The type must support
254 * the SyncReadStream concept.
255 *
256 * @param b The basic_streambuf object into which the data will be read.
257 *
258 * @param ec Set to indicate what error occurred, if any.
259 *
260 * @returns The number of bytes transferred.
261 *
262 * @note This overload is equivalent to calling:
263 * @code boost::asio::read(
264 * s, b,
265 * boost::asio::transfer_all(), ec); @endcode
266 */
267template <typename SyncReadStream, typename Allocator>
268std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
269 boost::system::error_code& ec);
270
271/// Attempt to read a certain amount of data from a stream before returning.
272/**
273 * This function is used to read a certain number of bytes of data from a
274 * stream. The call will block until one of the following conditions is true:
275 *
276 * @li The supplied buffer is full (that is, it has reached maximum size).
277 *
278 * @li The completion_condition function object returns 0.
279 *
280 * This operation is implemented in terms of zero or more calls to the stream's
281 * read_some function.
282 *
283 * @param s The stream from which the data is to be read. The type must support
284 * the SyncReadStream concept.
285 *
286 * @param b The basic_streambuf object into which the data will be read.
287 *
288 * @param completion_condition The function object to be called to determine
289 * whether the read operation is complete. The signature of the function object
290 * must be:
291 * @code std::size_t completion_condition(
292 * // Result of latest read_some operation.
293 * const boost::system::error_code& error,
294 *
295 * // Number of bytes transferred so far.
296 * std::size_t bytes_transferred
297 * ); @endcode
298 * A return value of 0 indicates that the read operation is complete. A non-zero
299 * return value indicates the maximum number of bytes to be read on the next
300 * call to the stream's read_some function.
301 *
302 * @returns The number of bytes transferred.
303 *
304 * @throws boost::system::system_error Thrown on failure.
305 */
306template <typename SyncReadStream, typename Allocator,
307 typename CompletionCondition>
308std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
309 CompletionCondition completion_condition);
310
311/// Attempt to read a certain amount of data from a stream before returning.
312/**
313 * This function is used to read a certain number of bytes of data from a
314 * stream. The call will block until one of the following conditions is true:
315 *
316 * @li The supplied buffer is full (that is, it has reached maximum size).
317 *
318 * @li The completion_condition function object returns 0.
319 *
320 * This operation is implemented in terms of zero or more calls to the stream's
321 * read_some function.
322 *
323 * @param s The stream from which the data is to be read. The type must support
324 * the SyncReadStream concept.
325 *
326 * @param b The basic_streambuf object into which the data will be read.
327 *
328 * @param completion_condition The function object to be called to determine
329 * whether the read operation is complete. The signature of the function object
330 * must be:
331 * @code std::size_t completion_condition(
332 * // Result of latest read_some operation.
333 * const boost::system::error_code& error,
334 *
335 * // Number of bytes transferred so far.
336 * std::size_t bytes_transferred
337 * ); @endcode
338 * A return value of 0 indicates that the read operation is complete. A non-zero
339 * return value indicates the maximum number of bytes to be read on the next
340 * call to the stream's read_some function.
341 *
342 * @param ec Set to indicate what error occurred, if any.
343 *
344 * @returns The number of bytes read. If an error occurs, returns the total
345 * number of bytes successfully transferred prior to the error.
346 */
347template <typename SyncReadStream, typename Allocator,
348 typename CompletionCondition>
349std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
350 CompletionCondition completion_condition, boost::system::error_code& ec);
351
352#endif // !defined(BOOST_NO_IOSTREAM)
353
354/*@}*/
355/**
356 * @defgroup async_read boost::asio::async_read
357 *
358 * @brief Start an asynchronous operation to read a certain amount of data from
359 * a stream.
360 */
361/*@{*/
362
363/// Start an asynchronous operation to read a certain amount of data from a
364/// stream.
365/**
366 * This function is used to asynchronously read a certain number of bytes of
367 * data from a stream. The function call always returns immediately. The
368 * asynchronous operation will continue until one of the following conditions is
369 * true:
370 *
371 * @li The supplied buffers are full. That is, the bytes transferred is equal to
372 * the sum of the buffer sizes.
373 *
374 * @li An error occurred.
375 *
376 * This operation is implemented in terms of zero or more calls to the stream's
377 * async_read_some function, and is known as a <em>composed operation</em>. The
378 * program must ensure that the stream performs no other read operations (such
379 * as async_read, the stream's async_read_some function, or any other composed
380 * operations that perform reads) until this operation completes.
381 *
382 * @param s The stream from which the data is to be read. The type must support
383 * the AsyncReadStream concept.
384 *
385 * @param buffers One or more buffers into which the data will be read. The sum
386 * of the buffer sizes indicates the maximum number of bytes to read from the
387 * stream. Although the buffers object may be copied as necessary, ownership of
388 * the underlying memory blocks is retained by the caller, which must guarantee
389 * that they remain valid until the handler is called.
390 *
391 * @param handler The handler to be called when the read operation completes.
392 * Copies will be made of the handler as required. The function signature of the
393 * handler must be:
394 * @code void handler(
395 * const boost::system::error_code& error, // Result of operation.
396 *
397 * std::size_t bytes_transferred // Number of bytes copied into the
398 * // buffers. If an error occurred,
399 * // this will be the number of
400 * // bytes successfully transferred
401 * // prior to the error.
402 * ); @endcode
403 * Regardless of whether the asynchronous operation completes immediately or
404 * not, the handler will not be invoked from within this function. Invocation of
405 * the handler will be performed in a manner equivalent to using
406 * boost::asio::io_service::post().
407 *
408 * @par Example
409 * To read into a single data buffer use the @ref buffer function as follows:
410 * @code
411 * boost::asio::async_read(s, boost::asio::buffer(data, size), handler);
412 * @endcode
413 * See the @ref buffer documentation for information on reading into multiple
414 * buffers in one go, and how to use it with arrays, boost::array or
415 * std::vector.
416 *
417 * @note This overload is equivalent to calling:
418 * @code boost::asio::async_read(
419 * s, buffers,
420 * boost::asio::transfer_all(),
421 * handler); @endcode
422 */
423template <typename AsyncReadStream, typename MutableBufferSequence,
424 typename ReadHandler>
425void async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
426 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
427
428/// Start an asynchronous operation to read a certain amount of data from a
429/// stream.
430/**
431 * This function is used to asynchronously read a certain number of bytes of
432 * data from a stream. The function call always returns immediately. The
433 * asynchronous operation will continue until one of the following conditions is
434 * true:
435 *
436 * @li The supplied buffers are full. That is, the bytes transferred is equal to
437 * the sum of the buffer sizes.
438 *
439 * @li The completion_condition function object returns 0.
440 *
441 * @param s The stream from which the data is to be read. The type must support
442 * the AsyncReadStream concept.
443 *
444 * @param buffers One or more buffers into which the data will be read. The sum
445 * of the buffer sizes indicates the maximum number of bytes to read from the
446 * stream. Although the buffers object may be copied as necessary, ownership of
447 * the underlying memory blocks is retained by the caller, which must guarantee
448 * that they remain valid until the handler is called.
449 *
450 * @param completion_condition The function object to be called to determine
451 * whether the read operation is complete. The signature of the function object
452 * must be:
453 * @code std::size_t completion_condition(
454 * // Result of latest async_read_some operation.
455 * const boost::system::error_code& error,
456 *
457 * // Number of bytes transferred so far.
458 * std::size_t bytes_transferred
459 * ); @endcode
460 * A return value of 0 indicates that the read operation is complete. A non-zero
461 * return value indicates the maximum number of bytes to be read on the next
462 * call to the stream's async_read_some function.
463 *
464 * @param handler The handler to be called when the read operation completes.
465 * Copies will be made of the handler as required. The function signature of the
466 * handler must be:
467 * @code void handler(
468 * const boost::system::error_code& error, // Result of operation.
469 *
470 * std::size_t bytes_transferred // Number of bytes copied into the
471 * // buffers. If an error occurred,
472 * // this will be the number of
473 * // bytes successfully transferred
474 * // prior to the error.
475 * ); @endcode
476 * Regardless of whether the asynchronous operation completes immediately or
477 * not, the handler will not be invoked from within this function. Invocation of
478 * the handler will be performed in a manner equivalent to using
479 * boost::asio::io_service::post().
480 *
481 * @par Example
482 * To read into a single data buffer use the @ref buffer function as follows:
483 * @code boost::asio::async_read(s,
484 * boost::asio::buffer(data, size),
485 * boost::asio::transfer_at_least(32),
486 * handler); @endcode
487 * See the @ref buffer documentation for information on reading into multiple
488 * buffers in one go, and how to use it with arrays, boost::array or
489 * std::vector.
490 */
491template <typename AsyncReadStream, typename MutableBufferSequence,
492 typename CompletionCondition, typename ReadHandler>
493void async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
494 CompletionCondition completion_condition,
495 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
496
497#if !defined(BOOST_NO_IOSTREAM)
498
499/// Start an asynchronous operation to read a certain amount of data from a
500/// stream.
501/**
502 * This function is used to asynchronously read a certain number of bytes of
503 * data from a stream. The function call always returns immediately. The
504 * asynchronous operation will continue until one of the following conditions is
505 * true:
506 *
507 * @li The supplied buffer is full (that is, it has reached maximum size).
508 *
509 * @li An error occurred.
510 *
511 * This operation is implemented in terms of zero or more calls to the stream's
512 * async_read_some function, and is known as a <em>composed operation</em>. The
513 * program must ensure that the stream performs no other read operations (such
514 * as async_read, the stream's async_read_some function, or any other composed
515 * operations that perform reads) until this operation completes.
516 *
517 * @param s The stream from which the data is to be read. The type must support
518 * the AsyncReadStream concept.
519 *
520 * @param b A basic_streambuf object into which the data will be read. Ownership
521 * of the streambuf is retained by the caller, which must guarantee that it
522 * remains valid until the handler is called.
523 *
524 * @param handler The handler to be called when the read operation completes.
525 * Copies will be made of the handler as required. The function signature of the
526 * handler must be:
527 * @code void handler(
528 * const boost::system::error_code& error, // Result of operation.
529 *
530 * std::size_t bytes_transferred // Number of bytes copied into the
531 * // buffers. If an error occurred,
532 * // this will be the number of
533 * // bytes successfully transferred
534 * // prior to the error.
535 * ); @endcode
536 * Regardless of whether the asynchronous operation completes immediately or
537 * not, the handler will not be invoked from within this function. Invocation of
538 * the handler will be performed in a manner equivalent to using
539 * boost::asio::io_service::post().
540 *
541 * @note This overload is equivalent to calling:
542 * @code boost::asio::async_read(
543 * s, b,
544 * boost::asio::transfer_all(),
545 * handler); @endcode
546 */
547template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
548void async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
549 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
550
551/// Start an asynchronous operation to read a certain amount of data from a
552/// stream.
553/**
554 * This function is used to asynchronously read a certain number of bytes of
555 * data from a stream. The function call always returns immediately. The
556 * asynchronous operation will continue until one of the following conditions is
557 * true:
558 *
559 * @li The supplied buffer is full (that is, it has reached maximum size).
560 *
561 * @li The completion_condition function object returns 0.
562 *
563 * This operation is implemented in terms of zero or more calls to the stream's
564 * async_read_some function, and is known as a <em>composed operation</em>. The
565 * program must ensure that the stream performs no other read operations (such
566 * as async_read, the stream's async_read_some function, or any other composed
567 * operations that perform reads) until this operation completes.
568 *
569 * @param s The stream from which the data is to be read. The type must support
570 * the AsyncReadStream concept.
571 *
572 * @param b A basic_streambuf object into which the data will be read. Ownership
573 * of the streambuf is retained by the caller, which must guarantee that it
574 * remains valid until the handler is called.
575 *
576 * @param completion_condition The function object to be called to determine
577 * whether the read operation is complete. The signature of the function object
578 * must be:
579 * @code std::size_t completion_condition(
580 * // Result of latest async_read_some operation.
581 * const boost::system::error_code& error,
582 *
583 * // Number of bytes transferred so far.
584 * std::size_t bytes_transferred
585 * ); @endcode
586 * A return value of 0 indicates that the read operation is complete. A non-zero
587 * return value indicates the maximum number of bytes to be read on the next
588 * call to the stream's async_read_some function.
589 *
590 * @param handler The handler to be called when the read operation completes.
591 * Copies will be made of the handler as required. The function signature of the
592 * handler must be:
593 * @code void handler(
594 * const boost::system::error_code& error, // Result of operation.
595 *
596 * std::size_t bytes_transferred // Number of bytes copied into the
597 * // buffers. If an error occurred,
598 * // this will be the number of
599 * // bytes successfully transferred
600 * // prior to the error.
601 * ); @endcode
602 * Regardless of whether the asynchronous operation completes immediately or
603 * not, the handler will not be invoked from within this function. Invocation of
604 * the handler will be performed in a manner equivalent to using
605 * boost::asio::io_service::post().
606 */
607template <typename AsyncReadStream, typename Allocator,
608 typename CompletionCondition, typename ReadHandler>
609void async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
610 CompletionCondition completion_condition,
611 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
612
613#endif // !defined(BOOST_NO_IOSTREAM)
614
615/*@}*/
616
617} // namespace asio
618} // namespace boost
619
620#include <boost/asio/detail/pop_options.hpp>
621
622#include <boost/asio/impl/read.hpp>
623
624#endif // BOOST_ASIO_READ_HPP