eolib::data::EoReader Class Reference

A class for reading EO data from a sequence of bytes. More...

#include <eolib/data/eo_reader.hpp>

Public Member Functions
	EoReader (std::vector< std::uint8_t > data)
	Creates a reader over the specified data.
	EoReader (std::string_view data)
	Creates a reader over a copy of the specified data.
	EoReader (const std::uint8_t *data, std::size_t length)
	Creates a reader over a copy of the specified data.
	EoReader (const EoReader &other)=default
	Creates a reader that shares this reader's data, with an independent copy of its position and chunked reading state.
	EoReader (EoReader &&other) noexcept
	Creates a reader that takes over another reader's data and state.
EoReader &	operator= (const EoReader &other)=default
	Replaces this reader's data and state with a copy of another reader's.
EoReader &	operator= (EoReader &&other) noexcept
	Replaces this reader's data and state with another reader's.
	~EoReader ()=default
EoReader	Slice () const
	Creates a new reader from a slice of this reader's data, starting at the current position.
EoReader	Slice (int index) const
	Creates a new reader from a slice of this reader's data, starting at the specified index.
EoReader	Slice (int index, int length) const
	Creates a new reader from a slice of this reader's data, with the specified index and length.
int	GetByte ()
	Reads a raw byte from the input data.
std::vector< std::uint8_t >	GetBytes (int length)
	Reads an array of raw bytes from the input data.
int	GetChar ()
	Reads an encoded 1-byte integer from the input data.
int	GetShort ()
	Reads an encoded 2-byte integer from the input data.
int	GetThree ()
	Reads an encoded 3-byte integer from the input data.
int	GetInt ()
	Reads an encoded 4-byte integer from the input data.
std::string	GetString ()
	Reads a string from the input data.
std::string	GetFixedString (int length, bool padded=false)
	Reads a fixed-length string from the input data.
std::string	GetEncodedString ()
	Reads an encoded string from the input data.
std::string	GetFixedEncodedString (int length, bool padded=false)
	Reads a fixed-length encoded string from the input data.
bool	GetChunkedReadingMode () const noexcept
	Gets the chunked reading mode for the reader.
void	SetChunkedReadingMode (bool chunked_reading_mode) noexcept
	Sets the chunked reading mode for the reader.
void	NextChunk ()
	Moves the reader position to the start of the next chunk.
int	Remaining () const noexcept
	Gets the number of bytes remaining in the input data.
int	Position () const noexcept
	Gets the current position in the input data.

Static Public Member Functions
static EoReader	View (std::string_view data) noexcept
	Creates a reader that refers to the specified data without copying it.
static EoReader	View (const std::uint8_t *data, std::size_t length) noexcept
	Creates a reader that refers to the specified data without copying it.
static EoReader	View (const std::vector< std::uint8_t > &data) noexcept
	Creates a reader that refers to the specified data without copying it.
static EoReader	View (std::vector< std::uint8_t > &&data)=delete
	Deleted to prevent creating a view over a temporary, which would dangle. Use the constructor instead.

Detailed Description

A class for reading EO data from a sequence of bytes.

EoReader features a chunked reading mode, which is important for accurate emulation of the official game client.

Reads past the end of the data (or the current chunk) do not throw; numeric reads return 0 and string/byte reads return truncated results.

Encoded numbers are returned as int. Malformed data can decode to negative or out-of-range values (a 0x00 byte decodes as -1), and 4-byte values above INT_MAX wrap to negative numbers, so code reading untrusted data must validate the values it reads.

