dmi_entity_create

Synopsis

#include <opendmi/entity.h>

dmi_entity_t *dmi_entity_create(
        dmi_context_t      *context,
        const dmi_buffer_t *buffer,
        size_t              offset);

Description

The dmi_entity_create function allocates a new entity descriptor and initializes it from the data of the structure, which begins at offset within buffer and runs to the end of the data the buffer holds. It parses the structure header, computes the total length (formatted area plus string set), and decodes the string table.

The structure refers to the data of the buffer in place rather than holding a copy of it, so the buffer is required to hold that data for as long as the entity lives. The structures read from a table all refer to the buffer of the table, which the context holds until it is closed.

The caller is responsible for destroying the returned entity descriptor with dmi_entity_destroy when it is no longer needed.

Parameters

context: DMI context handle.
buffer: Buffer holding the data of the structure.
offset: Offset the structure begins at within the buffer.

Return value

On success, returns a pointer to a newly allocated entity descriptor. On failure, returns nullptr (e.g. if context or buffer is nullptr, the structure length is invalid, or a memory allocation fails).

Errors

DMI_ERROR_ARGUMENT_NULL: Buffer is nullptr.
DMI_ERROR_ENTITY_LENGTH_INVALID: Length of the structure is shorter than its header.
DMI_ERROR_ENTITY_TRUNCATED: Structure, or the string set which follows it, runs past the end of the buffer.
DMI_ERROR_OUT_OF_MEMORY: Memory is exhausted.