blob: 49657f705a5e41c30799dc236e7b45d1902b1ccb [file] [log] [blame]
Radek Krejci5aeea3a2018-09-05 13:29:36 +02001/**
2 * @file libyang.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief The main libyang public header.
5 *
6 * Copyright (c) 2015 - 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_LIBYANG_H_
16#define LY_LIBYANG_H_
17
Radek Krejci0af5f5d2018-09-07 15:00:30 +020018#include <stdint.h>
19
Radek Krejci5aeea3a2018-09-05 13:29:36 +020020#ifdef __cplusplus
21extern "C" {
22#endif
23
Radek Krejcica376bd2020-06-11 16:04:06 +020024#include "context.h"
25#include "dict.h"
Michal Vaskoafac7822020-10-20 14:22:26 +020026#include "in.h"
Radek Krejci47fab892020-11-05 17:02:41 +010027#include "log.h"
28#include "out.h"
Radek Krejci7931b192020-06-25 17:05:03 +020029#include "parser_data.h"
Radek Krejcif0e1ba52020-05-22 15:14:35 +020030#include "parser_schema.h"
Radek Krejcif0e1ba52020-05-22 15:14:35 +020031#include "printer_data.h"
32#include "printer_schema.h"
Radek Krejci6caa6ab2018-10-24 10:04:48 +020033#include "set.h"
Radek Krejcie7b95092019-05-15 11:03:07 +020034#include "tree.h"
35#include "tree_data.h"
Radek Krejci6caa6ab2018-10-24 10:04:48 +020036#include "tree_schema.h"
37
Radek Krejci47fab892020-11-05 17:02:41 +010038/*
39 * The following headers are supposed to be included explicitly:
40 * - plugins_types.h
41 * - plugins_exts.h
42 */
43
Radek Krejci5aeea3a2018-09-05 13:29:36 +020044/**
Radek Krejcie53a8dc2018-10-17 12:52:40 +020045 * @mainpage About
46 *
47 * libyang is a library implementing processing of the YANG schemas and data modeled by the YANG language. The
48 * library is implemented in C for GNU/Linux and provides C API.
49 *
50 * @section about-features Main Features
51 *
Radek Krejci8678fa42020-08-18 16:07:28 +020052 * - [Parsing (and validating) schemas](@ref howtoSchema) in YANG format.
53 * - [Parsing (and validating) schemas](@ref howtoSchema) in YIN format.
54 * - [Parsing, validating and printing instance data](@ref howtoData) in XML format.
55 * - [Parsing, validating and printing instance data](@ref howtoData) in JSON format
Radek Krejcie53a8dc2018-10-17 12:52:40 +020056 * ([RFC 7951](https://tools.ietf.org/html/rfc7951)).
Radek Krejci8678fa42020-08-18 16:07:28 +020057 * - [Manipulation with the instance data](@ref howtoDataManipulation).
58 * - Support for [default values in the instance data](@ref howtoDataWD) ([RFC 6243](https://tools.ietf.org/html/rfc6243)).
59 * - Support for [YANG extensions and user types](@ref howtoPlugins).
Radek Krejci75104122021-04-01 15:37:45 +020060 * - Support for [YANG Metadata](@ref howtoDataMetadata) ([RFC 7952](https://tools.ietf.org/html/rfc6243)).
Michal Vaskodf135a82022-02-11 10:04:50 +010061 * - Support for [YANG Schema Mount](@ref howtoDataMountpoint) ([RFC 8528](https://tools.ietf.org/html/rfc8528)).
Radek Krejcie53a8dc2018-10-17 12:52:40 +020062 *
63 * The current implementation covers YANG 1.0 ([RFC 6020](https://tools.ietf.org/html/rfc6020)) as well as
64 * YANG 1.1 ([RFC 7950](https://tools.ietf.org/html/rfc7950)).
65 *
66 * @section about-license License
67 *
Michal Vaskodf135a82022-02-11 10:04:50 +010068 * Copyright (c) 2015-2022 CESNET, z.s.p.o.
Radek Krejcie53a8dc2018-10-17 12:52:40 +020069 *
70 * (The BSD 3-Clause License)
71 *
72 * Redistribution and use in source and binary forms, with or without
73 * modification, are permitted provided that the following conditions
74 * are met:
75 * 1. Redistributions of source code must retain the above copyright
76 * notice, this list of conditions and the following disclaimer.
77 * 2. Redistributions in binary form must reproduce the above copyright
78 * notice, this list of conditions and the following disclaimer in
79 * the documentation and/or other materials provided with the
80 * distribution.
81 * 3. Neither the name of the Company nor the names of its contributors
82 * may be used to endorse or promote products derived from this
83 * software without specific prior written permission.
84 */
85
86/**
Radek Krejci52785a22019-09-11 12:57:26 +020087 * @page howto libyang API Overview
Radek Krejcie53a8dc2018-10-17 12:52:40 +020088 *
Radek Krejci8678fa42020-08-18 16:07:28 +020089 * @section howtoGeneral General notes
90 *
91 * libyang is primarily intended for handling data modeled by YANG modeling language, so the library is supposed to be optimized
92 * for this purpose. However, as a side effect, the library has to be able precisely process YANG modules. Thus, it is usable by
93 * YANG module authors to validate their modules and schemas in the development process.
94 *
95 * - @subpage howtoStructures
96 * - @subpage howtoErrors
97 * - @subpage howtoLogger
98 * - @subpage howtoThreads
99 * - @subpage howtoContext
Michal Vaskoafac7822020-10-20 14:22:26 +0200100 * - @subpage howtoInput
101 * - @subpage howtoOutput
Radek Krejci8678fa42020-08-18 16:07:28 +0200102 * - @subpage howtoSchema
103 * - @subpage howtoData
104 * - @subpage howtoXPath
105 * - @subpage howtoPlugins
106 */
107
108/**
109 * @page howtoStructures Data Structures
110 *
111 * @section sizedarrays Sized Arrays
112 *
113 * The structure starts with 32bit number storing size of the array - the number of the items inside. The size is part of the
114 * array to have it allocated together with the array itself only when it is needed. However, the pointers to the array always
115 * points after the 32b number, so items can be accessed directly as for standard C arrays. Because of a known size (available
116 * via ::LY_ARRAY_COUNT macro), it is not terminated by any special byte (sequence), so there is also no limitation for specific
117 * content of the stored records (e.g. that first byte must not be NULL).
118 *
119 * The sized arrays must be carefully freed (which should be done anyway only internally), since pointers to the sized arrays used
120 * in libyang structures, does not point to the beginning of the allocated space.
121 *
122 * - ::LY_ARRAY_COUNT
123 * - ::LY_ARRAY_FOR
124 *
125 * @section struct_lists Lists
126 *
127 * The lists are structures connected via a `next` and `prev` pointers. Iterating over the siblings can be simply done by
128 * ::LY_LIST_FOR macro. Examples of such structures are ::lyd_node or ::lysc_node.
129 *
130 * The `prev` pointer is always filled. In case there is just a single item in the list, the `prev` pointer points to the
131 * item itself. Otherwise, the `prev` pointer of the first item points to the last item of the list. In contrast, the
132 * `next` pointer of the last item in the list is always NULL.
133 */
134
135/**
Michal Vasko5a5e7f82021-04-15 11:11:03 +0200136 * @page howtoThreads Threading Limitations
137 *
138 * @section context Context
139 *
140 * It is safe to read from ::ly_ctx structure concurrently and use its dictionary, which is protected by a lock.
141 * Thread-safe functions include any ones working with data trees (only context dictionary is accessed) and all
142 * the `ly_ctx_get_*()` functions. Generally, they are the functions with `const` context parameter.
143 *
144 * @section data Data Trees
145 *
146 * Data trees are not internally synchronized so the general safe practice of a single writer **or** several concurrent
147 * readers should be followed. Specifically, only the functions with non-const ::lyd_node parameters modify the node(s)
148 * and no concurrent execution of such functions should be allowed on a single data tree or subtrees of one.
149 */
150
151/**
Radek Krejci290a6a52019-09-12 17:13:17 +0200152 * @internal
153 * @page internals Developers' Notes
154 * @tableofcontents
155 *
156 * Following texts describes various internal subsystems and mechanism in libyang which are hidden from external users, but important
157 * for libyang developers. The texts should explain various decisions made and internal processes utilized in libyang.
158 */
159
Radek Krejci0af5f5d2018-09-07 15:00:30 +0200160#ifdef __cplusplus
161}
162#endif
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200163
164#endif /* LY_LIBYANG_H_ */