src/network/model/socket.h
changeset 10405 45c8fceae24e
parent 9145 5752b425cdf5
child 10440 1e48ff9185f1
--- a/src/network/model/socket.h	Thu Nov 14 19:07:55 2013 +0100
+++ b/src/network/model/socket.h	Thu Nov 14 22:43:53 2013 +0100
@@ -66,11 +66,19 @@
 class Socket : public Object
 {
 public:
+  /**
+   * \brief Get the type ID.
+   * \return the object TypeId
+   */
   static TypeId GetTypeId (void);
 
   Socket (void);
   virtual ~Socket (void);
 
+  /**
+   * \enum SocketErrno
+   * \brief Enumeration of the possible errors returned by a socket.
+   */
   enum SocketErrno {
     ERROR_NOTERROR,
     ERROR_ISCONN,
@@ -89,6 +97,10 @@
     SOCKET_ERRNO_LAST
   };
 
+  /**
+   * \enum SocketType
+   * \brief Enumeration of the possible socket types.
+   */
   enum SocketType {
     NS3_SOCK_STREAM,
     NS3_SOCK_SEQPACKET,
@@ -253,6 +265,7 @@
   /**
    * \brief Initiate a connection to a remote host
    * \param address Address of remote.
+   * \returns 0 on success, -1 on error (in which case errno is set).
    */
   virtual int Connect (const Address &address) = 0;
 
@@ -271,6 +284,8 @@
    *
    * For stream sockets, this returns the available space in bytes
    * left in the transmit buffer.
+   *
+   * \returns The number of bytes which can be sent in a single Send call.
    */
   virtual uint32_t GetTxAvailable (void) const = 0;
  
@@ -341,6 +356,9 @@
    * Return number of bytes which can be returned from one or 
    * multiple calls to Recv.
    * Must be possible to call this method from the Recv callback.
+   *
+   * \returns the number of bytes which can be returned from one or
+   *          multiple Recv calls.
    */
   virtual uint32_t GetRxAvailable (void) const = 0;
 
@@ -446,6 +464,8 @@
    * second parameter
    * \param size the number of bytes to copy from the buffer
    * \param flags Socket control flags
+   * \returns the number of bytes accepted for transmission if no error
+   *          occurs, and -1 otherwise.
    */
   int Send (const uint8_t* buf, uint32_t size, uint32_t flags);
 
@@ -613,7 +633,7 @@
    */
   bool IsRecvPktInfo () const;
 
-  /*
+  /**
    * \brief Manually set IP Type of Service field
    * 
    * This method corresponds to using setsockopt () IP_TOS of
@@ -626,7 +646,7 @@
    */
   void SetIpTos (uint8_t ipTos);
 
-  /*
+  /**
    * \brief Query the value of IP Type of Service of this socket
    *
    * This method corresponds to using getsockopt () IP_TOS of real network
@@ -655,11 +675,11 @@
    * This method corresponds to using getsockopt () IP_RECVTOS of real
    * network or BSD sockets.
    *
-   * \return Wheter the IP_RECVTOS is set
+   * \return Whether the IP_RECVTOS is set
    */
   bool IsIpRecvTos (void) const;
 
-  /*
+  /**
    * \brief Manually set IPv6 Traffic Class field
    * 
    * This method corresponds to using setsockopt () IPV6_TCLASS of
@@ -671,7 +691,7 @@
    */
   void SetIpv6Tclass (int ipTclass);
 
-  /*
+  /**
    * \brief Query the value of IPv6 Traffic Class field of this socket
    *
    * This method corresponds to using getsockopt () IPV6_TCLASS of real network
@@ -700,11 +720,11 @@
    * This method corresponds to using getsockopt () IPV6_RECVTCLASS of real
    * network or BSD sockets.
    *
-   * \return Wheter the IPV6_RECVTCLASS is set
+   * \return Whether the IPV6_RECVTCLASS is set
    */
   bool IsIpv6RecvTclass (void) const;
 
-  /*
+  /**
    * \brief Manually set IP Time to Live field
    * 
    * This method corresponds to using setsockopt () IP_TTL of
@@ -714,7 +734,7 @@
    */
   virtual void SetIpTtl (uint8_t ipTtl);
 
-  /*
+  /**
    * \brief Query the value of IP Time to Live field of this socket
    *
    * This method corresponds to using getsockopt () IP_TTL of real network
@@ -743,11 +763,11 @@
    * This method corresponds to using getsockopt () IP_RECVTTL of real
    * network or BSD sockets.
    *
-   * \return Wheter the IP_RECVTTL is set
+   * \return Whether the IP_RECVTTL is set
    */
   bool IsIpRecvTtl (void) const;
 
-  /*
+  /**
    * \brief Manually set IPv6 Hop Limit
    * 
    * This method corresponds to using setsockopt () IPV6_HOPLIMIT of
@@ -757,7 +777,7 @@
    */
   virtual void SetIpv6HopLimit (uint8_t ipHopLimit);
 
-  /*
+  /**
    * \brief Query the value of IP Hop Limit field of this socket
    *
    * This method corresponds to using getsockopt () IPV6_HOPLIMIT of real network
@@ -786,58 +806,135 @@
    * This method corresponds to using getsockopt () IPV6_RECVHOPLIMIT of real
    * network or BSD sockets.
    *
-   * \return Wheter the IPV6_RECVHOPLIMIT is set
+   * \return Whether the IPV6_RECVHOPLIMIT is set
    */
   bool IsIpv6RecvHopLimit (void) const;
  
 protected:
+  /**
+   * \brief Notify through the callback (if set) that the connection has been
+   *        established.
+   */
   void NotifyConnectionSucceeded (void);
+
+  /**
+   * \brief Notify through the callback (if set) that the connection has not been
+   *        established due to an error.
+   */
   void NotifyConnectionFailed (void);
+
+  /**
+   * \brief Notify through the callback (if set) that the connection has been
+   *        closed.
+   */
   void NotifyNormalClose (void);
+
+  /**
+   * \brief Notify through the callback (if set) that the connection has been
+   *        closed due to an error.
+   */
   void NotifyErrorClose (void);
+
+  /**
+   * \brief Notify through the callback (if set) that an incoming connection
+   *        is being requested by a remote host.
+   *
+   * This function returns true by default (i.e., accept all the incoming connections).
+   * The callback (if set) might restrict this behaviour by returning zero for a
+   * connection that should be refused.
+   *
+   * \param from the address the connection is incoming from
+   * \returns true if the connection must be accepted, false otherwise.
+   */
   bool NotifyConnectionRequest (const Address &from);
+
+  /**
+   * \brief Notify through the callback (if set) that a new connection has been
+   *        created.
+   */
   void NotifyNewConnectionCreated (Ptr<Socket> socket, const Address &from);
+
+  /**
+   * \brief Notify through the callback (if set) that some data have been sent.
+   *
+   * \param size number of sent bytes.
+   */
   void NotifyDataSent (uint32_t size);
+
+  /**
+   * \brief Notify through the callback (if set) that some data have been sent.
+   *
+   * \param spaceAvailable the number of bytes available in the transmission buffer.
+   */
   void NotifySend (uint32_t spaceAvailable);
+
+  /**
+   * \brief Notify through the callback (if set) that some data have been received.
+   */
   void NotifyDataRecv (void);
+
+  // inherited function, no doc necessary
   virtual void DoDispose (void);
 
+  /**
+   * \brief Checks if the socket has a specific IPv4 ToS set
+   *
+   * \returns true if the socket has a IPv4 ToS set, false otherwise.
+   */
   bool IsManualIpTos (void) const;
+
+  /**
+   * \brief Checks if the socket has a specific IPv6 Tclass set
+   *
+   * \returns true if the socket has a IPv6 Tclass set, false otherwise.
+   */
   bool IsManualIpv6Tclass (void) const;
+
+  /**
+   * \brief Checks if the socket has a specific IPv4 TTL set
+   *
+   * \returns true if the socket has a IPv4 TTL set, false otherwise.
+   */
   bool IsManualIpTtl (void) const;
+
+  /**
+   * \brief Checks if the socket has a specific IPv6 Hop Limit set
+   *
+   * \returns true if the socket has a IPv6 Hop Limit set, false otherwise.
+   */
   bool IsManualIpv6HopLimit (void) const;
 
-  Ptr<NetDevice> m_boundnetdevice;
-  bool m_recvPktInfo;
+  Ptr<NetDevice> m_boundnetdevice; //!< the device this socket is bound to (might be null).
+  bool m_recvPktInfo; //!< if the socket should add packet info tags to the packet forwarded to L4.
 
 private:
-  Callback<void, Ptr<Socket> >                   m_connectionSucceeded;
-  Callback<void, Ptr<Socket> >                   m_connectionFailed;
-  Callback<void, Ptr<Socket> >                   m_normalClose;
-  Callback<void, Ptr<Socket> >                   m_errorClose;
-  Callback<bool, Ptr<Socket>, const Address &>   m_connectionRequest;
-  Callback<void, Ptr<Socket>, const Address&>    m_newConnectionCreated;
-  Callback<void, Ptr<Socket>, uint32_t>          m_dataSent;
-  Callback<void, Ptr<Socket>, uint32_t >         m_sendCb;
-  Callback<void, Ptr<Socket> >                   m_receivedData;
+  Callback<void, Ptr<Socket> >                   m_connectionSucceeded;  //!< connection succeeded callback
+  Callback<void, Ptr<Socket> >                   m_connectionFailed;     //!< connection failed callback
+  Callback<void, Ptr<Socket> >                   m_normalClose;          //!< connection closed callback
+  Callback<void, Ptr<Socket> >                   m_errorClose;           //!< connection closed due to errors callback
+  Callback<bool, Ptr<Socket>, const Address &>   m_connectionRequest;    //!< connection request callback
+  Callback<void, Ptr<Socket>, const Address&>    m_newConnectionCreated; //!< connection created callback
+  Callback<void, Ptr<Socket>, uint32_t>          m_dataSent;             //!< data sent callback
+  Callback<void, Ptr<Socket>, uint32_t >         m_sendCb;               //!< packet sent callback
+  Callback<void, Ptr<Socket> >                   m_receivedData;         //!< data received callback
 
   //IPv4 options
-  bool m_manualIpTos;
-  bool m_manualIpTtl;
-  bool m_ipRecvTos;
-  bool m_ipRecvTtl;
+  bool m_manualIpTos; //!< socket has IPv4 TOS set
+  bool m_manualIpTtl; //!< socket has IPv4 TTL set
+  bool m_ipRecvTos;   //!< socket forwards IPv4 TOS tag to L4
+  bool m_ipRecvTtl;   //!< socket forwards IPv4 TTL tag to L4
 
-  uint8_t m_ipTos;
-  uint8_t m_ipTtl;
+  uint8_t m_ipTos; //!< the socket IPv4 TOS
+  uint8_t m_ipTtl; //!< the socket IPv4 TTL
 
   //IPv6 options
-  bool m_manualIpv6Tclass;
-  bool m_manualIpv6HopLimit;
-  bool m_ipv6RecvTclass;
-  bool m_ipv6RecvHopLimit;
+  bool m_manualIpv6Tclass;    //!< socket has IPv6 Tclass set
+  bool m_manualIpv6HopLimit;  //!< socket has IPv6 Hop Limit set
+  bool m_ipv6RecvTclass;      //!< socket forwards IPv6 Tclass tag to L4
+  bool m_ipv6RecvHopLimit;    //!< socket forwards IPv6 Hop Limit tag to L4
 
-  uint8_t m_ipv6Tclass;
-  uint8_t m_ipv6HopLimit;
+  uint8_t m_ipv6Tclass;     //!< the socket IPv6 Tclass
+  uint8_t m_ipv6HopLimit;   //!< the socket IPv6 Hop Limit
 };
 
 /**
@@ -848,18 +945,44 @@
 {
 public:
   SocketAddressTag ();
+
+  /**
+   * \brief Set the tag's address
+   *
+   * \param addr the address
+   */
   void SetAddress (Address addr);
+
+  /**
+   * \brief Get the tag's address
+   *
+   * \returns the address
+   */
   Address GetAddress (void) const;
 
+  /**
+   * \brief Get the type ID.
+   * \return the object TypeId
+   */
   static TypeId GetTypeId (void);
+
+  // inherited function, no need to doc.
   virtual TypeId GetInstanceTypeId (void) const;
+
+  // inherited function, no need to doc.
   virtual uint32_t GetSerializedSize (void) const;
+
+  // inherited function, no need to doc.
   virtual void Serialize (TagBuffer i) const;
+
+  // inherited function, no need to doc.
   virtual void Deserialize (TagBuffer i);
+
+  // inherited function, no need to doc.
   virtual void Print (std::ostream &os) const;
 
 private:
-  Address m_address;
+  Address m_address; //!< the address carried by the tag
 };
 
 /**
@@ -870,18 +993,44 @@
 {
 public:
   SocketIpTtlTag ();
+
+  /**
+   * \brief Set the tag's TTL
+   *
+   * \param ttl the TTL
+   */
   void SetTtl (uint8_t ttl);
