From 2bcef988d778ee30371133b8ef052fbae37cd05a Mon Sep 17 00:00:00 2001 From: brain Date: Sat, 26 Nov 2005 17:48:26 +0000 Subject: Added tons of comments. These will probably stay. git-svn-id: http://svn.inspircd.org/repository/trunk/inspircd@1958 e03df62e-2008-0410-955e-edbf42e46eb7 --- src/modules/m_spanningtree.cpp | 121 +++++++++++++++++++++++++++++------------ 1 file changed, 87 insertions(+), 34 deletions(-) diff --git a/src/modules/m_spanningtree.cpp b/src/modules/m_spanningtree.cpp index 4cc4b50d6..4cf8cbdea 100644 --- a/src/modules/m_spanningtree.cpp +++ b/src/modules/m_spanningtree.cpp @@ -27,12 +27,27 @@ using namespace std; Server *Srv; +// To attach sockets to the core of the ircd, we must use the InspSocket +// class which can be found in socket.h. This class allows modules to create +// listening and outbound sockets and attach sockets to existing (connected) +// file descriptors. These file descriptors can then be associated with the +// core of the ircd and bound to the socket engine. +// To use InspSocket, we must inherit from it, as shown in TreeSocket below. + class TreeSocket : public InspSocket { std::string myhost; public: + // InspSocket has several constructors used for various situations. + // This constructor is used to create a socket which may be used + // for both inbound and outbound (listen() and connect()) operations. + // When you inherit InspSocket you MUST call the superclass constructor + // within InspSocket, as shown below, unless you plan to completely + // override all behaviour of the class, which would prove to be more + // trouble than it's worth unless you're doing something really fancy. + TreeSocket(std::string host, int port, bool listening, unsigned long maxtime) : InspSocket(host, port, listening, maxtime) { @@ -40,21 +55,33 @@ class TreeSocket : public InspSocket myhost = host; } + // This simpler constructor of InspSocket is used when you wish to + // associate an existing file descriptor with an InspSocket class, + // or a class inherited from InspSocket. As before, you must call + // the superclass. Not doing so will get your module into a whole + // world of hurt. Similarly, your inherited class MUST implement + // the constructors you use even if all it does is call the parent. + TreeSocket(int newfd) : InspSocket(newfd) { - // Associate with an existing file descriptor (accepted from incoming connection) } + // This method is called when an outbound socket (connect() style) + // finishes connecting. Connections are asyncronous, so you should + // not just assume that immediately after you instantiate a socket + // it is connected or failed. This takes time, and when the results + // are available for you, this method will be called. + virtual bool OnConnected() { - Srv->Log(DEBUG,"Connected"); - Srv->SendToModeMask("o",WM_AND,"*** CONNECTED!"); this->Write("GET / HTTP/1.1\r\nHost: " + myhost + "\r\nConnection: Close\r\n\r\n"); - Srv->SendToModeMask("o",WM_AND,"*** DATA WRITTEN ***"); - Srv->Log(DEBUG,"Wrote"); return true; } + + // When errors occur on the connection, this event will be triggered. + // Check the programmer docs for information on possible values for + // the InspSocketError type. virtual void OnError(InspSocketError e) { @@ -64,16 +91,32 @@ class TreeSocket : public InspSocket Srv->SendToModeMask("o",WM_AND,x); } + // When a socket disconnects, this method is triggered. You cannot + // prevent the disconnection. + virtual int OnDisconnect() { Srv->Log(DEBUG,"Disconnect"); Srv->SendToModeMask("o",WM_AND,"*** DISCONNECTED!"); return true; } - + + // When data is ready to be read from a socket, this method will + // be triggered, and within it, you should call this->Read() to + // read any pending data. Up to 10 kilobytes of data may be returned + // for each call to Read(), and you should not call Read() more + // than once per method call. You should also not call Read() + // outside of OnDataReady(), doing so will just result in Read() + // returning NULL. If Read() returns NULL and you are within the + // OnDataReady() event this usually indicates an EOF condition + // and the socket should be closed by returning false from this + // method. If you return false, the core will remove your socket + // from its list, and handle the cleanup (such as deleting the + // pointer) for you. This means you do not need to track your + // socket resources once they are associated with the core. + virtual bool OnDataReady() { - Srv->Log(DEBUG,"Data"); Srv->SendToModeMask("o",WM_AND,"*** DATA ***"); char* data = this->Read(); if (data) @@ -82,41 +125,54 @@ class TreeSocket : public InspSocket } return (data != NULL); } + + // For outbound (connect style()) sockets only, the connection + // may time out, meaning that the time taken to connect was + // more than you specified when constructing the object. + // If this occurs, the OnTimeout method, as well as OnError, + // will be called to notify your class of the event. virtual void OnTimeout() { - Srv->Log(DEBUG,"Timeout"); Srv->SendToModeMask("o",WM_AND,"*** TIMED OUT ***"); } - + + // For any type of socket, when the file descriptor is freed + // with close(), under any situation, the OnClose() method + // will be called. + virtual void OnClose() { Srv->SendToModeMask("o",WM_AND,"*** CLOSED ***"); } + + // When a connection comes in over an inbound (listen() style) + // socket, the OnIncomingConnection method is triggered. You + // will be given a new file descriptor, and the ip of the + // connecting host. Most of the time, you will want to + // instantiate another class inherited from InspSocket, + // using the (int) constructor which will associate that class + // with the new file descriptor. You will usually then need + // to add that socket to the core, so that you will receive + // notifications for its activity. virtual int OnIncomingConnection(int newsock, char* ip) { - Srv->SendToModeMask("o",WM_AND,"*** INCOMING ***"); - // use the (int) constructor to associate an incoming - // connection with a class, without actually creating - // a connection or binding from scratch. TreeSocket* s = new TreeSocket(newsock); Srv->AddSocket(s); - char message[1024]; - sprintf(message,"Added new socket to list with fd %d from %s",newsock,ip); - Srv->Log(DEBUG,message); return true; } }; +// This is a test function which creates an outbound socket to a given +// hostname. It provides an example of how to create a new outbound +// socket to a host. + void handle_connecttest(char **parameters, int pcnt, userrec *user) { - // create a new class of type TreeSocket. - std::string a = parameters[0]; - TreeSocket* s = new TreeSocket(a,80,false,10); - Srv->Log(DEBUG,"Create TreeSocket"); - Srv->AddSocket(s); - Srv->Log(DEBUG,"Added socket"); + std::string addr = parameters[0]; + TreeSocket* sock = new TreeSocket(addr,80,false,10); + Srv->AddSocket(sock); } class ModuleSpanningTree : public Module @@ -125,30 +181,27 @@ class ModuleSpanningTree : public Module ModuleSpanningTree() { Srv = new Server; + Srv->AddCommand("CONNECTTEST",handle_connecttest,'o',1,"m_spanningtree.so"); - Srv->Log(DEBUG,"ModCreate"); + + // This is an example of how to create a new inbound socket to a host. + // Please remember that so long as you AddSocket() your sockets, you + // do not need to track resources and do not need to delete your classes + // when you are finished with them. + TreeSocket* listeningsock = new TreeSocket("127.0.0.1",11111,true,10); Srv->AddSocket(listeningsock); } - - virtual void OnUserJoin(userrec* user, chanrec* channel) - { - } - + virtual ~ModuleSpanningTree() { delete Srv; } - + virtual Version GetVersion() { return Version(1,0,0,0,VF_STATIC|VF_VENDOR); } - - virtual void OnUserConnect(userrec* user) - { - } - }; -- cgit v1.2.3