Added extra docs for new config system

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

1 files changed, 192 insertions, 188 deletions

diff --git a/docs/man/man3/InspSocket.3 b/docs/man/man3/InspSocket.3
index 63f2475d6..fc39dc8e6 100644
--- a/docs/man/man3/InspSocket.3
+++ b/docs/man/man3/InspSocket.3
@@ -1,4 +1,4 @@
-.TH "InspSocket" 3 "12 Dec 2005" "Version 1.0Betareleases" "InspIRCd" \" -*- nroff -*-
+.TH "InspSocket" 3 "14 Dec 2005" "Version 1.0Betareleases" "InspIRCd" \" -*- nroff -*-
 .ad l
 .nh
 .SH NAME
@@ -163,14 +163,14 @@ Definition at line 47 of file socket.h.
 .PP
 The default constructor does nothing and should not be used. 
 .PP
-Definition at line 49 of file socket.cpp.
+Definition at line 48 of file socket.cpp.
 .PP
 References I_DISCONNECTED, and state.
 .PP
 .nf
-50 {
-51         this->state = I_DISCONNECTED;
-52 }
+49 {
+50         this->state = I_DISCONNECTED;
+51 }
 .fi
 .PP
 .SS "InspSocket::InspSocket (int newfd, char * ip)"
@@ -179,16 +179,17 @@ This constructor is used to associate an existing connecting with an InspSocket
 .PP
 The given file descriptor must be valid, and when initialized, the InspSocket will be set with the given IP address and placed in CONNECTED state.
 .PP
-Definition at line 54 of file socket.cpp.
+Definition at line 53 of file socket.cpp.
 .PP
 References SocketEngine::AddFd(), fd, I_CONNECTED, IP, state, and X_ESTAB_MODULE.
 .PP
 .nf
