IRC Services Technical Reference Manual

Appendix C. List of callbacks

C-1. General notes
C-2. Services core callbacks
C-3. OperServ callbacks
C-4. NickServ callbacks
C-5. ChanServ callbacks
C-6. MemoServ callbacks
C-7. StatServ callbacks
C-8. HTTP server callbacks


C-1. General notes

The callbacks provided by Services are listed in this appendix under the names used to access them (e.g., with add_callback()). When using Services core callbacks, use a module parameter of NULL.

Where the descriptions below refer to "processing" a message, they refer to a message that is meant specifically for the callback in question and which is not to be passed on to other modules or the Services core.

Except as otherwise specified, callbacks which return zero must leave all arguments unchanged, and callbacks which return nonzero may modify any arguments which are not specified as const.


C-2. Services core callbacks

channel create
Parameters: Channel *channel, User *user, int32 mode
Called when a channel is created (i.e., when a client joins a nonexistent channel). The client that created the channel and that client's modes (CUMODE_*) are also passed to the callback (note that the client is not yet in the channel's client list). The callback routine should always return 0.
channel delete
Parameters: Channel *channel
Called when a channel is about to be deleted (i.e., when the last client has left the channel). The callback routine should always return 0.
channel JOIN
Parameters: Channel *channel, struct c_userlist *u
Called when a client has joined a channel. The callback routine should always return 0.
channel JOIN check
Parameters: const char *channel, User *user
Called when a client is about to join a channel. The callback routine should return 1 to refuse the client access to the channel or 0 to allow the JOIN to proceed normally.
channel KICK
Parameters: Channel *channel, User *user, const char *reason, const char *source
Called when a client has been kicked from a channel. The callback routine should always return 0.
channel MODE
Parameters: const char *source, Channel *channel, int modechar, int add, char **av
Called for each valid mode character in a MODE message, except for channel user modes (+o, +v, etc.). add is nonzero if adding modes, zero if removing them. av points to the first argument for the mode; there are guaranteed to be enough arguments for the mode character (provided the number of parameters in the mode definition is set correctly). The callback routine should return 1 if it processes the mode, 0 otherwise.
channel mode change
Parameters: Channel *channel
Called when a channel's modes have changed. The callback routine should always return 0.
channel umode change
Parameters: Channel *channel, struct c_userlist *user
Called when a client's modes on a channel have changed. The callback routine should always return 0.
channel PART
Parameters: Channel *channel, User *user, const char *reason
Called when a client parts from a channel. The callback routine should always return 0.
channel TOPIC
Parameters: Channel *channel, const char *topic, const char *setter time_t topic_time
Called when a TOPIC command is received. The callback routine should return 0 to permit the topic change or 1 to refuse it. Note that setter may be in the form "nick!user@host" instead of just a nickname, depending on the remote server type; however, Services currently stores only the nickname, and discards the username and hostname if present.
clear channel
Parameters: const char *source, Channel *channel, int what, const void *param
Called whenever the clear_channel() function (in actions.c) is called, before any other action is taken. The callback routine should return 1 to terminate clear_channel() processing or 0 to continue. Note that even if the callback routine returns 1, clear_channel() will still flush out any channel mode changes, so the routine does not need to do this itself. See the comments above clear_channel() in actions.c for the meaning of the parameters.
command line
Parameters: char *option, char *value
Called at program startup for each command-line option. option is the name of the option (the part of the option string after the initial "-", up to and not including any "="), and value" is the text after the "=" (NULL if no "=" is present). option is guaranteed to be non-NULL. The callback routine should return 0 if it does not recognize the option, 1 if it successfully processes the option, 2 if there is an error processing the option, or 3 if no error occurred but Services should terminate successfully.
connect
Parameters: none
Called when a connection to the remote server is established. Modules that want to send data to the remote server on startup should use this callback; attempting to send data to the server before the connection is established will cause the data to be lost. The callback routine should always return 0.
introduce_user
Parameters: char *nick
Called whenever Services may need to introduce a pseudoclient (at startup and when receiving a KILL message). The nick parameter is the nickname of the pseudoclient which should be introduced (if it exists), or NULL when introducing all pseudoclients. The callback routine should return 1 if nick is not NULL and the routine introduces a pseudoclient, 0 otherwise. (If nick is NULL, the routine should introduce any pseudoclients necessary and return 0.)
load module
Parameters: Module *module, const char *modname
Called when a module is loaded, after its init_module() routine has been called. modname is the name of the module, either specified by the module (char module_name[]) or copied from the module's path. The callback routine should always return 0. This callback may be used, for example, to add callback routines to a new module's callbacks when the module is loaded.
m_privmsg
Parameters: char *source, char *target, char *message
Called for every PRIVMSG which is not ignored by Services. The callback routine should return 1 if it processes the message, 0 otherwise.
m_whois
Parameters: char *source, char *target, char *target_server
Called for every WHOIS command. The callback routine should return 1 if it processes the message, 0 otherwise.
receive message
Parameters: char *source, char *cmd, int ac, char **av
Called for every message received from the uplink server. The callback routine should return 1 if it processes the message, 0 otherwise. Note that it is acceptable for a callback routine to modify the parameters passed and return 0 to allow the next routine to continue, subject to the following constraints:
reconfigure
Parameters: int after_configure
Called twice when Services is signalled to re-read its configuration files. The first call is made before any module configuration data is changed (but after the main Services configuration settings have been updated), with after_configure set to 0; the second call is made after all configuration data has been successfully read and configuration variables have been updated, with after_configure set to 1. Callback routines should always return 0.
save data
Parameters: none
Called whenever the save-data timeout runs out, or another action, such as OperServ UPDATE, explicitly causes data saving to occur. The callback routine should always return 0.
save data complete
Parameters: int successful
Called when a save-data operation completes. The successful parameter indicates whether the operation succeeded or not. The callback routine should always return 0.
server create
Parameters: Server *server
Called whenever a new server joins the network, after the server record is created. The callback routine should always return 0.
server delete
Parameters: Server *server, const char *reason
Called whenever a server splits from the network, before the server record is deleted. The callback routine should always return 0.
set topic
Parameters: const char *source, Channel *c, const char *topic, const char *setter, time_t t
Called twice whenever set_topic() (in actions.c) is called to set the topic of a channel from Services. Parameters are as for set_topic() (in actions.c), except as noted below; source will always be non-NULL. The first call is done before the channel structure is modified, and all callback routines must return 0 in this case. The second call is done after the channel structure is modified, but before c->topic_time is changed; in this call, topic and setter are both NULL. If the callback routine returns 1, no further processing is done. This is currently used to ensure that the topic time is set so that the IRC servers will acknowledge the change under certain protocols.
unload module
Parameters: Module *module
Called when a module is unloaded, after its exit_module() routine has been called. The module handle module is the same value as was passed to the "load module" callback for this module, but the handle may not be used with any module functions except get_module_name(). The callback routine should always return 0. Note that it is not necessary (and in fact not possible, as mentioned above) to use this callback to remove callback functions from a module which is being unloaded; those callback entries will be removed automatically.
user check
Parameters: int ac, char **av
Called whenever a client joins the network, before the User record is created. ac and av are the argument list to the NICK (or USER) message, as passed to users.c/do_nick(). The callback routine should return 0 to allow the client to connect or 1 to disallow (in this case the routine should take action to remove the client from the network, such as sending a KILL message).

