blob: c86bd13fa8d9b50591358a202c0ef95ab9e9091d [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 Krejci6caa6ab2018-10-24 10:04:48 +020024#include "log.h"
25#include "set.h"
26#include "dict.h"
27#include "context.h"
Radek Krejcie7b95092019-05-15 11:03:07 +020028#include "tree.h"
29#include "tree_data.h"
Radek Krejci6caa6ab2018-10-24 10:04:48 +020030#include "tree_schema.h"
Radek Krejcia5bba312020-01-09 15:41:20 +010031#include "printer.h"
32#include "printer_data.h"
Radek Krejcid3ca0632019-04-16 16:54:54 +020033#include "printer_schema.h"
Radek Krejcie7b95092019-05-15 11:03:07 +020034#include "printer_data.h"
Radek Krejci74a3e232019-07-16 10:46:05 +020035#include "plugins_types.h"
Radek Krejci6caa6ab2018-10-24 10:04:48 +020036
Radek Krejci5aeea3a2018-09-05 13:29:36 +020037/**
Radek Krejcie53a8dc2018-10-17 12:52:40 +020038 * @mainpage About
39 *
40 * libyang is a library implementing processing of the YANG schemas and data modeled by the YANG language. The
41 * library is implemented in C for GNU/Linux and provides C API.
42 *
43 * @section about-features Main Features
44 *
45 * - [Parsing (and validating) schemas](@ref howtoschemasparsers) in YANG format.
46 * - [Parsing (and validating) schemas](@ref howtoschemasparsers) in YIN format.
47 * - [Parsing, validating and printing instance data](@ref howtodata) in XML format.
48 * - [Parsing, validating and printing instance data](@ref howtodata) in JSON format
49 * ([RFC 7951](https://tools.ietf.org/html/rfc7951)).
50 * - [Manipulation with the instance data](@ref howtodatamanipulators).
51 * - Support for [default values in the instance data](@ref howtodatawd) ([RFC 6243](https://tools.ietf.org/html/rfc6243)).
52 * - Support for [YANG extensions and user types](@ref howtoschemaplugins).
53 * - Support for [YANG Metadata](@ref howtoschemametadata) ([RFC 7952](https://tools.ietf.org/html/rfc6243)).
54 *
55 * The current implementation covers YANG 1.0 ([RFC 6020](https://tools.ietf.org/html/rfc6020)) as well as
56 * YANG 1.1 ([RFC 7950](https://tools.ietf.org/html/rfc7950)).
57 *
58 * @section about-license License
59 *
60 * Copyright (c) 2015-2017 CESNET, z.s.p.o.
61 *
62 * (The BSD 3-Clause License)
63 *
64 * Redistribution and use in source and binary forms, with or without
65 * modification, are permitted provided that the following conditions
66 * are met:
67 * 1. Redistributions of source code must retain the above copyright
68 * notice, this list of conditions and the following disclaimer.
69 * 2. Redistributions in binary form must reproduce the above copyright
70 * notice, this list of conditions and the following disclaimer in
71 * the documentation and/or other materials provided with the
72 * distribution.
73 * 3. Neither the name of the Company nor the names of its contributors
74 * may be used to endorse or promote products derived from this
75 * software without specific prior written permission.
76 */
77
78/**
Radek Krejci52785a22019-09-11 12:57:26 +020079 * @page howto libyang API Overview
Radek Krejcie53a8dc2018-10-17 12:52:40 +020080 *
81 * - @subpage howtocontext
82 * - @subpage howtoschemas
83 * - @subpage howtodata
84 * - @subpage howtoxpath
85 * - @subpage howtoxml
86 * - @subpage howtothreads
87 * - @subpage howtologger
Radek Krejci290a6a52019-09-12 17:13:17 +020088 * - @subpage howtoplugins
Radek Krejcie53a8dc2018-10-17 12:52:40 +020089 * - @subpage howtostructures
90 */
91
92/**
Radek Krejci290a6a52019-09-12 17:13:17 +020093 * @internal
94 * @page internals Developers' Notes
95 * @tableofcontents
96 *
97 * Following texts describes various internal subsystems and mechanism in libyang which are hidden from external users, but important
98 * for libyang developers. The texts should explain various decisions made and internal processes utilized in libyang.
99 */
100
101/**
Radek Krejcie53a8dc2018-10-17 12:52:40 +0200102 * @page howtostructures Data Structures
103 *
104 * @section sizedarrays Sized Arrays
105 *
106 * The structure starts with 32bit number storing size of the array - the number of the items inside. The size is part of the
Radek Krejci2c4e7172018-10-19 15:56:26 +0200107 * array to have it allocated together with the array itself only when it is needed. However, the pointers to the array always
108 * points after the 32b number, so items can be accessed directly as for standard C arrays. Because of a known size (available
109 * via ::LY_ARRAY_SIZE macro), it is not terminated by any special byte (sequence), so there is also no limitation for specific
110 * content of the stored records (e.g. that first byte must not be NULL).
Radek Krejcie53a8dc2018-10-17 12:52:40 +0200111 *
Radek Krejci2c4e7172018-10-19 15:56:26 +0200112 * The sized arrays must be carefully freed (which should be done anyway only internally), since pointers to the sized arrays used
113 * in libyang structures, does not point to the beginning of the allocated space.
Radek Krejcie53a8dc2018-10-17 12:52:40 +0200114 *
115 * - ::LY_ARRAY_SIZE
Radek Krejcie53a8dc2018-10-17 12:52:40 +0200116 * - ::LY_ARRAY_FOR
117 *
118 * @section struct_lists Lists
119 *
120 * The lists are structures connected via a `next` pointer. Iterating over the siblings can be simply done by ::LY_LIST_FOR macro.
121 */
122
Radek Krejci950f6a52019-09-12 17:15:32 +0200123/**
124 * @page howtoplugins Plugins
125 *
126 * libyang supports several types of plugins to better support generic features of YANG that need some specific code for
127 * their specific instances in YANG schemas. This is the case of YANG types, which are derived from YANG built-in types
128 * (which are implemented by libyang), but the description of the derived type can specify some additional requirements or
129 * restriction that cannot be implemented generically and some special code is needed. The second case for libyang plugins
130 * are YANG extensions. For YANG extensions, most of the specification stays in their description (e.g. allowed substatements
131 * or place of the extension instanciation) and libyang is not able to process such a text in a generic way. In both cases,
132 * libyang provides API to provide functionality implementing the specifics of each type or extension.
133 */
Radek Krejci0af5f5d2018-09-07 15:00:30 +0200134#ifdef __cplusplus
135}
136#endif
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200137
138#endif /* LY_LIBYANG_H_ */