diff options
Diffstat (limited to 'doc/technical/send.txt')
| -rw-r--r-- | doc/technical/send.txt | 262 |
1 files changed, 262 insertions, 0 deletions
diff --git a/doc/technical/send.txt b/doc/technical/send.txt new file mode 100644 index 0000000..38fd916 --- /dev/null +++ b/doc/technical/send.txt @@ -0,0 +1,262 @@ +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$ |