data.h File Reference

#include <stddef.h>
#include "eo_compat.h"
#include "result.h"

Go to the source code of this file.

Data Structures
struct	EoWriter
struct	EoReader
struct	EoSerializeVTable
struct	EoSerialize
struct	EoPacketVTable
struct	EoPacket

Macros
#define	EO_CHAR_MAX   253
#define	EO_SHORT_MAX   64009
#define	EO_THREE_MAX   16194277
#define	EO_INT_MAX   4097152081
#define	EO_NUMBER_PADDING   0xFE
#define	EO_BREAK_BYTE   0xFF

Typedefs
typedef struct EoWriter	EoWriter
typedef struct EoReader	EoReader
typedef struct EoSerialize	EoSerialize
	Interface for serializable objects.
typedef struct EoPacket	EoPacket
	Interface for EO packets, which are serializable objects with a family and action.

Functions
EoResult	eo_string_to_windows_1252 (const char *value, char **out_value)
EoWriter	eo_writer_init (void)
EoWriter	eo_writer_init_with_capacity (size_t capacity)
void	eo_writer_free (EoWriter *writer)
EoResult	eo_writer_ensure_capacity (EoWriter *writer, size_t additional)
EoResult	eo_encode_number (int32_t number, uint8_t out_bytes[4])
int32_t	eo_decode_number (const uint8_t *bytes, size_t length)
void	eo_decode_string (uint8_t *buf, size_t length)
void	eo_encode_string (uint8_t *buf, size_t length)
bool	eo_writer_get_string_sanitization_mode (const EoWriter *writer)
void	eo_writer_set_string_sanitization_mode (EoWriter *writer, bool enabled)
EoResult	eo_writer_add_byte (EoWriter *writer, uint8_t value)
EoResult	eo_writer_add_char (EoWriter *writer, int32_t value)
EoResult	eo_writer_add_short (EoWriter *writer, int32_t value)
EoResult	eo_writer_add_three (EoWriter *writer, int32_t value)
EoResult	eo_writer_add_int (EoWriter *writer, int32_t value)
EoResult	eo_writer_add_string (EoWriter *writer, const char *value)
EoResult	eo_writer_add_encoded_string (EoWriter *writer, const char *value)
EoResult	eo_writer_add_fixed_string (EoWriter *writer, const char *value, size_t length, bool padded)
EoResult	eo_writer_add_fixed_encoded_string (EoWriter *writer, const char *value, size_t length, bool padded)
EoResult	eo_writer_add_bytes (EoWriter *writer, const uint8_t *data, size_t length)
EoReader	eo_reader_init (const uint8_t *data, size_t length)
bool	eo_reader_get_chunked_reading_mode (const EoReader *reader)
void	eo_reader_activate_chunked_reading (EoReader *reader)
size_t	eo_reader_remaining (const EoReader *reader)
EoResult	eo_reader_next_chunk (EoReader *reader)
EoResult	eo_reader_get_byte (EoReader *reader, uint8_t *out_value)
EoResult	eo_reader_get_char (EoReader *reader, int32_t *out_value)
EoResult	eo_reader_get_short (EoReader *reader, int32_t *out_value)
EoResult	eo_reader_get_three (EoReader *reader, int32_t *out_value)
EoResult	eo_reader_get_int (EoReader *reader, int32_t *out_value)
EoResult	eo_reader_get_string (EoReader *reader, char **out_value)
EoResult	eo_reader_get_encoded_string (EoReader *reader, char **out_value)
EoResult	eo_reader_get_fixed_string (EoReader *reader, size_t length, char **out_value)
EoResult	eo_reader_get_fixed_encoded_string (EoReader *reader, size_t length, char **out_value)
EoResult	eo_reader_get_bytes (EoReader *reader, size_t length, uint8_t **out_value)
static EoResult	eo_deserialize (EoSerialize *serialize, EoReader *reader)
static EoResult	eo_serialize (const EoSerialize *serialize, EoWriter *writer)
static size_t	eo_get_size (const EoSerialize *serialize)
static void	eo_free (EoSerialize *serialize)
static uint8_t	eo_packet_get_family (const EoPacket *packet)
	Gets the family of an EO packet.
