binserde.h

/**
 * @file binserde.h
 * @brief Binary Serialization Library for C
 * 
 * A lightweight, endian-safe binary serialization library with support for
 * versioning, schema evolution, and validation. No external dependencies.
 * 
 * Features:
 * - Compact binary format
 * - Automatic endianness handling (network byte order)
 * - Schema versioning and evolution
 * - Data validation
 * - File and network I/O support
 */

#ifndef BINSERDE_H
#define BINSERDE_H

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

/* Version Information */
#define BINSERDE_VERSION_MAJOR 1
#define BINSERDE_VERSION_MINOR 0
#define BINSERDE_VERSION_PATCH 0

/* Error Codes */
typedef enum {
    BINSERDE_OK = 0,
    BINSERDE_ERR_NULL_PTR = -1,
    BINSERDE_ERR_BUFFER_TOO_SMALL = -2,
    BINSERDE_ERR_INVALID_DATA = -3,
    BINSERDE_ERR_VERSION_MISMATCH = -4,
    BINSERDE_ERR_CHECKSUM_FAILED = -5,
    BINSERDE_ERR_UNKNOWN_TYPE = -6,
    BINSERDE_ERR_IO = -7,
} binserde_error_t;

/* Supported Data Types */
typedef enum {
    BINSERDE_TYPE_INT8 = 1,
    BINSERDE_TYPE_UINT8 = 2,
    BINSERDE_TYPE_INT16 = 3,
    BINSERDE_TYPE_UINT16 = 4,
    BINSERDE_TYPE_INT32 = 5,
    BINSERDE_TYPE_UINT32 = 6,
    BINSERDE_TYPE_INT64 = 7,
    BINSERDE_TYPE_UINT64 = 8,
    BINSERDE_TYPE_FLOAT = 9,
    BINSERDE_TYPE_DOUBLE = 10,
    BINSERDE_TYPE_BOOL = 11,
    BINSERDE_TYPE_STRING = 12,
    BINSERDE_TYPE_BYTES = 13,
    BINSERDE_TYPE_STRUCT_BEGIN = 14,
    BINSERDE_TYPE_STRUCT_END = 15,
    BINSERDE_TYPE_ARRAY_BEGIN = 16,
    BINSERDE_TYPE_ARRAY_END = 17,
} binserde_type_t;

/* Serialization Context */
typedef struct {
    uint8_t *buffer;      /* Output buffer */
    size_t capacity;      /* Buffer capacity */
    size_t position;      /* Current write position */
    uint32_t version;     /* Schema version */
    bool enable_checksum; /* Enable checksum validation */
} binserde_writer_t;

/* Deserialization Context */
typedef struct {
    const uint8_t *buffer; /* Input buffer */
    size_t size;           /* Buffer size */
    size_t position;       /* Current read position */
    uint32_t version;      /* Schema version */
    bool enable_checksum;  /* Enable checksum validation */
} binserde_reader_t;

/* Field Definition for Schema */
typedef struct {
    const char *name;     /* Field name */
    binserde_type_t type; /* Field type */
    uint32_t min_version; /* Minimum version where field exists */
    uint32_t max_version; /* Maximum version (0 = no max) */
    bool required;        /* Is field required */
} binserde_field_t;

/* Schema Definition */
typedef struct {
    const char *name;           /* Schema name */
    uint32_t version;           /* Schema version */
    binserde_field_t *fields;   /* Array of fields */
    size_t field_count;         /* Number of fields */
} binserde_schema_t;

/* API Functions */

/**
 * Initialize a writer context
 * @param writer Writer context to initialize
 * @param buffer Output buffer
 * @param capacity Buffer capacity
 * @param version Schema version
 * @return Error code
 */
binserde_error_t binserde_writer_init(binserde_writer_t *writer,
                                      uint8_t *buffer,
                                      size_t capacity,
                                      uint32_t version);

/**
 * Initialize a reader context
 * @param reader Reader context to initialize
 * @param buffer Input buffer
 * @param size Buffer size
 * @return Error code
 */
binserde_error_t binserde_reader_init(binserde_reader_t *reader,
                                      const uint8_t *buffer,
                                      size_t size);

/**
 * Write header with magic number and version
 * @param writer Writer context
 * @return Error code
 */
binserde_error_t binserde_write_header(binserde_writer_t *writer);

/**
 * Read and validate header
 * @param reader Reader context
 * @param version Output: schema version
 * @return Error code
 */
binserde_error_t binserde_read_header(binserde_reader_t *reader, uint32_t *version);

/**
 * Write integer types
 */
