]>
Commit | Line | Data |
---|---|---|
189935b1 | 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> |