dmi_encoder_initialize

Synopsis

#include <opendmi/encoder.h>

bool dmi_encoder_initialize(
        dmi_encoder_t      *encoder,
        dmi_buffer_t       *buffer,
        const dmi_entity_t *entity,
        dmi_encode_mode_t   mode,
        dmi_version_t       version);

Description

An encoder writes one structure back into the bytes it is made of: dmi_writer_t puts the bytes into a buffer, and the structure being encoded says what they are to carry. In the preserve mode a reader of the data the structure has been decoded from goes alongside, in step with what is written, so that the bytes the model does not hold are found at the position they are written at.

The dmi_encoder_initialize function sets the encoder up and writes the header of the structure. The structure is written into buffer, starting at the end of the data it holds, so that the structures of a table are written one after another. The length of the header is left for dmi_encoder_finish to fill in, once the length of the formatted area is known.

In the preserve mode, the strings of the structure are taken over as they are numbered, so that the fields referring to them keep their numbers, and the strings nothing refers to are kept too.

The encoder holds the strings of the structure, which are freed by dmi_encoder_finalize.

Parameters

encoder: Encoder to initialize.
buffer: Buffer to write the structure into.
entity: Structure to encode.
mode: How the bytes the model does not hold are written: DMI_ENCODE_MODE_PRESERVE takes them from the data the structure has been decoded from, so that encoding a structure which has not been changed gives back the very bytes it has been decoded from, and DMI_ENCODE_MODE_CANONICAL writes them the way the specification says they are, which is how a structure is repaired or built from scratch.
version: Version of the specification the canonical mode writes the structure for, which decides the groups of the fields it carries. Ignored in the preserve mode.

Return value

true on success, false otherwise.

Errors

DMI_ERROR_ARGUMENT_NULL: Encoder, buffer or entity is nullptr.
DMI_ERROR_OUT_OF_MEMORY: Buffers of the encoder cannot be allocated.