doc/api/send.txt

   1 The send functions are perhaps the most important API in all of ircd;
   2 without them, communications would not be possible.  Most of these
   3 functions are pretty much stand-alone, although one or two are
   4 intended for use in conjunction with the MsgQ interface.  The send
   5 functions use the MsgQ interface internally, but for the most part,
   6 this fact is hidden from the caller.
   7
   8 Command tokenization provides the greatest complication.  The
   9 functions do use ircd_snprintf() internally, so the use of numerics
  10 doesn't increase that complication.  The tokenization issue is dealt
  11 with by making each function accept two char* pointers, _cmd_ and
  12 _tok_, in that order, and then defining a CMD_* macro in msg.h that
  13 contains the message string and the token string in that order.  When
  14 one of these functions is called, it determines whether the
  15 destination will be a server or a user, then selects the correct one,
  16 either _cmd_ or _tok_, for that message.
  17
  18 The MsgQ interface provides the concept of a priority queue; messages
  19 which must be sent as soon as possible, regardless of what other
  20 messages may already be in the queue.  The sendcmdto_prio_one() and
  21 sendcmdto_flag_butone() functions make use of this priority queue.
  22 The function send_buffer() also takes a _prio_ argument that should be
  23 non-zero if the message passed to it should be placed in the priority
  24 queue.
  25
  26 <macro>
  27 #define SKIP_DEAF       0x01    /* skip users that are +d */
  28
  29 This flag may be passed to sendcmdto_channel_butone() to cause a
  30 message passed by that function to skip users that are +d.  See the
  31 documentation for sendcmdto_channel_butone() for more information.
  32 </macro>
  33
  34 <macro>
  35 #define SKIP_BURST      0x02    /* skip users that are bursting */
  36
  37 This is another flag that may be passed to
  38 sendcmdto_channel_butone().  Its purpose is to cause the server to not
  39 send the message across a link that is still in the "burst" stage of
  40 network junction.  See the documentation for
  41 sendcmdto_channel_butone() for more information.
  42 </macro>
  43
  44 <macro>
  45 #define SKIP_NONOPS     0x04    /* skip users that aren't chanops */
  46
  47 Some messages may need to be passed only to channel operators.  This
  48 flag is passed to sendcmdto_channel_butone() when that is the case.
  49 See the documentation for sendcmdto_channel_butone() for more
  50 information.
  51 </macro>
  52
  53 <function>
  54 void send_buffer(struct Client* to, struct MsgBuf* buf, int prio);
  55
  56 Some applications may need to build a message piece by piece, directly
  57 utilizing the MsgQ interface.  The function send_buffer() is used when
  58 that message has been completed to place the message on a client's
  59 queue.  See the documentation for the MsgQ interface for more
  60 information about struct MsgBuf and the _buf_ parameter.
  61 </function>
  62
  63 <function>
  64 void flush_connections(struct Client* cptr);
  65
  66 This function attempts to send all queued data to a client specified
  67 by _cptr_.  If _cptr_ is 0, all clients with non-empty send queues
  68 will have their queues flushed.
  69 </function>
  70
  71 <function>
  72 void send_queued(struct Client *to);
  73
  74 This function attempts to send all queued data to a client specified
  75 by _to_.  The _to_ parameter is not permitted to be 0.  This is the
  76 function called by flush_connections().
  77 </function>
  78
  79 <function>
  80 void sendrawto_one(struct Client *to, const char *pattern, ...);
  81
  82 Most of the actual send functions in this API send their data with a
  83 prefix--the numeric of the origin.  This function is used when a
  84 message should be sent _without_ that prefix.  The caller must specify
  85 the complete message, including the exact command, with the _pattern_
  86 argument and the variable argument list following it.
  87 </function>
  88
  89 <function>
  90 void sendcmdto_one(struct Client *from, const char *cmd, const char *tok,
  91                    struct Client *to, const char *pattern, ...);
  92
  93 This function is used for sending messages to specific clients.  The
  94 origin of the message is specified using the _from_ parameter; this
  95 will be used to formulate the origin.  As mentioned above, _cmd_ and
  96 _tok_ are used to determine the command and token to be used.  The
  97 _to_ parameter specifies which client the message should be sent to.
  98 The origin and command will be formatted and followed by a space; the
  99 given _pattern_ and the following arguments are passed to
 100 ircd_snprintf() for formatting.
 101 </function>
 102
 103 <function>
 104 void sendcmdto_prio_one(struct Client *from, const char *cmd, const char *tok,
 105                         struct Client *to, const char *pattern, ...);
 106
 107 This function is identical to sendcmdto_one() except that messages
 108 formatted using it will be placed onto the priority queue.
 109 </function>
 110
 111 <function>
 112 void sendcmdto_serv_butone(struct Client *from, const char *cmd,
 113                            const char *tok, struct Client *one,
 114                            const char *pattern, ...);
 115
 116 This function treats its arguments similar to sendcmdto_one() does.
 117 Messages passed created with this function are sent to all directly
 118 linked servers except for the _one_ passed.  If _one_ is 0, the
 119 message is sent to all linked servers.
 120 </function>
 121
 122 <function>
 123 void sendcmdto_common_channels(struct Client *from, const char *cmd,
 124                                const char *tok, const char *pattern, ...);
 125
 126 When a user quits IRC, all of the other users on the channels that the
 127 user is on must receive a single QUIT message.  This function formats
 128 the message, under control of _from_ (for the origin prefix), _cmd_
 129 and _tok_, and _pattern_ and the variable argument list, and sends
 130 that message to all local users on the same channels as the user
 131 specified by _from_.  This function does not send any messages across
 132 server<->server links.
 133 </function>
 134
 135 <function>
 136 void sendcmdto_channel_butserv(struct Client *from, const char *cmd,
 137                                const char *tok, struct Channel *to,
 138                                const char *pattern, ...);
 139
 140 This function is used to send a command to every local user on a
 141 particular channel, specified by _to_.  No messages are sent across
 142 the server<->server links.
 143 </function>
 144
 145 <function>
 146 void sendcmdto_channel_butone(struct Client *from, const char *cmd,
 147                               const char *tok, struct Channel *to,
 148                               struct Client *one, unsigned int skip,
 149                               const char *pattern, ...);
 150
 151 This function is used mostly for sending PRIVMSG commands to
 152 particular channels.  The users that receive the message are under the
 153 control of the _skip_ parameter, which is a binary OR of the
 154 SKIP_DEAF, SKIP_BURST, and SKIP_NONOPS flags, depending on what
 155 channel users should see the message.  This function sends messages
 156 across both client<->server and server<->server links, as needed.  The
 157 client specified by _one_ will not receive a copy of the message.
 158 </function>
 159
 160 <function>
 161 void sendcmdto_flag_butone(struct Client *from, const char *cmd,
 162                            const char *tok, struct Client *one,
 163                            unsigned int flag, const char *pattern, ...);
 164
 165 This function is used for sending messages to clients with specific
 166 user modes set (specified by the _flag_ parameter).  Three flags make
 167 sense for this function: FLAGS_WALLOP (user mode +w), FLAGS_DEBUG
 168 (user mode +g), and FLAGS_OPER.  FLAGS_OPER has a special meaning that
 169 further restricts distribution of the message only to IRC operators.
 170 For the purposes of this function, no distinction is made between
 171 global operators and local operators.
 172 </function>
 173
 174 <function>
 175 void sendcmdto_match_butone(struct Client *from, const char *cmd,
 176                             const char *tok, const char *to,
 177                             struct Client *one, unsigned int who,
 178                             const char *pattern, ...);
 179
 180 Certain kinds of global messages may be sent by IRC operators.  This
 181 function implements those global messages.  The _to_ parameter is used
 182 to specify a pattern by which to filter users, while _who_ specifies
 183 whether that pattern is to be applied to the user's server name or to
 184 the user's host name.  The _who_ parameter may be one of MATCH_SERVER
 185 or MATCH_HOST; these two macros are defined in s_user.h.  The _one_
 186 parameter will not receive a copy of the message.
 187 </function>
 188
 189 <function>
 190 void sendto_opmask_butone(struct Client *one, unsigned int mask,
 191                           const char *pattern, ...);
 192
 193 The sendto_opmask_butone() function sends a server notice to all
 194 subscribing users except for _one_.  The _mask_ parameter is one of
 195 the SNO_* values defined in client.h and is used for selection of
 196 subscribing users.
 197 </function>
 198
 199 <function>
 200 void vsendto_opmask_butone(struct Client *one, unsigned int mask,
 201                            const char *pattern, va_list vl);
 202
 203 The vsendto_opmask_butone() function is identical to the
 204 sendto_opmask_butone() function except that instead of a variable
 205 argument list, it takes a va_list, specified by _vl_.
 206 </function>
 207
 208 <macro>
 209 #define SND_EXPLICIT    0x40000000      /* first arg is a pattern to use */
 210
 211 When this flag, defined in ircd_reply.h, is combined with the _reply_
 212 argument to the send_reply() function, the format string send_reply()
 213 uses is obtained from the first argument in the variable argument list
 214 passed to that function, rather than from the table of replies.
 215 </macro>
 216
 217 <function>
 218 int send_reply(struct Client* to, int reply, ...);
 219
 220 The send_reply() function, declared in ircd_reply.h, is used to send
 221 clients numeric replies.  Unless SND_EXPLICIT is used, the pattern
 222 will be extracted from a table of replies.
 223 </function>
 224
 225 <authors>
 226 Kev <klmitch@mit.edu>
 227 </authors>
 228
 229 <changelog>
 230 [2001-6-15 Kev] Initial documentation for the send functions.
 231 </changelog>