include/syntax_api.h
/* [<][>][^][v][top][bottom][index][help] */
FUNCTIONS
This source file includes following functions.
1 /******************
2 Copyright (c) 2002 RIPE NCC
3
4 All Rights Reserved
5
6 Permission to use, copy, modify, and distribute this software and its
7 documentation for any purpose and without fee is hereby granted,
8 provided that the above copyright notice appear in all copies and that
9 both that copyright notice and this permission notice appear in
10 supporting documentation, and that the name of the author not be
11 used in advertising or publicity pertaining to distribution of the
12 software without specific, written prior permission.
13
14 THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
15 ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS; IN NO EVENT SHALL
16 AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
17 DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
18 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20 ***************************************/
21
22 #ifndef SYNTAX_API_H
23 #define SYNTAX_API_H
24
25 /***********************************************************************
26 Introduction
27
28 The RIPE RPSL parsing API is intended to allow applications to verify
29 and manipulate RPSL objects in a straightforward manner.
30
31 What it does:
32
33 * Syntax checks on attributes and objects
34
35 * Provides functions to access and manipulate attributes and objects
36
37 What it does not do:
38
39 * I/O (for loading or storing RPSL objects)
40
41 * Database interaction
42
43 * Non-syntax related checks (e.g. existance of objects referred to)
44
45
46
47 Usage
48
49 In a typical program, you need to initialize the data structures
50 representing an RPSL object, check for certain errors, manipulate the
51 data, and finally output the resulting object. To do this:
52
53 1. Create a string representing your RPSL object. This should be the
54 literal text of the object, as described in the RPSL documentation.
55 This can be read from a file or database, from user input, or created
56 dynamically by the program.
57
58 2. Call rpsl_object_init(), verifying the call worked.
59
60 3. Call rpsl_object_errors(), and check to see if you care about any of
61 the errors returned, possibly reporting them to the user.
62
63 4. Call rpsl_object_attr() for the attributes that you want to process.
64
65 5. For each attribute you want to use, call rpsl_attr_errors(), and
66 check to see if you care about any of the errors returned, possibly
67 reporting them to the user.
68
69 6. Remove unwanted attributes by rpsl_object_attr_delete().
70
71 7. Add new attributes by first calling rpsl_attr_init() and then
72 rpsl_object_attr_insert() or rpsl_object_attr_append().
73
74 8. When done, call rpsl_object_get_text() to retrieve an RPSL formatted
75 version of the object.
76
77
78 Data Structures
79
80 These are presented here primarily for enlightenment - often a quick
81 glance at a data structure can clarify the intent in ways that looking
82 at function descriptions never can.
83
84 ************************************************************************/
85
86 /* typedefs allow for forward references within structure definitions */
87 typedef struct rpsl_object rpsl_object_t;
88 typedef struct rpsl_attr rpsl_attr_t;
89 typedef struct rpsl_error rpsl_error_t;
90
91 /* strictness of checking */
92 enum {
93 RPSL_DICT_CORE,
94 RPSL_DICT_FRONT_END
95 };
96
97 /* various RPSL error levels (similar as syslog errors) */
98 enum {
99 RPSL_ERRLVL_NONE,
100 RPSL_ERRLVL_DEBUG,
101 RPSL_ERRLVL_INFO,
102 RPSL_ERRLVL_NOTICE,
103 RPSL_ERRLVL_WARN,
104 RPSL_ERRLVL_ERROR,
105 RPSL_ERRLVL_CRIT,
106 RPSL_ERRLVL_FATAL
107 };
108
109 /* error codes */
110 enum {
111 /* attribute-related errors */
112 RPSL_ERR_BADATTR,
113 RPSL_ERR_UNKNOWNATTR,
114 RPSL_ERR_EMPTYLIST,
115 RPSL_ERR_EMPTYATTR,
116 RPSL_ERR_SYNERR,
117 /* object-related errors */
118 RPSL_ERR_ONLYCOMMENTS,
119 RPSL_ERR_BADCLASS,
120 RPSL_ERR_UNKNOWNCLASS,
121 RPSL_ERR_ATTRNOTALLOWED,
122 RPSL_ERR_ATTRSINGLE,
123 RPSL_ERR_ATTRGENERATED,
124 RPSL_ERR_MISSINGATTR,
125 RPSL_ERR_MISSINGKEY,
126 /* modification-related errors */
127 RPSL_ERR_BADOFFSET,
128 RPSL_ERR_NOSUCHATTR
129 };
130
131 /* per-attribute errors */
132 struct rpsl_error {
133 gint level; /* level of the error (enum above) */
134 gint code; /* code for the error */
135 gchar *descr; /* description of the error */
136 gint attr_num; /* offset of attribute with this error, or
137 -1 if none */
138 };
139
140 /* information about an attribute */
141 struct rpsl_attr {
142 gchar *name; /* name, e.g. "inetnum" or "person" */
143 gchar *lcase_name; /* lower-case version of the name */
144 gchar *value; /* value of the object, e.g. "192.168.0.0/24" */
145 GList *errors; /* any errors with this attribute */
146 gint num; /* Position of attribute.
147 For class name, num = 0.
148 For attributes not in a class, num = -1. */
149 void *attr_info; /* attribute information (INTERNAL USE ONLY) */
150 };
151
152 /* information about an object */
153 struct rpsl_object {
154 GList *attributes; /* ordered attributes for this object */
155 GHashTable *attr_lookup; /* hash table used to do by-name lookups */
156 GList *errors; /* any errors with this object */
157 void *class_info; /* class information (INTERNAL USE ONLY) */
158 };
159
160 /* default column to start data on */
161 #define RPSL_STD_COLUMN 14
162
163 /* Allow C++ code to link */
164 #ifdef __cplusplus
165 extern "C" {
166 #endif
167
168 /* prototypes */
169 extern rpsl_attr_t *rpsl_attr_init(const gchar *s, const gchar *class);
170 extern rpsl_attr_t *rpsl_attr_copy(const rpsl_attr_t *attr);
171 extern rpsl_attr_t *rpsl_attr_clean_copy(const rpsl_attr_t *attr);
172 extern void rpsl_attr_delete(rpsl_attr_t *attr);
173 extern void rpsl_attr_delete_list(GList *attributes);
174 extern const gchar *rpsl_attr_get_name(const rpsl_attr_t *attr);
175 extern gint rpsl_attr_get_ofs(const rpsl_attr_t *attr);
176 extern const gchar *rpsl_attr_get_value(const rpsl_attr_t *attr);
177 extern gchar *rpsl_attr_get_clean_value(const rpsl_attr_t *attr);
178 extern GList *rpsl_attr_get_split_list(const rpsl_attr_t *attr);
179 extern void rpsl_attr_replace_value(rpsl_attr_t *attr, const gchar *value);
180 extern const GList *rpsl_attr_errors(const rpsl_attr_t *attr);
181
182 extern rpsl_object_t *rpsl_object_init(const gchar *s);
183 extern rpsl_object_t *rpsl_object_copy(const rpsl_object_t *object);
184 extern rpsl_object_t *rpsl_object_copy_flattened(const rpsl_object_t *object);
185 extern void rpsl_object_delete(rpsl_object_t *object);
186 extern const char *rpsl_object_get_class(const rpsl_object_t *object);
187 extern gchar *rpsl_object_get_text(const rpsl_object_t *object,
188 guint data_column);
189 extern gint rpsl_object_get_num_attr(const rpsl_object_t *object);
190 extern const GList *rpsl_object_get_all_attr(const rpsl_object_t *object);
191 extern GList *rpsl_object_get_attr(const rpsl_object_t *object,
192 const gchar *name);
193 extern const rpsl_attr_t *rpsl_object_get_attr_by_ofs(const rpsl_object_t *object,
194 gint ofs);
195 extern int rpsl_object_append_attr(rpsl_object_t *object,
196 rpsl_attr_t *attr,
197 rpsl_error_t *error);
198 extern int rpsl_object_add_attr(rpsl_object_t *object,
199 rpsl_attr_t *attr,
200 gint ofs,
201 rpsl_error_t *error);
202 extern rpsl_attr_t *rpsl_object_remove_attr(rpsl_object_t *object,
203 gint ofs,
204 rpsl_error_t *error);
205 extern rpsl_attr_t *rpsl_object_remove_attr_name(rpsl_object_t *object,
206 const gchar *name,
207 rpsl_error_t *error);
208 extern const GList *rpsl_object_errors(const rpsl_object_t *object);
209
210 extern gboolean rpsl_attr_is_required(const rpsl_object_t *object,
211 const gchar *attr);
212 extern gboolean rpsl_attr_is_multivalued(const rpsl_object_t *object,
213 const gchar *attr);
214 extern gboolean rpsl_attr_is_lookup(const rpsl_object_t *object,
215 const gchar *attr);
216 extern gboolean rpsl_attr_is_key(const rpsl_object_t *object,
217 const gchar *attr);
218 extern gboolean rpsl_attr_is_generated(const rpsl_object_t *object,
219 const gchar *attr);
220 extern gboolean rpsl_object_is_deleted(const rpsl_object_t *object);
221
222 extern gboolean rpsl_attr_has_error(const rpsl_attr_t *attr, int error_level);
223 extern gboolean rpsl_object_has_error(const rpsl_object_t *object,
224 int error_level);
225
226 gint rpsl_get_attr_id(const gchar *attr_name);
227 gint rpsl_get_class_id(const gchar *class_name);
228
229 extern void rpsl_load_dictionary(int level);
230 extern int rpsl_read_dictionary();
231
232 #ifdef __cplusplus
233 }
234 #endif /* C++ */
235
236 #endif /* SYNTAX_API_H */