+
+  /**
+   * \brief Get the tag's TTL
+   *
+   * \returns the TTL
+   */
   uint8_t GetTtl (void) const;
 
+  /**
+   * \brief Get the type ID.
+   * \return the object TypeId
+   */
   static TypeId GetTypeId (void);
+
+  // inherited function, no need to doc.
   virtual TypeId GetInstanceTypeId (void) const;
+
+  // inherited function, no need to doc.
   virtual uint32_t GetSerializedSize (void) const;
+
+  // inherited function, no need to doc.
   virtual void Serialize (TagBuffer i) const;
+
+  // inherited function, no need to doc.
   virtual void Deserialize (TagBuffer i);
+
+  // inherited function, no need to doc.
   virtual void Print (std::ostream &os) const;
 
 private:
-  uint8_t m_ttl;
+  uint8_t m_ttl; //!< the ttl carried by the tag
 };
 
 /**
@@ -892,82 +1041,188 @@
 {
 public:
   SocketIpv6HopLimitTag ();
+
+  /**
+   * \brief Set the tag's Hop Limit
+   *
+   * \param hopLimit the Hop Limit
+   */
   void SetHopLimit (uint8_t hopLimit);
+
+  /**
+   * \brief Get the tag's Hop Limit
+   *
+   * \returns the Hop Limit
+   */
   uint8_t GetHopLimit (void) const;
 
