eolib 0.5.0
A core C library for writing applications related to Endless Online
Loading...
Searching...
No Matches
data.h File Reference
#include <stdbool.h>
#include <stddef.h>
#include <stdint.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_set_chunked_reading_mode (EoReader *reader, bool enabled)
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 21 of file data.h.

◆ EO_CHAR_MAX

#define EO_CHAR_MAX   253

Maximum value encodable in one EO byte.

Definition at line 11 of file data.h.

◆ EO_INT_MAX

#define EO_INT_MAX   4097152081

Maximum value encodable in four EO bytes.

Definition at line 17 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 19 of file data.h.

◆ EO_SHORT_MAX

#define EO_SHORT_MAX   64009

Maximum value encodable in two EO bytes.

Definition at line 13 of file data.h.

◆ EO_THREE_MAX

#define EO_THREE_MAX   16194277

Maximum value encodable in three EO bytes.

Definition at line 15 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 462 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 392 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
bytesInput bytes.
lengthNumber 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 314 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
bufBuffer to decode.
lengthNumber 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 340 of file data.c.

◆ eo_deserialize()

EoResult eo_deserialize ( EoSerialize * serialize,
EoReader * reader )
inlinestatic

Deserializes data from a reader into a struct implementing EoSerialize.

Parameters
serializeStruct to populate.
readerReader 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 414 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
numberValue to encode.
out_bytesBuffer 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 273 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
bufBuffer to encode.
lengthNumber 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 375 of file data.c.

◆ eo_free()

void eo_free ( EoSerialize * serialize)
inlinestatic

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

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

Definition at line 452 of file data.h.

◆ eo_get_size()

size_t eo_get_size ( const EoSerialize * serialize)
inlinestatic

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

Parameters
serializeStruct to query.
Returns
Size in bytes of the serialized form, or 0 if serialize is NULL.

Definition at line 440 of file data.h.

◆ eo_packet_get_action()

uint8_t eo_packet_get_action ( const EoPacket * packet)
inlinestatic

Gets the action of an EO packet.

Parameters
packetEO packet to query.
Returns
Action of the EO packet.

Definition at line 492 of file data.h.

◆ eo_packet_get_family()

uint8_t eo_packet_get_family ( const EoPacket * packet)
inlinestatic

Gets the family of an EO packet.

Parameters
packetEO packet to query.
Returns
Family of the EO packet.

Definition at line 480 of file data.h.

◆ eo_reader_get_byte()

EoResult eo_reader_get_byte ( EoReader * reader,
uint8_t * out_value )

Reads a raw byte from the reader.

Parameters
readerReader to consume from.
out_valueOutput 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 931 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
readerReader to consume from.
lengthNumber of bytes to read.
out_valueOutput 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 1169 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
readerReader to consume from.
out_valueOutput 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 958 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
readerReader to query.
Returns
True if chunked reading is enabled.

Definition at line 846 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
readerReader to consume from.
out_valueOutput 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 1090 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
readerReader to consume from.
lengthNumber of bytes to read.
out_valueOutput 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 1138 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
readerReader to consume from.
lengthNumber of bytes to read.
out_valueOutput 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 1107 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
readerReader to consume from.
out_valueOutput 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 1042 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
readerReader to consume from.
out_valueOutput 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 985 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
readerReader to consume from.
out_valueOutput 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 1073 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
readerReader to consume from.
out_valueOutput 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 1012 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
dataPointer to the byte buffer. The caller must ensure it remains valid for the lifetime of the reader.
lengthNumber of bytes in the buffer.
Returns
The initialized reader with chunked reading mode disabled.

Definition at line 834 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
readerReader 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 889 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
readerReader to query.
Returns
Remaining bytes.

Definition at line 863 of file data.c.

◆ eo_reader_set_chunked_reading_mode()

void eo_reader_set_chunked_reading_mode ( EoReader * reader,
bool enabled )

Enables or disables chunked reading mode.

Parameters
readerReader to update.
enabledTrue to enable chunked reading.

Definition at line 851 of file data.c.

◆ eo_serialize()

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

Serializes a struct implementing EoSerialize into a writer.

Parameters
serializeStruct to serialize.
writerWriter 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 428 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
valueUTF-8 input string. If NULL, out_value is set to NULL and EO_SUCCESS is returned.
out_valueOutput 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 154 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
writerWriter to append to.
valueByte value to append.
Returns
EO_SUCCESS on success, or a non-zero EoResult on failure.

Definition at line 423 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
writerWriter to append to.
dataBytes to append.
lengthNumber of bytes to append.
Returns
EO_SUCCESS on success, or a non-zero EoResult on failure.

Definition at line 815 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
writerWriter to append to.
valueValue to encode.
Returns
EO_SUCCESS on success, or a non-zero EoResult on failure.

Definition at line 440 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
writerWriter to append to.
valueString to encode and append.
Returns
EO_SUCCESS on success, or a non-zero EoResult on failure.

Definition at line 607 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
writerWriter to append to.
valueString to encode and append (without terminator).
lengthFixed length of the string in bytes.
paddedIf 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 734 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
writerWriter to append to.
valueString to append (without terminator).
lengthFixed length of the string in bytes.
paddedIf 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 665 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
writerWriter to append to.
valueValue 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 529 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
writerWriter to append to.
valueValue 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_string()

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

Appends a raw string to the writer.

Parameters
writerWriter to append to.
valueString to append (without terminator).
Returns
EO_SUCCESS on success, or a non-zero EoResult on failure.

Definition at line 561 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
writerWriter to append to.
valueValue to encode.
Returns
EO_SUCCESS on success, or a non-zero EoResult on failure.

Definition at line 499 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
writerWriter to grow.
additionalAdditional 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 243 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
writerWriter 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 231 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
writerWriter to query.
Returns
True if sanitization mode is enabled.

Definition at line 410 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 216 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
capacityInitial allocation size in bytes.
Returns
The initialized writer.

Definition at line 221 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
writerWriter to update.
enabledTrue to enable sanitization.

Definition at line 415 of file data.c.