1 /**
2  * @file user_types.h
3  * @author Michal Vasko <mvasko@cesnet.cz>
4  * @brief libyang support for user YANG type implementations.
5  *
6  * Copyright (c) 2018 CESNET, z.s.p.o.
7  *
8  * This source code is licensed under BSD 3-Clause License (the "License").
9  * You may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  *     https://opensource.org/licenses/BSD-3-Clause
13  */
14 
15 #ifndef LY_USER_TYPES_H_
16 #define LY_USER_TYPES_H_
17 
18 #include "libyang.h"
19 
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23 
24 /**
25  * @defgroup user_types User Types
26  * @ingroup schematree
27  * @{
28  */
29 
30 /**
31  * @brief User types API version
32  */
33 #define LYTYPE_API_VERSION 1
34 
35 /**
36  * @brief Macro to store version of user type plugins API in the plugins.
37  * It is matched when the plugin is being loaded by libyang.
38  */
39 #ifdef STATIC
40 #define LYTYPE_VERSION_CHECK
41 #else
42 #define LYTYPE_VERSION_CHECK int lytype_api_version = LYTYPE_API_VERSION;
43 #endif
44 
45 
46 /**
47  * @brief Callback for storing user type values.
48  *
49  * This callback should overwrite the value stored in \p value using some custom encoding. Be careful,
50  * if the type is #LY_TYPE_BITS, the bits must be freed before overwritting the union value.
51  *
52  * @param[in] ctx libyang ctx to enable correct manipulation with values that are in the dictionary.
53  * @param[in] type_name Name of the type being stored.
54  * @param[in,out] value_str String value to be stored.
55  * @param[in,out] value Value union for the value to be stored in (already is but in the standard way).
56  * @param[out] err_msg Can be filled on error. If not, a generic error message will be printed.
57  * @return 0 on success, non-zero if an error occurred and the value could not be stored for any reason.
58  */
59 typedef int (*lytype_store_clb)(struct ly_ctx *ctx, const char *type_name, const char **value_str, lyd_val *value,
60                                 char **err_msg);
61 
62 struct lytype_plugin_list {
63     const char *module;          /**< Name of the module where the type is defined. */
64     const char *revision;        /**< Optional module revision - if not specified, the plugin applies to any revision,
65                                       which is not the best approach due to a possible future revisions of the module.
66                                       Instead, there should be defined multiple items in the plugins list, each with the
67                                       different revision, but all with the same store callback. The only valid use case
68                                       for the NULL revision is the case when the module has no revision. */
69     const char *name;            /**< Name of the type to be stored in a custom way. */
70     lytype_store_clb store_clb;  /**< Callback used for storing values of this type. */
71     void (*free_clb)(void *ptr); /**< Callback used for freeing values of this type. */
72 };
73 
74 /**
75  * @}
76  */
77 
78 #ifdef __cplusplus
79 }
80 #endif
81 
82 #endif /* LY_USER_TYPES_H_ */
83