include/gw-res.h

   1 /*
   2  * Copyright (c) 1995, the EUROPAGATE consortium (see below).
   3  *
   4  * The EUROPAGATE consortium members are:
   5  *
   6  *    University College Dublin
   7  *    Danmarks Teknologiske Videnscenter
   8  *    An Chomhairle Leabharlanna
   9  *    Consejo Superior de Investigaciones Cientificas
  10  *
  11  * Permission to use, copy, modify, distribute, and sell this software and
  12  * its documentation, in whole or in part, for any purpose, is hereby granted,
  13  * provided that:
  14  *
  15  * 1. This copyright and permission notice appear in all copies of the
  16  * software and its documentation. Notices of copyright or attribution
  17  * which appear at the beginning of any file must remain unchanged.
  18  *
  19  * 2. The names of EUROPAGATE or the project partners may not be used to
  20  * endorse or promote products derived from this software without specific
  21  * prior written permission.
  22  *
  23  * 3. Users of this software (implementors and gateway operators) agree to
  24  * inform the EUROPAGATE consortium of their use of the software. This
  25  * information will be used to evaluate the EUROPAGATE project and the
  26  * software, and to plan further developments. The consortium may use
  27  * the information in later publications.
  28  *
  29  * 4. Users of this software agree to make their best efforts, when
  30  * documenting their use of the software, to acknowledge the EUROPAGATE
  31  * consortium, and the role played by the software in their work.
  32  *
  33  * THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
  34  * EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
  35  * WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  36  * IN NO EVENT SHALL THE EUROPAGATE CONSORTIUM OR ITS MEMBERS BE LIABLE
  37  * FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF
  38  * ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA
  39  * OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND
  40  * ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE
  41  * USE OR PERFORMANCE OF THIS SOFTWARE.
  42  *
  43  */
  44
  45 /*
  46  * Resource management.
  47  *
  48  * Europagate, 1994-1995.
  49  *
  50  * $Log: gw-res.h,v $
  51  * Revision 1.6  1995/05/16 09:39:39  adam
  52  * LICENSE.
  53  *
  54  * Revision 1.5  1995/05/03  07:36:29  adam
  55  * New functions: gw_res_bool and gw_res_int.
  56  *
  57  * Revision 1.4  1995/04/19  12:12:02  adam
  58  * Resource system uses only one log debug level.
  59  *
  60  * Revision 1.3  1995/02/23  08:32:12  adam
  61  * Changed header.
  62  *
  63  * Revision 1.1.1.1  1995/02/09  17:27:12  adam
  64  * Initial version of email gateway under CVS control.
  65  *
  66  * Initial:       Dec  7, 94 (Adam Dickmeiss)
  67  */
  68 #ifndef GW_RES_H
  69 #define GW_RES_H
  70
  71 #define RES_DEBUG GW_LOG_DEBUGN(8)
  72
  73 typedef struct Gw_res_info *GwRes;   /* Gateway resource handle */
  74
  75 GwRes gw_res_init (void);
  76 /*
  77     A resource handle is returned by this function describing
  78     the empty resource.
  79  */
  80
  81 void gw_res_close (GwRes id);
  82 /*
  83     The resources described by 'id' are freed. No further references
  84     to 'id' are allowed.
  85  */
  86
  87 int gw_res_merge (GwRes id, const char *filename);
  88 /*
  89     The resources described by 'id' are merged by the contents of
  90     'filename'. If a resource is duplicated (in both resources 'id' and
  91     the file) the resource is set to the value specified in 'filename'.
  92
  93     This function returns 0 on success; -1 on failure ('filename'
  94     could not be read)
  95  */
  96
  97 const char *gw_res_get (GwRes id, const char *name, const char *def);
  98 /*
  99     The resource with name 'name' is checked in the resources represented
 100     by 'id'. If the resource is present a pointer to the value (null-
 101     terminated string) is returned. If the value is not present the
 102     value of 'def' is returned.
 103  */
 104
 105 int gw_res_put (GwRes id, const char *name, const char *value,
 106                 const char *fname);
 107 /*
 108     Change a resource - modify if it exists - add if not already
 109     there. The resource will have impact on the file name 'fname'.
 110     Use gw_res_commit (see below) to actually write to the
 111     resource file.
 112  */
 113
 114 int gw_res_commit (GwRes id, const char *fname);
 115 /*
 116     Rewrite the resource file 'fname'. If resources are modified/added
 117     then these will be written now.
 118  */
 119
 120
 121 int gw_res_trav (GwRes id, const char *fname, void (*tf)(const char *name,
 122                                                         const char *value));
 123 /*
 124     Traverse resources associated with file 'fname'. For each resource
 125     the handler 'tf' is invoked with name and value.
 126  */
 127
 128 int gw_res_bool (GwRes res, const char *name, int def_val);
 129 /*
 130     Return true(1) or false(0) depending on setting for name. If
 131     name doesn't exist, def_val is returned
 132  */
 133
 134 int gw_res_int (GwRes res, const char *name, int def_val);
 135 /*
 136     Treat value of name as integer. Issue warning (GW_LOG_WARN) if the value
 137     cannot be read as integer. If name doesn't exist, def_val is returned
 138  */
 139 /*
 140    GwRes file format.
 141
 142    A resource name must begin on column 0 on a  line. The name is followed
 143    by colon. The value of the resource comes after the colon. A value may
 144    span over several lines. Subsequent value lines are preceeded by one or
 145    more blanks (tab/space). Empty/blank lines are ignored. Lines beginning
 146    with # are treated as comments.
 147
 148    Example
 149     # Comment. Ignored
 150
 151     # Single line resource
 152     MaxSize: 1000
 153     # Multi line resource
 154     FatalMsg: A serious error
 155      occured. Aborting.
 156     # Yet another (danish):
 157     Warning: Advarsel, taenk
 158          dig om - inden du foretager dig noget.
 159
 160    The FatalMsg resource has the value "A serious error occured. Aborting.",
 161    and the Warning resource has the value
 162    "Advarsel, taenk dig om - inden du foretager dig noget." Note
 163    that all blanks used to separate subsequent lines are treated as exactly
 164    one blank.
 165 */
 166 #endif