Notice: When using add_callback_pri() with this callback, never add a routine with priority less than -9, or the operserv/sessions module will malfunction!

user create
Parameters: User *user, int ac, char **av, int reconnect
Called whenever a client joins the network, after the User record is created. ac and av are the argument list to the NICK (or USER) message, as passed to users.c/do_nick(). reconnect is nonzero for clients that are reconnecting after a network split. The callback routine should always return 0.
user delete
Parameters: User *user, char *reason, int is_kill
Called whenever a client leaves the network (whether by QUIT or KILL), before the User record is deleted. is_kill is 1 if the client is disconnecting because of a KILL, 0 if because of a QUIT. The callback routine should always return 0.
user MODE
Parameters: User *user, int modechar, int add, char **av
Called for every mode character given in a client MODE message. add is nonzero when adding modes and zero when subtracting. av points to the first argument for the mode; there are guaranteed to be enough arguments for the mode character (provided the number of parameters in the mode definition is set correctly). The callback routine should return 1 if it processes the mode, 0 otherwise.
user nickchange (after)
Parameters: User *user, const char *oldnick
Called whenever a client changes nicknames, after the nickname is actually changed. The callback routine should return 1 if it kills the client, 0 otherwise.
user nickchange (before)
Parameters: User *user, const char *newnick
Called whenever a client changes nicknames, before the nickname is actually changed. The callback routine should always return 0. Note that clients should never be killed within this callback; use the "user nickchange (after)" callback for that.
user servicestamp change
Parameters: User *user
Called when a client's Services timestamp (the servicestamp field) is altered and the network should be informed of it. The callback routine should always return 0.

