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

2 files changed, 162 insertions, 3 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
diff --git a/docs/WIN32.txt b/docs/WIN32.txt
index 21adb7e41..b2caf96bf 100644
--- a/docs/WIN32.txt
+++ b/docs/WIN32.txt
@@ -53,16 +53,22 @@ the following free components from Microsoft. Once downloaded install these pack
       (ie.. PROXY_SCANNER=1), note the proxy scan is not the best and its recommended to use
       another thrid party scanner.
 
-   D. If you are using Visual Studio 6, this next line can be very important. If you are an 
+   D. Do you want to use the MD5 message-digest algorithm to encrypt passwords?
+	  (Selecting "yes" protects your passwords from being stolen if someone
+	  gains access to the Services databases, but makes it impossible to recover
+      forgotten passwords. There is no way to reverse this operation, so make
+	  sure you really want to enable it.). Change DB_ENCRYPTION to be equal to 1
+
+   E. If you are using Visual Studio 6, this next line can be very important. If you are an 
       error during compile about "unresolved external symbol __ftol2", remove the # in front
       of VC6=/QIfist and attempt to compile again.
 
-   E. When compiling if you get an error about 'Cannot find wsock32.lib' or 'Cannot find 
+   F. When compiling if you get an error about 'Cannot find wsock32.lib' or 'Cannot find 
       msvcrt.lib' You need to define the libpath, in the LIBPATH directive. You can define 
       the path one of two ways, either with \ or / if you use \ you must add a secondary \ 
       so c:\mysql would be c:\\sdk\lib be sure to remove the # in front of LFLAGS
 
-   F. Most import is to set the DATDEST to be the folder name where data will be stored. 
+   G. Most import is to set the DATDEST to be the folder name where data will be stored. 
       This does not need to be the full path just the folder under the main executable 
       in which data will exist. In our example we will use "data"