PageRenderTime 43ms CodeModel.GetById 2ms app.highlight 31ms RepoModel.GetById 1ms app.codeStats 0ms

/src/network/model/socket.h

https://bitbucket.org/cttc-lena/ns-3-lena-dev
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 */