BUILD : 1.7.8 (577) BUGS : NOTES : Applied a patch in behalf of heinz.

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


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

1 files changed, 156 insertions, 155 deletions

diff --git a/docs/EVENTS b/docs/EVENTS
index 0fae9f766..594df325b 100644
--- a/docs/EVENTS
+++ b/docs/EVENTS
@@ -1,155 +1,156 @@
-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_REGISTERED       | Nick                                                         |

-| EVENT_NICK_DROPPED          | Nick                                                         |

-| EVENT_NICK_FORBIDDEN        | Nick                                                         |

-| EVENT_CHANGE_NICK           | Nick                                                         |

-| EVENT_USER_LOGOFF           | Nick                                                         |

-==============================================================================================

-

+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_REGISTERED       | Nick                                                         |
+| EVENT_NICK_DROPPED          | Nick                                                         |
+| EVENT_NICK_FORBIDDEN        | Nick                                                         |
+| EVENT_NICK_EXPIRE           | Nick                                                         |
+| EVENT_CHANGE_NICK           | Nick                                                         |
+| EVENT_USER_LOGOFF           | Nick                                                         |
+==============================================================================================
+