doc/api/modebuf.txt

   1 Generating and parsing channel mode strings is often a very
   2 complicated process.  The ModeBuf interface, along with the associated
   3 mode parsing functions, attempt to make this much more programmatic.
   4 The interface to the functions in this suite is itself very
   5 complicated, unfortunately, though most of the complication is in the
   6 effects of various flags on the operation of the functions.
   7
   8 <struct>
   9 struct ModeBuf;
  10
  11 This structure is used to accumulate and describe several mode
  12 changes.  None of its fields are directly or indirectly accessible to
  13 the application; a struct ModeBuf is only suitable for passing to the
  14 modebuf_*() suite of functions.  ModeBuf structures must be allocated
  15 by the caller.
  16 </struct>
  17
  18 <function>
  19 void modebuf_init(struct ModeBuf *mbuf, struct Client *source,
  20                   struct Client *connect, struct Channel *chan,
  21                   unsigned int dest);
  22
  23 This function initializes a caller-allocated ModeBuf, _mbuf_, with the
  24 given parameters.  If the mode should not be sent to a particular
  25 server, perhaps because it was received from that server, that server
  26 should be specified by the _connect_ parameter.  The channel the mode
  27 change will take place on is given by the _chan_ parameter, and the
  28 disposition of the mode is given by the _dest_ parameter, which is the
  29 binary OR of the MODEBUF_DEST_* flags described below.
  30 </function>
  31
  32 <macro>
  33 #define MODEBUF_DEST_CHANNEL    0x0001  /* Mode is flushed to channel */
  34
  35 This flag, when set in a call to modebuf_init(), causes the accumulated
  36 mode change to be sent to the channel (in client<->server protocol, of
  37 course).
  38 </macro>
  39
  40 <macro>
  41 #define MODEBUF_DEST_SERVER     0x0002  /* Mode is flushed to server */
  42
  43 If other servers should be made aware of the mode change, this flag
  44 should be passed to modebuf_init().  One time when the mode change may
  45 not be passed is when processing the mode in a BURST message.
  46 </macro>
  47
  48 <macro>
  49 #define MODEBUF_DEST_OPMODE     0x0100  /* Send server mode as OPMODE */
  50
  51 This flag is used to tell the modebuf_*() suite to send an OPMODE
  52 message to other servers, rather than an ordinary MODE message.
  53 </macro>
  54
  55 <macro>
  56 #define MODEBUF_DEST_DEOP       0x0200  /* Deop the offender */
  57
  58 When bouncing a mode change, giving this flag to modebuf_init() causes
  59 the originating user to be deopped on the channel as part of the mode
  60 bounce.
  61 </macro>
  62
  63 <macro>
  64 #define MODEBUF_DEST_BOUNCE     0x0400  /* Bounce the modes */
  65
  66 When a mode change is illegitimate, that is, when it originates from a
  67 user that is not (as far as this server knows) a channel operator, the
  68 mode change should be bounced.  This involves reversing the sense of
  69 the mode and sending it back to the originating server.  This flag is
  70 used to tell the modebuf_*() suite to do just that.
  71 </macro>
  72
  73 <macro>
  74 #define MODEBUF_DEST_LOG        0x0800  /* Log the mode changes to OPATH */
  75
  76 The OPMODE command is reserved for IRC operators.  When it is used,
  77 the server should log the command for accountability purposes.  This
  78 flag, given to modebuf_init(), will cause the ModeBuf system to log
  79 the exact mode change to a log file.
  80 </macro>
  81
  82 <macro>
  83 #define MODEBUF_DEST_HACK2      0x2000  /* Send a HACK(2) notice, reverse */
  84
  85 When a remote user that this server does not think is a channel
  86 operator proceeds to change a channel mode, that mode must be
  87 bounced.  In addition, in order to provide some debugging capability,
  88 a server notice may be sent, called a "HACK(2)" notice.  Passing
  89 modebuf_init() this flag causes that notice to be sent.
  90 </macro>
  91
  92 <macro>
  93 #define MODEBUF_DEST_HACK3      0x4000  /* Send a HACK(3) notice, TS == 0 */
  94
  95 When the origin of a mode change is a server, we should always accept
  96 the mode change.  To provide accountability, however, a server notice
  97 should be sent.  This flag will cause the server to generate a
  98 "HACK(3)" notice.
  99 </macro>
 100
 101 <macro>
 102 #define MODEBUF_DEST_HACK4      0x8000  /* Send a HACK(4) notice, TS == 0 */
 103
 104 Some servers are special.  When a server that has a Uworld entry
 105 issues a mode change, we send a "HACK(4)" message to differentiate it
 106 from an ordinary server changing a channel mode.  This is the flag
 107 that must be passed to modebuf_init() to cause that behavior.
 108 </macro>
 109
 110 <function>
 111 void modebuf_mode(struct ModeBuf *mbuf, unsigned int mode);
 112
 113 Certain channel modes take no arguments.  Those mode changes can be
 114 fed to the ModeBuf system using modebuf_mode().  The _mode_ parameter
 115 is a bit mask of the mode changes, and must have one of MODE_ADD or
 116 MODE_DEL set.
 117 </function>
 118
 119 <function>
 120 void modebuf_mode_uint(struct ModeBuf *mbuf, unsigned int mode,
 121                        unsigned int uint);
 122
 123 One channel mode, the "limit" mode ("+l"), takes a single integer
 124 argument.  This limit can be fed to the ModeBuf system with the
 125 modebuf_mode_uint() function.  The _mode_ parameter must be the binary
 126 OR of one of MODE_ADD or MODE_DEL with the MODE_LIMIT flag.  The
 127 _uint_ parameter specifies the limit.
 128 </function>
 129
 130 <function>
 131 void modebuf_mode_string(struct ModeBuf *mbuf, unsigned int mode,
 132                          char *string, int free);
 133
 134 Some channel modes take a string parameter.  These can be fed to
 135 ModeBuf with modebuf_mode_string().  The _mode_ parameter should be
 136 the binary OR of one of MODE_ADD or MODE_DEL with the flag for the
 137 mode.  The _string_ parameter specifies the string, and the _free_
 138 parameter indicates whether the ModeBuf system should call MyFree() on
 139 the string once it is done with it.
 140 </function>
 141
 142 <function>
 143 void modebuf_mode_client(struct ModeBuf *mbuf, unsigned int mode,
 144                          struct Client *client);
 145
 146 The remaining channel modes take a parameter specifying a client.
 147 These can be fed to ModeBuf with modebuf_mode_client().  The _mode_
 148 parameter should be the binary OR of one of MODE_ADD or MODE_DEL with
 149 the flag for the mode.  The _client_ parameter should be a pointer to
 150 a struct Client specifying which client the mode is supposed to act
 151 upon.
 152 </function>
 153
 154 <function>
 155 int modebuf_flush(struct ModeBuf *mbuf);
 156
 157 This function simply flushes the contents of the struct ModeBuf
 158 specified by _mbuf_ to the appropriate destinations, as was specified
 159 by the _dest_ parameter in the call to modebuf_init().  This function
 160 returns 0 for the convenience of callers that must return an integer.
 161 </function>
 162
 163 <function>
 164 void modebuf_extract(struct ModeBuf *mbuf, char *buf);
 165
 166 One use of the ModeBuf within ircd requires the ability to pull a
 167 simple mode string out of the struct ModeBuf for use elsewhere.  This
 168 can be accomplished with this function.  The _buf_ parameter should be
 169 large enough to accommodate the simple mode string.
 170 </function>
 171
 172 <function>
 173 void mode_ban_invalidate(struct Channel *chan);
 174
 175 Looking up bans affecting a particular user can be a fairly expensive
 176 operation, so the server caches the result of the lookup.  Should the
 177 ban list for a channel change, all the cached results must be
 178 invalidated to force rechecking.  This may be done with the
 179 mode_ban_invalidate() function, which acts upon the channel given by
 180 _chan_.
 181 </function>
 182
 183 <function>
 184 void mode_invite_clear(struct Channel *chan);
 185
 186 When a channel that was invite-only has the "+i" channel mode removed,
 187 the invite list that the server keeps is no longer necessary.  The
 188 mode_invite_clear() function flushes that invite list for the channel
 189 given by _chan_, reclaiming the memory used by the invite list.
 190 </function>
 191
 192 <function>
 193 int mode_parse(struct ModeBuf *mbuf, struct Client *cptr, struct Client *sptr,
 194                struct Channel *chptr, int parc, char *parv[],
 195                unsigned int flags);
 196
 197 This function parses a mode change command, given by the contents of
 198 _parv[]_, and under the control of _flags_.  The channel being modified
 199 is given by _chptr_, the source of the change is given by _sptr_, and
 200 the connection the change was received from is given by _cptr_.  The
 201 _parc_ parameter gives the count of the number of elements in the
 202 _parv[]_ array.  The ModeBuf must have already been initialized by a
 203 call to modebuf_init(), described above.  For more information on
 204 _flags_, see the MODE_PARSE_* macros described below.  This function
 205 returns an integer indicating the number of elements of _parv[]_ it
 206 used.  The modebuf_flush() function must be called upon return from
 207 mode_parse() to flush the mode changes to the channel.
 208 </function>
 209
 210 <macro>
 211 #define MODE_PARSE_SET          0x01    /* actually set channel modes */
 212
 213 When this flag is passed to mode_parse(), the channel mode being
 214 parsed will actually be effected on the channel.
 215 </macro>
 216
 217 <macro>
 218 #define MODE_PARSE_STRICT       0x02    /* +m +n +t style not supported */
 219
 220 Users are permitted to send complicated mode commands like "MODE #foo
 221 +m +n +t +k foo +i"; servers are not.  Passing this flag to
 222 mode_parse() causes it to strictly enforce this restriction.
 223 </macro>
 224
 225 <macro>
 226 #define MODE_PARSE_FORCE        0x04    /* force the mode to be applied */
 227
 228 Some mode changes are not permitted under normal circumstances.  When
 229 this flag is passed to mode_parse(), these mode changes will be
 230 accepted.
 231 </macro>
 232
 233 <macro>
 234 #define MODE_PARSE_BOUNCE       0x08    /* we will be bouncing the modes */
 235
 236 This flag warns mode_parse() that the mode is to be bounced.  This
 237 will cause it to systematically feed each mode into ModeBuf in order
 238 for that interface to generate the proper bounce messages.
 239 </macro>
 240
 241 <macro>
 242 #define MODE_PARSE_NOTOPER      0x10    /* send "not chanop" to user */
 243
 244 This flag is used to warn mode_parse() that the user generating the
 245 mode change is not a channel operator.  If the user attempts to change
 246 a mode, an appropriate error message will be sent to the user (once).
 247 </macro>
 248
 249 <macro>
 250 #define MODE_PARSE_NOTMEMBER    0x20    /* send "not member" to user */
 251
 252 This flag is used to warn mode_parse() that the user generating the
 253 mode change is not even on the channel.  If the user attempts to
 254 change a mode, an appropriate error message will be sent to the user
 255 (once).
 256 </macro>
 257
 258 <macro>
 259 #define MODE_PARSE_WIPEOUT      0x40    /* wipe out +k and +l during burst */
 260
 261 When this flag is passed to mode_parse(), the channel key and limit
 262 will be reversed if the mode string doesn't update them.  This is used
 263 for processing BURST messages.
 264 </macro>
 265
 266 <macro>
 267 #define MODE_PARSE_BURST        0x80    /* be even more strict w/extra args */
 268
 269 The BURST message is even more strict than a standard MODE message.
 270 Processing *must* stop after reading the mode string itself, or
 271 mode_parse() could gobble up arguments not intended for it.  This flag
 272 tells mode_parse() about this restriction.
 273 </macro>
 274
 275 <authors>
 276 Kev <klmitch@mit.edu>
 277 </authors>
 278
 279 <changelog>
 280 [2001-6-15 Kev] Initial documentation of the ModeBuf and mode parsing
 281 subsystems.
 282 </changelog>