libyang  2.0.164
libyang is YANG data modelling language parser and toolkit written (and providing API) in C.
Plugins: Extensions
Collaboration diagram for Plugins: Extensions:

Modules

 Plugins: Extensions compilation support
 
 Plugins: Extensions printer support
 

Data Structures

struct  lyplg_ext
 Extension plugin implementing various aspects of a YANG extension. More...
 
struct  lyplg_ext_record
 

Macros

#define LYPLG_EXT_API_VERSION   2
 Extensions API version. More...
 
#define LYPLG_EXTENSIONS
 Macro to define plugin information in external plugins. More...
 

Typedefs

typedef LY_ERR(* lyplg_ext_compile_clb) (struct lysc_ctx *cctx, const struct lysp_ext_instance *p_ext, struct lysc_ext_instance *c_ext)
 Callback to compile extension from the lysp_ext_instance to the lysc_ext_instance. The later structure is generally prepared and only the extension specific data are supposed to be added (if any). More...
 
typedef LY_ERR(* lyplg_ext_data_parse_clb) (struct ly_in *in, LYD_FORMAT format, struct lysc_ext_instance *ext, struct lyd_node *parent, uint32_t parse_opts)
 Callback for parsing YANG instance data described by an extension instance. More...
 
typedef LY_ERR(* lyplg_ext_data_validate_clb) (struct lysc_ext_instance *ext, struct lyd_node *sibling, uint32_t val_opts)
 Callback for validating parsed YANG instance data described by an extension instance. More...
 
typedef void(* lyplg_ext_free_clb) (struct ly_ctx *ctx, struct lysc_ext_instance *ext)
 Callback to free the extension-specific data created by its compilation. More...
 
typedef LY_ERR(* lyplg_ext_schema_printer_clb) (struct lyspr_ctx *ctx, struct lysc_ext_instance *ext, ly_bool *flag)
 Callback to print the compiled extension instance's private data in the INFO format. More...
 

Functions

LIBYANG_API_DECL LY_ERR lyd_insert_ext (struct lyd_node *parent, struct lyd_node *first)
 Insert extension instance data into a parent. More...
 
LIBYANG_API_DECL LY_ERR lyplg_ext_get_data (const struct ly_ctx *ctx, const struct lysc_ext_instance *ext, void **ext_data, ly_bool *ext_data_free)
 Get specific run-time extension instance data from a callback set by ly_ctx_set_ext_data_clb(). More...
 
LIBYANG_API_DECL void lyplg_ext_instance_substatements_free (struct ly_ctx *ctx, struct lysc_ext_substmt *substmts)
 Free the extension instance's data compiled with lys_compile_extension_instance(). More...
 
LIBYANG_API_DECL void lyplg_ext_log (const struct lysc_ext_instance *ext, LY_LOG_LEVEL level, LY_ERR err_no, const char *path, const char *format,...)
 Provide a log message from an extension plugin. More...
 

Detailed Description

Structures and functions to for libyang plugins implementing specific YANG extensions defined in YANG modules. For more information, see Type Plugins.

This part of libyang API is available by including <libyang/plugins_ext.h> header file.


Data Structure Documentation

◆ lyplg_ext

struct lyplg_ext

Extension plugin implementing various aspects of a YANG extension.

Definition at line 195 of file plugins_exts.h.

Data Fields
lyplg_ext_compile_clb compile

callback to compile extension instance from the parsed data

lyplg_ext_free_clb free

free the extension-specific data created by its compilation

const char * id

plugin identification (mainly for distinguish incompatible versions of the plugins for external tools)

lyplg_ext_data_parse_clb parse

callback to parse data instance according to the extension definition

lyplg_ext_schema_printer_clb sprinter

callback to print the compiled content (info format) of the extension instance

lyplg_ext_data_validate_clb validate

callback to validate parsed data instances according to the extension definition

◆ lyplg_ext_record

struct lyplg_ext_record

Definition at line 208 of file plugins_exts.h.

Data Fields
const char * module

name of the module where the extension is defined

const char * name

YANG name of the extension

struct lyplg_ext plugin

data to utilize plugin implementation

const char * revision

optional module revision - if not specified, the plugin applies to any revision, which is not an optimal approach due to a possible future revisions of the module. Instead, there should be defined multiple items in the plugins list, each with the different revision, but all with the same pointer to the plugin functions. The only valid use case for the NULL revision is the case the module has no revision.

Macro Definition Documentation

◆ LYPLG_EXT_API_VERSION

#define LYPLG_EXT_API_VERSION   2

Extensions API version.

Definition at line 103 of file plugins_exts.h.

◆ LYPLG_EXTENSIONS

#define LYPLG_EXTENSIONS
Value:
uint32_t plugins_extensions_apiver__ = LYPLG_EXT_API_VERSION; \
const struct lyplg_ext_record plugins_extensions__[]
#define LYPLG_EXT_API_VERSION
Extensions API version.
Definition: plugins_exts.h:103

Macro to define plugin information in external plugins.

Use as follows: LYPLG_EXTENSIONS = {{<filled information of lyplg_ext_record>}, ..., {0}};

Definition at line 111 of file plugins_exts.h.

Typedef Documentation

◆ lyplg_ext_compile_clb

typedef LY_ERR(* lyplg_ext_compile_clb) (struct lysc_ctx *cctx, const struct lysp_ext_instance *p_ext, struct lysc_ext_instance *c_ext)

