From 4d6d3859d208d5576e7149de9a0a5576b7cf5153 Mon Sep 17 00:00:00 2001 From: brain Date: Mon, 12 Dec 2005 18:31:52 +0000 Subject: Added extra documentation for InspSocket (at last) git-svn-id: http://svn.inspircd.org/repository/trunk/inspircd@2356 e03df62e-2008-0410-955e-edbf42e46eb7 --- docs/module-doc/classInspSocket.html | 414 +++++++++++++++++++++++------------ 1 file changed, 276 insertions(+), 138 deletions(-) (limited to 'docs/module-doc/classInspSocket.html') diff --git a/docs/module-doc/classInspSocket.html b/docs/module-doc/classInspSocket.html index b4c7e7fba..e8b83e847 100644 --- a/docs/module-doc/classInspSocket.html +++ b/docs/module-doc/classInspSocket.html @@ -5,7 +5,10 @@
Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members
-

InspSocket Class Reference

#include <socket.h> +

InspSocket Class Reference

InspSocket is an extendable socket class which modules can use for TCP socket support. +More... +

+#include <socket.h>

Collaboration diagram for InspSocket:

Collaboration graph
[legend]
List of all members. @@ -13,78 +16,113 @@ Collaboration diagram for InspSocket:


Public Member Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + + + + +
 InspSocket ()
 The default constructor does nothing and should not be used.
 InspSocket (int newfd, char *ip)
 This constructor is used to associate an existing connecting with an InspSocket class.
 InspSocket (std::string host, int port, bool listening, unsigned long maxtime)
 This constructor is used to create a new socket, either listening for connections, or an outbound connection to another host.
virtual bool OnConnected ()
 This method is called when an outbound connection on your socket is completed.
virtual void OnError (InspSocketError e)
 This method is called when an error occurs.
virtual int OnDisconnect ()
 When an established connection is terminated, the OnDisconnect method is triggered.
virtual bool OnDataReady ()
 When there is data waiting to be read on a socket, the OnDataReady() method is called.
virtual void OnTimeout ()
 When an outbound connection fails, and the attempt times out, you will receive this event.
virtual void OnClose ()
 Whenever close() is called, OnClose() will be called first.
virtual char * Read ()
 Reads all pending bytes from the socket into a char* array which can be up to 16 kilobytes in length.
std::string GetIP ()
 Returns the IP address associated with this connection, or an empty string if no IP address exists.
bool Timeout (time_t current)
 This function checks if the socket has timed out yet, given the current time in the parameter.
virtual int Write (std::string data)
 Writes a std::string to the socket.
virtual int OnIncomingConnection (int newfd, char *ip)
 If your socket is a listening socket, when a new connection comes in on the socket this method will be called.
void SetState (InspSocketState s)
 Changes the socket's state.
InspSocketState GetState ()
 Returns the current socket state.
bool Poll ()
 Only the core should call this function.
int GetFd ()
 This method returns the socket's file descriptor as assigned by the operating system, or -1 if no descriptor has been assigned.
virtual void Close ()
 This method causes the socket to close, and may also be triggered by other methods such as OnTimeout and OnError.
virtual ~InspSocket ()
 The destructor may implicitly call OnClose(), and will close() and shutdown() the file descriptor used for this socket.

Private Attributes

int fd
 The file descriptor of this socket.
std::string host
 The hostname connected to.
int port
 The port connected to, or the port this socket is listening on.
InspSocketState state
 The state for this socket, either listening, connecting, connected or error.
sockaddr_in addr
 The host being connected to, in sockaddr form.
in_addr addy
 The host being connected to, in in_addr form.
time_t timeout_end
 When this time is reached, the socket times out if it is in the CONNECTING state.
bool timeout
pollfd polls
 This value is true if the socket has timed out.
char ibuf [16384]
 Socket input buffer, used by read().
std::string IP
 The IP address being connected to stored in string form for easy retrieval by accessors.
sockaddr_in client
 Client sockaddr structure used by accept().
sockaddr_in server
 Server sockaddr structure used by accept().
socklen_t length
 Used by accept() to indicate the sizes of the sockaddr_in structures.

Detailed Description

- +InspSocket is an extendable socket class which modules can use for TCP socket support. +

+It is fully integrated into InspIRCds socket loop and attaches its sockets to the core's instance of the SocketEngine class, meaning that any sockets you create have the same power and abilities as a socket created by the core itself. To use InspSocket, you must inherit a class from it, and use the InspSocket constructors to establish connections and bindings.

