/*
 * Copyright © 2026 Pierre Le Marre
 *
 * SPDX-License-Identifier: MIT
 *
 * Author: Pierre Le Marre <dev@wismill.eu>
 */

#ifndef _XKBCOMMON_ERRORS_H_
#define _XKBCOMMON_ERRORS_H_

/* This file is autogenerated; please do not commit directly. */

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @file
 * @brief Error-handling related features
 */

/**
 * @defgroup error-api Error handling
 * Error-handling related features
 *
 * @{
 */

/**
 * @enum xkb_error_code
 * Error codes returned by the API.
 *
 * The numeric values are stable identifiers that are also used in logging.
 * See the @ref error-index for the full list of logging codes.
 *
 * <details>
 * <summary>About the numeric values</summary>
 *
 * Codes are small positive integers assigned *non-sequentially* by design:
 * it prevents callers from assuming adjacency implies relatedness.
 *
 * See [these guidelines] for further details on the methodology.
 *
 * The value -1 (`::XKB_ERROR_INVALID`) is reserved for pre-1.14
 * functions and does not follow the above scheme.
 * </details>
 *
 * @since 1.14.0
 *
 * [these guidelines]: https://github.com/haskellfoundation/error-message-index/blob/main/tool-developers.md#code-assignment-recommendations
 */
enum xkb_error_code {
    /**
     * An unspecified error occurred.
     *
     * Reserved for pre-1.14 functions, which signal errors via -1 return
     * values documented per-function.
     *
     * @since 1.14.0
     */
    XKB_ERROR_INVALID = -1,
    /**
     * The operation completed successfully.
     *
     * @since 1.14.0
     */
    XKB_SUCCESS = 0,
    /**
     * Unsupported modifier mask
     *
     * The modifier mask does not represent valid modifiers.
     *
     * @since 1.14.0
     */
    XKB_ERROR_UNSUPPORTED_MODIFIER_MASK = 60,
    /**
     * The given layout out-of-range policy is not supported
     *
     * Use the following to check if the linked libxkbcommon library supports a
     * given flag:
     *
     * ```c
     * xkb_feature_supported(XKB_FEATURE_ENUM_LAYOUT_OUT_OF_RANGE_POLICY, flag)
     * ```
     *
     * @since 1.14.0
     */
    XKB_ERROR_UNSUPPORTED_LAYOUT_OUT_OF_RANGE_POLICY = 214,
    /**
     * Layout index is not supported
     *
     * libxkbcommon supports different *layout index* ranges, depending on the
     * target
     * *keymap format*:
     * - `::XKB_KEYMAP_FORMAT_TEXT_V1`: 1..4
     * - `::XKB_KEYMAP_FORMAT_TEXT_V2`: 1..32
     *
     * @since 1.14.0
     */
    XKB_ERROR_UNSUPPORTED_LAYOUT_INDEX = 237,
    /**
     * Unsupported keymap format
     *
     * See `xkb_keymap_format` for the list of valid values.
     *
     * @since 1.14.0
     */
    XKB_ERROR_UNSUPPORTED_KEYMAP_FORMAT = 277,
    /**
     * Layout count limit exceeded for the corresponding keymap format
     *
     * @since 1.14.0
     */
    XKB_ERROR_LAYOUT_COUNT_LIMIT_EXCEEDED = 366,
    /**
     * Unsupported `xkb_a11y_flags` value
     *
     * Use the following to check if the linked libxkbcommon library supports a
     * given flag:
     *
     * ```c
     * xkb_feature_supported(XKB_FEATURE_ENUM_A11Y_FLAGS, flag)
     * ```
     *
     * @since 1.14.0
     */
    XKB_ERROR_UNSUPPORTED_A11Y_FLAGS = 371,
    /**
     * A `xkb_state` object has an unexpected `xkb_state_mode`
     *
     * @since 1.14.0
     */
    XKB_ERROR_UNEXPECTED_STATE_MODE = 399,
    /**
     * ABI struct size check failed
     *
     * The `size` field of a versioned structure does not match any known
     * version of that structure. This typically indicates the caller failed
     * to initialize the struct correctly, e.g. by omitting:
     *
     * ```c
     * .size = sizeof(struct xkb_foo)
     * ```
     *
     * @since 1.14.0
     */
    XKB_ERROR_ABI_INVALID_STRUCT_SIZE = 450,
    /**
     * Cannot allocate memory
     *
     * @since 1.14.0
     */
    XKB_ERROR_ALLOCATION_FAILURE = 550,
    /**
     * Unsupported keymap serialization flags
     *
     * See `::xkb_keymap_serialize_flags` for the list of valid flags.
     *
     * @since 1.14.0
     */
    XKB_ERROR_UNSUPPORTED_KEYMAP_SERIALIZATION_FLAGS = 829,
    /**
     * ABI forward-compatibility check failed
     *
     * The caller was compiled against a newer version of the library and is
     * using fields unknown to this version.
     *
     * @since 1.14.0
     */
    XKB_ERROR_ABI_FORWARD_COMPAT = 876,
    /**
     * ABI backward-compatibility check failed
     *
     * The caller was compiled against an older version of the library and is
     * missing fields that are mandatory in this version.
     *
     * @since 1.14.0
     */
    XKB_ERROR_ABI_BACKWARD_COMPAT = 914,
};

/** @} */

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* _XKBCOMMON_ERRORS_H_ */