static uint8_t	eo_packet_get_action (const EoPacket *packet)
	Gets the action of an EO packet.

Macro Definition Documentation

EO_BREAK_BYTE

#define EO_BREAK_BYTE   0xFF

Delimiter byte used to mark chunk boundaries in EO string/packet data.

Definition at line 20 of file data.h.

EO_CHAR_MAX

#define EO_CHAR_MAX   253

Maximum value encodable in one EO byte.

Definition at line 10 of file data.h.

EO_INT_MAX

#define EO_INT_MAX   4097152081

Maximum value encodable in four EO bytes.

Definition at line 16 of file data.h.

EO_NUMBER_PADDING

#define EO_NUMBER_PADDING   0xFE

Value used to represent missing bytes in EO number encoding.

Definition at line 18 of file data.h.

EO_SHORT_MAX

#define EO_SHORT_MAX   64009

Maximum value encodable in two EO bytes.

Definition at line 12 of file data.h.

EO_THREE_MAX

#define EO_THREE_MAX   16194277

Maximum value encodable in three EO bytes.

Definition at line 14 of file data.h.

Typedef Documentation

EoPacket

typedef struct EoPacket EoPacket

Interface for EO packets, which are serializable objects with a family and action.

Definition at line 460 of file data.h.

EoReader

typedef struct EoReader EoReader

Reader that parses EO-encoded bytes.

EoSerialize

typedef struct EoSerialize EoSerialize

Interface for serializable objects.

Definition at line 390 of file data.h.

EoWriter

typedef struct EoWriter EoWriter

Writer that accumulates EO-encoded bytes.

Function Documentation

eo_decode_number()

int32_t eo_decode_number	(	const uint8_t *	bytes,
		size_t	length )

Decodes an EO-encoded integer.

Parameters

bytes	Input bytes.
length	Number of bytes to decode (1-4).

Returns

The decoded value.

Remarks

Inputs must be valid EO-encoded bytes (values produced by eo_encode_number). Passing arbitrary bytes may produce values outside the representable range, resulting in a silent cast to int32_t with implementation-defined behavior.

Definition at line 334 of file data.c.

eo_decode_string()

void eo_decode_string	(	uint8_t *	buf,
		size_t	length )

Decodes a string in place using the EO string transform.

Parameters

buf	Buffer to decode.
length	Number of bytes in the buffer.

Remarks

This is a low-level transform exposed for advanced use. Prefer eo_reader_get_encoded_string and related functions which apply this transform automatically. Calling this twice on the same buffer (double-decoding) will corrupt the data.

Definition at line 362 of file data.c.

eo_deserialize()

EoResult eo_deserialize ( EoSerialize * serialize, EoReader * reader )

static

Deserializes data from a reader into a struct implementing EoSerialize.

Parameters

serialize	Struct to populate.
reader	Reader to consume from.

Returns

EO_SUCCESS on success, EO_NULL_PTR if serialize or reader is NULL, or a non-zero EoResult if deserialization fails.

Definition at line 412 of file data.h.

eo_encode_number()

EoResult eo_encode_number	(	int32_t	number,
		uint8_t	out_bytes[4] )

Encodes an integer into EO byte format.

Parameters

number	Value to encode.
out_bytes	Buffer for up to 4 encoded bytes.

Returns

EO_SUCCESS on success, EO_NULL_PTR if out_bytes is NULL, or EO_NUMBER_TOO_LARGE if the value exceeds the EO encoding range.

Remarks

Negative values are encoded using their 32-bit two's-complement bit pattern. As a result, only wrapped negative values whose unsigned representation is less than EO_INT_MAX are encodable.

Definition at line 290 of file data.c.

eo_encode_string()

void eo_encode_string	(	uint8_t *	buf,
		size_t	length )

Encodes a string in place using the EO string transform.

Parameters

buf	Buffer to encode.
length	Number of bytes in the buffer.

Remarks

This is a low-level transform exposed for advanced use. Prefer eo_writer_add_encoded_string and related functions which apply this transform automatically. Calling this twice on the same buffer (double-encoding) will corrupt the data.

Definition at line 400 of file data.c.