-Definition at line 30 of file socket.h.

Constructor & Destructor Documentation

+Definition at line 47 of file socket.h.

Constructor & Destructor Documentation

@@ -109,11 +147,13 @@ Definition at line 30 of f @@ -361,13 +415,15 @@ References Close().

+This method causes the socket to close, and may also be triggered by other methods such as OnTimeout and OnError. +

Definition at line 139 of file socket.cpp.

-References fd, and OnClose(). +References fd, and OnClose().

-Referenced by InspSocket(), and ~InspSocket().

00140 {
+Referenced by InspSocket(), and ~InspSocket().
00140 {
 00141         if (this->fd != -1)
 00142         {
 00143                 this->OnClose();
@@ -405,13 +461,15 @@ Referenced by InspSocket()
 
 

+This method returns the socket's file descriptor as assigned by the operating system, or -1 if no descriptor has been assigned. 
+

 
 

-Definition at line 252 of file socket.cpp.
+Definition at line 256 of file socket.cpp.
 

-References fd.
00253 {
-00254         return this->fd;
-00255 }
+References fd.
00257 {
+00258         return this->fd;
+00259 }
 

 

     
@@ -441,11 +499,13 @@ References fd.
150 of file socket.cpp.
 

-References IP.
00151 {
+References IP.
00151 {
 00152         return this->IP;
 00153 }
 

@@ -477,13 +537,15 @@ References IP.
247 of file socket.cpp.
+Definition at line 251 of file socket.cpp.
 

-References state.
00248 {
-00249         return this->state;
-00250 }
+References state.
00252 {
+00253         return this->state;
+00254 }
 

 

     
@@ -513,11 +575,13 @@ References state.

 
 

-
+Whenever close() is called, OnClose() will be called first. 
 

-Definition at line 263 of file socket.cpp.
+Please note that this means OnClose will be called alongside OnError(), OnTimeout(), and Close(), and also when cancelling a listening socket by calling the destructor indirectly.
 

-Referenced by Close().
00263 { return; }
+Definition at line 267 of file socket.cpp.
+

+Referenced by Close().
00267 { return; }
 

 

     
@@ -547,11 +611,14 @@ Referenced by Close().
 
 

+This method is called when an outbound connection on your socket is completed. 
+

+
Returns:
false to abort the connection, true to continue

 
 

-Definition at line 257 of file socket.cpp.
+Definition at line 261 of file socket.cpp.
 

-Referenced by Poll().
00257 { return true; }
+Referenced by Poll().
00261 { return true; }
 

 

     
@@ -581,11 +648,14 @@ Referenced by Poll().
 
 

+When there is data waiting to be read on a socket, the OnDataReady() method is called. 
+

+Within this method, you *MUST* call the Read() method to read any pending data. At its lowest level, this event is signalled by the core via the socket engine. If you return false from this function, the core removes your socket from its list and erases it from the socket engine, then calls InspSocket::Close() and deletes it. 
Returns:
false to close the socket

 
 

-Definition at line 261 of file socket.cpp.
+Definition at line 265 of file socket.cpp.
 

-Referenced by Poll().
00261 { return true; }
+Referenced by Poll().
00265 { return true; }
 

 

     
@@ -615,9 +685,11 @@ Referenced by Poll().
 
 

+When an established connection is terminated, the OnDisconnect method is triggered. 
+

 
 

-Definition at line 259 of file socket.cpp.
00259 { return 0; }
+Definition at line 263 of file socket.cpp.
00263 { return 0; }
 

 

     
@@ -648,11 +720,18 @@ Definition at line 259 o
@@ -692,11 +771,15 @@ Referenced by InspSocket()

- +If your socket is a listening socket, when a new connection comes in on the socket this method will be called.

-Definition at line 260 of file socket.cpp. +Given the new file descriptor in the parameters, and the IP, it is recommended you copy them to a new instance of your socket class, e.g.:

+MySocket* newsocket = new MySocket(newfd,ip);

+Once you have done this, you can then associate the new socket with the core using Server::AddSocket().

-Referenced by Poll().

00260 { return 0; }
+Definition at line 264 of file socket.cpp.
+

+Referenced by Poll().
00264 { return 0; }
 

 

     
@@ -726,11 +809,13 @@ Referenced by Poll().
 
 

-
+When an outbound connection fails, and the attempt times out, you will receive this event. 
 

-Definition at line 262 of file socket.cpp.
+The mthod will trigger once maxtime secons are reached (as given in the constructor) just before the socket's descriptor is closed.
+

+Definition at line 266 of file socket.cpp.
 

-Referenced by Poll().
00262 { return; }
+Referenced by Timeout().
00266 { return; }
 

 

     
@@ -760,52 +845,41 @@ Referenced by Poll().
 
 

-
-

-Definition at line 197 of file socket.cpp.
-

-References SocketEngine::AddFd(), client, SocketEngine::DelFd(), I_CONNECTED, I_CONNECTING, I_ERR_TIMEOUT, I_ERROR, I_LISTENING, length, OnConnected(), OnDataReady(), OnError(), OnIncomingConnection(), OnTimeout(), SetState(), state, timeout, timeout_end, and X_ESTAB_MODULE.
00198 {
-00199         if ((time(NULL) > timeout_end) && (this->state == I_CONNECTING))
-00200         {
-00201                 // for non-listening sockets, the timeout can occur
-00202                 // which causes termination of the connection after
-00203                 // the given number of seconds without a successful
-00204                 // connection.
-00205                 this->OnTimeout();
-00206                 this->OnError(I_ERR_TIMEOUT);
-00207                 timeout = true;
-00208                 this->state = I_ERROR;
-00209                 return false;
-00210         }
-00211 
-00212         int incoming = -1;
-00213         
-00214         switch (this->state)
-00215         {
-00216                 case I_CONNECTING:
-00217                         this->SetState(I_CONNECTED);
-00218                         /* Our socket was in write-state, so delete it and re-add it
-00219                          * in read-state.
-00220                          */
-00221                         SE->DelFd(this->fd);
-00222                         SE->AddFd(this->fd,true,X_ESTAB_MODULE);
-00223                         return this->OnConnected();
-00224                 break;
-00225                 case I_LISTENING:
-00226                         length = sizeof (client);
-00227                         incoming = accept (this->fd, (sockaddr*)&client,&length);
-00228                         this->OnIncomingConnection(incoming,inet_ntoa(client.sin_addr));
-00229                         return true;
-00230                 break;
-00231                 case I_CONNECTED:
-00232                         return this->OnDataReady();
-00233                 break;
-00234                 default:
-00235                 break;
-00236         }
-00237 
-00238         return true;
-00239 }
+Only the core should call this function. 
+

+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.
+

+Definition at line 214 of file socket.cpp.
+

+References SocketEngine::AddFd(), client, SocketEngine::DelFd(), I_CONNECTED, I_CONNECTING, I_LISTENING, length, OnConnected(), OnDataReady(), OnIncomingConnection(), SetState(), and X_ESTAB_MODULE.
00215 {
+00216         int incoming = -1;
+00217         
+00218         switch (this->state)
+00219         {
+00220                 case I_CONNECTING:
+00221                         this->SetState(I_CONNECTED);
+00222                         /* Our socket was in write-state, so delete it and re-add it
+00223                          * in read-state.
+00224                          */
+00225                         SE->DelFd(this->fd);
+00226                         SE->AddFd(this->fd,true,X_ESTAB_MODULE);
+00227                         return this->OnConnected();
+00228                 break;
+00229                 case I_LISTENING:
+00230                         length = sizeof (client);
+00231                         incoming = accept (this->fd, (sockaddr*)&client,&length);
+00232                         this->OnIncomingConnection(incoming,inet_ntoa(client.sin_addr));
+00233                         return true;
+00234                 break;
+00235                 case I_CONNECTED:
+00236                         return this->OnDataReady();
+00237                 break;
+00238                 default:
+00239                 break;
+00240         }
+00241 
+00242         return true;
+00243 }
 

 

     
@@ -835,11 +909,13 @@ References SocketEngin
+ +

+The default constructor does nothing and should not be used. +

Definition at line 49 of file socket.cpp.

-References I_DISCONNECTED, and state.

00050 {
+References I_DISCONNECTED, and state.
00050 {
 00051         this->state = I_DISCONNECTED;
 00052 }
 

@@ -155,11 +195,13 @@ References I

- +This constructor is used to associate an existing connecting with an InspSocket class. +

+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.

Definition at line 54 of file socket.cpp.

-References SocketEngine::AddFd(), fd, I_CONNECTED, IP, state, and X_ESTAB_MODULE.

00055 {
+References SocketEngine::AddFd(), fd, I_CONNECTED, IP, state, and X_ESTAB_MODULE.
00055 {
 00056         this->fd = newfd;
 00057         this->state = I_CONNECTED;
 00058         this->IP = ip;
@@ -216,11 +258,21 @@ References SocketEngin

+This constructor is used to create a new socket, either listening for connections, or an outbound connection to another host. +

+

Parameters:
+ + + + + +
host The hostname to connect to, or bind to
port The port number to connect to, or bind to
listening true to listen on the given host:port pair, or false to connect to them
maxtime Number of seconds to wait, if connecting, before the connection times out and an OnTimeout() event is generated
+

Definition at line 62 of file socket.cpp.

-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.

00063 {
+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.
00063 {
 00064         if (listening) {
 00065                 if ((this->fd = OpenTCPSocket()) == ERROR)
 00066                 {
@@ -324,13 +376,15 @@ References SocketEngin

+The destructor may implicitly call OnClose(), and will close() and shutdown() the file descriptor used for this socket. +

-Definition at line 265 of file socket.cpp. +Definition at line 269 of file socket.cpp.

-References Close().

00266 {
-00267         this->Close();
-00268 }
+References Close().
00270 {
+00271         this->Close();
+00272 }

+This method is called when an error occurs. +

+A closed socket in itself is not an error, however errors also generate close events.

Parameters:
+ + +
e The error type which occured
+

-Definition at line 258 of file socket.cpp. +Definition at line 262 of file socket.cpp.

-Referenced by InspSocket(), and Poll().

00258 { return; }
+Referenced by InspSocket(), and Timeout().
00262 { return; }

+Reads all pending bytes from the socket into a char* array which can be up to 16 kilobytes in length. +

Definition at line 155 of file socket.cpp.

-References DEBUG, and ibuf.

00156 {
+References DEBUG, and ibuf.
00156 {
 00157         int n = recv(this->fd,this->ibuf,sizeof(this->ibuf),0);
 00158         if (n > 0)
 00159         {
@@ -882,16 +958,70 @@ References DEBUG, and 
 
 

+Changes the socket's state. 
+

+The core uses this to change socket states, and you should not call it directly.
+

+Definition at line 245 of file socket.cpp.
+

+References DEBUG, and state.
+

+Referenced by Poll().
00246 {
+00247         log(DEBUG,"Socket state change");
+00248         this->state = s;
+00249 }
+

+

+
+

+ + + + +
+ + + + + + + + + +
bool InspSocket::Timeout ( time_t  current  ) 
+
+ + + + @@ -922,6 +1052,13 @@ Referenced by Poll().

+Writes a std::string to the socket. +

+No carriage returns or linefeeds are appended to the string.

Parameters:
+
+   +

-Definition at line 241 of file socket.cpp. +This function checks if the socket has timed out yet, given the current time in the parameter.

-References DEBUG, and state. +

Returns:
true if timed out, false if not timed out
+ +

+Definition at line 197 of file socket.cpp.

-Referenced by Poll().

00242 {
-00243         log(DEBUG,"Socket state change");
-00244         this->state = s;
-00245 }
+References I_CONNECTING, I_ERR_TIMEOUT, I_ERROR, OnError(), OnTimeout(), state, timeout, and timeout_end.
00198 {
+00199         if ((this->state == I_CONNECTING) && (current > timeout_end))
+00200         {
+00201                 // for non-listening sockets, the timeout can occur
+00202                 // which causes termination of the connection after
+00203                 // the given number of seconds without a successful
+00204                 // connection.
+00205                 this->OnTimeout();
+00206                 this->OnError(I_ERR_TIMEOUT);
+00207                 timeout = true;
+00208                 this->state = I_ERROR;
+00209                 return true;
+00210         }
+00211         return false;
+00212 }
+ +
data The data to send
+

Definition at line 174 of file socket.cpp.

00175 {
@@ -971,9 +1108,11 @@ Definition at line 174 o
     
 
 

+The host being connected to, in sockaddr form. 
+

 
 

-Definition at line 37 of file socket.h.
+Definition at line 78 of file socket.h.
 

 Referenced by InspSocket().    
   
@@ -998,9 +1137,11 @@ Referenced by InspSocket()
 
 

+The host being connected to, in in_addr form. 
+

 
 

-Definition at line 38 of file socket.h.
+Definition at line 84 of file socket.h.
 

 Referenced by InspSocket().    
   
@@ -1025,11 +1166,13 @@ Referenced by InspSocket()
 
 

+Client sockaddr structure used by accept(). 
+

 
 

-Definition at line 44 of file socket.h.
+Definition at line 119 of file socket.h.
 

-Referenced by Poll().    
+Referenced by Poll().    
   
 
 

@@ -1052,11 +1195,13 @@ Referenced by Poll().
     
 
 

+The file descriptor of this socket. 
+

 
 

-Definition at line 33 of file socket.h.
+Definition at line 54 of file socket.h.
 

-Referenced by Close(), GetFd(), and InspSocket().    
+Referenced by Close(), GetFd(), and InspSocket().    
   
 
 

@@ -1079,9 +1224,11 @@ Referenced by Close(), <
     
 
 

+The hostname connected to. 
+

 
 

-Definition at line 34 of file socket.h.    
+Definition at line 59 of file socket.h.    
   
 
 

@@ -1104,9 +1251,11 @@ Definition at line 34 of f
     
 
 

-
+Socket input buffer, used by read(). 
 

-Definition at line 42 of file socket.h.
+The class which extends InspSocket is expected to implement an extendable buffer which can grow much larger than 16k, this buffer is just designed to be temporary storage. space.
+

+Definition at line 106 of file socket.h.
 

 Referenced by Read().    
   
@@ -1131,9 +1280,11 @@ Referenced by Read().
     
 
 

+The IP address being connected to stored in string form for easy retrieval by accessors. 
+

 
 

-Definition at line 43 of file socket.h.
+Definition at line 113 of file socket.h.
 

 Referenced by GetIP(), and InspSocket().    
   
@@ -1158,36 +1309,13 @@ Referenced by GetIP(), a
     
 
 

-
-

-Definition at line 46 of file socket.h.
+Used by accept() to indicate the sizes of the sockaddr_in structures. 
 

-Referenced by Poll().    
-  
-
-

-
-  
-    
-  
-

-      
-        
-          
-        
-      
pollfd InspSocket::polls [private]          

-    

-
-  
-    
-    
+Referenced by Poll().    

-       
-    
 
 

-
+Definition at line 131 of file socket.h.
 

-Definition at line 41 of file socket.h.    

   

 

 

@@ -1210,9 +1338,11 @@ Definition at line 41 of f
     
 
 

+The port connected to, or the port this socket is listening on. 
+

 
 

-Definition at line 35 of file socket.h.    
+Definition at line 65 of file socket.h.    
   
 
 

@@ -1235,9 +1365,11 @@ Definition at line 35 of f
     
 
 

+Server sockaddr structure used by accept(). 
+

 
 

-Definition at line 45 of file socket.h.    
+Definition at line 125 of file socket.h.    
   
 
 

@@ -1260,11 +1392,13 @@ Definition at line 45 of f
     
 
 

+The state for this socket, either listening, connecting, connected or error. 
+

 
 

-Definition at line 36 of file socket.h.
+Definition at line 72 of file socket.h.
 

-Referenced by GetState(), InspSocket(), Poll(), and SetState().    
+Referenced by GetState(), InspSocket(), SetState(), and Timeout().    
   
 
 

@@ -1287,11 +1421,13 @@ Referenced by GetState()
     
 
 

+This value is true if the socket has timed out. 
+

 
 

-Definition at line 40 of file socket.h.
+Definition at line 97 of file socket.h.
 

-Referenced by InspSocket(), and Poll().    
+Referenced by InspSocket(), and Timeout().    
   
 
 

@@ -1314,16 +1450,18 @@ Referenced by InspSocket()
 
 

+When this time is reached, the socket times out if it is in the CONNECTING state. 
+

 
 

-Definition at line 39 of file socket.h.
+Definition at line 91 of file socket.h.
 

-Referenced by InspSocket(), and Poll().    
+Referenced by InspSocket(), and Timeout().    
   
 
 
The documentation for this class was generated from the following files:
-
Generated on Mon Dec 12 13:31:12 2005 for InspIRCd by 
+
Generated on Mon Dec 12 18:31:02 2005 for InspIRCd by 
 
 doxygen 1.4.4-20050815 

 
-- 
cgit v1.3.1-10-gc9f91