docs: Updating doxygen comments and minor update to normalize API
Change-Id: I24686acc36f372ee2eddffaaa6c104f964ceeca4
Refs: #1299
diff --git a/src/data.hpp b/src/data.hpp
index 88ffcc4..66b2849 100644
--- a/src/data.hpp
+++ b/src/data.hpp
@@ -39,17 +39,39 @@
/**
* @brief Create an empty Data object
+ *
+ * Note that in certain contexts that use Data::shared_from_this(), Data must be
+ * created using `make_shared`:
+ *
+ * shared_ptr<Data> data = make_shared<Data>();
+ *
+ * Otherwise, Data::shared_from_this() will throw an exception.
*/
Data();
/**
* @brief Create a new Data object with the given name
- * @param name A reference to the name which is copied.
+ *
+ * @param name A reference to the name
+ *
+ * Note that in certain contexts that use Data::shared_from_this(), Data must be
+ * created using `make_shared`:
+ *
+ * shared_ptr<Data> data = make_shared<Data>(name);
+ *
+ * Otherwise, Data::shared_from_this() will throw an exception.
*/
Data(const Name& name);
/**
* @brief Create a new Data object from wire encoding
+ *
+ * Note that in certain contexts that use Data::shared_from_this(), Data must be
+ * created using `make_shared`:
+ *
+ * shared_ptr<Data> data = make_shared<Data>(wire);
+ *
+ * Otherwise, Data::shared_from_this() will throw an exception.
*/
explicit
Data(const Block& wire)
@@ -58,11 +80,6 @@
}
/**
- * @brief The destructor
- */
- ~Data();
-
- /**
* @brief Fast encoding or block size estimation
*/
template<bool T>
@@ -82,36 +99,41 @@
wireDecode(const Block& wire);
/**
- * @brief Check if already has wire
+ * @brief Check if Data is already has wire encoding
*/
bool
hasWire() const;
////////////////////////////////////////////////////////////////////
+ /**
+ * @brief Get name of the Data packet
+ */
const Name&
getName() const;
/**
- * @brief Set name to a copy of the given Name.
+ * @brief Set name to a copy of the given Name
*
- * @param name The Name which is copied.
- * @return This Data so that you can chain calls to update values.
+ * @return This Data so that you can chain calls to update values
*/
- void
+ Data&
setName(const Name& name);
//
+ /**
+ * @brief Get MetaInfo block from Data packet
+ */
const MetaInfo&
getMetaInfo() const;
/**
- * @brief Set metaInfo to a copy of the given MetaInfo.
- * @param metaInfo The MetaInfo which is copied.
+ * @brief Set metaInfo to a copy of the given MetaInfo
+ *
* @return This Data so that you can chain calls to update values.
*/
- void
+ Data&
setMetaInfo(const MetaInfo& metaInfo);
//
@@ -124,7 +146,7 @@
uint32_t
getContentType() const;
- void
+ Data&
setContentType(uint32_t type);
//
@@ -132,7 +154,7 @@
const time::milliseconds&
getFreshnessPeriod() const;
- void
+ Data&
setFreshnessPeriod(const time::milliseconds& freshnessPeriod);
//
@@ -140,7 +162,7 @@
const name::Component&
getFinalBlockId() const;
- void
+ Data&
setFinalBlockId(const name::Component& finalBlockId);
//
@@ -158,17 +180,46 @@
getContent() const;
/**
- * @brief Set the content to a copy of the data in the vector.
- * @param content A vector whose contents are copied.
+ * @brief Set the content from the buffer (buffer will be copied)
+ *
+ * @param buffer Pointer to first byte of the buffer
+ * @param bufferSize Size of the buffer
+ *
* @return This Data so that you can chain calls to update values.
*/
- void
- setContent(const uint8_t* content, size_t contentLength);
+ Data&
+ setContent(const uint8_t* buffer, size_t bufferSize);
- void
- setContent(const Block& content);
+ /**
+ * @brief Set the content from the block
+ *
+ * Depending on type of the supplied block, there are two cases:
+ *
+ * - if block.type() == Tlv::Content, then block will be used directly as Data packet's
+ * content (no extra copying)
+ *
+ * - if block.type() != Tlv::Content, then this method will create a new Block with type
+ * Tlv::Content and put block as a nested element in the content Block.
+ *
+ * @param block The Block containing the content to assign
+ *
+ * @return This Data so that you can chain calls to update values.
+ */
+ Data&
+ setContent(const Block& block);
- void
+ /**
+ * @brief Set the content from the pointer to immutable buffer
+ *
+ * This method will create a Block with Tlv::Content and set contentValue as a payload
+ * for this block. Note that this method is very different from setContent(const
+ * Block&), since it does not require that payload should be a valid TLV element.
+ *
+ * @param contentValue The pointer to immutable buffer containing the content to assign
+ *
+ * @return This Data so that you can chain calls to update values.
+ */
+ Data&
setContent(const ConstBufferPtr& contentValue);
//
@@ -180,10 +231,10 @@
* @brief Set the signature to a copy of the given signature.
* @param signature The signature object which is cloned.
*/
- void
+ Data&
setSignature(const Signature& signature);
- void
+ Data&
setSignatureValue(const Block& value);
///////////////////////////////////////////////////////////////
@@ -197,7 +248,7 @@
uint64_t
getIncomingFaceId() const;
- void
+ Data&
setIncomingFaceId(uint64_t incomingFaceId);
public: // EqualityComparable concept
@@ -238,11 +289,6 @@
{
}
-inline
-Data::~Data()
-{
-}
-
template<bool T>
inline size_t
Data::wireEncode(EncodingImpl<T>& block, bool unsignedPortion/* = false*/) const
@@ -304,10 +350,6 @@
return m_wire;
}
-/**
- * Decode the input using a particular wire format and update this Data.
- * @param input The input byte array to be decoded.
- */
inline void
Data::wireDecode(const Block& wire)
{
@@ -354,11 +396,13 @@
return m_name;
}
-inline void
+inline Data&
Data::setName(const Name& name)
{
onChanged();
m_name = name;
+
+ return *this;
}
inline const MetaInfo&
@@ -367,11 +411,13 @@
return m_metaInfo;
}
-inline void
+inline Data&
Data::setMetaInfo(const MetaInfo& metaInfo)
{
onChanged();
m_metaInfo = metaInfo;
+
+ return *this;
}
inline uint32_t
@@ -380,11 +426,13 @@
return m_metaInfo.getType();
}
-inline void
+inline Data&
Data::setContentType(uint32_t type)
{
onChanged();
m_metaInfo.setType(type);
+
+ return *this;
}
inline const time::milliseconds&
@@ -393,11 +441,13 @@
return m_metaInfo.getFreshnessPeriod();
}
-inline void
+inline Data&
Data::setFreshnessPeriod(const time::milliseconds& freshnessPeriod)
{
onChanged();
m_metaInfo.setFreshnessPeriod(freshnessPeriod);
+
+ return *this;
}
inline const name::Component&
@@ -406,11 +456,13 @@
return m_metaInfo.getFinalBlockId();
}
-inline void
+inline Data&
Data::setFinalBlockId(const name::Component& finalBlockId)
{
onChanged();
m_metaInfo.setFinalBlockId(finalBlockId);
+
+ return *this;
}
inline const Block&
@@ -424,23 +476,27 @@
return m_content;
}
-inline void
+inline Data&
Data::setContent(const uint8_t* content, size_t contentLength)
{
onChanged();
m_content = dataBlock(Tlv::Content, content, contentLength);
+
+ return *this;
}
-inline void
+inline Data&
Data::setContent(const ConstBufferPtr& contentValue)
{
onChanged();
m_content = Block(Tlv::Content, contentValue); // not real a wire encoding yet
+
+ return *this;
}
-inline void
+inline Data&
Data::setContent(const Block& content)
{
onChanged();
@@ -450,6 +506,8 @@
else {
m_content = Block(Tlv::Content, content);
}
+
+ return *this;
}
inline const Signature&
@@ -458,18 +516,22 @@
return m_signature;
}
-inline void
+inline Data&
Data::setSignature(const Signature& signature)
{
onChanged();
m_signature = signature;
+
+ return *this;
}
-inline void
+inline Data&
Data::setSignatureValue(const Block& value)
{
onChanged();
m_signature.setValue(value);
+
+ return *this;
}
//
@@ -492,11 +554,13 @@
return getLocalControlHeader().getIncomingFaceId();
}
-inline void
+inline Data&
Data::setIncomingFaceId(uint64_t incomingFaceId)
{
getLocalControlHeader().setIncomingFaceId(incomingFaceId);
// ! do not reset Data's wire !
+
+ return *this;
}
inline void
diff --git a/src/encoding/block-helpers.hpp b/src/encoding/block-helpers.hpp
index f8e9c11..317cd13 100644
--- a/src/encoding/block-helpers.hpp
+++ b/src/encoding/block-helpers.hpp
@@ -62,6 +62,22 @@
return dataBlock(type, reinterpret_cast<const char*>(data), dataSize);
}
+template<class InputIterator>
+inline Block
+dataBlock(uint32_t type, InputIterator first, InputIterator last)
+{
+ size_t dataSize = 0;
+ for (InputIterator i = first; i != last; i++)
+ ++dataSize;
+
+ OBufferStream os;
+ Tlv::writeVarNumber(os, type);
+ Tlv::writeVarNumber(os, dataSize);
+ std::copy(first, last, std::ostream_iterator<uint8_t>(os));
+
+ return Block(os.buf());
+}
+
} // namespace ndn
#endif // NDN_BLOCK_HELPERS_HPP
diff --git a/src/encoding/tlv.hpp b/src/encoding/tlv.hpp
index ce35906..594cdce 100644
--- a/src/encoding/tlv.hpp
+++ b/src/encoding/tlv.hpp
@@ -97,7 +97,7 @@
*
* @param [in] begin Begin (pointer or iterator) of the buffer
* @param [in] end End (pointer or iterator) of the buffer
- * @param [out] number Read type number
+ * @param [out] type Read type number
*
* @throws This call never throws exception
*
diff --git a/src/exclude.hpp b/src/exclude.hpp
index 3801649..2fa939f 100644
--- a/src/exclude.hpp
+++ b/src/exclude.hpp
@@ -112,7 +112,7 @@
/**
* @brief Exclude all components from range [from, +Inf]
- * @param to last element of the range
+ * @param from the first element of the range
* @returns *this to allow chaining
*/
Exclude&
diff --git a/src/face.hpp b/src/face.hpp
index 11800c8..18f40e6 100644
--- a/src/face.hpp
+++ b/src/face.hpp
@@ -376,7 +376,9 @@
* If registeredPrefixId was obtained using setInterestFilter, the corresponding
* InterestFilter will be unset too.
*
- * @param registeredPrefixId The ID returned from registerPrefix.
+ * @param registeredPrefixId The ID returned from registerPrefix
+ * @param onSuccess Callback to be called when operation succeeds
+ * @param onFailure Callback to be called when operation fails
*/
void
unregisterPrefix(const RegisteredPrefixId* registeredPrefixId,
diff --git a/src/interest.hpp b/src/interest.hpp
index d67579e..ea007bd 100644
--- a/src/interest.hpp
+++ b/src/interest.hpp
@@ -34,7 +34,14 @@
{
public:
/**
- * @brief Create a new Interest with an empty name and "none" for all values.
+ * @brief Create a new Interest with an empty name (`ndn:/`)
+ *
+ * Note that in certain contexts that use Interest::shared_from_this(), Interest must be
+ * created using `make_shared`:
+ *
+ * shared_ptr<Interest> interest = make_shared<Interest>();
+ *
+ * Otherwise, Interest::shared_from_this() will throw an exception.
*/
Interest()
: m_nonce(0)
@@ -44,9 +51,16 @@
}
/**
- * @brief Create a new Interest with the given name and "none" for other values.
+ * @brief Create a new Interest with the given name
*
* @param name The name for the interest.
+ *
+ * Note that in certain contexts that use Interest::shared_from_this(), Interest must be
+ * created using `make_shared`:
+ *
+ * shared_ptr<Interest> interest = make_shared<Interest>(name);
+ *
+ * Otherwise, Interest::shared_from_this() will throw an exception.
*/
Interest(const Name& name)
: m_name(name)
@@ -57,9 +71,17 @@
}
/**
- * Create a new Interest with the given name and interest lifetime and "none" for other values.
- * @param name The name for the interest.
- * @param interestLifetimeMilliseconds The interest lifetime in time::milliseconds, or -1 for none.
+ * @brief Create a new Interest with the given name and interest lifetime
+ *
+ * @param name The name for the interest.
+ * @param interestLifetime The interest lifetime in time::milliseconds, or -1 for none.
+ *
+ * Note that in certain contexts that use Interest::shared_from_this(), Interest must be
+ * created using `make_shared`:
+ *
+ * shared_ptr<Interest> interest = make_shared<Interest>(name, time::seconds(1));
+ *
+ * Otherwise, Interest::shared_from_this() will throw an exception.
*/
Interest(const Name& name, const time::milliseconds& interestLifetime)
: m_name(name)
@@ -69,6 +91,16 @@
{
}
+ /**
+ * @brief Create a new Interest for the given name, selectors, and guiders
+ *
+ * Note that in certain contexts that use Interest::shared_from_this(), Interest must be
+ * created using `make_shared`:
+ *
+ * shared_ptr<Interest> interest = make_shared<Interest>(...);
+ *
+ * Otherwise, Interest::shared_from_this() will throw an exception.
+ */
Interest(const Name& name,
const Selectors& selectors,
int scope,
@@ -83,19 +115,17 @@
}
/**
- * Create a new Interest for the given name and values.
- * @param name
- * @param minSuffixComponents
- * @param maxSuffixComponents
- * @param exclude
- * @param childSelector
- * @param mustBeFresh
- * @param scope
- * @param interestLifetime
- * @param nonce
+ * @brief Create a new Interest for the given name and parameters
*
* @deprecated Interest().setX(...).setY(...)
* or use the overload taking Selectors
+ *
+ * Note that in certain contexts that use Interest::shared_from_this(), Interest must be
+ * created using `make_shared`:
+ *
+ * shared_ptr<Interest> interest = make_shared<Interest>(...);
+ *
+ * Otherwise, Interest::shared_from_this() will throw an exception.
*/
Interest(const Name& name,
int minSuffixComponents, int maxSuffixComponents,
@@ -115,6 +145,13 @@
/**
* @brief Create from wire encoding
+ *
+ * Note that in certain contexts that use Interest::shared_from_this(), Interest must be
+ * created using `make_shared`:
+ *
+ * shared_ptr<Interest> interest = make_shared<Interest>(wire);
+ *
+ * Otherwise, Interest::shared_from_this() will throw an exception.
*/
explicit
Interest(const Block& wire)
@@ -148,36 +185,37 @@
hasWire() const;
/**
- * Encode the name according to the "NDN URI Scheme". If there are interest selectors, append "?" and
- * added the selectors as a query string. For example "/test/name?ndn.ChildSelector=1".
- * @return The URI string.
+ * @brief Encode the name according to the NDN URI Scheme
+ *
+ * If there are interest selectors, this method will append "?" and add the selectors as
+ * a query string. For example, "/test/name?ndn.ChildSelector=1"
*/
inline std::string
toUri() const;
+ /**
+ * @brief Check if Interest has any selectors present
+ */
inline bool
hasSelectors() const;
- inline bool
- hasGuiders() const;
-
/**
- * @brief Check if Interest name matches the given name (using ndn_Name_match) and the given name also conforms to the
- * interest selectors.
- * @param self A pointer to the ndn_Interest struct.
- * @param name A pointer to the name to check.
- * @return 1 if the name and interest selectors match, 0 otherwise.
+ * @brief Check if Interest, including selectors, matches the given @p name
+ *
+ * @param name The name to be matched. If this is a Data name, it shall contain the
+ * implicit digest component
*/
bool
matchesName(const Name& name) const;
- /** @brief Determines whether this Interest can be satisfied by @p data.
+ /**
+ * @brief Check if Interest can be satisfied by @p data.
*
- * This method considers Name, MinSuffixComponents, MaxSuffixComponents,
- * PublisherPublicKeyLocator, and Exclude.
- * This method does not consider ChildSelector and MustBeFresh.
+ * This method considers Name, MinSuffixComponents, MaxSuffixComponents,
+ * PublisherPublicKeyLocator, and Exclude.
+ * This method does not consider ChildSelector and MustBeFresh.
*
- * @todo recognize implicit digest component
+ * @todo recognize implicit digest component
*/
bool
matchesData(const Data& data) const;
@@ -462,14 +500,6 @@
return !m_selectors.empty();
}
-inline bool
-Interest::hasGuiders() const
-{
- return m_scope >= 0 ||
- m_interestLifetime >= time::milliseconds::zero() ||
- m_nonce > 0;
-}
-
template<bool T>
inline size_t
Interest::wireEncode(EncodingImpl<T>& block) const
diff --git a/src/name-component.hpp b/src/name-component.hpp
index 9c98e3a..b83dd40 100644
--- a/src/name-component.hpp
+++ b/src/name-component.hpp
@@ -45,46 +45,84 @@
};
/**
- * Create a new Name::Component with a null value.
+ * Create a new name::Component with an empty value
*/
Component();
/**
- * @brief Directly create component from wire block
+ * @brief Create name::Component from a wire block
+ *
+ * @param wire Tlv::NameComponent Block from which to create name::Component
+ * @throws Error if wire.type() is not Tlv::NameComponent
*
* Any block can be implicitly converted to name::Component
- *
- * @throws Error if wire.type() is not Tlv::Component
*/
Component(const Block& wire);
/**
- * Create a new Name::Component, taking another pointer to the Blob value.
- * @param value A blob with a pointer to an immutable array. The pointer is copied.
+ * @brief Create a new name::Component from the buffer pointer (buffer pointer will be copied)
+ *
+ * @param buffer A pointer to an immutable buffer
+ *
+ * This constructor will create a new Tlv::NameComponent Block with `buffer` as a payload.
+ * Note that this method **will not** allocate new memory for and copy the payload until
+ * toWire() method is called.
*/
explicit
Component(const ConstBufferPtr& buffer);
/**
- * Create a new Name::Component, copying the given value.
- * @param value The value byte array.
+ * @brief Create a new name::Component from the buffer (data from buffer will be copied)
+ * @param buffer A reference to the buffer
+ *
+ * This constructor will create a new Tlv::NameComponent Block with `buffer` as a payload.
+ * Note that this method **will** allocate new memory for and copy the payload.
*/
explicit
- Component(const Buffer& value);
+ Component(const Buffer& buffer);
/**
- * Create a new Name::Component, copying the given value.
- * @param value Pointer to the value byte array.
- * @param valueLen Length of value.
+ * @brief Create a new name::Component from the buffer (data from buffer will be copied)
+ * @param buffer A pointer to the first byte of the buffer
+ * @param bufferSize Size of the buffer
+ *
+ * This constructor will create a new Tlv::NameComponent Block with `buffer` as a payload.
+ * Note that this method **will** allocate new memory for and copy the payload.
*/
- Component(const uint8_t* value, size_t valueLen);
+ Component(const uint8_t* buffer, size_t bufferSize);
+ /**
+ * @brief Create a new name::Component from the buffer (data from buffer will be copied)
+ * @param begin Iterator pointing to the beginning of the buffer
+ * @param end Iterator pointing to the ending of the buffer
+ *
+ * This constructor will create a new Tlv::NameComponent Block with `buffer` as a payload.
+ * Note that this method **will** allocate new memory for and copy the payload.
+ */
template<class InputIterator>
Component(InputIterator begin, InputIterator end);
+ /**
+ * @brief Create a new name::Component from the C string (data from string will be copied)
+ *
+ * @param str Zero-ended string. Note that this string will be interpreted as is (i.e.,
+ * it will not be interpreted as URI)
+ *
+ * This constructor will create a new Tlv::NameComponent Block with `buffer` as a payload.
+ * Note that this method **will** allocate new memory for and copy the payload.
+ */
explicit
Component(const char* str);
+ /**
+ * @brief Create a new name::Component from the STL string (data from string will be copied)
+ *
+ * @param str Const reference to STL string. Note that this string will be interpreted
+ * as is (i.e., it will not be interpreted as URI)
+ *
+ * This constructor will create a new Tlv::NameComponent Block with `buffer` as a payload.
+ * Note that this method **will** allocate new memory for and copy the payload.
+ */
explicit
Component(const std::string& str);
@@ -98,33 +136,36 @@
/**
* @brief Encode to a wire format
*/
- inline const Block&
+ const Block&
wireEncode() const;
/**
* @brief Decode from the wire format
*/
- inline void
+ void
wireDecode(const Block& wire);
/**
- * Make a Blob value by decoding the escapedString between beginOffset and endOffset according to the NDN URI Scheme.
- * If the escaped string is "", "." or ".." then return a Blob with a null pointer,
- * which means the component should be skipped in a URI name.
- * @param escapedString The escaped string. It does not need to be null-terminated because we only scan to endOffset.
+ * @brief Create name::Component by decoding the escapedString between beginOffset and
+ * endOffset according to the NDN URI Scheme.
+ *
+ * If the escaped string is "", "." or ".." then return an empty name::Component. Note
+ * that an empty name::Component should not be added to Name and if attempted, an
+ * exception will be thrown.
+ *
+ * @param escapedString String containing NDN URI-encoded name
+ * component. [escapedString+beginOffset, beginOffset+endOffset)
+ * must be a valid memory buffer.
* @param beginOffset The offset in escapedString of the beginning of the portion to decode.
- * @param endOffset The offset in escapedString of the end of the portion to decode.
- * @return The Blob value. If the escapedString is not a valid escaped component, then the Blob is a null pointer.
+ * @param endOffset The offset in escapedString of the end of the portion to decode.
*/
static Component
fromEscapedString(const char* escapedString, size_t beginOffset, size_t endOffset);
/**
- * Make a Blob value by decoding the escapedString according to the NDN URI Scheme.
- * If the escaped string is "", "." or ".." then return a Blob with a null pointer,
- * which means the component should be skipped in a URI name.
- * @param escapedString The null-terminated escaped string.
- * @return The Blob value. If the escapedString is not a valid escaped component, then the Blob is a null pointer.
+ * @brief Create name::Component by decoding the escapedString according to the NDN URI Scheme
+ *
+ * This overload is a convenience wrapper for fromEscapedString(char*,size_t,size)
*/
static Component
fromEscapedString(const char* escapedString)
@@ -133,34 +174,38 @@
}
/**
- * Make a Blob value by decoding the escapedString according to the NDN URI Scheme.
- * If the escaped string is "", "." or ".." then return a Blob with a null pointer,
- * which means the component should be skipped in a URI name.
- * @param escapedString The escaped string.
- * @return The Blob value. If the escapedString is not a valid escaped component, then the Blob is a null pointer.
+ * @brief Create name::Component by decoding the escapedString according to the NDN URI Scheme
+ *
+ * This overload is a convenience wrapper for fromEscapedString(char*,size_t,size)
*/
static Component
fromEscapedString(const std::string& escapedString)
{
- return fromEscapedString(escapedString.c_str());
+ return fromEscapedString(escapedString.c_str(), 0, escapedString.size());
}
/**
- * Write the value to result, escaping characters according to the NDN URI Scheme.
- * This also adds "..." to a value with zero or more ".".
- * @param value the buffer with the value to escape
- * @param result the string stream to write to.
+ * @brief Write *this to the output stream, escaping characters according to the NDN URI Scheme
+ *
+ * @deprecated Use toUri(std::ostream&) instead
+ *
+ * This also adds "..." to a value with zero or more "."
+ *
+ * @param os The output stream to where write the URI escaped version *this
*/
void
- toEscapedString(std::ostream& result) const;
+ toEscapedString(std::ostream& os) const;
/**
- * Convert the value by escaping characters according to the NDN URI Scheme.
- * This also adds "..." to a value with zero or more ".".
- * @param value the buffer with the value to escape
- * @return The escaped string.
+ * @brief Convert *this by escaping characters according to the NDN URI Scheme
+ *
+ * @deprecated Use toUri() instead
+ *
+ * This also adds "..." to a value with zero or more "."
+ *
+ * @return The escaped string
*/
- inline std::string
+ std::string
toEscapedString() const
{
std::ostringstream result;
@@ -168,13 +213,27 @@
return result.str();
}
- inline void
- toUri(std::ostream& result) const
+ /**
+ * @brief Write *this to the output stream, escaping characters according to the NDN URI Scheme
+ *
+ * This also adds "..." to a value with zero or more "."
+ *
+ * @param os The output stream to where write the URI escaped version *this
+ */
+ void
+ toUri(std::ostream& os) const
{
- return toEscapedString(result);
+ return toEscapedString(os);
}
- inline std::string
+ /**
+ * @brief Convert *this by escaping characters according to the NDN URI Scheme
+ *
+ * This also adds "..." to a value with zero or more "."
+ *
+ * @return The escaped string
+ */
+ std::string
toUri() const
{
return toEscapedString();
@@ -213,9 +272,16 @@
static Component
fromNumber(uint64_t number);
+ bool
+ empty() const
+ {
+ return !hasValue();
+ }
+
/**
- * Check if this is the same component as other.
- * @param other The other Component to compare with.
+ * @brief Check if this is the same component as other
+ *
+ * @param other The other Component to compare with
* @return true if the components are equal, otherwise false.
*/
bool
@@ -231,33 +297,12 @@
return std::equal(value_begin(), value_end(), other.value_begin());
}
- bool
- empty() const
- {
- return !hasValue();
- }
-
/**
- * Check if this is the same component as other.
- * @param other The other Component to compare with.
- * @return true if the components are equal, otherwise false.
- */
- bool
- operator==(const Component& other) const { return equals(other); }
-
- /**
- * Check if this is not the same component as other.
- * @param other The other Component to compare with.
- * @return true if the components are not equal, otherwise false.
- */
- bool
- operator!=(const Component& other) const { return !equals(other); }
-
- /**
- * Compare this to the other Component using NDN canonical ordering.
+ * @brief Compare this to the other Component using NDN canonical ordering
+ *
* @param other The other Component to compare with.
* @return 0 If they compare equal, -1 if *this comes before other in the canonical ordering, or
- * 1 if *this comes after other in the canonical ordering.
+ * 1 if *this comes after other in the canonical ordering.
*
* @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
*/
@@ -265,49 +310,84 @@
compare(const Component& other) const;
/**
- * Return true if this is less than or equal to the other Component in the NDN canonical ordering.
- * @param other The other Component to compare with.
+ * @brief Check if this is the same component as other
*
- * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
+ * @param other The other Component to compare with.
+ * @return true if the components are equal, otherwise false.
*/
bool
- operator<=(const Component& other) const { return compare(other) <= 0; }
+ operator==(const Component& other) const
+ {
+ return equals(other);
+ }
/**
- * Return true if this is less than the other Component in the NDN canonical ordering.
- * @param other The other Component to compare with.
- *
- * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
+ * @brief Check if this is not the same component as other
+ * @param other The other Component to compare with
+ * @return true if the components are not equal, otherwise false
*/
bool
- operator<(const Component& other) const { return compare(other) < 0; }
+ operator!=(const Component& other) const
+ {
+ return !equals(other);
+ }
/**
- * Return true if this is less than or equal to the other Component in the NDN canonical ordering.
- * @param other The other Component to compare with.
+ * @brief Check if the *this is less than or equal to the other in NDN canonical ordering
+ * @param other The other Component to compare with
*
* @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
*/
bool
- operator>=(const Component& other) const { return compare(other) >= 0; }
+ operator<=(const Component& other) const
+ {
+ return compare(other) <= 0;
+ }
/**
- * Return true if this is greater than the other Component in the NDN canonical ordering.
- * @param other The other Component to compare with.
+ * @brief Check if the *this is less than the other in NDN canonical ordering
+ * @param other The other Component to compare with
*
* @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
*/
bool
- operator>(const Component& other) const { return compare(other) > 0; }
+ operator<(const Component& other) const
+ {
+ return compare(other) < 0;
+ }
+ /**
+ * @brief Check if the *this is greater or equal than the other in NDN canonical ordering
+ * @param other The other Component to compare with
+ *
+ * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
+ */
+ bool
+ operator>=(const Component& other) const
+ {
+ return compare(other) >= 0;
+ }
+
+ /**
+ * @brief Check if the *this is greater than the other in NDN canonical ordering
+ * @param other The other Component to compare with
+ *
+ * @see http://named-data.net/doc/ndn-tlv/name.html#canonical-order
+ */
+ bool
+ operator>(const Component& other) const
+ {
+ return compare(other) > 0;
+ }
+
+ // !!! NOTE TO IMPLEMENTOR !!!
//
- // !!! MUST NOT INCLUDE ANY DATA HERE !!!
- //
- // This class is just a helper and is directly reinterpret_cast'ed from Block
+ // This class MUST NOT contain any data fields.
+ // Block can be reinterpret_cast'ed as Component type.
};
inline std::ostream&
-operator << (std::ostream& os, const Component& component)
+operator<<(std::ostream& os, const Component& component)
{
component.toEscapedString(os);
return os;
@@ -329,38 +409,38 @@
inline
Component::Component(const ConstBufferPtr& buffer)
- : Block (Tlv::NameComponent, buffer)
+ : Block(Tlv::NameComponent, buffer)
{
}
inline
Component::Component(const Buffer& value)
- : Block (Tlv::NameComponent, ConstBufferPtr(new Buffer(value)))
+ : Block(dataBlock(Tlv::NameComponent, value.buf(), value.size()))
{
}
inline
Component::Component(const uint8_t* value, size_t valueLen)
- : Block (Tlv::NameComponent, ConstBufferPtr(new Buffer(value, valueLen)))
+ : Block(dataBlock(Tlv::NameComponent, value, valueLen))
{
}
template<class InputIterator>
inline
Component::Component(InputIterator begin, InputIterator end)
- : Block (Tlv::NameComponent, ConstBufferPtr(new Buffer(begin, end)))
+ : Block(dataBlock(Tlv::NameComponent, begin, end))
{
}
inline
Component::Component(const char* str)
- : Block (Tlv::NameComponent, ConstBufferPtr(new Buffer(str, ::strlen(str))))
+ : Block(dataBlock(Tlv::NameComponent, str, ::strlen(str)))
{
}
inline
Component::Component(const std::string& str)
- : Block (Tlv::NameComponent, ConstBufferPtr(new Buffer(str.begin(), str.end())))
+ : Block(dataBlock(Tlv::NameComponent, str.c_str(), str.size()))
{
}
@@ -420,7 +500,7 @@
result << '%';
if (x < 16)
result << '0';
- result << (unsigned int)x;
+ result << static_cast<unsigned int>(x);
}
}
@@ -481,15 +561,12 @@
{
size_t totalLength = 0;
if (value_size() > 0)
- totalLength += block.prependByteArray (value(), value_size());
- totalLength += block.prependVarNumber (value_size());
- totalLength += block.prependVarNumber (Tlv::NameComponent);
+ totalLength += block.prependByteArray(value(), value_size());
+ totalLength += block.prependVarNumber(value_size());
+ totalLength += block.prependVarNumber(Tlv::NameComponent);
return totalLength;
}
-/**
- * @brief Encode to a wire format
- */
inline const Block&
Component::wireEncode() const
{
@@ -506,9 +583,6 @@
return *this;
}
-/**
- * @brief Decode from the wire format
- */
inline void
Component::wireDecode(const Block& wire)
{
diff --git a/src/security/key-chain.hpp b/src/security/key-chain.hpp
index db71884..30efa12 100644
--- a/src/security/key-chain.hpp
+++ b/src/security/key-chain.hpp
@@ -102,7 +102,7 @@
/**
* @brief prepare an unsigned identity certificate
*
- * @param keyName Key name, e.g., /<identity_name>/ksk-123456.
+ * @param keyName Key name, e.g., `/<identity_name>/ksk-123456`.
* @param signingIdentity The signing identity.
* @param notBefore Refer to IdentityCertificate.
* @param notAfter Refer to IdentityCertificate.
@@ -177,9 +177,7 @@
signByIdentity(const uint8_t* buffer, size_t bufferLength, const Name& identityName);
/**
- * @brief Set Sha256 weak signature.
- *
- * @param data.
+ * @brief Set Sha256 weak signature for @param data
*/
inline void
signWithSha256(Data& data);
@@ -187,8 +185,8 @@
/**
* @brief Generate a self-signed certificate for a public key.
*
- * @param keyName The name of the public key.
- * @return The generated certificate, NULL if selfSign fails.
+ * @param keyName The name of the public key
+ * @return The generated certificate, shared_ptr<IdentityCertificate>() if selfSign fails
*/
shared_ptr<IdentityCertificate>
selfSign(const Name& keyName);
diff --git a/src/security/public-key.cpp b/src/security/public-key.cpp
index 9449cc9..17f204b 100644
--- a/src/security/public-key.cpp
+++ b/src/security/public-key.cpp
@@ -28,11 +28,6 @@
{
}
-/**
- * Create a new PublicKey with the given values.
- * @param algorithm The algorithm of the public key.
- * @param keyDer The blob of the PublicKeyInfo in terms of DER.
- */
PublicKey::PublicKey(const uint8_t* keyDerBuf, size_t keyDerSize)
{
StringSource src(keyDerBuf, keyDerSize, true);
diff --git a/src/security/public-key.hpp b/src/security/public-key.hpp
index 1ed567c..e939978 100644
--- a/src/security/public-key.hpp
+++ b/src/security/public-key.hpp
@@ -43,11 +43,12 @@
PublicKey();
/**
- * Create a new PublicKey with the given values.
- * @param algorithm The algorithm of the public key.
- * @param keyDer The blob of the PublicKeyInfo in terms of DER.
+ * @brief Create a new PublicKey from @param keyDerBuf in DER buffer
*
- * @throws PublicKey::Error If algorithm is not supported or keyDer cannot be decoded
+ * @param keyDerBuf The pointer to the first byte of buffer containing DER of public key
+ * @param keyDerSize Size of the buffer
+ *
+ * @throws PublicKey::Error If DER in buffer cannot be decoded
*/
PublicKey(const uint8_t* keyDerBuf, size_t keyDerSize);
diff --git a/src/security/sec-public-info.hpp b/src/security/sec-public-info.hpp
index 790ad36..1949d51 100644
--- a/src/security/sec-public-info.hpp
+++ b/src/security/sec-public-info.hpp
@@ -44,7 +44,7 @@
};
/**
- * @brief The virtual Destructor.
+ * @brief The virtual Destructor
*/
virtual
~SecPublicInfo()
@@ -52,37 +52,37 @@
}
/**
- * @brief Check if the specified identity already exists.
+ * @brief Check if the specified identity already exists
*
- * @param identityName The identity name.
- * @return true if the identity exists, otherwise false.
+ * @param identityName The identity name
+ * @return true if the identity exists, otherwise false
*/
virtual bool
doesIdentityExist(const Name& identityName) = 0;
/**
- * @brief Add a new identity.
+ * @brief Add a new identity
*
- * if identity already exist, do not add it again.
+ * if identity already exist, do not add it again
*
- * @param identityName The identity name to be added.
+ * @param identityName The identity name to be added
*/
virtual void
addIdentity(const Name& identityName) = 0;
/**
- * @brief Revoke the identity.
+ * @brief Revoke the identity
*
- * @return true if the identity was revoked, otherwise false.
+ * @return true if the identity was revoked, otherwise false
*/
virtual bool
revokeIdentity() = 0;
/**
- * @brief Check if the specified key already exists.
+ * @brief Check if the specified key already exists
*
- * @param keyName The name of the key.
- * @return true if the key exists, otherwise false.
+ * @param keyName The name of the key
+ * @return true if the key exists, otherwise false
*/
virtual bool
doesPublicKeyExist(const Name& keyName) = 0;
@@ -90,28 +90,26 @@
/**
* @brief Add a public key to the identity storage.
*
- * @param keyName The name of the public key to be added.
- * @param keyType Type of the public key to be added.
- * @param publicKeyDer A blob of the public key DER to be added.
+ * @param keyName The name of the public key to be added
+ * @param keyType Type of the public key to be added
+ * @param publicKey Reference to the PublicKey object
*/
virtual void
- addPublicKey(const Name& keyName, KeyType keyType, const PublicKey& publicKeyDer) = 0;
+ addPublicKey(const Name& keyName, KeyType keyType, const PublicKey& publicKey) = 0;
/**
- * @brief Get the public key DER blob from the identity storage.
+ * @brief Get shared pointer to PublicKey object from the identity storage
*
- * @param keyName The name of the requested public key.
- * @return The DER Blob.
- * @throws SecPublicInfo::Error if public key does not exist.
+ * @param keyName The name of the requested public key
+ * @throws SecPublicInfo::Error if public key does not exist
*/
virtual shared_ptr<PublicKey>
getPublicKey(const Name& keyName) = 0;
/**
- * @brief Check if the specified certificate already exists.
+ * @brief Check if the specified certificate already exists
*
- * @param certificateName The name of the certificate.
- * @return true if the certificate exists, otherwise false.
+ * @param certificateName The name of the certificate
*/
virtual bool
doesCertificateExist(const Name& certificateName) = 0;
@@ -119,19 +117,18 @@
/**
* @brief Add a certificate to the identity storage.
*
- * It will add the corresponding public key and identity if they do not exist.
+ * It will add the corresponding public key and identity if they do not exist
*
- * @param certificate The certificate to be added.
+ * @param certificate The certificate to be added
*/
virtual void
addCertificate(const IdentityCertificate& certificate) = 0;
/**
- * @brief Get a certificate from the identity storage.
+ * @brief Get a shared pointer to identity certificate object from the identity storage
*
- * @param certificateName The name of the requested certificate.
- * @return The requested certificate.
- * @throws SecPublicInfo::Error if the certificate does not exist.
+ * @param certificateName The name of the requested certificate
+ * @throws SecPublicInfo::Error if the certificate does not exist
*/
virtual shared_ptr<IdentityCertificate>
getCertificate(const Name& certificateName) = 0;
@@ -142,77 +139,74 @@
*****************************************/
/**
- * @brief Get the default identity.
+ * @brief Get name of the default identity
*
- * @param return The name of default identity,
* @throws SecPublicInfo::Error if there is no default.
*/
virtual Name
getDefaultIdentity() = 0;
/**
- * @brief Get the default key name for the specified identity.
+ * @brief Get name of the default key name for the specified identity
*
- * @param identityName The identity name.
- * @return The default key name.
- * @throws SecPublicInfo::Error if there is no default.
+ * @param identityName The identity name
+ * @throws SecPublicInfo::Error if there is no default
*/
virtual Name
getDefaultKeyNameForIdentity(const Name& identityName) = 0;
/**
- * @brief Get the default certificate name for the specified key.
+ * @brief Get name of the default certificate name for the specified key
*
* @param keyName The key name.
- * @return The default certificate name.
* @throws SecPublicInfo::Error if there is no default.
*/
virtual Name
getDefaultCertificateNameForKey(const Name& keyName) = 0;
/**
- * @brief Get all the identities in public info.
+ * @brief Get all the identities from public info
*
- * @param nameList On return, the identity list.
- * @param isDefault If specified, only the default identity is returned.
+ * @param [out] nameList On return, the identity list
+ * @param isDefault If specified, only the default identity is returned
*/
virtual void
getAllIdentities(std::vector<Name>& nameList, bool isDefault) = 0;
/**
- * @brief Get all the key name in public info.
+ * @brief Get all the key names from public info
*
- * @param nameList On return, the key name list.
- * @param isDefault If specified, only the default keys are returned.
+ * @param [out] nameList On return, the key name list.
+ * @param isDefault If specified, only the default keys are returned
*/
virtual void
getAllKeyNames(std::vector<Name>& nameList, bool isDefault) = 0;
/**
- * @brief Get all the key name of a particular identity.
+ * @brief Get all the key names of a particular identity
*
- * @param identity The specified identity name.
- * @param nameList On return, the key name list.
- * @param isDefault If specified, only the default key is returned.
+ * @param identity The specified identity name
+ * @param [out] nameList On return, the key name list
+ * @param isDefault If specified, only the default key is returned
*/
virtual void
getAllKeyNamesOfIdentity(const Name& identity, std::vector<Name>& nameList, bool isDefault) = 0;
/**
- * @brief Get all the certificate name in public info.
+ * @brief Get all the certificate name in public info
*
- * @param nameList On return, the certificate name list.
- * @param isDefault If specified, only the default certificates are returned.
+ * @param [out] nameList On return, the certificate name list
+ * @param isDefault If specified, only the default certificates are returned
*/
virtual void
getAllCertificateNames(std::vector<Name>& nameList, bool isDefault) = 0;
/**
- * @brief Get all the certificate name of a particular key.
+ * @brief Get all the certificate name of a particular key name
*
- * @param identity The specified key name.
- * @param nameList On return, the certificate name list.
- * @param isDefault If specified, only the default certificate is returned.
+ * @param keyName The specified key name
+ * @param [out] nameList On return, the certificate name list
+ * @param isDefault If specified, only the default certificate is returned
*/
virtual void
getAllCertificateNamesOfKey(const Name& keyName, std::vector<Name>& nameList, bool isDefault) = 0;
@@ -222,25 +216,25 @@
*****************************************/
/**
- * @brief Delete a certificate.
+ * @brief Delete a certificate
*
- * @param certificateName The certificate name.
+ * @param certificateName The certificate name
*/
virtual void
deleteCertificateInfo(const Name& certificateName) = 0;
/**
- * @brief Delete a public key and related certificates.
+ * @brief Delete a public key and related certificates
*
- * @param keyName The key name.
+ * @param keyName The key name
*/
virtual void
deletePublicKeyInfo(const Name& keyName) = 0;
/**
- * @brief Delete an identity and related public keys and certificates.
+ * @brief Delete an identity and related public keys and certificates
*
- * @param identity The identity name.
+ * @param identity The identity name
*/
virtual void
deleteIdentityInfo(const Name& identity) = 0;
@@ -252,27 +246,27 @@
*****************************************/
/**
- * @brief Set the default identity.
+ * @brief Set the default identity
*
- * @param identityName The default identity name.
+ * @param identityName The default identity name
*/
virtual void
setDefaultIdentityInternal(const Name& identityName) = 0;
/**
- * @brief Set the default key name for the corresponding identity.
+ * @brief Set the default key name for the corresponding identity
*
- * @param keyName The key name.
- * @throws SecPublicInfo::Error if the key does not exist.
+ * @param keyName The key name
+ * @throws SecPublicInfo::Error if the key does not exist
*/
virtual void
setDefaultKeyNameForIdentityInternal(const Name& keyName) = 0;
/**
- * @brief Set the default certificate name for the corresponding key.
+ * @brief Set the default certificate name for the corresponding key
*
- * @param certificateName The certificate name.
- * @throws SecPublicInfo::Error if the certificatedoes not exist.
+ * @param certificateName The certificate name
+ * @throws SecPublicInfo::Error if the certificate does not exist
*/
virtual void
setDefaultCertificateNameForKeyInternal(const Name& certificateName) = 0;
@@ -284,48 +278,48 @@
*****************************************/
/**
- * @brief Set the default identity.
+ * @brief Set the default identity
*
- * @param identityName The default identity name.
- * @throws SecPublicInfo::Error if the identity does not exist.
+ * @param identityName The default identity name
+ * @throws SecPublicInfo::Error if the identity does not exist
*/
inline void
setDefaultIdentity(const Name& identityName);
/**
- * @brief Set the default key name for the corresponding identity.
+ * @brief Set the default key name for the corresponding identity
*
- * @param keyName The key name.
- * @throws SecPublicInfo::Error if either the identity or key does not exist.
+ * @param keyName The key name
+ * @throws SecPublicInfo::Error if either the identity or key does not exist
*/
inline void
setDefaultKeyNameForIdentity(const Name& keyName);
/**
- * @brief Set the default certificate name for the corresponding key.
+ * @brief Set the default certificate name for the corresponding key
*
- * @param certificateName The certificate name.
- * @throws SecPublicInfo::Error if either the certificate or key does not exist.
+ * @param certificateName The certificate name
+ * @throws SecPublicInfo::Error if either the certificate or key does not exist
*/
inline void
setDefaultCertificateNameForKey(const Name& certificateName);
/**
- * @brief Generate a key name for the identity.
+ * @brief Generate a key name for the identity
*
- * @param identityName The identity name.
- * @param useKsk If true, generate a KSK name, otherwise a DSK name.
- * @return The generated key name.
+ * @param identityName The identity name
+ * @param useKsk If true, generate a KSK name, otherwise a DSK name
+ * @return The generated key name
*/
inline Name
getNewKeyName(const Name& identityName, bool useKsk);
/**
- * @brief Get the default certificate name for the specified identity.
+ * @brief Get the default certificate name for the specified identity
*
- * @param identityName The identity name.
- * @return The default certificate name.
- * @throws SecPublicInfo::Error if no certificate is found.
+ * @param identityName The identity name
+ * @return The default certificate name
+ * @throws SecPublicInfo::Error if no certificate is found
*/
inline Name
getDefaultCertificateNameForIdentity(const Name& identityName);
@@ -333,16 +327,16 @@
/**
* @brief Get the default certificate name of the default identity
*
- * @return The requested certificate name.
- * @throws SecPublicInfo::Error if no certificate is found.
+ * @return The requested certificate name
+ * @throws SecPublicInfo::Error if no certificate is found
*/
inline Name
getDefaultCertificateName();
/**
- * @brief Add a certificate and set the certificate as the default one of its corresponding key.
+ * @brief Add a certificate and set the certificate as the default one of its corresponding key
*
- * @param certificate The certificate to be added.
+ * @param certificate The certificate to be added
* @throws SecPublicInfo::Error if the certificate cannot be added (though it is really rare)
*/
inline void
@@ -350,9 +344,9 @@
/**
* @brief Add a certificate into the public key identity storage and set the certificate as the
- * default one of its corresponding identity.
+ * default one of its corresponding identity
*
- * @param certificate The certificate to be added.
+ * @param certificate The certificate to be added
* @throws SecPublicInfo::Error if the certificate cannot be added (though it is really rare)
*/
inline void
@@ -360,24 +354,24 @@
/**
* @brief Add a certificate into the public key identity storage and set the certificate as the
- * default one of the default identity.
+ * default one of the default identity
*
- * @param certificate The certificate to be added.
+ * @param certificate The certificate to be added
* @throws SecPublicInfo::Error if the certificate cannot be added (though it is really rare)
*/
inline void
addCertificateAsSystemDefault(const IdentityCertificate& certificate);
/**
- * @brief get cached default certificate of the default identity.
+ * @brief Get cached default certificate of the default identity
*
- * @return The certificate which might be a NULL pointer.
+ * @return The certificate which might be empty shared_ptr<IdentityCertificate>()
*/
inline shared_ptr<IdentityCertificate>
defaultCertificate();
/**
- * @brief try to get the default certificate of the default identity from the public info.
+ * @brief try to get the default certificate of the default identity from the public info
*/
inline void
refreshDefaultCertificate();
diff --git a/src/security/sec-tpm-file.hpp b/src/security/sec-tpm-file.hpp
index 0f1d8be..d9f95c4 100644
--- a/src/security/sec-tpm-file.hpp
+++ b/src/security/sec-tpm-file.hpp
@@ -60,7 +60,7 @@
}
virtual bool
- getInTerminal()
+ getInTerminal() const
{
return m_inTerminal;
}
diff --git a/src/security/sec-tpm-memory.hpp b/src/security/sec-tpm-memory.hpp
index df0c7e3..e0dd34c 100644
--- a/src/security/sec-tpm-memory.hpp
+++ b/src/security/sec-tpm-memory.hpp
@@ -64,7 +64,7 @@
}
virtual bool
- getInTerminal()
+ getInTerminal() const
{
return m_inTerminal;
}
diff --git a/src/security/sec-tpm-osx.cpp b/src/security/sec-tpm-osx.cpp
index a7e1cd9..69c3deb 100644
--- a/src/security/sec-tpm-osx.cpp
+++ b/src/security/sec-tpm-osx.cpp
@@ -269,7 +269,7 @@
}
bool
-SecTpmOsx::getInTerminal()
+SecTpmOsx::getInTerminal() const
{
return m_impl->m_inTerminal;
}
diff --git a/src/security/sec-tpm-osx.hpp b/src/security/sec-tpm-osx.hpp
index f7d9959..6effb67 100644
--- a/src/security/sec-tpm-osx.hpp
+++ b/src/security/sec-tpm-osx.hpp
@@ -58,7 +58,7 @@
setInTerminal(bool inTerminal);
virtual bool
- getInTerminal();
+ getInTerminal() const;
virtual bool
isLocked();
diff --git a/src/security/sec-tpm.hpp b/src/security/sec-tpm.hpp
index 5a163c6..69b5f22 100644
--- a/src/security/sec-tpm.hpp
+++ b/src/security/sec-tpm.hpp
@@ -53,8 +53,8 @@
* You should be cautious when using this method, because remembering password is kind of
* dangerous.
*
- * @param password The password.
- * @param passwordLength The length of password.
+ * @param password The password
+ * @param passwordLength The length of password
*/
virtual void
setTpmPassword(const uint8_t* password, size_t passwordLength) = 0;
@@ -66,34 +66,28 @@
resetTpmPassword() = 0;
/**
- * @brief set inTerminal flag
+ * @brief Set inTerminal flag to @param inTerminal
*
* If the inTerminal flag is set, and password is not set, TPM may ask for password via terminal.
* inTerminal flag is set by default.
- *
- * @param inTerminal.
*/
virtual void
setInTerminal(bool inTerminal) = 0;
/**
- * @brief get inTerminal flag
- *
- * @return inTerminal flag.
+ * @brief Get value of inTerminal flag
*/
virtual bool
- getInTerminal() = 0;
+ getInTerminal() const = 0;
/**
- * @brief check if TPM is locked.
- *
- * @return true if locked, false otherwise
+ * @brief Check if TPM is locked
*/
virtual bool
isLocked() = 0;
/**
- * @brief Unlock the TPM.
+ * @brief Unlock the TPM
*
* @param password The password.
* @param passwordLength The password size. 0 indicates no password.
@@ -195,17 +189,17 @@
doesKeyExistInTpm(const Name& keyName, KeyClass keyClass) = 0;
/**
- * @brief Generate a random block.
+ * @brief Generate a random block
*
- * @param res The pointer to the generated block.
- * @param size The random block size.
- * @return true for success, otherwise false.
+ * @param res The pointer to the generated block
+ * @param size The random block size
+ * @return true for success, otherwise false
*/
virtual bool
generateRandomBlock(uint8_t* res, size_t size) = 0;
/**
- * @brief Add the application into the ACL of a particular key.
+ * @brief Add the application into the ACL of a particular key
*
* @param keyName the name of key
* @param keyClass the class of key, e.g. Private Key
@@ -216,29 +210,31 @@
addAppToAcl(const Name& keyName, KeyClass keyClass, const std::string& appPath, AclType acl) = 0;
/**
- * @brief Export a private key in PKCS#5 format.
+ * @brief Export a private key in PKCS#5 format
*
- * @param keyName The private key name.
- * @param password The password to encrypt the private key.
- * @return The private key info (in PKCS8 format) if exist.
- * @throws SecTpm::Error if private key cannot be exported.
+ * @param keyName The private key name
+ * @param password The password to encrypt the private key
+ * @return The private key info (in PKCS8 format) if exist
+ * @throws SecTpm::Error if private key cannot be exported
*/
ConstBufferPtr
exportPrivateKeyPkcs5FromTpm(const Name& keyName, const std::string& password);
/**
- * @brief Import a private key in PKCS#5 format.
+ * @brief Import a private key in PKCS#5 formatted @param buffer of size @param bufferSize
*
* Also recover the public key and installed it in TPM.
*
- * @param keyName The private key name.
- * @param key The encoded private key info.
- * @param password The password to encrypt the private key.
- * @return False if import fails.
+ * @param keyName The private key name
+ * @param buffer Pointer to the first byte of the buffer containing PKCS#5-encoded
+ * private key info
+ * @param bufferSize Size of the buffer
+ * @param password The password to encrypt the private key
+ * @return false if import fails
*/
bool
importPrivateKeyPkcs5IntoTpm(const Name& keyName,
- const uint8_t* buf, size_t size,
+ const uint8_t* buffer, size_t bufferSize,
const std::string& password);
protected:
@@ -252,25 +248,28 @@
exportPrivateKeyPkcs8FromTpm(const Name& keyName) = 0;
/**
- * @brief Import a private key in PKCS#8 format.
+ * @brief Import a private key from PKCS#8 formatted @param buffer of size @param bufferSize
*
- * @param keyName The private key name.
- * @param key The encoded private key info.
- * @return False if import fails.
+ * @param keyName The private key name.
+ * @param buffer Pointer to the first byte of the buffer containing PKCS#8-encoded
+ * private key info
+ * @param bufferSize Size of the buffer
+ * @return false if import fails
*/
virtual bool
- importPrivateKeyPkcs8IntoTpm(const Name& keyName, const uint8_t* buf, size_t size) = 0;
+ importPrivateKeyPkcs8IntoTpm(const Name& keyName, const uint8_t* buffer, size_t bufferSize) = 0;
/**
- * @brief Import a public key in PKCS#1 format.
+ * @brief Import a public key in PKCS#1 formatted @param buffer of size @param bufferSize
*
- * @param keyName The public key name.
- * @param key The encoded public key info.
- * @return False if import fails.
+ * @param keyName The public key name
+ * @param buffer Pointer to the first byte of the buffer containing PKCS#1-encoded
+ * private key info
+ * @param bufferSize Size of the buffer
+ * @return false if import fails
*/
virtual bool
- importPublicKeyPkcs1IntoTpm(const Name& keyName, const uint8_t* buf, size_t size) = 0;
-
+ importPublicKeyPkcs1IntoTpm(const Name& keyName, const uint8_t* buffer, size_t bufferSize) = 0;
/**
* @brief Get import/export password.
diff --git a/src/security/validator-regex.hpp b/src/security/validator-regex.hpp
index fd006c4..e0977a8 100644
--- a/src/security/validator-regex.hpp
+++ b/src/security/validator-regex.hpp
@@ -50,7 +50,7 @@
/**
* @brief Add a rule for data verification.
*
- * @param policy The verification rule
+ * @param rule The verification rule
*/
inline void
addDataVerificationRule(shared_ptr<SecRuleRelative> rule);
diff --git a/src/security/validator.hpp b/src/security/validator.hpp
index c6fac7a..88f1d63 100644
--- a/src/security/validator.hpp
+++ b/src/security/validator.hpp
@@ -184,7 +184,6 @@
static bool
verifySignature(const uint8_t* buf, const size_t size, const SignatureSha256& sig);
-
protected:
/**
* @brief Check the Data against policy and return the next validation step if necessary.
@@ -192,11 +191,11 @@
* If there is no next validation step, that validation MUST have been done.
* i.e., either onValidated or onValidationFailed callback is invoked.
*
- * @param data The Data to check.
- * @param nSteps The number of validation steps that have been done.
- * @param onDataValidated If the Data is validated, this calls onValidated(data).
- * @param onDataValidationFailed If validation fails, this calls onValidationFailed(data).
- * @param nextSteps On return, contains the next validation step.
+ * @param data The Data to check.
+ * @param nSteps The number of validation steps that have been done.
+ * @param onValidated If the Data is validated, this calls onValidated(data)
+ * @param onValidationFailed If validation fails, this calls onValidationFailed(data)
+ * @param nextSteps On return, contains the next validation step
*/
virtual void
checkPolicy(const Data& data,
@@ -212,11 +211,11 @@
* If there is no next validation step, that validation MUST have been done.
* i.e., either onValidated or onValidationFailed callback is invoked.
*
- * @param data The Interest to check.
- * @param nSteps The number of validation steps that have been done.
- * @param OnInterestValidated If the Interest is validated, this calls onValidated(data).
- * @param OnInterestValidationFailed If validation fails, this calls onValidationFailed(data).
- * @return the indication of next validation step, null if there is no further step.
+ * @param interest The Interest to check.
+ * @param nSteps The number of validation steps that have been done.
+ * @param onValidated If the Interest is validated, this calls onValidated(data)
+ * @param onValidationFailed If validation fails, this calls onValidationFailed(data)
+ * @param nextSteps On return, contains the next validation step
*/
virtual void
checkPolicy(const Interest& interest,
diff --git a/src/transport/transport.hpp b/src/transport/transport.hpp
index 8291356..8b16639 100644
--- a/src/transport/transport.hpp
+++ b/src/transport/transport.hpp
@@ -38,25 +38,24 @@
~Transport();
/**
- * Connect transport
+ * @brief Connect transport
*
- * @throws If connection cannot be established
+ * @throws boost::system::system_error if connection cannot be established
*/
inline virtual void
connect(boost::asio::io_service& io_service,
const ReceiveCallback& receiveCallback);
/**
- * Close the connection.
+ * @brief Close the connection.
*/
virtual void
close() = 0;
/**
- * @brief Set data to the host
+ * @brief Send block of data from @param wire through the transport
*
- * @param data A pointer to the buffer of data to send.
- * @param dataLength The number of bytes in data.
+ * @param wire A block of data to send
*/
virtual void
send(const Block& wire) = 0;
diff --git a/src/util/string-helper.hpp b/src/util/string-helper.hpp
index b4878ae..13b0b31 100644
--- a/src/util/string-helper.hpp
+++ b/src/util/string-helper.hpp
@@ -23,9 +23,10 @@
static const char* WHITESPACE_CHARS = " \n\r\t";
/**
- * Return the hex representation of the bytes in array.
- * @param array The array of bytes.
- * @return Hex string.
+ * @brief Return the hex representation of the bytes in array
+ *
+ * @param array The array of bytes
+ * @param arraySize Size of the array
*/
inline std::string
toHex(const uint8_t* array, size_t arraySize)
@@ -46,8 +47,7 @@
}
/**
- * Modify str in place to erase whitespace on the left.
- * @param str
+ * @brief Modify str in place to erase whitespace on the left
*/
inline void
trimLeft(std::string& str)
@@ -63,8 +63,7 @@
}
/**
- * Modify str in place to erase whitespace on the right.
- * @param str
+ * @brief Modify str in place to erase whitespace on the right
*/
inline void
trimRight(std::string& str)
@@ -80,8 +79,7 @@
}
/**
- * Modify str in place to erase whitespace on the left and right.
- * @param str
+ * @brief Modify str in place to erase whitespace on the left and right
*/
inline void
trim(std::string& str)
@@ -91,9 +89,7 @@
}
/**
- * Convert the hex character to an integer from 0 to 15, or -1 if not a hex character.
- * @param c
- * @return
+ * @brief Convert the hex character to an integer from 0 to 15, or -1 if not a hex character
*/
inline int
fromHexChar(uint8_t c)
@@ -109,8 +105,7 @@
}
/**
- * Return a copy of str, converting each escaped "%XX" to the char value.
- * @param str
+ * @brief Return a copy of str, converting each escaped "%XX" to the char value
*/
inline std::string
unescape(const std::string& str)