C-3. OperServ callbacks

command
Parameters: User *user, char *command
Called for every message (other than a CTCP PING or empty message) received by OperServ. command is the first word in the message (where words are separated by spaces); the remaining text can be obtained through repeated calls to strtok() with a NULL first parameter. The callback routine should return 1 if it processes the message, 0 otherwise. If the routine does not process the message, it must not call strtok().
expire maskdata
Parameters: uint32 type, MaskData *md
Called when a MaskData entry is about to be expired, just before it is actually deleted. The callback routine should always return 0.
HELP
Parameters: User *user, char *param
Called when the HELP command is used with a parameter. The callback should return 1 if it processes the message, 0 otherwise.
HELP COMMANDS
Parameters: User *user, int which
Called when the HELP COMMANDS command is used. The which parameter is 0 when called after the list of unprivileged (IRC operator) commands, 1 after the Services operator commands, 2 after the Services administrator commands, and 3 after the Services root commands. The callback routine should always return 0.
SET
Parameters: User *u, char *option, char *param
Called when the SET command is used. All parameters are guaranteed to be valid (non-NULL); param may contain multiple words. The callback routine should return 1 if it processes the given option, 0 otherwise.
STATS
Parameters: User *user, char *extra
Called for every STATS command that is not plain "STATS", "STATS ALL", "STATS NETWORK", or "STATS RESET". "extra" contains the remainder of the message (after STATS and any following whitespace). The callback routine should return 1 if it processes the command, 0 otherwise.
STATS ALL
Parameters: User *user, const char *s_OperServ
Called for every STATS ALL command. s_OperServ is the OperServ pseudoclient nickname; the callback routine should send messages using this nickname. The callback routine should always return 0.
cancel_akill (operserv/akill module)
Parameters: const char *username, const char *host
Called when an autokill is to be removed from the uplink server. The callback routine should return 1 if it removes the autokill, 0 otherwise.
cancel_exclude (operserv/akill module)
Parameters: const char *username, const char *host
Called when an autokill exclusion is to be removed from the uplink server. The callback routine should return 1 if it removes the autokill exclusion, 0 otherwise.
send_akill (operserv/akill module)
Parameters: const char *username, const char *host, time_t expires, const char *who, const char *reason
Called when an autokill is to be sent to the uplink server. The callback routine should return 1 if it sends the autokill, 0 otherwise.
send_exclude (operserv/akill module)
Parameters: const char *username, const char *host, time_t expires, const char *who, const char *reason
Called when an autokill exclusion is to be sent to the uplink server. The callback routine should return 1 if it sends the autokill exclusion, 0 otherwise.
cancel_sgline (operserv/sline module)
Parameters: const char *mask
Called when an SGline is to be removed from the uplink server. The callback routine should return 1 if it removes the SGline, 0 otherwise.
cancel_sqline (operserv/sline module)
Parameters: const char *mask
Called when an SQline is to be removed from the uplink server. The callback routine should return 1 if it removes the SQline, 0 otherwise.
cancel_szline (operserv/sline module)
Parameters: const char *mask
Called when an SZline is to be removed from the uplink server. The callback routine should return 1 if it removes the SZline, 0 otherwise.
send_sgline (operserv/sline module)
Parameters: const char *mask, time_t expires, const char *who, const char *reason
Called when an SGline is to be sent to the uplink server. The callback routine should return 1 if it sends the SGline, 0 otherwise.
send_sqline (operserv/sline module)
Parameters: const char *mask, time_t expires, const char *who, const char *reason
Called when an SQline is to be sent to the uplink server. The callback routine should return 1 if it sends the SQline, 0 otherwise.
send_szline (operserv/sline module)
Parameters: const char *mask, time_t expires, const char *who, const char *reason
Called when an SZline is to be sent to the uplink server. The callback routine should return 1 if it sends the SZline, 0 otherwise.

