Added comments to m_cloaking.cpp

git-svn-id: http://svn.inspircd.org/repository/trunk/inspircd@379 e03df62e-2008-0410-955e-edbf42e46eb7

diff --git a/src/InspIRCd.layout b/src/InspIRCd.layout
index 342b4d6ebc80d9238d650dc58a2054e90117fc77..e1fdf1462169fc7240435fb889f0098ab93cc7c1 100644 (file)
--- a/src/InspIRCd.layout
+++ b/src/InspIRCd.layout
@@ -1,5 +1,5 @@
 [Editors]
-Focused=1
+Focused=-1
 Order=7,3,2,6,25,24,-1,1,4,5,0
 
 [Editor_0]
@@ -12,10 +12,10 @@ LeftChar=1
 
 [Editor_1]
 Open=1
-Top=1
-CursorCol=1
-CursorRow=2503
-TopLine=2471
+Top=0
+CursorCol=71
+CursorRow=2385
+TopLine=2361
 LeftChar=1
 
 [Editor_2]
@@ -84,10 +84,10 @@ LeftChar=1
 
 [Editor_10]
 Open=1
-Top=0
-CursorCol=29
-CursorRow=65
-TopLine=19
+Top=1
+CursorCol=3
+CursorRow=146
+TopLine=91
 LeftChar=1
 
 [Editor_11]

diff --git a/src/modules/m_cloaking.cpp b/src/modules/m_cloaking.cpp
index c9fe717663cac051adf0da46c10a6d485d85e96a..aae1820360d79ca3b57781af854d80a85a82f1fd 100644 (file)
--- a/src/modules/m_cloaking.cpp
+++ b/src/modules/m_cloaking.cpp
@@ -1,5 +1,17 @@
-#include <stdio.h>
+// Hostname cloaking (+x mode) module for inspircd.
+// version 1.0.0.1 by brain (C. J. Edwards) Mar 2004.
+//
+// When loaded this module will automatically set the
+// +x mode on all connecting clients.
+//
+// Setting +x on a client causes the module to change the
+// dhost entry (displayed host) for each user who has the
+// mode, cloaking their host. Unlike unreal, the algorithm
+// is non-reversible as uncloaked hosts are passed along
+// the server->server link, and all encoding of hosts is
+// done locally on the server by this module.
 
+#include <stdio.h>
 #include "users.h"
 #include "channels.h"
 #include "modules.h"
@@ -15,12 +27,19 @@ class ModuleCloaking : public Module
  public:
        ModuleCloaking()
        {
+               // We must create an instance of the Server class to work with
                Srv = new Server;
                
-               // doesn't require oper, client umode with no params
-               // (actually, you cant have params for a umode!)
+               // we must create a new mode. Set the parameters so the
+               // mode doesn't require oper, and is a client usermode
+               // with no parameters (actually, you cant have params for a umode!)
                if (!Srv->AddExtendedMode('x',MT_CLIENT,false,0,0))
                {
+                       // we couldn't claim mode x... possibly anther module has it,
+                       // this might become likely to happen if there are a lot of 3rd
+                       // party modules around in the future -- any 3rd party modules
+                       // SHOULD implement a system of configurable mode letters (e.g.
+                       // from a config file)
                        Srv->Log(DEFAULT,"*** m_cloaking: ERROR, failed to allocate user mode +x!");
                        printf("Could not claim usermode +x for this module!");
                        exit(0);
@@ -29,25 +48,44 @@ class ModuleCloaking : public Module
        
        virtual ~ModuleCloaking()
        {
+               // not really neccessary, but free it anyway
                delete Srv;
        }
        
        virtual Version GetVersion()
        {
+               // returns the version number of the module to be
+               // listed in /MODULES
                return Version(1,0,0,1);
        }
        
        virtual bool OnExtendedMode(userrec* user, chanrec* chan, char modechar, int type, bool mode_on, string_list &params)
        {
-               Srv->Log(DEBUG,"in mode handler");
+               // this method is called for any extended mode character.
+               // all module modes for all modules pass through here
+               // (unless another module further up the chain claims them)
+               // so we must be VERY careful to only act upon modes which
+               // we have claimed ourselves. This is a feature to allow
+               // modules to 'spy' on extended mode activity if they so wish.
                if ((modechar == 'x') && (type == MT_CLIENT))
                {
-                       Srv->Log(DEBUG,"this is my mode!");
+                       // we've now determined that this is our mode character...
+                       // is the user adding the mode to their list or removing it?
                        if (mode_on)
                        {
-                               Srv->Log(DEBUG,"mode being turned on");
+                               // the mode is being turned on - so attempt to
+                               // allocate the user a cloaked host using a non-reversible
+                               // algorithm (its simple, but its non-reversible so the
+                               // simplicity doesnt really matter). This algorithm
+                               // will not work if the user has only one level of domain
+                               // naming in their hostname (e.g. if they are on a lan or
+                               // are connecting via localhost) -- this doesnt matter much.
                                if (strstr(user->host,"."))
                                {
+                                       // in inspircd users have two hostnames. A displayed
+                                       // hostname which can be modified by modules (e.g.
+                                       // to create vhosts, implement chghost, etc) and a
+                                       // 'real' hostname which you shouldnt write to.
                                        std::string a = strstr(user->host,".");
                                        char ra[64];
                                        long seed,s2;
@@ -61,31 +99,40 @@ class ModuleCloaking : public Module
                        }
                        else
                        {
-                               Srv->Log(DEBUG,"cloak: de-allocated cloak");
+                               // user is removing the mode, so just restore their real host
+                               // and make it match the displayed one.
                                strcpy(user->dhost,user->host);
                        }
+                       // this mode IS ours, and we have handled it. If we chose not to handle it,
+                       // for example the user cannot cloak as they have a vhost or such, then
+                       // we could return 0 here instead of 1 and the core would not send the mode
+                       // change to the user.
                        return 1;
                }
                else
                {
                        // this mode isn't ours, we have to bail and return 0 to not handle it.
-                       Srv->Log(DEBUG,"not my mode");
                        return 0;
                }
        }
 
        virtual void OnUserConnect(userrec* user)
        {
-               Srv->Log(DEBUG,"Sending SAMODE +x for user");
-               char* modes[2];
-               modes[0] = user->nick;
-               modes[1] = "+x";
-               Srv->SendMode(modes,2,user);
-               Srv->Log(DEBUG,"Sent SAMODE +x for user");
+               // Heres the weird bit. When a user connects we must set +x on them, so
+               // we're going to use the SendMode method of the Server class to send
+               // the mode to the client. This is basically the same as sending an
+               // SAMODE in unreal. Note that to the user it will appear as if they set
+               // the mode on themselves.
+               
+               char* modes[2];                 // only two parameters
+               modes[0] = user->nick;          // first parameter is the nick
+               modes[1] = "+x";                // second parameter is the mode
+               Srv->SendMode(modes,2,user);    // send these, forming the command "MODE <nick> +x"
        }
 
 };
 
+// stuff down here is the module-factory stuff. For basic modules you can ignore this.
 
 class ModuleCloakingFactory : public ModuleFactory
 {