Attempt to read a certain amount of data from a stream before returning.
template< typename SyncReadStream, typename MutableBufferSequence, typename CompletionCondition> std::size_t read( SyncReadStream & s, const MutableBufferSequence & buffers, CompletionCondition completion_condition);
This function is used to read a certain number of bytes of data from a stream. The call will block until one of the following conditions is true:
- The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes.
- The completion_condition function object returns true.
This operation is implemented in terms of one or more calls to the stream's read_some function.
Parameters
- s
The stream from which the data is to be read. The type must support the SyncReadStream concept.
- buffers
One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the stream.
- completion_condition
-
The function object to be called to determine whether the read operation is complete. The signature of the function object must be:
bool completion_condition( const boost::system::error_code& error, // Result of latest read_some // operation. std::size_t bytes_transferred // Number of bytes transferred // so far. );
A return value of true indicates that the read operation is complete. False indicates that further calls to the stream's read_some function are required.
Return Value
The number of bytes transferred.
Exceptions
- boost::system::system_error
Thrown on failure.
Example
To read into a single data buffer use the buffer function as follows:
boost::asio::read(s, boost::asio::buffer(data, size), boost::asio::transfer_at_least(32));
See the buffer documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.