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
  41 typedef char *(*set_eval) ( struct set *set, char *value );
  42
  43 extern char *SET_INVALID;
  44
  45 typedef enum
  46 {
  47         SET_NOSAVE = 0x0001,
  48         SET_NULL_OK = 0x0100,
  49         SET_HIDDEN = 0x0200,
  50         SET_PASSWORD = 0x0400,
  51         SET_HIDDEN_DEFAULT = 0x0800,
  52 } set_flags_t;
  53
  54 typedef struct set
  55 {
  56         void *data;     /* Here you can save a pointer to the
  57                            object this settings belongs to. */
  58
  59         char *key;
  60         char *old_key;  /* Previously known as; for smooth upgrades. */
  61         char *value;
  62         char *def;      /* Default value. If the set_setstr() function
  63                            notices a new value is exactly the same as
  64                            the default, value gets set to NULL. So when
  65                            you read a setting, don't forget about this!
  66                            In fact, you should only read values using
  67                            set_getstr/int(). */
  68
  69         set_flags_t flags; /* Mostly defined per user. */
  70
  71         /* Eval: Returns SET_INVALID if the value is incorrect, exactly
  72            the passed value variable, or a corrected value. In case of
  73            the latter, set_setstr() will free() the returned string! */
  74         set_eval eval;
  75         void *eval_data;
  76         struct set *next;
  77 } set_t;
  78
  79 #define set_value( set ) ((set)->value) ? ((set)->value) : ((set)->def)
  80
  81 /* Should be pretty clear. */
  82 set_t *set_add( set_t **head, const char *key, const char *def, set_eval eval, void *data );
  83
  84 /* Returns the raw set_t. Might be useful sometimes. */
  85 set_t *set_find( set_t **head, const char *key );
  86
  87 /* Returns a pointer to the string value of this setting. Don't modify the
  88    returned string, and don't free() it! */
  89 G_MODULE_EXPORT char *set_getstr( set_t **head, const char *key );
  90
  91 /* Get an integer. In previous versions set_getint() was also used to read
  92    boolean values, but this SHOULD be done with set_getbool() now! */
  93 G_MODULE_EXPORT int set_getint( set_t **head, const char *key );
  94 G_MODULE_EXPORT int set_getbool( set_t **head, const char *key );
  95
  96 /* set_setstr() strdup()s the given value, so after using this function
  97    you can free() it, if you want. */
  98 int set_setstr( set_t **head, const char *key, char *value );
  99 int set_setint( set_t **head, const char *key, int value );
 100 void set_del( set_t **head, const char *key );
 101 int set_reset( set_t **head, const char *key );
 102
 103 /* returns true if a setting shall be shown to the user */
 104 int set_isvisible( set_t *set );
 105
 106 /* Two very useful generic evaluators. */
 107 char *set_eval_int( set_t *set, char *value );
 108 char *set_eval_bool( set_t *set, char *value );
 109
 110 /* Another more complicated one. */
 111 char *set_eval_list( set_t *set, char *value );
 112
 113 /* Some not very generic evaluators that really shouldn't be here... */
 114 char *set_eval_to_char( set_t *set, char *value );
 115 char *set_eval_oauth( set_t *set, char *value );
 116
 117 #endif /* __SET_H__ */