1697 lines
58 KiB
C
1697 lines
58 KiB
C
/*
|
|
* SPDX-License-Identifier: ISC
|
|
*
|
|
* Copyright (c) 2017-2021 Michael Drake <tlsa@netsurf-browser.org>
|
|
*/
|
|
|
|
/**
|
|
* \file
|
|
* \brief CYAML library public header.
|
|
*
|
|
* CYAML is a C library for parsing and serialising structured YAML documents.
|
|
*/
|
|
|
|
#ifndef CYAML_H
|
|
#define CYAML_H
|
|
|
|
#ifdef __cplusplus
|
|
extern "C"
|
|
{
|
|
#endif
|
|
|
|
#include <stdarg.h>
|
|
#include <stdint.h>
|
|
#include <stddef.h>
|
|
|
|
/**
|
|
* CYAML library version string.
|
|
*/
|
|
extern const char *cyaml_version_str;
|
|
|
|
/**
|
|
* CYAML library version number suitable for comparisons.
|
|
*
|
|
* Version number binary composition is `0bRUUUUUUUJJJJJJJJNNNNNNNNPPPPPPPP`.
|
|
*
|
|
* | Character | Meaning |
|
|
* | --------- | -------------------------------------- |
|
|
* | `R` | Release flag. If set, it's a release. |
|
|
* | `U` | Unused / reserved. |
|
|
* | `J` | Major component of version. |
|
|
* | `N` | Minor component of version. |
|
|
* | `P` | Patch component of version. |
|
|
*/
|
|
extern const uint32_t cyaml_version;
|
|
|
|
/**
|
|
* CYAML value types.
|
|
*
|
|
* These are the fundamental data types that apply to "values" in CYAML.
|
|
*
|
|
* CYAML "values" are represented in by \ref cyaml_schema_value.
|
|
*/
|
|
typedef enum cyaml_type {
|
|
CYAML_INT, /**< Value is a signed integer. */
|
|
CYAML_UINT, /**< Value is an unsigned signed integer. */
|
|
CYAML_BOOL, /**< Value is a boolean. */
|
|
/**
|
|
* Value is an enum. Values of this type require a string / value
|
|
* mapping array in the schema entry, to define the list of valid
|
|
* enum values.
|
|
*/
|
|
CYAML_ENUM,
|
|
/**
|
|
* Value is a flags bit field. Values of this type require a string /
|
|
* value list in the schema entry, to define the list of valid flag
|
|
* values. Each bit is a boolean flag. To store values of various
|
|
* bit sizes, use a \ref CYAML_BITFIELD instead.
|
|
*
|
|
* In the YAML, a \ref CYAML_FLAGS value must be presented as a
|
|
* sequence of strings.
|
|
*/
|
|
CYAML_FLAGS,
|
|
CYAML_FLOAT, /**< Value is floating point. */
|
|
CYAML_STRING, /**< Value is a string. */
|
|
/**
|
|
* Value is a mapping. Values of this type require mapping schema
|
|
* array in the schema entry.
|
|
*/
|
|
CYAML_MAPPING,
|
|
/**
|
|
* Value is a bit field. Values of this type require an array of value
|
|
* definitions in the schema entry. If the bit field is used to store
|
|
* only single-bit flags, it may be better to use \ref CYAML_FLAGS
|
|
* instead.
|
|
*
|
|
* In the YAML, a \ref CYAML_FLAGS value must be presented as a
|
|
* mapping of bit field entry names to their numerical values.
|
|
*/
|
|
CYAML_BITFIELD,
|
|
/**
|
|
* Value is a sequence. Values of this type must be the direct
|
|
* children of a mapping. They require:
|
|
*
|
|
* - A schema describing the type of the sequence entries.
|
|
* - Offset to the array entry count member in the mapping structure.
|
|
* - Size in bytes of the count member in the mapping structure.
|
|
* - The minimum and maximum number of sequence count entries.
|
|
* Set `max` to \ref CYAML_UNLIMITED to make array count
|
|
* unconstrained.
|
|
*/
|
|
CYAML_SEQUENCE,
|
|
/**
|
|
* Value is a **fixed length** sequence. It is similar to \ref
|
|
* CYAML_SEQUENCE, however:
|
|
*
|
|
* - Values of this type do not need to be direct children of a mapping.
|
|
* - The minimum and maximum entry count must be the same. If not
|
|
* \ref CYAML_ERR_SEQUENCE_FIXED_COUNT will be returned.
|
|
* - Unlike with \ref CYAML_SEQUENCE, where the min and max are limits,
|
|
* here they are the actual entry count.
|
|
* - Since values of this type represent a constant size array, the
|
|
* given entry count must not be \ref CYAML_UNLIMITED, because that
|
|
* would cause it to attempt a massive allocation, which on most
|
|
* systems would fail.
|
|
* - The offset and size of the count structure member is unused.
|
|
* Because the count is a schema-defined constant, it does not need
|
|
* to be recorded.
|
|
*/
|
|
CYAML_SEQUENCE_FIXED,
|
|
/**
|
|
* Value of this type is completely ignored. This is most useful for
|
|
* ignoring particular keys in a mapping, when the LivCYAML client has
|
|
* not set a configuration of \ref CYAML_CFG_IGNORE_UNKNOWN_KEYS.
|
|
*/
|
|
CYAML_IGNORE,
|
|
/**
|
|
* Count of the valid CYAML types. This value is **not a valid type**
|
|
* itself.
|
|
*/
|
|
CYAML__TYPE_COUNT,
|
|
} cyaml_type_e;
|
|
|
|
/**
|
|
* CYAML value flags.
|
|
*
|
|
* These may be bitwise-ORed together.
|
|
*/
|
|
typedef enum cyaml_flag {
|
|
CYAML_FLAG_DEFAULT = 0, /**< Default value flags (none set). */
|
|
CYAML_FLAG_OPTIONAL = (1 << 0), /**< Mapping field is optional. */
|
|
/**
|
|
* Value is a pointer to its type.
|
|
*
|
|
* With this there must be a non-NULL value. Consider using
|
|
* \ref CYAML_FLAG_POINTER_NULL or \ref CYAML_FLAG_POINTER_NULL_STR
|
|
* if you want to allow NULL values.
|
|
*/
|
|
CYAML_FLAG_POINTER = (1 << 1),
|
|
/**
|
|
* Permit `NULL` values for \ref CYAML_FLAG_POINTER types.
|
|
*
|
|
* An empty value in the YAML is loaded as a NULL pointer, and NULL
|
|
* pointers are saved in YAML as empty values.
|
|
*
|
|
* Note, when you set \ref CYAML_FLAG_POINTER_NULL, then
|
|
* \ref CYAML_FLAG_POINTER is set automatically.
|
|
*/
|
|
CYAML_FLAG_POINTER_NULL = (1 << 2) | CYAML_FLAG_POINTER,
|
|
/**
|
|
* Permit storage of `NULL` values as special NULL strings in YAML.
|
|
*
|
|
* This extends \ref CYAML_FLAG_POINTER_NULL, but in addition to
|
|
* treating empty values as NULL, any of the following are also treated
|
|
* as NULL:
|
|
*
|
|
* * `null`,
|
|
* * `Null`,
|
|
* * `NULL`,
|
|
* * `~`,
|
|
*
|
|
* Note that as a side effect, loading a \ref CYAML_STRING field with
|
|
* one of these values will not store the literal string, it will store
|
|
* NULL.
|
|
*
|
|
* When saving, a NULL value will be recorded in the YAML as `null`.
|
|
*
|
|
* Note, when you set \ref CYAML_FLAG_POINTER_NULL_STR, then both
|
|
* \ref CYAML_FLAG_POINTER and \ref CYAML_FLAG_POINTER_NULL are set
|
|
* automatically.
|
|
*/
|
|
CYAML_FLAG_POINTER_NULL_STR = (1 << 3) | CYAML_FLAG_POINTER_NULL,
|
|
/**
|
|
* Make value handling strict.
|
|
*
|
|
* For \ref CYAML_ENUM and \ref CYAML_FLAGS types, in strict mode
|
|
* the YAML must contain a matching string. Without strict, numerical
|
|
* values are also permitted.
|
|
*
|
|
* * For \ref CYAML_ENUM, the value becomes the value of the enum.
|
|
* The numerical value is treated as signed.
|
|
* * For \ref CYAML_FLAGS, the values are bitwise ORed together.
|
|
* The numerical values are treated as unsigned.
|
|
*
|
|
* For \ref CYAML_FLOAT types, in strict mode floating point values
|
|
* that would cause overflow or underflow are not permitted.
|
|
*/
|
|
CYAML_FLAG_STRICT = (1 << 4),
|
|
/**
|
|
* When saving, emit mapping / sequence value in block style.
|
|
*
|
|
* This can be used to override, for this value, any default style set
|
|
* in the \ref cyaml_cfg_flags CYAML behavioural configuration flags.
|
|
*
|
|
* \note This is ignored unless the value's type is \ref CYAML_MAPPING,
|
|
* \ref CYAML_SEQUENCE, or \ref CYAML_SEQUENCE_FIXED.
|
|
*
|
|
* \note If both \ref CYAML_FLAG_BLOCK and \ref CYAML_FLAG_FLOW are set,
|
|
* then block style takes precedence.
|
|
*
|
|
* \note If neither block nor flow style set either here, or in the
|
|
* \ref cyaml_cfg_flags CYAML behavioural configuration flags,
|
|
* then libyaml's default behaviour is used.
|
|
*/
|
|
CYAML_FLAG_BLOCK = (1 << 5),
|
|
/**
|
|
* When saving, emit mapping / sequence value in flow style.
|
|
*
|
|
* This can be used to override, for this value, any default style set
|
|
* in the \ref cyaml_cfg_flags CYAML behavioural configuration flags.
|
|
*
|
|
* \note This is ignored unless the value's type is \ref CYAML_MAPPING,
|
|
* \ref CYAML_SEQUENCE, or \ref CYAML_SEQUENCE_FIXED.
|
|
*
|
|
* \note If both \ref CYAML_FLAG_BLOCK and \ref CYAML_FLAG_FLOW are set,
|
|
* then block style takes precedence.
|
|
*
|
|
* \note If neither block nor flow style set either here, or in the
|
|
* \ref cyaml_cfg_flags CYAML behavioural configuration flags,
|
|
* then libyaml's default behaviour is used.
|
|
*/
|
|
CYAML_FLAG_FLOW = (1 << 6),
|
|
/**
|
|
* When comparing strings for this value, compare with case sensitivity.
|
|
*
|
|
* By default, strings are compared with case sensitivity.
|
|
* If \ref CYAML_CFG_CASE_INSENSITIVE is set, this can override
|
|
* the configured behaviour for this specific value.
|
|
*
|
|
* \note If both \ref CYAML_FLAG_CASE_SENSITIVE and
|
|
* \ref CYAML_FLAG_CASE_INSENSITIVE are set,
|
|
* then case insensitive takes precedence.
|
|
*
|
|
* \note This applies to values of types \ref CYAML_MAPPING,
|
|
* \ref CYAML_ENUM, and \ref CYAML_FLAGS. For mappings,
|
|
* it applies to matching of the mappings' keys. For
|
|
* enums and flags it applies to the comparison of
|
|
* \ref cyaml_strval strings.
|
|
*/
|
|
CYAML_FLAG_CASE_SENSITIVE = (1 << 7),
|
|
/**
|
|
* When comparing strings for this value, compare with case sensitivity.
|
|
*
|
|
* By default, strings are compared with case sensitivity.
|
|
* If \ref CYAML_CFG_CASE_INSENSITIVE is set, this can override
|
|
* the configured behaviour for this specific value.
|
|
*
|
|
* \note If both \ref CYAML_FLAG_CASE_SENSITIVE and
|
|
* \ref CYAML_FLAG_CASE_INSENSITIVE are set,
|
|
* then case insensitive takes precedence.
|
|
*
|
|
* \note This applies to values of types \ref CYAML_MAPPING,
|
|
* \ref CYAML_ENUM, and \ref CYAML_FLAGS. For mappings,
|
|
* it applies to matching of the mappings' keys. For
|
|
* enums and flags it applies to the comparison of
|
|
* \ref cyaml_strval strings.
|
|
*/
|
|
CYAML_FLAG_CASE_INSENSITIVE = (1 << 8),
|
|
/**
|
|
* When saving, emit scalar value with plain style (no quotes).
|
|
*
|
|
* \note This is ignored if the value is non-scaler.
|
|
*
|
|
* \note In cases where conflicting scalar style flags are set, the
|
|
* the one with the highest precedence is used. From lowest to
|
|
* highest precedence:
|
|
* \ref CYAML_FLAG_SCALAR_PLAIN,
|
|
* \ref CYAML_FLAG_SCALAR_FOLDED,
|
|
* \ref CYAML_FLAG_SCALAR_LITERAL,
|
|
* \ref CYAML_FLAG_SCALAR_QUOTE_SINGLE,
|
|
* \ref CYAML_FLAG_SCALAR_QUOTE_DOUBLE,
|
|
*
|
|
* If none of these are set, libyaml's default behaviour is used.
|
|
*/
|
|
CYAML_FLAG_SCALAR_PLAIN = (1 << 9),
|
|
/**
|
|
* When saving, emit scalar value with folded style:
|
|
*
|
|
* ```yaml
|
|
* string: >
|
|
* This string
|
|
* really has no line breaks!
|
|
* ```
|
|
*
|
|
* See the notes for \ref CYAML_FLAG_SCALAR_PLAIN for applicability
|
|
* and precedence.
|
|
*/
|
|
CYAML_FLAG_SCALAR_FOLDED = (1 << 10),
|
|
/**
|
|
* When saving, emit scalar value with literal style:
|
|
*
|
|
* ```yaml
|
|
* string: |
|
|
* This is a
|
|
* multi-line string!
|
|
* ```
|
|
*
|
|
* See the notes for \ref CYAML_FLAG_SCALAR_PLAIN for applicability
|
|
* and precedence.
|
|
*/
|
|
CYAML_FLAG_SCALAR_LITERAL = (1 << 11),
|
|
/**
|
|
* When saving, emit scalar value with single quotes (`'`).
|
|
*
|
|
* See the notes for \ref CYAML_FLAG_SCALAR_PLAIN for applicability
|
|
* and precedence.
|
|
*/
|
|
CYAML_FLAG_SCALAR_QUOTE_SINGLE = (1 << 12),
|
|
/**
|
|
* When saving, emit scalar value with double quotes (`"`).
|
|
*
|
|
* See the notes for \ref CYAML_FLAG_SCALAR_PLAIN for applicability
|
|
* and precedence.
|
|
*/
|
|
CYAML_FLAG_SCALAR_QUOTE_DOUBLE = (1 << 13),
|
|
} cyaml_flag_e;
|
|
|
|
/**
|
|
* Mapping between a string and a signed value.
|
|
*
|
|
* Used for \ref CYAML_ENUM and \ref CYAML_FLAGS types.
|
|
*/
|
|
typedef struct cyaml_strval {
|
|
const char *str; /**< String representing enum or flag value. */
|
|
int64_t val; /**< Value of given string. */
|
|
} cyaml_strval_t;
|
|
|
|
/**
|
|
* Bitfield value info.
|
|
*
|
|
* Used for \ref CYAML_BITFIELD type.
|
|
*/
|
|
typedef struct cyaml_bitdef {
|
|
const char *name; /**< String representing the value's name. */
|
|
uint8_t offset; /**< Bit offset to value in bit field. */
|
|
uint8_t bits; /**< Maximum bits available for value. */
|
|
} cyaml_bitdef_t;
|
|
|
|
/**
|
|
* Schema definition for a value.
|
|
*
|
|
* \note There are convenience macros for each of the types to assist in
|
|
* building a CYAML schema data structure for your YAML documents.
|
|
*
|
|
* This is the fundamental building block of CYAML schemas. The load, save and
|
|
* free functions take parameters of this type to explain what the top-level
|
|
* type of the YAML document should be.
|
|
*
|
|
* Values of type \ref CYAML_SEQUENCE and \ref CYAML_SEQUENCE_FIXED
|
|
* contain a reference to another \ref cyaml_schema_value representing
|
|
* the type of the entries of the sequence. For example, if you want
|
|
* a sequence of integers, you'd have a \ref cyaml_schema_value for the
|
|
* for the sequence value type, and another for the integer value type.
|
|
*
|
|
* Values of type \ref CYAML_MAPPING contain an array of \ref cyaml_schema_field
|
|
* entries, defining the YAML keys allowed by the mapping. Each field contains
|
|
* a \ref cyaml_schema_value representing the schema for the value.
|
|
*/
|
|
typedef struct cyaml_schema_value {
|
|
/**
|
|
* The type of the value defined by this schema entry.
|
|
*/
|
|
enum cyaml_type type;
|
|
/** Flags indicating value's characteristics. */
|
|
enum cyaml_flag flags;
|
|
/**
|
|
* Size of the value's client data type in bytes.
|
|
*
|
|
* For example, `short` `int`, `long`, `int8_t`, etc are all signed
|
|
* integer types, so they would have the type \ref CYAML_INT,
|
|
* however, they have different sizes.
|
|
*/
|
|
uint32_t data_size;
|
|
/** Anonymous union containing type-specific attributes. */
|
|
union {
|
|
/** \ref CYAML_STRING type-specific schema data. */
|
|
struct {
|
|
/**
|
|
* Minimum string length (bytes).
|
|
*
|
|
* \note Excludes trailing NUL.
|
|
*/
|
|
uint32_t min;
|
|
/**
|
|
* Maximum string length (bytes).
|
|
*
|
|
* \note Excludes trailing NULL, so for character array
|
|
* strings (rather than pointer strings), this
|
|
* must be no more than `data_size - 1`.
|
|
*/
|
|
uint32_t max;
|
|
} string;
|
|
/** \ref CYAML_MAPPING type-specific schema data. */
|
|
struct {
|
|
/**
|
|
* Array of cyaml mapping field schema definitions.
|
|
*
|
|
* The array must be terminated by an entry with a
|
|
* NULL key. See \ref cyaml_schema_field_t
|
|
* and \ref CYAML_FIELD_END for more info.
|
|
*/
|
|
const struct cyaml_schema_field *fields;
|
|
} mapping;
|
|
/** \ref CYAML_BITFIELD type-specific schema data. */
|
|
struct {
|
|
/** Array of bit definitions for the bit field. */
|
|
const struct cyaml_bitdef *bitdefs;
|
|
/** Entry count for bitdefs array. */
|
|
uint32_t count;
|
|
} bitfield;
|
|
/**
|
|
* \ref CYAML_SEQUENCE and \ref CYAML_SEQUENCE_FIXED
|
|
* type-specific schema data.
|
|
*/
|
|
struct {
|
|
/**
|
|
* Schema definition for the type of the entries in the
|
|
* sequence.
|
|
*
|
|
* All of a sequence's entries must be of the same
|
|
* type, and a sequence can not have an entry type of
|
|
* type \ref CYAML_SEQUENCE (although \ref
|
|
* CYAML_SEQUENCE_FIXED is allowed). That is, you
|
|
* can't have a sequence of variable-length sequences.
|
|
*/
|
|
const struct cyaml_schema_value *entry;
|
|
/**
|
|
* Minimum number of sequence entries.
|
|
*
|
|
* \note min and max must be the same for \ref
|
|
* CYAML_SEQUENCE_FIXED.
|
|
*/
|
|
uint32_t min;
|
|
/**
|
|
* Maximum number of sequence entries.
|
|
*
|
|
* \note min and max must be the same for \ref
|
|
* CYAML_SEQUENCE_FIXED.
|
|
*/
|
|
uint32_t max;
|
|
} sequence;
|
|
/**
|
|
* \ref CYAML_ENUM and \ref CYAML_FLAGS type-specific schema
|
|
* data.
|
|
*/
|
|
struct {
|
|
/** Array of string / value mappings defining enum. */
|
|
const cyaml_strval_t *strings;
|
|
/** Entry count for strings array. */
|
|
uint32_t count;
|
|
} enumeration;
|
|
};
|
|
} cyaml_schema_value_t;
|
|
|
|
/**
|
|
* Schema definition entry for mapping fields.
|
|
*
|
|
* YAML mappings are key:value pairs. CYAML only supports scalar mapping keys,
|
|
* i.e. the keys must be strings. Each mapping field schema contains a
|
|
* \ref cyaml_schema_value to define field's value.
|
|
*
|
|
* The schema for mappings is composed of an array of entries of this
|
|
* data structure. It specifies the name of the key, and the type of
|
|
* the value. It also specifies the offset into the data at which value
|
|
* data should be placed. The array is terminated by an entry with a NULL key.
|
|
*/
|
|
typedef struct cyaml_schema_field {
|
|
/**
|
|
* String for YAML mapping key that his schema entry describes,
|
|
* or NULL to indicated the end of an array of \ref cyaml_schema_field
|
|
* entries.
|
|
*/
|
|
const char *key;
|
|
/**
|
|
* Offset in data structure at which the value for this key should
|
|
* be placed / read from.
|
|
*/
|
|
uint32_t data_offset;
|
|
/**
|
|
* \ref CYAML_SEQUENCE only: Offset to sequence
|
|
* entry count member in mapping's data structure.
|
|
*/
|
|
uint32_t count_offset;
|
|
/**
|
|
* \ref CYAML_SEQUENCE only: Size in bytes of sequence
|
|
* entry count member in mapping's data structure.
|
|
*/
|
|
uint8_t count_size;
|
|
/**
|
|
* Defines the schema for the mapping field's value.
|
|
*/
|
|
struct cyaml_schema_value value;
|
|
} cyaml_schema_field_t;
|
|
|
|
/**
|
|
* CYAML behavioural configuration flags for clients
|
|
*
|
|
* These may be bitwise-ORed together.
|
|
*/
|
|
typedef enum cyaml_cfg_flags {
|
|
/**
|
|
* This indicates CYAML's default behaviour.
|
|
*/
|
|
CYAML_CFG_DEFAULT = 0,
|
|
/**
|
|
* When set, unknown mapping keys are ignored when loading YAML.
|
|
* Without this flag set, CYAML's default behaviour is to return
|
|
* with the error \ref CYAML_ERR_INVALID_KEY.
|
|
*/
|
|
CYAML_CFG_IGNORE_UNKNOWN_KEYS = (1 << 0),
|
|
/**
|
|
* When saving, emit mapping / sequence values in block style.
|
|
*
|
|
* This setting can be overridden for specific values using schema
|
|
* value flags (\ref cyaml_flag).
|
|
*
|
|
* \note This only applies to values of type \ref CYAML_MAPPING,
|
|
* \ref CYAML_SEQUENCE, or \ref CYAML_SEQUENCE_FIXED.
|
|
*
|
|
* \note If both \ref CYAML_CFG_STYLE_BLOCK and
|
|
* \ref CYAML_CFG_STYLE_FLOW are set, then block style takes
|
|
* precedence.
|
|
*/
|
|
CYAML_CFG_STYLE_BLOCK = (1 << 1),
|
|
/**
|
|
* When saving, emit mapping / sequence values in flow style.
|
|
*
|
|
* This setting can be overridden for specific values using schema
|
|
* value flags (\ref cyaml_flag).
|
|
*
|
|
* \note This only applies to values of type \ref CYAML_MAPPING,
|
|
* \ref CYAML_SEQUENCE, or \ref CYAML_SEQUENCE_FIXED.
|
|
*
|
|
* \note If both \ref CYAML_CFG_STYLE_BLOCK and
|
|
* \ref CYAML_CFG_STYLE_FLOW are set, then block style takes
|
|
* precedence.
|
|
*/
|
|
CYAML_CFG_STYLE_FLOW = (1 << 2),
|
|
/**
|
|
* When saving, emit "---" at document start and "..." at document end.
|
|
*
|
|
* If this flag isn't set, these document delimiting marks will not
|
|
* be emitted.
|
|
*/
|
|
CYAML_CFG_DOCUMENT_DELIM = (1 << 3),
|
|
/**
|
|
* When comparing strings, compare without case sensitivity.
|
|
*
|
|
* By default, strings are compared with case sensitivity.
|
|
*/
|
|
CYAML_CFG_CASE_INSENSITIVE = (1 << 4),
|
|
/**
|
|
* When loading, don't allow YAML aliases in the document.
|
|
*
|
|
* If this option is enabled, anchors will be ignored, and the
|
|
* error code \ref CYAML_ERR_ALIAS will be returned if an alias
|
|
* is encountered.
|
|
*
|
|
* Setting this removes the overhead of recording anchors, so
|
|
* it may be worth setting if aliases are not required, and
|
|
* memory is constrained.
|
|
*/
|
|
CYAML_CFG_NO_ALIAS = (1 << 5),
|
|
/**
|
|
* Log any ignored mapping keys at \ref CYAML_LOG_WARNING level.
|
|
*/
|
|
CYAML_CFG_IGNORED_KEY_WARNING = (1 << 6),
|
|
} cyaml_cfg_flags_t;
|
|
|
|
/**
|
|
* CYAML function return codes indicating success or reason for failure.
|
|
*
|
|
* Use \ref cyaml_strerror() to convert an error code to a human-readable
|
|
* string.
|
|
*/
|
|
typedef enum cyaml_err {
|
|
CYAML_OK, /**< Success. */
|
|
CYAML_ERR_OOM, /**< Memory allocation failed. */
|
|
CYAML_ERR_ALIAS, /**< See \ref CYAML_CFG_NO_ALIAS. */
|
|
CYAML_ERR_FILE_OPEN, /**< Failed to open file. */
|
|
CYAML_ERR_INVALID_KEY, /**< Mapping key rejected by schema. */
|
|
CYAML_ERR_INVALID_VALUE, /**< Value rejected by schema. */
|
|
CYAML_ERR_INVALID_ALIAS, /**< No anchor found for alias. */
|
|
CYAML_ERR_INTERNAL_ERROR, /**< Internal error in LibCYAML. */
|
|
CYAML_ERR_UNEXPECTED_EVENT, /**< YAML event rejected by schema. */
|
|
CYAML_ERR_STRING_LENGTH_MIN, /**< String length too short. */
|
|
CYAML_ERR_STRING_LENGTH_MAX, /**< String length too long. */
|
|
CYAML_ERR_INVALID_DATA_SIZE, /**< Value's data size unsupported. */
|
|
CYAML_ERR_TOP_LEVEL_NON_PTR, /**< Top level type must be pointer. */
|
|
CYAML_ERR_BAD_TYPE_IN_SCHEMA, /**< Schema contains invalid type. */
|
|
CYAML_ERR_BAD_MIN_MAX_SCHEMA, /**< Schema minimum exceeds maximum. */
|
|
CYAML_ERR_BAD_PARAM_SEQ_COUNT, /**< Bad seq_count param for schema. */
|
|
CYAML_ERR_BAD_PARAM_NULL_DATA, /**< Client gave NULL data argument. */
|
|
CYAML_ERR_BAD_BITVAL_IN_SCHEMA, /**< Bit value beyond bit field size. */
|
|
CYAML_ERR_SEQUENCE_ENTRIES_MIN, /**< Too few sequence entries. */
|
|
CYAML_ERR_SEQUENCE_ENTRIES_MAX, /**< Too many sequence entries. */
|
|
CYAML_ERR_SEQUENCE_FIXED_COUNT, /**< Mismatch between min and max. */
|
|
CYAML_ERR_SEQUENCE_IN_SEQUENCE, /**< Non-fixed sequence in sequence. */
|
|
CYAML_ERR_MAPPING_FIELD_MISSING, /**< Required mapping field missing. */
|
|
CYAML_ERR_BAD_CONFIG_NULL_MEMFN, /**< Client gave NULL mem function. */
|
|
CYAML_ERR_BAD_PARAM_NULL_CONFIG, /**< Client gave NULL config arg. */
|
|
CYAML_ERR_BAD_PARAM_NULL_SCHEMA, /**< Client gave NULL schema arg. */
|
|
CYAML_ERR_LIBYAML_EMITTER_INIT, /**< Failed to initialise libyaml. */
|
|
CYAML_ERR_LIBYAML_PARSER_INIT, /**< Failed to initialise libyaml. */
|
|
CYAML_ERR_LIBYAML_EVENT_INIT, /**< Failed to initialise libyaml. */
|
|
CYAML_ERR_LIBYAML_EMITTER, /**< Error inside libyaml emitter. */
|
|
CYAML_ERR_LIBYAML_PARSER, /**< Error inside libyaml parser. */
|
|
CYAML_ERR__COUNT, /**< Count of CYAML return codes.
|
|
* This is **not a valid return
|
|
* code** itself.
|
|
*/
|
|
} cyaml_err_t;
|
|
|
|
/**
|
|
* Value schema helper macro for values with \ref CYAML_INT type.
|
|
*
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _type The C type for this value.
|
|
*/
|
|
#define CYAML_VALUE_INT( \
|
|
_flags, _type) \
|
|
.type = CYAML_INT, \
|
|
.flags = (enum cyaml_flag)(_flags), \
|
|
.data_size = sizeof(_type)
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_INT type.
|
|
*
|
|
* Use this for integers contained in structs.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
*/
|
|
#define CYAML_FIELD_INT( \
|
|
_key, _flags, _structure, _member) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_INT(((_flags) & (~CYAML_FLAG_POINTER)), \
|
|
(((_structure *)NULL)->_member)), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_INT type.
|
|
*
|
|
* Use this for pointers to integers.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
*/
|
|
#define CYAML_FIELD_INT_PTR( \
|
|
_key, _flags, _structure, _member) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_INT(((_flags) | CYAML_FLAG_POINTER), \
|
|
(*(((_structure *)NULL)->_member))), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Value schema helper macro for values with \ref CYAML_UINT type.
|
|
*
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _type The C type for this value.
|
|
*/
|
|
#define CYAML_VALUE_UINT( \
|
|
_flags, _type) \
|
|
.type = CYAML_UINT, \
|
|
.flags = (enum cyaml_flag)(_flags), \
|
|
.data_size = sizeof(_type)
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_UINT type.
|
|
*
|
|
* Use this for unsigned integers contained in structs.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
*/
|
|
#define CYAML_FIELD_UINT( \
|
|
_key, _flags, _structure, _member) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_UINT(((_flags) & (~CYAML_FLAG_POINTER)), \
|
|
(((_structure *)NULL)->_member)), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_UINT type.
|
|
*
|
|
* Use this for pointers to unsigned integers.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
*/
|
|
#define CYAML_FIELD_UINT_PTR( \
|
|
_key, _flags, _structure, _member) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_UINT(((_flags) | CYAML_FLAG_POINTER), \
|
|
(*(((_structure *)NULL)->_member))), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Value schema helper macro for values with \ref CYAML_BOOL type.
|
|
*
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _type The C type for this value.
|
|
*/
|
|
#define CYAML_VALUE_BOOL( \
|
|
_flags, _type) \
|
|
.type = CYAML_BOOL, \
|
|
.flags = (enum cyaml_flag)(_flags), \
|
|
.data_size = sizeof(_type)
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_BOOL type.
|
|
*
|
|
* Use this for boolean types contained in structs.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
*/
|
|
#define CYAML_FIELD_BOOL( \
|
|
_key, _flags, _structure, _member) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_BOOL(((_flags) & (~CYAML_FLAG_POINTER)), \
|
|
(((_structure *)NULL)->_member)), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_BOOL type.
|
|
*
|
|
* Use this for pointers to boolean types.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
*/
|
|
#define CYAML_FIELD_BOOL_PTR( \
|
|
_key, _flags, _structure, _member) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_BOOL(((_flags) | CYAML_FLAG_POINTER), \
|
|
(*(((_structure *)NULL)->_member))), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Value schema helper macro for values with \ref CYAML_ENUM type.
|
|
*
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _type The C type for this value.
|
|
* \param[in] _strings Array of string data for enumeration values.
|
|
* \param[in] _strings_count Number of entries in _strings.
|
|
*/
|
|
#define CYAML_VALUE_ENUM( \
|
|
_flags, _type, _strings, _strings_count) \
|
|
.type = CYAML_ENUM, \
|
|
.flags = (enum cyaml_flag)(_flags), \
|
|
.data_size = sizeof(_type), \
|
|
.enumeration = { \
|
|
.strings = _strings, \
|
|
.count = _strings_count, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_ENUM type.
|
|
*
|
|
* Use this for enumerated types contained in structs.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
* \param[in] _strings Array of string data for enumeration values.
|
|
* \param[in] _strings_count Number of entries in _strings.
|
|
*/
|
|
#define CYAML_FIELD_ENUM( \
|
|
_key, _flags, _structure, _member, _strings, _strings_count) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_ENUM(((_flags) & (~CYAML_FLAG_POINTER)), \
|
|
(((_structure *)NULL)->_member), \
|
|
_strings, _strings_count), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_ENUM type.
|
|
*
|
|
* Use this for pointers to enumerated types.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
* \param[in] _strings Array of string data for enumeration values.
|
|
* \param[in] _strings_count Number of entries in _strings.
|
|
*/
|
|
#define CYAML_FIELD_ENUM_PTR( \
|
|
_key, _flags, _structure, _member, _strings, _strings_count) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_ENUM(((_flags) | CYAML_FLAG_POINTER), \
|
|
(*(((_structure *)NULL)->_member)), \
|
|
_strings, _strings_count), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Value schema helper macro for values with \ref CYAML_FLAGS type.
|
|
*
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _type The C type for this value.
|
|
* \param[in] _strings Array of string data for flag values.
|
|
* \param[in] _strings_count Number of entries in _strings.
|
|
*/
|
|
#define CYAML_VALUE_FLAGS( \
|
|
_flags, _type, _strings, _strings_count) \
|
|
.type = CYAML_FLAGS, \
|
|
.flags = (enum cyaml_flag)(_flags), \
|
|
.data_size = sizeof(_type), \
|
|
.enumeration = { \
|
|
.strings = _strings, \
|
|
.count = _strings_count, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_FLAGS type.
|
|
*
|
|
* Use this for flag types contained in structs.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
* \param[in] _strings Array of string data for flag values.
|
|
* \param[in] _strings_count Number of entries in _strings.
|
|
*/
|
|
#define CYAML_FIELD_FLAGS( \
|
|
_key, _flags, _structure, _member, _strings, _strings_count) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_FLAGS(((_flags) & (~CYAML_FLAG_POINTER)), \
|
|
(((_structure *)NULL)->_member), \
|
|
_strings, _strings_count), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_FLAGS type.
|
|
*
|
|
* Use this for pointers to flag types.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
* \param[in] _strings Array of string data for flag values.
|
|
* \param[in] _strings_count Number of entries in _strings.
|
|
*/
|
|
#define CYAML_FIELD_FLAGS_PTR( \
|
|
_key, _flags, _structure, _member, _strings, _strings_count) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_FLAGS(((_flags) | CYAML_FLAG_POINTER), \
|
|
(*(((_structure *)NULL)->_member)), \
|
|
_strings, _strings_count), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Value schema helper macro for values with \ref CYAML_BITFIELD type.
|
|
*
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _type The C type for this value.
|
|
* \param[in] _bitvals Array of bit field value data for the bit field.
|
|
* \param[in] _bitvals_count Number of entries in _bitvals.
|
|
*/
|
|
#define CYAML_VALUE_BITFIELD( \
|
|
_flags, _type, _bitvals, _bitvals_count) \
|
|
.type = CYAML_BITFIELD, \
|
|
.flags = (enum cyaml_flag)(_flags), \
|
|
.data_size = sizeof(_type), \
|
|
.bitfield = { \
|
|
.bitdefs = _bitvals, \
|
|
.count = _bitvals_count, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_BITFIELD type.
|
|
*
|
|
* Use this for bit field types contained in structs.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
* \param[in] _bitvals Array of bit field value data for the bit field.
|
|
* \param[in] _bitvals_count Number of entries in _bitvals.
|
|
*/
|
|
#define CYAML_FIELD_BITFIELD( \
|
|
_key, _flags, _structure, _member, _bitvals, _bitvals_count) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_BITFIELD(((_flags) & (~CYAML_FLAG_POINTER)), \
|
|
(((_structure *)NULL)->_member), \
|
|
_bitvals, _bitvals_count), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_BITFIELD type.
|
|
*
|
|
* Use this for pointers to bit field types.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
* \param[in] _bitvals Array of bit field value data for the bit field.
|
|
* \param[in] _bitvals_count Number of entries in _bitvals.
|
|
*/
|
|
#define CYAML_FIELD_BITFIELD_PTR( \
|
|
_key, _flags, _structure, _member, _bitvals, _bitvals_count) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_BITFIELD(((_flags) | CYAML_FLAG_POINTER), \
|
|
(*(((_structure *)NULL)->_member)), \
|
|
_bitvals, _bitvals_count), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Value schema helper macro for values with \ref CYAML_FLOAT type.
|
|
*
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _type The C type for this value.
|
|
*/
|
|
#define CYAML_VALUE_FLOAT( \
|
|
_flags, _type) \
|
|
.type = CYAML_FLOAT, \
|
|
.flags = (enum cyaml_flag)(_flags), \
|
|
.data_size = sizeof(_type)
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_FLOAT type.
|
|
*
|
|
* Use this for floating point types contained in structs.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
*/
|
|
#define CYAML_FIELD_FLOAT( \
|
|
_key, _flags, _structure, _member) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_FLOAT(((_flags) & (~CYAML_FLAG_POINTER)), \
|
|
(((_structure *)NULL)->_member)), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_FLOAT type.
|
|
*
|
|
* Use this for pointers to floating point types.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
*/
|
|
#define CYAML_FIELD_FLOAT_PTR( \
|
|
_key, _flags, _structure, _member) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_FLOAT(((_flags) | CYAML_FLAG_POINTER), \
|
|
(*(((_structure *)NULL)->_member))), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Value schema helper macro for values with \ref CYAML_STRING type.
|
|
*
|
|
* \note If the string is an array (`char str[N];`) then the \ref
|
|
* CYAML_FLAG_POINTER flag must **not** be set, and the max
|
|
* length must be no more than `N-1`.
|
|
*
|
|
* If the string is a pointer (`char *str;`), then the \ref
|
|
* CYAML_FLAG_POINTER flag **must be set**.
|
|
*
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _type The C type for this value.
|
|
* \param[in] _min Minimum string length in bytes.
|
|
* Excludes trailing '\0'.
|
|
* \param[in] _max The C type for this value.
|
|
* Excludes trailing '\0'.
|
|
*/
|
|
#define CYAML_VALUE_STRING( \
|
|
_flags, _type, _min, _max) \
|
|
.type = CYAML_STRING, \
|
|
.flags = (enum cyaml_flag)(_flags), \
|
|
.data_size = sizeof(_type), \
|
|
.string = { \
|
|
.min = _min, \
|
|
.max = _max, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_STRING type.
|
|
*
|
|
* Use this for fields with C array type, e.g. `char str[N];`. This fills the
|
|
* maximum string length (`N-1`) out automatically.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
* \param[in] _min Minimum string length in bytes. Excludes '\0'.
|
|
*/
|
|
#define CYAML_FIELD_STRING( \
|
|
_key, _flags, _structure, _member, _min) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_STRING(((_flags) & (~CYAML_FLAG_POINTER)), \
|
|
(((_structure *)NULL)->_member), _min, \
|
|
sizeof(((_structure *)NULL)->_member) - 1), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_STRING type.
|
|
*
|
|
* Use this for fields with C pointer type, e.g. `char *str;`. This creates
|
|
* a separate allocation for the string data, and fills in the pointer.
|
|
*
|
|
* Use `0` for _min and \ref CYAML_UNLIMITED for _max for unconstrained string
|
|
* lengths.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
* \param[in] _min Minimum string length in bytes. Excludes '\0'.
|
|
* \param[in] _max Maximum string length in bytes. Excludes '\0'.
|
|
*/
|
|
#define CYAML_FIELD_STRING_PTR( \
|
|
_key, _flags, _structure, _member, _min, _max) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_STRING(((_flags) | CYAML_FLAG_POINTER), \
|
|
(((_structure *)NULL)->_member), \
|
|
_min, _max), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Value schema helper macro for values with \ref CYAML_MAPPING type.
|
|
*
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _type The C type of structure corresponding to mapping.
|
|
* \param[in] _fields Pointer to mapping fields schema array.
|
|
*/
|
|
#define CYAML_VALUE_MAPPING( \
|
|
_flags, _type, _fields) \
|
|
.type = CYAML_MAPPING, \
|
|
.flags = (enum cyaml_flag)(_flags), \
|
|
.data_size = sizeof(_type), \
|
|
.mapping = { \
|
|
.fields = _fields, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_MAPPING type.
|
|
*
|
|
* Use this for structures contained within other structures.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the containing mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
* \param[in] _fields Pointer to mapping fields schema array.
|
|
*/
|
|
#define CYAML_FIELD_MAPPING( \
|
|
_key, _flags, _structure, _member, _fields) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_MAPPING(((_flags) & (~CYAML_FLAG_POINTER)), \
|
|
(((_structure *)NULL)->_member), _fields), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_MAPPING type.
|
|
*
|
|
* Use this for pointers to structures.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the containing mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
* \param[in] _fields Pointer to mapping fields schema array.
|
|
*/
|
|
#define CYAML_FIELD_MAPPING_PTR( \
|
|
_key, _flags, _structure, _member, _fields) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_MAPPING(((_flags) | CYAML_FLAG_POINTER), \
|
|
(*(((_structure *)NULL)->_member)), _fields), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Value schema helper macro for values with \ref CYAML_SEQUENCE type.
|
|
*
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _type The C type of sequence **entries**.
|
|
* \param[in] _entry Pointer to schema for the **entries** in sequence.
|
|
* \param[in] _min Minimum number of sequence entries required.
|
|
* \param[in] _max Maximum number of sequence entries required.
|
|
*/
|
|
#define CYAML_VALUE_SEQUENCE( \
|
|
_flags, _type, _entry, _min, _max) \
|
|
.type = CYAML_SEQUENCE, \
|
|
.flags = (enum cyaml_flag)(_flags), \
|
|
.data_size = sizeof(_type), \
|
|
.sequence = { \
|
|
.entry = _entry, \
|
|
.min = _min, \
|
|
.max = _max, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_SEQUENCE type.
|
|
*
|
|
* To use this, there must be a member in {_structure} called "{_member}_count",
|
|
* for storing the number of entries in the sequence.
|
|
*
|
|
* For example, for the following structure:
|
|
*
|
|
* ```
|
|
* struct my_structure {
|
|
* unsigned *my_sequence;
|
|
* unsigned my_sequence_count;
|
|
* };
|
|
* ```
|
|
*
|
|
* Pass the following as parameters:
|
|
*
|
|
* | Parameter | Value |
|
|
* | ---------- | --------------------- |
|
|
* | _structure | `struct my_structure` |
|
|
* | _member | `my_sequence` |
|
|
*
|
|
* If you want to call the structure member for storing the sequence entry
|
|
* count something else, then use \ref CYAML_FIELD_SEQUENCE_COUNT instead.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
* \param[in] _entry Pointer to schema for the **entries** in sequence.
|
|
* \param[in] _min Minimum number of sequence entries required.
|
|
* \param[in] _max Maximum number of sequence entries required.
|
|
*/
|
|
#define CYAML_FIELD_SEQUENCE( \
|
|
_key, _flags, _structure, _member, _entry, _min, _max) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.count_offset = offsetof(_structure, _member ## _count), \
|
|
.count_size = sizeof(((_structure *)NULL)->_member ## _count), \
|
|
.value = { \
|
|
CYAML_VALUE_SEQUENCE((_flags), \
|
|
(*(((_structure *)NULL)->_member)), \
|
|
_entry, _min, _max), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_SEQUENCE type.
|
|
*
|
|
* Compared to .\ref CYAML_FIELD_SEQUENCE, this macro takes an extra `_count`
|
|
* parameter, allowing the structure member name for the sequence entry count
|
|
* to be provided explicitly.
|
|
*
|
|
* For example, for the following structure:
|
|
*
|
|
* ```
|
|
* struct my_structure {
|
|
* unsigned *things;
|
|
* unsigned n_things;
|
|
* };
|
|
* ```
|
|
*
|
|
* Pass the following as parameters:
|
|
*
|
|
* | Parameter | Value |
|
|
* | ---------- | --------------------- |
|
|
* | _structure | `struct my_structure` |
|
|
* | _member | `things` |
|
|
* | _count | `n_things` |
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
* \param[in] _count The member in _structure for this sequence's
|
|
* entry count.
|
|
* \param[in] _entry Pointer to schema for the **entries** in sequence.
|
|
* \param[in] _min Minimum number of sequence entries required.
|
|
* \param[in] _max Maximum number of sequence entries required.
|
|
*/
|
|
#define CYAML_FIELD_SEQUENCE_COUNT( \
|
|
_key, _flags, _structure, _member, _count, _entry, _min, _max) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.count_offset = offsetof(_structure, _count), \
|
|
.count_size = sizeof(((_structure *)NULL)->_count), \
|
|
.value = { \
|
|
CYAML_VALUE_SEQUENCE((_flags), \
|
|
(*(((_structure *)NULL)->_member)), \
|
|
_entry, _min, _max), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Value schema helper macro for values with \ref CYAML_SEQUENCE_FIXED type.
|
|
*
|
|
* Note that since this is a fixed size sequence, it must not be used with an
|
|
* excessive entry count. For example, passing \ref CYAML_UNLIMITED as the count
|
|
* to a \ref CYAML_SEQUENCE_FIXED with the \ref CYAML_FLAG_POINTER flag would
|
|
* cause an enormous allocation, which would fail on many systems.
|
|
*
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _type The C type of sequence **entries**.
|
|
* \param[in] _entry Pointer to schema for the **entries** in sequence.
|
|
* \param[in] _count Number of sequence entries required.
|
|
*/
|
|
#define CYAML_VALUE_SEQUENCE_FIXED( \
|
|
_flags, _type, _entry, _count) \
|
|
.type = CYAML_SEQUENCE_FIXED, \
|
|
.flags = (enum cyaml_flag)(_flags), \
|
|
.data_size = sizeof(_type), \
|
|
.sequence = { \
|
|
.entry = _entry, \
|
|
.min = _count, \
|
|
.max = _count, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_SEQUENCE_FIXED type.
|
|
*
|
|
* Note that since this is a fixed size sequence, it must not be used with an
|
|
* excessive entry count. For example, passing \ref CYAML_UNLIMITED as the count
|
|
* to a \ref CYAML_SEQUENCE_FIXED with the \ref CYAML_FLAG_POINTER flag would
|
|
* cause an enormous allocation, which would fail on many systems.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key for this value.
|
|
* \param[in] _flags Any behavioural flags relevant to this value.
|
|
* \param[in] _structure The structure corresponding to the mapping.
|
|
* \param[in] _member The member in _structure for this mapping value.
|
|
* \param[in] _entry Pointer to schema for the **entries** in sequence.
|
|
* \param[in] _count Number of sequence entries required.
|
|
*/
|
|
#define CYAML_FIELD_SEQUENCE_FIXED( \
|
|
_key, _flags, _structure, _member, _entry, _count) \
|
|
{ \
|
|
.key = _key, \
|
|
.data_offset = offsetof(_structure, _member), \
|
|
.value = { \
|
|
CYAML_VALUE_SEQUENCE_FIXED((_flags), \
|
|
(*(((_structure *)NULL)->_member)), \
|
|
_entry, _count), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for keys with \ref CYAML_IGNORE type.
|
|
*
|
|
* \param[in] _key String defining the YAML mapping key to ignore.
|
|
* \param[in] _flags Any behavioural flags relevant to this key.
|
|
*/
|
|
#define CYAML_FIELD_IGNORE( \
|
|
_key, _flags) \
|
|
{ \
|
|
.key = _key, \
|
|
.value = { \
|
|
.type = CYAML_IGNORE, \
|
|
.flags = (_flags), \
|
|
}, \
|
|
}
|
|
|
|
/**
|
|
* Mapping schema helper macro for terminating an array of mapping fields.
|
|
*
|
|
* CYAML mapping schemas are formed from an array of \ref cyaml_schema_field
|
|
* entries, and an entry with a NULL key indicates the end of the array.
|
|
*/
|
|
#define CYAML_FIELD_END { .key = NULL }
|
|
|
|
/**
|
|
* Identifies that a \ref CYAML_SEQUENCE has unconstrained maximum entry
|
|
* count.
|
|
*/
|
|
#define CYAML_UNLIMITED 0xffffffff
|
|
|
|
/**
|
|
* Helper macro for counting array elements.
|
|
*
|
|
* \note Don't use this macro on pointers.
|
|
*
|
|
* \param[in] _a A C array.
|
|
* \return Array element count.
|
|
*/
|
|
#define CYAML_ARRAY_LEN(_a) ((sizeof(_a)) / (sizeof(_a[0])))
|
|
|
|
/**
|
|
* Data loaded or saved by CYAML has this type. CYAML schemas are used
|
|
* to describe the data contained.
|
|
*/
|
|
typedef void cyaml_data_t;
|
|
|
|
/** CYAML logging levels. */
|
|
typedef enum cyaml_log_e {
|
|
CYAML_LOG_DEBUG, /**< Debug level logging. */
|
|
CYAML_LOG_INFO, /**< Info level logging. */
|
|
CYAML_LOG_NOTICE, /**< Notice level logging. */
|
|
CYAML_LOG_WARNING, /**< Warning level logging. */
|
|
CYAML_LOG_ERROR, /**< Error level logging. */
|
|
} cyaml_log_t;
|
|
|
|
/**
|
|
* CYAML logging function prototype.
|
|
*
|
|
* Clients may implement this to manage logging from CYAML themselves.
|
|
* Otherwise, consider using the standard logging function, \ref cyaml_log.
|
|
*
|
|
* \param[in] level Log level of message to log.
|
|
* \param[in] ctx Client's private logging context.
|
|
* \param[in] fmt Format string for message to log.
|
|
* \param[in] args Additional arguments used by fmt.
|
|
*/
|
|
typedef void (*cyaml_log_fn_t)(
|
|
cyaml_log_t level,
|
|
void *ctx,
|
|
const char *fmt,
|
|
va_list args);
|
|
|
|
/**
|
|
* CYAML memory allocation / freeing function.
|
|
*
|
|
* Clients may implement this to handle memory allocation / freeing.
|
|
*
|
|
* \param[in] ctx Client's private allocation context.
|
|
* \param[in] ptr Existing allocation to resize, or NULL.
|
|
* \param[in] size The new size for the allocation. \note setting 0 must
|
|
* be treated as free().
|
|
* \return If `size == 0`, returns NULL. If `size > 0`, returns NULL on failure,
|
|
* and any existing allocation is left untouched, or return non-NULL as
|
|
* the new allocation on success, and the original pointer becomes
|
|
* invalid.
|
|
*/
|
|
typedef void * (*cyaml_mem_fn_t)(
|
|
void *ctx,
|
|
void *ptr,
|
|
size_t size);
|
|
|
|
/**
|
|
* Client CYAML configuration data.
|
|
*
|
|
* \todo Should provide facility for client to provide its own custom
|
|
* allocation functions.
|
|
*/
|
|
typedef struct cyaml_config {
|
|
/**
|
|
* Client function to use for logging.
|
|
*
|
|
* Clients can implement their own logging function and set it here.
|
|
* Otherwise, set `log_fn` to \ref cyaml_log if CYAML's default
|
|
* logging to `stderr` is suitable (see its documentation for more
|
|
* details), or set to `NULL` to suppress all logging.
|
|
*
|
|
* \note Useful backtraces are issued through the `log_fn` at
|
|
* \ref CYAML_LOG_ERROR level. If your application needs
|
|
* to load user YAML data, these backtraces can help users
|
|
* figure out what's wrong with their YAML, causing it to
|
|
* be rejected by your schema.
|
|
*/
|
|
cyaml_log_fn_t log_fn;
|
|
/**
|
|
* Client logging function context pointer.
|
|
*
|
|
* Clients using their own custom logging function can pass their
|
|
* context here, which will be passed through to their log_fn.
|
|
*
|
|
* The default logging function, \ref cyaml_log doesn't require a
|
|
* logging context, so pass NULL for the log_ctx if using that.
|
|
*/
|
|
void *log_ctx;
|
|
/**
|
|
* Client function to use for memory allocation handling.
|
|
*
|
|
* Clients can implement their own, or pass \ref cyaml_mem to use
|
|
* CYAML's default allocator.
|
|
*
|
|
* \note Depending on platform, when using CYAML's default allocator,
|
|
* clients may need to take care to ensure any allocated memory
|
|
* is freed using \ref cyaml_mem too.
|
|
*/
|
|
cyaml_mem_fn_t mem_fn;
|
|
/**
|
|
* Client memory function context pointer.
|
|
*
|
|
* Clients using their own custom allocation function can pass their
|
|
* context here, which will be passed through to their mem_fn.
|
|
*
|
|
* The default allocation function, \ref cyaml_mem doesn't require an
|
|
* allocation context, so pass NULL for the mem_ctx if using that.
|
|
*/
|
|
void *mem_ctx;
|
|
/**
|
|
* Minimum logging priority level to be issued.
|
|
*
|
|
* Specifying e.g. \ref CYAML_LOG_WARNING will cause only warnings and
|
|
* errors to emerge.
|
|
*/
|
|
cyaml_log_t log_level;
|
|
/** CYAML behaviour flags. */
|
|
cyaml_cfg_flags_t flags;
|
|
} cyaml_config_t;
|
|
|
|
/**
|
|
* Standard CYAML logging function.
|
|
*
|
|
* This logs to `stderr`. It clients want to log elsewhere they must
|
|
* implement their own logging function, and pass it to CYAML in the
|
|
* \ref cyaml_config_t structure.
|
|
*
|
|
* \note This default logging function composes single log messages from
|
|
* multiple separate fprintfs to `stderr`. If the client application
|
|
* writes to `stderr` from multiple threads, individual \ref cyaml_log
|
|
* messages may get broken up by the client applications logging. To
|
|
* avoid this, clients should implement their own \ref cyaml_log_fn_t and
|
|
* pass it in via \ref cyaml_config_t.
|
|
*
|
|
* \param[in] level Log level of message to log.
|
|
* \param[in] ctx Logging context, unused.
|
|
* \param[in] fmt Format string for message to log.
|
|
* \param[in] args Additional arguments used by fmt.
|
|
*/
|
|
extern void cyaml_log(
|
|
cyaml_log_t level,
|
|
void *ctx,
|
|
const char *fmt,
|
|
va_list args);
|
|
|
|
/**
|
|
* CYAML default memory allocation / freeing function.
|
|
*
|
|
* This is used when clients don't supply their own. It is exposed to
|
|
* enable clients to use the same allocator as libcyaml used internally
|
|
* to allocate/free memory when they have not provided their own allocation
|
|
* function.
|
|
*
|
|
* \param[in] ctx Allocation context, unused.
|
|
* \param[in] ptr Existing allocation to resize, or NULL.
|
|
* \param[in] size The new size for the allocation. \note When `size == 0`
|
|
* this frees `ptr`.
|
|
* \return If `size == 0`, returns NULL. If `size > 0`, returns NULL on failure,
|
|
* and any existing allocation is left untouched, or return non-NULL as
|
|
* the new allocation on success, and the original pointer becomes
|
|
* invalid.
|
|
*/
|
|
extern void * cyaml_mem(
|
|
void *ctx,
|
|
void *ptr,
|
|
size_t size);
|
|
|
|
/**
|
|
* Load a YAML document from a file at the given path.
|
|
*
|
|
* \note In the event of the top-level mapping having only optional fields,
|
|
* and the YAML not setting any of them, this function can return \ref
|
|
* CYAML_OK, and `NULL` in the `data_out` parameter.
|
|
*
|
|
* \param[in] path Path to YAML file to load.
|
|
* \param[in] config Client's CYAML configuration structure.
|
|
* \param[in] schema CYAML schema for the YAML to be loaded.
|
|
* \param[out] data_out Returns the caller-owned loaded data on success.
|
|
* Untouched on failure.
|
|
* \param[out] seq_count_out On success, returns the sequence entry count.
|
|
* Untouched on failure.
|
|
* Must be non-NULL if top-level schema type is
|
|
* \ref CYAML_SEQUENCE, otherwise, must be NULL.
|
|
* \return \ref CYAML_OK on success, or appropriate error code otherwise.
|
|
*/
|
|
extern cyaml_err_t cyaml_load_file(
|
|
const char *path,
|
|
const cyaml_config_t *config,
|
|
const cyaml_schema_value_t *schema,
|
|
cyaml_data_t **data_out,
|
|
unsigned *seq_count_out);
|
|
|
|
/**
|
|
* Load a YAML document from a data buffer.
|
|
*
|
|
* \note In the event of the top-level mapping having only optional fields,
|
|
* and the YAML not setting any of them, this function can return \ref
|
|
* CYAML_OK, and `NULL` in the `data_out` parameter.
|
|
*
|
|
* \param[in] input Buffer to load YAML data from.
|
|
* \param[in] input_len Length of input in bytes.
|
|
* \param[in] config Client's CYAML configuration structure.
|
|
* \param[in] schema CYAML schema for the YAML to be loaded.
|
|
* \param[out] data_out Returns the caller-owned loaded data on success.
|
|
* Untouched on failure.
|
|
* \param[out] seq_count_out On success, returns the sequence entry count.
|
|
* Untouched on failure.
|
|
* Must be non-NULL if top-level schema type is
|
|
* \ref CYAML_SEQUENCE, otherwise, must be NULL.
|
|
* \return \ref CYAML_OK on success, or appropriate error code otherwise.
|
|
*/
|
|
extern cyaml_err_t cyaml_load_data(
|
|
const uint8_t *input,
|
|
size_t input_len,
|
|
const cyaml_config_t *config,
|
|
const cyaml_schema_value_t *schema,
|
|
cyaml_data_t **data_out,
|
|
unsigned *seq_count_out);
|
|
|
|
/**
|
|
* Save a YAML document to a file at the given path.
|
|
*
|
|
* \param[in] path Path to YAML file to write.
|
|
* \param[in] config Client's CYAML configuration structure.
|
|
* \param[in] schema CYAML schema for the YAML to be saved.
|
|
* \param[in] data The caller-owned data to be saved.
|
|
* \param[in] seq_count If top level type is sequence, this should be the
|
|
* entry count, otherwise it is ignored.
|
|
* \return \ref CYAML_OK on success, or appropriate error code otherwise.
|
|
*/
|
|
extern cyaml_err_t cyaml_save_file(
|
|
const char *path,
|
|
const cyaml_config_t *config,
|
|
const cyaml_schema_value_t *schema,
|
|
const cyaml_data_t *data,
|
|
unsigned seq_count);
|
|
|
|
/**
|
|
* Save a YAML document into a string in memory.
|
|
*
|
|
* This allocates a buffer containing the serialised YAML data.
|
|
*
|
|
* To free the returned YAML string, clients should use the \ref cyaml_mem_fn_t
|
|
* function set in the \ref cyaml_config_t passed to this function.
|
|
* For example:
|
|
*
|
|
* ```
|
|
* char *yaml;
|
|
* size_t len;
|
|
* err = cyaml_save_file(&yaml, &len, &config, &client_schema, client_data, 0);
|
|
* if (err == CYAML_OK) {
|
|
* // Use `yaml`:
|
|
* printf("%*s\n", len, yaml);
|
|
* // Free `yaml`:
|
|
* config.mem_fn(config.mem_ctx, yaml, 0);
|
|
* }
|
|
* ```
|
|
*
|
|
* \note The returned YAML string does not have a trailing '\0'.
|
|
*
|
|
* \param[out] output Returns the caller-owned serialised YAML data on
|
|
* success, untouched on failure. Clients should use
|
|
* the \ref cyaml_mem_fn_t function set in the \ref
|
|
* cyaml_config_t to free the data.
|
|
* \param[out] len Returns the length of the data in output on success,
|
|
* untouched on failure.
|
|
* \param[in] config Client's CYAML configuration structure.
|
|
* \param[in] schema CYAML schema for the YAML to be saved.
|
|
* \param[in] data The caller-owned data to be saved.
|
|
* \param[in] seq_count If top level type is sequence, this should be the
|
|
* entry count, otherwise it is ignored.
|
|
* \return \ref CYAML_OK on success, or appropriate error code otherwise.
|
|
*/
|
|
extern cyaml_err_t cyaml_save_data(
|
|
char **output,
|
|
size_t *len,
|
|
const cyaml_config_t *config,
|
|
const cyaml_schema_value_t *schema,
|
|
const cyaml_data_t *data,
|
|
unsigned seq_count);
|
|
|
|
/**
|
|
* Free data returned by a CYAML load function.
|
|
*
|
|
* This is a convenience function, which is here purely to minimise the
|
|
* amount of code required in clients. Clients would be better off writing
|
|
* their own free function for the specific data once loaded.
|
|
*
|
|
* \note This is a recursive operation, freeing all nested data.
|
|
*
|
|
* \param[in] config The client's CYAML library config.
|
|
* \param[in] schema The schema describing the content of data. Must match
|
|
* the schema given to the CYAML load function used to
|
|
* load the data.
|
|
* \param[in] data The data structure to free.
|
|
* \param[in] seq_count If top level type is sequence, this should be the
|
|
* entry count, otherwise it is ignored.
|
|
* \return \ref CYAML_OK on success, or appropriate error code otherwise.
|
|
*/
|
|
extern cyaml_err_t cyaml_free(
|
|
const cyaml_config_t *config,
|
|
const cyaml_schema_value_t *schema,
|
|
cyaml_data_t *data,
|
|
unsigned seq_count);
|
|
|
|
/**
|
|
* Convert a cyaml error code to a human-readable string.
|
|
*
|
|
* \param[in] err Error code code to convert.
|
|
* \return String representing err. The string is '\0' terminated, and owned
|
|
* by libcyaml.
|
|
*/
|
|
extern const char * cyaml_strerror(
|
|
cyaml_err_t err);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|