set.h

   1   /********************************************************************\
   2   * BitlBee -- An IRC to other IM-networks gateway                     *
   3   *                                                                    *
   4   * Copyright 2002-2006 Wilmer van der Gaast and others                *
   5   \********************************************************************/
   6
   7 /* Some stuff to register, handle and save user preferences             */
   8
   9 /*
  10   This program is free software; you can redistribute it and/or modify
  11   it under the terms of the GNU General Public License as published by
  12   the Free Software Foundation; either version 2 of the License, or
  13   (at your option) any later version.
  14
  15   This program is distributed in the hope that it will be useful,
  16   but WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18   GNU General Public License for more details.
  19
  20   You should have received a copy of the GNU General Public License with
  21   the Debian GNU/Linux distribution in /usr/share/common-licenses/GPL;
  22   if not, write to the Free Software Foundation, Inc., 59 Temple Place,
  23   Suite 330, Boston, MA  02111-1307  USA
  24 */
  25
  26 #ifndef __SET_H__
  27 #define __SET_H__
  28
  29 struct set;
  30
  31 /* This used to be specific to irc_t structures, but it's more generic now
  32    (so it can also be used for account_t structs). It's pretty simple, but
  33    so far pretty useful.
  34
  35    In short, it just keeps a linked list of settings/variables and it also
  36    remembers a default value for every setting. And to prevent the user
  37    from setting invalid values, you can write an evaluator function for
  38    every setting, which can check a new value and block it by returning
  39    NULL, or replace it by returning a new value. See struct set.eval.
  40    One thing that is really missing here is additional data for the
  41    evaluator. This could be useful to add minimum and maximum values for
  42    integers, for example. */
  43
  44 typedef char *(*set_eval) ( struct set *set, char *value );
  45
  46 extern char *SET_INVALID;
  47
  48 #define SET_NULL_OK        0x0100
  49
  50 typedef struct set
  51 {
  52         void *data;     /* Here you can save a pointer to the
  53                            object this settings belongs to. */
  54
  55         char *key;
  56         char *value;
  57         char *def;      /* Default value. If the set_setstr() function
  58                            notices a new value is exactly the same as
  59                            the default, value gets set to NULL. So when
  60                            you read a setting, don't forget about this!
  61                            In fact, you should only read values using
  62                            set_getstr/int(). */
  63
  64         int flags;      /* See account.h, for example. set.c doesn't use
  65                            this (yet?). */
  66
  67         /* Eval: Returns SET_INVALID if the value is incorrect or exactly
  68            the passed value variable. When returning a corrected value,
  69            set_setstr() should be able to free() the returned string! */
  70         set_eval eval;
  71         struct set *next;
  72 } set_t;
  73
  74 /* Should be pretty clear. */
  75 set_t *set_add( set_t **head, char *key, char *def, set_eval eval, void *data );
  76
  77 /* Returns the raw set_t. Might be useful sometimes. */
  78 set_t *set_find( set_t **head, char *key );
  79
  80 /* Returns a pointer to the string value of this setting. Don't modify the
  81    returned string, and don't free() it! */
  82 G_MODULE_EXPORT char *set_getstr( set_t **head, char *key );
  83
  84 /* Get an integer. In previous versions set_getint() was also used to read
  85    boolean values, but this SHOULD be done with set_getbool() now! */
  86 G_MODULE_EXPORT int set_getint( set_t **head, char *key );
  87 G_MODULE_EXPORT int set_getbool( set_t **head, char *key );
  88
  89 /* set_setstr() strdup()s the given value, so after using this function
  90    you can free() it, if you want. */
  91 int set_setstr( set_t **head, char *key, char *value );
  92 int set_setint( set_t **head, char *key, int value );
  93 void set_del( set_t **head, char *key );
  94 int set_reset( set_t **head, char *key );
  95
  96 /* Two very useful generic evaluators. */
  97 char *set_eval_int( set_t *set, char *value );
  98 char *set_eval_bool( set_t *set, char *value );
  99
 100 /* Some not very generic evaluators that really shouldn't be here... */
 101 char *set_eval_to_char( set_t *set, char *value );
 102 char *set_eval_ops( set_t *set, char *value );
 103
 104 #endif /* __SET_H__ */