ircu api - send

The send functions are perhaps the most important API in all of ircd; without them, communications would not be possible. Most of these functions are pretty much stand-alone, although one or two are intended for use in conjunction with the MsgQ interface. The send functions use the MsgQ interface internally, but for the most part, this fact is hidden from the caller.

Command tokenization provides the greatest complication. The functions do use ircd_snprintf internally, so the use of numerics doesn't increase that complication. The tokenization issue is dealt with by making each function accept two char* pointers, _cmd_ and _tok_, in that order, and then defining a CMD_* macro in msg.h that contains the message string and the token string in that order. When one of these functions is called, it determines whether the destination will be a server or a user, then selects the correct one, either _cmd_ or _tok_, for that message.

The MsgQ interface provides the concept of a priority queue; messages which must be sent as soon as possible, regardless of what other messages may already be in the queue. The sendcmdto_prio_one and sendcmdto_flag_butone functions make use of this priority queue. The function send_buffer also takes a _prio_ argument that should be non-zero if the message passed to it should be placed in the priority queue.


 * 1) define SKIP_DEAF	0x01	/* skip users that are +d */

This flag may be passed to sendcmdto_channel_butone to cause a message passed by that function to skip users that are +d. See the documentation for sendcmdto_channel_butone for more information.


 * 1) define SKIP_BURST	0x02	/* skip users that are bursting */

This is another flag that may be passed to sendcmdto_channel_butone. Its purpose is to cause the server to not send the message across a link that is still in the "burst" stage of network junction. See the documentation for sendcmdto_channel_butone for more information.


 * 1) define SKIP_NONOPS	0x04	/* skip users that aren't chanops */

Some messages may need to be passed only to channel operators. This flag is passed to sendcmdto_channel_butone when that is the case. See the documentation for sendcmdto_channel_butone for more information.

void send_buffer(struct Client* to, struct MsgBuf* buf, int prio);

Some applications may need to build a message piece by piece, directly utilizing the MsgQ interface. The function send_buffer is used when that message has been completed to place the message on a client's queue. See the documentation for the MsgQ interface for more information about struct MsgBuf and the _buf_ parameter.

void flush_connections(struct Client* cptr);

This function attempts to send all queued data to a client specified by _cptr_. If _cptr_ is 0, all clients with non-empty send queues will have their queues flushed.

void send_queued(struct Client *to);

This function attempts to send all queued data to a client specified by _to_. The _to_ parameter is not permitted to be 0. This is the function called by flush_connections.

void sendrawto_one(struct Client *to, const char *pattern, ...);

Most of the actual send functions in this API send their data with a prefix--the numeric of the origin. This function is used when a message should be sent _without_ that prefix. The caller must specify the complete message, including the exact command, with the _pattern_ argument and the variable argument list following it.

void sendcmdto_one(struct Client *from, const char *cmd, const char *tok,		  struct Client *to, const char *pattern, ...);

This function is used for sending messages to specific clients. The origin of the message is specified using the _from_ parameter; this will be used to formulate the origin. As mentioned above, _cmd_ and _tok_ are used to determine the command and token to be used. The _to_ parameter specifies which client the message should be sent to. The origin and command will be formatted and followed by a space; the given _pattern_ and the following arguments are passed to ircd_snprintf for formatting.

void sendcmdto_prio_one(struct Client *from, const char *cmd, const char *tok,			struct Client *to, const char *pattern, ...);

This function is identical to sendcmdto_one except that messages formatted using it will be placed onto the priority queue.

void sendcmdto_serv_butone(struct Client *from, const char *cmd,			  const char *tok, struct Client *one,			   const char *pattern, ...);

This function treats its arguments similar to sendcmdto_one does. Messages passed created with this function are sent to all directly linked servers except for the _one_ passed. If _one_ is 0, the message is sent to all linked servers.

void sendcmdto_common_channels(struct Client *from, const char *cmd,			      const char *tok, const char *pattern, ...);

When a user quits IRC, all of the other users on the channels that the user is on must receive a single QUIT message. This function formats the message, under control of _from_ (for the origin prefix), _cmd_ and _tok_, and _pattern_ and the variable argument list, and sends that message to all local users on the same channels as the user specified by _from_. This function does not send any messages across server<->server links.

void sendcmdto_channel_butserv(struct Client *from, const char *cmd,			      const char *tok, struct Channel *to,			       const char *pattern, ...);

This function is used to send a command to every local user on a particular channel, specified by _to_. No messages are sent across the server<->server links.

void sendcmdto_channel_butone(struct Client *from, const char *cmd,			     const char *tok, struct Channel *to,			      struct Client *one, unsigned int skip,			      const char *pattern, ...);

This function is used mostly for sending PRIVMSG commands to particular channels. The users that receive the message are under the control of the _skip_ parameter, which is a binary OR of the SKIP_DEAF, SKIP_BURST, and SKIP_NONOPS flags, depending on what channel users should see the message. This function sends messages across both client<->server and server<->server links, as needed. The client specified by _one_ will not receive a copy of the message.

void sendcmdto_flag_butone(struct Client *from, const char *cmd,			  const char *tok, struct Client *one,			   unsigned int flag, const char *pattern, ...);

This function is used for sending messages to clients with specific user modes set (specified by the _flag_ parameter). Three flags make sense for this function: FLAGS_WALLOP (user mode +w), FLAGS_DEBUG (user mode +g), and FLAGS_OPER. FLAGS_OPER has a special meaning that further restricts distribution of the message only to IRC operators. For the purposes of this function, no distinction is made between global operators and local operators.

void sendcmdto_match_butone(struct Client *from, const char *cmd,			   const char *tok, const char *to,			    struct Client *one, unsigned int who,			    const char *pattern, ...);

Certain kinds of global messages may be sent by IRC operators. This function implements those global messages. The _to_ parameter is used to specify a pattern by which to filter users, while _who_ specifies whether that pattern is to be applied to the user's server name or to the user's host name. The _who_ parameter may be one of MATCH_SERVER or MATCH_HOST; these two macros are defined in s_user.h. The _one_ parameter will not receive a copy of the message.

void sendto_opmask_butone(struct Client *one, unsigned int mask,			 const char *pattern, ...);

The sendto_opmask_butone function sends a server notice to all subscribing users except for _one_. The _mask_ parameter is one of the SNO_* values defined in client.h and is used for selection of subscribing users.

void vsendto_opmask_butone(struct Client *one, unsigned int mask,			  const char *pattern, va_list vl);

The vsendto_opmask_butone function is identical to the sendto_opmask_butone function except that instead of a variable argument list, it takes a va_list, specified by _vl_.


 * 1) define SND_EXPLICIT	0x40000000	/* first arg is a pattern to use */

When this flag, defined in ircd_reply.h, is combined with the _reply_ argument to the send_reply function, the format string send_reply uses is obtained from the first argument in the variable argument list passed to that function, rather than from the table of replies.

int send_reply(struct Client* to, int reply, ...);

The send_reply function, declared in ircd_reply.h, is used to send clients numeric replies. Unless SND_EXPLICIT is used, the pattern will be extracted from a table of replies.

Kev 

[2001-6-15 Kev] Initial documentation for the send functions.