BUILD : 1.7.8 (574) BUGS : N/A NOTES : Internal Events, Win32 can build with encryption, nickIsServices() works if format is nick@services

git-svn-id: svn://svn.anope.org/anope/trunk@574 31f1291d-b8d6-0310-a050-a5561fc1590b


git-svn-id: http://anope.svn.sourceforge.net/svnroot/anope/trunk@424 5417fbe8-f217-4b02-8779-1006273d7864

1 files changed, 153 insertions, 0 deletions

diff --git a/docs/EVENTS b/docs/EVENTS
new file mode 100644
index 000000000..4d4819588
--- /dev/null
+++ b/docs/EVENTS
@@ -0,0 +1,153 @@
+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 writting 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;

+	}

+

+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, 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 module error code so you can confirm that 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(char *message);

+

+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, 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 module error code so you can confirm that it was added

+   correctly.

+

+E. With that setup in your function you will be passed 1 items, 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(char *source)

+	{

+

+  		if (!stricmp(source, EVENT_START)) {

+      		alog("Saving the databases! has started");

+		} else {

+      		alog("Saving the databases is complete");

+  		}

+  		return MOD_CONT;

+	}

+

+==============================================================================================

+4. Triggered Events List

+==============================================================================================

+| Event Hook                  |    Event Argument                                            |

+==============================================================================================

+| EVENT_DB_SAVING             | EVENT_START, EVENT_STOP                                      |

+| EVENT_NEWNICK               | Nick as it connected                                         |

+| EVENT_BOT_UNASSIGN          | Channel name                                                 |

+| EVENT_BOT_JOIN              | Channel name                                                 |

+| EVENT_BOT_CREATE            | Bot Nick                                                     |

+| EVENT_BOT_CHANGE            | Bot Nick                                                     |

+| EVENT_BOT_DEL               | Bot Nick                                                     |

+| EVENT_BOT_ASSIGN            | Bot Nick                                                     |

+| EVENT_TOPIC_UPDATED         | Channel Name                                                 |

+| EVENT_CHAN_EXPIRE           | Channel Name                                                 |

+| EVENT_CHAN_REGISTERED       | Channel Name                                                 |

+| EVENT_CHAN_DROP             | Channel Name                                                 |

+| EVENT_CHAN_FORBIDDEN        | Channel Name                                                 |

+| EVENT_CHAN_SUSPENDED        | Channel Name                                                 |

+| EVENT_CONNECT               | EVENT_START, EVENT_STOP                                      |

+| EVENT_DB_EXPIRE             | EVENT_START, EVENT_STOP                                      |

+| EVENT_RESTART               | EVENT_START                                                  |

+| EVENT_SHUTDOWN              | EVENT_START, EVENT_STOP                                      |

+| EVENT_SIGNAL                | quit message                                                 |

+| EVENT_NICK_REGISTED         | Nick                                                         |

+| EVENT_NICK_DROPPED          | Nick                                                         |

+| EVENT_NICK_FORBIDDEN        | Nick                                                         |

+| EVENT_CHANGE_NICK           | Nick                                                         |

+==============================================================================================
\ No newline at end of file