diff options
Diffstat (limited to 'docs/EVENTS')
| -rw-r--r-- | docs/EVENTS | 416 |
1 files changed, 416 insertions, 0 deletions
diff --git a/docs/EVENTS b/docs/EVENTS new file mode 100644 index 000000000..bc8af9dce --- /dev/null +++ b/docs/EVENTS @@ -0,0 +1,416 @@ +Anope Internal Events +--------------------- + +1) Intro +2) Complex Events +3) Triggered Events +4) Triggered Events List + +1) Introduction to Internal Events + + Internal Events are setup to give module developers more information + about what the core is doing at different times. This information can + be as complex as data we are feeding to the uplink, to simple triggered + events such as the databases being saved. A list of triggered events + can be found below. Additional there is a module included with the core + which can provide some clue as to how to use the code in your modules. + The rest of this document assumes that you are used to writing modules. + +2) Complex Events + + This type of events are based around what happens when we talk to the + IRCd, much like MESSAGE events that the IRCD sends to us. The events + are triggered when Anope writes to the ircd. To watch for these events + you must have some knowledge of how the IRCd command system works. In + our example we will trap for NICK events. + + A) All functions most be formatted as: + + int functioname(char *source, int ac, char **av); + + B) In AnopeInit you must declare EvtMessage in some fashion, it is into + this variable that we will create the event handler. Here is what the + base AnopeInit should look like at this point: + + int AnopeInit(int argc, char **argv) + { + EvtMessage *msg = NULL; + int status; + + moduleAddAuthor(AUTHOR); + moduleAddVersion(VERSION); + return MOD_CONT; + } + + Note that AUTHOR and VERSION should be defined above the AnopeInit + function, just like you should do with any module. + + C) Pass "createEventHandler" the name of the message in this case NICK, + and the function that was created in Step A. At this point you should + assign the return of "createEventHandler" to the EvtMessage variable. + + msg = createEventHandler("NICK", my_nick); + + D) The Handler is not ready for use yet; now you must add it to the hash + with "moduleAddEventHandler". You will want to pass to this function + the return of "createEventHandler". + + status = moduleAddEventHandler(msg); + + It will return the same module error codes as adding a regular message, + which you can use to confirm it was added correctly. + + E) With that setup in your function you will be passed 3 items. The source + most of the time this will be set to ServerName or NULL; consult our + IRCd documentation about how messages are formatted. AC is the count of + variables you will find in AV. + + int my_nick(char *source, int ac, char **av) + { + alog("Internal Event - nick is %s",av[0]); + return MOD_CONT; + } + +3) Triggered Events + + These events also known as "event hooks" are internal events such as + expiring of nicks to the saving of databases. + + A) All functions most be formatted as: + + int functioname(int argc, char **argv); + + B) In AnopeInit you must declare EvtHook in some fashion; it is into + this variable that we will create the event handler. Here is what + the base AnopeInit should look like at this point: + + int AnopeInit(int argc, char **argv) + { + EvtHook *hook = NULL; + int status; + + moduleAddAuthor(AUTHOR); + moduleAddVersion(VERSION); + return MOD_CONT; + } + + C) Pass "createEventHook" the name of the event. In this case we are + going to hook to the saving of databases, "EVENT_DB_SAVING". + + hook = createEventHook(EVENT_DB_SAVING, my_save); + + D) The Handler is not ready for use yet; now you must add it to the hash + with "moduleAddEventHook". You will want to pass to this function the + return of "createEventHook" + + status = moduleAddEventHook(hook); + + It will return the same module error codes as adding a regular message, + which you can use to confirm it was added correctly. + + E) With that setup in your function you will be passed 1 item. The message + is very simple; it could be as simple as a start, stop or message. In + the case of saving it has a start and stop. + + int my_save(int argc, char **argv) + { + if (argc < 1) { + return MOD_CONT; + } + + if (!stricmp(argv[0], EVENT_START)) { + alog("Saving the databases! has started"); + } else { + alog("Saving the databases is complete"); + } + return MOD_CONT; + } + +4) Triggered Events List + + Here's a list of all event hooks we currently offer, with a description + of what argument is being passed to the event functions for this type of + event. All arguments are plain-text strings (char *). The list is sorted + in alphabetical order. + + Note that all events are emitted AFTER the action has taken place, so + any deleted nick/channel/etc won't exist anymore and any created one will + exist when your function is being run, unless noted otherwise. + + Also note that EVENT_START and EVENT_STOP should not be matched with an + equal sign, but with string comparision. See the bundled events module for + an example on how to do this. + + The arguments are given as av[0] for the first argument, av[1] for the + second argument, and so on. If av[0] and av[1] are given, the event has + two arguments, and argc should be 2. + + EVENT_ACCESS_ADD + An user has been added to a channel access list. + av[0] Name of the channel the user has been added to. + av[1] The nickname of the user that has just added an entry to the + access list. + av[2] The nickname of the user that has been added to the access + list. + av[3] The level number the user has been added with. + + EVENT_ACCESS_CHANGE + An user level has been changed on a channel access list. + av[0] Name of the channel the access list has been modified which. + av[1] The nickname of the user that has just modified the access + list of the channel. + av[2] The nickname of the user wich his access level has just been + modified. + av[3] The new access level for the user. + + EVENT_ACCESS_CLEAR + A channel access list has been cleared. + av[0] Name of the channel the access list has been cleared of + av[1] The nickname of the user that has cleared the access list + + EVENT_ACCESS_DEL + An user has been deleted of a channel access list. + av[0] Name of the channel the access entry has been deleted which. + av[1] The nickname of the user that has just deleted the access entry. + av[2] [OPTIONAL] The nickname of the user wich his access level has just + been removed. Not present if numbers were used (e.g. /cs access + del 7). + + EVENT_BOT_ASSIGN + A BotServ bot has been assigned to a channel. + av[0] Name of the channel the bot has been assigned to. + av[1] The nickname of the bot that has been assigned to the channel. + + EVENT_BOT_BAN + A BotServ bot has banned a user, e.g. kickers. + av[0] The nick of the user banned. + av[1] The Channel the user was banned from. + av[2] The mask that was banned. + + EVENT_BOT_CHANGE + The properties of a BotServ bot have been changed. + av[0] The nickname of the bot involved. + + EVENT_BOT_CREATE + A new BotServ bot has been created, and is ready to use. + av[0] The nickname of the newly created bot. + + EVENT_BOT_DEL + A BotServ bot is being deleted from BotServ. This event is being sent + just before the actual deletion is performed. + av[0] The nickname of the bot being deleted. + + EVENT_BOT_FANTASY + A fantasy command of the bot has been triggered. This event should be + used to create your own fantasy commands. + av[0] The fantasy command that has been triggered without leading '!'. + av[1] The nickname of the user that has triggered the fantasy + command. + av[2] The name of the channel the fantasy command has been triggered + on. + av[3] Contains any optional paramenters passed after the fantasy + command. If none are present, this will not exist, and argc will + will be 3. + + EVENT_BOT_FANTASY_NO_ACCESS + A fantasy command of the bot has been triggered by someone without + access to BotServ FANTASY commands on the channel. This will NOT + trigger if someone with access has triggered a fantasy command; use + EVENT_BOT_FANTASY for those. Hook to both events to catch both event + triggers. + av[0] The fantasy command that has been triggered without leading '!'. + av[1] The nickname of the user that has triggered the fantasy + command. + av[2] The name of the channel the fantasy command has been triggered + on. + av[3] Contains any optional paramenters passed after the fantasy + command. If none are present, this will not exist, and argc will + will be 3. + + EVENT_BOT_JOIN + A BotServ bot has joined a channel and opped itself. + av[0] The channel name the bot has just joined. + av[1] The nickname of the bot that has joined the channel. + + EVENT_BOT_KICK + A BotServ bot has kicked a user from a channel. + av[0] The name of the user that has been kicked. + av[1] The name of the channel the user was kicked from. + av[2] The reason for the kick. + + EVENT_BOT_UNASSIGN + A BotServ bot is being unassigned from a channel. This event is being + sent before the actual removing of the bot is done. + av[0] The channel name the bot has been unassigned from. + av[1] The nickname of the bot that has been unassigned. + + EVENT_CHAN_DROP + A channel has been dropped and deleted. + av[0] The name of the channel that has been dropped. + + EVENT_CHAN_EXPIRE + A channel has been expired and will be deleted. The event will be + emitted just before the actual channel deletion happens. + av[0] The name of the channel that has been expired. + + EVENT_CHAN_FORBIDDEN + A channel has been forbidden (ChanServ FORBID). + av[0] The name of the channel that has been forbidden. + + EVENT_CHAN_KICK + Someone has just been kicked from a channel. + av[0] The nick of the user that has been kicked. + av[1] The channel the user has been kicked from. + + EVENT_CHAN_REGISTERED + A new channel has been registered. + av[0] The name of the channel that has been registered. + + EVENT_CHAN_SUSPENDED + A channel has been suspended (ChanServ SUSPEND). + av[0] The name of the channel that has been suspended. + + EVENT_CHAN_UNSUSPEND + A channel has been unsuspended (ChanServ UNSUSPEND). + av[0] The name of the channel that has been unsuspended. + + EVENT_CHANGE_NICK + A user has just changed it's nick. + av[0] The new nickname of the user. + + EVENT_CONNECT + This event is emitted when the connection to our uplink hub is being + made. + av[0] EVENT_START or EVENT_STOP, to indicate if it's emitted before + or after the connection has been made. EVENT_STOP is emitted + before our burst is being sent over the link. + + EVENT_DB_EXPIRE + This event is emitted when the expiry routines for all things that can + expire in Anope are being run. + av[0] EVENT_START or EVENT_STOP, to indicate if it's being emitted + before or after the expiry routines have been run. + + EVENT_DB_SAVING + This event is emitted when the databases are being saved. + av[0] EVENT_START or EVENT_STOP, to indicate if it's emitted before + or after the saving routines have been run. + + EVENT_DB_BACKUP + This event is emitted when the databases are backed up. + av[0] EVENT_START when the backup commences, and EVENT_STOP when it + finishes. + + EVENT_DEFCON_LEVEL + The DefCon level has just been changed. This event is emitted before + any DefCon-related action is taken. The internal DefConLevel has + already been raised at this point. + av[0] The new level of DefCon being invoked. + + EVENT_GROUP + A user has grouped it's nickname to another user group. + av[0] The nickname of the user that joined the group. + + EVENT_JOIN_CHANNEL + A user joins a channel. + av[0] EVENT_START or EVENT_STOP. EVENT_START when the user has passed + all access checks and is allowed to join, but has not yet + joined the channel. EVENT_STOP when the user has joined and all + needed modes are set etc. + av[1] The nickname of the user joining the channel. + av[2] The name of the channel the user has joined. + + EVENT_NEWNICK + A new user has been introduced on the network. + av[0] The nickname of the newly introduced user. + + EVENT_NICK_DROPPED + A user's nick has just been dropped. Note that the nickname information + has already been deleted! + av[0] The nickname of the user that has just been dropped. + + EVENT_NICK_EXPIRE + A user's nick has just expired. Note that, as with EVENT_NICK_DROPPED, + the nickname information has already been deleted! + av[0] The nickname of the user that has just expired. + + EVENT_NICK_FORBIDDEN + A user's nick has just been forbidden. + av[0] The nickname that has just been forbidden. + + EVENT_NICK_IDENTIFY + A user has just identified for it's nickname with NickServ. + av[0] The nickname of the user that just identified. + + EVENT_NICK_LOGOUT + A user has just (been) logged out. + av[0] The nickname of the user that has (been) logged out. + + EVENT_NICK_REGISTERED + A new user has just registered it's nickname. This event is being + emitted when the registration is completed, but the user modes have not + yet been set. + av[0] The nickname of the newly registered user. + + EVENT_NICK_SUSPENDED + A user's nick has just been suspended. + av[0] The nickname that has just been suspended. + + EVENT_NICK_UNSUSPEND + A user's nick has just been unsuspended. + av[0] The nickname that has just been unsuspended. + + EVENT_PART_CHANNEL + A user parts a channel. + av[0] EVENT_START or EVENT_STOP. EVENT_START when the user is about + to be removed from the channel internally, EVENT_STOP when + this has been done. + av[1] The nickname of the user parting the channel. + av[2] The name of the channel the user has parted. + av[3] The reason the user parted the channel, this is not always sent + so check the count to make sure it was passed. (ac == 4) + + EVENT_RELOAD + This event is emitted after the configuration file has been reloaded. + av[0] Always EVENT_START. + + EVENT_RESTART + This event is emitted before the services are being restarted. + av[0] Always EVENT_START. + + EVENT_SERVER_CONNECT + A new server has just connected to the network. + av[0] The name of the new server. + + EVENT_SERVER_SQUIT + A server has sent an SQUIT and is about to be removed from the + network. This event is being sent before the server is actually + removed from the network. + av[0] The name of the server that is being removed. + + EVENT_SHUTDOWN + This event is emitted when Anope is being shut down. + av[0] EVENT_START or EVENT_STOP, to indicate where in the process of + restarting the core is. With EVENT_START, services are still + fully online and operating. With EVENT_STOP, every internal + clean up has been done already, and the SQUIT has been sent; + the only thing done after emitting the event is closing the + socket to the uplink hub. + + EVENT_SIGNAL + This event is emitted when Anope is quitting because of a signal it + received. + av[0] The quit message that will be sent with the SQUIT for this + shutdown. + + EVENT_TOPIC_UPDATED + A channel topic has been succesfully updated. Note that this event is + only emitted if the new topic has been fully accepted and set by the + Anope core. + av[0] The name of the channel involved. + av[1] The new topic set on the channel. + + EVENT_USER_LOGOFF + A user has left the network. This event is emitted before the internal + removal is performed, so the user still exists internally. + av[0] The nickname of the user leaving the network. |