eo_free()

void eo_free ( EoSerialize * serialize )

static

Frees any heap-allocated memory owned by a struct implementing EoSerialize.

Parameters

serialize

Struct to free.

Remarks

This function does not free the struct itself, only any internal memory it owns.

Definition at line 450 of file data.h.

eo_get_size()

size_t eo_get_size ( const EoSerialize * serialize )

static

Returns the size in bytes of the serialized form of a struct implementing EoSerialize.

Parameters

serialize

Struct to query.

Returns

Size in bytes of the serialized form, or 0 if serialize is NULL.

Definition at line 438 of file data.h.

eo_packet_get_action()

uint8_t eo_packet_get_action ( const EoPacket * packet )

static

Gets the action of an EO packet.

Parameters

packet

EO packet to query.

Returns

Action of the EO packet.

Definition at line 490 of file data.h.

eo_packet_get_family()

uint8_t eo_packet_get_family ( const EoPacket * packet )

static

Gets the family of an EO packet.

Parameters

packet

EO packet to query.

Returns

Family of the EO packet.

Definition at line 478 of file data.h.

eo_reader_activate_chunked_reading()

void eo_reader_activate_chunked_reading

(

EoReader *

reader

)

Enables chunked reading mode.

Parameters

reader

Reader to update.

Definition at line 917 of file data.c.

eo_reader_get_byte()

EoResult eo_reader_get_byte	(	EoReader *	reader,
		uint8_t *	out_value )

Reads a raw byte from the reader.

Parameters

reader	Reader to consume from.
out_value	Output for the byte.

Returns

EO_SUCCESS on success, EO_NULL_PTR if reader or out_value is NULL, or EO_BUFFER_UNDERRUN if not enough bytes remain (non-chunked mode only).

Remarks

In chunked reading mode, reading past the end of a chunk returns EO_SUCCESS with out_value set to 0 rather than EO_BUFFER_UNDERRUN. Use eo_reader_remaining() to check available bytes before reading.

Definition at line 996 of file data.c.

eo_reader_get_bytes()

EoResult eo_reader_get_bytes	(	EoReader *	reader,
		size_t	length,
		uint8_t **	out_value )

Reads raw bytes from the reader.

Parameters

reader	Reader to consume from.
length	Number of bytes to read.
out_value	Output buffer, heap-allocated — caller must free.

Returns

EO_SUCCESS on success, EO_NULL_PTR if reader or out_value is NULL, EO_BUFFER_UNDERRUN if not enough bytes remain, or EO_ALLOC_FAILED if memory allocation fails.

Definition at line 1247 of file data.c.

eo_reader_get_char()

EoResult eo_reader_get_char	(	EoReader *	reader,
		int32_t *	out_value )

Reads a 1-byte EO-encoded number.

Parameters

reader	Reader to consume from.
out_value	Output for the value.

Returns

EO_SUCCESS on success, EO_NULL_PTR if reader or out_value is NULL, or EO_BUFFER_UNDERRUN if not enough bytes remain (non-chunked mode only).

Remarks

In chunked reading mode, reading past the end of a chunk returns EO_SUCCESS with out_value set to 0 rather than EO_BUFFER_UNDERRUN. Use eo_reader_remaining() to check available bytes before reading.

Definition at line 1025 of file data.c.

eo_reader_get_chunked_reading_mode()

bool eo_reader_get_chunked_reading_mode

(

const EoReader *

reader

)

Returns the current chunked reading mode.

Parameters

reader

Reader to query.

Returns

True if chunked reading is enabled.

Definition at line 912 of file data.c.

eo_reader_get_encoded_string()

EoResult eo_reader_get_encoded_string	(	EoReader *	reader,
		char **	out_value )

Reads the remaining bytes as an EO-encoded string.

Parameters

reader	Reader to consume from.
out_value	Output string, heap-allocated — caller must free.

Returns

EO_SUCCESS on success, EO_NULL_PTR if reader or out_value is NULL, or EO_ALLOC_FAILED if memory allocation fails.

Definition at line 1166 of file data.c.

eo_reader_get_fixed_encoded_string()

