/* [<][>][^][v][top][bottom][index][help] */
DEFINITIONS
This source file includes following functions.
- rpsl_object_t
- rpsl_attr_t
- rpsl_error_t
- rpsl_template_t
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;
/* [<][>][^][v][top][bottom][index][help] */
88 typedef struct rpsl_attr rpsl_attr_t;
/* [<][>][^][v][top][bottom][index][help] */
89 typedef struct rpsl_error rpsl_error_t;
/* [<][>][^][v][top][bottom][index][help] */
90 typedef struct rpsl_template rpsl_template_t;
/* [<][>][^][v][top][bottom][index][help] */
91
92 /* strictness of checking */
93 enum {
94 RPSL_DICT_CORE,
95 RPSL_DICT_FRONT_END
96 };
97
98 /* various RPSL error levels (similar as syslog errors) */
99 enum {
100 RPSL_ERRLVL_NONE,
101 RPSL_ERRLVL_DEBUG,
102 RPSL_ERRLVL_INFO,
103 RPSL_ERRLVL_NOTICE,
104 RPSL_ERRLVL_WARN,
105 RPSL_ERRLVL_ERROR,
106 RPSL_ERRLVL_CRIT,
107 RPSL_ERRLVL_FATAL
108 };
109
110 /* error codes */
111 enum {
112 /* attribute-related errors */
113 RPSL_ERR_BADATTR,
114 RPSL_ERR_UNKNOWNATTR,
115 RPSL_ERR_EMPTYLIST,
116 RPSL_ERR_EMPTYATTR,
117 RPSL_ERR_SYNERR,
118 /* object-related errors */
119 RPSL_ERR_ONLYCOMMENTS,
120 RPSL_ERR_BADCLASS,
121 RPSL_ERR_UNKNOWNCLASS,
122 RPSL_ERR_ATTRNOTALLOWED,
123 RPSL_ERR_ATTRSINGLE,
124 RPSL_ERR_ATTRGENERATED,
125 RPSL_ERR_MISSINGATTR,
126 RPSL_ERR_MISSINGKEY,
127 /* modification-related errors */
128 RPSL_ERR_BADOFFSET,
129 RPSL_ERR_NOSUCHATTR
130 };
131
132 /* per-attribute errors */
133 struct rpsl_error {
134 gint level; /* level of the error (enum above) */
135 gint code; /* code for the error */
136 gchar *descr; /* description of the error */
137 gint attr_num; /* offset of attribute with this error, or
138 -1 if none */
139 };
140
141 /* information about an attribute */
142 struct rpsl_attr {
143 gchar *name; /* name, e.g. "inetnum" or "person" */
144 gchar *lcase_name; /* lower-case version of the name */
145 gchar *value; /* value of the object, e.g. "192.168.0.0/24" */
146 GList *errors; /* any errors with this attribute */
147 gint num; /* Position of attribute.
148 For class name, num = 0.
149 For attributes not in a class, num = -1. */
150 void *attr_info; /* attribute information (INTERNAL USE ONLY) */
151 };
152
153 /* information about an object */
154 struct rpsl_object {
155 GList *attributes; /* ordered attributes for this object */
156 GHashTable *attr_lookup; /* hash table used to do by-name lookups */
157 GList *errors; /* any errors with this object */
158 void *class_info; /* class information (INTERNAL USE ONLY) */
159 };
160
161 /* information about a class */
162 struct rpsl_template {
163 gchar *name; /* "person", "descr", ... */
164 gchar *code; /* "pn", "de", ... */
165 gboolean is_required; /* mandatory/optional */
166 gboolean is_generated; /* generated/user-specified */
167 gboolean is_multivalued; /* single/multiple */
168 gboolean is_lookup; /* lookup key */
169 gboolean is_inverse; /* inverse key */
170 gboolean is_primary; /* primary key */
171 gboolean is_list; /* RPSL list (comma-separated) */
172 gboolean is_ripe_list; /* RIPE list (space-separated) */
173 };
174
175 /* default column to start data on */
176 #define RPSL_STD_COLUMN 14
177
178 /* Allow C++ code to link */
179 #ifdef __cplusplus
180 extern "C" {
181 #endif
182
183 /* prototypes */
184 extern rpsl_attr_t *rpsl_attr_init(const gchar *s, const gchar *class);
185 extern rpsl_attr_t *rpsl_attr_copy(const rpsl_attr_t *attr);
186 extern rpsl_attr_t *rpsl_attr_clean_copy(const rpsl_attr_t *attr);
187 extern void rpsl_attr_delete(rpsl_attr_t *attr);
188 extern void rpsl_attr_delete_list(GList *attributes);
189 extern const gchar *rpsl_attr_get_name(const rpsl_attr_t *attr);
190 extern gint rpsl_attr_get_ofs(const rpsl_attr_t *attr);
191 extern const gchar *rpsl_attr_get_value(const rpsl_attr_t *attr);
192 extern gchar *rpsl_attr_get_clean_value(const rpsl_attr_t *attr);
193 extern gchar *rpsl_attr_get_clean_lines(const rpsl_attr_t *attr);
194 extern GList *rpsl_attr_get_split_list(const rpsl_attr_t *attr);
195 extern void rpsl_attr_replace_value(rpsl_attr_t *attr, const gchar *value);
196 extern const GList *rpsl_attr_errors(const rpsl_attr_t *attr);
197
198 extern rpsl_object_t *rpsl_object_init(const gchar *s);
199 extern rpsl_object_t *rpsl_object_copy(const rpsl_object_t *object);
200 extern rpsl_object_t *rpsl_object_copy_flattened(const rpsl_object_t *object);
201 extern void rpsl_object_delete(rpsl_object_t *object);
202 extern const char *rpsl_object_get_class(const rpsl_object_t *object);
203 extern gchar *rpsl_object_get_text(const rpsl_object_t *object,
204 guint data_column);
205 extern gint rpsl_object_get_num_attr(const rpsl_object_t *object);
206 extern const GList *rpsl_object_get_all_attr(const rpsl_object_t *object);
207 extern GList *rpsl_object_get_attr(const rpsl_object_t *object,
208 const gchar *name);
209 extern const rpsl_attr_t *rpsl_object_get_attr_by_ofs(const rpsl_object_t *object,
210 gint ofs);
211 extern int rpsl_object_append_attr(rpsl_object_t *object,
212 rpsl_attr_t *attr,
213 rpsl_error_t *error);
214 extern int rpsl_object_add_attr(rpsl_object_t *object,
215 rpsl_attr_t *attr,
216 gint ofs,
217 rpsl_error_t *error);
218 extern rpsl_attr_t *rpsl_object_remove_attr(rpsl_object_t *object,
219 gint ofs,
220 rpsl_error_t *error);
221 extern rpsl_attr_t *rpsl_object_remove_attr_name(rpsl_object_t *object,
222 const gchar *name,
223 rpsl_error_t *error);
224 extern const GList *rpsl_object_errors(const rpsl_object_t *object);
225
226 extern gboolean rpsl_attr_is_required(const rpsl_object_t *object,
227 const gchar *attr);
228 extern gboolean rpsl_attr_is_multivalued(const rpsl_object_t *object,
229 const gchar *attr);
230 extern gboolean rpsl_attr_is_lookup(const rpsl_object_t *object,
231 const gchar *attr);
232 extern gboolean rpsl_attr_is_key(const rpsl_object_t *object,
233 const gchar *attr);
234 extern gboolean rpsl_attr_is_generated(const rpsl_object_t *object,
235 const gchar *attr);
236 extern gboolean rpsl_object_is_deleted(const rpsl_object_t *object);
237
238 extern gboolean rpsl_attr_has_error(const rpsl_attr_t *attr, int error_level);
239 extern gboolean rpsl_object_has_error(const rpsl_object_t *object,
240 int error_level);
241
242 gint rpsl_get_attr_id(const gchar *attr_name);
243 gint rpsl_get_class_id(const gchar *class_name);
244
245 extern void rpsl_load_dictionary(int level);
246 extern int rpsl_read_dictionary();
247
248 extern const gchar* const *rpsl_get_classes();
249 extern const rpsl_template_t* const *rpsl_get_template(const gchar *class);
250
251 #ifdef __cplusplus
252 }
253 #endif /* C++ */
254
255 #endif /* SYNTAX_API_H */