+  /**
+   * \brief Get the type ID.
+   * \return the object TypeId
+   */
   static TypeId GetTypeId (void);
+
+  // inherited function, no need to doc.
   virtual TypeId GetInstanceTypeId (void) const;
+
+  // inherited function, no need to doc.
   virtual uint32_t GetSerializedSize (void) const;
+
+  // inherited function, no need to doc.
   virtual void Serialize (TagBuffer i) const;
+
+  // inherited function, no need to doc.
   virtual void Deserialize (TagBuffer i);
+
+  // inherited function, no need to doc.
   virtual void Print (std::ostream &os) const;
 
 private:
-  uint8_t m_hopLimit;
+  uint8_t m_hopLimit; //!< the Hop Limit carried by the tag
 };
 
 /**
- * \brief indicated whether packets should be sent out with
- * the DF flag set.
+ * \brief indicates whether packets should be sent out with
+ * the DF (Don't Fragment) flag set.
  */
 class SocketSetDontFragmentTag : public Tag
 {
 public:
   SocketSetDontFragmentTag ();
+
+  /**
+   * \brief Enables the DF (Don't Fragment) flag
+   */
   void Enable (void);
+
+  /**
+   * \brief Disables the DF (Don't Fragment) flag
+   */
   void Disable (void);
+
+  /**
+   * \brief Checks if the DF (Don't Fragment) flag is set
+   *
+   * \returns true if DF is set.
+   */
   bool IsEnabled (void) const;
 
+  /**
+   * \brief Get the type ID.
+   * \return the object TypeId
+   */
   static TypeId GetTypeId (void);
+
+  // inherited function, no need to doc.
   virtual TypeId GetInstanceTypeId (void) const;
+
+  // inherited function, no need to doc.
   virtual uint32_t GetSerializedSize (void) const;
+
+  // inherited function, no need to doc.
   virtual void Serialize (TagBuffer i) const;
+
+  // inherited function, no need to doc.
   virtual void Deserialize (TagBuffer i);
+
+  // inherited function, no need to doc.
   virtual void Print (std::ostream &os) const;
 private:
-  bool m_dontFragment;
+  bool m_dontFragment; //!< DF bit value for outgoing packets.
 };
 
