doc/technical/send.txt

   1
   2 send.c re-work
   3
   4 PREFIXES
   5 ========
   6
   7   Server prefixes are the ":%s" strings at the beginning of messages.
   8 They are used by servers to route the message properly and by servers to
   9 local clients to update their idea of who is whom.
  10
  11 ":nick!user@host" is a prefix ":name" where name is either a nick
  12 or name of a server is another valid prefix.
  13
  14 Typical prefix for a local client to a channel:
  15
  16 ":Dianora!db@irc.db.net"
  17
  18 for a prefix to a remote server:
  19 ":Dianora"
  20
  21 e.g. as seen locally on a channel:
  22
  23 ":Dianora!db@irc.db.net PRIVMSG #us-opers :ON TOP OF ...\r\n"
  24
  25 e.g. as seen sent to a remote server:
  26 ":Dianora PRIVMSG #us-opers :ON TOP OF ...\r\n"
  27
  28   It has been argued that full prefixes sent locally are a waste of bandwidth
  29 (Isomer from Undernet has argued this). i.e. instead of sending:
  30 ":nick!user@host" for a local prefix, one could just send ":nick"..
  31 Unfortunately, this breaks many clients badly. Personally I feel that
  32 until clients are updated to understand that a full prefix isn't always
  33 going to be sent, that this should be held off on.
  34
  35   As much as possible, prefix generation is now moved "upstairs" as
  36 much as possible. i.e. if its known its a local client only, then the
  37 onus of the prefix generation, is the users, not hidden in send.c
  38 This allows somewhat faster code to be written, as the prefix doesn't
  39 have to be regenerated over and over again.
  40
  41   Prefixes aren't sent in all cases, such as a new user using NICK
  42 A prefix is needed when it must be routed.
  43
  44 i.e.
  45
  46 NICK newnick
  47
  48   There is obviously no prefix needed from a locally connected client.
  49
  50
  51
  52 FUNCTIONS
  53 =========
  54
  55 sendto_one()    - Should be used for _local_ clients only
  56                   it expects the prefix to be pre-built by user.
  57
  58                   usage - sendto_one(struct Client *to, char *pattern, ...);
  59
  60                   typical use:
  61
  62                   sendto_one(acptr,":%s NOTICE %s :I'm tired", me.name,
  63                              acptr->name);
  64                   Note: This was from a server "me" hence only one
  65                   name in prefix.
  66
  67                   This would be an example of a client sptr, noticing
  68                   acptr IF acptr is known to be a local client:
  69
  70                   sendto_one(acptr,":%s!%s@%s NOTICE %s :You there?",
  71                              sptr->name,
  72                              sptr->username,
  73                              sptr->host,
  74                              acptr->name);
  75
  76 sendto_one_prefix()
  77                 - Sends a message to a remote client, with proper
  78                   prefix and target (name or UID).
  79                   usage - sendto_one_prefix(struct Client *target_p,
  80                                             struct Client *source_p,
  81                                             const char *command,
  82                                             const char *pattern, ...)
  83
  84                   typical use:
  85
  86                   sendto_one_prefix(target_p, source_p, "INVITE", ":%s",
  87                                     chptr->chname);
  88
  89
  90 sendto_one_notice()
  91                 - Sends a notice from this server to target. Target may
  92                   be a local or remote client.
  93                   Prefix and target are chosen based on TS6 capability.
  94
  95                   typical use:
  96
  97                   sendto_one_notice(source_p, ":You suck. Yes, really.");
  98
  99 sendto_one_numeric()
 100                 - Sends a numeric from this server to target. Target may
 101                   be a local or remote client.
 102                   Prefix and target are chosen based on TS6 capability.
 103
 104                   typical use:
 105
 106                   sendto_one_numeric(source_p, RPL_STATSDEBUG,
 107                                      "p :%u staff members", count);
 108
 109 sendto_channel_flags()
 110                 - This function sends a var args message to a channel globally,
 111                   except to the client specified as "one", the prefix
 112                   is built by this function on the fly as it has to
 113                   be sent both to local clients on this server and to
 114                   remote servers.
 115                   For type use one of:
 116                   ONLY_SERVERS ALL_MEMBERS ONLY_CHANOPS ONLY_CHANOPSVOICED
 117                   If type is not ALL_MEMBERS it's not sent to not-CHW-capable
 118                   servers.
 119                   Deaf (umode +D) clients are always skipped.
 120
 121                   usage - sendto_channel_flags(struct Client *one,
 122                                                int type,
 123                                                struct Client *from,
 124                                                struct Channel *chptr,
 125                                                const char *pattern, ... );
 126
 127                   sendto_channel_butone(cptr, ALL_MEMBERS, sptr, chptr
 128                                         "PRIVMSG %s :HI!",
 129                                         chptr->chname);
 130
 131                   e.g. if channel message is coming from "cptr"
 132                   it must not be sent back to cptr.
 133
 134
 135 sendto_server()
 136                 - This function sends specified var args message
 137                   to all connected servers except the client "one"
 138                   which have all of "caps" capabilities but none
 139                   of "nocaps" capabilities.
 140
 141                   If "chptr" is not NULL and is a local channel,
 142                   nothing is sent.
 143
 144                   usage - sendto_server(struct Client *one,
 145                                         struct Channel *chptr,
 146                                         unsigned long caps,
 147                                         unsigned long nocaps,
 148                                         const char *format, ... );
 149
 150 sendto_common_channels_local()
 151                 - This function is used only by m_nick and exit_one_client
 152                   its used to propagate nick changes to all channels user
 153                   is in, and QUIT messages to all channels user is in.
 154                   As it only sends to local clients, prefix generation
 155                   is left to the user. It also sends the message to the
 156                   user if the user isn't on any channels.
 157
 158                   usage - sendto_common_channels_local(struct Client *user,
 159                                                        const char *pattern,
 160                                                        ...);
 161
 162 sendto_channel_local()
 163                 - This function is used to send only locally, never
 164                   to remote servers. This is useful when removing
 165                   local chanops, or adding a local chanop. MODE/SJOIN
 166                   sent to remote server allows that server to propagate
 167                   mode changes to its clients locally.
 168                   The message is also sent to deaf (umode +D) clients.
 169
 170                   usage - sendto_channel_local(int type,
 171                                                struct Channel *chptr,
 172                                                const char *pattern, ... );
 173
 174                   prefix must be pre-built. type is a flag
 175                   denoting ONE of
 176                   ALL_MEMBERS           - all members locally are sent to
 177                   ONLY_CHANOPS_VOICED   - only chanops and voiced see this
 178                   ONLY_CHANOPS          - only chanops see this
 179
 180
 181 sendto_match_butone()
 182                 - only used for the old style oper masking
 183                   i.e. /msg #hostmask which in hyb7 is /msg $#hostmask
 184                   or  /msg $servermask in hyb7 /msg $$servermask
 185
 186                   usage - sendto_match_butone(struct Client *one,
 187                                               struct Client *source_p,
 188                                               char *mask,
 189                                               int what,
 190                                               const char *pattern, ... );
 191
 192                   one is the client not to send to
 193                   mask is the actual mask
 194                   what is either MATCH_HOST or MATCH_SERVER
 195
 196 sendto_match_servs()
 197                 - Allows sending a message to servers whose names match
 198                   the given mask. A message is also sent to non-matching
 199                   servers which have matching servers behind them.
 200                   Used for ENCAP, remote kline, etc.
 201                   No message is sent to source_p->from.
 202
 203                   usage - sendto_match_servs(struct Client *source_p,
 204                                              const char *mask,
 205                                              int cap, int nocap,
 206                                              const char *pattern, ...);
 207
 208 sendto_anywhere()
 209                 - Allows the sending of a message to any client on the net
 210                   without knowing whether its local or remote. The penalty
 211                   is the calculation of a run-time prefix.
 212                   It is less efficient then sendto_one()
 213
 214                   usage - sendto_anywhere(struct Client *to,
 215                                           struct Client *from,
 216                                           const char *command,
 217                                           const char *pattern, ...);
 218
 219                   e.g.
 220                   sendto_anywhere(target_p, source_p,
 221                                   "PRIVMSG", ":Hi, Where ever you are");
 222
 223 sendto_realops_flags()
 224                 - combines old sendto_realops and sendto_realops_flags
 225                   sends specified message to opers locally only
 226                   depending on umodes. UMODE_ALL is UMODE_SERVNOTICE.
 227                   the message is sent as a server notice, prefixed with
 228                   "*** Notice -- ".
 229
 230                   usage - sendto_realops_flags(int flags,
 231                                                const char *pattern, ... );
 232
 233                   e.g.
 234                   sendto_realops_flags(UMODE_ALL,
 235                                  "Don't eat the yellow snow");
 236
 237 sendto_wallops_flags()
 238                 - sends specified message to opers/users locally,
 239                   depending on umodes.  used for messages that need
 240                   to be in wallops form
 241                 - some policy decisions about who gets what live in here
 242
 243                   usage - sendto_wallops_flags(int flags,
 244                                     struct Client *, const char *patterm ...);
 245
 246                   e.g.
 247                   sendto_wallops_flags(UMODE_LOCOPS,
 248                                       sptr, "Message");
 249
 250 -- Diane Bruce
 251 Updated Jan 2006 by jilles with ratbox and late hybrid7 changes
 252
 253 $Id: send.txt 26 2006-09-20 18:02:06Z spb $