Callback to compile extension from the lysp_ext_instance to the lysc_ext_instance. The later structure is generally prepared and only the extension specific data are supposed to be added (if any).

The parsed generic statements can be processed by the callback on its own or the lys_compile_extension_instance function can be used to let the compilation to libyang following the standard rules for processing the YANG statements.

Parameters
[in]cctxCurrent compile context.
[in]p_extParsed extension instance data.
[in,out]c_extPrepared compiled extension instance structure where an addition, extension-specific, data are supposed to be placed for later use (data validation or use of external tool).
Returns
LY_SUCCESS in case of success.
LY_EVALID in case of non-conforming parsed data.
LY_ENOT in case the extension instance is not supported and should be removed.

Definition at line 139 of file plugins_exts.h.

◆ lyplg_ext_data_parse_clb

typedef LY_ERR(* lyplg_ext_data_parse_clb) (struct ly_in *in, LYD_FORMAT format, struct lysc_ext_instance *ext, struct lyd_node *parent, uint32_t parse_opts)

Callback for parsing YANG instance data described by an extension instance.

This callback is used only for nested data definition (with a standard YANG schema parent). Note that the siblings parsed by this function and directly connected to parent must have the flag LYD_EXT set.

Parameters
[in]inInput handler with the data to parse.
[in]formatFormat if the data in in.
[in]extCompiled extension instance.
[in,out]parentData parent to append to.
[in]parse_optsParse options, see Data parser options. They will always include LYD_PARSE_ONLY.
Returns
LY_SUCCESS on success.
LY_ENOT if the data are not described by ext.
LY_ERR on error.

Definition at line 176 of file plugins_exts.h.

◆ lyplg_ext_data_validate_clb

typedef LY_ERR(* lyplg_ext_data_validate_clb) (struct lysc_ext_instance *ext, struct lyd_node *sibling, uint32_t val_opts)

Callback for validating parsed YANG instance data described by an extension instance.

This callback is used only for nested data definition (with a standard YANG schema parent).

Parameters
[in]extCompiled extension instance.
[in]siblingFirst sibling parsed by lyplg_ext_data_parse_clb.
[in]val_optsValidation options, see Data validation options.
Returns
LY_SUCCESS on success.
LY_ERR on error.

Definition at line 190 of file plugins_exts.h.

◆ lyplg_ext_free_clb

typedef void(* lyplg_ext_free_clb) (struct ly_ctx *ctx, struct lysc_ext_instance *ext)

Callback to free the extension-specific data created by its compilation.

Parameters
[in]ctxlibyang context.
[in,out]extCompiled extension structure where the data to free are placed.

Definition at line 159 of file plugins_exts.h.

◆ lyplg_ext_schema_printer_clb

typedef LY_ERR(* lyplg_ext_schema_printer_clb) (struct lyspr_ctx *ctx, struct lysc_ext_instance *ext, ly_bool *flag)

Callback to print the compiled extension instance's private data in the INFO format.

Parameters
[in]ctxYANG printer context to provide output handler and other information for printing.
[in]extThe compiled extension instance, mainly to access the extensions.
[in,out]flagFlag to be shared with the caller regarding the opening brackets - 0 if the '{' not yet printed, 1 otherwise.
Returns
LY_SUCCESS when everything was fine, other LY_ERR values in case of failure

Definition at line 151 of file plugins_exts.h.

Function Documentation

◆ lyd_insert_ext()

LIBYANG_API_DECL LY_ERR lyd_insert_ext ( struct lyd_node parent,
struct lyd_node first 
)

Insert extension instance data into a parent.

Parameters
[in]parentParent node to insert into.
[in]firstFirst top-level sibling node to insert.
Returns
LY_SUCCESS on success.
LY_ERR error on error.

◆ lyplg_ext_get_data()

LIBYANG_API_DECL LY_ERR lyplg_ext_get_data ( const struct ly_ctx ctx,
const struct lysc_ext_instance ext,
void **  ext_data,
ly_bool ext_data_free 
)

Get specific run-time extension instance data from a callback set by ly_ctx_set_ext_data_clb().

Parameters
[in]ctxContext with the callback.
[in]extCompiled extension instance.
[out]ext_dataProvided extension instance data.
[out]ext_data_freeWhether the extension instance should free ext_data or not.
Returns
LY_SUCCESS on success.
LY_ERR on error.

◆ lyplg_ext_instance_substatements_free()

LIBYANG_API_DECL void lyplg_ext_instance_substatements_free ( struct ly_ctx ctx,
struct lysc_ext_substmt substmts 
)

Free the extension instance's data compiled with lys_compile_extension_instance().

Parameters
[in]ctxlibyang context
[in]substmtsThe sized array of extension instance's substatements. The whole array is freed except the storage places which are expected to be covered by the extension plugin.

◆ lyplg_ext_log()

LIBYANG_API_DECL void lyplg_ext_log ( const struct lysc_ext_instance ext,
LY_LOG_LEVEL  level,
LY_ERR  err_no,
const char *  path,
const char *  format,
  ... 
)

Provide a log message from an extension plugin.

Parameters
[in]extCompiled extension structure providing generic information about the extension/plugin causing the message.
[in]levelLog message level (error, warning, etc.)
[in]err_noError type code.
[in]pathPath relevant to the message.
[in]formatFormat string to print.