-/*
- * \brief indicated whether the socket has IP_TOS set.
+/**
+ * \brief indicates whether the socket has IP_TOS set.
  * This tag is for IPv4 socket.
  */
 class SocketIpTosTag : public Tag
 {
 public:
   SocketIpTosTag ();
+
+  /**
+   * \brief Set the tag's TOS
+   *
+   * \param tos the TOS
+   */
   void SetTos (uint8_t tos);
+
+  /**
+   * \brief Get the tag's TOS
+   *
+   * \returns the TOS
+   */
   uint8_t GetTos (void) const;
   
+  /**
+   * \brief Get the type ID.
+   * \return the object TypeId
+   */
   static TypeId GetTypeId (void);
+
+  // inherited function, no need to doc.
   virtual TypeId GetInstanceTypeId (void) const;
+
+  // inherited function, no need to doc.
   virtual uint32_t GetSerializedSize (void) const;
+
+  // inherited function, no need to doc.
   virtual void Serialize (TagBuffer i) const;
+
+  // inherited function, no need to doc.
   virtual void Deserialize (TagBuffer i);
+
+  // inherited function, no need to doc.
   virtual void Print (std::ostream &os) const;
 private:
-  uint8_t m_ipTos;
+  uint8_t m_ipTos;  //!< the TOS carried by the tag
 };
 
