doc/technical/send.txt

PREFIXES
========

  Server prefixes are the ":%s" strings at the beginning of messages.
They are used by servers to route the message properly and by servers to
local clients to update their idea of who is whom.

":nick!user@host" is a prefix ":name" where name is either a nick
or name of a server is another valid prefix.

Typical prefix for a local client to a channel:

":Dianora!db@irc.db.net"

for a prefix to a remote server:
":Dianora"

e.g. as seen locally on a channel:

":Dianora!db@irc.db.net PRIVMSG #us-opers :ON TOP OF ...\r\n"

e.g. as seen sent to a remote server:
":Dianora PRIVMSG #us-opers :ON TOP OF ...\r\n"

  It has been argued that full prefixes sent locally are a waste of bandwidth
(Isomer from Undernet has argued this). i.e. instead of sending:
":nick!user@host" for a local prefix, one could just send ":nick"..
Unfortunately, this breaks many clients badly. Personally I feel that
until clients are updated to understand that a full prefix isn't always
going to be sent, that this should be held off on.

  As much as possible, prefix generation is now moved "upstairs" as
much as possible. i.e. if its known its a local client only, then the
onus of the prefix generation, is the users, not hidden in send.c
This allows somewhat faster code to be written, as the prefix doesn't
have to be regenerated over and over again.

  Prefixes aren't sent in all cases, such as a new user using NICK
A prefix is needed when it must be routed.

i.e.

NICK newnick

  There is obviously no prefix needed from a locally connected client.


FUNCTIONS
=========

sendto_one()    - Should be used for _local_ clients only
                  it expects the prefix to be pre-built by user.
                  
                  usage - sendto_one(struct Client *to, char *pattern, ...);

                  typical use:

                  sendto_one(acptr,":%s NOTICE %s :I'm tired", me.name);
                  Note: This was from a server "me" hence only one
                  name in prefix.

                  This would be an example of a client sptr, noticing
                  acptr IF acptr is known to be a local client:

                  sendto_one(acptr,":%s!%s@%s NOTICE %s :You there?",
                             sptr->name,
                             sptr->username,
                             sptr->host,
                             acptr->name);

sendto_channel_butone()
                - This function sends a var args message to a channel globally,
                  except to the client specified as "one", the prefix
                  is built by this function on the fly as it has to
                  be sent both to local clients on this server and to
                  remote servers. +D clients are omitted, as this is used
                  only for PRIVMSG/NOTICE.

                  usage - sendto_channel_butone(struct Client *one,
                                                struct Client *from,
                                                struct Channel *chptr,
                                                const char *pattern, ... );

                  sendto_channel_butone(cptr, sptr, chptr
                                        "PRIVMSG %s :HI!",
                                        chptr->chname);

                  e.g. if channel message is coming from "cptr"
                  it must not be sent back to cptr.


sendto_ll_serv_butone(struct Client *one, struct Client *sptr, int add,
                      const char *pattern, ...)

                - This function is almost identical to sendto_channel_butone
                  however, it will also not send on a nick as given by sptr,
                  if target server does not "know" about it.
                  As the name implies, it is used for "lazylinks"

sendto_server()
                - This function sends specified var args message
                  to all connected servers except the client "one"
                - chptr can be NULL, in which case it goes to server
                - caps is a set of CAPS to send =to=
                - nocaps is a set of CAPS to not send =to=
        
              usage - sendto_server(struct Client *one,
                        struct Channel *chptr,
                        unsigned long caps,
                        unsigned long nocaps,
                        unsigned long llflags,
                        const char *pattern, ... );  


sendto_common_channels_local()
                - This function is used only by m_nick and exit_one_client
                  its used to propagate nick changes to all channels user
                  is in, and QUIT messages to all channels user is in.
                  As it only sends to local clients, prefix generation
                  is left to the user. It also sends the message to the
                  user if the user isn't on any channels.

                  usage - sendto_common_channels_local(struct Client *user,
                                                       const char *pattern,
                                                       ...);