EoResult eo_reader_get_fixed_encoded_string	(	EoReader *	reader,
		size_t	length,
		char **	out_value )

Reads a fixed-length EO-encoded string.

Parameters

reader	Reader to consume from.
length	Number of bytes to read.
out_value	Output string, heap-allocated — caller must free.

Returns

EO_SUCCESS on success, EO_NULL_PTR if reader or out_value is NULL, EO_BUFFER_UNDERRUN if not enough bytes remain, or EO_ALLOC_FAILED if memory allocation fails.

Definition at line 1216 of file data.c.

eo_reader_get_fixed_string()

EoResult eo_reader_get_fixed_string	(	EoReader *	reader,
		size_t	length,
		char **	out_value )

Reads a fixed-length raw string.

Parameters

reader	Reader to consume from.
length	Number of bytes to read.
out_value	Output string, heap-allocated — caller must free.

Returns

EO_SUCCESS on success, EO_NULL_PTR if reader or out_value is NULL, EO_BUFFER_UNDERRUN if not enough bytes remain, or EO_ALLOC_FAILED if memory allocation fails.

Definition at line 1185 of file data.c.

eo_reader_get_int()

EoResult eo_reader_get_int	(	EoReader *	reader,
		int32_t *	out_value )

Reads a 4-byte EO-encoded number.

Parameters

reader	Reader to consume from.
out_value	Output for the value.

Returns

EO_SUCCESS on success, EO_NULL_PTR if reader or out_value is NULL, or EO_BUFFER_UNDERRUN if not enough bytes remain (non-chunked mode only).

Remarks

In chunked reading mode, reading past the end of a chunk returns EO_SUCCESS with out_value set to 0 rather than EO_BUFFER_UNDERRUN. Use eo_reader_remaining() to check available bytes before reading.

Definition at line 1115 of file data.c.

eo_reader_get_short()

EoResult eo_reader_get_short	(	EoReader *	reader,
		int32_t *	out_value )

Reads a 2-byte EO-encoded number.

Parameters

reader	Reader to consume from.
out_value	Output for the value.

Returns

EO_SUCCESS on success, EO_NULL_PTR if reader or out_value is NULL, or EO_BUFFER_UNDERRUN if not enough bytes remain (non-chunked mode only).

Remarks

In chunked reading mode, reading past the end of a chunk returns EO_SUCCESS with out_value set to 0 rather than EO_BUFFER_UNDERRUN. Use eo_reader_remaining() to check available bytes before reading.

Definition at line 1054 of file data.c.

eo_reader_get_string()

EoResult eo_reader_get_string	(	EoReader *	reader,
		char **	out_value )

Reads the remaining bytes as a raw string.

Parameters

reader	Reader to consume from.
out_value	Output string, heap-allocated — caller must free.

Returns

EO_SUCCESS on success, EO_NULL_PTR if reader or out_value is NULL, or EO_ALLOC_FAILED if memory allocation fails.

Definition at line 1147 of file data.c.

eo_reader_get_three()

EoResult eo_reader_get_three	(	EoReader *	reader,
		int32_t *	out_value )

Reads a 3-byte EO-encoded number.

Parameters

reader	Reader to consume from.
out_value	Output for the value.

Returns

EO_SUCCESS on success, EO_NULL_PTR if reader or out_value is NULL, or EO_BUFFER_UNDERRUN if not enough bytes remain (non-chunked mode only).

Remarks

In chunked reading mode, reading past the end of a chunk returns EO_SUCCESS with out_value set to 0 rather than EO_BUFFER_UNDERRUN. Use eo_reader_remaining() to check available bytes before reading.

Definition at line 1084 of file data.c.

eo_reader_init()

EoReader eo_reader_init	(	const uint8_t *	data,
		size_t	length )

Initializes a reader over an existing byte buffer.

Parameters

data	Pointer to the byte buffer. The caller must ensure it remains valid for the lifetime of the reader.
length	Number of bytes in the buffer.

Returns

The initialized reader with chunked reading mode disabled.

Definition at line 900 of file data.c.

eo_reader_next_chunk()

EoResult eo_reader_next_chunk

(

EoReader *

reader

)

Advances to the next chunk when chunked reading is enabled.