-55 {
-56         this->fd = newfd;
-57         this->state = I_CONNECTED;
-58         this->IP = ip;
-59         SE->AddFd(this->fd,true,X_ESTAB_MODULE);
+54 {
+55         this->fd = newfd;
+56         this->state = I_CONNECTED;
+57         this->IP = ip;
+58         SE->AddFd(this->fd,true,X_ESTAB_MODULE);
+59         socket_ref[this->fd] = this;
 60 }
 .fi
 .PP
@@ -211,7 +212,7 @@ This constructor is used to create a new socket, either listening for connection
 .PP
 Definition at line 62 of file socket.cpp.
 .PP
-References SocketEngine::AddFd(), addr, addy, Close(), DEBUG, fd, I_CONNECTING, I_ERR_BIND, I_ERR_CONNECT, I_ERR_SOCKET, I_ERROR, I_LISTENING, IP, OnError(), state, timeout, timeout_end, and X_ESTAB_MODULE.
+References SocketEngine::AddFd(), addr, addy, BindSocket(), Close(), DEBUG, fd, I_CONNECTING, I_ERR_BIND, I_ERR_CONNECT, I_ERR_SOCKET, I_ERROR, I_LISTENING, IP, OnError(), OpenTCPSocket(), state, timeout, timeout_end, and X_ESTAB_MODULE.
 .PP
 .nf
 63 {
@@ -239,70 +240,72 @@ References SocketEngine::AddFd(), addr, addy, Close(), DEBUG, fd, I_CONNECTING,
 85                         {
 86                                 this->state = I_LISTENING;
 87                                 SE->AddFd(this->fd,true,X_ESTAB_MODULE);
-88                                 log(DEBUG,'New socket now in I_LISTENING state');
-89                                 return;
-90                         }
-91                 }                       
-92         } else {
-93                 char* ip;
-94                 this->host = host;
-95                 hostent* hoste = gethostbyname(host.c_str());
-96                 if (!hoste) {
-97                         ip = (char*)host.c_str();
-98                 } else {
-99                         struct in_addr* ia = (in_addr*)hoste->h_addr;
-100                         ip = inet_ntoa(*ia);
-101                 }
-102 
-103                 this->IP = ip;
-104 
-105                 timeout_end = time(NULL)+maxtime;
-106                 timeout = false;
-107                 if ((this->fd = socket(AF_INET, SOCK_STREAM, 0)) == -1)
-108                 {
-109                         this->state = I_ERROR;
-110                         this->OnError(I_ERR_SOCKET);
-111                         return;
-112                 }
-113                 this->port = port;
-114                 inet_aton(ip,&addy);
-115                 addr.sin_family = AF_INET;
-116                 addr.sin_addr = addy;
-117                 addr.sin_port = htons(this->port);
-118 
-119                 int flags;
-120                 flags = fcntl(this->fd, F_GETFL, 0);
-121                 fcntl(this->fd, F_SETFL, flags | O_NONBLOCK);
-122 
-123                 if(connect(this->fd, (sockaddr*)&this->addr,sizeof(this->addr)) == -1)
-124                 {
-125                         if (errno != EINPROGRESS)
-126                         {
-127                                 this->Close();
-128                                 this->OnError(I_ERR_CONNECT);
-129                                 this->state = I_ERROR;
-130                                 return;
-131                         }
-132                 }
-133                 this->state = I_CONNECTING;
-134                 SE->AddFd(this->fd,false,X_ESTAB_MODULE);
-135                 return;
-136         }
-137 }
+88                                 socket_ref[this->fd] = this;
+89                                 log(DEBUG,'New socket now in I_LISTENING state');
+90                                 return;
+91                         }
+92                 }                       
+93         } else {
+94                 char* ip;
+95                 this->host = host;
+96                 hostent* hoste = gethostbyname(host.c_str());
+97                 if (!hoste) {
+98                         ip = (char*)host.c_str();
+99                 } else {
+100                         struct in_addr* ia = (in_addr*)hoste->h_addr;
+101                         ip = inet_ntoa(*ia);
+102                 }
+103 
+104                 this->IP = ip;
+105 
+106                 timeout_end = time(NULL)+maxtime;
+107                 timeout = false;
+108                 if ((this->fd = socket(AF_INET, SOCK_STREAM, 0)) == -1)
+109                 {
+110                         this->state = I_ERROR;
+111                         this->OnError(I_ERR_SOCKET);
+112                         return;
+113                 }
+114                 this->port = port;
+115                 inet_aton(ip,&addy);
+116                 addr.sin_family = AF_INET;
+117                 addr.sin_addr = addy;
+118                 addr.sin_port = htons(this->port);
+119 
+120                 int flags;
+121                 flags = fcntl(this->fd, F_GETFL, 0);
+122                 fcntl(this->fd, F_SETFL, flags | O_NONBLOCK);
+123 
+124                 if(connect(this->fd, (sockaddr*)&this->addr,sizeof(this->addr)) == -1)
+125                 {
+126                         if (errno != EINPROGRESS)
+127                         {
+128                                 this->Close();
+129                                 this->OnError(I_ERR_CONNECT);
+130                                 this->state = I_ERROR;
+131                                 return;
+132                         }
+133                 }
+134                 this->state = I_CONNECTING;
+135                 SE->AddFd(this->fd,false,X_ESTAB_MODULE);
+136                 socket_ref[this->fd] = this;
+137                 return;
+138         }
+139 }
 .fi
 .PP
 .SS "InspSocket::~InspSocket ()\fC [virtual]\fP"
 .PP
 The destructor may implicitly call \fBOnClose()\fP, and will close() and shutdown() the file descriptor used for this socket. 
 .PP
-Definition at line 269 of file socket.cpp.
+Definition at line 272 of file socket.cpp.
 .PP
 References Close().
 .PP
 .nf
-270 {
-271         this->Close();
-272 }
+273 {
+274         this->Close();
+275 }
 .fi
 .PP
 .SH "Member Function Documentation"
@@ -311,64 +314,65 @@ References Close().
 .PP
 This method causes the socket to close, and may also be triggered by other methods such as OnTimeout and OnError. 
 .PP
-Definition at line 139 of file socket.cpp.
+Definition at line 141 of file socket.cpp.
 .PP
 References fd, and OnClose().
 .PP
 Referenced by InspSocket(), and ~InspSocket().
 .PP
 .nf