sendto_channel_local()
                - This function is used only to send locally, never
                  to remote servers. This is useful when removing
                  local chanops, or adding a local chanop. MODE/SJOIN
                  sent to remote server allows that server to propagate
                  mode changes to its clients locally. If nodeaf is YES,
                  +D clients are omitted (used for delivering WALLCHOPS).

                  usage - sendto_channel_local(type, nodeaf,
                                               struct Channel *chptr,
                                               const char *pattern, ... );


                  prefix must be pre-built. type is a flag
                  denoting ONE of 
                  ALL_MEMBERS           - all members locally are sent to
                  NON_CHANOPS           - only non-chanops see this
                  ONLY_CHANOPS_VOICED   - both chanops and voiced see this
                  ONLY_CHANOPS          - only chanops see this


sendto_match_butone()
match_it()      - both only used for the old style oper masking
                  i.e. /msg #hostmask which in hyb7 is /msg $#hostmask
                  or  /msg $servermask in hyb7 /msg $$servermask

                  usage - match_it(struct Client *one,
                                   const char *mask,
                                   int what);

                  one is the client to match on either hostmask or servermask
                  mask is the actual mask
                  what is either MATCH_HOST or MATCH_SERVER

                  usage - sendto_match_butone(struct Client *one,
                                              struct Client *from,
                                              char *mark,
                                              int what,
                                              const char *pattern, ... );

sendto_channel_remote()
                - Is only used to send a message to a remote server


sendto_match_cap_servs()
                - Is used only to send MODE lists to remote server
                  who are capable of it. i.e. MODE #channel +e nick!user@host

sendto_match_noncap_servs()
                - Is used only to send MODE lists to remote servers that
                  are not capable of it. i.e. MODE #channel +o nick
                - This allows you to send a MODE #channel +h nick via 
                  sendto_match_cap_servs and MODE #channel +o nick to 
                  servers which don't support it.

sendto_anywhere()
                - Allows the sending of a message to any client on the net
                  without knowing whether its local or remote. The penalty
                  is the calculation of a run-time prefix.
                  It is less efficient then sendto_one()

                  usage - sendto_anywhere(struct Client *to,
                                          struct Client *from,
                                          const char *pattern, ...);

                  e.g.
                  sendto_anywhere(acptr, sptr,
                                  "PRIVMSG Larz :Hi, Where ever you are");

sendto_realops_flags()
                - combines old sendto_realops and sendto_realops_flags
                  sends specified message to opers locally only
                  depending on two flags, UMODE i.e. +y +d or UMODE_SERVNOTICE
                  or special case, UMODE_ALL (see client.h UMODE flags )
                  to send to any oper. The second flag gives the level
                  of whom to send the messages to, OPERS, ADMINS only or both.
                  (See send.h for those flags)

                  usage - sendto_realops_flags(int umode, int level,
                                               const char *pattern, ... );

                  e.g.
                  sendto_realops_flags(UMODE_ALL, L_ALL,
                                 "Don't eat the yellow snow");

sendto_wallops_flags()
                - sends specified message to opers locally, 
                  depending on flags.  used for messages that need
                  to be in wallops form

                  usage - sendto_wall_flags(int flags,
                                    struct Client *, const char *patterm ...);

                  e.g.
                  sendto_wallops_flags(UMODE_WALLOP,
                                      sptr, "Message");

ts_warn()       - Only used to send warning messages to all opers
                  without flooding them with warnings.
                  It limits the number of warnings to no more than 5
                  every 5 seconds. It probably can go away now.
 
                  usage - ts_warn(const char *pattern, ... );

*** LOCAL HELPER FUNCTIONS (static) ***

send_format()   - Used to format a varargs buffer into given buffer
                  returns length of buffer built, enforces RFC1459 length
                  limits and appends \r\n as per rfc.

                  usage - send_format(char *sendbuf,
                                      const char *pattern, ... );

send_message()
                - This local function does the actual send of message
                  
                  usage: send_message(struct Client *to, char *msg, int len);

                  The message has to be pre-formatted and the length
                  must be pre-calculated. 

send_message_remote()
                - This local function does the actual send of message to
                  remote clients

                  usage: send_message_remote(struct Client *to,
                  struct Client *from, char *msg, int len);

                  The message has to be pre-formatted and the length
                  must be pre-calculated.


-- Diane Bruce 

$Id$
Revision:	7668
Committed:	Wed Jul 20 17:09:49 2016 UTC (10 years ago) by michael
Content type:	text/plain
File size:	10628 byte(s)
Log Message:	- Fixed svn properties
#	Content
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$