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, five different flags that can be set for features, and six
  12 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.
  35
  36 Feature Flags
  37
  38 There are five feature flags, one of which is used internally by the
  39 feature subsystem.  Two of these flags, FEAT_OPER and FEAT_MYOPER, are
  40 used to select who can see the settings of those features; FEAT_OPER
  41 permits any operator anywhere on the network to examine the settings
  42 of a particular feature, whereas FEAT_MYOPER only permits operators
  43 local to a server to examine feature values.  If neither of these two
  44 flags is specified, then any user may examine that feature's value.
  45
  46 The other two flags only have any meaning for string values; they are
  47 FEAT_NULL, which is used to specify that a feature of type "STR" may
  48 have a NULL value, and FEAT_CASE, which specifies that the feature is
  49 case sensitive--this may be used on file names, for example.
  50
  51 Marking Features
  52
  53 When the configuration file is read, there must be some way to
  54 determine if a particular F-line has been removed since the last time
  55 the configuration file was read.  The way this is done in the features
  56 subsystem is to have a "mark" for each feature.  Prior to reading the
  57 configuration file, all marks are cleared for all features (and all
  58 "unmark" call-backs are called).  As each F-line is encountered and
  59 processed, that feature's mark is set.  Finally, when the
  60 configuration file has been fully read, all remaining unmarked
  61 features are reset to their default values (and all "mark" call-backs
  62 are called).
  63
  64 Adding New Features
  65
  66 To add a new feature, first determine the feature's name (which must
  67 begin with the string "FEAT_") and its type ("NONE," "INT," "BOOL," or
  68 "STR").  Then add the feature to the enum Feature in an appropriate
  69 place (i.e., it's good to group all features affecting operators
  70 separate from those features affecting networking code), and a
  71 corresponding entry in the features[] table in ircd_features.c.  It
  72 will be best to use one of the F_?() macros, which are documented
  73 below.  Then, whenever you need to refer to the value of a specific
  74 feature, call the appropriate feature_<type>() function, as documented
  75 below.
  76
  77 <enum>
  78 enum Feature;
  79
  80 The "Feature" enum lists all of the features known to the feature
  81 subsystem.  Each feature name *must* begin with "FEAT_"; the portion
  82 of the name following "FEAT_" will be what you use to set the feature
  83 from the configuration file or with the "set" or "reset" commands.
  84 </enum>
  85
  86 <function>
  87 int feature_set(struct Client* from, const char* const* fields, int count);
  88
  89 The feature_set() function takes an array of strings and a count of
  90 the number of strings in the array.  The first string is a feature
  91 name, and, for most features, the second string will be that feature's
  92 value.  The _from_ parameter is the struct Client describing the user
  93 that issued the "set" command.  This parameter may be NULL if
  94 feature_set() is being called from the configuration file subsystem.
  95 </function>
  96
  97 <function>
  98 int feature_reset(struct Client* from, const char* const* fields, int count);
  99
 100 The feature_reset() function is very similar in arguments to the
 101 feature_set() function, except that it may not be called from the
 102 configuration file subsystem.  It resets the named feature to its
 103 default value.
 104 </function>
 105
 106 <function>
 107 int feature_get(struct Client* from, const char* const* fields, int count);
 108
 109 Again, feature_get() is very similar in arguments to the feature_set()
 110 function, except that again it may not be called from the
 111 configuration file subsystem.  It reports the value of the named
 112 feature to the user that issued the "get" command.
 113 </function>
 114
 115 <function>
 116 void feature_unmark(void);
 117
 118 This function is used to unmark all feature values, as described in
 119 the subsection "Marking Features."  It takes no arguments and returns
 120 nothing.
 121 </function>
 122
 123 <function>
 124 void feature_mark(void);
 125
 126 The complement to feature_unmark(), feature_mark() resets all
 127 unchanged feature settings to their defaults.  See the subsection on
 128 "Marking Features."
 129 </function>
 130
 131 <function>
 132 void feature_report(struct Client* to);
 133
 134 Reports all F-lines to a user using RPL_STATSFLINE, except those which
 135 the user is not permitted to see due to flag settings.
 136 </function>
 137
 138 <function>
 139 int feature_int(enum Feature feat);
 140
 141 To retrieve the values of integer features, call this function.
 142 Calling this function on a different type of feature, such as a "BOOL"
 143 feature, will result in an assertion failure.
 144 </function>
 145
 146 <function>
 147 int feature_bool(enum Feature feat);
 148
 149 This function is the complement of feature_int() for features of type
 150 "BOOL."
 151 </function>
 152
 153 <function>
 154 const char *feature_str(enum Feature feat);
 155
 156 Use this function to retrieve strings values for features of type
 157 "STR"; you may not modify nor free the string value.
 158 </function>
 159
 160 <macro>
 161 #define F_N(type, flags, set, reset, get, unmark, mark, report)
 162
 163 This macro is used in the features[] table to simplify defining a
 164 feature of type "NONE."  The _type_ parameter is the name of the
 165 feature excluding the "FEAT_" prefix, and MUST NOT be in
 166 double-quotes.  The _flags_ parameter may be 0, FEAT_OPER, or
 167 FEAT_MYOPER--the bitwise OR of these two flags is permissible but
 168 would not make sense.  The rest of the arguments are pointers to
 169 functions implementing the named call-back.
 170 </macro>
 171
 172 <macro>
 173 #define F_I(type, flags, v_int)
 174
 175 To define integer features, use the F_I() macro.  The _type_ and
 176 _flags_ parameters are as for F_N(), and the _v_int_ macro specifies
 177 the default value of the feature.
 178 </macro>
 179
 180 <macro>
 181 #define F_B(type, flags, v_int)
 182
 183 This macro is used for defining features of type "BOOL"; it is very
 184 similar to F_I(), but _v_int_ should either 0 (for a "FALSE" value) or
 185 1 (for a "TRUE" value).
 186 </macro>
 187
 188 <macro>
 189 #define F_S(type, flags, v_str)
 190
 191 Also similar to F_I(), F_S() defines features of type "STR."  The
 192 _flags_ argument may be the bitwise OR of one of FEAT_OPER or
 193 FEAT_MYOPER with the special string flags FEAT_NULL and FEAT_CASE,
 194 which are described above in the section "Feature Flags."
 195 </macro>
 196
 197 <authors>
 198 Kev <klmitch@mit.edu>
 199 </authors>
 200
 201 <changelog>
 202 [2000-12-18 Kev] Document the features API
 203 </changelog>