doc/api/features.txt

   1 As of u2.10.11, most of the compile-time configuration options present
   2 in previous versions of ircu have been provided via the configuration
   3 file as "features."  This document is intended not only to give an
   4 explanation of how to use the features subsystem in new code, but also
   5 how to define new features.
   6
   7 In the ircd_features.h header file is an enum Feature that lists all
   8 the features known to the features subsystem.  The order of entries in
   9 this list must match precisely the order of features as listed in the
  10 features[] table in ircd_features.c.  There are four kinds of
  11 features, seven different flags that can be set for features, and
  12 seven different call-backs for more complex features.
  13
  14 Types of Features
  15
  16 There are at present four different types of features: NONE, INT,
  17 BOOL, and STR.  Features of type "NONE" are complex features, such as
  18 the logging subsystem, that have complicated behavior that's managed
  19 through the use of call-backs.  The call-backs available are set,
  20 which is called to set the value of the feature; reset, which is
  21 called to reset the value of the feature back to its default; get,
  22 which is called to send the user a RPL_FEATURE to describe the feature
  23 setting; unmark, which is called prior to reading the configuration
  24 file; mark, which is called after reading the configuration file; and
  25 report, which is used to send a user a list of RPL_STATSFLINE
  26 replies.
  27
  28 In comparison to type "NONE," the other types are very simple.  Type
  29 "INT" is used for features that take an integer value; "BOOL" is for
  30 those features that are boolean types; and "STR" is for those features
  31 that take simple string values.  The values for these feature types
  32 are handled directly by the features subsystem, and can be examined
  33 from code with the feature_int(), feature_bool(), and feature_str()
  34 functions, described below.  These features have a notify callback,
  35 which is used to warn subsystems that use the values of particular
  36 features that the value has changed.
  37
  38 Feature Flags
  39
  40 There are seven feature flags, one of which is used internally by the
  41 feature subsystem.  Three of these flags, FEAT_OPER, FEAT_MYOPER, and
  42 FEAT_NODISP, are used to select who can see the settings of those
  43 features; FEAT_OPER permits any operator anywhere on the network to
  44 examine the settings of a particular feature, whereas FEAT_MYOPER only
  45 permits operators local to a server to examine feature values, and
  46 FEAT_NODISP prohibits display of the feature value altogether.  If
  47 none of these three flags are specified, then any user may examine
  48 that feature's value.
  49
  50 Two other flags only have any meaning for string values; they are
  51 FEAT_NULL, which is used to specify that a feature of type "STR" may
  52 have a NULL value, and FEAT_CASE, which specifies that the feature is
  53 case sensitive--this may be used on file names, for example.  Note
  54 that if you give "0" as the default value for a feature, you must also
  55 set the FEAT_NULL flag.
  56
  57 The remaining non-internal flag is FEAT_READ, which simply sets the
  58 feature to be read-only; a feature so marked may only be changed
  59 through the configuration file.
  60
  61 Marking Features
  62
  63 When the configuration file is read, there must be some way to
  64 determine if a particular Feature entry has been removed since the
  65 last time the configuration file was read.  The way this is done in
  66 the features subsystem is to have a "mark" for each feature.  Prior to
  67 reading the configuration file, all marks are cleared for all features
  68 (and all "unmark" call-backs are called).  As each Feature entry is
  69 encountered and processed, that feature's mark is set.  Finally, when
  70 the configuration file has been fully read, all remaining unmarked
  71 features are reset to their default values (and all "mark" call-backs
  72 are called).
  73
  74 Adding New Features
  75
  76 To add a new feature, first determine the feature's name (which must
  77 begin with the string "FEAT_") and its type ("NONE," "INT," "BOOL," or
  78 "STR").  Then add the feature to the enum Feature in an appropriate
  79 place (i.e., it's good to group all features affecting operators
  80 separate from those features affecting networking code), and a
  81 corresponding entry in the features[] table in ircd_features.c.  It
  82 will be best to use one of the F_?() macros, which are documented
  83 below.  Then, whenever you need to refer to the value of a specific
  84 feature, call the appropriate feature_<type>() function, as documented
  85 below.
  86
  87 <enum>
  88 enum Feature;
  89
  90 The "Feature" enum lists all of the features known to the feature
  91 subsystem.  Each feature name *must* begin with "FEAT_"; the portion
  92 of the name following "FEAT_" will be what you use to set the feature
  93 from the configuration file or with the "set" or "reset" commands.
  94 </enum>
  95
  96 <function>
  97 int feature_set(struct Client* from, const char* const* fields, int count);
  98
  99 The feature_set() function takes an array of strings and a count of
 100 the number of strings in the array.  The first string is a feature
 101 name, and, for most features, the second string will be that feature's
 102 value.  The _from_ parameter is the struct Client describing the user
 103 that issued the "set" command.  This parameter may be NULL if
 104 feature_set() is being called from the configuration file subsystem.
 105 </function>
 106
 107 <function>
 108 int feature_reset(struct Client* from, const char* const* fields, int count);
 109
 110 The feature_reset() function is very similar in arguments to the
 111 feature_set() function, except that it may not be called from the
 112 configuration file subsystem.  It resets the named feature to its
 113 default value.
 114 </function>
 115
 116 <function>
 117 int feature_get(struct Client* from, const char* const* fields, int count);
 118
 119 Again, feature_get() is very similar in arguments to the feature_set()
 120 function, except that again it may not be called from the
 121 configuration file subsystem.  It reports the value of the named
 122 feature to the user that issued the "get" command.
 123 </function>
 124
 125 <function>
 126 void feature_unmark(void);
 127
 128 This function is used to unmark all feature values, as described in
 129 the subsection "Marking Features."  It takes no arguments and returns
 130 nothing.
 131 </function>
 132
 133 <function>
 134 void feature_mark(void);
 135
 136 The complement to feature_unmark(), feature_mark() resets all
 137 unchanged feature settings to their defaults.  See the subsection on
 138 "Marking Features."
 139 </function>
 140
 141 <function>
 142 void feature_init(void);
 143
 144 This function initializes the feature interface by setting the default
 145 values for all features correctly.
 146 </function>
 147
 148 <function>
 149 void feature_report(struct Client* to);
 150
 151 Reports all Feature entries to a user using RPL_STATSFLINE, except
 152 those which the user is not permitted to see due to flag settings.
 153 </function>
 154
 155 <function>
 156 int feature_int(enum Feature feat);
 157
 158 To retrieve the values of integer features, call this function.
 159 Calling this function on a different type of feature, such as a "BOOL"
 160 feature, will result in an assertion failure.
 161 </function>
 162
 163 <function>
 164 int feature_bool(enum Feature feat);
 165
 166 This function is the complement of feature_int() for features of type
 167 "BOOL."
 168 </function>
 169
 170 <function>
 171 const char *feature_str(enum Feature feat);
 172
 173 Use this function to retrieve strings values for features of type
 174 "STR"; you may not modify nor free the string value.
 175 </function>
 176
 177 <macro>
 178 #define F_N(type, flags, set, reset, get, notify, unmark, mark, report)
 179
 180 This macro is used in the features[] table to simplify defining a
 181 feature of type "NONE."  The _type_ parameter is the name of the
 182 feature excluding the "FEAT_" prefix, and MUST NOT be in
 183 double-quotes.  The _flags_ parameter may be 0, FEAT_OPER, or
 184 FEAT_MYOPER--the bitwise OR of these two flags is permissible but
 185 would not make sense.  The rest of the arguments are pointers to
 186 functions implementing the named call-back.
 187 </macro>
 188
 189 <macro>
 190 #define F_I(type, flags, v_int, notify)
 191
 192 To define integer features, use the F_I() macro.  The _type_ and
 193 _flags_ parameters are as for F_N(), and the _v_int_ parameter
 194 specifies the default value of the feature.  The _notify_ parameter,
 195 if non-zero, will be called whenever the value of the feature changes.
 196 </macro>
 197
 198 <macro>
 199 #define F_B(type, flags, v_int, notify)
 200
 201 This macro is used for defining features of type "BOOL"; it is very
 202 similar to F_I(), but _v_int_ should either 0 (for a "FALSE" value) or
 203 1 (for a "TRUE" value).  The _notify_ parameter, if non-zero, will be
 204 called whenever the value of the feature changes.
 205 </macro>
 206
 207 <macro>
 208 #define F_S(type, flags, v_str, notify)
 209
 210 Also similar to F_I(), F_S() defines features of type "STR."  The
 211 _flags_ argument may be the bitwise OR of one of FEAT_OPER or
 212 FEAT_MYOPER with the special string flags FEAT_NULL and FEAT_CASE,
 213 which are described above in the section "Feature Flags."  The
 214 _notify_ parameter, if non-zero, will be called whenever the value of
 215 the feature changes.  Note that FEAT_NULL *must* be set if the default
 216 string _v_str_ is set to NULL.
 217 </macro>
 218
 219 <authors>
 220 Kev <klmitch@mit.edu>
 221 </authors>
 222
 223 <changelog>
 224 [2001-06-13 Kev] Mention notify with the other callbacks
 225
 226 [2001-01-02 Kev] Add documentation for new flags and for the notify
 227 mechanism
 228
 229 [2000-12-18 Kev] Document the features API
 230 </changelog>