modules/rpsl/syntax_api.h

/* [<][>][^][v][top][bottom][index][help] */

DEFINITIONS

This source file includes following functions.
  1. rpsl_object_t
  2. rpsl_attr_t
  3. rpsl_error_t
  4. 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 */

/* [<][>][^][v][top][bottom][index][help] */