Parameters

reader

Reader to advance.

Returns

EO_SUCCESS on success, EO_NULL_PTR if reader is NULL, or EO_CHUNKED_MODE_DISABLED if chunked reading mode is not active.

Definition at line 952 of file data.c.

eo_reader_remaining()

size_t eo_reader_remaining

(

const EoReader *

reader

)

Returns the number of bytes remaining in the current read window.

Parameters

reader

Reader to query.

Returns

Remaining bytes.

Definition at line 926 of file data.c.

eo_serialize()

EoResult eo_serialize ( const EoSerialize * serialize, EoWriter * writer )

static

Serializes a struct implementing EoSerialize into a writer.

Parameters

serialize	Struct to serialize.
writer	Writer to append to.

Returns

EO_SUCCESS on success, EO_NULL_PTR if serialize or writer is NULL, or a non-zero EoResult if serialization fails.

Definition at line 426 of file data.h.

eo_string_to_windows_1252()

EoResult eo_string_to_windows_1252	(	const char *	value,
		char **	out_value )

Converts a UTF-8 string to Windows-1252 (CP1252) encoding.

Parameters

value	UTF-8 input string. If NULL, out_value is set to NULL and EO_SUCCESS is returned.
out_value	Output string in Windows-1252, heap-allocated — caller must free.

Returns

EO_SUCCESS on success, EO_NULL_PTR if out_value is NULL, or EO_ALLOC_FAILED if memory allocation fails.

Remarks

Valid UTF-8 multi-byte sequences are decoded and mapped to their Windows-1252 equivalents. Characters with no Windows-1252 representation are replaced with '?'. Bytes that do not form a valid UTF-8 sequence are passed through unchanged, so strings that are already Windows-1252 encoded are returned as-is.

Definition at line 164 of file data.c.

eo_writer_add_byte()

EoResult eo_writer_add_byte	(	EoWriter *	writer,
		uint8_t	value )

Appends a raw byte to the writer.

Parameters

writer	Writer to append to.
value	Byte value to append.

Returns

EO_SUCCESS on success, or a non-zero EoResult on failure.

Definition at line 451 of file data.c.

eo_writer_add_bytes()

EoResult eo_writer_add_bytes	(	EoWriter *	writer,
		const uint8_t *	data,
		size_t	length )

Appends raw bytes to the writer.

Parameters

writer	Writer to append to.
data	Bytes to append.
length	Number of bytes to append.

Returns

EO_SUCCESS on success, or a non-zero EoResult on failure.

Definition at line 880 of file data.c.

eo_writer_add_char()

EoResult eo_writer_add_char	(	EoWriter *	writer,
		int32_t	value )

Appends a 1-byte EO-encoded number.

Parameters

writer	Writer to append to.
value	Value to encode.

Returns

EO_SUCCESS on success, or a non-zero EoResult on failure.

Definition at line 469 of file data.c.

eo_writer_add_encoded_string()

EoResult eo_writer_add_encoded_string	(	EoWriter *	writer,
		const char *	value )

Appends a string encoded with the EO string transform.

Parameters

writer	Writer to append to.
value	String to encode and append.

Returns

EO_SUCCESS on success, or a non-zero EoResult on failure.

Definition at line 646 of file data.c.

eo_writer_add_fixed_encoded_string()

EoResult eo_writer_add_fixed_encoded_string	(	EoWriter *	writer,
		const char *	value,
		size_t	length,
		bool	padded )

Appends a fixed-length string encoded with the EO string transform, with optional padding.

Parameters

writer	Writer to append to.
value	String to encode and append (without terminator).
length	Fixed length of the string in bytes.
padded	If true, shorter strings will be padded with 0xFF bytes.

Returns

EO_SUCCESS on success, EO_STR_OUT_OF_RANGE if the string is too long, EO_STR_TOO_SHORT if the string is too short and padding is disabled, or a non-zero EoResult on other failures.

Definition at line 789 of file data.c.

eo_writer_add_fixed_string()

EoResult eo_writer_add_fixed_string	(	EoWriter *	writer,
		const char *	value,
		size_t	length,
		bool	padded )