-140 {
-141         if (this->fd != -1)
-142         {
-143                 this->OnClose();
-144                 shutdown(this->fd,2);
-145                 close(this->fd);
-146                 this->fd = -1;
-147         }
-148 }
+142 {
+143         if (this->fd != -1)
+144         {
+145                 this->OnClose();
+146                 shutdown(this->fd,2);
+147                 close(this->fd);
+148                 socket_ref[this->fd] = NULL;
+149                 this->fd = -1;
+150         }
+151 }
 .fi
 .PP
 .SS "int InspSocket::GetFd ()"
 .PP
 This method returns the socket's file descriptor as assigned by the operating system, or -1 if no descriptor has been assigned. 
 .PP
-Definition at line 256 of file socket.cpp.
+Definition at line 259 of file socket.cpp.
 .PP
 References fd.
 .PP
 .nf
-257 {
-258         return this->fd;
-259 }
+260 {
+261         return this->fd;
+262 }
 .fi
 .PP
 .SS "\fBstd::string\fP InspSocket::GetIP ()"
 .PP
 Returns the IP address associated with this connection, or an empty string if no IP address exists. 
 .PP
-Definition at line 150 of file socket.cpp.
+Definition at line 153 of file socket.cpp.
 .PP
 References IP.
 .PP
 .nf
-151 {
-152         return this->IP;
-153 }
+154 {
+155         return this->IP;
+156 }
 .fi
 .PP
 .SS "\fBInspSocketState\fP InspSocket::GetState ()"
 .PP
 Returns the current socket state. 
 .PP
-Definition at line 251 of file socket.cpp.
+Definition at line 254 of file socket.cpp.
 .PP
 References state.
 .PP
 .nf
-252 {
-253         return this->state;
-254 }
+255 {
+256         return this->state;
+257 }
 .fi
 .PP
 .SS "void InspSocket::OnClose ()\fC [virtual]\fP"
@@ -377,12 +381,12 @@ Whenever close() is called, \fBOnClose()\fP will be called first.
 .PP
 Please note that this means OnClose will be called alongside \fBOnError()\fP, \fBOnTimeout()\fP, and \fBClose()\fP, and also when cancelling a listening socket by calling the destructor indirectly.
 .PP
-Definition at line 267 of file socket.cpp.
+Definition at line 270 of file socket.cpp.
 .PP
 Referenced by Close().
 .PP
 .nf
-267 { return; }
+270 { return; }
 .fi
 .PP
 .SS "bool InspSocket::OnConnected ()\fC [virtual]\fP"
@@ -396,12 +400,12 @@ false to abort the connection, true to continue
 .PP
 
 .PP
-Definition at line 261 of file socket.cpp.
+Definition at line 264 of file socket.cpp.
 .PP
 Referenced by Poll().
 .PP
 .nf
-261 { return true; }
+264 { return true; }
 .fi
 .PP
 .SS "bool InspSocket::OnDataReady ()\fC [virtual]\fP"
@@ -417,22 +421,22 @@ false to close the socket
 .PP
 
 .PP
-Definition at line 265 of file socket.cpp.
+Definition at line 268 of file socket.cpp.
 .PP
 Referenced by Poll().
 .PP
 .nf
-265 { return true; }
+268 { return true; }
 .fi
 .PP
 .SS "int InspSocket::OnDisconnect ()\fC [virtual]\fP"
 .PP
 When an established connection is terminated, the OnDisconnect method is triggered. 
 .PP
-Definition at line 263 of file socket.cpp.
+Definition at line 266 of file socket.cpp.
 .PP
 .nf
-263 { return 0; }
+266 { return 0; }
 .fi
 .PP
 .SS "void InspSocket::OnError (\fBInspSocketError\fP e)\fC [virtual]\fP"
@@ -448,12 +452,12 @@ A closed socket in itself is not an error, however errors also generate close ev
 .PP
 
 .PP
-Definition at line 262 of file socket.cpp.
+Definition at line 265 of file socket.cpp.
 .PP
 Referenced by InspSocket(), and Timeout().
 .PP
 .nf
-262 { return; }
+265 { return; }
 .fi
 .PP
 .SS "int InspSocket::OnIncomingConnection (int newfd, char * ip)\fC [virtual]\fP"
