docs: wrote Doxygen comments for all files
refs: #4118
Change-Id: Ib0e7f1926cdabcca5aa401b59b24519412a099f7
diff --git a/src/adjacent.cpp b/src/adjacent.cpp
index 55ddff5..78c71b5 100644
--- a/src/adjacent.cpp
+++ b/src/adjacent.cpp
@@ -17,15 +17,15 @@
* You should have received a copy of the GNU General Public License along with
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
**/
+
+#include "adjacent.hpp"
+#include "logger.hpp"
+
#include <iostream>
#include <string>
#include <cmath>
#include <limits>
-
-#include "adjacent.hpp"
-#include "logger.hpp"
-
namespace nlsr {
INIT_LOGGER("Adjacent");
diff --git a/src/adjacent.hpp b/src/adjacent.hpp
index 29d7567..499e45e 100644
--- a/src/adjacent.hpp
+++ b/src/adjacent.hpp
@@ -17,6 +17,7 @@
* You should have received a copy of the GNU General Public License along with
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
**/
+
#include <string>
#include <cmath>
#include <boost/cstdint.hpp>
@@ -29,6 +30,11 @@
namespace nlsr {
+/*! \brief A neighbor reachable over a Face.
+ *
+ * Represents another node that we expect to be running NLSR that we
+ * should be able to reach over a direct Face connection.
+ */
class Adjacent
{
@@ -120,6 +126,7 @@
return m_faceId;
}
+ /*! \brief Equality is when name, Face URI, and link cost are all equal. */
bool
operator==(const Adjacent& adjacent) const;
@@ -148,11 +155,18 @@
static const float DEFAULT_LINK_COST;
private:
+ /*! m_name The NLSR-configured router name of the neighbor */
ndn::Name m_name;
+ /*! m_connectingFaceUri The NFD-level specification of the Face*/
ndn::util::FaceUri m_faceUri;
+ /*! m_linkCost The semi-arbitrary cost to traverse the link. */
double m_linkCost;
+ /*! m_status Whether the neighbor is active or not */
Status m_status;
+ /*! m_interestTimedOutNo How many failed Hello interests we have sent since the last reply */
uint32_t m_interestTimedOutNo;
+ /*! m_faceId The NFD-assigned ID for the neighbor, used to
+ * determine whether a Face is available */
uint64_t m_faceId;
};
diff --git a/src/common.hpp b/src/common.hpp
index 470d8b1..0d67efc 100644
--- a/src/common.hpp
+++ b/src/common.hpp
@@ -19,6 +19,11 @@
*
**/
+/*! \file
+ * Shared include file to provide a single point-of-entry, and
+ * hopefully improve compile times.
+ */
+
#ifndef NLSR_COMMON_HPP
#define NLSR_COMMON_HPP
diff --git a/src/communication/sync-logic-handler.hpp b/src/communication/sync-logic-handler.hpp
index 72a5487..6de6113 100644
--- a/src/communication/sync-logic-handler.hpp
+++ b/src/communication/sync-logic-handler.hpp
@@ -22,6 +22,8 @@
#ifndef NLSR_SYNC_LOGIC_HANDLER_HPP
#define NLSR_SYNC_LOGIC_HANDLER_HPP
+#include "test-access-control.hpp"
+
#include <ndn-cxx/face.hpp>
#include <ChronoSync/socket.hpp>
@@ -30,8 +32,6 @@
#include <boost/cstdint.hpp>
#include <boost/throw_exception.hpp>
-#include "test-access-control.hpp"
-
class InterestManager;
namespace nlsr {
@@ -39,6 +39,14 @@
class ConfParameter;
class Lsdb;
+/*! \brief NLSR-to-ChronoSync interaction point
+ *
+ * This class serves as the abstraction for the syncing portion of
+ * NLSR and its components. NLSR has no particular reliance on
+ * ChronoSync, except that the NLSR source would need to be modified
+ * for use with other sync protocols.
+ *
+ */
class SyncLogicHandler
{
public:
@@ -54,45 +62,77 @@
SyncLogicHandler(ndn::Face& face, Lsdb& lsdb, ConfParameter& conf);
- /*! \brief Receive and parse update from Sync
-
- Parses the router name the update came from and passes it to processUpdateFromSync
-
- \param v The information that Sync has acquired.
+ /*! \brief Hook function to call whenever sync detects new data.
+ *
+ * This function packages the sync information into discrete updates
+ * and passes those off to another function, processUpdateFromSync.
+ * \sa processUpdateFromSync
+ *
+ * \param v A container with the new information sync has received
*/
void
onChronoSyncUpdate(const std::vector<chronosync::MissingDataInfo>& v);
- /*! \brief Wrapper function to call publishSyncUpdate with correct LSA type
-
- \param type The LSA type constant
- \param seqNo The latest seqNo known to lsdb
+ /*! \brief Instruct ChronoSync to publish an update.
+ *
+ * This function instructs sync to push an update into the network,
+ * based on whatever the state of the sequencing manager is when
+ * this is called. Since each ChronoSync instance maintains its own
+ * PIT, doing this satisfies those interests so that other routers
+ * know a sync update is available.
+ * \sa publishSyncUpdate
*/
void
publishRoutingUpdate(const ndn::Name& type, const uint64_t& seqNo);
- /*! \brief Creates ChronoSync socket and register additional sync nodes (user prefixes)
-
- \param syncPrefix /localhop/NLSR/sync
+ /*! \brief Create and configure a socket to enable ChronoSync for this NLSR.
+ *
+ * In a typical situation this only needs to be called once, when NLSR starts.
+ * \param syncPrefix The sync prefix you want this ChronoSync to use
+ * \sa Nlsr::initialize
*/
void
createSyncSocket(const ndn::Name& syncPrefix);
private:
+ /*! \brief Simple function to glue Name components together
+ */
void
buildUpdatePrefix();
+ /*! \brief Determine which kind of LSA was updated and fetch it.
+ *
+ * Checks that the received update is not from us, which can happen,
+ * and then inspects the update to determine which kind of LSA the
+ * update is for. Finally, it expresses interest for the correct LSA
+ * type.
+ * \throws SyncUpdate::Error If the sync update doesn't look like a sync LSA update.
+ */
void
processUpdateFromSync(const ndn::Name& originRouter,
const ndn::Name& updateName, const uint64_t& seqNo);
+ /*! \brief Consults the LSDB to determine if a sync update has a new LSA.
+ *
+ * Given some information about an LSA, consult the LSDB to
+ * determine if the sequence number represents a new LSA from the
+ * origin router.
+ */
bool
isLsaNew(const ndn::Name& originRouter, const std::string& lsaType,
const uint64_t& seqNo);
+ /*! \brief Fetch an LSA of a certain type, with a certain sequence number.
+ */
void
expressInterestForLsa(const ndn::Name& updateName, const uint64_t& seqNo);
+ /*! \brief Instruct ChronoSync, via the sync socket, to publish an update.
+ *
+ * Each ChronoSync instance maintains its own PIT for sync
+ * updates. This function creates a data that satisfies that update,
+ * so that the interested routers will know new data is available.
+ */
void
publishSyncUpdate(const ndn::Name& updatePrefix, uint64_t seqNo);
@@ -103,7 +143,7 @@
private:
Lsdb& m_lsdb;
- ConfParameter& m_confParam;
+ const ConfParameter& m_confParam;
PUBLIC_WITH_TESTS_ELSE_PRIVATE:
ndn::Name m_nameLsaUserPrefix;
diff --git a/src/conf-file-processor.cpp b/src/conf-file-processor.cpp
index c80f439..e48158c 100644
--- a/src/conf-file-processor.cpp
+++ b/src/conf-file-processor.cpp
@@ -19,8 +19,8 @@
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
**/
-#include "conf-parameter.hpp"
#include "conf-file-processor.hpp"
+#include "conf-parameter.hpp"
#include "adjacent.hpp"
#include "utility/name-helper.hpp"
#include "update/prefix-update-processor.hpp"
diff --git a/src/conf-file-processor.hpp b/src/conf-file-processor.hpp
index d6cdcbe..1f0918a 100644
--- a/src/conf-file-processor.hpp
+++ b/src/conf-file-processor.hpp
@@ -21,14 +21,27 @@
#ifndef NLSR_CONF_FILE_PROCESSOR_HPP
#define NLSR_CONF_FILE_PROCESSOR_HPP
+#include "nlsr.hpp"
+
#include <boost/smart_ptr/shared_ptr.hpp>
#include <boost/property_tree/ptree.hpp>
#include <boost/cstdint.hpp>
-#include "nlsr.hpp"
-
namespace nlsr {
+/*! \brief A class containing methods to parse an NLSR configuration file
+ *
+ * This class contains methods to parse an NLSR configuration file and
+ * set all the parameters in NLSR to the received values. There are
+ * defaults for any unconfigured settings.
+ *
+ * This is currently called by the wrapper class NlsrRunner to
+ * populate the NLSR object with its configuration before NLSR is
+ * started.
+ *
+ * \sa nlsr::ConfParameter
+ * \sa NlsrRunner::run
+ */
class ConfFileProcessor
{
public:
@@ -38,38 +51,80 @@
{
}
+ /*! \brief Load and parse the configuration file, then populate NLSR.
+ *
+ * Entry-point function that chains all the necessary steps together
+ * to configure an NLSR object.
+ *
+ * \return A boolean for whether configuration was successful.
+ */
bool
processConfFile();
private:
typedef boost::property_tree::ptree ConfigSection;
+ /*! \brief Parse the configuration file into a tree and process the nodes.
+ *
+ * Reads the configuration file as a property tree, and then iterates
+ * over them, attempting to parse each node. The nodes themselves
+ * are passed to another function that determines what kind of
+ * section it is and handles it appropriately. On any error in
+ * reading the file, return false.
+ *
+ * \return Whether configuration was successful.
+ */
bool
load(std::istream& input);
+ /*! \brief A dispatcher-like function to send configuration tree nodes to the right subfunction.
+ */
bool
processSection(const std::string& sectionName, const ConfigSection& section);
+ /*! \brief Parse general options, including router name, logging directory, LSA refresh.
+ */
bool
processConfSectionGeneral(const ConfigSection& section);
+ /*! \brief Configure options relating to neighbor configuration and detection.
+ *
+ * Parse options that control NLSR's behavior about neighbors. Such
+ * things include how many hello interests are sent and what their
+ * timeout is, as well as parsing neighbor specifications. Neighbor
+ * Face URIs are parsed and confirmed as valid here by ndn-cxx.
+ */
bool
processConfSectionNeighbors(const ConfigSection& section);
+ /*! \brief Set the state of hyperbolic routing: off, on, dry-run.
+ */
bool
processConfSectionHyperbolic(const ConfigSection& section);
+ /*! \brief Set options for the FIB: nexthops per prefix, routing calculation interval.
+ */
bool
processConfSectionFib(const ConfigSection& section);
+ /*! \brief Set prefixes that NLSR is supposed to advertise immediately.
+ */
bool
processConfSectionAdvertising(const ConfigSection& section);
+ /*! \brief Parse and set rules for the validator.
+ *
+ * This section parses and sets rules for the validators, which
+ * control what criteria Interest and Data need to follow to be
+ * considered valid by this NLSR.
+ */
bool
processConfSectionSecurity(const ConfigSection& section);
private:
+ /*! m_confFileName The full path of the configuration file to parse. */
std::string m_confFileName;
+ /*! m_nlsr The NLSR object to configure upon successful parsing. */
Nlsr& m_nlsr;
};
diff --git a/src/conf-parameter.hpp b/src/conf-parameter.hpp
index e21e547..29f9f9c 100644
--- a/src/conf-parameter.hpp
+++ b/src/conf-parameter.hpp
@@ -106,6 +106,17 @@
HYPERBOLIC_STATE_DEFAULT = 0
};
+/*! \brief A class to house all the configuration parameters for NLSR.
+ *
+ * This class is conceptually a singleton (but not mechanically) which
+ * is just a collection of attributes that serve as a
+ * separation-of-data for NLSR's configuration variables. NLSR refers
+ * to an instance of this class for all its configuration
+ * parameters. This object is typically populated by a
+ * ConfFileProcessor reading a configuration file.
+ *
+ * \sa nlsr::ConfFileProcessor
+ */
class ConfParameter
{
@@ -441,6 +452,8 @@
return m_log4CxxConfPath;
}
+ /*! \brief Dump the current state of all attributes to the log.
+ */
void
writeLog();
diff --git a/src/hello-protocol.cpp b/src/hello-protocol.cpp
index 2e17e16..afbd564 100644
--- a/src/hello-protocol.cpp
+++ b/src/hello-protocol.cpp
@@ -16,8 +16,8 @@
*
* You should have received a copy of the GNU General Public License along with
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
- *
**/
+#include "hello-protocol.hpp"
#include "hello-protocol.hpp"
#include "nlsr.hpp"
@@ -150,7 +150,7 @@
m_nlsr.getAdjacencyList().getTimedOutInterestCount(neighbor);
_LOG_DEBUG("Status: " << status);
_LOG_DEBUG("Info Interest Timed out: " << infoIntTimedOutCount);
- if ((infoIntTimedOutCount < m_nlsr.getConfParameter().getInterestRetryNumber())) {
+ if (infoIntTimedOutCount < m_nlsr.getConfParameter().getInterestRetryNumber()) {
// interest name: /<neighbor>/NLSR/INFO/<router>
ndn::Name interestName(neighbor);
interestName.append(NLSR_COMPONENT);
@@ -188,11 +188,6 @@
this, _1, _2));
}
- // A validator is called on the incoming data, and if the data
- // passes the validator's description/definitions, this function is
- // called. Set the neighbor's status to active and refresh its
- // LSA. If there was a change in status, we schedule an adjacency
- // LSA build.
void
HelloProtocol::onContentValidated(const std::shared_ptr<const ndn::Data>& data)
{
@@ -223,8 +218,6 @@
hpIncrementSignal(Statistics::PacketType::RCV_HELLO_DATA);
}
- // Simply logs a debug message that the content could not be
- // validated (and is implicitly being discarded as a result).
void
HelloProtocol::onContentValidationFailed(const std::shared_ptr<const ndn::Data>& data,
const std::string& msg)
diff --git a/src/hello-protocol.hpp b/src/hello-protocol.hpp
index dbc12d0..29b2c05 100644
--- a/src/hello-protocol.hpp
+++ b/src/hello-protocol.hpp
@@ -44,53 +44,60 @@
{
}
- /*! \brief Schedules a hello Interest event.
-
- \param seconds The number of seconds to wait before calling the event.
+ /*! \brief Schedules a Hello Interest event.
+ *
+ * This function serves as the Hello Interest loop, and must be
+ * explicitly called to start the Hello cycle. This is done at
+ * NLSR's initialization.
+ *
+ * \sa Nlsr::initialize
+ * \param seconds The number of seconds to wait before calling the event.
*/
void
scheduleInterest(uint32_t seconds);
- /*! \brief Sends a hello Interest packet.
-
- \param interestNamePrefix The name of the router that has published the
- update we want. Here that should be: \<router name\>/NLSR/INFO
-
- \param seconds The lifetime of the Interest we construct, in seconds
-
- This function attempts to contact neighboring routers to
- determine their status (which currently is one of: ACTIVE,
- INACTIVE, or UNKNOWN)
+ /*! \brief Sends a Hello Interest packet.
+ *
+ * \param interestNamePrefix The name of the router that has published the
+ * update we want. Here that should be: \<router name\>/NLSR/INFO
+ *
+ * \param seconds The lifetime of the Interest we construct, in seconds
+ *
+ * This function attempts to contact neighboring routers to
+ * determine their status (which currently is one of: ACTIVE,
+ * INACTIVE, or UNKNOWN)
*/
void
expressInterest(const ndn::Name& interestNamePrefix, uint32_t seconds);
- /*! \brief Sends a hello Interest packet that was previously scheduled.
-
- \param seconds (ignored)
-
- This function is called as part of a schedule to regularly
- determine the adjacency status of neighbors. This function checks
- if the specified neighbor has a Face, and if not creates one. If
- the neighbor had a Face, it calls \c expressInterest, else it will
- attempt to create a Face, which will itself attempt to contact the
- neighbor. Then the function schedules for this function to be invoked again.
+ /*! \brief Sends Hello Interests to all neighbors
+ *
+ * \param seconds (ignored)
+ *
+ * This function is called as part of a schedule to regularly
+ * determine the adjacency status of neighbors. This function
+ * creates and sends a Hello Interest to each neighbor in
+ * Nlsr::m_adjacencyList. If the neighbor has not been contacted
+ * before and curerntly has no Face in NFD, this method will call a
+ * different pipeline that creates the Face first, then registers
+ * prefixes.
*/
void
sendScheduledInterest(uint32_t seconds);
- /*! \brief Processes a hello Interest from a neighbor.
-
- \param name (ignored)
-
- \param interest The Interest object that we have received and need to
- process.
-
- Processes a hello Interest that this router receives from one of
- its neighbors. If the neighbor that sent the Interest does not
- have a Face, NLSR will attempt to register one. Also, if the
- neighbor that sent the Interest was previously marked as INACTIVE,
- NLSR will attempt to contact it with its own hello Interest.
+ /*! \brief Processes a Hello Interest from a neighbor.
+ *
+ * \param name (ignored)
+ *
+ * \param interest The Interest object that we have received and need to
+ * process.
+ *
+ * Processes a Hello Interest that this router receives from one of
+ * its neighbors. If the neighbor that sent the Interest does not
+ * have a Face, NLSR will attempt to create one. Also, if the
+ * neighbor that sent the Interest was previously marked as
+ * INACTIVE, NLSR will attempt to contact it with its own Hello
+ * Interest.
*/
void
processInterest(const ndn::Name& name, const ndn::Interest& interest);
@@ -98,29 +105,75 @@
ndn::util::signal::Signal<HelloProtocol, Statistics::PacketType> hpIncrementSignal;
private:
+ /*! \brief Try to contact a neighbor via Hello protocol again
+ *
+ * This function will re-send Hello Interests a configured number
+ * of times. After that many failures, HelloProtocol will mark the neighbor as
+ * inactive and will not attempt to contact them until the next time
+ * HelloProtocol::sendScheduledInterest is called.
+ *
+ * \sa nlsr::ConfParameter::getInterestRetryNumber
+ */
void
processInterestTimedOut(const ndn::Interest& interest);
+ /*! \brief Verify signatures and validate incoming Hello data.
+ */
void
onContent(const ndn::Interest& interest, const ndn::Data& data);
PUBLIC_WITH_TESTS_ELSE_PRIVATE:
+
+ /*! \brief Change a neighbor's status
+ *
+ * Whenever incoming Hello data is verified and validated, change
+ * the status of this neighbor and then schedule an adjacency LSA
+ * build for us. This also resets the number of times we've failed
+ * to contact this neighbor so that we will retry later.
+ */
void
onContentValidated(const std::shared_ptr<const ndn::Data>& data);
private:
+ /*! \brief Log that incoming data couldn't be validated, but do nothing else.
+ */
void
onContentValidationFailed(const std::shared_ptr<const ndn::Data>& data,
const std::string& msg);
+ /*! \brief Treat a failed Face registration as an INACTIVE neighbor.
+ *
+ * If NLSR fails to register a Face when contacting a neighbor, it
+ * will instantly toggle that neighbor to INACTIVE. This is
+ * necessary because NLSR will put off building its own adjacency
+ * LSA until the status of each neighbor is definitively
+ * known. Without this, NLSR might have to wait many scheduled Hello
+ * intervals to finish building an adjacency LSA.
+ */
void
onRegistrationFailure(const ndn::nfd::ControlResponse& response,
const ndn::Name& name);
+ /*! \brief Set up a Face for NLSR use.
+ *
+ * When NLSR receives a Hello Interest from a neighbor that it has
+ * not seen before, it may need to create a Face for that
+ * neighbor. After doing so, it will be necessary to inform NFD
+ * about the standard prefixes that NLSR needs a node to have in
+ * order to conduct normal operations. This function accomplishes
+ * that, and then sends its own Hello Interest to confirm the
+ * contact.
+ */
void
onRegistrationSuccess(const ndn::nfd::ControlParameters& commandSuccessResult,
const ndn::Name& neighbor, const ndn::time::milliseconds& timeout);
+ /*! \brief Create a Face for an adjacency
+ * \sa HelloProtocol::onRegistrationSuccess
+ */
+ void
+ registerPrefixes(const ndn::Name& adjName, const std::string& faceUri,
+ double linkCost, const ndn::time::milliseconds& timeout);
private:
Nlsr& m_nlsr;
ndn::Scheduler& m_scheduler;
diff --git a/src/logger.cpp b/src/logger.cpp
index 580fc3f..c51cd93 100644
--- a/src/logger.cpp
+++ b/src/logger.cpp
@@ -16,10 +16,10 @@
*
* You should have received a copy of the GNU General Public License along with
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
- *
- * \author A K M Mahmudul Hoque <ahoque1@memphis.edu>
- *
**/
+
+#include "logger.hpp"
+
#include <log4cxx/logger.h>
#include <log4cxx/basicconfigurator.h>
#include <log4cxx/xml/domconfigurator.h>
@@ -32,8 +32,6 @@
#include <boost/algorithm/string.hpp>
#include <boost/filesystem.hpp>
-#include "logger.hpp"
-
void
INIT_LOG4CXX(const std::string& log4cxxConfPath)
{
diff --git a/src/logger.hpp b/src/logger.hpp
index cf171a9..d75687c 100644
--- a/src/logger.hpp
+++ b/src/logger.hpp
@@ -16,11 +16,17 @@
*
* You should have received a copy of the GNU General Public License along with
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
- *
- * \author A K M Mahmudul Hoque <ahoque1@memphis.edu>
- *
**/
+/*! \file logger.hpp
+ * \brief Define macros and auxiliary functions for logging.
+ *
+ * This file defines the macros that NLSR uses for logging
+ * messages. An intrepid hacker could replace this system cleanly by
+ * providing a system that redefines all of the _LOG_* macros with an
+ * arbitrary system, as long as the underlying system accepts strings.
+ */
+
#ifndef NLSR_LOGGER_HPP
#define NLSR_LOGGER_HPP
diff --git a/src/nlsr-runner.hpp b/src/nlsr-runner.hpp
index 80ee8d6..7d4505e 100644
--- a/src/nlsr-runner.hpp
+++ b/src/nlsr-runner.hpp
@@ -32,6 +32,15 @@
namespace nlsr {
+/*! \brief A wrapper class to instantiate and configure an NLSR object.
+ *
+ * As its name suggests, this class is responsible for running
+ * NLSR. It creates an nlsr::ConfFileProcessor to read a configuration
+ * file and uses that to configure and then start an NLSR process. It
+ * also initializes loggers and optionally daemonizes the NLSR
+ * process. This class only exists to provide this functionality, and
+ * there is no special reliance of NLSR on this class.
+ */
class NlsrRunner
{
public:
@@ -47,6 +56,18 @@
NlsrRunner(std::string& configFileName, bool isDaemonProcess);
+ /*! \brief Instantiate, configure, and start the NLSR process.
+ *
+ * Each NlsrRunner is uniquely paired to the Face it's instantiated
+ * with. This is *not* a factory-type class, but a one-to-one
+ * relationship. If one wants to create multiple NLSR classes,
+ * multiple NLSR runners need to be created, too.
+ *
+ * \throws Error If the configuration file cannot be processed. NLSR
+ * is not started.
+ *
+ * \sa Nlsr::canonizeNeighborUris
+ */
void
run();
diff --git a/src/nlsr.hpp b/src/nlsr.hpp
index 54af8b4..89410e9 100644
--- a/src/nlsr.hpp
+++ b/src/nlsr.hpp
@@ -40,7 +40,9 @@
#include "utility/name-helper.hpp"
#include "stats-collector.hpp"
+#include <boost/cstdint.hpp>
#include <stdexcept>
+#include <boost/throw_exception.hpp>
#include <ndn-cxx/face.hpp>
#include <ndn-cxx/security/key-chain.hpp>
@@ -53,9 +55,6 @@
#include <ndn-cxx/data.hpp>
#include <ndn-cxx/encoding/block.hpp>
-#include <boost/cstdint.hpp>
-#include <boost/throw_exception.hpp>
-
namespace nlsr {
static ndn::Name DEFAULT_BROADCAST_PREFIX("/ndn/broadcast");
@@ -292,12 +291,24 @@
return m_validator;
}
+ /*! \brief Add a certificate NLSR claims to be authoritative for to the certificate store.
+ *
+ * \sa CertificateStore
+ */
void
loadCertToPublish(std::shared_ptr<ndn::IdentityCertificate> certificate)
{
m_certStore.insert(certificate);
}
+ /*! \brief Find a certificate
+ *
+ * Find a certificate that NLSR has. First it checks against the
+ * certificates this NLSR claims to be authoritative for, usually
+ * something like this specific router's certificate, and then
+ * checks the cache of certficates it has already fetched. If none
+ * can be found, it will return an empty pointer.
+ */
std::shared_ptr<const ndn::IdentityCertificate>
getCertificate(const ndn::Name& certificateNameWithoutVersion)
{
@@ -399,18 +410,28 @@
}
private:
+ /*! \brief Registers the prefix that NLSR will use for key/certificate interests.
+ */
void
registerKeyPrefix();
+ /*! \brief Registers the prefix that NLSR will consider to be the machine-local, secure prefix.
+ */
void
registerLocalhostPrefix();
+ /*! \brief Attempts to satisfy an Interest for a certificate, and send it back.
+ */
void
onKeyInterest(const ndn::Name& name, const ndn::Interest& interest);
+ /*! \brief Do nothing.
+ */
void
onKeyPrefixRegSuccess(const ndn::Name& name);
+ /*! \brief Do nothing.
+ */
void
onFaceEventNotification(const ndn::nfd::FaceEventNotification& faceEventNotification);
@@ -463,7 +484,13 @@
HelloProtocol m_helloProtocol;
private:
+ /*! \brief Where NLSR caches certificates it has fetched to validate
+ * Data signatures.
+ */
std::shared_ptr<ndn::CertificateCacheTtl> m_certificateCache;
+ /*! \brief Where NLSR stores certificates it claims to be
+ * authoritative for. Usually the router certificate.
+ */
security::CertificateStore m_certStore;
PUBLIC_WITH_TESTS_ELSE_PRIVATE:
diff --git a/src/publisher/lsa-publisher.hpp b/src/publisher/lsa-publisher.hpp
index 1c33242..6726b5a 100644
--- a/src/publisher/lsa-publisher.hpp
+++ b/src/publisher/lsa-publisher.hpp
@@ -44,7 +44,9 @@
ndn::Face& face,
ndn::KeyChain& keyChain);
- /*! \brief Returns the adj. LSAs represented by this object. */
+ /*! \brief Generates an TLV-format AdjacencyLsa from AdjacencyLsas
+ * and their Adjacents.
+ */
std::list<tlv::AdjacencyLsa>
getTlvLsas();
@@ -65,7 +67,9 @@
ndn::Face& face,
ndn::KeyChain& keyChain);
- /*! \brief Returns the cor. LSAs represented by this object. */
+ /*! \brief Generates a TLV-format CoordinateLsa from CoordinateLsas
+ * and their hyperbolic coordinates.
+ */
std::list<tlv::CoordinateLsa>
getTlvLsas();
@@ -85,7 +89,10 @@
NameLsaPublisher(Lsdb& lsdb,
ndn::Face& face,
ndn::KeyChain& keyChain);
- /*! \brief Returns the name LSAs represented by this object. */
+
+ /*! \brief Generates a TLV-format NameLsa from NameLsas and their
+ * list of name prefixes.
+ */
std::list<tlv::NameLsa>
getTlvLsas();
diff --git a/src/publisher/lsdb-dataset-interest-handler.hpp b/src/publisher/lsdb-dataset-interest-handler.hpp
index f8aa025..b92a72f 100644
--- a/src/publisher/lsdb-dataset-interest-handler.hpp
+++ b/src/publisher/lsdb-dataset-interest-handler.hpp
@@ -69,7 +69,8 @@
}
private:
- /*! \brief set dispatcher for localhost/router name.
+ /*! \brief Capture-point for Interests to verify Interests are
+ * valid, and then process them.
*/
void
setDispatcher(ndn::mgmt::Dispatcher& dispatcher);
diff --git a/src/publisher/segment-publisher.hpp b/src/publisher/segment-publisher.hpp
index 82109eb..59c44b4 100644
--- a/src/publisher/segment-publisher.hpp
+++ b/src/publisher/segment-publisher.hpp
@@ -52,6 +52,8 @@
{
}
+ /*! \brief Define the max segment size as half the max NDN packet size.
+ */
static size_t
getMaxSegmentSize()
{
@@ -65,7 +67,12 @@
return ndn::time::milliseconds(1000);
}
- /*! \brief Publish data under provided prefix
+ /*! \brief Publish data under the provided prefix
+ *
+ * Processes whatever is provided from SegmentPublisher::generate,
+ * by breaking it into segments of MAX_SEGMENT_SIZE and sending each
+ * one individually. The last segment is distinguished by having the
+ * final block ID set to a timestamp.
*/
void
publish(const ndn::Name& prefix,
@@ -112,6 +119,8 @@
generate(ndn::EncodingBuffer& outBuffer) = 0;
private:
+ /*! \brief Helper function to sign and put data on a Face.
+ */
void
publishSegment(std::shared_ptr<ndn::Data>& data, const ndn::security::SigningInfo& signingInfo)
{
diff --git a/src/route/fib.cpp b/src/route/fib.cpp
index 0eb6d16..de73310 100644
--- a/src/route/fib.cpp
+++ b/src/route/fib.cpp
@@ -48,6 +48,7 @@
(it->second).getNexthopList().getNextHops().begin();
nhit != (it->second).getNexthopList().getNextHops().end(); nhit++) {
//remove entry from NDN-FIB
+ // Only unregister the prefix if it ISN'T a neighbor.
if (isPrefixUpdatable((it->second).getName())) {
unregisterPrefix((it->second).getName(), nhit->getConnectingFaceUri());
}
diff --git a/src/route/fib.hpp b/src/route/fib.hpp
index 4f15655..5761a3d 100644
--- a/src/route/fib.hpp
+++ b/src/route/fib.hpp
@@ -38,6 +38,19 @@
class ConfParameter;
class FibEntry;
+/*! \brief Maps names to lists of next hops, and exports this information to NFD.
+ *
+ * The FIB (Forwarding Information Base) is the "authoritative" source
+ * of how to route Interests on this router to other nodes running
+ * NLSR. In essence, the FIB is a map that takes name prefixes to a
+ * list of next-hops out of this router. This class also contains
+ * methods to inform NFD about these relationships. The FIB has its
+ * entries populated by the NamePrefixTable
+ *
+ * \sa nlsr::NamePrefixTable
+ * \sa nlsr::NamePrefixTable::addEntry
+ * \sa nlsr::NamePrefixTable::updateWithNewRoute
+ */
class Fib
{
public:
@@ -51,15 +64,42 @@
{
}
- FibEntry*
- processUpdate(const ndn::Name& name, NexthopList& allHops);
-
+ /*! \brief Completely remove a name prefix from the FIB.
+ *
+ * If a name prefix is found to no longer be reachable from this
+ * router, it will be removed from the FIB and all of its next-hops
+ * will be unregistered from NFD.
+ *
+ * \sa nlsr::NamePrefixTable::removeEntry
+ */
VIRTUAL_WITH_TESTS void
remove(const ndn::Name& name);
+ /*! \brief Set the nexthop list of a name.
+ *
+ * This method is the entry for others to add next-hop information
+ * to the FIB. Formally put, this method registers in NFD all
+ * next-hops in allHops, and unregisters the set difference of
+ * newHops - oldHops. This method also schedules the regular refresh
+ * of those next hops.
+ *
+ * \param name The name prefix that the next-hops apply to
+ * \param allHops A complete list of next-hops to associate with name.
+ */
VIRTUAL_WITH_TESTS void
update(const ndn::Name& name, NexthopList& allHops);
+ /*! \brief Remove all entries from the FIB.
+ *
+ * This method is called before terminating NLSR to minimize the
+ * time NFD spends routing on now-invalid information. This is not
+ * strictly necessary, because eventually those prefix registrations
+ * will expire, but cleaning up after ourselves improves
+ * performance.
+ *
+ * \sa NlsrRunner::run
+ *
+ */
void
clean();
@@ -69,6 +109,26 @@
m_refreshTime = fert;
}
+ /*! \brief Inform NFD of a next-hop
+ *
+ * This method informs NFD of a next-hop for some name prefix. This
+ * method actually submits the information to NFD's RIB, which then
+ * aggregates its own best hops and updates NFD's (the actual)
+ * FIB. Typically, NLSR's FIB and NFD's FIB will be almost the
+ * same. However, this is not necessarily the case and there may be
+ * cases when other sources of information provide better next-hops
+ * to NFD that NLSR doesn't know about. For example, an operator
+ * could set up a direct link to a node that isn't running NLSR.
+ *
+ * \param namePrefix The name prefix to register a next-hop for
+ * \param faceUri The faceUri of the adjacent that this prefix can be reached through
+ * \param faceCost The cost to reach namePrefix through faceUri
+ * \param timeout How long this registration should last
+ * \param flags Route inheritance flags (CAPTURE, CHILD_INHERIT)
+ * \param times How many times we have failed to register this prefix since the last success.
+ *
+ * \sa Fib::registerPrefixInNfd
+ */
void
registerPrefix(const ndn::Name& namePrefix,
const ndn::util::FaceUri& faceUri,
@@ -84,22 +144,39 @@
writeLog();
private:
+ /*! \brief Indicates whether a prefix is a direct neighbor or not.
+ *
+ * \return Whether the name is NOT associated with a direct neighbor
+ */
bool
isPrefixUpdatable(const ndn::Name& name);
+ /*! \brief Does one half of the updating of a FibEntry with new next-hops.
+ *
+ * Adds nexthops to a FibEntry and registers them in NFD.
+ * \sa Fib::update
+ * \sa Fib::removeOldNextHopsFromFibEntryAndNfd
+ */
void
addNextHopsToFibEntryAndNfd(FibEntry& entry, NexthopList& hopsToAdd);
unsigned int
getNumberOfFacesForName(NexthopList& nextHopList);
+ /*! \brief Unregisters a prefix from NFD's RIB.
+ *
+ */
void
unregisterPrefix(const ndn::Name& namePrefix, const std::string& faceUri);
+ /*! \brief Log registration success, and update the Face ID associated with a URI.
+ */
void
onRegistrationSuccess(const ndn::nfd::ControlParameters& commandSuccessResult,
const std::string& message, const ndn::util::FaceUri& faceUri);
+ /*! \brief Retry a prefix (next-hop) registration up to three (3) times.
+ */
void
onRegistrationFailure(const ndn::nfd::ControlResponse& response,
const std::string& message,
@@ -107,18 +184,26 @@
const ndn::util::FaceUri& faceUri,
uint8_t times);
+ /*! \brief Log a successful unregistration.
+ */
void
onUnregistrationSuccess(const ndn::nfd::ControlParameters& commandSuccessResult,
const std::string& message);
+ /*! \brief Log an unregistration failure. Does not retry.
+ */
void
onUnregistrationFailure(const ndn::nfd::ControlResponse& response,
const std::string& message);
+ /*! \brief Log a successful strategy setting.
+ */
void
onSetStrategySuccess(const ndn::nfd::ControlParameters& commandSuccessResult,
const std::string& message);
+ /*! \brief Retry a strategy setting up to three (3) times.
+ */
void
onSetStrategyFailure(const ndn::nfd::ControlResponse& response,
const ndn::nfd::ControlParameters& parameters,
@@ -126,16 +211,45 @@
const std::string& message);
PUBLIC_WITH_TESTS_ELSE_PRIVATE:
+ /*! \brief Internal portion of Fib::update.
+ * \sa Fib::update
+ */
+ FibEntry*
+ processUpdate(const ndn::Name& name, NexthopList& allHops);
+
+ /*! \brief Schedule a refresh event for an entry.
+ *
+ * Schedules a refresh event for an entry. In order to form a
+ * perpetual loop, refreshCallback needs to call
+ * Fib::scheduleEntryRefresh in some way, with refreshCallback being
+ * the same each time. In the current implementation, this is
+ * accomplished by having a separate function, Fib::scheduleLoop,
+ * that does this work.
+ * \sa Fib::scheduleLoop
+ */
void
scheduleEntryRefresh(FibEntry& entry, const afterRefreshCallback& refreshCb);
private:
+ /*! \brief Continue the entry refresh cycle.
+ */
void
scheduleLoop(FibEntry& entry);
+ /*! \brief Cancel an entry's refresh event.
+ *
+ * Cancel an entry's refresh event. This only needs to be done when
+ * an entry is removed. Typically this happens when NLSR is
+ * terminated or crashes, and we don't want the scheduler to crash
+ * because it's referencing memory that has no valid function.
+ *
+ * \sa NlsrRunner::run
+ */
void
cancelEntryRefresh(const FibEntry& entry);
+ /*! \brief Refreshes an entry in NFD.
+ */
void
refreshEntry(const ndn::Name& name, afterRefreshCallback refreshCb);
@@ -152,6 +266,10 @@
AdjacencyList& m_adjacencyList;
ConfParameter& m_confParameter;
+ /*! GRACE_PERIOD A "window" we append to the timeout time to
+ * allow for things like stuttering prefix registrations and
+ * processing time when refreshing events.
+ */
static const uint64_t GRACE_PERIOD;
};
diff --git a/src/route/map-entry.hpp b/src/route/map-entry.hpp
index ab8ba98..84f3dd1 100644
--- a/src/route/map-entry.hpp
+++ b/src/route/map-entry.hpp
@@ -17,9 +17,8 @@
* You should have received a copy of the GNU General Public License along with
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
*
- * \author A K M Mahmudul Hoque <ahoque1@memphis.edu>
- *
**/
+
#ifndef NLSR_MAP_ENTRY_HPP
#define NLSR_MAP_ENTRY_HPP
diff --git a/src/route/name-prefix-table-entry.hpp b/src/route/name-prefix-table-entry.hpp
index e88166b..b345231 100644
--- a/src/route/name-prefix-table-entry.hpp
+++ b/src/route/name-prefix-table-entry.hpp
@@ -56,6 +56,9 @@
return m_rteList;
}
+ /*! \brief Resets the next hop lists of all routing table entries
+ * that advertise this name prefix.
+ */
void
resetRteListNextHop()
{
@@ -78,24 +81,25 @@
return m_nexthopList;
}
- /*! \brief Generates a next-hop list from routing table entries. */
+ /*! \brief Collect all next-hops that are advertised by this entry's
+ * routing entries.
+ */
void
generateNhlfromRteList();
/*! \brief Removes a routing entry from this NPT entry.
- \param rtpePtr The routing entry
- \return The remaining number of other NPTs using the removed routing entry.
- */
+ * \return The number of NPTs using the just-removed routing entry.
+ */
uint64_t
removeRoutingTableEntry(std::shared_ptr<RoutingTablePoolEntry> rtpePtr);
/*! \brief Adds a routing entry to this NPT entry.
- \param rtpePtr The routing entry.
-
- Adds a routing table pool entry to this NPT entry's list
- (reminder: each RTPE has a next-hop list). They are used to
- calculate this entry's overall next-hop list.
- */
+ * \param rtpePtr The routing entry.
+ *
+ * Adds a routing table pool entry to this NPT entry's list
+ * (reminder: each RTPE has a next-hop list). They are used to
+ * calculate this entry's overall next-hop list.
+ */
void
addRoutingTableEntry(std::shared_ptr<RoutingTablePoolEntry> rtpePtr);
diff --git a/src/route/nexthop-list.hpp b/src/route/nexthop-list.hpp
index 918cab2..b35f3bf 100644
--- a/src/route/nexthop-list.hpp
+++ b/src/route/nexthop-list.hpp
@@ -17,18 +17,19 @@
* You should have received a copy of the GNU General Public License along with
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
**/
+
#ifndef NLSR_NEXTHOP_LIST_HPP
#define NLSR_NEXTHOP_LIST_HPP
+#include "nexthop.hpp"
+#include "adjacent.hpp"
+
#include <set>
#include <iostream>
#include <boost/cstdint.hpp>
#include <ndn-cxx/face.hpp>
-#include "nexthop.hpp"
-#include "adjacent.hpp"
-
namespace nlsr {
struct NextHopComparator {
@@ -144,4 +145,4 @@
} // namespace nlsr
-#endif //NLSR_NEXTHOP_LIST_HPP
+#endif // NLSR_NEXTHOP_LIST_HPP
diff --git a/src/route/routing-table-entry.hpp b/src/route/routing-table-entry.hpp
index b553fa1..6e01c45 100644
--- a/src/route/routing-table-entry.hpp
+++ b/src/route/routing-table-entry.hpp
@@ -17,15 +17,15 @@
* You should have received a copy of the GNU General Public License along with
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
*
- * \author A K M Mahmudul Hoque <ahoque1@memphis.edu>
- *
**/
+
#ifndef NLSR_ROUTING_TABLE_ENTRY_HPP
#define NLSR_ROUTING_TABLE_ENTRY_HPP
+#include "nexthop-list.hpp"
+
#include <iostream>
#include <ndn-cxx/name.hpp>
-#include "nexthop-list.hpp"
namespace nlsr {
diff --git a/src/route/routing-table-pool-entry.hpp b/src/route/routing-table-pool-entry.hpp
index 0e64386..ff84dfe 100644
--- a/src/route/routing-table-pool-entry.hpp
+++ b/src/route/routing-table-pool-entry.hpp
@@ -17,19 +17,32 @@
* You should have received a copy of the GNU General Public License along with
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
*
- * \author Nicholas Gordon <nmgordon@memphis.edu>
- *
**/
#ifndef NLSR_ROUTING_TABLE_POOL_ENTRY_HPP
#define NLSR_ROUTING_TABLE_POOL_ENTRY_HPP
+#include "routing-table-entry.hpp"
+#include "nexthop-list.hpp"
+
#include <iostream>
#include <ndn-cxx/name.hpp>
-#include "nexthop-list.hpp"
-#include "routing-table-entry.hpp"
namespace nlsr {
+
+/*! \brief A deduplication system for the NamePrefixTable
+ *
+ * The NamePrefixTable associates name prefixes to a router. To do
+ * this, it needs to know if certain routers are reachable. This in
+ * turn requires access to entries from the RoutingTable, which are
+ * associated with name prefixes. Doing this naively copies the entry
+ * from the RoutingTable each time, which is costly. This class
+ * provides a deduplication system where the NamePrefixTable can
+ * maintain a collection of RoutingTablePoolEntries. Then, this new
+ * class can be associated with the name prefixes instead of the
+ * original entries, which provides a minimal memory solution.
+ * \sa NamePrefixTable
+ */
class RoutingTablePoolEntry : public RoutingTableEntry
{
public:
diff --git a/src/route/routing-table.hpp b/src/route/routing-table.hpp
index 903ca79..b138c9d 100644
--- a/src/route/routing-table.hpp
+++ b/src/route/routing-table.hpp
@@ -23,15 +23,15 @@
#ifndef NLSR_ROUTING_TABLE_HPP
#define NLSR_ROUTING_TABLE_HPP
+#include "conf-parameter.hpp"
+#include "routing-table-entry.hpp"
+
#include <iostream>
#include <utility>
#include <string>
#include <boost/cstdint.hpp>
#include <ndn-cxx/util/scheduler.hpp>
-#include "conf-parameter.hpp"
-#include "routing-table-entry.hpp"
-
namespace nlsr {
class Nlsr;
@@ -48,33 +48,34 @@
}
/*! \brief Calculates a list of next hops for each router in the network.
- \param pnlsr The NLSR object that contains the LSAs needed for adj. info.
-
- Calculates the list of next hops to every other router in the network.
- */
+ * \param pnlsr The NLSR object that contains the LSAs needed for adj. info.
+ *
+ * Calculates the list of next hops to every other router in the network.
+ */
void
calculate(Nlsr& pnlsr);
/*! \brief Adds a next hop to a routing table entry.
- \param destRouter The destination router whose RTE we want to modify.
- \param nh The next hop to add to the RTE.
- */
+ * \param destRouter The destination router whose RTE we want to modify.
+ * \param nh The next hop to add to the RTE.
+ */
void
addNextHop(const ndn::Name& destRouter, NextHop& nh);
/*! \brief Adds a next hop to a routing table entry in a dry run scenario.
- \param destRouter The destination router whose RTE we want to modify.
- \param nh The next hop to add to the router.
- */
+ * \param destRouter The destination router whose RTE we want to modify.
+ * \param nh The next hop to add to the router.
+ */
void
addNextHopToDryTable(const ndn::Name& destRouter, NextHop& nh);
RoutingTableEntry*
findRoutingTableEntry(const ndn::Name& destRouter);
- /*! \brief Schedules a calculation event in the event scheduler.
- \param pnlsr The NLSR whose scheduling status is needed.
- */
+ /*! \brief Schedules a calculation event in the event scheduler only
+ * if one isn't already scheduled.
+ * \param pnlsr The NLSR whose scheduling status is needed.
+ */
void
scheduleRoutingTableCalculation(Nlsr& pnlsr);
@@ -131,4 +132,4 @@
} // namespace nlsr
-#endif //NLSR_ROUTING_TABLE_HPP
+#endif // NLSR_ROUTING_TABLE_HPP
diff --git a/src/security/certificate-store.hpp b/src/security/certificate-store.hpp
index b591fe7..4b84df6 100644
--- a/src/security/certificate-store.hpp
+++ b/src/security/certificate-store.hpp
@@ -31,6 +31,13 @@
namespace nlsr {
namespace security {
+/*! \brief Store certificates for names
+ *
+ * Stores certificates that this router claims to be authoritative
+ * for. That is, this stores only the certificates that we will reply
+ * to KEY interests with, e.g. when other routers are verifying data
+ * we have sent.
+ */
class CertificateStore
{
public:
diff --git a/src/tlv/adjacency-lsa.hpp b/src/tlv/adjacency-lsa.hpp
index 217366a..f1854a4 100644
--- a/src/tlv/adjacency-lsa.hpp
+++ b/src/tlv/adjacency-lsa.hpp
@@ -43,7 +43,7 @@
LsaInfo
Adjacency*
- \sa http://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
+ \sa https://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
*/
class AdjacencyLsa
{
@@ -109,13 +109,33 @@
return *this;
}
+ /*! \brief Encodes the Adjacent objects and some info using the method in TAG.
+ *
+ * This function will TLV-format the Adjacent objects and some LSA
+ * info using the implementation speciifed by TAG. Usually this is
+ * called with an estimator first to guess how long the buffer needs
+ * to be, then with an encoder to do the real work. This process is
+ * automated by the other wireEncode.
+ * \sa AdjacencyLsa::wireEncode()
+ */
template<ndn::encoding::Tag TAG>
size_t
wireEncode(ndn::EncodingImpl<TAG>& block) const;
+ /*! \brief Create a TLV encoding of this object.
+ *
+ * Create a block containing the TLV encoding of this object. That
+ * involves two steps: estimating the size that the information will
+ * take up, and then creating a buffer of that size and encoding the
+ * information into it. Both steps are accomplished by
+ * AdjacencyLsa::wireEncode(ndn::EncodingImpl<TAG>&)
+ */
const ndn::Block&
wireEncode() const;
+ /*! \brief Populate this object by decoding the one contained in the
+ * given block.
+ */
void
wireDecode(const ndn::Block& wire);
diff --git a/src/tlv/adjacency.hpp b/src/tlv/adjacency.hpp
index 5767ce6..2e5dec7 100644
--- a/src/tlv/adjacency.hpp
+++ b/src/tlv/adjacency.hpp
@@ -39,7 +39,7 @@
Uri
Cost
- \sa http://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
+ \sa https://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
*/
class Adjacency
{
@@ -101,13 +101,31 @@
return *this;
}
+ /*! \brief TLV-encode this object using the implementation in from TAG.
+ *
+ * This method TLV-encodes this Adjacency object using the
+ * implementation given by TAG. Usually two implementations are
+ * provided: a size estimator and a real encoder, which are used in
+ * sequence to allocate the necessary block size and then encode it.
+ * \sa Adjacency::wireEncode()
+ */
template<ndn::encoding::Tag TAG>
size_t
wireEncode(ndn::EncodingImpl<TAG>& block) const;
+ /*! \brief Create a TLV encoding of this object.
+ *
+ * This function automates the process of guessing the necessary
+ * size of a block containing this object, and then creating a block
+ * and putting the TLV encoding into it.
+ * \sa Adjacency::wireEncode(ndn::EncodingImpl<TAG>&)
+ */
const ndn::Block&
wireEncode() const;
+ /*! \brief Populate this object by decoding the object contained in
+ * the given block.
+ */
void
wireDecode(const ndn::Block& wire);
diff --git a/src/tlv/coordinate-lsa.hpp b/src/tlv/coordinate-lsa.hpp
index 0568cc1..18c32ab 100644
--- a/src/tlv/coordinate-lsa.hpp
+++ b/src/tlv/coordinate-lsa.hpp
@@ -103,13 +103,33 @@
return *this;
}
+ /*! \brief Encodes the hyperbolic coordinates and some info using the method in TAG.
+ *
+ * This function will TLV-format the hyperbolic coordinates objects and some LSA
+ * info using the implementation speciifed by TAG. Usually this is
+ * called with an estimator first to guess how long the buffer needs
+ * to be, then with an encoder to do the real work. This process is
+ * automated by the other wireEncode.
+ * \sa CoordinateLsa::wireEncode()
+ */
template<ndn::encoding::Tag TAG>
size_t
wireEncode(ndn::EncodingImpl<TAG>& block) const;
+ /*! \brief Create a TLV encoding of this object.
+ *
+ * Create a block containing the TLV encoding of this object. That
+ * involves two steps: estimating the size that the information will
+ * take up, and then creating a buffer of that size and encoding the
+ * information into it. Both steps are accomplished by
+ * CoordinateLsa::wireEncode(ndn::EncodingImpl<TAG>&)
+ */
const ndn::Block&
wireEncode() const;
+ /*! \brief Populate this object by decoding the one contained in the
+ * given block.
+ */
void
wireDecode(const ndn::Block& wire);
diff --git a/src/tlv/lsa-info.hpp b/src/tlv/lsa-info.hpp
index ef2142a..4573661 100644
--- a/src/tlv/lsa-info.hpp
+++ b/src/tlv/lsa-info.hpp
@@ -22,6 +22,8 @@
#ifndef NLSR_TLV_LSA_INFO_HPP
#define NLSR_TLV_LSA_INFO_HPP
+#include "lsa.hpp"
+
#include <ndn-cxx/util/time.hpp>
#include <ndn-cxx/encoding/block.hpp>
#include <ndn-cxx/encoding/encoding-buffer.hpp>
@@ -29,8 +31,6 @@
#include <ndn-cxx/name.hpp>
#include <boost/throw_exception.hpp>
-#include "lsa.hpp"
-
namespace nlsr {
namespace tlv {
@@ -115,13 +115,33 @@
return m_hasInfiniteExpirationPeriod;
}
+ /*! \brief Encodes LSA info using the method in TAG.
+ *
+ * This function will TLV-format LSA info using the implementation
+ * speciifed by TAG. Usually this is called with an estimator first
+ * to guess how long the buffer needs to be, then with an encoder to
+ * do the real work. This process is automated by the other
+ * wireEncode.
+ * \sa LsaInfo::wireEncode()
+ */
template<ndn::encoding::Tag TAG>
size_t
wireEncode(ndn::EncodingImpl<TAG>& block) const;
+ /*! \brief Create a TLV encoding of this object.
+ *
+ * Create a block containing the TLV encoding of this object. That
+ * involves two steps: estimating the size that the information will
+ * take up, and then creating a buffer of that size and encoding the
+ * information into it. Both steps are accomplished by
+ * LsaInfo::wireEncode(ndn::EncodingImpl<TAG>&)
+ */
const ndn::Block&
wireEncode() const;
+ /*! \brief Populate this object by decoding the one contained in the
+ * given block.
+ */
void
wireDecode(const ndn::Block& wire);
diff --git a/src/tlv/lsdb-status.hpp b/src/tlv/lsdb-status.hpp
index 5fc8f8c..fb494e6 100644
--- a/src/tlv/lsdb-status.hpp
+++ b/src/tlv/lsdb-status.hpp
@@ -45,7 +45,7 @@
CoordinateLsa*
NameLsa*
- \sa http://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
+ \sa https://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
*/
class LsdbStatus
{
@@ -156,13 +156,34 @@
return m_hasNameLsas;
}
+ /*! \brief Encodes the LSA objects and some info for each LSA using
+ * the method in TAG.
+ *
+ * This function will TLV-format the LSA objects and some LSA
+ * info using the implementation specified by TAG. Usually this is
+ * called with an estimator first to guess how long the buffer needs
+ * to be, then with an encoder to do the real work. This process is
+ * automated by the other wireEncode.
+ * \sa LsdbStatus::wireEncode()
+ */
template<ndn::encoding::Tag TAG>
size_t
wireEncode(ndn::EncodingImpl<TAG>& block) const;
+ /*! \brief Create a TLV encoding of this object.
+ *
+ * Create a block containing the TLV encoding of this object. That
+ * involves two steps: estimating the size that the information will
+ * take up, and then creating a buffer of that size and encoding the
+ * information into it. Both steps are accomplished by
+ * LsdbStatus::wireEncode(ndn::EncodingImpl<TAG>&)
+ */
const ndn::Block&
wireEncode() const;
+ /*! \brief Populate this object by decoding the one contained in the
+ * given block.
+ */
void
wireDecode(const ndn::Block& wire);
diff --git a/src/tlv/name-lsa.hpp b/src/tlv/name-lsa.hpp
index e120af8..2e137be 100644
--- a/src/tlv/name-lsa.hpp
+++ b/src/tlv/name-lsa.hpp
@@ -42,7 +42,7 @@
LsaInfo
Name+
- \sa http://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
+ \sa https://redmine.named-data.net/projects/nlsr/wiki/LSDB_DataSet
*/
class NameLsa
{
@@ -108,13 +108,33 @@
return *this;
}
+ /*! \brief Encodes the Name objects and some info using the method in TAG.
+ *
+ * This function will TLV-format the Name objects and some LSA
+ * info using the implementation speciifed by TAG. Usually this is
+ * called with an estimator first to guess how long the buffer needs
+ * to be, then with an encoder to do the real work. This process is
+ * automated by the other wireEncode.
+ * \sa NameLsa::wireEncode()
+ */
template<ndn::encoding::Tag TAG>
size_t
wireEncode(ndn::EncodingImpl<TAG>& block) const;
+ /*! \brief Create a TLV encoding of this object.
+ *
+ * Create a block containing the TLV encoding of this object. That
+ * involves two steps: estimating the size that the information will
+ * take up, and then creating a buffer of that size and encoding the
+ * information into it. Both steps are accomplished by
+ * NameLsa::wireEncode(ndn::EncodingImpl<TAG>&)
+ */
const ndn::Block&
wireEncode() const;
+ /*! \brief Populate this object by decoding the one contained in the
+ * given block.
+ */
void
wireDecode(const ndn::Block& wire);
diff --git a/src/tlv/tlv-nlsr.hpp b/src/tlv/tlv-nlsr.hpp
index e202b64..4a52b1b 100644
--- a/src/tlv/tlv-nlsr.hpp
+++ b/src/tlv/tlv-nlsr.hpp
@@ -24,11 +24,15 @@
#include <ndn-cxx/encoding/tlv.hpp>
-namespace ndn {
-namespace tlv {
+namespace ndn {
+namespace tlv {
namespace nlsr {
-// LSDB DataSet
+/*! The TLV block types that NLSR uses to encode/decode LSA types. The
+ * way NLSR encodes LSAs to TLV is by encoding each element of the
+ * LSA as a separate TLV block. So, block types are needed. These are
+ * used in the LSDB Status Dataset.
+ */
enum {
LsaInfo = 128,
OriginRouter = 129,
diff --git a/src/update/nfd-rib-commands.hpp b/src/update/nfd-rib-commands.hpp
index 39ecb5f..b259b7e 100644
--- a/src/update/nfd-rib-commands.hpp
+++ b/src/update/nfd-rib-commands.hpp
@@ -19,6 +19,21 @@
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
**/
+/*! \file
+ * Define parameters for NFD RIB commands
+ *
+ * When validating an NFD RIB command, NLSR is only concerned with the
+ * name in the command. However, a request is rejected if it has
+ * unsolicited fields, so the origin, which is set by NFD's RIB, must
+ * be considered optional. We consider these to be secure because they
+ * are currently only received over the localhost prefix. These serve
+ * to support NFD RIB to NLSR route readvertising.
+ *
+ * \sa NfdRibCommandProcessor
+ * \sa nlsr::Nlsr::LOCALHOST_PREFIX
+ * \sa nlsr::Nlsr::getDispatcher
+ */
+
#ifndef UPDATE_NFD_RIB_COMMANDS_HPP
#define UPDATE_NFD_RIB_COMMANDS_HPP
diff --git a/src/update/prefix-update-commands.hpp b/src/update/prefix-update-commands.hpp
index 9cb2790..ce851a9 100644
--- a/src/update/prefix-update-commands.hpp
+++ b/src/update/prefix-update-commands.hpp
@@ -19,6 +19,18 @@
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
**/
+/*! \file
+ * Define parameters for commands to manipulate advertised name prefixes
+ *
+ * These classes serve to define what parameters are required for
+ * Prefix Update commands. We assume these commands are secure because
+ * they are received on the localhost prefix. We require that a name
+ * be present to action upon, and also that our response have a
+ * name. Responses are only sent on failures.
+ *
+ * \sa PrefixUpdateProcessor
+ */
+
#ifndef NLSR_UPDATE_PREFIX_UPDATE_COMMANDS_HPP
#define NLSR_UPDATE_PREFIX_UPDATE_COMMANDS_HPP
diff --git a/src/update/prefix-update-processor.hpp b/src/update/prefix-update-processor.hpp
index 6ee9506..52780e6 100644
--- a/src/update/prefix-update-processor.hpp
+++ b/src/update/prefix-update-processor.hpp
@@ -55,6 +55,18 @@
ndn::KeyChain& keyChain,
std::shared_ptr<ndn::CertificateCacheTtl> certificateCache,
security::CertificateStore& certStore);
+
+ /*! \brief Load the validator's configuration from a section of a
+ * configuration file.
+ * \sa ConfFileProcessor::processConfFile
+ * \sa ConfFileProcessor::processConfSectionSecurity
+ *
+ * Loads the state of the validator for prefix update commands by
+ * reading a section from a configuration file. This function is
+ * expecting the section to be from a Boost property tree object.
+ *
+ * \throws PrefixUpdateProcessor::Error If configuration fails to load successfully
+ */
void
loadValidator(ConfigSection section, const std::string& filename);