283 lines
10 KiB
Plaintext
283 lines
10 KiB
Plaintext
Generating and parsing channel mode strings is often a very
|
|
complicated process. The ModeBuf interface, along with the associated
|
|
mode parsing functions, attempt to make this much more programmatic.
|
|
The interface to the functions in this suite is itself very
|
|
complicated, unfortunately, though most of the complication is in the
|
|
effects of various flags on the operation of the functions.
|
|
|
|
<struct>
|
|
struct ModeBuf;
|
|
|
|
This structure is used to accumulate and describe several mode
|
|
changes. None of its fields are directly or indirectly accessible to
|
|
the application; a struct ModeBuf is only suitable for passing to the
|
|
modebuf_*() suite of functions. ModeBuf structures must be allocated
|
|
by the caller.
|
|
</struct>
|
|
|
|
<function>
|
|
void modebuf_init(struct ModeBuf *mbuf, struct Client *source,
|
|
struct Client *connect, struct Channel *chan,
|
|
unsigned int dest);
|
|
|
|
This function initializes a caller-allocated ModeBuf, _mbuf_, with the
|
|
given parameters. If the mode should not be sent to a particular
|
|
server, perhaps because it was received from that server, that server
|
|
should be specified by the _connect_ parameter. The channel the mode
|
|
change will take place on is given by the _chan_ parameter, and the
|
|
disposition of the mode is given by the _dest_ parameter, which is the
|
|
binary OR of the MODEBUF_DEST_* flags described below.
|
|
</function>
|
|
|
|
<macro>
|
|
#define MODEBUF_DEST_CHANNEL 0x0001 /* Mode is flushed to channel */
|
|
|
|
This flag, when set in a call to modebuf_init(), causes the accumulated
|
|
mode change to be sent to the channel (in client<->server protocol, of
|
|
course).
|
|
</macro>
|
|
|
|
<macro>
|
|
#define MODEBUF_DEST_SERVER 0x0002 /* Mode is flushed to server */
|
|
|
|
If other servers should be made aware of the mode change, this flag
|
|
should be passed to modebuf_init(). One time when the mode change may
|
|
not be passed is when processing the mode in a BURST message.
|
|
</macro>
|
|
|
|
<macro>
|
|
#define MODEBUF_DEST_OPMODE 0x0100 /* Send server mode as OPMODE */
|
|
|
|
This flag is used to tell the modebuf_*() suite to send an OPMODE
|
|
message to other servers, rather than an ordinary MODE message.
|
|
</macro>
|
|
|
|
<macro>
|
|
#define MODEBUF_DEST_DEOP 0x0200 /* Deop the offender */
|
|
|
|
When bouncing a mode change, giving this flag to modebuf_init() causes
|
|
the originating user to be deopped on the channel as part of the mode
|
|
bounce.
|
|
</macro>
|
|
|
|
<macro>
|
|
#define MODEBUF_DEST_BOUNCE 0x0400 /* Bounce the modes */
|
|
|
|
When a mode change is illegitimate, that is, when it originates from a
|
|
user that is not (as far as this server knows) a channel operator, the
|
|
mode change should be bounced. This involves reversing the sense of
|
|
the mode and sending it back to the originating server. This flag is
|
|
used to tell the modebuf_*() suite to do just that.
|
|
</macro>
|
|
|
|
<macro>
|
|
#define MODEBUF_DEST_LOG 0x0800 /* Log the mode changes to OPATH */
|
|
|
|
The OPMODE command is reserved for IRC operators. When it is used,
|
|
the server should log the command for accountability purposes. This
|
|
flag, given to modebuf_init(), will cause the ModeBuf system to log
|
|
the exact mode change to a log file.
|
|
</macro>
|
|
|
|
<macro>
|
|
#define MODEBUF_DEST_HACK2 0x2000 /* Send a HACK(2) notice, reverse */
|
|
|
|
When a remote user that this server does not think is a channel
|
|
operator proceeds to change a channel mode, that mode must be
|
|
bounced. In addition, in order to provide some debugging capability,
|
|
a server notice may be sent, called a "HACK(2)" notice. Passing
|
|
modebuf_init() this flag causes that notice to be sent.
|
|
</macro>
|
|
|
|
<macro>
|
|
#define MODEBUF_DEST_HACK3 0x4000 /* Send a HACK(3) notice, TS == 0 */
|
|
|
|
When the origin of a mode change is a server, we should always accept
|
|
the mode change. To provide accountability, however, a server notice
|
|
should be sent. This flag will cause the server to generate a
|
|
"HACK(3)" notice.
|
|
</macro>
|
|
|
|
<macro>
|
|
#define MODEBUF_DEST_HACK4 0x8000 /* Send a HACK(4) notice, TS == 0 */
|
|
|
|
Some servers are special. When a server that has a Uworld entry
|
|
issues a mode change, we send a "HACK(4)" message to differentiate it
|
|
from an ordinary server changing a channel mode. This is the flag
|
|
that must be passed to modebuf_init() to cause that behavior.
|
|
</macro>
|
|
|
|
<function>
|
|
void modebuf_mode(struct ModeBuf *mbuf, unsigned int mode);
|
|
|
|
Certain channel modes take no arguments. Those mode changes can be
|
|
fed to the ModeBuf system using modebuf_mode(). The _mode_ parameter
|
|
is a bit mask of the mode changes, and must have one of MODE_ADD or
|
|
MODE_DEL set.
|
|
</function>
|
|
|
|
<function>
|
|
void modebuf_mode_uint(struct ModeBuf *mbuf, unsigned int mode,
|
|
unsigned int uint);
|
|
|
|
One channel mode, the "limit" mode ("+l"), takes a single integer
|
|
argument. This limit can be fed to the ModeBuf system with the
|
|
modebuf_mode_uint() function. The _mode_ parameter must be the binary
|
|
OR of one of MODE_ADD or MODE_DEL with the MODE_LIMIT flag. The
|
|
_uint_ parameter specifies the limit.
|
|
</function>
|
|
|
|
<function>
|
|
void modebuf_mode_string(struct ModeBuf *mbuf, unsigned int mode,
|
|
char *string, int free);
|
|
|
|
Some channel modes take a string parameter. These can be fed to
|
|
ModeBuf with modebuf_mode_string(). The _mode_ parameter should be
|
|
the binary OR of one of MODE_ADD or MODE_DEL with the flag for the
|
|
mode. The _string_ parameter specifies the string, and the _free_
|
|
parameter indicates whether the ModeBuf system should call MyFree() on
|
|
the string once it is done with it.
|
|
</function>
|
|
|
|
<function>
|
|
void modebuf_mode_client(struct ModeBuf *mbuf, unsigned int mode,
|
|
struct Client *client);
|
|
|
|
The remaining channel modes take a parameter specifying a client.
|
|
These can be fed to ModeBuf with modebuf_mode_client(). The _mode_
|
|
parameter should be the binary OR of one of MODE_ADD or MODE_DEL with
|
|
the flag for the mode. The _client_ parameter should be a pointer to
|
|
a struct Client specifying which client the mode is supposed to act
|
|
upon.
|
|
</function>
|
|
|
|
<function>
|
|
int modebuf_flush(struct ModeBuf *mbuf);
|
|
|
|
This function simply flushes the contents of the struct ModeBuf
|
|
specified by _mbuf_ to the appropriate destinations, as was specified
|
|
by the _dest_ parameter in the call to modebuf_init(). This function
|
|
returns 0 for the convenience of callers that must return an integer.
|
|
</function>
|
|
|
|
<function>
|
|
void modebuf_extract(struct ModeBuf *mbuf, char *buf);
|
|
|
|
One use of the ModeBuf within ircd requires the ability to pull a
|
|
simple mode string out of the struct ModeBuf for use elsewhere. This
|
|
can be accomplished with this function. The _buf_ parameter should be
|
|
large enough to accommodate the simple mode string.
|
|
</function>
|
|
|
|
<function>
|
|
void mode_ban_invalidate(struct Channel *chan);
|
|
|
|
Looking up bans affecting a particular user can be a fairly expensive
|
|
operation, so the server caches the result of the lookup. Should the
|
|
ban list for a channel change, all the cached results must be
|
|
invalidated to force rechecking. This may be done with the
|
|
mode_ban_invalidate() function, which acts upon the channel given by
|
|
_chan_.
|
|
</function>
|
|
|
|
<function>
|
|
void mode_invite_clear(struct Channel *chan);
|
|
|
|
When a channel that was invite-only has the "+i" channel mode removed,
|
|
the invite list that the server keeps is no longer necessary. The
|
|
mode_invite_clear() function flushes that invite list for the channel
|
|
given by _chan_, reclaiming the memory used by the invite list.
|
|
</function>
|
|
|
|
<function>
|
|
int mode_parse(struct ModeBuf *mbuf, struct Client *cptr, struct Client *sptr,
|
|
struct Channel *chptr, int parc, char *parv[],
|
|
unsigned int flags);
|
|
|
|
This function parses a mode change command, given by the contents of
|
|
_parv[]_, and under the control of _flags_. The channel being modified
|
|
is given by _chptr_, the source of the change is given by _sptr_, and
|
|
the connection the change was received from is given by _cptr_. The
|
|
_parc_ parameter gives the count of the number of elements in the
|
|
_parv[]_ array. The ModeBuf must have already been initialized by a
|
|
call to modebuf_init(), described above. For more information on
|
|
_flags_, see the MODE_PARSE_* macros described below. This function
|
|
returns an integer indicating the number of elements of _parv[]_ it
|
|
used. The modebuf_flush() function must be called upon return from
|
|
mode_parse() to flush the mode changes to the channel.
|
|
</function>
|
|
|
|
<macro>
|
|
#define MODE_PARSE_SET 0x01 /* actually set channel modes */
|
|
|
|
When this flag is passed to mode_parse(), the channel mode being
|
|
parsed will actually be effected on the channel.
|
|
</macro>
|
|
|
|
<macro>
|
|
#define MODE_PARSE_STRICT 0x02 /* +m +n +t style not supported */
|
|
|
|
Users are permitted to send complicated mode commands like "MODE #foo
|
|
+m +n +t +k foo +i"; servers are not. Passing this flag to
|
|
mode_parse() causes it to strictly enforce this restriction.
|
|
</macro>
|
|
|
|
<macro>
|
|
#define MODE_PARSE_FORCE 0x04 /* force the mode to be applied */
|
|
|
|
Some mode changes are not permitted under normal circumstances. When
|
|
this flag is passed to mode_parse(), these mode changes will be
|
|
accepted.
|
|
</macro>
|
|
|
|
<macro>
|
|
#define MODE_PARSE_BOUNCE 0x08 /* we will be bouncing the modes */
|
|
|
|
This flag warns mode_parse() that the mode is to be bounced. This
|
|
will cause it to systematically feed each mode into ModeBuf in order
|
|
for that interface to generate the proper bounce messages.
|
|
</macro>
|
|
|
|
<macro>
|
|
#define MODE_PARSE_NOTOPER 0x10 /* send "not chanop" to user */
|
|
|
|
This flag is used to warn mode_parse() that the user generating the
|
|
mode change is not a channel operator. If the user attempts to change
|
|
a mode, an appropriate error message will be sent to the user (once).
|
|
</macro>
|
|
|
|
<macro>
|
|
#define MODE_PARSE_NOTMEMBER 0x20 /* send "not member" to user */
|
|
|
|
This flag is used to warn mode_parse() that the user generating the
|
|
mode change is not even on the channel. If the user attempts to
|
|
change a mode, an appropriate error message will be sent to the user
|
|
(once).
|
|
</macro>
|
|
|
|
<macro>
|
|
#define MODE_PARSE_WIPEOUT 0x40 /* wipe out +k and +l during burst */
|
|
|
|
When this flag is passed to mode_parse(), the channel key and limit
|
|
will be reversed if the mode string doesn't update them. This is used
|
|
for processing BURST messages.
|
|
</macro>
|
|
|
|
<macro>
|
|
#define MODE_PARSE_BURST 0x80 /* be even more strict w/extra args */
|
|
|
|
The BURST message is even more strict than a standard MODE message.
|
|
Processing *must* stop after reading the mode string itself, or
|
|
mode_parse() could gobble up arguments not intended for it. This flag
|
|
tells mode_parse() about this restriction.
|
|
</macro>
|
|
|
|
<authors>
|
|
Kev <klmitch@mit.edu>
|
|
</authors>
|
|
|
|
<changelog>
|
|
[2001-6-15 Kev] Initial documentation of the ModeBuf and mode parsing
|
|
subsystems.
|
|
</changelog>
|