@@ -466,12 +470,12 @@ MySocket* newsocket = new MySocket(newfd,ip);
 .PP
 Once you have done this, you can then associate the new socket with the core using \fBServer::AddSocket()\fP.
 .PP
-Definition at line 264 of file socket.cpp.
+Definition at line 267 of file socket.cpp.
 .PP
 Referenced by Poll().
 .PP
 .nf
-264 { return 0; }
+267 { return 0; }
 .fi
 .PP
 .SS "void InspSocket::OnTimeout ()\fC [virtual]\fP"
@@ -480,12 +484,12 @@ When an outbound connection fails, and the attempt times out, you will receive t
 .PP
 The mthod will trigger once maxtime secons are reached (as given in the constructor) just before the socket's descriptor is closed.
 .PP
-Definition at line 266 of file socket.cpp.
+Definition at line 269 of file socket.cpp.
 .PP
 Referenced by Timeout().
 .PP
 .nf
-266 { return; }
+269 { return; }
 .fi
 .PP
 .SS "bool InspSocket::Poll ()"
@@ -494,64 +498,64 @@ Only the core should call this function.
 .PP
 When called, it is assumed the socket is ready to read data, and the method call routes the event to the various methods of InspSocket for you to handle. This can also cause the socket's state to change.
 .PP
-Definition at line 214 of file socket.cpp.
+Definition at line 217 of file socket.cpp.
 .PP
 References SocketEngine::AddFd(), client, SocketEngine::DelFd(), I_CONNECTED, I_CONNECTING, I_LISTENING, length, OnConnected(), OnDataReady(), OnIncomingConnection(), SetState(), and X_ESTAB_MODULE.
 .PP
 .nf
-215 {
-216         int incoming = -1;
-217         
-218         switch (this->state)
-219         {
-220                 case I_CONNECTING:
-221                         this->SetState(I_CONNECTED);
-222                         /* Our socket was in write-state, so delete it and re-add it
-223                          * in read-state.
-224                          */
-225                         SE->DelFd(this->fd);
-226                         SE->AddFd(this->fd,true,X_ESTAB_MODULE);
-227                         return this->OnConnected();
-228                 break;
-229                 case I_LISTENING:
-230                         length = sizeof (client);
-231                         incoming = accept (this->fd, (sockaddr*)&client,&length);
-232                         this->OnIncomingConnection(incoming,inet_ntoa(client.sin_addr));
-233                         return true;
-234                 break;
-235                 case I_CONNECTED:
-236                         return this->OnDataReady();
+218 {
+219         int incoming = -1;
+220         
+221         switch (this->state)
+222         {
+223                 case I_CONNECTING:
+224                         this->SetState(I_CONNECTED);
+225                         /* Our socket was in write-state, so delete it and re-add it
+226                          * in read-state.
+227                          */
+228                         SE->DelFd(this->fd);
+229                         SE->AddFd(this->fd,true,X_ESTAB_MODULE);
+230                         return this->OnConnected();
+231                 break;
+232                 case I_LISTENING:
+233                         length = sizeof (client);
+234                         incoming = accept (this->fd, (sockaddr*)&client,&length);
+235                         this->OnIncomingConnection(incoming,inet_ntoa(client.sin_addr));
+236                         return true;
 237                 break;
-238                 default:
-239                 break;
-240         }
-241 
-242         return true;
-243 }
+238                 case I_CONNECTED:
+239                         return this->OnDataReady();
+240                 break;
+241                 default:
+242                 break;
+243         }
+244 
+245         return true;
+246 }
 .fi
 .PP
 .SS "char * InspSocket::Read ()\fC [virtual]\fP"
 .PP
 Reads all pending bytes from the socket into a char* array which can be up to 16 kilobytes in length. 
 .PP
-Definition at line 155 of file socket.cpp.
+Definition at line 158 of file socket.cpp.
 .PP
 References DEBUG, and ibuf.
 .PP
 .nf
