1 //------------------------------------------------------------------------------ 2 // Copyright (c) 2001-2002, OpenBeOS 3 // 4 // Permission is hereby granted, free of charge, to any person obtaining a 5 // copy of this software and associated documentation files (the "Software"), 6 // to deal in the Software without restriction, including without limitation 7 // the rights to use, copy, modify, merge, publish, distribute, sublicense, 8 // and/or sell copies of the Software, and to permit persons to whom the 9 // Software is furnished to do so, subject to the following conditions: 10 // 11 // The above copyright notice and this permission notice shall be included in 12 // all copies or substantial portions of the Software. 13 // 14 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 15 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 16 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 17 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 18 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 19 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 20 // DEALINGS IN THE SOFTWARE. 21 //------------------------------------------------------------------------------ 22 23 #ifndef _NETENDPOINT_H 24 #define _NETENDPOINT_H 25 26 #include <BeBuild.h> 27 #include <SupportDefs.h> 28 #include <Archivable.h> 29 #include <sys/socket.h> 30 31 32 #include <NetAddress.h> 33 #include <NetBuffer.h> 34 35 /* 36 * BNetEndpoint 37 * 38 * BNetEndpoint is an object that implements a networking endpoint abstraction. 39 * Think of it as an object-oriented socket. BNetEndpoint provides 40 * various ways to send and receive data, establish network connections, bind 41 * to local addresses, and listen for and accept new connections. 42 * 43 */ 44 45 // Nettle forward declarations 46 class NLEndpoint; 47 class NLAddress; 48 class NLPacket; 49 50 51 52 class BNetEndpoint : public BArchivable 53 { 54 public: 55 56 BNetEndpoint(int proto = SOCK_STREAM); 57 virtual ~BNetEndpoint(); 58 59 /* 60 * It is important to call InitCheck() after creating an instance of this class. 61 */ 62 status_t InitCheck(); 63 64 BNetEndpoint &operator=(const BNetEndpoint &); 65 BNetEndpoint(const BNetEndpoint &); 66 67 /* 68 * When a BNetEndpoint is archived, it saves various state information 69 * which will allow reinstantiation later. For example, if a BNetEndpoint 70 * that is connected to a remote FTP server is archived, when the archive 71 * is later instantiated the connection to the FTP server will be reopened 72 * automatically. 73 */ 74 BNetEndpoint(BMessage *archive); 75 virtual status_t Archive(BMessage *into, bool deep = true) const; 76 static BArchivable *Instantiate(BMessage *archive); 77 78 79 /* 80 * BNetEndpoint::SetProtocol() 81 * 82 * allows the protocol type to be changed from stream 83 * to datagram and vice-versa. The current connection (if any) is closed and 84 * the BNetEndpoint's state is reset. 85 * 86 * Returns B_OK if successful, B_ERROR otherwise. 87 */ 88 89 status_t SetProtocol(int proto); 90 91 /* 92 * These functions allow various options to be set for data communications. 93 * The first allows any option to be set; the latter two turn nonblocking 94 * I/O on or off, and toggle reuseaddr respectively. The default is for 95 * *blocking* I/O and for reuseaddr to be OFF. 96 * 97 * Returns 0 if successful, -1 otherwise. 98 */ 99 int SetOption(int32 opt, int32 lev, const void *data, unsigned int datasize); 100 int SetNonBlocking(bool on = true); 101 int SetReuseAddr(bool on = true); 102 103 /* 104 * LocalAddr() returns a BNetAddress corresponding to the local address used by this 105 * BNetEndpoint. RemoteAddr() returns a BNetAddress corresponding to the address of 106 * the remote peer we are connected to, if using a connected stream protocol. 107 */ 108 const BNetAddress &LocalAddr(); 109 const BNetAddress &RemoteAddr(); 110 111 /* 112 * BNetEndpoint::Socket() returns the actual socket used for data communications. 113 */ 114 int Socket() const; 115 116 /* 117 * BNetEndpoint::Close() 118 * 119 * Close the current BNetEndpoint, terminating any existing connection (if any) 120 * and discarding unread data. 121 */ 122 123 virtual void Close(); 124 125 /* 126 * BNetEndpoint::Bind() 127 * 128 * Bind this BNetEndpoint to a local address. Calling bind() without specifying 129 * a BNetAddress or port number binds to a random local port. The actual port 130 * bound to can be determined by a subsequent call to BNetEndpoint::getAddr(). 131 * 132 * Returns B_OK if successful, B_ERROR otherwise. 133 */ 134 virtual status_t Bind(const BNetAddress &addr); 135 virtual status_t Bind(int port = 0); 136 137 /* 138 * BNetEndpoint::Connect() 139 * 140 * Connect this BNetEndpoint to a remote address. The first version takes 141 * a BNetAddress already set to the remote address as an argument; the other 142 * one internally constructs a BNetAddress from the passed-in hostname and port 143 * number. 144 * 145 * Returns B_OK if successful, B_ERROR otherwise. 146 */ 147 virtual status_t Connect(const BNetAddress &addr); 148 virtual status_t Connect(const char *addr, int port); 149 150 /* 151 * BNetEndpoint::Listen() 152 * 153 * Specify the number of pending incoming connection attemps to queue. 154 * This is the number of connection requests that will be allowed in between 155 * calls to BNetEndpoint::accept(). When this number is exceeded, new 156 * connection attempts are refused until BNetEndpoint::accept() is called. 157 * 158 * Returns B_OK if successful, B_ERROR otherwise. 159 */ 160 161 virtual status_t Listen(int backlog = 5); 162 163 /* 164 * BNetEndpoint::Accept() 165 * 166 * Accepts new connections to a bound stream protocol BNetEndpoint. 167 * Blocks for timeout milleseconds (defaults to forever) waiting for 168 * new connections. Returns a BNetEndpoint with the same characteristics 169 * as the one calling BNetEndpoint::Accept(), the new one representing the new 170 * connection. This returned BNetEndpoint is ready for communication and 171 * must be deleted at a later time using delete. 172 */ 173 174 virtual BNetEndpoint *Accept(int32 timeout = -1); 175 176 /* 177 * BNetEndpoint::Error() will return the integer error code (set by the OS) 178 * for the last send/recv error. Likewise, BNetEndpoint::ErrorStr() returns 179 * a string describing the error. 180 */ 181 int Error() const; 182 char *ErrorStr() const; 183 184 /* 185 * BNetEndpoint::Send() 186 * 187 * Send data to the remote end of the connection. If not connected, fails. 188 * If using a datagram protocol, fails unless BNetEndpoint::Connect() 189 * has been called, which caches the address we are sending to. The first 190 * version sends an arbitrary buffer of size size; the second sends the 191 * contents of a BNetBuffer. Both return the number of bytes actually 192 * sent, or -1 on failure. 193 */ 194 virtual int32 Send(const void *buf, size_t size, int flags = 0); 195 virtual int32 Send(BNetBuffer &pack, int flags = 0); 196 197 /* 198 * BNetEndpoint::SendTo() 199 * 200 * Send data to the address specified by the passed-in BNetAddress object. 201 * Fails if not using a datagram protocol. The first version sends 202 * an arbitrary buffer of size size; the second sends the contents of a 203 * BNetBuffer. Both return the number of bytes actually sent, 204 * and return -1 on failure. 205 */ 206 207 virtual int32 SendTo(const void *buf, size_t size, const BNetAddress &to, int flags = 0); 208 virtual int32 SendTo(BNetBuffer &pack, const BNetAddress &to, int flags = 0); 209 210 /* 211 * BNetEndpoint::SetTimeout() 212 * 213 * Sets an optional timeout (in microseconds) for calls to BNetEndpoint::Receive() 214 * and BNetEndpoint::ReceiveFrom(). Causes these calls to time out after the specified 215 * number of microseconds when in blocking mode. 216 */ 217 void SetTimeout(bigtime_t usec); 218 219 /* 220 * BNetEndpoint::Receive() 221 * 222 * Receive data pending on the BNetEndpoint's connection. If in the default 223 * blocking mode, blocks until data is available or a timeout (set by 224 * BNetEndpoint::SetTimeout). The first call receives into a preallocated buffer 225 * of the specified size; the second call receives (at most) size bytes into 226 * an BNetBuffer. The data is appended to the end of the BNetBuffer; this allows 227 * a BNetBuffer to be used in a loop to buffer incoming data read in chunks 228 * until a certain size is read. Both return the number of bytes actually 229 * received, and return -1 on error. 230 */ 231 virtual int32 Receive(void *buf, size_t size, int flags = 0); 232 virtual int32 Receive(BNetBuffer &pack, size_t size, int flags = 0); 233 234 /* 235 * BNetEndpoint::ReceiveFrom() 236 * 237 * Receive datagrams from an arbitrary source and fill in the passed-in BNetAddress 238 * with the address from whence the datagram came. As usual, both return the 239 * actual number of bytes read. In the BNetBuffer version, the data is appended 240 * to the end of the BNetBuffer; this allows a BNetBuffer to be used in a loop to 241 * buffer incoming data read in chunks until a certain amount is read. 242 */ 243 virtual int32 ReceiveFrom(void *buf, size_t size, BNetAddress &from, int flags = 0); 244 virtual int32 ReceiveFrom(BNetBuffer &pack, size_t size, BNetAddress &from, int flags = 0); 245 246 /* 247 * BNetEndpoint::IsDataPending() 248 * 249 * Returns true if there is data waiting to be received on this BNetEndpoint. 250 * Will block for usec_timeout microseconds if specified, waiting for data. 251 */ 252 virtual bool IsDataPending(bigtime_t usec_timeout = 0); 253 254 inline NLEndpoint *GetImpl() const; 255 256 protected: 257 status_t m_init; 258 259 private: 260 virtual void _ReservedBNetEndpointFBCCruft1(); 261 virtual void _ReservedBNetEndpointFBCCruft2(); 262 virtual void _ReservedBNetEndpointFBCCruft3(); 263 virtual void _ReservedBNetEndpointFBCCruft4(); 264 virtual void _ReservedBNetEndpointFBCCruft5(); 265 virtual void _ReservedBNetEndpointFBCCruft6(); 266 267 int32 __ReservedBNetEndpointFBCCruftData[9]; 268 BNetAddress m_peer; 269 BNetAddress m_addr; 270 BNetAddress m_conaddr; 271 }; 272 273 274 inline NLEndpoint *BNetEndpoint::GetImpl() const 275 { 276 return NULL; // No Nettle backward compatibility 277 } 278 279 #endif // _NETENDPOINT_H 280