pegasus/anope
1
0
Fork 0
mirror of https://github.com/anope/anope.git synced 2026-06-23 20:46:38 +02:00
Code Activity
Files
ffbcff160474cd45fbcbbadaff32f38e1d7fea71
anope/docs/EVENTS
T
geniusdex geniusdex@31f1291d-b8d6-0310-a050-a5561fc1590b 34a88d38c3 BUILD : 1.7.19 (1318) BUGS : 791 NOTES : Fixed inconsistent use of ACCESS events 
git-svn-id: svn://svn.anope.org/anope/trunk@1318 31f1291d-b8d6-0310-a050-a5561fc1590b


git-svn-id: http://anope.svn.sourceforge.net/svnroot/anope/trunk@1036 5417fbe8-f217-4b02-8779-1006273d7864
2007-12-15 15:50:16 +00:00

417 lines
17 KiB
Plaintext
Raw Blame History

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.
View Git Blame Copy Permalink