binserde_error_t binserde_write_int8(binserde_writer_t *writer, int8_t value);
binserde_error_t binserde_write_uint8(binserde_writer_t *writer, uint8_t value);
binserde_error_t binserde_write_int16(binserde_writer_t *writer, int16_t value);
binserde_error_t binserde_write_uint16(binserde_writer_t *writer, uint16_t value);
binserde_error_t binserde_write_int32(binserde_writer_t *writer, int32_t value);
binserde_error_t binserde_write_uint32(binserde_writer_t *writer, uint32_t value);
binserde_error_t binserde_write_int64(binserde_writer_t *writer, int64_t value);
binserde_error_t binserde_write_uint64(binserde_writer_t *writer, uint64_t value);

/**
 * Write floating point types
 */
binserde_error_t binserde_write_float(binserde_writer_t *writer, float value);
binserde_error_t binserde_write_double(binserde_writer_t *writer, double value);

/**
 * Write boolean
 */
binserde_error_t binserde_write_bool(binserde_writer_t *writer, bool value);

/**
 * Write string (null-terminated)
 * @param writer Writer context
 * @param value String to write
 * @return Error code
 */
binserde_error_t binserde_write_string(binserde_writer_t *writer, const char *value);

/**
 * Write raw bytes
 * @param writer Writer context
 * @param data Byte array
 * @param length Length of byte array
 * @return Error code
 */
binserde_error_t binserde_write_bytes(binserde_writer_t *writer,
                                      const uint8_t *data,
                                      uint32_t length);

/**
 * Read integer types
 */
binserde_error_t binserde_read_int8(binserde_reader_t *reader, int8_t *value);
binserde_error_t binserde_read_uint8(binserde_reader_t *reader, uint8_t *value);
binserde_error_t binserde_read_int16(binserde_reader_t *reader, int16_t *value);
binserde_error_t binserde_read_uint16(binserde_reader_t *reader, uint16_t *value);
binserde_error_t binserde_read_int32(binserde_reader_t *reader, int32_t *value);
binserde_error_t binserde_read_uint32(binserde_reader_t *reader, uint32_t *value);
binserde_error_t binserde_read_int64(binserde_reader_t *reader, int64_t *value);
binserde_error_t binserde_read_uint64(binserde_reader_t *reader, uint64_t *value);

/**
 * Read floating point types
 */
binserde_error_t binserde_read_float(binserde_reader_t *reader, float *value);
binserde_error_t binserde_read_double(binserde_reader_t *reader, double *value);

/**
 * Read boolean
 */
binserde_error_t binserde_read_bool(binserde_reader_t *reader, bool *value);

/**
 * Read string (allocates memory, caller must free)
 * @param reader Reader context
 * @param value Output: pointer to allocated string
 * @return Error code
 */
binserde_error_t binserde_read_string(binserde_reader_t *reader, char **value);

/**
 * Read raw bytes (allocates memory, caller must free)
 * @param reader Reader context
 * @param data Output: pointer to allocated byte array
 * @param length Output: length of byte array
 * @return Error code
 */
binserde_error_t binserde_read_bytes(binserde_reader_t *reader,
                                     uint8_t **data,
                                     uint32_t *length);

/**
 * Write checksum (call after all data is written)
 * @param writer Writer context
 * @return Error code
 */
binserde_error_t binserde_write_checksum(binserde_writer_t *writer);

/**
 * Validate checksum (call after all data is read)
 * @param reader Reader context
 * @return Error code
 */
binserde_error_t binserde_validate_checksum(binserde_reader_t *reader);

/**
 * Get current writer position (bytes written)
 * @param writer Writer context
 * @return Number of bytes written
 */
size_t binserde_writer_position(const binserde_writer_t *writer);

/**
 * Get current reader position (bytes read)
 * @param reader Reader context
 * @return Number of bytes read
 */
size_t binserde_reader_position(const binserde_reader_t *reader);

/**
 * Get error string for error code
 * @param error Error code
 * @return Human-readable error message
 */
const char *binserde_error_string(binserde_error_t error);

/**
 * Validate schema against buffer
 * @param schema Schema definition
 * @param buffer Data buffer
 * @param size Buffer size
 * @return Error code
 */
binserde_error_t binserde_validate_schema(const binserde_schema_t *schema,
                                          const uint8_t *buffer,
                                          size_t size);

/**
 * File I/O: Write to file
 * @param filename File path
 * @param buffer Data to write
 * @param size Data size
 * @return Error code
 */
binserde_error_t binserde_write_file(const char *filename,
                                     const uint8_t *buffer,
                                     size_t size);

/**
 * File I/O: Read from file (allocates memory, caller must free)
 * @param filename File path
 * @param buffer Output: pointer to allocated buffer
 * @param size Output: buffer size
 * @return Error code
 */
binserde_error_t binserde_read_file(const char *filename,
                                    uint8_t **buffer,
                                    size_t *size);

#endif /* BINSERDE_H */