dmi_string_set

Synopsis

#include <opendmi/utils/string.h>

#define DMI_STRING_BYTES_MAX 64

bool dmi_string_set(dmi_context_t *context, char **pstring, const char *value);
bool dmi_string_set_bytes(
        dmi_context_t *context,
        char         **pstring,
        const uint8_t *data,
        size_t         length,
        bool           trim);

const char *dmi_string_from_bytes(
        const uint8_t *data,
        size_t         length,
        char          *buffer,
        bool           trim);

Description

The dmi_string_set function copies value, frees the string held by the variable pstring points to, and stores the copy in the variable. If value is nullptr, the string is freed and the variable is set to nullptr.

The copy is made before the string is freed, so that value may be the string itself, and a failure leaves the variable as it was.

The caller is responsible for freeing the string with free() or dmi_free once it is no longer needed.

The dmi_string_from_bytes function copies the text the length bytes at data spell, e.g. a signature a structure holds, into buffer, and terminates it. The text is taken only if all the bytes are printable; with trim, the spaces are left out.

The dmi_string_set_bytes function does the same into a string of its own, which it stores the way dmi_string_set does. It is meant for the strings a structure spells in its own bytes, which the structure owns, see DMI_ATTRIBUTE_FLAG_OWNED in DMI_ATTRIBUTE: a handler sets them, and the library frees them as the structure is released.

Parameters

context: Context to raise the error on, or nullptr to report none.
pstring: Variable holding the string, which is either nullptr or allocated with malloc().
value: String to copy, or nullptr.
data: Bytes the text is taken from.
length: Number of the bytes, at most DMI_STRING_BYTES_MAX for dmi_string_set_bytes.
buffer: Buffer at least one byte longer than the bytes, which the text is copied into.
trim: Whether the spaces are left out.

Return value

The dmi_string_set and dmi_string_set_bytes functions return true on success, and false on failure. If the bytes are not all printable, or spell no text, dmi_string_set_bytes sets the string to nullptr, which is not a failure.

The dmi_string_from_bytes function returns the text in buffer, or nullptr if the bytes are not all printable or spell no text.

The bytes spell no text if there are none of them, or, with trim, if they are all spaces.

Errors

DMI_ERROR_ARGUMENT_NULL: Raised if pstring is nullptr, by dmi_string_set_bytes if data is nullptr while length is not zero, and by dmi_string_from_bytes if data or buffer is nullptr. The function takes no context, so its error reaches no error queue.
DMI_ERROR_ARGUMENT_INVALID: Raised by dmi_string_set_bytes if length exceeds DMI_STRING_BYTES_MAX.
DMI_ERROR_OUT_OF_MEMORY: Raised if memory is exhausted.

Example

char *vendor = nullptr;

if (!dmi_string_set(context, &vendor, "Acme"))
    return false;
...
dmi_string_set(context, &vendor, nullptr);