diff --git a/src/core/model/object-base.h b/src/core/model/object-base.h index a3cc4ac68..02daa9c94 100644 --- a/src/core/model/object-base.h +++ b/src/core/model/object-base.h @@ -26,6 +26,8 @@ #include /** + * \brief Register the class in the ns-3 factory. + * * This macro should be invoked once for every class which * defines a new GetTypeId method. */ diff --git a/src/core/model/object.h b/src/core/model/object.h index 87e1edbd7..8a15c4816 100644 --- a/src/core/model/object.h +++ b/src/core/model/object.h @@ -64,7 +64,8 @@ class Object : public SimpleRefCount { public: /** - * Get the type ID. + * \brief Get the type ID. + * \return the object TypeId */ static TypeId GetTypeId (void); diff --git a/src/dsr/model/dsr-rcache.h b/src/dsr/model/dsr-rcache.h index 02dd073de..345d2c410 100644 --- a/src/dsr/model/dsr-rcache.h +++ b/src/dsr/model/dsr-rcache.h @@ -625,8 +625,8 @@ private: public: /** - * \brief dijsktra algorithm to get the best route from m_netGraph and update the m_bestRoutesTable_link - * \when current graph information has changed + * \brief Dijsktra algorithm to get the best route from m_netGraph and update the m_bestRoutesTable_link + * when current graph information has changed * \param The type of the cache */ void SetCacheType (std::string type); diff --git a/src/dsr/model/dsr-routing.h b/src/dsr/model/dsr-routing.h index 089a39324..63423855a 100644 --- a/src/dsr/model/dsr-routing.h +++ b/src/dsr/model/dsr-routing.h @@ -153,7 +153,7 @@ public: */ Ptr GetPassiveBuffer () const; - ///\functions used to direct to route cache + /// functions used to direct to route cache //\{ bool IsLinkCache (); void UseExtends (RouteCacheEntry::IP_VECTOR rt); diff --git a/src/internet/helper/internet-stack-helper.cc b/src/internet/helper/internet-stack-helper.cc index a16259f6b..bf1552521 100644 --- a/src/internet/helper/internet-stack-helper.cc +++ b/src/internet/helper/internet-stack-helper.cc @@ -216,16 +216,16 @@ namespace ns3 { // Global maps of protocol/interface pairs to file objects seems to fit the // bill. // -typedef std::pair, uint32_t> InterfacePairIpv4; -typedef std::map > InterfaceFileMapIpv4; -typedef std::map > InterfaceStreamMapIpv4; +typedef std::pair, uint32_t> InterfacePairIpv4; /**< Ipv4/interface pair */ +typedef std::map > InterfaceFileMapIpv4; /**< Ipv4/interface and Pcap file wrapper container */ +typedef std::map > InterfaceStreamMapIpv4; /**< Ipv4/interface and output stream container */ static InterfaceFileMapIpv4 g_interfaceFileMapIpv4; /**< A mapping of Ipv4/interface pairs to pcap files */ static InterfaceStreamMapIpv4 g_interfaceStreamMapIpv4; /**< A mapping of Ipv4/interface pairs to ascii streams */ -typedef std::pair, uint32_t> InterfacePairIpv6; -typedef std::map > InterfaceFileMapIpv6; -typedef std::map > InterfaceStreamMapIpv6; +typedef std::pair, uint32_t> InterfacePairIpv6; /**< Ipv6/interface pair */ +typedef std::map > InterfaceFileMapIpv6; /**< Ipv6/interface and Pcap file wrapper container */ +typedef std::map > InterfaceStreamMapIpv6; /**< Ipv6/interface and output stream container */ static InterfaceFileMapIpv6 g_interfaceFileMapIpv6; /**< A mapping of Ipv6/interface pairs to pcap files */ static InterfaceStreamMapIpv6 g_interfaceStreamMapIpv6; /**< A mapping of Ipv6/interface pairs to pcap files */ @@ -490,6 +490,12 @@ InternetStackHelper::Install (std::string nodeName) const Install (node); } +/** + * \brief Sync function for IPv4 packet - Pcap output + * \param p smart pointer to the packet + * \param ipv4 smart pointer to the node's IPv4 stack + * \param interface incoming interface + */ static void Ipv4L3ProtocolRxTxSink (Ptr p, Ptr ipv4, uint32_t interface) { @@ -582,6 +588,12 @@ InternetStackHelper::EnablePcapIpv4Internal (std::string prefix, Ptr ipv4, g_interfaceFileMapIpv4[std::make_pair (ipv4, interface)] = file; } +/** + * \brief Sync function for IPv6 packet - Pcap output + * \param p smart pointer to the packet + * \param ipv6 smart pointer to the node's IPv6 stack + * \param interface incoming interface + */ static void Ipv6L3ProtocolRxTxSink (Ptr p, Ptr ipv6, uint32_t interface) { @@ -674,6 +686,15 @@ InternetStackHelper::EnablePcapIpv6Internal (std::string prefix, Ptr ipv6, g_interfaceFileMapIpv6[std::make_pair (ipv6, interface)] = file; } +/** + * \brief Sync function for IPv4 dropped packet - Ascii output + * \param stream the output stream + * \param header IPv4 header + * \param packet smart pointer to the packet + * \param reason the reason for the dropping + * \param ipv4 smart pointer to the node's IPv4 stack + * \param interface incoming interface + */ static void Ipv4L3ProtocolDropSinkWithoutContext ( Ptr stream, @@ -701,6 +722,13 @@ Ipv4L3ProtocolDropSinkWithoutContext ( *stream->GetStream () << "d " << Simulator::Now ().GetSeconds () << " " << *p << std::endl; } +/** + * \brief Sync function for IPv4 transmitted packet - Ascii output + * \param stream the output stream + * \param packet smart pointer to the packet + * \param ipv4 smart pointer to the node's IPv4 stack + * \param interface incoming interface + */ static void Ipv4L3ProtocolTxSinkWithoutContext ( Ptr stream, @@ -718,6 +746,13 @@ Ipv4L3ProtocolTxSinkWithoutContext ( *stream->GetStream () << "t " << Simulator::Now ().GetSeconds () << " " << *packet << std::endl; } +/** + * \brief Sync function for IPv4 received packet - Ascii output + * \param stream the output stream + * \param packet smart pointer to the packet + * \param ipv4 smart pointer to the node's IPv4 stack + * \param interface incoming interface + */ static void Ipv4L3ProtocolRxSinkWithoutContext ( Ptr stream, @@ -735,6 +770,16 @@ Ipv4L3ProtocolRxSinkWithoutContext ( *stream->GetStream () << "r " << Simulator::Now ().GetSeconds () << " " << *packet << std::endl; } +/** + * \brief Sync function for IPv4 dropped packet - Ascii output + * \param stream the output stream + * \param context the context + * \param header IPv4 header + * \param packet smart pointer to the packet + * \param reason the reason for the dropping + * \param ipv4 smart pointer to the node's IPv4 stack + * \param interface incoming interface + */ static void Ipv4L3ProtocolDropSinkWithContext ( Ptr stream, @@ -768,6 +813,14 @@ Ipv4L3ProtocolDropSinkWithContext ( #endif } +/** + * \brief Sync function for IPv4 transmitted packet - Ascii output + * \param stream the output stream + * \param context the context + * \param packet smart pointer to the packet + * \param ipv4 smart pointer to the node's IPv4 stack + * \param interface incoming interface + */ static void Ipv4L3ProtocolTxSinkWithContext ( Ptr stream, @@ -791,6 +844,14 @@ Ipv4L3ProtocolTxSinkWithContext ( #endif } +/** + * \brief Sync function for IPv4 received packet - Ascii output + * \param stream the output stream + * \param context the context + * \param packet smart pointer to the packet + * \param ipv4 smart pointer to the node's IPv4 stack + * \param interface incoming interface + */ static void Ipv4L3ProtocolRxSinkWithContext ( Ptr stream, @@ -963,6 +1024,15 @@ InternetStackHelper::EnableAsciiIpv4Internal ( g_interfaceStreamMapIpv4[std::make_pair (ipv4, interface)] = stream; } +/** + * \brief Sync function for IPv6 dropped packet - Ascii output + * \param stream the output stream + * \param header IPv6 header + * \param packet smart pointer to the packet + * \param reason the reason for the dropping + * \param ipv6 smart pointer to the node's IPv6 stack + * \param interface incoming interface + */ static void Ipv6L3ProtocolDropSinkWithoutContext ( Ptr stream, @@ -990,6 +1060,13 @@ Ipv6L3ProtocolDropSinkWithoutContext ( *stream->GetStream () << "d " << Simulator::Now ().GetSeconds () << " " << *p << std::endl; } +/** + * \brief Sync function for IPv6 transmitted packet - Ascii output + * \param stream the output stream + * \param packet smart pointer to the packet + * \param ipv6 smart pointer to the node's IPv6 stack + * \param interface incoming interface + */ static void Ipv6L3ProtocolTxSinkWithoutContext ( Ptr stream, @@ -1007,6 +1084,13 @@ Ipv6L3ProtocolTxSinkWithoutContext ( *stream->GetStream () << "t " << Simulator::Now ().GetSeconds () << " " << *packet << std::endl; } +/** + * \brief Sync function for IPv6 received packet - Ascii output + * \param stream the output stream + * \param packet smart pointer to the packet + * \param ipv6 smart pointer to the node's IPv6 stack + * \param interface incoming interface + */ static void Ipv6L3ProtocolRxSinkWithoutContext ( Ptr stream, @@ -1024,6 +1108,16 @@ Ipv6L3ProtocolRxSinkWithoutContext ( *stream->GetStream () << "r " << Simulator::Now ().GetSeconds () << " " << *packet << std::endl; } +/** + * \brief Sync function for IPv6 dropped packet - Ascii output + * \param stream the output stream + * \param context the context + * \param header IPv6 header + * \param packet smart pointer to the packet + * \param reason the reason for the dropping + * \param ipv6 smart pointer to the node's IPv6 stack + * \param interface incoming interface + */ static void Ipv6L3ProtocolDropSinkWithContext ( Ptr stream, @@ -1057,6 +1151,14 @@ Ipv6L3ProtocolDropSinkWithContext ( #endif } +/** + * \brief Sync function for IPv6 transmitted packet - Ascii output + * \param stream the output stream + * \param context the context + * \param packet smart pointer to the packet + * \param ipv6 smart pointer to the node's IPv6 stack + * \param interface incoming interface + */ static void Ipv6L3ProtocolTxSinkWithContext ( Ptr stream, @@ -1080,6 +1182,14 @@ Ipv6L3ProtocolTxSinkWithContext ( #endif } +/** + * \brief Sync function for IPv6 received packet - Ascii output + * \param stream the output stream + * \param context the context + * \param packet smart pointer to the packet + * \param ipv6 smart pointer to the node's IPv6 stack + * \param interface incoming interface + */ static void Ipv6L3ProtocolRxSinkWithContext ( Ptr stream, diff --git a/src/internet/helper/internet-stack-helper.h b/src/internet/helper/internet-stack-helper.h index f4d16b06f..b960ef33d 100644 --- a/src/internet/helper/internet-stack-helper.h +++ b/src/internet/helper/internet-stack-helper.h @@ -80,7 +80,15 @@ public: * Destroy the InternetStackHelper */ virtual ~InternetStackHelper(void); + + /** + * \brief Copy constructor + */ InternetStackHelper (const InternetStackHelper &); + + /** + * \brief Copy constructor + */ InternetStackHelper &operator = (const InternetStackHelper &o); /** @@ -266,8 +274,21 @@ private: uint32_t interface, bool explicitFilename); + /** + * \brief Initialize the helper to its default values + */ void Initialize (void); + + /** + * \internal + * \brief TCP objects factory + */ ObjectFactory m_tcpFactory; + + /** + * \internal + * \brief IPv4 routing helper. + */ const Ipv4RoutingHelper *m_routing; /** @@ -278,6 +299,10 @@ private: /** * \internal + * + * \brief create an object from its TypeId and aggregates it to the node + * \param node the node + * \param typeId the object TypeId */ static void CreateAndAggregateObjectFromTypeId (Ptr node, const std::string typeId); @@ -288,40 +313,64 @@ private: /** * \internal + * + * \brief checks if there is an hook to a Pcap wrapper + * \param ipv4 pointer to the IPv4 object + * \returns true if a hook is found */ bool PcapHooked (Ptr ipv4); /** * \internal + * + * \brief checks if there is an hook to an ascii output stream + * \param ipv4 pointer to the IPv4 object + * \returns true if a hook is found */ bool AsciiHooked (Ptr ipv4); /** * \internal + * + * \brief checks if there is an hook to a Pcap wrapper + * \param ipv6 pointer to the IPv6 object + * \returns true if a hook is found */ bool PcapHooked (Ptr ipv6); /** * \internal + * + * \brief checks if there is an hook to an ascii output stream + * \param ipv6 pointer to the IPv6 object + * \returns true if a hook is found */ bool AsciiHooked (Ptr ipv6); /** + * \internal + * * \brief IPv4 install state (enabled/disabled) ? */ bool m_ipv4Enabled; /** + * \internal + * * \brief IPv6 install state (enabled/disabled) ? */ bool m_ipv6Enabled; /** + * \internal + * * \brief IPv4 ARP Jitter state (enabled/disabled) ? */ bool m_ipv4ArpJitterEnabled; /** + * \internal + * * \brief IPv6 IPv6 NS and RS Jitter state (enabled/disabled) ? */ bool m_ipv6NsRsJitterEnabled; diff --git a/src/internet/helper/internet-trace-helper.h b/src/internet/helper/internet-trace-helper.h index f1b1818ce..5fffd88bf 100644 --- a/src/internet/helper/internet-trace-helper.h +++ b/src/internet/helper/internet-trace-helper.h @@ -268,7 +268,7 @@ public: void EnableAsciiIpv4All (Ptr stream); /** - * @brief Enable pcap output on the Ipv4 and interface pair specified by a + * @brief Enable ascii trace output on the Ipv4 and interface pair specified by a * global node-id (of a previously created node) and interface. Since there * can be only one Ipv4 aggregated to a node, the node-id unambiguously * determines the Ipv4. @@ -283,7 +283,7 @@ public: void EnableAsciiIpv4 (std::string prefix, uint32_t nodeid, uint32_t deviceid, bool explicitFilename); /** - * @brief Enable pcap output on the Ipv4 and interface pair specified by a + * @brief Enable ascii trace output on the Ipv4 and interface pair specified by a * global node-id (of a previously created node) and interface. Since there * can be only one Ipv4 aggregated to a node, the node-id unambiguously * determines the Ipv4. @@ -299,7 +299,21 @@ public: private: /** - * @internal Avoid code duplication. + * @internal + * + * @brief Enable ascii trace output on the Ipv4 and interface pair specified by a + * global node-id (of a previously created node) and interface. Since there + * can be only one Ipv4 aggregated to a node, the node-id unambiguously + * determines the Ipv4. + * + * @param stream An OutputStreamWrapper representing an existing file to use + * when writing trace data. + * @param prefix Filename prefix to use when creating ascii trace files + * @param nodeid The node identifier/number of the node on which to enable + * ascii tracing + * @param interface The device identifier/index of the device on which to enable + * ascii tracing + * @param explicitFilename Treat the prefix as an explicit filename if true. */ void EnableAsciiIpv4Impl (Ptr stream, std::string prefix, @@ -308,17 +322,50 @@ private: bool explicitFilename); /** - * @internal Avoid code duplication. + * @internal + * + * @brief Enable ascii trace output on the Ipv4 and interface pair specified by a + * global node-id (of a previously created node) and interface. Since there + * can be only one Ipv4 aggregated to a node, the node-id unambiguously + * determines the Ipv4. + * + * @param stream An OutputStreamWrapper representing an existing file to use + * when writing trace data. + * @param prefix Filename prefix to use when creating ascii trace files + * @param n container of nodes. */ void EnableAsciiIpv4Impl (Ptr stream, std::string prefix, NodeContainer n); /** - * @internal Avoid code duplication. + * @internal + * + * @brief Enable ascii trace output on the Ipv4 and interface pair specified by a + * global node-id (of a previously created node) and interface. Since there + * can be only one Ipv4 aggregated to a node, the node-id unambiguously + * determines the Ipv4. + * + * @param stream An OutputStreamWrapper representing an existing file to use + * when writing trace data. + * @param prefix Filename prefix to use when creating ascii trace files + * @param c Ipv4InterfaceContainer of Ipv4 and interface pairs */ void EnableAsciiIpv4Impl (Ptr stream, std::string prefix, Ipv4InterfaceContainer c); /** - * @internal Avoid code duplication. + * @internal + * + * @brief Enable ascii trace output on the Ipv4 and interface pair specified by a + * global node-id (of a previously created node) and interface. Since there + * can be only one Ipv4 aggregated to a node, the node-id unambiguously + * determines the Ipv4. + * + * @param stream An OutputStreamWrapper representing an existing file to use + * when writing trace data. + * @param prefix Filename prefix to use when creating ascii trace files + * @param ipv4Name Name of the Ptr on which you want to enable tracing. + * @param interface The device identifier/index of the device on which to enable + * ascii tracing + * @param explicitFilename Treat the prefix as an explicit filename if true. */ void EnableAsciiIpv4Impl (Ptr stream, std::string prefix, @@ -327,7 +374,20 @@ private: bool explicitFilename); /** - * @internal Avoid code duplication. + * @internal + * + * @brief Enable ascii trace output on the Ipv4 and interface pair specified by a + * global node-id (of a previously created node) and interface. Since there + * can be only one Ipv4 aggregated to a node, the node-id unambiguously + * determines the Ipv4. + * + * @param stream An OutputStreamWrapper representing an existing file to use + * when writing trace data. + * @param prefix Filename prefix to use when creating ascii trace files + * @param ipv4 Ptr on which you want to enable tracing. + * @param interface The device identifier/index of the device on which to enable + * ascii tracing + * @param explicitFilename Treat the prefix as an explicit filename if true. */ void EnableAsciiIpv4Impl (Ptr stream, std::string prefix, @@ -558,7 +618,7 @@ public: void EnableAsciiIpv6 (Ptr stream, NodeContainer n); /** - * @brief Enable pcap output on the Ipv6 and interface pair specified by a + * @brief Enable ascii trace output on the Ipv6 and interface pair specified by a * global node-id (of a previously created node) and interface. Since there * can be only one Ipv6 aggregated to a node, the node-id unambiguously * determines the Ipv6. @@ -573,7 +633,7 @@ public: void EnableAsciiIpv6 (std::string prefix, uint32_t nodeid, uint32_t interface, bool explicitFilename); /** - * @brief Enable pcap output on the Ipv6 and interface pair specified by a + * @brief Enable ascii trace output on the Ipv6 and interface pair specified by a * global node-id (of a previously created node) and interface. Since there * can be only one Ipv6 aggregated to a node, the node-id unambiguously * determines the Ipv6. @@ -605,7 +665,21 @@ public: private: /** - * @internal Avoid code duplication. + * @internal + * + * @brief Enable ascii trace output on the Ipv6 and interface pair specified by a + * global node-id (of a previously created node) and interface. Since there + * can be only one Ipv6 aggregated to a node, the node-id unambiguously + * determines the Ipv6. + * + * @param stream An OutputStreamWrapper representing an existing file to use + * when writing trace data. + * @param prefix Filename prefix to use when creating ascii trace files + * @param nodeid The node identifier/number of the node on which to enable + * ascii tracing + * @param interface The device identifier/index of the device on which to enable + * ascii tracing + * @param explicitFilename Treat the prefix as an explicit filename if true. */ void EnableAsciiIpv6Impl (Ptr stream, std::string prefix, @@ -614,17 +688,50 @@ private: bool explicitFilename); /** - * @internal Avoid code duplication. + * @internal + * + * @brief Enable ascii trace output on the Ipv6 and interface pair specified by a + * global node-id (of a previously created node) and interface. Since there + * can be only one Ipv6 aggregated to a node, the node-id unambiguously + * determines the Ipv6. + * + * @param stream An OutputStreamWrapper representing an existing file to use + * when writing trace data. + * @param prefix Filename prefix to use when creating ascii trace files + * @param n container of nodes. */ void EnableAsciiIpv6Impl (Ptr stream, std::string prefix, NodeContainer n); /** - * @internal Avoid code duplication. + * @internal + * + * @brief Enable ascii trace output on the Ipv6 and interface pair specified by a + * global node-id (of a previously created node) and interface. Since there + * can be only one Ipv6 aggregated to a node, the node-id unambiguously + * determines the Ipv6. + * + * @param stream An OutputStreamWrapper representing an existing file to use + * when writing trace data. + * @param prefix Filename prefix to use when creating ascii trace files + * @param c Ipv6InterfaceContainer of Ipv6 and interface pairs */ void EnableAsciiIpv6Impl (Ptr stream, std::string prefix, Ipv6InterfaceContainer c); /** - * @internal Avoid code duplication. + * @internal + * + * @brief Enable ascii trace output on the Ipv6 and interface pair specified by a + * global node-id (of a previously created node) and interface. Since there + * can be only one Ipv6 aggregated to a node, the node-id unambiguously + * determines the Ipv6. + * + * @param stream An OutputStreamWrapper representing an existing file to use + * when writing trace data. + * @param prefix Filename prefix to use when creating ascii trace files + * @param ipv6Name Name of the Ptr on which you want to enable tracing. + * @param interface The device identifier/index of the device on which to enable + * ascii tracing + * @param explicitFilename Treat the prefix as an explicit filename if true. */ void EnableAsciiIpv6Impl (Ptr stream, std::string prefix, @@ -633,7 +740,20 @@ private: bool explicitFilename); /** - * @internal Avoid code duplication. + * @internal + * + * @brief Enable ascii trace output on the Ipv6 and interface pair specified by a + * global node-id (of a previously created node) and interface. Since there + * can be only one Ipv6 aggregated to a node, the node-id unambiguously + * determines the Ipv6. + * + * @param stream An OutputStreamWrapper representing an existing file to use + * when writing trace data. + * @param prefix Filename prefix to use when creating ascii trace files + * @param ipv6 Ptr on which you want to enable tracing. + * @param interface The device identifier/index of the device on which to enable + * ascii tracing + * @param explicitFilename Treat the prefix as an explicit filename if true. */ void EnableAsciiIpv6Impl (Ptr stream, std::string prefix, diff --git a/src/internet/helper/ipv4-routing-helper.h b/src/internet/helper/ipv4-routing-helper.h index f777f17a0..6a676836a 100644 --- a/src/internet/helper/ipv4-routing-helper.h +++ b/src/internet/helper/ipv4-routing-helper.h @@ -110,7 +110,7 @@ public: void PrintRoutingTableEvery (Time printInterval, Ptr node, Ptr stream) const; /** - * \brief Request a specified routing protocol from Ipv4RoutingProtocol protocol + * \brief Request a specified routing protocol <T> from Ipv4RoutingProtocol protocol * * If protocol is Ipv4ListRouting, then protocol will be searched in the list, * otherwise a simple DynamicCast will be performed @@ -122,11 +122,44 @@ public: static Ptr GetRouting (Ptr protocol); private: + /** + * \internal + * + * \brief prints the routing tables of a node. + * \param node The node ptr for which we need the routing table to be printed + * \param stream The output stream object to use + * + * This method calls the PrintRoutingTable() method of the + * Ipv6RoutingProtocol stored in the Ipv6 object; + * the output format is routing protocol-specific. + */ void Print (Ptr node, Ptr stream) const; + + /** + * \internal + * + * \brief prints the routing tables of a node at regular intervals specified by user. + * \param printInterval the time interval for which the routing table is supposed to be printed. + * \param node The node ptr for which we need the routing table to be printed + * \param stream The output stream object to use + * + * This method calls the PrintRoutingTable() method of the + * Ipv6RoutingProtocol stored in the Ipv6 object, for the selected node + * at the specified interval; the output format is routing protocol-specific. + */ void PrintEvery (Time printInterval, Ptr node, Ptr stream) const; }; +/** + * \brief Request a specified routing protocol <T> from Ipv4RoutingProtocol protocol + * + * If protocol is Ipv4ListRouting, then protocol will be searched in the list, + * otherwise a simple DynamicCast will be performed + * + * \param protocol Smart pointer to Ipv4RoutingProtocol object + * \return a Smart Pointer to the requested protocol (zero if the protocol can't be found) + */ template Ptr Ipv4RoutingHelper::GetRouting (Ptr protocol) { diff --git a/src/internet/helper/ipv6-address-helper.h b/src/internet/helper/ipv6-address-helper.h index f1e4e56e3..aca38b371 100644 --- a/src/internet/helper/ipv6-address-helper.h +++ b/src/internet/helper/ipv6-address-helper.h @@ -73,6 +73,11 @@ namespace ns3 { * If this method is called, the addressed returned will include a * modified EUI-64-format identifier created from the MAC address as * specified in \RFC{4291}. + * + * BEWARE: the underlying implementation acts as a Singleton. + * In other terms, two different instances of Ipv6AddressHelper will + * pick IPv6 numbers from the same pool. Changing the network in one of them + * will also change the network in the other instances. */ class Ipv6AddressHelper { diff --git a/src/internet/helper/ipv6-interface-container.h b/src/internet/helper/ipv6-interface-container.h index f366ca7b3..18b47d24d 100644 --- a/src/internet/helper/ipv6-interface-container.h +++ b/src/internet/helper/ipv6-interface-container.h @@ -41,7 +41,12 @@ namespace ns3 class Ipv6InterfaceContainer { public: + + /** + * \brief Container Const Iterator for pairs of Ipv6 smart pointer / Interface Index. + */ typedef std::vector, uint32_t> >::const_iterator Iterator; + /** * \brief Constructor. */ @@ -205,6 +210,10 @@ public: void SetDefaultRoute (uint32_t i, Ipv6Address routerAddr); private: + /** + * \internal + * \brief Container for pairs of Ipv6 smart pointer / Interface Index. + */ typedef std::vector, uint32_t> > InterfaceVector; /** diff --git a/src/internet/helper/ipv6-list-routing-helper.h b/src/internet/helper/ipv6-list-routing-helper.h index ed64b5769..3dd59d838 100644 --- a/src/internet/helper/ipv6-list-routing-helper.h +++ b/src/internet/helper/ipv6-list-routing-helper.h @@ -86,9 +86,15 @@ private: * \internal * \brief Assignment operator declared private and not implemented to disallow * assignment and prevent the compiler from happily inserting its own. + * \param o object to copy from + * \returns a reference to the new object */ Ipv6ListRoutingHelper &operator = (const Ipv6ListRoutingHelper &o); + /** + * \internal + * \brief Container for pairs of Ipv6RoutingHelper pointer / priority. + */ std::list > m_list; }; diff --git a/src/internet/helper/ipv6-routing-helper.h b/src/internet/helper/ipv6-routing-helper.h index 8c08d617a..df577a53e 100644 --- a/src/internet/helper/ipv6-routing-helper.h +++ b/src/internet/helper/ipv6-routing-helper.h @@ -112,7 +112,7 @@ public: void PrintRoutingTableEvery (Time printInterval, Ptr node, Ptr stream) const; /** - * \brief Request a specified routing protocol from Ipv6RoutingProtocol protocol + * \brief Request a specified routing protocol <T> from Ipv6RoutingProtocol protocol * * If protocol is Ipv6ListRouting, then protocol will be searched in the list, * otherwise a simple DynamicCast will be performed @@ -124,10 +124,43 @@ public: static Ptr GetRouting (Ptr protocol); private: + /** + * \internal + * + * \brief prints the routing tables of a node. + * \param node The node ptr for which we need the routing table to be printed + * \param stream The output stream object to use + * + * This method calls the PrintRoutingTable() method of the + * Ipv6RoutingProtocol stored in the Ipv6 object; + * the output format is routing protocol-specific. + */ void Print (Ptr node, Ptr stream) const; + + /** + * \internal + * + * \brief prints the routing tables of a node at regular intervals specified by user. + * \param printInterval the time interval for which the routing table is supposed to be printed. + * \param node The node ptr for which we need the routing table to be printed + * \param stream The output stream object to use + * + * This method calls the PrintRoutingTable() method of the + * Ipv6RoutingProtocol stored in the Ipv6 object, for the selected node + * at the specified interval; the output format is routing protocol-specific. + */ void PrintEvery (Time printInterval, Ptr node, Ptr stream) const; }; +/** + * \brief Request a specified routing protocol <T> from Ipv6RoutingProtocol protocol + * + * If protocol is Ipv6ListRouting, then protocol will be searched in the list, + * otherwise a simple DynamicCast will be performed + * + * \param protocol Smart pointer to Ipv6RoutingProtocol object + * \return a Smart Pointer to the requested protocol (zero if the protocol can't be found) + */ template Ptr Ipv6RoutingHelper::GetRouting (Ptr protocol) { diff --git a/src/internet/helper/ipv6-static-routing-helper.h b/src/internet/helper/ipv6-static-routing-helper.h index 4b18c379a..efb59e9bb 100644 --- a/src/internet/helper/ipv6-static-routing-helper.h +++ b/src/internet/helper/ipv6-static-routing-helper.h @@ -121,6 +121,8 @@ private: * \internal * \brief Assignment operator declared private and not implemented to disallow * assignment and prevent the compiler from happily inserting its own. + * \param o object to copy from + * \returns a reference to the new object */ Ipv6StaticRoutingHelper &operator = (const Ipv6StaticRoutingHelper &o); }; diff --git a/src/internet/model/icmpv4-l4-protocol.h b/src/internet/model/icmpv4-l4-protocol.h index 8daa66acf..3a7329107 100644 --- a/src/internet/model/icmpv4-l4-protocol.h +++ b/src/internet/model/icmpv4-l4-protocol.h @@ -24,12 +24,26 @@ public: static uint16_t GetStaticProtocolNumber (void); virtual int GetProtocolNumber (void) const; + + /** + * \brief Receive method. + * \param p the packet + * \param header the IPv4 header + * \param interface the interface from which the packet is coming + */ virtual enum IpL4Protocol::RxStatus Receive (Ptr p, - Ipv4Header const &header, - Ptr incomingInterface); + Ipv4Header const &header, + Ptr incomingInterface); + + /** + * \brief Receive method. + * \param p the packet + * \param header the IPv6 header + * \param interface the interface from which the packet is coming + */ virtual enum IpL4Protocol::RxStatus Receive (Ptr p, - Ipv6Header const &header, - Ptr incomingInterface); + Ipv6Header const &header, + Ptr incomingInterface); void SendDestUnreachFragNeeded (Ipv4Header header, Ptr orgData, uint16_t nextHopMtu); void SendTimeExceededTtl (Ipv4Header header, Ptr orgData); diff --git a/src/internet/model/icmpv6-l4-protocol.h b/src/internet/model/icmpv6-l4-protocol.h index 868171993..0e5c33b58 100644 --- a/src/internet/model/icmpv6-l4-protocol.h +++ b/src/internet/model/icmpv6-l4-protocol.h @@ -346,8 +346,7 @@ public: /** * \brief Receive method. * \param p the packet - * \param src source address - * \param dst destination address + * \param header the IPv6 header * \param interface the interface from which the packet is coming */ virtual enum IpL4Protocol::RxStatus Receive (Ptr p, diff --git a/src/internet/model/ip-l4-protocol.h b/src/internet/model/ip-l4-protocol.h index 3c2c9a2e6..5238b20c6 100644 --- a/src/internet/model/ip-l4-protocol.h +++ b/src/internet/model/ip-l4-protocol.h @@ -74,6 +74,15 @@ public: virtual enum RxStatus Receive (Ptr p, Ipv4Header const &header, Ptr incomingInterface) = 0; + + /** + * \param p packet to forward up + * \param header IPv6 Header information + * \param incomingInterface the Ipv6Interface on which the packet arrived + * + * Called from lower-level layers to send the packet up + * in the stack. + */ virtual enum RxStatus Receive (Ptr p, Ipv6Header const &header, Ptr incomingInterface) = 0; @@ -96,6 +105,22 @@ public: uint8_t icmpType, uint8_t icmpCode, uint32_t icmpInfo, Ipv4Address payloadSource, Ipv4Address payloadDestination, const uint8_t payload[8]); + + + /** + * \param icmpSource the source address of the icmp message + * \param icmpTtl the ttl of the icmp message + * \param icmpType the 'type' field of the icmp message + * \param icmpCode the 'code' field of the icmp message + * \param icmpInfo extra information dependent on the icmp message + * generated by Icmpv6L4Protocol + * \param payloadSource the source address of the packet which triggered + * the icmp message + * \param payloadDestination the destination address of the packet which + * triggered the icmp message. + * \param payload the first 8 bytes of the udp header of the packet + * which triggered the icmp message. + */ virtual void ReceiveIcmp (Ipv6Address icmpSource, uint8_t icmpTtl, uint8_t icmpType, uint8_t icmpCode, uint32_t icmpInfo, Ipv6Address payloadSource, Ipv6Address payloadDestination, @@ -103,6 +128,7 @@ public: typedef Callback, Ipv4Address, Ipv4Address, uint8_t, Ptr > DownTargetCallback; typedef Callback, Ipv6Address, Ipv6Address, uint8_t, Ptr > DownTargetCallback6; + /** * This method allows a caller to set the current down target callback * set for this L4 protocol @@ -110,7 +136,15 @@ public: * \param cb current Callback for the L4 protocol */ virtual void SetDownTarget (DownTargetCallback cb) = 0; + + /** + * This method allows a caller to set the current down target callback + * set for this L4 protocol + * + * \param cb current Callback for the L4 protocol + */ virtual void SetDownTarget6 (DownTargetCallback6 cb) = 0; + /** * This method allows a caller to get the current down target callback * set for this L4 protocol, for @@ -118,6 +152,13 @@ public: * \return current Callback for the L4 protocol */ virtual DownTargetCallback GetDownTarget (void) const = 0; + + /** + * This method allows a caller to get the current down target callback + * set for this L4 protocol, for + * + * \return current Callback for the L4 protocol + */ virtual DownTargetCallback6 GetDownTarget6 (void) const = 0; }; diff --git a/src/internet/model/ipv4-routing-protocol.h b/src/internet/model/ipv4-routing-protocol.h index 63d23400d..a8c1f66f0 100644 --- a/src/internet/model/ipv4-routing-protocol.h +++ b/src/internet/model/ipv4-routing-protocol.h @@ -50,11 +50,22 @@ class NetDevice; class Ipv4RoutingProtocol : public Object { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); + /// Callback for unicast packets to be forwarded typedef Callback, Ptr, const Ipv4Header &> UnicastForwardCallback; + + /// Callback for multicast packets to be forwarded typedef Callback, Ptr, const Ipv4Header &> MulticastForwardCallback; + + /// Callback for packets to be locally delivered typedef Callback, const Ipv4Header &, uint32_t > LocalDeliverCallback; + + /// Callback for routing errors (e.g., no route found) typedef Callback, const Ipv4Header &, Socket::SocketErrno > ErrorCallback; /** diff --git a/src/internet/model/ipv6-address-generator.cc b/src/internet/model/ipv6-address-generator.cc index 715c7b3fd..f25da3326 100644 --- a/src/internet/model/ipv6-address-generator.cc +++ b/src/internet/model/ipv6-address-generator.cc @@ -28,54 +28,163 @@ NS_LOG_COMPONENT_DEFINE ("Ipv6AddressGenerator"); namespace ns3 { +/** + * \internal + * \ingroup address + * + * \brief Implementation class of Ipv6AddressGenerator + * This generator assigns addresses sequentially from a provided + * network address; used in topology code. It also keeps track of all + * addresses assigned to perform duplicate detection. + * + */ class Ipv6AddressGeneratorImpl { public: Ipv6AddressGeneratorImpl (); virtual ~Ipv6AddressGeneratorImpl (); + /** + * \internal + * \brief Initialise the base network and interfaceId for the generator + * + * The first call to NextAddress() or GetAddress() will return the + * value passed in. + * + * \param net The network for the base Ipv6Address + * \param prefix The prefix of the base Ipv6Address + * \param interfaceId The base interface ID used for initialization + */ void Init (const Ipv6Address net, const Ipv6Prefix prefix, const Ipv6Address interfaceId); - Ipv6Address GetNetwork (const Ipv6Prefix prefix) const; + /** + * \internal + * \brief Get the next network according to the given Ipv6Prefix + * + * This operation is a pre-increment, meaning that the internal state + * is changed before returning the new network address. + * + * This also resets the interface ID to the base interface ID that was + * used for initialization. + * + * \param prefix The Ipv6Prefix used to set the next network + * \returns the IPv6 address of the next network + */ Ipv6Address NextNetwork (const Ipv6Prefix prefix); + /** + * \internal + * \brief Get the current network of the given Ipv6Prefix + * + * Does not change the internal state; this just peeks at the current + * network + * + * \param prefix The Ipv6Prefix for the current network + * \returns the IPv6 address of the current network + */ + Ipv6Address GetNetwork (const Ipv6Prefix prefix) const; + + /** + * \internal + * \brief Set the interfaceId for the given Ipv6Prefix + * + * \param interfaceId The interfaceId to set for the current Ipv6Prefix + * \param prefix The Ipv6Prefix whose address is to be set + */ void InitAddress (const Ipv6Address interfaceId, const Ipv6Prefix prefix); + + /** + * \internal + * \brief Get the Ipv6Address that will be allocated upon NextAddress () + * + * Does not change the internal state; just is used to peek the next + * address that will be allocated upon NextAddress () + * + * \param prefix The Ipv6Prefix for the current network + * \returns the IPv6 address + */ Ipv6Address GetAddress (const Ipv6Prefix prefix) const; + + /** + * \internal + * \brief Allocate the next Ipv6Address for the configured network and prefix + * + * This operation is a post-increment, meaning that the first address + * allocated will be the one that was initially configured. + * + * \param prefix The Ipv6Prefix for the current network + * \returns the IPv6 address + */ Ipv6Address NextAddress (const Ipv6Prefix prefix); + /** + * \internal + * \brief Reset the networks and Ipv6Address to zero + */ void Reset (void); + + /** + * \internal + * \brief Add the Ipv6Address to the list of IPv6 entries + * + * Typically, this is used by external address allocators that want + * to make use of this class's ability to track duplicates. AddAllocated + * is always called internally for any address generated by NextAddress () + * + * \param addr The Ipv6Address to be added to the list of Ipv6 entries + * \returns true on success + */ bool AddAllocated (const Ipv6Address addr); + /** + * \internal + * \brief Used to turn off fatal errors and assertions, for testing + */ void TestMode (void); -private: - static const uint32_t N_BITS = 128; - static const uint32_t MOST_SIGNIFICANT_BIT = 0x80; +private: + static const uint32_t N_BITS = 128; //!< /internal the number of bits in the address + static const uint32_t MOST_SIGNIFICANT_BIT = 0x80; //!< /internal MSB set to 1 + + /** + * \internal + * \brief Create an index number for the prefix + * \param prefix the prefix to index + * \returns an index + */ uint32_t PrefixToIndex (Ipv6Prefix prefix) const; + /** + * \internal + * \brief This class holds the state for a given network + */ class NetworkState { public: - uint8_t prefix[16]; - uint32_t shift; - uint8_t network[16]; - uint8_t addr[16]; - uint8_t addrMax[16]; + uint8_t prefix[16]; //!< /internal the network prefix + uint32_t shift; //!< /internal a shift + uint8_t network[16]; //!< /internal the network + uint8_t addr[16]; //!< /internal the address + uint8_t addrMax[16]; //!< /internal the maximum address }; - NetworkState m_netTable[N_BITS]; + NetworkState m_netTable[N_BITS]; //!< /internal the available networks + /** + * \internal + * \brief This class holds the allocated addresses + */ class Entry { public: - uint8_t addrLow[16]; - uint8_t addrHigh[16]; + uint8_t addrLow[16]; //!< /internal the lowest allocated address + uint8_t addrHigh[16]; //!< /internal the highest allocated address }; - std::list m_entries; - Ipv6Address m_base; - bool m_test; + std::list m_entries; //!< /internal contained of allocated addresses + Ipv6Address m_base; //!< /internal base address + bool m_test; //!< /internal test mode (if true) }; Ipv6AddressGeneratorImpl::Ipv6AddressGeneratorImpl () diff --git a/src/internet/model/ipv6-address-generator.h b/src/internet/model/ipv6-address-generator.h index 5695cd7a2..94e219b25 100644 --- a/src/internet/model/ipv6-address-generator.h +++ b/src/internet/model/ipv6-address-generator.h @@ -50,6 +50,12 @@ namespace ns3 { * The interface ID is often an EUI-64 address derived from the MAC address, * but can also be a pseudo-random value (\RFC{3041}). This implementation * does not generate EUI-64-based interface IDs. + * + * BEWARE: this class acts as a Singleton. + * In other terms, two different instances of Ipv6AddressGenerator will + * pick IPv6 numbers from the same pool. Changing the network in one of them + * will also change the network in the other instances. + * */ class Ipv6AddressGenerator { @@ -68,7 +74,7 @@ public: const Ipv6Address interfaceId = "::1"); /** - * \brief Get the next network acoording to the given Ipv6Prefix + * \brief Get the next network according to the given Ipv6Prefix * * This operation is a pre-increment, meaning that the internal state * is changed before returning the new network address. @@ -77,6 +83,7 @@ public: * used for initialization. * * \param prefix The Ipv6Prefix used to set the next network + * \returns the IPv6 address of the next network */ static Ipv6Address NextNetwork (const Ipv6Prefix prefix); @@ -87,6 +94,7 @@ public: * network * * \param prefix The Ipv6Prefix for the current network + * \returns the IPv6 address of the current network */ static Ipv6Address GetNetwork (const Ipv6Prefix prefix); @@ -103,18 +111,20 @@ public: * * This operation is a post-increment, meaning that the first address * allocated will be the one that was initially configured. - * . + * * \param prefix The Ipv6Prefix for the current network + * \returns the IPv6 address */ static Ipv6Address NextAddress (const Ipv6Prefix prefix); /** - * \brief Get the Ipv6Address that will be allocated upon NextAddress() + * \brief Get the Ipv6Address that will be allocated upon NextAddress () * * Does not change the internal state; just is used to peek the next * address that will be allocated upon NextAddress () * * \param prefix The Ipv6Prefix for the current network + * \returns the IPv6 address */ static Ipv6Address GetAddress (const Ipv6Prefix prefix); @@ -128,9 +138,10 @@ public: * * Typically, this is used by external address allocators that want * to make use of this class's ability to track duplicates. AddAllocated - * is always called internally for any address generated by NextAddress() + * is always called internally for any address generated by NextAddress () * * \param addr The Ipv6Address to be added to the list of Ipv6 entries + * \returns true on success */ static bool AddAllocated (const Ipv6Address addr); diff --git a/src/internet/model/ipv6-end-point-demux.h b/src/internet/model/ipv6-end-point-demux.h index db7ee6748..ebfec4fd1 100644 --- a/src/internet/model/ipv6-end-point-demux.h +++ b/src/internet/model/ipv6-end-point-demux.h @@ -37,7 +37,14 @@ class Ipv6EndPoint; class Ipv6EndPointDemux { public: + /** + * \brief Container of the IPv6 endpoints. + */ typedef std::listEndPoints; + + /** + * \brief Iterator to the container of the IPv6 endpoints. + */ typedef std::list::iterator EndPointsI; /** diff --git a/src/internet/model/ipv6-end-point.h b/src/internet/model/ipv6-end-point.h index 9fc8d951a..ad2de7d9b 100644 --- a/src/internet/model/ipv6-end-point.h +++ b/src/internet/model/ipv6-end-point.h @@ -149,8 +149,7 @@ public: /** * \brief Forward the packet to the upper level. * \param p the packet - * \param srcAddr source address - * \param dstAddr source address + * \param header the packet header * \param port source port */ void ForwardUp (Ptr p, Ipv6Header header, uint16_t port); @@ -171,8 +170,7 @@ private: /** * \brief ForwardUp wrapper. * \param p packet - * \param saddr source IPv6 address - * \param daddr dest IPv6 address + * \param header the packet header * \param sport source port */ void DoForwardUp (Ptr p, Ipv6Header header, uint16_t sport); diff --git a/src/internet/model/ipv6-extension-demux.h b/src/internet/model/ipv6-extension-demux.h index 5ed9025ed..9e274747c 100644 --- a/src/internet/model/ipv6-extension-demux.h +++ b/src/internet/model/ipv6-extension-demux.h @@ -86,6 +86,10 @@ protected: virtual void DoDispose (); private: + + /** + * \brief Container of the IPv6 Extensions. + */ typedef std::list > Ipv6ExtensionList_t; /** diff --git a/src/internet/model/ipv6-extension-header.h b/src/internet/model/ipv6-extension-header.h index 0bba77324..f311d99c6 100644 --- a/src/internet/model/ipv6-extension-header.h +++ b/src/internet/model/ipv6-extension-header.h @@ -196,6 +196,7 @@ private: /** * \brief Calculate padding. * \param alignment alignment + * \return the number of pad bytes */ uint32_t CalculatePad (Ipv6OptionHeader::Alignment alignment) const; diff --git a/src/internet/model/ipv6-extension.h b/src/internet/model/ipv6-extension.h index 07d09190d..ec01d5893 100755 --- a/src/internet/model/ipv6-extension.h +++ b/src/internet/model/ipv6-extension.h @@ -381,7 +381,6 @@ private: * \brief Process the timeout for packet fragments * \param key representing the packet fragments * \param ipHeader the IP header of the original packet - * \param iif Input Interface */ void HandleFragmentsTimeout (std::pair key, Ipv6Header & ipHeader); @@ -401,6 +400,9 @@ private: */ void CancelTimeout (); + /** + * \brief Container for the packet fragments. + */ typedef std::map, Ptr > MapFragments_t; /** @@ -521,6 +523,9 @@ protected: virtual void DoDispose (); private: + /** + * \brief Container for the extension routing. + */ typedef std::list > Ipv6ExtensionRoutingList_t; /** diff --git a/src/internet/model/ipv6-interface-address.h b/src/internet/model/ipv6-interface-address.h index 6efc7497f..68f8bc7ff 100644 --- a/src/internet/model/ipv6-interface-address.h +++ b/src/internet/model/ipv6-interface-address.h @@ -179,7 +179,22 @@ private: */ Scope_e m_scope; + /** + * \brief Equal to operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operands are equal + */ friend bool operator == (Ipv6InterfaceAddress const& a, Ipv6InterfaceAddress const& b); + + /** + * \brief Not equal to operator. + * + * \param a the first operand + * \param b the first operand + * \returns true if the operands are not equal + */ friend bool operator != (Ipv6InterfaceAddress const& a, Ipv6InterfaceAddress const& b); /** @@ -188,6 +203,13 @@ private: uint32_t m_nsDadUid; }; +/** + * \brief Stream insertion operator. + * + * \param os the reference to the output stream + * \param addr the Ipv6InterfaceAddress + * \returns the reference to the output stream + */ std::ostream& operator<< (std::ostream& os, const Ipv6InterfaceAddress &addr); /* follow Ipv4InterfaceAddress way, maybe not inline them */ diff --git a/src/internet/model/ipv6-interface.h b/src/internet/model/ipv6-interface.h index 6b309463b..8426e62b8 100644 --- a/src/internet/model/ipv6-interface.h +++ b/src/internet/model/ipv6-interface.h @@ -257,8 +257,19 @@ protected: virtual void DoDispose (); private: + /** + * \brief Container for the Ipv6InterfaceAddresses. + */ typedef std::list Ipv6InterfaceAddressList; + + /** + * \brief Container Iterator for the Ipv6InterfaceAddresses. + */ typedef std::list::iterator Ipv6InterfaceAddressListI; + + /** + * \brief Const Container Itareator for the Ipv6InterfaceAddresses. + */ typedef std::list::const_iterator Ipv6InterfaceAddressListCI; /** diff --git a/src/internet/model/ipv6-l3-protocol.h b/src/internet/model/ipv6-l3-protocol.h index e6118e103..8e162c880 100644 --- a/src/internet/model/ipv6-l3-protocol.h +++ b/src/internet/model/ipv6-l3-protocol.h @@ -217,6 +217,7 @@ public: /** * \brief Get interface index which is on a specified net device. * \param device net device + * \returns the interface index */ int32_t GetInterfaceForDevice (Ptr device) const; @@ -224,6 +225,7 @@ public: * \brief Add an address on interface. * \param i interface index * \param address to add + * \returns true if the operation succeeded */ bool AddAddress (uint32_t i, Ipv6InterfaceAddress address); @@ -246,6 +248,7 @@ public: * \brief Remove an address from an interface. * \param interfaceIndex interface index * \param addressIndex address index on the interface + * \returns true if the operation succeeded */ bool RemoveAddress (uint32_t interfaceIndex, uint32_t addressIndex); @@ -255,7 +258,7 @@ public: * \param address Ipv6Address to be removed from the interface * \returns true if the operation succeeded */ - bool RemoveAddress (uint32_t interface, Ipv6Address address); + bool RemoveAddress (uint32_t interfaceIndex, Ipv6Address address); /** * \brief Set metric for an interface. @@ -288,6 +291,7 @@ public: /** * \brief Is specified interface up ? * \param i interface index + * \returns true if the interface is up */ bool IsUp (uint32_t i) const; @@ -306,6 +310,7 @@ public: /** * \brief Is interface allows forwarding ? * \param i interface index + * \returns true if the interface is forwarding */ bool IsForwarding (uint32_t i) const; @@ -380,11 +385,29 @@ private: friend class Ipv6L3ProtocolTestCase; friend class Ipv6ExtensionLooseRouting; + /** + * \brief Container of the IPv6 Interfaces. + */ typedef std::list > Ipv6InterfaceList; + + /** + * \brief Container of the IPv6 Raw Sockets. + */ typedef std::list > SocketList; + + /** + * \brief Container of the IPv6 L4 instances. + */ typedef std::list > L4List_t; + /** + * \brief Container of the IPv6 Autoconfigured addresses. + */ typedef std::list< Ptr > Ipv6AutoconfiguredPrefixList; + + /** + * \brief Iterator of the container of the IPv6 Autoconfigured addresses. + */ typedef std::list< Ptr >::iterator Ipv6AutoconfiguredPrefixListI; /** @@ -411,6 +434,7 @@ private: /** * \brief Copy constructor. * \param o object to copy + * \returns the copied object */ Ipv6L3Protocol &operator = (const Ipv6L3Protocol& o); @@ -421,6 +445,7 @@ private: * \param protocol L4 protocol * \param payloadSize payload size * \param hopLimit Hop limit + * \param tclass Tclass * \return newly created IPv6 header */ Ipv6Header BuildHeader (Ipv6Address src, Ipv6Address dst, uint8_t protocol, diff --git a/src/internet/model/ipv6-list-routing.h b/src/internet/model/ipv6-list-routing.h index 29ed332ff..43c542fe6 100644 --- a/src/internet/model/ipv6-list-routing.h +++ b/src/internet/model/ipv6-list-routing.h @@ -118,7 +118,14 @@ protected: virtual void DoDispose (void); private: + /** + * \brief Container identifying an IPv6 Routing Protocol entry in the list. + */ typedef std::pair > Ipv6RoutingProtocolEntry; + + /** + * \brief Container of the IPv6 Routing Protocols. + */ typedef std::list Ipv6RoutingProtocolList; /** diff --git a/src/internet/model/ipv6-option-demux.h b/src/internet/model/ipv6-option-demux.h index e1e4a603e..5e8103cf0 100644 --- a/src/internet/model/ipv6-option-demux.h +++ b/src/internet/model/ipv6-option-demux.h @@ -86,6 +86,9 @@ protected: virtual void DoDispose (); private: + /** + * \brief Container of the IPv6 Options types. + */ typedef std::list > Ipv6OptionList_t; /** diff --git a/src/internet/model/ipv6-packet-info-tag.h b/src/internet/model/ipv6-packet-info-tag.h index 943e72280..5c3a8410e 100644 --- a/src/internet/model/ipv6-packet-info-tag.h +++ b/src/internet/model/ipv6-packet-info-tag.h @@ -45,22 +45,70 @@ class Ipv6PacketInfoTag : public Tag { public: Ipv6PacketInfoTag (); - // Implemented, but not used in the stack yet + + /** + * \brief Get the type ID. + * \return the object TypeId + */ + static TypeId GetTypeId (void); + + /** + * \brief Set the tag's address + * + * \param addr the address + */ void SetAddress (Ipv6Address addr); - // Implemented, but not used in the stack yet + + /** + * \brief Get the tag's address + * + * \returns the address + */ Ipv6Address GetAddress (void) const; + + /** + * \brief Set the tag's receiving interface + * + * \param ifindex the interface index + */ void SetRecvIf (uint32_t ifindex); + + /** + * \brief Get the tag's receiving interface + * + * \returns the interface index + */ uint32_t GetRecvIf (void) const; - // Implemented, but not used in the stack yet + + /** + * \brief Set the tag's Hop Limit + * + * \param ttl the hop limit + */ void SetHoplimit (uint8_t ttl); - // Implemented, but not used in the stack yet + + /** + * \brief Get the tag's Hop Limit + * + * \returns the Hop Limit + */ uint8_t GetHoplimit (void) const; - // Implemented, but not used in the stack yet + + /** + * \brief Set the tag's Traffic Class + * + * \param tclass the Traffic Class + */ void SetTrafficClass (uint8_t tclass); - // Implemented, but not used in the stack yet + + /** + * \brief Get the tag's Traffic Class + * + * \returns the Traffic Class + */ uint8_t GetTrafficClass (void) const; - static TypeId GetTypeId (void); + // inherited functions, no doc necessary virtual TypeId GetInstanceTypeId (void) const; virtual uint32_t GetSerializedSize (void) const; virtual void Serialize (TagBuffer i) const; @@ -83,10 +131,10 @@ private: * 3. the arriving hop limit, and * 4. the arriving traffic class value. */ - Ipv6Address m_addr; - uint8_t m_ifindex; - uint8_t m_hoplimit; - uint8_t m_tclass; + Ipv6Address m_addr; //!< the packet address (src or dst) + uint8_t m_ifindex; //!< the Interface index + uint8_t m_hoplimit; //!< the Hop Limit + uint8_t m_tclass; //!< the Traffic Class }; } // namespace ns3 diff --git a/src/internet/model/ipv6-packet-probe.h b/src/internet/model/ipv6-packet-probe.h index 2808f5731..20f5b3521 100644 --- a/src/internet/model/ipv6-packet-probe.h +++ b/src/internet/model/ipv6-packet-probe.h @@ -48,7 +48,12 @@ namespace ns3 { class Ipv6PacketProbe : public Probe { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (); + Ipv6PacketProbe (); virtual ~Ipv6PacketProbe (); @@ -103,7 +108,9 @@ private: */ void TraceSink (Ptr packet, Ptr ipv6, uint32_t interface); + /// Traced Callback: the packet, the Ipv6 object and the interface. TracedCallback, Ptr, uint32_t> m_output; + /// Traced Callback: the previous packet's size and the actual packet's size. TracedCallback m_outputBytes; /// The traced packet. diff --git a/src/internet/model/ipv6-pmtu-cache.h b/src/internet/model/ipv6-pmtu-cache.h index be78bbc2c..173231371 100644 --- a/src/internet/model/ipv6-pmtu-cache.h +++ b/src/internet/model/ipv6-pmtu-cache.h @@ -108,7 +108,11 @@ private: */ std::map m_pathMtu; + /** + * \brief Container of the IPv6 PMTU data (Ipv6 destination address and expiration event). + */ typedef std::map ::iterator pathMtuTimerIter; + /** * \brief Path MTU Expiration table */ diff --git a/src/internet/model/ipv6-raw-socket-impl.h b/src/internet/model/ipv6-raw-socket-impl.h index 4684e1c38..302f5034c 100644 --- a/src/internet/model/ipv6-raw-socket-impl.h +++ b/src/internet/model/ipv6-raw-socket-impl.h @@ -232,26 +232,26 @@ public: /** * \brief Set the filter to pass one ICMPv6 type - * \param the ICMPv6 type to pass + * \param type the ICMPv6 type to pass */ void Icmpv6FilterSetPass(uint8_t type); /** * \brief Set the filter to block one ICMPv6 type - * \param the ICMPv6 type to block + * \param type the ICMPv6 type to block */ void Icmpv6FilterSetBlock(uint8_t type); /** * \brief Ask the filter about the status of one ICMPv6 type - * \param the ICMPv6 type + * \param type the ICMPv6 type * \return true if the ICMP type is passing through */ bool Icmpv6FilterWillPass(uint8_t type); /** * \brief Ask the filter about the status of one ICMPv6 type - * \param the ICMPv6 type + * \param type the ICMPv6 type * \return true if the ICMP type is being blocked */ bool Icmpv6FilterWillBlock(uint8_t type); @@ -319,7 +319,7 @@ private: */ typedef struct { - uint32_t icmpv6Filt[8]; + uint32_t icmpv6Filt[8]; //!< ICMPv6 filter specification } icmpv6Filter; /** diff --git a/src/internet/model/ipv6-route.h b/src/internet/model/ipv6-route.h index d1e674787..c16d8ffc7 100644 --- a/src/internet/model/ipv6-route.h +++ b/src/internet/model/ipv6-route.h @@ -123,6 +123,13 @@ private: Ptr m_outputDevice; }; +/** + * \brief Stream insertion operator. + * + * \param os the reference to the output stream + * \param route the Ipv6 route + * \returns the reference to the output stream + */ std::ostream& operator<< (std::ostream& os, Ipv6Route const& route); /** @@ -231,6 +238,13 @@ private: std::map m_ttls; }; +/** + * \brief Stream insertion operator. + * + * \param os the reference to the output stream + * \param route the Ipv6 multicast route + * \returns the reference to the output stream + */ std::ostream& operator<< (std::ostream& os, Ipv6MulticastRoute const& route); } /* namespace ns3 */ diff --git a/src/internet/model/ipv6-routing-protocol.h b/src/internet/model/ipv6-routing-protocol.h index b1cb9785a..9f4676c70 100644 --- a/src/internet/model/ipv6-routing-protocol.h +++ b/src/internet/model/ipv6-routing-protocol.h @@ -54,11 +54,22 @@ class NetDevice; class Ipv6RoutingProtocol : public Object { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); + /// Callback for unicast packets to be forwarded typedef Callback, Ptr, Ptr, const Ipv6Header &> UnicastForwardCallback; + + /// Callback for multicast packets to be forwarded typedef Callback, Ptr, Ptr, const Ipv6Header &> MulticastForwardCallback; + + /// Callback for packets to be locally delivered typedef Callback, const Ipv6Header &, uint32_t > LocalDeliverCallback; + + /// Callback for routing errors (e.g., no route found) typedef Callback, const Ipv6Header &, Socket::SocketErrno > ErrorCallback; /** diff --git a/src/internet/model/ipv6-routing-table-entry.h b/src/internet/model/ipv6-routing-table-entry.h index 84c9a720e..05ee0afa4 100644 --- a/src/internet/model/ipv6-routing-table-entry.h +++ b/src/internet/model/ipv6-routing-table-entry.h @@ -260,6 +260,13 @@ private: }; +/** +* \brief Stream insertion operator. +* +* \param os the reference to the output stream +* \param route the Ipv6 routing table entry +* \returns the reference to the output stream +*/ std::ostream& operator<< (std::ostream& os, Ipv6RoutingTableEntry const& route); /** @@ -364,6 +371,13 @@ private: std::vector m_outputInterfaces; }; +/** +* \brief Stream insertion operator. +* +* \param os the reference to the output stream +* \param route the Ipv6 multicast routing table entry +* \returns the reference to the output stream +*/ std::ostream& operator<< (std::ostream& os, Ipv6MulticastRoutingTableEntry const& route); } /* namespace ns3 */ diff --git a/src/internet/model/ipv6-static-routing.h b/src/internet/model/ipv6-static-routing.h index 85b5cd779..d17c04a18 100644 --- a/src/internet/model/ipv6-static-routing.h +++ b/src/internet/model/ipv6-static-routing.h @@ -205,6 +205,7 @@ public: * \param origin IPv6 address of the source * \param group the multicast group address. * \param inputInterface the input interface index + * \return true on success */ bool RemoveMulticastRoute (Ipv6Address origin, Ipv6Address group, uint32_t inputInterface); @@ -250,12 +251,22 @@ protected: virtual void DoDispose (); private: + /// Container for the network routes typedef std::list > NetworkRoutes; + + /// Const Iterator for container for the network routes typedef std::list >::const_iterator NetworkRoutesCI; + + /// Iterator for container for the network routes typedef std::list >::iterator NetworkRoutesI; + /// Container for the multicast routes typedef std::list MulticastRoutes; + + /// Const Iterator for container for the multicast routes typedef std::list::const_iterator MulticastRoutesCI; + + /// Iterator for container for the multicast routes typedef std::list::iterator MulticastRoutesI; /** diff --git a/src/internet/model/ipv6.h b/src/internet/model/ipv6.h index a108ee522..afc450b3f 100644 --- a/src/internet/model/ipv6.h +++ b/src/internet/model/ipv6.h @@ -79,6 +79,10 @@ class Ipv6RoutingProtocol; class Ipv6 : public Object { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); /** diff --git a/src/internet/model/tcp-header.h b/src/internet/model/tcp-header.h index 56b5ac02f..722510dbb 100644 --- a/src/internet/model/tcp-header.h +++ b/src/internet/model/tcp-header.h @@ -122,22 +122,55 @@ public: uint16_t GetUrgentPointer () const; /** - * \param source the ip source to use in the underlying - * ip packet. - * \param destination the ip destination to use in the - * underlying ip packet. - * \param protocol the protocol number to use in the underlying - * ip packet. + * \brief Initialize the TCP checksum. * * If you want to use tcp checksums, you should call this * method prior to adding the header to a packet. + * + * \param source the IP source to use in the underlying + * IP packet. + * \param destination the IP destination to use in the + * underlying IP packet. + * \param protocol the protocol number to use in the underlying + * IP packet. + * */ void InitializeChecksum (Ipv4Address source, Ipv4Address destination, uint8_t protocol); + + /** + * \brief Initialize the TCP checksum. + * + * If you want to use tcp checksums, you should call this + * method prior to adding the header to a packet. + * + * \param source the IP source to use in the underlying + * IP packet. + * \param destination the IP destination to use in the + * underlying IP packet. + * \param protocol the protocol number to use in the underlying + * IP packet. + * + */ void InitializeChecksum (Ipv6Address source, Ipv6Address destination, uint8_t protocol); + + /** + * \brief Initialize the TCP checksum. + * + * If you want to use tcp checksums, you should call this + * method prior to adding the header to a packet. + * + * \param source the IP source to use in the underlying + * IP packet. + * \param destination the IP destination to use in the + * underlying IP packet. + * \param protocol the protocol number to use in the underlying + * IP packet. + * + */ void InitializeChecksum (Address source, Address destination, uint8_t protocol); diff --git a/src/internet/model/tcp-socket-base.cc b/src/internet/model/tcp-socket-base.cc index 87c641396..8958a8d42 100644 --- a/src/internet/model/tcp-socket-base.cc +++ b/src/internet/model/tcp-socket-base.cc @@ -210,42 +210,42 @@ TcpSocketBase::~TcpSocketBase (void) CancelAllTimers (); } -/** Associate a node with this TCP socket */ +/* Associate a node with this TCP socket */ void TcpSocketBase::SetNode (Ptr node) { m_node = node; } -/** Associate the L4 protocol (e.g. mux/demux) with this socket */ +/* Associate the L4 protocol (e.g. mux/demux) with this socket */ void TcpSocketBase::SetTcp (Ptr tcp) { m_tcp = tcp; } -/** Set an RTT estimator with this socket */ +/* Set an RTT estimator with this socket */ void TcpSocketBase::SetRtt (Ptr rtt) { m_rtt = rtt; } -/** Inherit from Socket class: Returns error code */ +/* Inherit from Socket class: Returns error code */ enum Socket::SocketErrno TcpSocketBase::GetErrno (void) const { return m_errno; } -/** Inherit from Socket class: Returns socket type, NS3_SOCK_STREAM */ +/* Inherit from Socket class: Returns socket type, NS3_SOCK_STREAM */ enum Socket::SocketType TcpSocketBase::GetSocketType (void) const { return NS3_SOCK_STREAM; } -/** Inherit from Socket class: Returns associated node */ +/* Inherit from Socket class: Returns associated node */ Ptr TcpSocketBase::GetNode (void) const { @@ -253,7 +253,7 @@ TcpSocketBase::GetNode (void) const return m_node; } -/** Inherit from Socket class: Bind socket to an end-point in TcpL4Protocol */ +/* Inherit from Socket class: Bind socket to an end-point in TcpL4Protocol */ int TcpSocketBase::Bind (void) { @@ -282,7 +282,7 @@ TcpSocketBase::Bind6 (void) return SetupCallback (); } -/** Inherit from Socket class: Bind socket (with specific address) to an end-point in TcpL4Protocol */ +/* Inherit from Socket class: Bind socket (with specific address) to an end-point in TcpL4Protocol */ int TcpSocketBase::Bind (const Address &address) { @@ -352,7 +352,7 @@ TcpSocketBase::Bind (const Address &address) return SetupCallback (); } -/** Inherit from Socket class: Initiate connection to a remote address:port */ +/* Inherit from Socket class: Initiate connection to a remote address:port */ int TcpSocketBase::Connect (const Address & address) { @@ -424,7 +424,7 @@ TcpSocketBase::Connect (const Address & address) return DoConnect (); } -/** Inherit from Socket class: Listen on the endpoint for an incoming connection */ +/* Inherit from Socket class: Listen on the endpoint for an incoming connection */ int TcpSocketBase::Listen (void) { @@ -441,7 +441,7 @@ TcpSocketBase::Listen (void) return 0; } -/** Inherit from Socket class: Kill this socket and signal the peer (if any) */ +/* Inherit from Socket class: Kill this socket and signal the peer (if any) */ int TcpSocketBase::Close (void) { @@ -468,7 +468,7 @@ TcpSocketBase::Close (void) return DoClose (); } -/** Inherit from Socket class: Signal a termination of send */ +/* Inherit from Socket class: Signal a termination of send */ int TcpSocketBase::ShutdownSend (void) { @@ -502,7 +502,7 @@ TcpSocketBase::ShutdownSend (void) return 0; } -/** Inherit from Socket class: Signal a termination of receive */ +/* Inherit from Socket class: Signal a termination of receive */ int TcpSocketBase::ShutdownRecv (void) { @@ -511,7 +511,7 @@ TcpSocketBase::ShutdownRecv (void) return 0; } -/** Inherit from Socket class: Send a packet. Parameter flags is not used. +/* Inherit from Socket class: Send a packet. Parameter flags is not used. Packet has no TCP header. Invoked by upper-layer application */ int TcpSocketBase::Send (Ptr p, uint32_t flags) @@ -546,15 +546,15 @@ TcpSocketBase::Send (Ptr p, uint32_t flags) } } -/** Inherit from Socket class: In TcpSocketBase, it is same as Send() call */ +/* Inherit from Socket class: In TcpSocketBase, it is same as Send() call */ int TcpSocketBase::SendTo (Ptr p, uint32_t flags, const Address &address) { return Send (p, flags); // SendTo() and Send() are the same } -/** Inherit from Socket class: Return data to upper-layer application. Parameter flags - is not used. Data is returned as a packet of size no larger than maxSize */ +/* Inherit from Socket class: Return data to upper-layer application. Parameter flags + is not used. Data is returned as a packet of size no larger than maxSize */ Ptr TcpSocketBase::Recv (uint32_t maxSize, uint32_t flags) { @@ -581,7 +581,7 @@ TcpSocketBase::Recv (uint32_t maxSize, uint32_t flags) return outPacket; } -/** Inherit from Socket class: Recv and return the remote's address */ +/* Inherit from Socket class: Recv and return the remote's address */ Ptr TcpSocketBase::RecvFrom (uint32_t maxSize, uint32_t flags, Address &fromAddress) { @@ -606,7 +606,7 @@ TcpSocketBase::RecvFrom (uint32_t maxSize, uint32_t flags, Address &fromAddress) return packet; } -/** Inherit from Socket class: Get the max number of bytes an app can send */ +/* Inherit from Socket class: Get the max number of bytes an app can send */ uint32_t TcpSocketBase::GetTxAvailable (void) const { @@ -614,7 +614,7 @@ TcpSocketBase::GetTxAvailable (void) const return m_txBuffer.Available (); } -/** Inherit from Socket class: Get the max number of bytes an app can read */ +/* Inherit from Socket class: Get the max number of bytes an app can read */ uint32_t TcpSocketBase::GetRxAvailable (void) const { @@ -622,7 +622,7 @@ TcpSocketBase::GetRxAvailable (void) const return m_rxBuffer.Available (); } -/** Inherit from Socket class: Return local address:port */ +/* Inherit from Socket class: Return local address:port */ int TcpSocketBase::GetSockName (Address &address) const { @@ -644,7 +644,7 @@ TcpSocketBase::GetSockName (Address &address) const return 0; } -/** Inherit from Socket class: Bind this socket to the specified NetDevice */ +/* Inherit from Socket class: Bind this socket to the specified NetDevice */ void TcpSocketBase::BindToNetDevice (Ptr netdevice) { @@ -668,7 +668,7 @@ TcpSocketBase::BindToNetDevice (Ptr netdevice) return; } -/** Clean up after Bind. Set up callback functions in the end-point. */ +/* Clean up after Bind. Set up callback functions in the end-point. */ int TcpSocketBase::SetupCallback (void) { @@ -694,7 +694,7 @@ TcpSocketBase::SetupCallback (void) return 0; } -/** Perform the real connection tasks: Send SYN if allowed, RST if invalid */ +/* Perform the real connection tasks: Send SYN if allowed, RST if invalid */ int TcpSocketBase::DoConnect (void) { @@ -716,7 +716,7 @@ TcpSocketBase::DoConnect (void) return 0; } -/** Do the action to close the socket. Usually send a packet with appropriate +/* Do the action to close the socket. Usually send a packet with appropriate flags depended on the current m_state. */ int TcpSocketBase::DoClose (void) @@ -759,7 +759,7 @@ TcpSocketBase::DoClose (void) return 0; } -/** Peacefully close the socket by notifying the upper layer and deallocate end point */ +/* Peacefully close the socket by notifying the upper layer and deallocate end point */ void TcpSocketBase::CloseAndNotify (void) { @@ -780,7 +780,7 @@ TcpSocketBase::CloseAndNotify (void) } -/** Tell if a sequence number range is out side the range that my rx buffer can +/* Tell if a sequence number range is out side the range that my rx buffer can accpet */ bool TcpSocketBase::OutOfRange (SequenceNumber32 head, SequenceNumber32 tail) const @@ -799,7 +799,7 @@ TcpSocketBase::OutOfRange (SequenceNumber32 head, SequenceNumber32 tail) const return (tail < m_rxBuffer.NextRxSequence () || m_rxBuffer.MaxRxSequence () <= head); } -/** Function called by the L3 protocol when it received a packet to pass on to +/* Function called by the L3 protocol when it received a packet to pass on to the TCP. This function is registered as the "RxCallback" function in SetupCallback(), which invoked by Bind(), and CompleteFork() */ void @@ -841,7 +841,7 @@ TcpSocketBase::ForwardIcmp6 (Ipv6Address icmpSource, uint8_t icmpTtl, } } -/** The real function to handle the incoming packet from lower layers. This is +/* The real function to handle the incoming packet from lower layers. This is wrapped by ForwardUp() so that this function can be overloaded by daughter classes. */ void @@ -1035,7 +1035,7 @@ TcpSocketBase::DoForwardUp (Ptr packet, Ipv6Header header, uint16_t port } } -/** Received a packet upon ESTABLISHED state. This function is mimicking the +/* Received a packet upon ESTABLISHED state. This function is mimicking the role of tcp_rcv_established() in tcp_input.c in Linux kernel. */ void TcpSocketBase::ProcessEstablished (Ptr packet, const TcpHeader& tcpHeader) @@ -1081,7 +1081,7 @@ TcpSocketBase::ProcessEstablished (Ptr packet, const TcpHeader& tcpHeade } } -/** Process the newly received ACK */ +/* Process the newly received ACK */ void TcpSocketBase::ReceivedAck (Ptr packet, const TcpHeader& tcpHeader) { @@ -1118,7 +1118,7 @@ TcpSocketBase::ReceivedAck (Ptr packet, const TcpHeader& tcpHeader) } } -/** Received a packet upon LISTEN state. */ +/* Received a packet upon LISTEN state. */ void TcpSocketBase::ProcessListen (Ptr packet, const TcpHeader& tcpHeader, const Address& fromAddress, const Address& toAddress) @@ -1148,7 +1148,7 @@ TcpSocketBase::ProcessListen (Ptr packet, const TcpHeader& tcpHeader, packet, tcpHeader, fromAddress, toAddress); } -/** Received a packet upon SYN_SENT */ +/* Received a packet upon SYN_SENT */ void TcpSocketBase::ProcessSynSent (Ptr packet, const TcpHeader& tcpHeader) { @@ -1206,7 +1206,7 @@ TcpSocketBase::ProcessSynSent (Ptr packet, const TcpHeader& tcpHeader) } } -/** Received a packet upon SYN_RCVD */ +/* Received a packet upon SYN_RCVD */ void TcpSocketBase::ProcessSynRcvd (Ptr packet, const TcpHeader& tcpHeader, const Address& fromAddress, const Address& toAddress) @@ -1296,7 +1296,7 @@ TcpSocketBase::ProcessSynRcvd (Ptr packet, const TcpHeader& tcpHeader, } } -/** Received a packet upon CLOSE_WAIT, FIN_WAIT_1, or FIN_WAIT_2 states */ +/* Received a packet upon CLOSE_WAIT, FIN_WAIT_1, or FIN_WAIT_2 states */ void TcpSocketBase::ProcessWait (Ptr packet, const TcpHeader& tcpHeader) { @@ -1367,7 +1367,7 @@ TcpSocketBase::ProcessWait (Ptr packet, const TcpHeader& tcpHeader) } } -/** Received a packet upon CLOSING */ +/* Received a packet upon CLOSING */ void TcpSocketBase::ProcessClosing (Ptr packet, const TcpHeader& tcpHeader) { @@ -1399,7 +1399,7 @@ TcpSocketBase::ProcessClosing (Ptr packet, const TcpHeader& tcpHeader) } } -/** Received a packet upon LAST_ACK */ +/* Received a packet upon LAST_ACK */ void TcpSocketBase::ProcessLastAck (Ptr packet, const TcpHeader& tcpHeader) { @@ -1435,7 +1435,7 @@ TcpSocketBase::ProcessLastAck (Ptr packet, const TcpHeader& tcpHeader) } } -/** Peer sent me a FIN. Remember its sequence in rx buffer. */ +/* Peer sent me a FIN. Remember its sequence in rx buffer. */ void TcpSocketBase::PeerClose (Ptr p, const TcpHeader& tcpHeader) { @@ -1472,7 +1472,7 @@ TcpSocketBase::PeerClose (Ptr p, const TcpHeader& tcpHeader) DoPeerClose (); // Change state, respond with ACK } -/** Received a in-sequence FIN. Close down this socket. */ +/* Received a in-sequence FIN. Close down this socket. */ void TcpSocketBase::DoPeerClose (void) { @@ -1510,7 +1510,7 @@ TcpSocketBase::DoPeerClose (void) } } -/** Kill this socket. This is a callback function configured to m_endpoint in +/* Kill this socket. This is a callback function configured to m_endpoint in SetupCallback(), invoked when the endpoint is destroyed. */ void TcpSocketBase::Destroy (void) @@ -1531,7 +1531,7 @@ TcpSocketBase::Destroy (void) CancelAllTimers (); } -/** Kill this socket. This is a callback function configured to m_endpoint in +/* Kill this socket. This is a callback function configured to m_endpoint in SetupCallback(), invoked when the endpoint is destroyed. */ void TcpSocketBase::Destroy6 (void) @@ -1552,7 +1552,7 @@ TcpSocketBase::Destroy6 (void) CancelAllTimers (); } -/** Send an empty packet with specified TCP flags */ +/* Send an empty packet with specified TCP flags */ void TcpSocketBase::SendEmptyPacket (uint8_t flags) { @@ -1667,7 +1667,7 @@ TcpSocketBase::SendEmptyPacket (uint8_t flags) } } -/** This function closes the endpoint completely. Called upon RST_TX action. */ +/* This function closes the endpoint completely. Called upon RST_TX action. */ void TcpSocketBase::SendRST (void) { @@ -1677,7 +1677,7 @@ TcpSocketBase::SendRST (void) DeallocateEndPoint (); } -/** Deallocate the end point and cancel all the timers */ +/* Deallocate the end point and cancel all the timers */ void TcpSocketBase::DeallocateEndPoint (void) { @@ -1709,7 +1709,7 @@ TcpSocketBase::DeallocateEndPoint (void) } } -/** Configure the endpoint to a local address. Called by Connect() if Bind() didn't specify one. */ +/* Configure the endpoint to a local address. Called by Connect() if Bind() didn't specify one. */ int TcpSocketBase::SetupEndpoint () { @@ -1770,7 +1770,7 @@ TcpSocketBase::SetupEndpoint6 () return 0; } -/** This function is called only if a SYN received in LISTEN state. After +/* This function is called only if a SYN received in LISTEN state. After TcpSocketBase cloned, allocate a new end point to handle the incoming connection and send a SYN+ACK to complete the handshake. */ void @@ -1820,7 +1820,7 @@ TcpSocketBase::ConnectionSucceeded () } } -/** Extract at most maxSize bytes from the TxBuffer at sequence seq, add the +/* Extract at most maxSize bytes from the TxBuffer at sequence seq, add the TCP header, and send to TcpL4Protocol */ uint32_t TcpSocketBase::SendDataPacket (SequenceNumber32 seq, uint32_t maxSize, bool withAck) @@ -1926,7 +1926,7 @@ TcpSocketBase::SendDataPacket (SequenceNumber32 seq, uint32_t maxSize, bool with return sz; } -/** Send as much pending data as possible according to the Tx window. Note that +/* Send as much pending data as possible according to the Tx window. Note that * this function did not implement the PSH flag */ bool @@ -2071,7 +2071,7 @@ TcpSocketBase::ReceivedData (Ptr p, const TcpHeader& tcpHeader) } } -/** Called by ForwardUp() to estimate RTT */ +/* Called by ForwardUp() to estimate RTT */ void TcpSocketBase::EstimateRtt (const TcpHeader& tcpHeader) { @@ -2281,7 +2281,7 @@ TcpSocketBase::CancelAllTimers () m_timewaitEvent.Cancel (); } -/** Move TCP to Time_Wait state and schedule a transition to Closed state */ +/* Move TCP to Time_Wait state and schedule a transition to Closed state */ void TcpSocketBase::TimeWait () { @@ -2294,7 +2294,7 @@ TcpSocketBase::TimeWait () &TcpSocketBase::CloseAndNotify, this); } -/** Below are the attribute get/set functions */ +/* Below are the attribute get/set functions */ void TcpSocketBase::SetSndBufSize (uint32_t size) @@ -2418,13 +2418,13 @@ TcpSocketBase::GetAllowBroadcast (void) const return false; } -/** Placeholder function for future extension that reads more from the TCP header */ +/* Placeholder function for future extension that reads more from the TCP header */ void TcpSocketBase::ReadOptions (const TcpHeader&) { } -/** Placeholder function for future extension that changes the TCP header */ +/* Placeholder function for future extension that changes the TCP header */ void TcpSocketBase::AddOptions (TcpHeader&) { diff --git a/src/internet/model/tcp-socket-base.h b/src/internet/model/tcp-socket-base.h index 8a789913c..e83763617 100644 --- a/src/internet/model/tcp-socket-base.h +++ b/src/internet/model/tcp-socket-base.h @@ -61,6 +61,11 @@ class TcpHeader; class TcpSocketBase : public TcpSocket { public: + /** + * Get the type ID. + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); /** * Create an unbound TCP socket @@ -69,13 +74,30 @@ public: /** * Clone a TCP socket, for use upon receiving a connection request in LISTEN state + * + * \param sock the original Tcp Socket */ TcpSocketBase (const TcpSocketBase& sock); virtual ~TcpSocketBase (void); // Set associated Node, TcpL4Protocol, RttEstimator to this socket + + /** + * \brief Set the associated node. + * \param node the node + */ virtual void SetNode (Ptr node); + + /** + * \brief Set the associated TCP L4 protocol. + * \param tcp the TCP L4 protocol + */ virtual void SetTcp (Ptr tcp); + + /** + * \brief Set the associated RTT estimator. + * \param rtt the RTT estimator + */ virtual void SetRtt (Ptr rtt); // Necessary implementations of null functions from ns3::Socket @@ -101,6 +123,8 @@ public: protected: // Implementing ns3::TcpSocket -- Attribute get/set + // inherited, no need to doc + virtual void SetSndBufSize (uint32_t size); virtual uint32_t GetSndBufSize (void) const; virtual void SetRcvBufSize (uint32_t size); @@ -126,120 +150,454 @@ protected: virtual bool SetAllowBroadcast (bool allowBroadcast); virtual bool GetAllowBroadcast (void) const; + + // Helper functions: Connection set up - int SetupCallback (void); // Common part of the two Bind(), i.e. set callback and remembering local addr:port - int DoConnect (void); // Sending a SYN packet to make a connection if the state allows - void ConnectionSucceeded (void); // Schedule-friendly wrapper for Socket::NotifyConnectionSucceeded() - int SetupEndpoint (void); // Configure m_endpoint for local addr for given remote addr - int SetupEndpoint6 (void); // Configure m_endpoint6 for local addr for given remote addr - void CompleteFork (Ptr, const TcpHeader&, const Address& fromAddress, const Address& toAdress); + + /** + * \brief Common part of the two Bind(), i.e. set callback and remembering local addr:port + * + * \returns 0 on success, -1 on failure + */ + int SetupCallback (void); + + /** + * \brief Perform the real connection tasks: Send SYN if allowed, RST if invalid + * + * \returns 0 on success + */ + int DoConnect (void); + + /** + * \brief Schedule-friendly wrapper for Socket::NotifyConnectionSucceeded() + */ + void ConnectionSucceeded (void); + + /** + * \brief Configure the endpoint to a local address. Called by Connect() if Bind() didn't specify one. + * + * \returns 0 on success + */ + int SetupEndpoint (void); + + /** + * \brief Configure the endpoint v6 to a local address. Called by Connect() if Bind() didn't specify one. + * + * \returns 0 on success + */ + int SetupEndpoint6 (void); + + /** + * \brief Complete a connection by forking the socket + * + * This function is called only if a SYN received in LISTEN state. After + * TcpSocketBase cloned, allocate a new end point to handle the incoming + * connection and send a SYN+ACK to complete the handshake. + * + * \param p the packet triggering the fork + * \param tcpHeader the TCP header of the triggering packet + * \param fromAddress the address of the remote host + * \param toAddress the address the connection is directed to + */ + void CompleteFork (Ptr p, const TcpHeader& tcpHeader, const Address& fromAddress, const Address& toAddress); + + // Helper functions: Transfer operation + + /** + * \brief Called by the L3 protocol when it received a packet to pass on to TCP. + * + * \param packet the incoming packet + * \param header the apcket's IPv4 header + * \param port the incoming port + * \param incomingInterface the incoming interface + */ void ForwardUp (Ptr packet, Ipv4Header header, uint16_t port, Ptr incomingInterface); + + /** + * \brief Called by the L3 protocol when it received a packet to pass on to TCP. + * + * \param packet the incoming packet + * \param header the apcket's IPv6 header + * \param port the incoming port + */ void ForwardUp6 (Ptr packet, Ipv6Header header, uint16_t port); + + /** + * \brief Called by TcpSocketBase::ForwardUp(). + * + * \param packet the incoming packet + * \param header the apcket's IPv4 header + * \param port the incoming port + * \param incomingInterface the incoming interface + */ virtual void DoForwardUp (Ptr packet, Ipv4Header header, uint16_t port, Ptr incomingInterface); //Get a pkt from L3 - virtual void DoForwardUp (Ptr packet, Ipv6Header header, uint16_t port); // Ipv6 version + + /** + * \brief Called by TcpSocketBase::ForwardUp6(). + * + * \param packet the incoming packet + * \param header the apcket's IPv6 header + * \param port the incoming port + */ + virtual void DoForwardUp (Ptr packet, Ipv6Header header, uint16_t port); + + /** + * \brief Called by the L3 protocol when it received an ICMP packet to pass on to TCP. + * + * \param icmpSource the ICMP source address + * \param icmpTtl the ICMP Time to Live + * \param icmpType the ICMP Type + * \param icmpCode the ICMP Code + * \param icmpInfo the ICMP Info + */ void ForwardIcmp (Ipv4Address icmpSource, uint8_t icmpTtl, uint8_t icmpType, uint8_t icmpCode, uint32_t icmpInfo); - void ForwardIcmp6 (Ipv6Address icmpSource, uint8_t icmpTtl, uint8_t icmpType, uint8_t icmpCode, uint32_t icmpInfo); - bool SendPendingData (bool withAck = false); // Send as much as the window allows - uint32_t SendDataPacket (SequenceNumber32 seq, uint32_t maxSize, bool withAck); // Send a data packet - void SendEmptyPacket (uint8_t flags); // Send a empty packet that carries a flag, e.g. ACK - void SendRST (void); // Send reset and tear down this socket - bool OutOfRange (SequenceNumber32 head, SequenceNumber32 tail) const; // Check if a sequence number range is within the rx window + + /** + * \brief Called by the L3 protocol when it received an ICMPv6 packet to pass on to TCP. + * + * \param icmpSource the ICMP source address + * \param icmpTtl the ICMP Time to Live + * \param icmpType the ICMP Type + * \param icmpCode the ICMP Code + * \param icmpInfo the ICMP Info + */ + void ForwardIcmp6 (Ipv6Address icmpSource, uint8_t icmpTtl, uint8_t icmpType, uint8_t icmpCode, uint32_t icmpInfo); + + /** + * \brief Send as much pending data as possible according to the Tx window. + * + * Note that this function did not implement the PSH flag. + * + * \param withAck forces an ACK to be sent + * \returns true if some data have been sent + */ + bool SendPendingData (bool withAck = false); + + /** + * \brief Extract at most maxSize bytes from the TxBuffer at sequence seq, add the + * TCP header, and send to TcpL4Protocol + * + * \param seq the sequence number + * \param maxSize the maximum data block to be transmitted (in bytes) + * \param withAck forces an ACK to be sent + * \returns the number of bytes sent + */ + uint32_t SendDataPacket (SequenceNumber32 seq, uint32_t maxSize, bool withAck); + + /** + * \brief Send a empty packet that carries a flag, e.g. ACK + * + * \param flags the packet's flags + */ + void SendEmptyPacket (uint8_t flags); + + /** + * \brief Send reset and tear down this socket + */ + void SendRST (void); + + /** + * \brief Check if a sequence number range is within the rx window + * + * \param head start of the Sequence window + * \param tail end of the Sequence window + * \returns true if it is in range + */ + bool OutOfRange (SequenceNumber32 head, SequenceNumber32 tail) const; + // Helper functions: Connection close - int DoClose (void); // Close a socket by sending RST, FIN, or FIN+ACK, depend on the current state - void CloseAndNotify (void); // To CLOSED state, notify upper layer, and deallocate end point - void Destroy (void); // Kill this socket by zeroing its attributes - void Destroy6 (void); // Kill this socket by zeroing its attributes - void DeallocateEndPoint (void); // Deallocate m_endPoint - void PeerClose (Ptr, const TcpHeader&); // Received a FIN from peer, notify rx buffer - void DoPeerClose (void); // FIN is in sequence, notify app and respond with a FIN - void CancelAllTimers (void); // Cancel all timer when endpoint is deleted - void TimeWait (void); // Move from CLOSING or FIN_WAIT_2 to TIME_WAIT state + + /** + * \brief Close a socket by sending RST, FIN, or FIN+ACK, depend on the current state + * + * \returns 0 on success + */ + int DoClose (void); + + /** + * \brief Peacefully close the socket by notifying the upper layer and deallocate end point + */ + void CloseAndNotify (void); + + /** + * \brief Kill this socket by zeroing its attributes (IPv4) + * + * This is a callback function configured to m_endpoint in + * SetupCallback(), invoked when the endpoint is destroyed. + */ + void Destroy (void); + + /** + * \brief Kill this socket by zeroing its attributes (IPv6) + * + * This is a callback function configured to m_endpoint in + * SetupCallback(), invoked when the endpoint is destroyed. + */ + void Destroy6 (void); + + /** + * \brief Deallocate m_endPoint + */ + void DeallocateEndPoint (void); + + /** + * \brief Received a FIN from peer, notify rx buffer + * + * \param p the packet + * \param tcpHeader the packet's TCP header + */ + void PeerClose (Ptr p, const TcpHeader& tcpHeader); + + /** + * \brief FIN is in sequence, notify app and respond with a FIN + */ + void DoPeerClose (void); + + /** + * \brief Cancel all timer when endpoint is deleted + */ + void CancelAllTimers (void); + + /** + * \brief Move from CLOSING or FIN_WAIT_2 to TIME_WAIT state + */ + void TimeWait (void); // State transition functions - void ProcessEstablished (Ptr, const TcpHeader&); // Received a packet upon ESTABLISHED state - void ProcessListen (Ptr, const TcpHeader&, const Address&, const Address&); // Process the newly received ACK - void ProcessSynSent (Ptr, const TcpHeader&); // Received a packet upon SYN_SENT - void ProcessSynRcvd (Ptr, const TcpHeader&, const Address&, const Address&); // Received a packet upon SYN_RCVD - void ProcessWait (Ptr, const TcpHeader&); // Received a packet upon CLOSE_WAIT, FIN_WAIT_1, FIN_WAIT_2 - void ProcessClosing (Ptr, const TcpHeader&); // Received a packet upon CLOSING - void ProcessLastAck (Ptr, const TcpHeader&); // Received a packet upon LAST_ACK + + /** + * \brief Received a packet upon ESTABLISHED state. + * + * This function is mimicking the role of tcp_rcv_established() in tcp_input.c in Linux kernel. + * + * \param packet the packet + * \param tcpHeader the packet's TCP header + */ + void ProcessEstablished (Ptr packet, const TcpHeader& tcpHeader); // Received a packet upon ESTABLISHED state + + /** + * \brief Received a packet upon LISTEN state. + * + * \param packet the packet + * \param tcpHeader the packet's TCP header + * \param fromAddress the source address + * \param toAddress the destination address + */ + void ProcessListen (Ptr packet, const TcpHeader& tcpHeader, + const Address& fromAddress, const Address& toAddress); + + /** + * \brief Received a packet upon SYN_SENT + * + * \param packet the packet + * \param tcpHeader the packet's TCP header + */ + void ProcessSynSent (Ptr packet, const TcpHeader& tcpHeader); + + /** + * \brief Received a packet upon SYN_RCVD. + * + * \param packet the packet + * \param tcpHeader the packet's TCP header + * \param fromAddress the source address + * \param toAddress the destination address + */ + void ProcessSynRcvd (Ptr packet, const TcpHeader& tcpHeader, + const Address& fromAddress, const Address& toAddress); + + /** + * \brief Received a packet upon CLOSE_WAIT, FIN_WAIT_1, FIN_WAIT_2 + * + * \param packet the packet + * \param tcpHeader the packet's TCP header + */ + void ProcessWait (Ptr packet, const TcpHeader& tcpHeader); + + /** + * \brief Received a packet upon CLOSING + * + * \param packet the packet + * \param tcpHeader the packet's TCP header + */ + void ProcessClosing (Ptr packet, const TcpHeader& tcpHeader); + + /** + * \brief Received a packet upon LAST_ACK + * + * \param packet the packet + * \param tcpHeader the packet's TCP header + */ + void ProcessLastAck (Ptr packet, const TcpHeader& tcpHeader); // Window management - virtual uint32_t UnAckDataCount (void); // Return count of number of unacked bytes - virtual uint32_t BytesInFlight (void); // Return total bytes in flight - virtual uint32_t Window (void); // Return the max possible number of unacked bytes - virtual uint32_t AvailableWindow (void); // Return unfilled portion of window - virtual uint16_t AdvertisedWindowSize (void); // The amount of Rx window announced to the peer + + /** + * \brief Return count of number of unacked bytes + * \returns count of number of unacked bytes + */ + virtual uint32_t UnAckDataCount (void); + + /** + * \brief Return total bytes in flight + * \returns total bytes in flight + */ + virtual uint32_t BytesInFlight (void); + + /** + * \brief Return the max possible number of unacked bytes + * \returns the max possible number of unacked bytes + */ + virtual uint32_t Window (void); + + /** + * \brief Return unfilled portion of window + * \return unfilled portion of window + */ + virtual uint32_t AvailableWindow (void); + + /** + * \brief The amount of Rx window announced to the peer + * \returns size of Rx window announced to the peer + */ + virtual uint16_t AdvertisedWindowSize (void); + // Manage data tx/rx - virtual Ptr Fork (void) = 0; // Call CopyObject<> to clone me - virtual void ReceivedAck (Ptr, const TcpHeader&); // Received an ACK packet - virtual void ReceivedData (Ptr, const TcpHeader&); // Recv of a data, put into buffer, call L7 to get it if necessary - virtual void EstimateRtt (const TcpHeader&); // RTT accounting - virtual void NewAck (SequenceNumber32 const& seq); // Update buffers w.r.t. ACK - virtual void DupAck (const TcpHeader& t, uint32_t count) = 0; // Received dupack - virtual void ReTxTimeout (void); // Call Retransmit() upon RTO event - virtual void Retransmit (void); // Halving cwnd and call DoRetransmit() - virtual void DelAckTimeout (void); // Action upon delay ACK timeout, i.e. send an ACK - virtual void LastAckTimeout (void); // Timeout at LAST_ACK, close the connection - virtual void PersistTimeout (void); // Send 1 byte probe to get an updated window size - virtual void DoRetransmit (void); // Retransmit the oldest packet - virtual void ReadOptions (const TcpHeader&); // Read option from incoming packets - virtual void AddOptions (TcpHeader&); // Add option to outgoing packets + + /** + * \brief Call CopyObject<> to clone me + * \returns a copy of the socket + */ + virtual Ptr Fork (void) = 0; + + /** + * \brief Received an ACK packet + * \param packet the packet + * \param tcpHeader the packet's TCP header + */ + virtual void ReceivedAck (Ptr packet, const TcpHeader& tcpHeader); + + /** + * \brief Recv of a data, put into buffer, call L7 to get it if necessary + * \param packet the packet + * \param tcpHeader the packet's TCP header + */ + virtual void ReceivedData (Ptr packet, const TcpHeader& tcpHeader); + + /** + * \brief Take into account the packet for RTT estimation + * \param tcpHeader the packet's TCP header + */ + virtual void EstimateRtt (const TcpHeader& tcpHeader); + + /** + * \brief Update buffers w.r.t. ACK + * \param seq the sequence number + */ + virtual void NewAck (SequenceNumber32 const& seq); + + /** + * \brief Received dupack (duplicate ACK) + * \param tcpHeader the packet's TCP header + * \param count counter of duplicate ACKs + */ + virtual void DupAck (const TcpHeader& tcpHeader, uint32_t count) = 0; + + /** + * \brief Call Retransmit() upon RTO event + */ + virtual void ReTxTimeout (void); + + /** + * \brief Halving cwnd and call DoRetransmit() + */ + virtual void Retransmit (void); + + /** + * \brief Action upon delay ACK timeout, i.e. send an ACK + */ + virtual void DelAckTimeout (void); + + /** + * \brief Timeout at LAST_ACK, close the connection + */ + virtual void LastAckTimeout (void); + + /** + * \brief Send 1 byte probe to get an updated window size + */ + virtual void PersistTimeout (void); + + /** + * \brief Retransmit the oldest packet + */ + virtual void DoRetransmit (void); + + /** + * \brief Read option from incoming packets + * \param tcpHeader the packet's TCP header + */ + virtual void ReadOptions (const TcpHeader& tcpHeader); + + /** + * \brief Add option to outgoing packets + * \param tcpHeader the packet's TCP header + */ + virtual void AddOptions (TcpHeader& tcpHeader); + protected: // Counters and events - EventId m_retxEvent; //< Retransmission event - EventId m_lastAckEvent; //< Last ACK timeout event - EventId m_delAckEvent; //< Delayed ACK timeout event - EventId m_persistEvent; //< Persist event: Send 1 byte to probe for a non-zero Rx window - EventId m_timewaitEvent; //< TIME_WAIT expiration event: Move this socket to CLOSED state - uint32_t m_dupAckCount; //< Dupack counter - uint32_t m_delAckCount; //< Delayed ACK counter - uint32_t m_delAckMaxCount; //< Number of packet to fire an ACK before delay timeout - bool m_noDelay; //< Set to true to disable Nagle's algorithm - uint32_t m_cnCount; //< Count of remaining connection retries - uint32_t m_cnRetries; //< Number of connection retries before giving up - TracedValue