Skip to content

dtpackable

Facade for object serialization/deserialization via packing and unpacking binary data.

Please refer to dtvtable for more information on vtable dispatching.

The design pattern is for polymorphic objects that can serialize and deserialize their state to and from binary representations, enabling storage and transmission.

Mini-guide

  • For a class to implement this facade, it must register a dtpackable_vt_t vtable for its model number and implement the pack and unpack functions.
  • To call the facade functions, pass the handle to the function cast as dtpackable_handle.
  • Use the length query before packing to size buffers correctly.

Example

my_object_handle handle = obtain_your_object_handle_somehow();

// get the expected packed length
int32_t length = 0;
dterr_t* err = dtpackable_packx_length((dtpackable_handle)handle, &length);
if (err == NULL) {
    uint8_t* buffer = allocate_buffer(length);

    // pack the object into the buffer
    int32_t offset = 0;
    err = dtpackable_packx((dtpackable_handle)handle, buffer, &offset, length);
}

Data structures

dtpackable_handle

Opaque handle used for dispatch operations.

dtpackable_vt_t

Virtual table defining pack and unpack operations.

Members:

dtpackable_packx_length_fn packx_length Computes required packed length.
dtpackable_packx_fn packx Packs the object into a buffer.
dtpackable_unpackx_fn unpackx Unpacks the object from a buffer.
dtpackable_validate_unpacked_fn validate_unpacked Validates unpacked state.

Macros

DTPACKABLE_COMMON_MEMBERS

Defines common members required at the start of implementation structures.

DTPACKABLE_DECLARE_API

Declares the public API for a concrete implementation.

DTPACKABLE_INIT_VTABLE

Initializes a static vtable for a concrete implementation.

Functions

dtpackable_packx

Dispatches a pack operation using the handle model number.

Params:

dtpackable_handle handle Opaque handle identifying the object.
uint8_t* output Output buffer for packed data.
int32_t* offset In-out offset into the buffer.
int32_t length Total buffer length.

Return: dterr_t* Error object on failure, or null on success.

dtpackable_packx_length

Dispatches a packed length query using the handle model number.

Params:

dtpackable_handle handle Opaque handle identifying the object.
int32_t* length Receives the required packed length.

Return: dterr_t* Error object on failure, or null on success.

dtpackable_unpackx

Dispatches an unpack operation using the handle model number.

Params:

dtpackable_handle handle Opaque handle identifying the object.
const uint8_t* input Input buffer containing packed data.
int32_t* offset In-out offset into the buffer.
int32_t length Total buffer length.

Return: dterr_t* Error object on failure, or null on success.

dtpackable_validate_unpacked

Dispatches validation of unpacked state using the handle model number.

Params:

dtpackable_handle handle Opaque handle identifying the object.

Return: dterr_t* Error object on failure, or null on success.