ns-3.24: comparison src/network/model/socket.h

equal deleted inserted replaced

-:eb6495608840
+:45c8fceae24e
 * More details are provided in the ns-3 tutorial.
 */
 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,
 ERROR_NOTCONN,
 ERROR_MSGSIZE,
 ERROR_ADDRNOTAVAIL,
 ERROR_ADDRINUSE,
 SOCKET_ERRNO_LAST
 };
+/**
+* \enum SocketType
+* \brief Enumeration of the possible socket types.
+*/
 enum SocketType {
 NS3_SOCK_STREAM,
 NS3_SOCK_SEQPACKET,
 NS3_SOCK_DGRAM,
 NS3_SOCK_RAW
 virtual int ShutdownRecv (void) = 0;
 /**
 * \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;
 /**
 * \brief Listen for incoming connections.
 * For datagram sockets, this returns the number of bytes that
 * can be passed atomically through the underlying protocol.
 *
 * 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;
 /**
 * \brief Send data (or dummy data) to the remote host
 /**
 * 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;
 /**
 * \brief Read data from the socket
 * \param buf A pointer to a raw byte buffer of some data to send.  If
 * this buffer is 0, we send dummy data whose size is specified by the
 * 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);
 /**
 *
 * \returns True if packet information should be sent to socket
 */
 bool IsRecvPktInfo () const;
-/*
+/**
 * \brief Manually set IP Type of Service field
 *
 * This method corresponds to using setsockopt () IP_TOS of
 * real network or BSD sockets. This option is for IPv4 only.
 * Setting the IP TOS should also change the socket queueing
 *
 * \param ipTos The desired TOS value for IP headers
 */
 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
 * or BSD sockets.
 *
 * \brief Ask if the socket is currently passing information about IP Type of Service up the stack
 *
 * 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
 * real network or BSD sockets. This option is for IPv6 only.
 * Setting the IPV6_TCLASSS to -1 clears the option and let the socket
 *
 * \param ipTclass The desired TCLASS value for IPv6 headers
 */
 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
 * or BSD sockets.
 *
 * \brief Ask if the socket is currently passing information about IPv6 Traffic Class up the stack
 *
 * 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
 * real network or BSD sockets.
 *
 * \param ipTtl The desired TTL value for IP headers
 */
 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
 * or BSD sockets.
 *
 * \brief Ask if the socket is currently passing information about IP_TTL up the stack
 *
 * 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
 * real network or BSD sockets.
 *
 * \param ipHopLimit The desired Hop Limit value for IPv6 headers
 */
 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
 * or BSD sockets.
 *
 * \brief Ask if the socket is currently passing information about IPv6 Hop Limit up the stack
 *
 * 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;
+Ptr<NetDevice> m_boundnetdevice; //!< the device this socket is bound to (might be null).
-bool m_recvPktInfo;
+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_connectionSucceeded;  //!< connection succeeded callback
-Callback<void, Ptr<Socket> >                   m_connectionFailed;
+Callback<void, Ptr<Socket> >                   m_connectionFailed;     //!< connection failed callback
-Callback<void, Ptr<Socket> >                   m_normalClose;
+Callback<void, Ptr<Socket> >                   m_normalClose;          //!< connection closed callback
-Callback<void, Ptr<Socket> >                   m_errorClose;
+Callback<void, Ptr<Socket> >                   m_errorClose;           //!< connection closed due to errors callback
-Callback<bool, Ptr<Socket>, const Address &>   m_connectionRequest;
+Callback<bool, Ptr<Socket>, const Address &>   m_connectionRequest;    //!< connection request callback
-Callback<void, Ptr<Socket>, const Address&>    m_newConnectionCreated;
+Callback<void, Ptr<Socket>, const Address&>    m_newConnectionCreated; //!< connection created callback
-Callback<void, Ptr<Socket>, uint32_t>          m_dataSent;
+Callback<void, Ptr<Socket>, uint32_t>          m_dataSent;             //!< data sent callback
-Callback<void, Ptr<Socket>, uint32_t >         m_sendCb;
+Callback<void, Ptr<Socket>, uint32_t >         m_sendCb;               //!< packet sent callback
-Callback<void, Ptr<Socket> >                   m_receivedData;
+Callback<void, Ptr<Socket> >                   m_receivedData;         //!< data received callback
 //IPv4 options
-bool m_manualIpTos;
+bool m_manualIpTos; //!< socket has IPv4 TOS set
-bool m_manualIpTtl;
+bool m_manualIpTtl; //!< socket has IPv4 TTL set
-bool m_ipRecvTos;
+bool m_ipRecvTos;   //!< socket forwards IPv4 TOS tag to L4
-bool m_ipRecvTtl;
+bool m_ipRecvTtl;   //!< socket forwards IPv4 TTL tag to L4
-uint8_t m_ipTos;
+uint8_t m_ipTos; //!< the socket IPv4 TOS
-uint8_t m_ipTtl;
+uint8_t m_ipTtl; //!< the socket IPv4 TTL
 //IPv6 options
-bool m_manualIpv6Tclass;
+bool m_manualIpv6Tclass;    //!< socket has IPv6 Tclass set
-bool m_manualIpv6HopLimit;
+bool m_manualIpv6HopLimit;  //!< socket has IPv6 Hop Limit set
-bool m_ipv6RecvTclass;
+bool m_ipv6RecvTclass;      //!< socket forwards IPv6 Tclass tag to L4
-bool m_ipv6RecvHopLimit;
+bool m_ipv6RecvHopLimit;    //!< socket forwards IPv6 Hop Limit tag to L4
-uint8_t m_ipv6Tclass;
+uint8_t m_ipv6Tclass;     //!< the socket IPv6 Tclass
-uint8_t m_ipv6HopLimit;
+uint8_t m_ipv6HopLimit;   //!< the socket IPv6 Hop Limit
 };
 /**
 * \brief This class implements a tag that carries an address
 * of a packet across the socket interface.
 */
 class SocketAddressTag : public Tag
 {
 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
 };
 /**
 * \brief This class implements a tag that carries the socket-specific
 * TTL of a packet to the IP layer
 */
 class SocketIpTtlTag : public Tag
 {
 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
 };
 /**
 * \brief This class implements a tag that carries the socket-specific
 * HOPLIMIT of a packet to the IPv6 layer
 */
 class SocketIpv6HopLimitTag : public Tag
 {
 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
+* \brief indicates whether packets should be sent out with
-* the DF flag set.
+* 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
 #endif /* NS3_SOCKET_H */

changeset 10405	45c8fceae24e
parent 9145	5752b425cdf5
child 10440	1e48ff9185f1