C-4. NickServ callbacks

authed (module nickserv/mail-auth)
Parameters: User *u, NickInfo *ni, NickGroupInfo *ngi, int authreason
Called when a client successfully authenticates its nickname with the AUTH command, after all normal processing has been performed. authreason is the value that the ngi->authreason field had before being cleared (one of the NICKAUTH_* constants). The callback routine should always return 0.
cancel user
Parameters: User *u, int old_status, int old_authstat
Called whenever the cancel_user() routine is called for a client with a registered nickname. old_status is the value of the client's nickname's status field while the nickname was in use (when the callback is called, all temporary flags will have been cleared); old_authstat is likewise the value before clearing of the nickname group's authstat field. The callback routine should always return 0.
check_expire
Parameters: NickInfo *ni, NickGroupInfo *ngi
Called when a nickname is being checked for expiration, after the nickname's last-used time has been updated (if appropriate). The callback routine should return 1 if the nickname should be expired, 0 otherwise. If returning 1, the callback routine should log an appropriate message.
check recognized
Parameters: const User *u
Called whenever Services needs to check whether a client is recognized as being the owner of the nickname it is using (e.g., when the client connects to the network). The User structure is guaranteed to have valid ni and ngi pointers. The callback routine should return:
collide
Parameters: User *u
Called whenever NickServ determines that a client should be "collided". The callback should return 1 if it handles colliding the client (for example, by forcibly changing the client's nickname), or 0 to allow normal collide processing to continue.
command
Parameters: User *user, char *command
Called for every message (other than a CTCP PING or empty message) received by NickServ. See the OperServ "command" callback for details.
HELP
Parameters: User *user, char *param
Called when the HELP command is used with a parameter. The callback should return 1 if it processes the messages, 0 otherwise.
HELP COMMANDS
Parameters: User *user, int which
Called when the HELP COMMANDS command is used. The which parameter is 0 when called after the list of unprivileged commands and 1 after the list of privileged commands (those shown to IRC operators). The callback routine should always return 0.
identified
Parameters: User *u, int old_authstat
Called when a client identifies for its nickname via the IDENTIFY command. old_authstat is the authorization status of the nickname before the identify took place. The callback routine should always return 0.
IDENTIFY check
Parameters: User *u, char *pass
Called when a client attempts to identify for its nickname, after the standard checks (whether the nickname exists, etc.) are done but before the password itself is checked. The callback routine should return 1 to disallow identification or 0 to allow processing to continue normally.
nick delete
Parameters: NickInfo *ni
Called when a nickname's registration is deleted. The callback routine should always return 0.
nickgroup delete
Parameters: NickGroupInfo *ngi, const char *oldnick
Called when a nickname group is deleted (i.e., when the last nickname for the group is deleted), after the "nick delete" callback is called. oldnick is the nickname whose deletion caused this nickname group to be deleted. The callback routine should always return 0.
REGISTER/LINK check
Parameters: User *u, const char *nick, char *password, char *email
Called when a client attempts to register its nickname, after the validity of the parameters has been checked but before checking whether the nickname exists or the password is strong enough. u is the client that sent the REGISTER command, and nick is their nickname (the same as u->nick). email may be NULL (if the client did not provide an E-mail address), but password will always be non-NULL. The callback routine should return 0 to allow the registration to continue or 1 to disallow it.

Also called by the nickserv/link module when a client attempts to link a new nickname to its own. In this case nick is the requested target nickname (different from u->nick), and password and email are both NULL. The callback is called after the nickname is checked for validity (length and invalid characters), but before checking whether the client has registered their current nickname. The callback routine should return 0 to allow the link to be made or 1 to disallow it.

registered
Parameters: User *u, NickInfo *ni, NickGroupInfo *ngi, int *replied
Called when a client registers its nickname, after the data structures have been set up. The integer pointed to by replied can be set to 1 to disable the standard "your nickname has been registered" reply. The callback need not call put_xxx() even if it modifies ni or ngi, as the caller will do so afterwards. The callback routine should always return 0.
SET
Parameters: User *u, NickInfo *ni, NickGroupInfo *ngi, char *option, char *param
Called when the SET command is used. All parameters are guaranteed to be valid (non-NULL), and standard permission checks will have been performed (so u either is identified for ni/ngi or is a Services administrator). The callback routine should return 1 if it processes the given option, 0 otherwise.
SET EMAIL
Parameters: User *u, NickGroupInfo *ngi, char *last_email
Called when the E-mail address associated with a nickname group is set, changed, or unset. u is the client making the change; this may not necessarily be the owner of the nickname if, for example, a Services administrator is making the change. The new address is stored in ngi->email, while the previous address is passed in last_email (this will be NULL if no address was previously set). The callback routine should always return 0.
set identified
Parameters: User *u, int old_authstat
Called whenever the set_identified() routine is called for a client, after the nickname structure has been updated. old_authstat is the previous value of the client nickname's authstat field. The callback routine should always return 0.
UNSET
Parameters: User *u, NickInfo *ni, NickGroupInfo *ngi, char *option
Called when the UNSET command is used. All parameters are guaranteed to be valid (non-NULL), and standard permission checks will have been performed (so u either is identified for ni/ngi or is a Services administrator). The callback routine should return 1 if it processes the given option, 0 otherwise.
send_svsjoin (nickserv/autojoin module)
Parameters: const char *nick, const char *channel
Called when a client should be forced to join a channel. The callback routine should return 1 if it forces the client into the channel, 0 otherwise.

C-5. ChanServ callbacks

check_chan_user_modes
Parameters: const char *source, User *user, Channel *c, int32 modes
Called when checking a client's modes on a channel, before any standard checks are performed. The mode change is being performed by source (NULL for a channel join) on user on channel c, and the client's current modes on the channel are modes. The callback routine should return 0 to allow normal checking to continue or 1 to abort further checks.

Note: source may be the empty string; this indicates an internal call to verify a client's current modes. In this case callback routines should not make any decisions about modes based on the value of source.

check_kick
Parameters: User *user, const char *chan, ChannelInfo *ci, char **mask_ret, const char **reason_ret
Called when checking whether a client should be kicked from a channel, before any standard checks are performed. All parameters are guaranteed to be non-NULL, except for ci, which will be NULL when the channel is not registered. The callback routine may return:
check_modes
Parameters: Channel *channel, ChannelInfo *ci, int add, int32 flag
Called when checking a channel's modes against its mode lock for every mode locked either on (add nonzero) or off (add zero). The callback routine should return 1 if it processes the mode, 0 if not. If a mode is not processed by any callback and is further not specially handled by Services (+k and +l modes), the default action is to simply modify the channel's current modes to match the mode lock (by calling set_cmode(...,"+X") or set_cmode(...,"-X") for mode X), so it is not necessary to add a callback for modes for which this behavior is sufficient.
CLEAR
Parameters: User *user, Channel *channel, char *what
Called when a valid CLEAR command is received (i.e., from a client with permission to use the command on the given channel). The callback routine should return 1 if it processes the command, 0 if not.
command
Parameters: User *user, char *command
Called for every message (other than a CTCP PING or empty message) received by ChanServ. See the OperServ "command" callback for details.
HELP
Parameters: User *user, char *param
Called when the HELP command is used with a parameter. The callback should return 1 if it processes the message, 0 otherwise.
HELP COMMANDS
Parameters: User *user, int which
Called when the HELP COMMANDS command is used. The which parameter is 0 when called after the list of unprivileged commands and 1 after the list of privileged commands (those shown to IRC operators). The callback routine should always return 0.
INVITE
Parameters: User *u, Channel *c, ChannelInfo *ci
Called whenever a valid INVITE command is received (i.e., the client has permission to use INVITE for the channel). The callback should return 0 to allow normal processing to continue or 1 to abort further processing.
SET
Parameters: User *u, ChannelInfo *ci, char *option, char *param
Called when the SET command is used. All parameters are guaranteed to be valid (non-NULL), and standard permission checks will have been performed (so `u' either is identified for ci or is a Services administrator). The callback routine should return 1 if it processes the given option, 0 otherwise.
SET MLOCK
Parameters: User *u, ChannelInfo *ci, int modechar, int add, char **av
Called for each valid mode character in a SET MLOCK command. add is nonzero if adding modes, zero if removing them. av points to the first argument for the mode; there are guaranteed to be enough arguments for the mode character (provided the number of arguments in the mode definition is set correctly. The new mode lock (currently being constructed) is stored in the ci->mlock structure. The callback routine should return 1 if it encounters an invalid parameter for a mode, 0 otherwise.

Also called with modechar set to zero when all modes have been processed. In this case, add and av are undefined, and the callback routine should return 1 if there is a problem with the mode lock, 0 otherwise.

UNBAN
Parameters: User *u, Channel *c, ChannelInfo *ci
Called whenever a valid UNBAN command is received (i.e., the client has permission to use UNBAN for the channel). The callback should return 0 to allow normal processing to continue or 1 to abort further processing.
UNSET
Parameters: User *u, ChannelInfo *ci, char *option
Called when the UNSET command is used. All parameters are guaranteed to be valid (non-NULL), and standard permission checks will have been performed (so `u' either is identified for ci or is a Services administrator). The callback routine should return 1 if it processes the given option, 0 otherwise.

C-6. MemoServ callbacks

command
Parameters: User *user, char *command
Called for every message (other than a CTCP PING or empty message) received by MemoServ. See the OperServ "command" callback for details.
HELP
Parameters: User *user, char *param
Called when the HELP command is used with a parameter. The callback should return 1 if it processes the message, 0 otherwise.
HELP COMMANDS
Parameters: User *user, int which
Called when the HELP COMMANDS command is used. The which parameter is 0 when called after the list of unprivileged commands and 1 after the list of privileged commands (those shown to IRC operators). The callback routine should always return 0.
receive memo
Parameters: const User *sender, const char *target, NickGroupInfo *target_ngi, const char *channel, const char *text
Called when a nickname receives a memo. sender is the client sending the memo; target is the recipient's nickname, and target_ngi is the corresponding NickGroupInfo structure. channel is the name of the channel the memo was addressed to if a channel memo, NULL if an ordinary memo. The callback should return 0 to cause the memo to be received by the target nickname normally, 1 if it successfully delivered the memo, or an error message number (from the language string list) if the memo could/should not be delivered.

Callback routines for this callback should use one of the following two priorities (defined in memoserv.h): MS_RECEIVE_PRI_CHECK for routines which check whether the memo is allowed to be sent, or MS_RECEIVE_PRI_DELIVER for actually sending the memo.

SET
Parameters: User *u, MemoInfo *mi, char *option, char *param
Called when the SET command is used. All parameters are guaranteed to be valid (non-NULL), and standard permission checks will have been performed. mi points to the MemoInfo for the client's nickname. The callback routine should return 1 if it handles the given option, 0 otherwise.

C-7. StatServ callbacks

command
Parameters: User *user, char *command
Called for every message (other than a CTCP PING or empty message) received by StatServ. See the OperServ "command" callback for details.
HELP
Parameters: User *user, char *param
Called when the HELP command is used with a parameter. The callback should return 1 if it processes the message, 0 otherwise.
HELP COMMANDS
Parameters: User *user, int which
Called when the HELP COMMANDS command is used. The which parameter is currently always 0. The callback routine should always return 0.

C-8. HTTP server callbacks

auth
Parameters: Client *c, int *close_ptr
Called for each valid request received by the server. c is the client from which the request was received; the request data is stored in the client structure (see http.h), and at a minimum the method, url, version_major, and version_minor fields will be set appropriately. If the request is denied and the connection should be closed after the reply is sent, the callback routine should set *close_ptr to a nonzero value (*close_ptr should not be modified if the request is not denied). The callback routine should return HTTP_AUTH_ALLOW to explicitly allow the request to proceed, HTTP_AUTH_DENY to deny the request (in which case the module must send an appropriate error message), or HTTP_AUTH_UNDECIDED to pass the request through to the next callback; if all authorization callbacks pass the request through, it is treated as allowed.
request
Parameters: Client *c, int *close_ptr
Called for each valid request received by the server and either explicitly allowed or passed through by all authorization callbacks. c is the client from which the request was received; the request data is stored in the client structure (see http.h), and at a minimum the method, url, version_major, and version_minor fields will be set appropriately. If the connection should be closed after the reply is sent, the callback routine should set *close_ptr to a nonzero value. The callback routine should return 1 if it processes the request, 0 otherwise.