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 */

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