InputByteStreamRef::read

std::size_t read(void* pBuffer, std::size_t cbBuffer); /*1*/
 template <class ReadingPolicy>
/*см. ниже*/ read(void* pBuffer, std::size_t cbBuffer, ReadingPolicy); /*2*/

Реализует чтение заданного количества байт из потока InputByteStreamRef.

Параметры шаблона

ReadingPolicy

Вычисляемый дедукцией тип политики чтения, используемой перегрузкой 2. Тип должен определять статическую константу компиляции value, содержащую битовую маску идентификаторов компонент политики. Эти идентификаторы заданы перечислением reading_policy_flags и имеют следующие значения. Символическое имя Целочисленное значение Описание force_fill_buffer 1 Операции чтения из потоков InputByteStreamRef блокируют осуществляющий чтение поток выполнения до тех пор, пока поданный на вход операции буфер не будет заполнен полностью, или операция чтения не будет явно отменена. Если данная политика не задана, операции чтения завершаются, как только из потока удается считать хоть какое-то количество данных, или происходит явная отмена операции. Например, если в результате неполного чтения достигнут конец данных, и флаг force_fill_buffer сброшен, операции чтения вернут управление вызывающей чтение стороне. Если же флаг установлен, операции чтения будут пытаться читать данные до тех пор, пока выходной буфер не будет заполен полностью, или операция чтения не будет отменена. get_error_code 2 Операции чтения возвращают коды ошибок типа return_code_t вместо генерации исключений для типичных ошибок чтения. Существует также метафункция reading_policy, которая позволяет задать маску политик шаблонными параметрами, как указано в примере ниже.

Параметры

[out]	pBuffer	Указатель, который в случае успешного завершения функции принимает считанные данные. Объем считанных данных возвращается, прямо или опосредовано через пару, методами.
	cbBuffer	Размер буфера в байтах.

Возвращаемое значение:

Перегрузка 1 возвращает объем прочитанных данных. Тип значения, возвращаемого перегрузкой 2, зависит от политики ReadingPolicy. Если политикой не указан флаг reading_policy_flags::get_error_code, перегрузка 2 возвращает объем считанных данных аналогично перегрузке 1. Если флаг reading_policy_flags::get_error_code установлен, возвращается пара std::pair значений std::pair<return_code_t, std::size_t> - код завершения чтения в качестве первого элемента пары, и объем считанных байт - в качестве второго.

См. также

IInputByteStream::ReadArray
InputByteStreamRef::read_as
InputByteStreamRef::read_all_as

Если чтение блокирует вызывающий поток выполнения, и эта блокировка прерывается нормальным образом (например, когда поток осуществляет чтение из интернет канала, и другой поток вызывает метод IInternetConnectionEndPoint::CancelOperations над этим каналом, или по TCP каналу связи поступает сигнал FIN)), перегрузка 2, в зависимости от значения флага политики reading_policy_flags::get_error_code, возвращает код успешного завершения CHSVERROR_SUCCESS_CANCELLED (0x2417000f) или генерирует исключение Chusov::Exceptions::OperationCancelledException. Перегрузка 1 в таких случаях всегда генерирует это исключение.

Пусть is - объект класса InputByteStreamRef. Тогда вызов перегрузки 1

is.read(pBuf, cbBuf);

эквивалентен вызову перегрузки 2 следующим образом.

is.read(pBuf, cbBuf, reading_policy<>());

В отличие от метода read метод read_as по умолчанию использует политику reading_policy_flags::force_fill_buffer.

Пример: Чтение из потока с заполнением буфера полностью и с использованием сигнализации об ошибках чтения с помощью кода завершения.

#include <tuple>
#include <cstdint>
#include <camaas/istream.h>

std::uint32_t read_dword(CAMaaS::InputByteStreamRef is)
{
    std::uint32_t result;
    return_code_t err;
    std::tie(err, std::ignore) = is.read(&result, sizeof(result), reading_policy<
        reading_policy_flags::force_fill_buffer, reading_policy_flags::get_error_code>());
    if (ChsvFailed(err))
        return std::uint32_t(-1);
    return result;
}