-156 {
-157         int n = recv(this->fd,this->ibuf,sizeof(this->ibuf),0);
-158         if (n > 0)
-159         {
-160                 ibuf[n] = 0;
-161                 return ibuf;
-162         }
-163         else
-164         {
-165                 log(DEBUG,'EOF or error on socket');
-166                 return NULL;
-167         }
-168 }
+159 {
+160         int n = recv(this->fd,this->ibuf,sizeof(this->ibuf),0);
+161         if (n > 0)
+162         {
+163                 ibuf[n] = 0;
+164                 return ibuf;
+165         }
+166         else
+167         {
+168                 log(DEBUG,'EOF or error on socket');
+169                 return NULL;
+170         }
+171 }
 .fi
 .PP
 .SS "void InspSocket::SetState (\fBInspSocketState\fP s)"
@@ -560,17 +564,17 @@ Changes the socket's state.
 .PP
 The core uses this to change socket states, and you should not call it directly.
 .PP
-Definition at line 245 of file socket.cpp.
+Definition at line 248 of file socket.cpp.
 .PP
 References DEBUG, and state.
 .PP
 Referenced by Poll().
 .PP
 .nf
-246 {
-247         log(DEBUG,'Socket state change');
-248         this->state = s;
-249 }
+249 {
+250         log(DEBUG,'Socket state change');
+251         this->state = s;
+252 }
 .fi
 .PP
 .SS "bool InspSocket::Timeout (time_t current)"
@@ -584,26 +588,26 @@ true if timed out, false if not timed out
 .PP
 
 .PP
-Definition at line 197 of file socket.cpp.
+Definition at line 200 of file socket.cpp.
 .PP
 References I_CONNECTING, I_ERR_TIMEOUT, I_ERROR, OnError(), OnTimeout(), state, timeout, and timeout_end.
 .PP
 .nf
-198 {
-199         if ((this->state == I_CONNECTING) && (current > timeout_end))
-200         {
-201                 // for non-listening sockets, the timeout can occur
-202                 // which causes termination of the connection after
-203                 // the given number of seconds without a successful
-204                 // connection.
-205                 this->OnTimeout();
-206                 this->OnError(I_ERR_TIMEOUT);
-207                 timeout = true;
-208                 this->state = I_ERROR;
-209                 return true;
-210         }
-211         return false;
-212 }
+201 {
+202         if ((this->state == I_CONNECTING) && (current > timeout_end))
+203         {
+204                 // for non-listening sockets, the timeout can occur
+205                 // which causes termination of the connection after
+206                 // the given number of seconds without a successful
+207                 // connection.
+208                 this->OnTimeout();
+209                 this->OnError(I_ERR_TIMEOUT);
+210                 timeout = true;
+211                 this->state = I_ERROR;
+212                 return true;
+213         }
+214         return false;
+215 }
 .fi
 .PP
 .SS "int InspSocket::Write (\fBstd::string\fP data)\fC [virtual]\fP"
@@ -619,30 +623,30 @@ No carriage returns or linefeeds are appended to the string.
 .PP
 
 .PP
-Definition at line 174 of file socket.cpp.
+Definition at line 177 of file socket.cpp.
 .PP
 .nf
-175 {
-176         char* d = (char*)data.c_str();
-177         unsigned int written = 0;
-178         int n = 0;
-179         int s = data.length();
-180         while ((written < data.length()) && (n >= 0))
-181         {
-182                 n = send(this->fd,d,s,0);
-183                 if (n > 0)
-184                 {
-185                         // If we didnt write everything, advance
-186                         // the pointers so that when we retry
-187                         // the next time around the loop, we try
-188                         // to write what we failed to write before.
-189                         written += n;
-190                         s -= n;
-191                         d += n;
-192                 }
-193         }
-194         return written;
-195 }
+178 {
+179         char* d = (char*)data.c_str();
+180         unsigned int written = 0;
+181         int n = 0;
+182         int s = data.length();
+183         while ((written < data.length()) && (n >= 0))
+184         {
+185                 n = send(this->fd,d,s,0);
+186                 if (n > 0)
+187                 {
+188                         // If we didnt write everything, advance
+189                         // the pointers so that when we retry
+190                         // the next time around the loop, we try
+191                         // to write what we failed to write before.
+192                         written += n;
+193                         s -= n;
+194                         d += n;
+195                 }
+196         }
+197         return written;
+198 }
 .fi
 .PP
 .SH "Member Data Documentation"