1 |
PREFIXES |
2 |
======== |
3 |
|
4 |
Server prefixes are the ":%s" strings at the beginning of messages. |
5 |
They are used by servers to route the message properly and by servers to |
6 |
local clients to update their idea of who is whom. |
7 |
|
8 |
":nick!user@host" is a prefix ":name" where name is either a nick |
9 |
or name of a server is another valid prefix. |
10 |
|
11 |
Typical prefix for a local client to a channel: |
12 |
|
13 |
":Dianora!db@irc.db.net" |
14 |
|
15 |
for a prefix to a remote server: |
16 |
":Dianora" |
17 |
|
18 |
e.g. as seen locally on a channel: |
19 |
|
20 |
":Dianora!db@irc.db.net PRIVMSG #us-opers :ON TOP OF ...\r\n" |
21 |
|
22 |
e.g. as seen sent to a remote server: |
23 |
":Dianora PRIVMSG #us-opers :ON TOP OF ...\r\n" |
24 |
|
25 |
It has been argued that full prefixes sent locally are a waste of bandwidth |
26 |
(Isomer from Undernet has argued this). i.e. instead of sending: |
27 |
":nick!user@host" for a local prefix, one could just send ":nick".. |
28 |
Unfortunately, this breaks many clients badly. Personally I feel that |
29 |
until clients are updated to understand that a full prefix isn't always |
30 |
going to be sent, that this should be held off on. |
31 |
|
32 |
As much as possible, prefix generation is now moved "upstairs" as |
33 |
much as possible. i.e. if its known its a local client only, then the |
34 |
onus of the prefix generation, is the users, not hidden in send.c |
35 |
This allows somewhat faster code to be written, as the prefix doesn't |
36 |
have to be regenerated over and over again. |
37 |
|
38 |
Prefixes aren't sent in all cases, such as a new user using NICK |
39 |
A prefix is needed when it must be routed. |
40 |
|
41 |
i.e. |
42 |
|
43 |
NICK newnick |
44 |
|
45 |
There is obviously no prefix needed from a locally connected client. |
46 |
|
47 |
|
48 |
|
49 |
FUNCTIONS |
50 |
========= |
51 |
|
52 |
sendto_one() - Should be used for _local_ clients only |
53 |
it expects the prefix to be pre-built by user. |
54 |
|
55 |
usage - sendto_one(struct Client *to, char *pattern, ...); |
56 |
|
57 |
typical use: |
58 |
|
59 |
sendto_one(acptr,":%s NOTICE %s :I'm tired", me.name); |
60 |
Note: This was from a server "me" hence only one |
61 |
name in prefix. |
62 |
|
63 |
This would be an example of a client sptr, noticing |
64 |
acptr IF acptr is known to be a local client: |
65 |
|
66 |
sendto_one(acptr,":%s!%s@%s NOTICE %s :You there?", |
67 |
sptr->name, |
68 |
sptr->username, |
69 |
sptr->host, |
70 |
acptr->name); |
71 |
|
72 |
sendto_channel_butone() |
73 |
- This function sends a var args message to a channel globally, |
74 |
except to the client specified as "one", the prefix |
75 |
is built by this function on the fly as it has to |
76 |
be sent both to local clients on this server and to |
77 |
remote servers. +D clients are omitted, as this is used |
78 |
only for PRIVMSG/NOTICE. |
79 |
|
80 |
usage - sendto_channel_butone(struct Client *one, |
81 |
struct Client *from, |
82 |
struct Channel *chptr, |
83 |
const char *pattern, ... ); |
84 |
|
85 |
sendto_channel_butone(cptr, sptr, chptr |
86 |
"PRIVMSG %s :HI!", |
87 |
chptr->chname); |
88 |
|
89 |
e.g. if channel message is coming from "cptr" |
90 |
it must not be sent back to cptr. |
91 |
|
92 |
|
93 |
sendto_ll_serv_butone(struct Client *one, struct Client *sptr, int add, |
94 |
const char *pattern, ...) |
95 |
|
96 |
- This function is almost identical to sendto_channel_butone |
97 |
however, it will also not send on a nick as given by sptr, |
98 |
if target server does not "know" about it. |
99 |
As the name implies, it is used for "lazylinks" |
100 |
|
101 |
sendto_server() |
102 |
- This function sends specified var args message |
103 |
to all connected servers except the client "one" |
104 |
- chptr can be NULL, in which case it goes to server |
105 |
- caps is a set of CAPS to send =to= |
106 |
- nocaps is a set of CAPS to not send =to= |
107 |
|
108 |
usage - sendto_server(struct Client *one, |
109 |
struct Channel *chptr, |
110 |
unsigned long caps, |
111 |
unsigned long nocaps, |
112 |
unsigned long llflags, |
113 |
const char *pattern, ... ); |
114 |
|
115 |
|
116 |
sendto_common_channels_local() |
117 |
- This function is used only by m_nick and exit_one_client |
118 |
its used to propagate nick changes to all channels user |
119 |
is in, and QUIT messages to all channels user is in. |
120 |
As it only sends to local clients, prefix generation |
121 |
is left to the user. It also sends the message to the |
122 |
user if the user isn't on any channels. |
123 |
|
124 |
usage - sendto_common_channels_local(struct Client *user, |
125 |
const char *pattern, |
126 |
...); |
127 |
|
128 |
sendto_channel_local() |
129 |
- This function is used only to send locally, never |
130 |
to remote servers. This is useful when removing |
131 |
local chanops, or adding a local chanop. MODE/SJOIN |
132 |
sent to remote server allows that server to propagate |
133 |
mode changes to its clients locally. If nodeaf is YES, |
134 |
+D clients are omitted (used for delivering WALLCHOPS). |
135 |
|
136 |
usage - sendto_channel_local(type, nodeaf, |
137 |
struct Channel *chptr, |
138 |
const char *pattern, ... ); |
139 |
|
140 |
|
141 |
prefix must be pre-built. type is a flag |
142 |
denoting ONE of |
143 |
ALL_MEMBERS - all members locally are sent to |
144 |
NON_CHANOPS - only non-chanops see this |
145 |
ONLY_CHANOPS_VOICED - both chanops and voiced see this |
146 |
ONLY_CHANOPS - only chanops see this |
147 |
|
148 |
|
149 |
sendto_match_butone() |
150 |
match_it() - both only used for the old style oper masking |
151 |
i.e. /msg #hostmask which in hyb7 is /msg $#hostmask |
152 |
or /msg $servermask in hyb7 /msg $$servermask |
153 |
|
154 |
usage - match_it(struct Client *one, |
155 |
const char *mask, |
156 |
int what); |
157 |
|
158 |
one is the client to match on either hostmask or servermask |
159 |
mask is the actual mask |
160 |
what is either MATCH_HOST or MATCH_SERVER |
161 |
|
162 |
usage - sendto_match_butone(struct Client *one, |
163 |
struct Client *from, |
164 |
char *mark, |
165 |
int what, |
166 |
const char *pattern, ... ); |
167 |
|
168 |
sendto_channel_remote() |
169 |
- Is only used to send a message to a remote server |
170 |
|
171 |
|
172 |
sendto_match_cap_servs() |
173 |
- Is used only to send MODE lists to remote server |
174 |
who are capable of it. i.e. MODE #channel +e nick!user@host |
175 |
|
176 |
sendto_match_noncap_servs() |
177 |
- Is used only to send MODE lists to remote servers that |
178 |
are not capable of it. i.e. MODE #channel +o nick |
179 |
- This allows you to send a MODE #channel +h nick via |
180 |
sendto_match_cap_servs and MODE #channel +o nick to |
181 |
servers which don't support it. |
182 |
|
183 |
sendto_anywhere() |
184 |
- Allows the sending of a message to any client on the net |
185 |
without knowing whether its local or remote. The penalty |
186 |
is the calculation of a run-time prefix. |
187 |
It is less efficient then sendto_one() |
188 |
|
189 |
usage - sendto_anywhere(struct Client *to, |
190 |
struct Client *from, |
191 |
const char *pattern, ...); |
192 |
|
193 |
e.g. |
194 |
sendto_anywhere(acptr, sptr, |
195 |
"PRIVMSG Larz :Hi, Where ever you are"); |
196 |
|
197 |
sendto_realops_flags() |
198 |
- combines old sendto_realops and sendto_realops_flags |
199 |
sends specified message to opers locally only |
200 |
depending on two flags, UMODE i.e. +y +d or UMODE_SERVNOTICE |
201 |
or special case, UMODE_ALL (see client.h UMODE flags ) |
202 |
to send to any oper. The second flag gives the level |
203 |
of whom to send the messages to, OPERS, ADMINS only or both. |
204 |
(See send.h for those flags) |
205 |
|
206 |
usage - sendto_realops_flags(int umode, int level, |
207 |
const char *pattern, ... ); |
208 |
|
209 |
e.g. |
210 |
sendto_realops_flags(UMODE_ALL, L_ALL, |
211 |
"Don't eat the yellow snow"); |
212 |
|
213 |
sendto_wallops_flags() |
214 |
- sends specified message to opers locally, |
215 |
depending on flags. used for messages that need |
216 |
to be in wallops form |
217 |
|
218 |
usage - sendto_wall_flags(int flags, |
219 |
struct Client *, const char *patterm ...); |
220 |
|
221 |
e.g. |
222 |
sendto_wallops_flags(UMODE_WALLOP, |
223 |
sptr, "Message"); |
224 |
|
225 |
ts_warn() - Only used to send warning messages to all opers |
226 |
without flooding them with warnings. |
227 |
It limits the number of warnings to no more than 5 |
228 |
every 5 seconds. It probably can go away now. |
229 |
|
230 |
usage - ts_warn(const char *pattern, ... ); |
231 |
|
232 |
*** LOCAL HELPER FUNCTIONS (static) *** |
233 |
|
234 |
send_format() - Used to format a varargs buffer into given buffer |
235 |
returns length of buffer built, enforces RFC1459 length |
236 |
limits and appends \r\n as per rfc. |
237 |
|
238 |
usage - send_format(char *sendbuf, |
239 |
const char *pattern, ... ); |
240 |
|
241 |
send_message() |
242 |
- This local function does the actual send of message |
243 |
|
244 |
usage: send_message(struct Client *to, char *msg, int len); |
245 |
|
246 |
The message has to be pre-formatted and the length |
247 |
must be pre-calculated. |
248 |
|
249 |
send_message_remote() |
250 |
- This local function does the actual send of message to |
251 |
remote clients |
252 |
|
253 |
usage: send_message_remote(struct Client *to, |
254 |
struct Client *from, char *msg, int len); |
255 |
|
256 |
The message has to be pre-formatted and the length |
257 |
must be pre-calculated. |
258 |
|
259 |
|
260 |
-- Diane Bruce |
261 |
|
262 |
$Id$ |