.TH "InspSocket" 3 "12 Dec 2005" "Version 1.0Betareleases" "InspIRCd" \" -*- nroff -*- .ad l .nh .SH NAME InspSocket \- InspSocket is an extendable socket class which modules can use for TCP socket support. .PP .SH SYNOPSIS .br .PP \fC#include \fP .PP .SS "Public Member Functions" .in +1c .ti -1c .RI "\fBInspSocket\fP ()" .br .RI "\fIThe default constructor does nothing and should not be used. \fP" .ti -1c .RI "\fBInspSocket\fP (int newfd, char *ip)" .br .RI "\fIThis constructor is used to associate an existing connecting with an InspSocket class. \fP" .ti -1c .RI "\fBInspSocket\fP (\fBstd::string\fP \fBhost\fP, int \fBport\fP, bool listening, unsigned long maxtime)" .br .RI "\fIThis constructor is used to create a new socket, either listening for connections, or an outbound connection to another host. \fP" .ti -1c .RI "virtual bool \fBOnConnected\fP ()" .br .RI "\fIThis method is called when an outbound connection on your socket is completed. \fP" .ti -1c .RI "virtual void \fBOnError\fP (\fBInspSocketError\fP e)" .br .RI "\fIThis method is called when an error occurs. \fP" .ti -1c .RI "virtual int \fBOnDisconnect\fP ()" .br .RI "\fIWhen an established connection is terminated, the OnDisconnect method is triggered. \fP" .ti -1c .RI "virtual bool \fBOnDataReady\fP ()" .br .RI "\fIWhen there is data waiting to be read on a socket, the \fBOnDataReady()\fP method is called. \fP" .ti -1c .RI "virtual void \fBOnTimeout\fP ()" .br .RI "\fIWhen an outbound connection fails, and the attempt times out, you will receive this event. \fP" .ti -1c .RI "virtual void \fBOnClose\fP ()" .br .RI "\fIWhenever close() is called, \fBOnClose()\fP will be called first. \fP" .ti -1c .RI "virtual char * \fBRead\fP ()" .br .RI "\fIReads all pending bytes from the socket into a char* array which can be up to 16 kilobytes in length. \fP" .ti -1c .RI "\fBstd::string\fP \fBGetIP\fP ()" .br .RI "\fIReturns the IP address associated with this connection, or an empty string if no IP address exists. \fP" .ti -1c .RI "bool \fBTimeout\fP (time_t current)" .br .RI "\fIThis function checks if the socket has timed out yet, given the current time in the parameter. \fP" .ti -1c .RI "virtual int \fBWrite\fP (\fBstd::string\fP data)" .br .RI "\fIWrites a \fBstd::string\fP to the socket. \fP" .ti -1c .RI "virtual int \fBOnIncomingConnection\fP (int newfd, char *ip)" .br .RI "\fIIf your socket is a listening socket, when a new connection comes in on the socket this method will be called. \fP" .ti -1c .RI "void \fBSetState\fP (\fBInspSocketState\fP s)" .br .RI "\fIChanges the socket's state. \fP" .ti -1c .RI "\fBInspSocketState\fP \fBGetState\fP ()" .br .RI "\fIReturns the current socket state. \fP" .ti -1c .RI "bool \fBPoll\fP ()" .br .RI "\fIOnly the core should call this function. \fP" .ti -1c .RI "int \fBGetFd\fP ()" .br .RI "\fIThis method returns the socket's file descriptor as assigned by the operating system, or -1 if no descriptor has been assigned. \fP" .ti -1c .RI "virtual void \fBClose\fP ()" .br .RI "\fIThis method causes the socket to close, and may also be triggered by other methods such as OnTimeout and OnError. \fP" .ti -1c .RI "virtual \fB~InspSocket\fP ()" .br .RI "\fIThe destructor may implicitly call \fBOnClose()\fP, and will close() and shutdown() the file descriptor used for this socket. \fP" .in -1c .SS "Private Attributes" .in +1c .ti -1c .RI "int \fBfd\fP" .br .RI "\fIThe file descriptor of this socket. \fP" .ti -1c .RI "\fBstd::string\fP \fBhost\fP" .br .RI "\fIThe hostname connected to. \fP" .ti -1c .RI "int \fBport\fP" .br .RI "\fIThe port connected to, or the port this socket is listening on. \fP" .ti -1c .RI "\fBInspSocketState\fP \fBstate\fP" .br .RI "\fIThe state for this socket, either listening, connecting, connected or error. \fP" .ti -1c .RI "sockaddr_in \fBaddr\fP" .br .RI "\fIThe host being connected to, in sockaddr form. \fP" .ti -1c .RI "in_addr \fBaddy\fP" .br .RI "\fIThe host being connected to, in in_addr form. \fP" .ti -1c .RI "time_t \fBtimeout_end\fP" .br .RI "\fIWhen this time is reached, the socket times out if it is in the CONNECTING state. \fP" .ti -1c .RI "bool \fBtimeout\fP" .br .RI "\fIThis value is true if the socket has timed out. \fP" .ti -1c .RI "char \fBibuf\fP [16384]" .br .RI "\fISocket input buffer, used by read(). \fP" .ti -1c .RI "\fBstd::string\fP \fBIP\fP" .br .RI "\fIThe IP address being connected to stored in string form for easy retrieval by accessors. \fP" .ti -1c .RI "sockaddr_in \fBclient\fP" .br .RI "\fIClient sockaddr structure used by accept(). \fP" .ti -1c .RI "sockaddr_in \fBserver\fP" .br .RI "\fI\fBServer\fP sockaddr structure used by accept(). \fP" .ti -1c .RI "socklen_t \fBlength\fP" .br .RI "\fIUsed by accept() to indicate the sizes of the sockaddr_in structures. \fP" .in -1c .SH "Detailed Description" .PP 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 \fBSocketEngine\fP 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. .PP Definition at line 47 of file socket.h. .SH "Constructor & Destructor Documentation" .PP .SS "InspSocket::InspSocket ()" .PP The default constructor does nothing and should not be used. .PP Definition at line 49 of file socket.cpp. .PP References I_DISCONNECTED, and state. .PP .nf 50 { 51 this->state = I_DISCONNECTED; 52 } .fi .PP .SS "InspSocket::InspSocket (int newfd, char * ip)" .PP This constructor is used to associate an existing connecting with an InspSocket class. .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. .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); 60 } .fi .PP .SS "InspSocket::InspSocket (\fBstd::string\fP host, int port, bool listening, unsigned long maxtime)" .PP This constructor is used to create a new socket, either listening for connections, or an outbound connection to another host. .PP \fBParameters:\fP .RS 4 \fIhost\fP The hostname to connect to, or bind to .br \fIport\fP The port number to connect to, or bind to .br \fIlistening\fP true to listen on the given host:port pair, or false to connect to them .br \fImaxtime\fP Number of seconds to wait, if connecting, before the connection times out and an \fBOnTimeout()\fP event is generated .RE .PP .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. .PP .nf 63 { 64 if (listening) { 65 if ((this->fd = OpenTCPSocket()) == ERROR) 66 { 67 this->fd = -1; 68 this->state = I_ERROR; 69 this->OnError(I_ERR_SOCKET); 70 log(DEBUG,'OpenTCPSocket() error'); 71 return; 72 } 73 else 74 { 75 if (BindSocket(this->fd,this->client,this->server,port,(char*)host.c_str()) == ERROR) 76 { 77 this->Close(); 78 this->fd = -1; 79 this->state = I_ERROR; 80 this->OnError(I_ERR_BIND); 81 log(DEBUG,'BindSocket() error %s',strerror(errno)); 82 return; 83 } 84 else 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 } .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. .PP References Close(). .PP .nf 270 { 271 this->Close(); 272 } .fi .PP .SH "Member Function Documentation" .PP .SS "void InspSocket::Close ()\fC [virtual]\fP" .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. .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 } .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. .PP References fd. .PP .nf 257 { 258 return this->fd; 259 } .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. .PP References IP. .PP .nf 151 { 152 return this->IP; 153 } .fi .PP .SS "\fBInspSocketState\fP InspSocket::GetState ()" .PP Returns the current socket state. .PP Definition at line 251 of file socket.cpp. .PP References state. .PP .nf 252 { 253 return this->state; 254 } .fi .PP .SS "void InspSocket::OnClose ()\fC [virtual]\fP" .PP 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. .PP Referenced by Close(). .PP .nf 267 { return; } .fi .PP .SS "bool InspSocket::OnConnected ()\fC [virtual]\fP" .PP This method is called when an outbound connection on your socket is completed. .PP \fBReturns:\fP .RS 4 false to abort the connection, true to continue .RE .PP .PP Definition at line 261 of file socket.cpp. .PP Referenced by Poll(). .PP .nf 261 { return true; } .fi .PP .SS "bool InspSocket::OnDataReady ()\fC [virtual]\fP" .PP When there is data waiting to be read on a socket, the \fBOnDataReady()\fP method is called. .PP Within this method, you *MUST* call the \fBRead()\fP 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 \fBInspSocket::Close()\fP and deletes it. .PP \fBReturns:\fP .RS 4 false to close the socket .RE .PP .PP Definition at line 265 of file socket.cpp. .PP Referenced by Poll(). .PP .nf 265 { 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. .PP .nf 263 { return 0; } .fi .PP .SS "void InspSocket::OnError (\fBInspSocketError\fP e)\fC [virtual]\fP" .PP This method is called when an error occurs. .PP A closed socket in itself is not an error, however errors also generate close events. .PP \fBParameters:\fP .RS 4 \fIe\fP The error type which occured .RE .PP .PP Definition at line 262 of file socket.cpp. .PP Referenced by InspSocket(), and Timeout(). .PP .nf 262 { return; } .fi .PP .SS "int InspSocket::OnIncomingConnection (int newfd, char * ip)\fC [virtual]\fP" .PP If your socket is a listening socket, when a new connection comes in on the socket this method will be called. .PP 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.: .PP 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. .PP Referenced by Poll(). .PP .nf 264 { return 0; } .fi .PP .SS "void InspSocket::OnTimeout ()\fC [virtual]\fP" .PP When an outbound connection fails, and the attempt times out, you will receive this event. .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. .PP Referenced by Timeout(). .PP .nf 266 { return; } .fi .PP .SS "bool InspSocket::Poll ()" .PP 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. .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(); 237 break; 238 default: 239 break; 240 } 241 242 return true; 243 } .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. .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 } .fi .PP .SS "void InspSocket::SetState (\fBInspSocketState\fP s)" .PP 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. .PP References DEBUG, and state. .PP Referenced by Poll(). .PP .nf 246 { 247 log(DEBUG,'Socket state change'); 248 this->state = s; 249 } .fi .PP .SS "bool InspSocket::Timeout (time_t current)" .PP This function checks if the socket has timed out yet, given the current time in the parameter. .PP \fBReturns:\fP .RS 4 true if timed out, false if not timed out .RE .PP .PP Definition at line 197 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 } .fi .PP .SS "int InspSocket::Write (\fBstd::string\fP data)\fC [virtual]\fP" .PP Writes a \fBstd::string\fP to the socket. .PP No carriage returns or linefeeds are appended to the string. .PP \fBParameters:\fP .RS 4 \fIdata\fP The data to send .RE .PP .PP Definition at line 174 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 } .fi .PP .SH "Member Data Documentation" .PP .SS "sockaddr_in \fBInspSocket::addr\fP\fC [private]\fP" .PP The host being connected to, in sockaddr form. .PP Definition at line 78 of file socket.h. .PP Referenced by InspSocket(). .SS "in_addr \fBInspSocket::addy\fP\fC [private]\fP" .PP The host being connected to, in in_addr form. .PP Definition at line 84 of file socket.h. .PP Referenced by InspSocket(). .SS "sockaddr_in \fBInspSocket::client\fP\fC [private]\fP" .PP Client sockaddr structure used by accept(). .PP Definition at line 119 of file socket.h. .PP Referenced by Poll(). .SS "int \fBInspSocket::fd\fP\fC [private]\fP" .PP The file descriptor of this socket. .PP Definition at line 54 of file socket.h. .PP Referenced by Close(), GetFd(), and InspSocket(). .SS "\fBstd::string\fP \fBInspSocket::host\fP\fC [private]\fP" .PP The hostname connected to. .PP Definition at line 59 of file socket.h. .SS "char \fBInspSocket::ibuf\fP[16384]\fC [private]\fP" .PP Socket input buffer, used by read(). .PP 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. .PP Definition at line 106 of file socket.h. .PP Referenced by Read(). .SS "\fBstd::string\fP \fBInspSocket::IP\fP\fC [private]\fP" .PP The IP address being connected to stored in string form for easy retrieval by accessors. .PP Definition at line 113 of file socket.h. .PP Referenced by GetIP(), and InspSocket(). .SS "socklen_t \fBInspSocket::length\fP\fC [private]\fP" .PP Used by accept() to indicate the sizes of the sockaddr_in structures. .PP Definition at line 131 of file socket.h. .PP Referenced by Poll(). .SS "int \fBInspSocket::port\fP\fC [private]\fP" .PP The port connected to, or the port this socket is listening on. .PP Definition at line 65 of file socket.h. .SS "sockaddr_in \fBInspSocket::server\fP\fC [private]\fP" .PP \fBServer\fP sockaddr structure used by accept(). .PP Definition at line 125 of file socket.h. .SS "\fBInspSocketState\fP \fBInspSocket::state\fP\fC [private]\fP" .PP The state for this socket, either listening, connecting, connected or error. .PP Definition at line 72 of file socket.h. .PP Referenced by GetState(), InspSocket(), SetState(), and Timeout(). .SS "bool \fBInspSocket::timeout\fP\fC [private]\fP" .PP This value is true if the socket has timed out. .PP Definition at line 97 of file socket.h. .PP Referenced by InspSocket(), and Timeout(). .SS "time_t \fBInspSocket::timeout_end\fP\fC [private]\fP" .PP When this time is reached, the socket times out if it is in the CONNECTING state. .PP Definition at line 91 of file socket.h. .PP Referenced by InspSocket(), and Timeout(). .SH "Author" .PP Generated automatically by Doxygen for InspIRCd from the source code.