A reader either owns its data (the constructors, which copy or take the data) or refers to data owned by the caller (View, which doesn't copy). Copies and slices of a reader share its data, and are views if it is a view.

See: https://github.com/Cirras/eo-protocol/blob/master/docs/chunks.md

Constructor & Destructor Documentation

EoReader() [1/5]

eolib::data::EoReader::EoReader ( std::vector< std::uint8_t > data )

explicit

Creates a reader over the specified data.

Parameters

data	the data to read.

EoReader() [2/5]

eolib::data::EoReader::EoReader ( std::string_view data )

explicit

Creates a reader over a copy of the specified data.

Parameters

data	the data to read, as a byte string.

EoReader() [3/5]

eolib::data::EoReader::EoReader	(	const std::uint8_t *	data,
		std::size_t	length )

Creates a reader over a copy of the specified data.

Parameters

data	a pointer to the data to read.
length	the number of bytes to read from data.

EoReader() [4/5]

eolib::data::EoReader::EoReader ( const EoReader & other )

default

Creates a reader that shares this reader's data, with an independent copy of its position and chunked reading state.

Parameters

other

the reader to copy.

EoReader() [5/5]

eolib::data::EoReader::EoReader ( EoReader && other )

noexcept

Creates a reader that takes over another reader's data and state.

The other reader is left empty.

Parameters

other

the reader to move from.

~EoReader()

eolib::data::EoReader::~EoReader ( )

default

Member Function Documentation

View() [1/4]

EoReader eolib::data::EoReader::View ( std::string_view data )

staticnoexcept

Creates a reader that refers to the specified data without copying it.

The data must outlive the reader, and all copies and slices of it. Generated types copy their fields out of the reader, so the data only needs to live until deserialization is complete.

Parameters

data	the data to read, as a byte string.

Returns

a reader over the data.

View() [2/4]

EoReader eolib::data::EoReader::View ( const std::uint8_t * data, std::size_t length )

staticnoexcept

Creates a reader that refers to the specified data without copying it.

The data must outlive the reader, and all copies and slices of it. Generated types copy their fields out of the reader, so the data only needs to live until deserialization is complete.

Parameters

data	a pointer to the data to read.
length	the number of bytes to read from data.

Returns

a reader over the data.

View() [3/4]

EoReader eolib::data::EoReader::View ( const std::vector< std::uint8_t > & data )

staticnoexcept

Creates a reader that refers to the specified data without copying it.

The data must outlive the reader, and all copies and slices of it. Generated types copy their fields out of the reader, so the data only needs to live until deserialization is complete.

Parameters

data	the data to read.

Returns

a reader over the data.

View() [4/4]

EoReader eolib::data::EoReader::View ( std::vector< std::uint8_t > && data )

staticdelete

Deleted to prevent creating a view over a temporary, which would dangle. Use the constructor instead.

operator=() [1/2]

EoReader & eolib::data::EoReader::operator= ( const EoReader & other )

default

Replaces this reader's data and state with a copy of another reader's.

The data is shared.

Parameters

other

the reader to copy.

Returns

this reader.

operator=() [2/2]

EoReader & eolib::data::EoReader::operator= ( EoReader && other )

noexcept

Replaces this reader's data and state with another reader's.

The other reader is left empty.

Parameters

other

the reader to move from.

Returns

this reader.

Slice() [1/3]

EoReader eolib::data::EoReader::Slice

(

)

const

Creates a new reader from a slice of this reader's data, starting at the current position.

The new reader shares the underlying data but has independent position and chunked reading state.

Returns

the new reader, covering the remaining data.

Slice() [2/3]

EoReader eolib::data::EoReader::Slice

(

int

index

)

const

Creates a new reader from a slice of this reader's data, starting at the specified index.

The new reader shares the underlying data but has independent position and chunked reading state.

Parameters

index

the index in this reader's data where the slice starts. Indexes past the end produce an empty reader.

Returns

the new reader, covering the data from index to the end.

Exceptions

std::invalid_argument

if the index is negative.

Slice() [3/3]

EoReader eolib::data::EoReader::Slice	(	int	index,
		int	length ) const

Creates a new reader from a slice of this reader's data, with the specified index and length.

The new reader shares the underlying data but has independent position and chunked reading state.

Parameters

index	the index in this reader's data where the slice starts.
length	the length of the slice. The slice is truncated if it extends past the end of the data.

Returns

the new reader, covering the specified range.

Exceptions

std::invalid_argument

if the index or length is negative.

GetByte()

int eolib::data::EoReader::GetByte

(

)

Reads a raw byte from the input data.

Returns

the byte value, or 0 if there is no data remaining.

GetBytes()

std::vector< std::uint8_t > eolib::data::EoReader::GetBytes

(

int

length

)

Reads an array of raw bytes from the input data.

Parameters

length

the number of bytes to read.

Returns

the bytes read, which may be fewer than length if there isn't enough data remaining.

GetChar()

int eolib::data::EoReader::GetChar

(

)

Reads an encoded 1-byte integer from the input data.

Returns

the decoded value. If fewer bytes remain, it is decoded from the bytes that are available (0 if there are none).

GetShort()

int eolib::data::EoReader::GetShort

(

)

Reads an encoded 2-byte integer from the input data.

Returns

the decoded value. If fewer bytes remain, it is decoded from the bytes that are available (0 if there are none).

GetThree()

int eolib::data::EoReader::GetThree

(

)

Reads an encoded 3-byte integer from the input data.

Returns

the decoded value. If fewer bytes remain, it is decoded from the bytes that are available (0 if there are none).

GetInt()

int eolib::data::EoReader::GetInt

(

)

Reads an encoded 4-byte integer from the input data.

Returns

the decoded value. If fewer bytes remain, it is decoded from the bytes that are available (0 if there are none). Values above INT_MAX wrap to negative numbers.

GetString()

std::string eolib::data::EoReader::GetString

(

)

Reads a string from the input data.

Returns

all remaining data, or the rest of the current chunk in chunked reading mode, as a string.

GetFixedString()

std::string eolib::data::EoReader::GetFixedString	(	int	length,
		bool	padded = false )

Reads a fixed-length string from the input data.

Parameters

length	the length of the string.
padded	true if the string is padded with trailing 0xFF bytes, which are removed.

Returns

the string, which may be shorter than length if there isn't enough data remaining.

Exceptions

std::invalid_argument

if the length is negative.

GetEncodedString()

std::string eolib::data::EoReader::GetEncodedString

(

)

Reads an encoded string from the input data.

Returns

all remaining data, or the rest of the current chunk in chunked reading mode, as a decoded string.

GetFixedEncodedString()

std::string eolib::data::EoReader::GetFixedEncodedString	(	int	length,
		bool	padded = false )

Reads a fixed-length encoded string from the input data.

Parameters

length	the length of the string.
padded	true if the string is padded with trailing 0xFF bytes, which are removed.

Returns

the decoded string, which may be shorter than length if there isn't enough data remaining.

Exceptions

std::invalid_argument

if the length is negative.

GetChunkedReadingMode()

bool eolib::data::EoReader::GetChunkedReadingMode ( ) const

noexcept

Gets the chunked reading mode for the reader.

Returns

true if the reader is in chunked reading mode.

SetChunkedReadingMode()

void eolib::data::EoReader::SetChunkedReadingMode ( bool chunked_reading_mode )

noexcept

Sets the chunked reading mode for the reader.

In chunked reading mode, the reader will treat 0xFF bytes as the boundaries between chunks of data.

Parameters

chunked_reading_mode

true to enable chunked reading mode.

NextChunk()

void eolib::data::EoReader::NextChunk

(

)

Moves the reader position to the start of the next chunk.

Exceptions

std::logic_error

if not in chunked reading mode.

Remaining()

int eolib::data::EoReader::Remaining ( ) const

noexcept

Gets the number of bytes remaining in the input data.

Returns

the number of bytes remaining, or the number remaining in the current chunk in chunked reading mode.

Position()

int eolib::data::EoReader::Position ( ) const

noexcept

Gets the current position in the input data.

Returns

the number of bytes read from the start of the input data.