signature: reorganize code
In SignatureInfo, Signature, and its subclasses:
* Improve Doxygen.
* Improve error messages.
* Make comparison operators non-member functions.
refs #4171
Change-Id: I9395a72594702255b41e3700ee145f35fc1a41f2
diff --git a/src/signature.hpp b/src/signature.hpp
index 4644807..315d061 100644
--- a/src/signature.hpp
+++ b/src/signature.hpp
@@ -1,5 +1,5 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
-/**
+/*
* Copyright (c) 2013-2017 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
@@ -22,13 +22,17 @@
#ifndef NDN_SIGNATURE_HPP
#define NDN_SIGNATURE_HPP
-#include "common.hpp"
#include "signature-info.hpp"
namespace ndn {
-/**
- * A Signature is storage for the signature-related information (info and value) in a Data packet.
+/** @brief Holds SignatureInfo and SignatureValue in a Data packet
+ *
+ * A Signature is not a TLV element itself. It collects SignatureInfo and SignatureValue TLV
+ * elements together for easy access.
+ * In most cases, an application should use a subclass of Signature such as @p DigestSha256 , @p
+ * SignatureSha256WithRsa , or @p SignatureSha256WithEcdsa instead of using @p Signature type
+ * directly.
*/
class Signature
{
@@ -51,22 +55,15 @@
explicit
Signature(const SignatureInfo& info, const Block& value = Block());
+ /** @brief Determine whether SignatureInfo is valid
+ */
+ explicit
operator bool() const
{
return m_info.getSignatureType() != -1;
}
- /**
- * @brief Get SignatureInfo in the wire format
- */
- const Block&
- getInfo() const
- {
- return m_info.wireEncode(); // will do nothing if wire already exists
- }
-
- /**
- * @brief Get SignatureInfo
+ /** @brief Get SignatureInfo
*/
const SignatureInfo&
getSignatureInfo() const
@@ -74,16 +71,21 @@
return m_info;
}
- /**
- * @brief Set SignatureInfo from a block
- *
- * @throws tlv::Error if supplied block is not formatted correctly
+ /** @brief Get SignatureInfo as wire format
+ */
+ const Block&
+ getInfo() const
+ {
+ return m_info.wireEncode();
+ }
+
+ /** @brief Decode SignatureInfo from wire format
+ * @throw tlv::Error decode error
*/
void
setInfo(const Block& info);
- /**
- * @brief Set SignatureInfo
+ /** @brief Set SignatureInfo
*/
void
setInfo(const SignatureInfo& info)
@@ -91,26 +93,22 @@
m_info = info;
}
- /**
- * @brief Get SignatureValue in the wire format
+ /** @brief Get SignatureValue
*/
const Block&
getValue() const
{
- m_value.encode(); // will do nothing if wire already exists
return m_value;
}
- /**
- * @brief Get SignatureValue from a block
- *
- * @throws tlv::Error if supplied block has type different from SignatureValue
+ /** @brief Set SignatureValue
+ * @throws tlv::Error TLV-TYPE of supplied block is not SignatureValue, or the block does not have TLV-VALUE
*/
void
setValue(const Block& value);
- /**
- * @brief Get signature type
+public: // SignatureInfo fields
+ /** @brief Get SignatureType
*/
uint32_t
getType() const
@@ -118,8 +116,7 @@
return m_info.getSignatureType();
}
- /**
- * @brief Check if SignatureInfo block has a KeyLocator
+ /** @brief Check if KeyLocator exists in SignatureInfo
*/
bool
hasKeyLocator() const
@@ -127,10 +124,8 @@
return m_info.hasKeyLocator();
}
- /**
- * @brief Get KeyLocator
- *
- * @throws Signature::Error if KeyLocator does not exist
+ /** @brief Get KeyLocator
+ * @throw tlv::Error KeyLocator does not exist in SignatureInfo
*/
const KeyLocator&
getKeyLocator() const
@@ -138,8 +133,7 @@
return m_info.getKeyLocator();
}
- /**
- * @brief Set KeyLocator
+ /** @brief Set KeyLocator
*/
void
setKeyLocator(const KeyLocator& keyLocator)
@@ -147,11 +141,10 @@
m_info.setKeyLocator(keyLocator);
}
- /**
- * @brief Unset KeyLocator
+ /** @brief Unset KeyLocator
*
- * Note that specific signature types may provide advisory (non-virtual) override
- * to prevent unsetting KeyLocator if it is required by the specification.
+ * @note Subclasses of Signature may provide advisory (non-virtual) override to prevent unsetting
+ * KeyLocator if it is required by the specification.
*/
void
unsetKeyLocator()
@@ -159,25 +152,23 @@
m_info.unsetKeyLocator();
}
-public: // EqualityComparable concept
- bool
- operator==(const Signature& other) const
- {
- return getInfo() == other.getInfo() &&
- getValue() == other.getValue();
- }
-
- bool
- operator!=(const Signature& other) const
- {
- return !(*this == other);
- }
-
protected:
SignatureInfo m_info;
mutable Block m_value;
};
+inline bool
+operator==(const Signature& lhs, const Signature& rhs)
+{
+ return lhs.getInfo() == rhs.getInfo() && lhs.getValue() == rhs.getValue();
+}
+
+inline bool
+operator!=(const Signature& lhs, const Signature& rhs)
+{
+ return !(lhs == rhs);
+}
+
} // namespace ndn
#endif // NDN_SIGNATURE_HPP