/src/network/model/socket.h
C++ Header | 1234 lines | 240 code | 136 blank | 858 comment | 0 complexity | bd8420af99fc99b57b6ffa9e04890cc9 MD5 | raw file
1/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ 2/* 3 * Copyright (c) 2006 Georgia Tech Research Corporation 4 * 2007 INRIA 5 * 6 * This program is free software; you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License version 2 as 8 * published by the Free Software Foundation; 9 * 10 * This program is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU General Public License for more details. 14 * 15 * You should have received a copy of the GNU General Public License 16 * along with this program; if not, write to the Free Software 17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 18 * 19 * Authors: George F. Riley<riley@ece.gatech.edu> 20 * Mathieu Lacage <mathieu.lacage@sophia.inria.fr> 21 */ 22 23#ifndef NS3_SOCKET_H 24#define NS3_SOCKET_H 25 26#include "ns3/callback.h" 27#include "ns3/ptr.h" 28#include "ns3/tag.h" 29#include "ns3/object.h" 30#include "ns3/net-device.h" 31#include "address.h" 32#include <stdint.h> 33#include "ns3/inet-socket-address.h" 34#include "ns3/inet6-socket-address.h" 35 36namespace ns3 { 37 38 39class Node; 40class Packet; 41 42/** 43 * \ingroup network 44 * \defgroup socket Socket 45 */ 46 47/** 48 * \brief A low-level Socket API based loosely on the BSD Socket API. 49 * \ingroup socket 50 * 51 * A few things to keep in mind about this type of socket: 52 * - it uses ns-3 API constructs such as class ns3::Address instead of 53 * C-style structs 54 * - in contrast to the original BSD socket API, this API is asynchronous: 55 * it does not contain blocking calls. Sending and receiving operations 56 * must make use of the callbacks provided. 57 * - It also uses class ns3::Packet as a fancy byte buffer, allowing 58 * data to be passed across the API using an ns-3 Packet instead of 59 * a raw data pointer. 60 * - Not all of the full POSIX sockets API is supported 61 * 62 * Other than that, it tries to stick to the BSD API to make it 63 * easier for those who know the BSD API to use this API. 64 * More details are provided in the ns-3 tutorial. 65 */ 66class Socket : public Object 67{ 68public: 69 /** 70 * \brief Get the type ID. 71 * \return the object TypeId 72 */ 73 static TypeId GetTypeId (void); 74 75 Socket (void); 76 virtual ~Socket (void); 77 78 /** 79 * \enum SocketErrno 80 * \brief Enumeration of the possible errors returned by a socket. 81 */ 82 enum SocketErrno { 83 ERROR_NOTERROR, 84 ERROR_ISCONN, 85 ERROR_NOTCONN, 86 ERROR_MSGSIZE, 87 ERROR_AGAIN, 88 ERROR_SHUTDOWN, 89 ERROR_OPNOTSUPP, 90 ERROR_AFNOSUPPORT, 91 ERROR_INVAL, 92 ERROR_BADF, 93 ERROR_NOROUTETOHOST, 94 ERROR_NODEV, 95 ERROR_ADDRNOTAVAIL, 96 ERROR_ADDRINUSE, 97 SOCKET_ERRNO_LAST 98 }; 99 100 /** 101 * \enum SocketType 102 * \brief Enumeration of the possible socket types. 103 */ 104 enum SocketType { 105 NS3_SOCK_STREAM, 106 NS3_SOCK_SEQPACKET, 107 NS3_SOCK_DGRAM, 108 NS3_SOCK_RAW 109 }; 110 111 /** 112 * This method wraps the creation of sockets that is performed 113 * on a given node by a SocketFactory specified by TypeId. 114 * 115 * \return A smart pointer to a newly created socket. 116 * 117 * \param node The node on which to create the socket 118 * \param tid The TypeId of a SocketFactory class to use 119 */ 120 static Ptr<Socket> CreateSocket (Ptr<Node> node, TypeId tid); 121 /** 122 * \brief Get last error number. 123 * 124 * \return the errno associated to the last call which failed in this 125 * socket. Each socket's errno is initialized to zero 126 * when the socket is created. 127 */ 128 virtual enum Socket::SocketErrno GetErrno (void) const = 0; 129 /** 130 * \return the socket type, analogous to getsockopt (SO_TYPE) 131 */ 132 virtual enum Socket::SocketType GetSocketType (void) const = 0; 133 /** 134 * \brief Return the node this socket is associated with. 135 * \returns the node 136 */ 137 virtual Ptr<Node> GetNode (void) const = 0; 138 /** 139 * \brief Specify callbacks to allow the caller to determine if 140 * the connection succeeds of fails. 141 * \param connectionSucceeded this callback is invoked when the 142 * connection request initiated by the user is successfully 143 * completed. The callback is passed back a pointer to 144 * the same socket object. 145 * \param connectionFailed this callback is invoked when the 146 * connection request initiated by the user is unsuccessfully 147 * completed. The callback is passed back a pointer to the 148 * same socket object. 149 */ 150 void SetConnectCallback (Callback<void, Ptr<Socket> > connectionSucceeded, 151 Callback<void, Ptr<Socket> > connectionFailed); 152 /** 153 * \brief Detect socket recv() events such as graceful shutdown or error. 154 * 155 * For connection-oriented sockets, the first callback is used to signal 156 * that the remote side has gracefully shut down the connection, and the 157 * second callback denotes an error corresponding to cases in which 158 * a traditional recv() socket call might return -1 (error), such 159 * as a connection reset. For datagram sockets, these callbacks may 160 * never be invoked. 161 * 162 * \param normalClose this callback is invoked when the 163 * peer closes the connection gracefully 164 * \param errorClose this callback is invoked when the 165 * connection closes abnormally 166 */ 167 void SetCloseCallbacks (Callback<void, Ptr<Socket> > normalClose, 168 Callback<void, Ptr<Socket> > errorClose); 169 /** 170 * \brief Accept connection requests from remote hosts 171 * \param connectionRequest Callback for connection request from peer. 172 * This user callback is passed a pointer to this socket, the 173 * ip address and the port number of the connection originator. 174 * This callback must return true to accept the incoming connection, 175 * false otherwise. If the connection is accepted, the 176 * "newConnectionCreated" callback will be invoked later to 177 * give access to the user to the socket created to match 178 * this new connection. If the user does not explicitly 179 * specify this callback, all incoming connections will be refused. 180 * \param newConnectionCreated Callback for new connection: when a new 181 * is accepted, it is created and the corresponding socket is passed 182 * back to the user through this callback. This user callback is 183 * passed a pointer to the new socket, and the ip address and 184 * port number of the connection originator. 185 */ 186 void SetAcceptCallback (Callback<bool, Ptr<Socket>, 187 const Address &> connectionRequest, 188 Callback<void, Ptr<Socket>, 189 const Address&> newConnectionCreated); 190 /** 191 * \brief Notify application when a packet has been sent from transport 192 * protocol (non-standard socket call) 193 * \param dataSent Callback for the event that data is sent from the 194 * underlying transport protocol. This callback is passed a 195 * pointer to the socket, and the number of bytes sent. 196 */ 197 void SetDataSentCallback (Callback<void, Ptr<Socket>, 198 uint32_t> dataSent); 199 /** 200 * \brief Notify application when space in transmit buffer is added 201 * 202 * This callback is intended to notify a 203 * socket that would have been blocked in a blocking socket model 204 * that space is available in the transmit buffer and that it 205 * can call Send() again. 206 * 207 * \param sendCb Callback for the event that the socket transmit buffer 208 * fill level has decreased. This callback is passed a pointer to 209 * the socket, and the number of bytes available for writing 210 * into the buffer (an absolute value). If there is no transmit 211 * buffer limit, a maximum-sized integer is always returned. 212 */ 213 void SetSendCallback (Callback<void, Ptr<Socket>, uint32_t> sendCb); 214 /** 215 * \brief Notify application when new data is available to be read. 216 * 217 * This callback is intended to notify a socket that would 218 * have been blocked in a blocking socket model that data 219 * is available to be read. 220 */ 221 void SetRecvCallback (Callback<void, Ptr<Socket> >); 222 /** 223 * \brief Allocate a local endpoint for this socket. 224 * \param address the address to try to allocate 225 * \returns 0 on success, -1 on failure. 226 */ 227 virtual int Bind (const Address &address) = 0; 228 229 /** 230 * \brief Allocate a local IPv4 endpoint for this socket. 231 * 232 * \returns 0 on success, -1 on failure. 233 */ 234 virtual int Bind () = 0; 235 236 /** 237 * \brief Allocate a local IPv6 endpoint for this socket. 238 * 239 * \returns 0 on success, -1 on failure. 240 */ 241 virtual int Bind6 () = 0; 242 243 /** 244 * \brief Close a socket. 245 * \returns zero on success, -1 on failure. 246 * 247 * After the Close call, the socket is no longer valid, and cannot 248 * safely be used for subsequent operations. 249 */ 250 virtual int Close (void) = 0; 251 252 /** 253 * \returns zero on success, -1 on failure. 254 * 255 * Do not allow any further Send calls. This method is typically 256 * implemented for Tcp sockets by a half close. 257 */ 258 virtual int ShutdownSend (void) = 0; 259 260 /** 261 * \returns zero on success, -1 on failure. 262 * 263 * Do not allow any further Recv calls. This method is typically 264 * implemented for Tcp sockets by a half close. 265 */ 266 virtual int ShutdownRecv (void) = 0; 267 268 /** 269 * \brief Initiate a connection to a remote host 270 * \param address Address of remote. 271 * \returns 0 on success, -1 on error (in which case errno is set). 272 */ 273 virtual int Connect (const Address &address) = 0; 274 275 /** 276 * \brief Listen for incoming connections. 277 * \returns 0 on success, -1 on error (in which case errno is set). 278 */ 279 virtual int Listen (void) = 0; 280 281 /** 282 * \brief Returns the number of bytes which can be sent in a single call 283 * to Send. 284 * 285 * For datagram sockets, this returns the number of bytes that 286 * can be passed atomically through the underlying protocol. 287 * 288 * For stream sockets, this returns the available space in bytes 289 * left in the transmit buffer. 290 * 291 * \returns The number of bytes which can be sent in a single Send call. 292 */ 293 virtual uint32_t GetTxAvailable (void) const = 0; 294 295 /** 296 * \brief Send data (or dummy data) to the remote host 297 * 298 * This function matches closely in semantics to the send() function 299 * call in the standard C library (libc): 300 * ssize_t send (int s, const void *msg, size_t len, int flags); 301 * except that the send I/O is asynchronous. This is the 302 * primary Send method at this low-level API and must be implemented 303 * by subclasses. 304 * 305 * In a typical blocking sockets model, this call would block upon 306 * lack of space to hold the message to be sent. In ns-3 at this 307 * API, the call returns immediately in such a case, but the callback 308 * registered with SetSendCallback() is invoked when the socket 309 * has space (when it conceptually unblocks); this is an asynchronous 310 * I/O model for send(). 311 * 312 * This variant of Send() uses class ns3::Packet to encapsulate 313 * data, rather than providing a raw pointer and length field. 314 * This allows an ns-3 application to attach tags if desired (such 315 * as a flow ID) and may allow the simulator to avoid some data 316 * copies. Despite the appearance of sending Packets on a stream 317 * socket, just think of it as a fancy byte buffer with streaming 318 * semantics. 319 * 320 * If either the message buffer within the Packet is too long to pass 321 * atomically through the underlying protocol (for datagram sockets), 322 * or the message buffer cannot entirely fit in the transmit buffer 323 * (for stream sockets), -1 is returned and SocketErrno is set 324 * to ERROR_MSGSIZE. If the packet does not fit, the caller can 325 * split the Packet (based on information obtained from 326 * GetTxAvailable) and reattempt to send the data. 327 * 328 * The flags argument is formed by or'ing one or more of the values: 329 * MSG_OOB process out-of-band data 330 * MSG_DONTROUTE bypass routing, use direct interface 331 * These flags are _unsupported_ as of ns-3.1. 332 * 333 * \param p ns3::Packet to send 334 * \param flags Socket control flags 335 * \returns the number of bytes accepted for transmission if no error 336 * occurs, and -1 otherwise. 337 * 338 * \see SetSendCallback 339 */ 340 virtual int Send (Ptr<Packet> p, uint32_t flags) = 0; 341 342 /** 343 * \brief Send data to a specified peer. 344 * 345 * This method has similar semantics to Send () but subclasses may 346 * want to provide checks on socket state, so the implementation is 347 * pushed to subclasses. 348 * 349 * \param p packet to send 350 * \param flags Socket control flags 351 * \param toAddress IP Address of remote host 352 * \returns -1 in case of error or the number of bytes copied in the 353 * internal buffer and accepted for transmission. 354 */ 355 virtual int SendTo (Ptr<Packet> p, uint32_t flags, 356 const Address &toAddress) = 0; 357 358 /** 359 * Return number of bytes which can be returned from one or 360 * multiple calls to Recv. 361 * Must be possible to call this method from the Recv callback. 362 * 363 * \returns the number of bytes which can be returned from one or 364 * multiple Recv calls. 365 */ 366 virtual uint32_t GetRxAvailable (void) const = 0; 367 368 /** 369 * \brief Read data from the socket 370 * 371 * This function matches closely in semantics to the recv() function 372 * call in the standard C library (libc): 373 * ssize_t recv (int s, void *buf, size_t len, int flags); 374 * except that the receive I/O is asynchronous. This is the 375 * primary Recv method at this low-level API and must be implemented 376 * by subclasses. 377 * 378 * This method is normally used only on a connected socket. 379 * In a typical blocking sockets model, this call would block until 380 * at least one byte is returned or the connection closes. 381 * In ns-3 at this API, the call returns immediately in such a case 382 * and returns 0 if nothing is available to be read. 383 * However, an application can set a callback, ns3::SetRecvCallback, 384 * to be notified of data being available to be read 385 * (when it conceptually unblocks); this is an asynchronous 386 * I/O model for recv(). 387 * 388 * This variant of Recv() uses class ns3::Packet to encapsulate 389 * data, rather than providing a raw pointer and length field. 390 * This allows an ns-3 application to attach tags if desired (such 391 * as a flow ID) and may allow the simulator to avoid some data 392 * copies. Despite the appearance of receiving Packets on a stream 393 * socket, just think of it as a fancy byte buffer with streaming 394 * semantics. 395 * 396 * The semantics depend on the type of socket. For a datagram socket, 397 * each Recv() returns the data from at most one Send(), and order 398 * is not necessarily preserved. For a stream socket, the bytes 399 * are delivered in order, and on-the-wire packet boundaries are 400 * not preserved. 401 * 402 * The flags argument is formed by or'ing one or more of the values: 403 * MSG_OOB process out-of-band data 404 * MSG_PEEK peek at incoming message 405 * None of these flags are supported for now. 406 * 407 * Some variants of Recv() are supported as additional API, 408 * including RecvFrom(), overloaded Recv() without arguments, 409 * and variants that use raw character buffers. 410 * 411 * \param maxSize reader will accept packet up to maxSize 412 * \param flags Socket control flags 413 * \returns Ptr<Packet> of the next in-sequence packet. Returns 414 * 0 if the socket cannot return a next in-sequence packet conforming 415 * to the maxSize and flags. 416 * 417 * \see SetRecvCallback 418 */ 419 virtual Ptr<Packet> Recv (uint32_t maxSize, uint32_t flags) = 0; 420 421 /** 422 * \brief Read a single packet from the socket and retrieve the sender 423 * address. 424 * 425 * Calls Recv(maxSize, flags) with maxSize 426 * implicitly set to maximum sized integer, and flags set to zero. 427 * 428 * This method has similar semantics to Recv () but subclasses may 429 * want to provide checks on socket state, so the implementation is 430 * pushed to subclasses. 431 * 432 * \param maxSize reader will accept packet up to maxSize 433 * \param flags Socket control flags 434 * \param fromAddress output parameter that will return the 435 * address of the sender of the received packet, if any. Remains 436 * untouched if no packet is received. 437 * \returns Ptr<Packet> of the next in-sequence packet. Returns 438 * 0 if the socket cannot return a next in-sequence packet. 439 */ 440 virtual Ptr<Packet> RecvFrom (uint32_t maxSize, uint32_t flags, 441 Address &fromAddress) = 0; 442 443 ///////////////////////////////////////////////////////////////////// 444 // The remainder of these public methods are overloaded methods // 445 // or variants of Send() and Recv(), and they are non-virtual // 446 ///////////////////////////////////////////////////////////////////// 447 448 /** 449 * \brief Send data (or dummy data) to the remote host 450 * 451 * Overloaded version of Send(..., flags) with flags set to zero. 452 * 453 * \param p ns3::Packet to send 454 * \returns the number of bytes accepted for transmission if no error 455 * occurs, and -1 otherwise. 456 */ 457 int Send (Ptr<Packet> p); 458 459 /** 460 * \brief Send data (or dummy data) to the remote host 461 * 462 * This method is provided so as to have an API which is closer in 463 * appearance to that of real network or BSD sockets. 464 * 465 * \param buf A pointer to a raw byte buffer of some data to send. If 466 * this buffer is 0, we send dummy data whose size is specified by the 467 * second parameter 468 * \param size the number of bytes to copy from the buffer 469 * \param flags Socket control flags 470 * \returns the number of bytes accepted for transmission if no error 471 * occurs, and -1 otherwise. 472 */ 473 int Send (const uint8_t* buf, uint32_t size, uint32_t flags); 474 475 476 /** 477 * \brief Send data to a specified peer. 478 * 479 * This method is provided so as to have an API which is closer in 480 * appearance to that of real network or BSD sockets. 481 * 482 * \param buf A pointer to a raw byte buffer of some data to send. 483 * If this is 0, we send dummy data whose size is specified by the 484 * third parameter 485 * \param size the number of bytes to copy from the buffer 486 * \param flags Socket control flags 487 * \param address IP Address of remote host 488 * \returns -1 in case of error or the number of bytes copied in the 489 * internal buffer and accepted for transmission. 490 * 491 */ 492 int SendTo (const uint8_t* buf, uint32_t size, uint32_t flags, 493 const Address &address); 494 495 /** 496 * \brief Read a single packet from the socket 497 * 498 * Overloaded version of Recv(maxSize, flags) with maxSize 499 * implicitly set to maximum sized integer, and flags set to zero. 500 * 501 * \returns Ptr<Packet> of the next in-sequence packet. Returns 502 * 0 if the socket cannot return a next in-sequence packet. 503 */ 504 Ptr<Packet> Recv (void); 505 506 /** 507 * \brief Recv data (or dummy data) from the remote host 508 * 509 * This method is provided so as to have an API which is closer in 510 * appearance to that of real network or BSD sockets. 511 * 512 * If the underlying packet was carring null (fake) data, this buffer 513 * will be zeroed up to the length specified by the return value. 514 * 515 * \param buf A pointer to a raw byte buffer to write the data to. 516 * \param size Number of bytes (at most) to copy to buf 517 * \param flags any flags to pass to the socket 518 * \returns number of bytes copied into buf 519 */ 520 int Recv (uint8_t* buf, uint32_t size, uint32_t flags); 521 522 /** 523 * \brief Read a single packet from the socket and retrieve the sender 524 * address. 525 * 526 * Calls RecvFrom (maxSize, flags, fromAddress) with maxSize 527 * implicitly set to maximum sized integer, and flags set to zero. 528 * 529 * \param fromAddress output parameter that will return the 530 * address of the sender of the received packet, if any. Remains 531 * untouched if no packet is received. 532 * \returns Ptr<Packet> of the next in-sequence packet. Returns 533 * 0 if the socket cannot return a next in-sequence packet. 534 */ 535 Ptr<Packet> RecvFrom (Address &fromAddress); 536 537 /** 538 * \brief Read a single packet from the socket and retrieve the sender 539 * address. 540 * 541 * This method is provided so as to have an API which is closer in 542 * appearance to that of real network or BSD sockets. 543 * 544 * \param buf A pointer to a raw byte buffer to write the data to. 545 * If the underlying packet was carring null (fake) data, this buffer 546 * will be zeroed up to the length specified by the return value. 547 * \param size Number of bytes (at most) to copy to buf 548 * \param flags any flags to pass to the socket 549 * \param fromAddress output parameter that will return the 550 * address of the sender of the received packet, if any. Remains 551 * untouched if no packet is received. 552 * \returns number of bytes copied into buf 553 */ 554 int RecvFrom (uint8_t* buf, uint32_t size, uint32_t flags, 555 Address &fromAddress); 556 /** 557 * \brief Get socket address. 558 * \param address the address name this socket is associated with. 559 * \returns 0 if success, -1 otherwise 560 */ 561 virtual int GetSockName (Address &address) const = 0; 562 563 /** 564 * \brief Bind a socket to specific device. 565 * 566 * This method corresponds to using setsockopt() SO_BINDTODEVICE 567 * of real network or BSD sockets. If set on a socket, this option will 568 * force packets to leave the bound device regardless of the device that 569 * IP routing would naturally choose. In the receive direction, only 570 * packets received from the bound interface will be delivered. 571 * 572 * This option has no particular relationship to binding sockets to 573 * an address via Socket::Bind (). It is possible to bind sockets to a 574 * specific IP address on the bound interface by calling both 575 * Socket::Bind (address) and Socket::BindToNetDevice (device), but it 576 * is also possible to bind to mismatching device and address, even if 577 * the socket can not receive any packets as a result. 578 * 579 * \param netdevice Pointer to Netdevice of desired interface 580 * \returns nothing 581 */ 582 virtual void BindToNetDevice (Ptr<NetDevice> netdevice); 583 584 /** 585 * \brief Returns socket's bound netdevice, if any. 586 * 587 * This method corresponds to using getsockopt() SO_BINDTODEVICE 588 * of real network or BSD sockets. 589 * 590 * 591 * \returns Pointer to interface. 592 */ 593 Ptr<NetDevice> GetBoundNetDevice (); 594 595 596 /** 597 * \brief Configure whether broadcast datagram transmissions are allowed 598 * 599 * This method corresponds to using setsockopt() SO_BROADCAST of 600 * real network or BSD sockets. If set on a socket, this option 601 * will enable or disable packets to be transmitted to broadcast 602 * destination addresses. 603 * 604 * \param allowBroadcast Whether broadcast is allowed 605 * \return true if operation succeeds 606 */ 607 virtual bool SetAllowBroadcast (bool allowBroadcast) = 0; 608 609 /** 610 * \brief Query whether broadcast datagram transmissions are allowed 611 * 612 * This method corresponds to using getsockopt() SO_BROADCAST of 613 * real network or BSD sockets. 614 * 615 * \returns true if broadcast is allowed, false otherwise 616 */ 617 virtual bool GetAllowBroadcast () const = 0; 618 619 /** 620 * \brief Enable/Disable receive packet information to socket. 621 * 622 * For IP_PKTINFO/IP6_PKTINFO. This method is only usable for 623 * Raw socket and Datagram Socket. Not supported for Stream socket. 624 * 625 * Method doesn't make distinction between IPv4 and IPv6. If it is enabled, 626 * it is enabled for all types of sockets that supports packet information 627 * 628 * \param flag Enable/Disable receive information 629 * \returns nothing 630 */ 631 void SetRecvPktInfo (bool flag); 632 633 /** 634 * \brief Get status indicating whether enable/disable packet information to socket 635 * 636 * \returns True if packet information should be sent to socket 637 */ 638 bool IsRecvPktInfo () const; 639 640 /** 641 * \brief Manually set IP Type of Service field 642 * 643 * This method corresponds to using setsockopt () IP_TOS of 644 * real network or BSD sockets. This option is for IPv4 only. 645 * Setting the IP TOS should also change the socket queueing 646 * priority as stated in the man page. However, socket priority 647 * is not yet supported. 648 * 649 * \param ipTos The desired TOS value for IP headers 650 */ 651 void SetIpTos (uint8_t ipTos); 652 653 /** 654 * \brief Query the value of IP Type of Service of this socket 655 * 656 * This method corresponds to using getsockopt () IP_TOS of real network 657 * or BSD sockets. 658 * 659 * \return The raw IP TOS value 660 */ 661 uint8_t GetIpTos (void) const; 662 663 /** 664 * \brief Tells a socket to pass information about IP Type of Service up the stack 665 * 666 * This method corresponds to using setsockopt () IP_RECVTOS of real 667 * network or BSD sockets. In our implementation, the socket simply 668 * adds a SocketIpTosTag tag to the packet before passing the 669 * packet up the stack. 670 * 671 * \param ipv4RecvTos Whether the socket should add SocketIpv4TosTag tag 672 * to the packet 673 */ 674 void SetIpRecvTos (bool ipv4RecvTos); 675 676 /** 677 * \brief Ask if the socket is currently passing information about IP Type of Service up the stack 678 * 679 * This method corresponds to using getsockopt () IP_RECVTOS of real 680 * network or BSD sockets. 681 * 682 * \return Whether the IP_RECVTOS is set 683 */ 684 bool IsIpRecvTos (void) const; 685 686 /** 687 * \brief Manually set IPv6 Traffic Class field 688 * 689 * This method corresponds to using setsockopt () IPV6_TCLASS of 690 * real network or BSD sockets. This option is for IPv6 only. 691 * Setting the IPV6_TCLASSS to -1 clears the option and let the socket 692 * uses the default value. 693 * 694 * \param ipTclass The desired TCLASS value for IPv6 headers 695 */ 696 void SetIpv6Tclass (int ipTclass); 697 698 /** 699 * \brief Query the value of IPv6 Traffic Class field of this socket 700 * 701 * This method corresponds to using getsockopt () IPV6_TCLASS of real network 702 * or BSD sockets. 703 * 704 * \return The raw IPV6_TCLASS value 705 */ 706 uint8_t GetIpv6Tclass (void) const; 707 708 /** 709 * \brief Tells a socket to pass information about IPv6 Traffic Class up the stack 710 * 711 * This method corresponds to using setsockopt () IPV6_RECVTCLASS of real 712 * network or BSD sockets. In our implementation, the socket simply 713 * adds a SocketIpv6TclasssTag tag to the packet before passing the 714 * packet up the stack. 715 * 716 * \param ipv6RecvTclass Whether the socket should add SocketIpv6TclassTag tag 717 * to the packet 718 */ 719 void SetIpv6RecvTclass (bool ipv6RecvTclass); 720 721 /** 722 * \brief Ask if the socket is currently passing information about IPv6 Traffic Class up the stack 723 * 724 * This method corresponds to using getsockopt () IPV6_RECVTCLASS of real 725 * network or BSD sockets. 726 * 727 * \return Whether the IPV6_RECVTCLASS is set 728 */ 729 bool IsIpv6RecvTclass (void) const; 730 731 /** 732 * \brief Manually set IP Time to Live field 733 * 734 * This method corresponds to using setsockopt () IP_TTL of 735 * real network or BSD sockets. 736 * 737 * \param ipTtl The desired TTL value for IP headers 738 */ 739 virtual void SetIpTtl (uint8_t ipTtl); 740 741 /** 742 * \brief Query the value of IP Time to Live field of this socket 743 * 744 * This method corresponds to using getsockopt () IP_TTL of real network 745 * or BSD sockets. 746 * 747 * \return The raw IP TTL value 748 */ 749 virtual uint8_t GetIpTtl (void) const; 750 751 /** 752 * \brief Tells a socket to pass information about IP_TTL up the stack 753 * 754 * This method corresponds to using setsockopt () IP_RECVTTL of real 755 * network or BSD sockets. In our implementation, the socket simply 756 * adds a SocketIpTtlTag tag to the packet before passing the 757 * packet up the stack. 758 * 759 * \param ipv4RecvTtl Whether the socket should add SocketIpv4TtlTag tag 760 * to the packet 761 */ 762 void SetIpRecvTtl (bool ipv4RecvTtl); 763 764 /** 765 * \brief Ask if the socket is currently passing information about IP_TTL up the stack 766 * 767 * This method corresponds to using getsockopt () IP_RECVTTL of real 768 * network or BSD sockets. 769 * 770 * \return Whether the IP_RECVTTL is set 771 */ 772 bool IsIpRecvTtl (void) const; 773 774 /** 775 * \brief Manually set IPv6 Hop Limit 776 * 777 * This method corresponds to using setsockopt () IPV6_HOPLIMIT of 778 * real network or BSD sockets. 779 * 780 * \param ipHopLimit The desired Hop Limit value for IPv6 headers 781 */ 782 virtual void SetIpv6HopLimit (uint8_t ipHopLimit); 783 784 /** 785 * \brief Query the value of IP Hop Limit field of this socket 786 * 787 * This method corresponds to using getsockopt () IPV6_HOPLIMIT of real network 788 * or BSD sockets. 789 * 790 * \return The raw IPv6 Hop Limit value 791 */ 792 virtual uint8_t GetIpv6HopLimit (void) const; 793 794 /** 795 * \brief Tells a socket to pass information about IPv6 Hop Limit up the stack 796 * 797 * This method corresponds to using setsockopt () IPV6_RECVHOPLIMIT of real 798 * network or BSD sockets. In our implementation, the socket simply 799 * adds a SocketIpv6HopLimitTag tag to the packet before passing the 800 * packet up the stack. 801 * 802 * \param ipv6RecvHopLimit Whether the socket should add SocketIpv6HopLimitTag tag 803 * to the packet 804 */ 805 void SetIpv6RecvHopLimit (bool ipv6RecvHopLimit); 806 807 /** 808 * \brief Ask if the socket is currently passing information about IPv6 Hop Limit up the stack 809 * 810 * This method corresponds to using getsockopt () IPV6_RECVHOPLIMIT of real 811 * network or BSD sockets. 812 * 813 * \return Whether the IPV6_RECVHOPLIMIT is set 814 */ 815 bool IsIpv6RecvHopLimit (void) const; 816 817protected: 818 /** 819 * \brief Notify through the callback (if set) that the connection has been 820 * established. 821 */ 822 void NotifyConnectionSucceeded (void); 823 824 /** 825 * \brief Notify through the callback (if set) that the connection has not been 826 * established due to an error. 827 */ 828 void NotifyConnectionFailed (void); 829 830 /** 831 * \brief Notify through the callback (if set) that the connection has been 832 * closed. 833 */ 834 void NotifyNormalClose (void); 835 836 /** 837 * \brief Notify through the callback (if set) that the connection has been 838 * closed due to an error. 839 */ 840 void NotifyErrorClose (void); 841 842 /** 843 * \brief Notify through the callback (if set) that an incoming connection 844 * is being requested by a remote host. 845 * 846 * This function returns true by default (i.e., accept all the incoming connections). 847 * The callback (if set) might restrict this behaviour by returning zero for a 848 * connection that should be refused. 849 * 850 * \param from the address the connection is incoming from 851 * \returns true if the connection must be accepted, false otherwise. 852 */ 853 bool NotifyConnectionRequest (const Address &from); 854 855 /** 856 * \brief Notify through the callback (if set) that a new connection has been 857 * created. 858 */ 859 void NotifyNewConnectionCreated (Ptr<Socket> socket, const Address &from); 860 861 /** 862 * \brief Notify through the callback (if set) that some data have been sent. 863 * 864 * \param size number of sent bytes. 865 */ 866 void NotifyDataSent (uint32_t size); 867 868 /** 869 * \brief Notify through the callback (if set) that some data have been sent. 870 * 871 * \param spaceAvailable the number of bytes available in the transmission buffer. 872 */ 873 void NotifySend (uint32_t spaceAvailable); 874 875 /** 876 * \brief Notify through the callback (if set) that some data have been received. 877 */ 878 void NotifyDataRecv (void); 879 880 // inherited function, no doc necessary 881 virtual void DoDispose (void); 882 883 /** 884 * \brief Checks if the socket has a specific IPv4 ToS set 885 * 886 * \returns true if the socket has a IPv4 ToS set, false otherwise. 887 */ 888 bool IsManualIpTos (void) const; 889 890 /** 891 * \brief Checks if the socket has a specific IPv6 Tclass set 892 * 893 * \returns true if the socket has a IPv6 Tclass set, false otherwise. 894 */ 895 bool IsManualIpv6Tclass (void) const; 896 897 /** 898 * \brief Checks if the socket has a specific IPv4 TTL set 899 * 900 * \returns true if the socket has a IPv4 TTL set, false otherwise. 901 */ 902 bool IsManualIpTtl (void) const; 903 904 /** 905 * \brief Checks if the socket has a specific IPv6 Hop Limit set 906 * 907 * \returns true if the socket has a IPv6 Hop Limit set, false otherwise. 908 */ 909 bool IsManualIpv6HopLimit (void) const; 910 911 Ptr<NetDevice> m_boundnetdevice; //!< the device this socket is bound to (might be null). 912 bool m_recvPktInfo; //!< if the socket should add packet info tags to the packet forwarded to L4. 913 914private: 915 Callback<void, Ptr<Socket> > m_connectionSucceeded; //!< connection succeeded callback 916 Callback<void, Ptr<Socket> > m_connectionFailed; //!< connection failed callback 917 Callback<void, Ptr<Socket> > m_normalClose; //!< connection closed callback 918 Callback<void, Ptr<Socket> > m_errorClose; //!< connection closed due to errors callback 919 Callback<bool, Ptr<Socket>, const Address &> m_connectionRequest; //!< connection request callback 920 Callback<void, Ptr<Socket>, const Address&> m_newConnectionCreated; //!< connection created callback 921 Callback<void, Ptr<Socket>, uint32_t> m_dataSent; //!< data sent callback 922 Callback<void, Ptr<Socket>, uint32_t > m_sendCb; //!< packet sent callback 923 Callback<void, Ptr<Socket> > m_receivedData; //!< data received callback 924 925 //IPv4 options 926 bool m_manualIpTos; //!< socket has IPv4 TOS set 927 bool m_manualIpTtl; //!< socket has IPv4 TTL set 928 bool m_ipRecvTos; //!< socket forwards IPv4 TOS tag to L4 929 bool m_ipRecvTtl; //!< socket forwards IPv4 TTL tag to L4 930 931 uint8_t m_ipTos; //!< the socket IPv4 TOS 932 uint8_t m_ipTtl; //!< the socket IPv4 TTL 933 934 //IPv6 options 935 bool m_manualIpv6Tclass; //!< socket has IPv6 Tclass set 936 bool m_manualIpv6HopLimit; //!< socket has IPv6 Hop Limit set 937 bool m_ipv6RecvTclass; //!< socket forwards IPv6 Tclass tag to L4 938 bool m_ipv6RecvHopLimit; //!< socket forwards IPv6 Hop Limit tag to L4 939 940 uint8_t m_ipv6Tclass; //!< the socket IPv6 Tclass 941 uint8_t m_ipv6HopLimit; //!< the socket IPv6 Hop Limit 942}; 943 944/** 945 * \brief This class implements a tag that carries an address 946 * of a packet across the socket interface. 947 */ 948class SocketAddressTag : public Tag 949{ 950public: 951 SocketAddressTag (); 952 953 /** 954 * \brief Set the tag's address 955 * 956 * \param addr the address 957 */ 958 void SetAddress (Address addr); 959 960 /** 961 * \brief Get the tag's address 962 * 963 * \returns the address 964 */ 965 Address GetAddress (void) const; 966 967 /** 968 * \brief Get the type ID. 969 * \return the object TypeId 970 */ 971 static TypeId GetTypeId (void); 972 973 // inherited function, no need to doc. 974 virtual TypeId GetInstanceTypeId (void) const; 975 976 // inherited function, no need to doc. 977 virtual uint32_t GetSerializedSize (void) const; 978 979 // inherited function, no need to doc. 980 virtual void Serialize (TagBuffer i) const; 981 982 // inherited function, no need to doc. 983 virtual void Deserialize (TagBuffer i); 984 985 // inherited function, no need to doc. 986 virtual void Print (std::ostream &os) const; 987 988private: 989 Address m_address; //!< the address carried by the tag 990}; 991 992/** 993 * \brief This class implements a tag that carries the socket-specific 994 * TTL of a packet to the IP layer 995 */ 996class SocketIpTtlTag : public Tag 997{ 998public: 999 SocketIpTtlTag (); 1000 1001 /** 1002 * \brief Set the tag's TTL 1003 * 1004 * \param ttl the TTL 1005 */ 1006 void SetTtl (uint8_t ttl); 1007 1008 /** 1009 * \brief Get the tag's TTL 1010 * 1011 * \returns the TTL 1012 */ 1013 uint8_t GetTtl (void) const; 1014 1015 /** 1016 * \brief Get the type ID. 1017 * \return the object TypeId 1018 */ 1019 static TypeId GetTypeId (void); 1020 1021 // inherited function, no need to doc. 1022 virtual TypeId GetInstanceTypeId (void) const; 1023 1024 // inherited function, no need to doc. 1025 virtual uint32_t GetSerializedSize (void) const; 1026 1027 // inherited function, no need to doc. 1028 virtual void Serialize (TagBuffer i) const; 1029 1030 // inherited function, no need to doc. 1031 virtual void Deserialize (TagBuffer i); 1032 1033 // inherited function, no need to doc. 1034 virtual void Print (std::ostream &os) const; 1035 1036private: 1037 uint8_t m_ttl; //!< the ttl carried by the tag 1038}; 1039 1040/** 1041 * \brief This class implements a tag that carries the socket-specific 1042 * HOPLIMIT of a packet to the IPv6 layer 1043 */ 1044class SocketIpv6HopLimitTag : public Tag 1045{ 1046public: 1047 SocketIpv6HopLimitTag (); 1048 1049 /** 1050 * \brief Set the tag's Hop Limit 1051 * 1052 * \param hopLimit the Hop Limit 1053 */ 1054 void SetHopLimit (uint8_t hopLimit); 1055 1056 /** 1057 * \brief Get the tag's Hop Limit 1058 * 1059 * \returns the Hop Limit 1060 */ 1061 uint8_t GetHopLimit (void) const; 1062 1063 /** 1064 * \brief Get the type ID. 1065 * \return the object TypeId 1066 */ 1067 static TypeId GetTypeId (void); 1068 1069 // inherited function, no need to doc. 1070 virtual TypeId GetInstanceTypeId (void) const; 1071 1072 // inherited function, no need to doc. 1073 virtual uint32_t GetSerializedSize (void) const; 1074 1075 // inherited function, no need to doc. 1076 virtual void Serialize (TagBuffer i) const; 1077 1078 // inherited function, no need to doc. 1079 virtual void Deserialize (TagBuffer i); 1080 1081 // inherited function, no need to doc. 1082 virtual void Print (std::ostream &os) const; 1083 1084private: 1085 uint8_t m_hopLimit; //!< the Hop Limit carried by the tag 1086}; 1087 1088/** 1089 * \brief indicates whether packets should be sent out with 1090 * the DF (Don't Fragment) flag set. 1091 */ 1092class SocketSetDontFragmentTag : public Tag 1093{ 1094public: 1095 SocketSetDontFragmentTag (); 1096 1097 /** 1098 * \brief Enables the DF (Don't Fragment) flag 1099 */ 1100 void Enable (void); 1101 1102 /** 1103 * \brief Disables the DF (Don't Fragment) flag 1104 */ 1105 void Disable (void); 1106 1107 /** 1108 * \brief Checks if the DF (Don't Fragment) flag is set 1109 * 1110 * \returns true if DF is set. 1111 */ 1112 bool IsEnabled (void) const; 1113 1114 /** 1115 * \brief Get the type ID. 1116 * \return the object TypeId 1117 */ 1118 static TypeId GetTypeId (void); 1119 1120 // inherited function, no need to doc. 1121 virtual TypeId GetInstanceTypeId (void) const; 1122 1123 // inherited function, no need to doc. 1124 virtual uint32_t GetSerializedSize (void) const; 1125 1126 // inherited function, no need to doc. 1127 virtual void Serialize (TagBuffer i) const; 1128 1129 // inherited function, no need to doc. 1130 virtual void Deserialize (TagBuffer i); 1131 1132 // inherited function, no need to doc. 1133 virtual void Print (std::ostream &os) const; 1134private: 1135 bool m_dontFragment; //!< DF bit value for outgoing packets. 1136}; 1137 1138/** 1139 * \brief indicates whether the socket has IP_TOS set. 1140 * This tag is for IPv4 socket. 1141 */ 1142class SocketIpTosTag : public Tag 1143{ 1144public: 1145 SocketIpTosTag (); 1146 1147 /** 1148 * \brief Set the tag's TOS 1149 * 1150 * \param tos the TOS 1151 */ 1152 void SetTos (uint8_t tos); 1153 1154 /** 1155 * \brief Get the tag's TOS 1156 * 1157 * \returns the TOS 1158 */ 1159 uint8_t GetTos (void) const; 1160 1161 /** 1162 * \brief Get the type ID. 1163 * \return the object TypeId 1164 */ 1165 static TypeId GetTypeId (void); 1166 1167 // inherited function, no need to doc. 1168 virtual TypeId GetInstanceTypeId (void) const; 1169 1170 // inherited function, no need to doc. 1171 virtual uint32_t GetSerializedSize (void) const; 1172 1173 // inherited function, no need to doc. 1174 virtual void Serialize (TagBuffer i) const; 1175 1176 // inherited function, no need to doc. 1177 virtual void Deserialize (TagBuffer i); 1178 1179 // inherited function, no need to doc. 1180 virtual void Print (std::ostream &os) const; 1181private: 1182 uint8_t m_ipTos; //!< the TOS carried by the tag 1183}; 1184 1185/** 1186 * \brief indicates whether the socket has IPV6_TCLASS set. 1187 * This tag is for IPv6 socket. 1188 */ 1189class SocketIpv6TclassTag : public Tag 1190{ 1191public: 1192 SocketIpv6TclassTag (); 1193 1194 /** 1195 * \brief Set the tag's Tclass 1196 * 1197 * \param tclass the Tclass 1198 */ 1199 void SetTclass (uint8_t tclass); 1200 1201 /** 1202 * \brief Get the tag's Tclass 1203 * 1204 * \returns the Tclass 1205 */ 1206 uint8_t GetTclass (void) const; 1207 1208 /** 1209 * \brief Get the type ID. 1210 * \return the object TypeId 1211 */ 1212 static TypeId GetTypeId (void); 1213 1214 // inherited function, no need to doc. 1215 virtual TypeId GetInstanceTypeId (void) const; 1216 1217 // inherited function, no need to doc. 1218 virtual uint32_t GetSerializedSize (void) const; 1219 1220 // inherited function, no need to doc. 1221 virtual void Serialize (TagBuffer i) const; 1222 1223 // inherited function, no need to doc. 1224 virtual void Deserialize (TagBuffer i); 1225 1226 // inherited function, no need to doc. 1227 virtual void Print (std::ostream &os) const; 1228private: 1229 uint8_t m_ipv6Tclass; //!< the Tclass carried by the tag 1230}; 1231 1232} // namespace ns3 1233 1234#endif /* NS3_SOCKET_H */