From 05d649ef54db2ec8fafb007dbeab020dfedb072c Mon Sep 17 00:00:00 2001 From: Craig Dowell Date: Tue, 10 Jul 2007 12:38:51 -0700 Subject: [PATCH] doxygen --- src/routing/static-router.cc | 25 +++++- src/routing/static-router.h | 152 ++++++++++++++++++++++++++++++++--- 2 files changed, 161 insertions(+), 16 deletions(-) diff --git a/src/routing/static-router.cc b/src/routing/static-router.cc index 6f48a0f36..6f1fd245b 100644 --- a/src/routing/static-router.cc +++ b/src/routing/static-router.cc @@ -55,7 +55,7 @@ StaticRouterLSA::StaticRouterLSA (StaticRouterLSA& lsa) } StaticRouterLSA& -StaticRouterLSA::operator= (StaticRouterLSA lsa) +StaticRouterLSA::operator= (StaticRouterLSA& lsa) { NS_DEBUG("StaticRouterLSA Operator ="); NS_ASSERT_MSG(IsEmpty(), "The LSA must be empty before assignment"); @@ -274,7 +274,10 @@ StaticRouter::GetNumLSAs (void) Ipv4Mask maskRemote = ipv4Remote->GetNetworkMask(ifIndexRemote); NS_DEBUG("Working with remote address " << addrRemote); // -// Now we can fill out the link state advertisement for this link. +// Now we can fill out the link state advertisement for this link. There +// are always two link records; the first is a point-to-point record +// describing the link and the second is a stub network record with the +// network number. // StaticRouterLSA *pLSA = new StaticRouterLSA; pLSA->m_linkStateId = m_routerId; @@ -301,11 +304,18 @@ StaticRouter::GetNumLSAs (void) return m_LSAs.size (); } +// +// Get the nth link state advertisement from this router. +// bool StaticRouter::GetLSA (uint32_t n, StaticRouterLSA &lsa) { NS_ASSERT_MSG(lsa.IsEmpty(), "Must pass empty LSA"); - +// +// All of the work was done in GetNumLSAs. All we have to do here is to +// walk the list of link state advertisements created there and return the +// one the client is interested in. +// ListOfLSAs_t::iterator i = m_LSAs.begin (); uint32_t j = 0; @@ -318,9 +328,14 @@ StaticRouter::GetLSA (uint32_t n, StaticRouterLSA &lsa) return true; } } + return false; } +// +// Link through the given channel and find the net device that's on the +// other end. This only makes sense with a point-to-point channel. +// Ptr StaticRouter::GetAdjacent(Ptr nd, Ptr ch) { @@ -358,6 +373,10 @@ StaticRouter::GetAdjacent(Ptr nd, Ptr ch) } } +// +// Given a node and a net device, find the IPV4 interface index that +// corresponds to that net device. +// uint32_t StaticRouter::FindIfIndexForDevice(Ptr node, Ptr nd) { diff --git a/src/routing/static-router.h b/src/routing/static-router.h index 5ed6b3e79..0d0cd09ac 100644 --- a/src/routing/static-router.h +++ b/src/routing/static-router.h @@ -28,7 +28,11 @@ namespace ns3 { /** - * \brief A single link record for a link state advertisement + * \brief A single link record for a link state advertisement. + * + * The StaticRouterLinkRecord is modeled after the OSPF link record field of + * a Link State Advertisement. Right now we will only see two types of link + * records corresponding to a stub network and a point-to-point link (channel). * * For Type 3 link (Stub), */ @@ -49,14 +53,24 @@ public: // For Type 3 link (Stub), set m_linkData to mask 0xffffffff // Ipv4Address m_linkData; // for links to RouterLSA, - + /** + * Enumeration of the possible types of Static Router Link Records. These + * are defined in the OSPF spec. We currently only use PointToPoint and + * StubNetwork types. + */ enum LinkType { - PointToPoint = 1, - TransitNetwork, - StubNetwork, - VirtualLink + PointToPoint = 1, /**< Record representing a point to point channel */ + TransitNetwork, /**< Unused -- for future OSPF compatibility */ + StubNetwork, /**< Record represents a leaf node network */ + VirtualLink /**< Unused -- for future OSPF compatibility */ } m_linkType; - + /** + * An abstract cost associated with forwarding a packet across a link. + * A sum of metrics must have a well-defined meaning. That is, you shouldn't + * use bandwidth as a metric (how does the sum of the bandwidth of two hops + * relate to the cost of sending a packet); rather you should use something + * like delay. + */ uint32_t m_metric; }; @@ -70,19 +84,77 @@ public: class StaticRouterLSA { public: + /** + * Create a blank Static Router Link State Advertisement. On completion, + * any Ipv4Address variables initialized to 0.0.0.0 and the list of Link + * State Records is empty. + */ StaticRouterLSA(); + /** + * Copy constructor for a Static Router Link State Advertisement. + * Takes a piece of memory and constructs a semantically identical copy of + * the given LSA. + * + * @param lsa The existing LSA to be used as the source. + */ StaticRouterLSA (StaticRouterLSA& lsa); + /** + * Destroy an existing Static Router Link State Advertisement. Any Static + * router Link Records present in the list are freed. + */ ~StaticRouterLSA(); - - StaticRouterLSA& operator= (StaticRouterLSA lsa); - + /** + * Assignment operator for a Static Router Link State Advertisement. + * Takes an existing Static Router Link State Advertisement and overwrites + * it to make a semantically identical copy of a given prototype LSA. + * + * If there are any Static Router Link Records present in the existing + * LSA, they are freed before the assignment happens. + * + * @param lsa The existing LSA to be used as the source. + * @returns Reference to the overwritten LSA. + */ + StaticRouterLSA& operator= (StaticRouterLSA& lsa); + /** + * Add a given Static Router Link Record to a given Static Router Link + * State Advertisement. + * + * @param lr The Static Router Link Record to be added. + * @returns The number of link records in the list. + */ uint32_t AddLinkRecord (StaticRouterLinkRecord* lr); + /** + * Release all of the Static Router Link Records present in the Static + * Router Link State Advertisement and make the list of link records empty. + */ void ClearLinkRecords(void); + /** + * Check to see of the list of Static Router Link Records present in the + * Static Router Link State Advertisement is empty. + * + * @returns True if the list is empty, false otherwise. + */ bool IsEmpty(void); - + /** + * Print the contents of the Static Router Link State Advertisement and + * any Static Router Link Records present in the list. Quite verbose. + */ void Print (std::ostream &os); - + /** + * The Link State ID is defined by the OSPF spec. We always set it to the + * router ID of the router making the advertisement. + * + * @see RoutingEnvironment::AllocateRouterId () + * @see StaticRouter::GetRouterId () + */ Ipv4Address m_linkStateId; + /** + * The Advertising Router is defined by the OSPF spec. We always set it to + * the router ID of the router making the advertisement. + * + * @see RoutingEnvironment::AllocateRouterId () + * @see StaticRouter::GetRouterId () + */ Ipv4Address m_advertisingRtr; typedef std::list ListOfLinkRecords_t; @@ -103,11 +175,65 @@ std::ostream& operator<< (std::ostream& os, StaticRouterLSA& lsa); class StaticRouter : public Object { public: + /** + * The Interface ID of the Static Router interface. + * + * @see Object::QueryInterface () + */ static const InterfaceId iid; + /** + * Create a Static Router class and aggregate its interface onto the Node + * provided. + * + * @param lsa The existing Node onto which this router will be aggregated. + */ StaticRouter (Ptr node); - + /** + * Get the Router ID associated with this Static Router. The Router IDs + * are allocated in the RoutingEnvironment -- one per Router, starting at + * 0.0.0.1 and incrementing with each instantiation of a router. + * + * @see RoutingEnvironment::AllocateRouterId () + * @returns The Router ID associated with the Static Router. + */ Ipv4Address GetRouterId(void); + /** + * Get the Number of Static Router Link State Advertisements that this + * router can export. + * + * This is a fairly expensive operation in that every time it is called + * the current list of LSAs is built by walking connected point-to-point + * channels and peeking into adjacent IPV4 stacks to get address information. + * This is done to allow for limited dymanics of the Static Routing + * environment. By that we mean that you can discover new link state + * advertisements after a network topology change by calling GetNumLSAs and + * then by reading those advertisements. + * + * @see StaticRouterLSA + * @see StaticRouter::GetLSA () + * @returns The number of Static Router Link State Advertisements. + */ uint32_t GetNumLSAs (void); + /** + * Get a Static Router Link State Advertisements that this router has said + * that it can export. + * + * This is a fairly inexpensive expensive operation in that the hard work + * was done in GetNumLSAs. We just copy the indicated Static Router Link + * State Advertisement into the requested StaticRouterLSA object. + * + * You must call StaticRouter::GetNumLSAs before calling this method in + * order to discover the adjacent routers and build the advertisements. + * GetNumLSAs will return the number of LSAs this router advertises. + * The parameter n (requested LSA number) must be in the range 0 to + * GetNumLSAs() - 1. + * + * @see StaticRouterLSA + * @see StaticRouter::GetNumLSAs () + * @param n The index number of the LSA you want to read. + * @param lsa The StaticRouterLSA class to receive the LSA information. + * @returns The number of Static Router Link State Advertisements. + */ bool GetLSA (uint32_t n, StaticRouterLSA &lsa); protected: