00001 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ 00002 /* 00003 * Copyright (c) 2006 Georgia Tech Research Corporation 00004 * 2007 INRIA 00005 * 00006 * This program is free software; you can redistribute it and/or modify 00007 * it under the terms of the GNU General Public License version 2 as 00008 * published by the Free Software Foundation; 00009 * 00010 * This program is distributed in the hope that it will be useful, 00011 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00013 * GNU General Public License for more details. 00014 * 00015 * You should have received a copy of the GNU General Public License 00016 * along with this program; if not, write to the Free Software 00017 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00018 * 00019 * Authors: George F. Riley<riley@ece.gatech.edu> 00020 * Mathieu Lacage <mathieu.lacage@sophia.inria.fr> 00021 */ 00022 00023 #ifndef __SOCKET_H__ 00024 #define __SOCKET_H__ 00025 00026 #include "ns3/callback.h" 00027 #include "ns3/ptr.h" 00028 #include "ns3/tag.h" 00029 #include "ns3/object.h" 00030 #include "address.h" 00031 #include <stdint.h> 00032 00033 namespace ns3 { 00034 00035 00036 class Node; 00037 class Packet; 00038 00039 /** 00040 * \ingroup node 00041 * \defgroup socket Socket 00042 */ 00043 00044 /** 00045 * \brief A low-level Socket API based loosely on the BSD Socket API. 00046 * \ingroup socket 00047 * 00048 * A few things to keep in mind about this type of socket: 00049 * - it uses ns-3 API constructs such as class ns3::Address instead of 00050 * C-style structs 00051 * - in contrast to the original BSD socket API, this API is asynchronous: 00052 * it does not contain blocking calls. Sending and receiving operations 00053 * must make use of the callbacks provided. 00054 * - It also uses class ns3::Packet as a fancy byte buffer, allowing 00055 * data to be passed across the API using an ns-3 Packet instead of 00056 * a raw data pointer. 00057 * - Not all of the full POSIX sockets API is supported 00058 * 00059 * Other than that, it tries to stick to the BSD API to make it 00060 * easier for those who know the BSD API to use this API. 00061 * More details are provided in the ns-3 tutorial. 00062 */ 00063 class Socket : public Object 00064 { 00065 public: 00066 00067 Socket (void); 00068 virtual ~Socket (void); 00069 00070 enum SocketErrno { 00071 ERROR_NOTERROR, 00072 ERROR_ISCONN, 00073 ERROR_NOTCONN, 00074 ERROR_MSGSIZE, 00075 ERROR_AGAIN, 00076 ERROR_SHUTDOWN, 00077 ERROR_OPNOTSUPP, 00078 ERROR_AFNOSUPPORT, 00079 ERROR_INVAL, 00080 ERROR_BADF, 00081 ERROR_NOROUTETOHOST, 00082 SOCKET_ERRNO_LAST 00083 }; 00084 00085 /** 00086 * This method wraps the creation of sockets that is performed 00087 * by a socket factory on a given node based on a TypeId. 00088 * 00089 * \return A smart pointer to a newly created socket. 00090 * 00091 * \param node The node on which to create the socket 00092 * \param tid The TypeId of the socket to create 00093 */ 00094 static Ptr<Socket> CreateSocket (Ptr<Node> node, TypeId tid); 00095 /** 00096 * \return the errno associated to the last call which failed in this 00097 * socket. Each socket's errno is initialized to zero 00098 * when the socket is created. 00099 */ 00100 virtual enum Socket::SocketErrno GetErrno (void) const = 0; 00101 /** 00102 * \returns the node this socket is associated with. 00103 */ 00104 virtual Ptr<Node> GetNode (void) const = 0; 00105 /** 00106 * \param connectionSucceeded this callback is invoked when the 00107 * connection request initiated by the user is successfully 00108 * completed. The callback is passed back a pointer to 00109 * the same socket object. 00110 * \param connectionFailed this callback is invoked when the 00111 * connection request initiated by the user is unsuccessfully 00112 * completed. The callback is passed back a pointer to the 00113 * same socket object. 00114 */ 00115 void SetConnectCallback (Callback<void, Ptr<Socket> > connectionSucceeded, 00116 Callback<void, Ptr<Socket> > connectionFailed); 00117 /** 00118 * \brief Accept connection requests from remote hosts 00119 * \param connectionRequest Callback for connection request from peer. 00120 * This user callback is passed a pointer to this socket, the 00121 * ip address and the port number of the connection originator. 00122 * This callback must return true to accept the incoming connection, 00123 * false otherwise. If the connection is accepted, the 00124 * "newConnectionCreated" callback will be invoked later to 00125 * give access to the user to the socket created to match 00126 * this new connection. If the user does not explicitly 00127 * specify this callback, all incoming connections will be refused. 00128 * \param newConnectionCreated Callback for new connection: when a new 00129 * is accepted, it is created and the corresponding socket is passed 00130 * back to the user through this callback. This user callback is 00131 * passed a pointer to the new socket, and the ip address and 00132 * port number of the connection originator. 00133 */ 00134 void SetAcceptCallback (Callback<bool, Ptr<Socket>, 00135 const Address &> connectionRequest, 00136 Callback<void, Ptr<Socket>, 00137 const Address&> newConnectionCreated); 00138 /** 00139 * \brief Notify application when a packet has been sent from transport 00140 * protocol (non-standard socket call) 00141 * \param dataSent Callback for the event that data is sent from the 00142 * underlying transport protocol. This callback is passed a 00143 * pointer to the socket, and the number of bytes sent. 00144 */ 00145 void SetDataSentCallback (Callback<void, Ptr<Socket>, 00146 uint32_t> dataSent); 00147 /** 00148 * \brief Notify application when space in transmit buffer is added 00149 * 00150 * This callback is intended to notify a 00151 * socket that would have been blocked in a blocking socket model 00152 * that space is available in the transmit buffer and that it 00153 * can call Send() again. 00154 * 00155 * \param sendCb Callback for the event that the socket transmit buffer 00156 * fill level has decreased. This callback is passed a pointer to 00157 * the socket, and the number of bytes available for writing 00158 * into the buffer (an absolute value). If there is no transmit 00159 * buffer limit, a maximum-sized integer is always returned. 00160 */ 00161 void SetSendCallback (Callback<void, Ptr<Socket>, uint32_t> sendCb); 00162 /** 00163 * \brief Notify application when new data is available to be read. 00164 * 00165 * This callback is intended to notify a socket that would 00166 * have been blocked in a blocking socket model that data 00167 * is available to be read. 00168 */ 00169 void SetRecvCallback (Callback<void, Ptr<Socket> >); 00170 /** 00171 * \param address the address to try to allocate 00172 * \returns 0 on success, -1 on failure. 00173 * 00174 * Allocate a local endpoint for this socket. 00175 */ 00176 virtual int Bind (const Address &address) = 0; 00177 00178 /** 00179 * Allocate a local endpoint for this socket. 00180 * 00181 * \returns 0 on success, -1 on failure. 00182 */ 00183 virtual int Bind () = 0; 00184 00185 /** 00186 * \brief Close a socket. 00187 * 00188 * After the Close call, the socket is no longer valid, and cannot 00189 * safely be used for subsequent operations. 00190 */ 00191 virtual int Close (void) = 0; 00192 00193 /** 00194 * \returns zero on success, -1 on failure. 00195 * 00196 * Do not allow any further Send calls. This method is typically 00197 * implemented for Tcp sockets by a half close. 00198 */ 00199 virtual int ShutdownSend (void) = 0; 00200 00201 /** 00202 * \returns zero on success, -1 on failure. 00203 * 00204 * Do not allow any further Recv calls. This method is typically 00205 * implemented for Tcp sockets by a half close. 00206 */ 00207 virtual int ShutdownRecv (void) = 0; 00208 00209 /** 00210 * \brief Initiate a connection to a remote host 00211 * \param address Address of remote. 00212 */ 00213 virtual int Connect (const Address &address) = 0; 00214 00215 /** 00216 * \brief Listen for incoming connections. 00217 * \returns 0 on success, -1 on error (in which case errno is set). 00218 */ 00219 virtual int Listen (void) = 0; 00220 00221 /** 00222 * \brief Returns the number of bytes which can be sent in a single call 00223 * to Send. 00224 * 00225 * For datagram sockets, this returns the number of bytes that 00226 * can be passed atomically through the underlying protocol. 00227 * 00228 * For stream sockets, this returns the available space in bytes 00229 * left in the transmit buffer. 00230 */ 00231 virtual uint32_t GetTxAvailable (void) const = 0; 00232 00233 /** 00234 * \brief Send data (or dummy data) to the remote host 00235 * 00236 * This function matches closely in semantics to the send() function 00237 * call in the standard C library (libc): 00238 * ssize_t send (int s, const void *msg, size_t len, int flags); 00239 * except that the send I/O is asynchronous. This is the 00240 * primary Send method at this low-level API and must be implemented 00241 * by subclasses. 00242 * 00243 * In a typical blocking sockets model, this call would block upon 00244 * lack of space to hold the message to be sent. In ns-3 at this 00245 * API, the call returns immediately in such a case, but the callback 00246 * registered with SetSendCallback() is invoked when the socket 00247 * has space (when it conceptually unblocks); this is an asynchronous 00248 * I/O model for send(). 00249 * 00250 * This variant of Send() uses class ns3::Packet to encapsulate 00251 * data, rather than providing a raw pointer and length field. 00252 * This allows an ns-3 application to attach tags if desired (such 00253 * as a flow ID) and may allow the simulator to avoid some data 00254 * copies. Despite the appearance of sending Packets on a stream 00255 * socket, just think of it as a fancy byte buffer with streaming 00256 * semantics. 00257 * 00258 * If either the message buffer within the Packet is too long to pass 00259 * atomically through the underlying protocol (for datagram sockets), 00260 * or the message buffer cannot entirely fit in the transmit buffer 00261 * (for stream sockets), -1 is returned and SocketErrno is set 00262 * to ERROR_MSGSIZE. If the packet does not fit, the caller can 00263 * split the Packet (based on information obtained from 00264 * GetTxAvailable) and reattempt to send the data. 00265 * 00266 * The flags argument is formed by or'ing one or more of the values: 00267 * MSG_OOB process out-of-band data 00268 * MSG_DONTROUTE bypass routing, use direct interface 00269 * These flags are _unsupported_ as of ns-3.1. 00270 * 00271 * \param p ns3::Packet to send 00272 * \param flags Socket control flags 00273 * \returns the number of bytes accepted for transmission if no error 00274 * occurs, and -1 otherwise. 00275 * 00276 * \see SetSendCallback 00277 */ 00278 virtual int Send (Ptr<Packet> p, uint32_t flags) = 0; 00279 00280 /** 00281 * \brief Send data to a specified peer. 00282 * 00283 * This method has similar semantics to Send () but subclasses may 00284 * want to provide checks on socket state, so the implementation is 00285 * pushed to subclasses. 00286 * 00287 * \param p packet to send 00288 * \param flags Socket control flags 00289 * \param toAddress IP Address of remote host 00290 * \returns -1 in case of error or the number of bytes copied in the 00291 * internal buffer and accepted for transmission. 00292 */ 00293 virtual int SendTo (Ptr<Packet> p, uint32_t flags, 00294 const Address &toAddress) = 0; 00295 00296 /** 00297 * Return number of bytes which can be returned from one or 00298 * multiple calls to Recv. 00299 * Must be possible to call this method from the Recv callback. 00300 */ 00301 virtual uint32_t GetRxAvailable (void) const = 0; 00302 00303 /** 00304 * \brief Read data from the socket 00305 * 00306 * This function matches closely in semantics to the recv() function 00307 * call in the standard C library (libc): 00308 * ssize_t recv (int s, void *buf, size_t len, int flags); 00309 * except that the receive I/O is asynchronous. This is the 00310 * primary Recv method at this low-level API and must be implemented 00311 * by subclasses. 00312 * 00313 * This method is normally used only on a connected socket. 00314 * In a typical blocking sockets model, this call would block until 00315 * at least one byte is returned or the connection closes. 00316 * In ns-3 at this API, the call returns immediately in such a case 00317 * and returns 0 if nothing is available to be read. 00318 * However, an application can set a callback, ns3::SetRecvCallback, 00319 * to be notified of data being available to be read 00320 * (when it conceptually unblocks); this is an asynchronous 00321 * I/O model for recv(). 00322 * 00323 * This variant of Recv() uses class ns3::Packet to encapsulate 00324 * data, rather than providing a raw pointer and length field. 00325 * This allows an ns-3 application to attach tags if desired (such 00326 * as a flow ID) and may allow the simulator to avoid some data 00327 * copies. Despite the appearance of receiving Packets on a stream 00328 * socket, just think of it as a fancy byte buffer with streaming 00329 * semantics. 00330 * 00331 * The semantics depend on the type of socket. For a datagram socket, 00332 * each Recv() returns the data from at most one Send(), and order 00333 * is not necessarily preserved. For a stream socket, the bytes 00334 * are delivered in order, and on-the-wire packet boundaries are 00335 * not preserved. 00336 * 00337 * The flags argument is formed by or'ing one or more of the values: 00338 * MSG_OOB process out-of-band data 00339 * MSG_PEEK peek at incoming message 00340 * None of these flags are supported for now. 00341 * 00342 * Some variants of Recv() are supported as additional API, 00343 * including RecvFrom(), overloaded Recv() without arguments, 00344 * and variants that use raw character buffers. 00345 * 00346 * \param maxSize reader will accept packet up to maxSize 00347 * \param flags Socket control flags 00348 * \returns Ptr<Packet> of the next in-sequence packet. Returns 00349 * 0 if the socket cannot return a next in-sequence packet conforming 00350 * to the maxSize and flags. 00351 * 00352 * \see SetRecvCallback 00353 */ 00354 virtual Ptr<Packet> Recv (uint32_t maxSize, uint32_t flags) = 0; 00355 00356 /** 00357 * \brief Read a single packet from the socket and retrieve the sender 00358 * address. 00359 * 00360 * Calls Recv(maxSize, flags) with maxSize 00361 * implicitly set to maximum sized integer, and flags set to zero. 00362 * 00363 * This method has similar semantics to Recv () but subclasses may 00364 * want to provide checks on socket state, so the implementation is 00365 * pushed to subclasses. 00366 * 00367 * \param maxSize reader will accept packet up to maxSize 00368 * \param flags Socket control flags 00369 * \param fromAddress output parameter that will return the 00370 * address of the sender of the received packet, if any. Remains 00371 * untouched if no packet is received. 00372 * \returns Ptr<Packet> of the next in-sequence packet. Returns 00373 * 0 if the socket cannot return a next in-sequence packet. 00374 */ 00375 virtual Ptr<Packet> RecvFrom (uint32_t maxSize, uint32_t flags, 00376 Address &fromAddress) = 0; 00377 00378 ///////////////////////////////////////////////////////////////////// 00379 // The remainder of these public methods are overloaded methods // 00380 // or variants of Send() and Recv(), and they are non-virtual // 00381 ///////////////////////////////////////////////////////////////////// 00382 00383 /** 00384 * \brief Send data (or dummy data) to the remote host 00385 * 00386 * Overloaded version of Send(..., flags) with flags set to zero. 00387 * 00388 * \param p ns3::Packet to send 00389 * \returns the number of bytes accepted for transmission if no error 00390 * occurs, and -1 otherwise. 00391 */ 00392 int Send (Ptr<Packet> p); 00393 00394 /** 00395 * \brief Send data (or dummy data) to the remote host 00396 * 00397 * This method is provided so as to have an API which is closer in 00398 * appearance to that of real network or BSD sockets. 00399 * 00400 * \param buf A pointer to a raw byte buffer of some data to send. If 00401 * this buffer is 0, we send dummy data whose size is specified by the 00402 * second parameter 00403 * \param size the number of bytes to copy from the buffer 00404 * \param flags Socket control flags 00405 */ 00406 int Send (const uint8_t* buf, uint32_t size, uint32_t flags); 00407 00408 00409 /** 00410 * \brief Send data to a specified peer. 00411 * 00412 * This method is provided so as to have an API which is closer in 00413 * appearance to that of real network or BSD sockets. 00414 * 00415 * \param buf A pointer to a raw byte buffer of some data to send. 00416 * If this is 0, we send dummy data whose size is specified by the 00417 * third parameter 00418 * \param size the number of bytes to copy from the buffer 00419 * \param flags Socket control flags 00420 * \param address IP Address of remote host 00421 * \returns -1 in case of error or the number of bytes copied in the 00422 * internal buffer and accepted for transmission. 00423 * 00424 */ 00425 int SendTo (const uint8_t* buf, uint32_t size, uint32_t flags, 00426 const Address &address); 00427 00428 /** 00429 * \brief Read a single packet from the socket 00430 * 00431 * Overloaded version of Recv(maxSize, flags) with maxSize 00432 * implicitly set to maximum sized integer, and flags set to zero. 00433 * 00434 * \returns Ptr<Packet> of the next in-sequence packet. Returns 00435 * 0 if the socket cannot return a next in-sequence packet. 00436 */ 00437 Ptr<Packet> Recv (void); 00438 00439 /** 00440 * \brief Recv data (or dummy data) from the remote host 00441 * 00442 * This method is provided so as to have an API which is closer in 00443 * appearance to that of real network or BSD sockets. 00444 * 00445 * If the underlying packet was carring null (fake) data, this buffer 00446 * will be zeroed up to the length specified by the return value. 00447 * 00448 * \param buf A pointer to a raw byte buffer to write the data to. 00449 * \param size Number of bytes (at most) to copy to buf 00450 * \param flags any flags to pass to the socket 00451 * \returns number of bytes copied into buf 00452 */ 00453 int Recv (uint8_t* buf, uint32_t size, uint32_t flags); 00454 00455 /** 00456 * \brief Read a single packet from the socket and retrieve the sender 00457 * address. 00458 * 00459 * Calls RecvFrom (maxSize, flags, fromAddress) with maxSize 00460 * implicitly set to maximum sized integer, and flags set to zero. 00461 * 00462 * \param fromAddress output parameter that will return the 00463 * address of the sender of the received packet, if any. Remains 00464 * untouched if no packet is received. 00465 * \returns Ptr<Packet> of the next in-sequence packet. Returns 00466 * 0 if the socket cannot return a next in-sequence packet. 00467 */ 00468 Ptr<Packet> RecvFrom (Address &fromAddress); 00469 00470 /** 00471 * \brief Read a single packet from the socket and retrieve the sender 00472 * address. 00473 * 00474 * This method is provided so as to have an API which is closer in 00475 * appearance to that of real network or BSD sockets. 00476 * 00477 * \param buf A pointer to a raw byte buffer to write the data to. 00478 * If the underlying packet was carring null (fake) data, this buffer 00479 * will be zeroed up to the length specified by the return value. 00480 * \param size Number of bytes (at most) to copy to buf 00481 * \param flags any flags to pass to the socket 00482 * \param fromAddress output parameter that will return the 00483 * address of the sender of the received packet, if any. Remains 00484 * untouched if no packet is received. 00485 * \returns number of bytes copied into buf 00486 */ 00487 int RecvFrom (uint8_t* buf, uint32_t size, uint32_t flags, 00488 Address &fromAddress); 00489 /** 00490 * \returns the address name this socket is associated with. 00491 */ 00492 virtual int GetSockName (Address &address) const = 0; 00493 00494 protected: 00495 void NotifyConnectionSucceeded (void); 00496 void NotifyConnectionFailed (void); 00497 bool NotifyConnectionRequest (const Address &from); 00498 void NotifyNewConnectionCreated (Ptr<Socket> socket, const Address &from); 00499 void NotifyDataSent (uint32_t size); 00500 void NotifySend (uint32_t spaceAvailable); 00501 void NotifyDataRecv (void); 00502 private: 00503 Callback<void, Ptr<Socket> > m_connectionSucceeded; 00504 Callback<void, Ptr<Socket> > m_connectionFailed; 00505 Callback<bool, Ptr<Socket>, const Address &> m_connectionRequest; 00506 Callback<void, Ptr<Socket>, const Address&> m_newConnectionCreated; 00507 Callback<void, Ptr<Socket>, uint32_t> m_dataSent; 00508 Callback<void, Ptr<Socket>, uint32_t > m_sendCb; 00509 Callback<void, Ptr<Socket> > m_receivedData; 00510 00511 }; 00512 00513 /** 00514 * \brief This class implements a tag that carries an address 00515 * of a packet across the socket interface. 00516 */ 00517 class SocketAddressTag : public Tag 00518 { 00519 public: 00520 SocketAddressTag (); 00521 void SetAddress (Address addr); 00522 Address GetAddress (void) const; 00523 00524 static TypeId GetTypeId (void); 00525 virtual TypeId GetInstanceTypeId (void) const; 00526 virtual uint32_t GetSerializedSize (void) const; 00527 virtual void Serialize (TagBuffer i) const; 00528 virtual void Deserialize (TagBuffer i); 00529 virtual void Print (std::ostream &os) const; 00530 00531 private: 00532 Address m_address; 00533 }; 00534 00535 /** 00536 * \brief This class implements a tag that carries the socket-specific 00537 * TTL of a packet to the IP layer 00538 */ 00539 class SocketIpTtlTag : public Tag 00540 { 00541 public: 00542 SocketIpTtlTag (); 00543 void SetTtl (uint8_t ttl); 00544 uint8_t GetTtl (void) const; 00545 00546 static TypeId GetTypeId (void); 00547 virtual TypeId GetInstanceTypeId (void) const; 00548 virtual uint32_t GetSerializedSize (void) const; 00549 virtual void Serialize (TagBuffer i) const; 00550 virtual void Deserialize (TagBuffer i); 00551 virtual void Print (std::ostream &os) const; 00552 00553 private: 00554 uint8_t m_ttl; 00555 }; 00556 00557 00558 /** 00559 * \brief indicated whether packets should be sent out with 00560 * the DF flag set. 00561 */ 00562 class SocketSetDontFragmentTag : public Tag 00563 { 00564 public: 00565 SocketSetDontFragmentTag (); 00566 void Enable (void); 00567 void Disable (void); 00568 bool IsEnabled (void) const; 00569 00570 static TypeId GetTypeId (void); 00571 virtual TypeId GetInstanceTypeId (void) const; 00572 virtual uint32_t GetSerializedSize (void) const; 00573 virtual void Serialize (TagBuffer i) const; 00574 virtual void Deserialize (TagBuffer i); 00575 virtual void Print (std::ostream &os) const; 00576 private: 00577 bool m_dontFragment; 00578 }; 00579 00580 } //namespace ns3 00581 00582 #endif /* SOCKET_H */ 00583 00584