Appends a fixed-length string to the writer, with optional padding.

Parameters

writer	Writer to append to.
value	String to append (without terminator).
length	Fixed length of the string in bytes.
padded	If true, shorter strings will be padded with 0xFF bytes.

Returns

EO_SUCCESS on success, EO_STR_OUT_OF_RANGE if the string is too long, EO_STR_TOO_SHORT if the string is too short and padding is disabled, or a non-zero EoResult on other failures.

Definition at line 711 of file data.c.

eo_writer_add_int()

EoResult eo_writer_add_int	(	EoWriter *	writer,
		int32_t	value )

Appends a 4-byte EO-encoded number.

Parameters

writer	Writer to append to.
value	Value to encode.

Returns

EO_SUCCESS on success, EO_INVALID_INT if the value is outside the representable 4-byte EO int range, or a non-zero EoResult on failure.

Remarks

Values in [0, INT32_MAX] are always representable. Negative values are only representable when their 32-bit unsigned bit pattern is less than EO_INT_MAX, which corresponds to the range [INT32_MIN, -197815216].

Definition at line 561 of file data.c.

eo_writer_add_short()

EoResult eo_writer_add_short	(	EoWriter *	writer,
		int32_t	value )

Appends a 2-byte EO-encoded number.

Parameters

writer	Writer to append to.
value	Value to encode.

Returns

EO_SUCCESS on success, or a non-zero EoResult on failure.

Definition at line 499 of file data.c.

eo_writer_add_string()

EoResult eo_writer_add_string	(	EoWriter *	writer,
		const char *	value )

Appends a raw string to the writer.

Parameters

writer	Writer to append to.
value	String to append (without terminator).

Returns

EO_SUCCESS on success, or a non-zero EoResult on failure.

Definition at line 594 of file data.c.

eo_writer_add_three()

EoResult eo_writer_add_three	(	EoWriter *	writer,
		int32_t	value )

Appends a 3-byte EO-encoded number.

Parameters

writer	Writer to append to.
value	Value to encode.

Returns

EO_SUCCESS on success, or a non-zero EoResult on failure.

Definition at line 530 of file data.c.

eo_writer_ensure_capacity()

EoResult eo_writer_ensure_capacity	(	EoWriter *	writer,
		size_t	additional )

Ensures a writer has space for additional bytes, reallocating if necessary.

Parameters

writer	Writer to grow.
additional	Additional bytes required.

Returns

EO_SUCCESS on success, EO_NULL_PTR if writer is NULL, EO_OVERFLOW if the required size would overflow, or EO_ALLOC_FAILED if memory reallocation fails.

Remarks

This is an advanced function. Prefer using the eo_writer_add_* functions which call this automatically.

Definition at line 256 of file data.c.

eo_writer_free()

void eo_writer_free

(

EoWriter *

writer

)

Frees the memory allocated by a writer and zeroes the struct.

Parameters

writer

Writer to free. If NULL, this function does nothing.

Remarks

The caller is responsible for calling this function when the writer is no longer needed. Failure to do so will leak the writer's data buffer.

Definition at line 244 of file data.c.

eo_writer_get_string_sanitization_mode()

bool eo_writer_get_string_sanitization_mode

(

const EoWriter *

writer

)

Returns the current writer string sanitization mode.

Parameters

writer

Writer to query.

Returns

True if sanitization mode is enabled.

Definition at line 438 of file data.c.

eo_writer_init()

EoWriter eo_writer_init

(

void

)

Initializes a writer with a default initial capacity.

Returns

The initialized writer.

Definition at line 229 of file data.c.

eo_writer_init_with_capacity()

EoWriter eo_writer_init_with_capacity

(

size_t

capacity

)

Initializes a writer with a specified initial capacity.

Parameters

capacity

Initial allocation size in bytes.

Returns

The initialized writer.

Definition at line 234 of file data.c.

eo_writer_set_string_sanitization_mode()

void eo_writer_set_string_sanitization_mode	(	EoWriter *	writer,
		bool	enabled )

Enables or disables string sanitization mode.

Parameters

writer	Writer to update.
enabled	True to enable sanitization.

Definition at line 443 of file data.c.