-/*
- * \brief indicated whether the socket has IPV6_TCLASS set.
+/**
+ * \brief indicates whether the socket has IPV6_TCLASS set.
  * This tag is for IPv6 socket.
  */
 class SocketIpv6TclassTag : public Tag
 {
 public:
   SocketIpv6TclassTag ();
+
+  /**
+   * \brief Set the tag's Tclass
+   *
+   * \param tclass the Tclass
+   */
   void SetTclass (uint8_t tclass);
+
+  /**
+   * \brief Get the tag's Tclass
+   *
+   * \returns the Tclass
+   */
   uint8_t GetTclass (void) const;
   
+  /**
+   * \brief Get the type ID.
+   * \return the object TypeId
+   */
   static TypeId GetTypeId (void);
+
+  // inherited function, no need to doc.
   virtual TypeId GetInstanceTypeId (void) const;
+
+  // inherited function, no need to doc.
   virtual uint32_t GetSerializedSize (void) const;
+
+  // inherited function, no need to doc.
   virtual void Serialize (TagBuffer i) const;
+
+  // inherited function, no need to doc.
   virtual void Deserialize (TagBuffer i);
+
+  // inherited function, no need to doc.
   virtual void Print (std::ostream &os) const;
 private:
-  uint8_t m_ipv6Tclass;
+  uint8_t m_ipv6Tclass; //!< the Tclass carried by the tag
 };
 
 } // namespace ns3