Doxygen comments in

This commit is contained in:
Oran Juice 2014-09-27 18:20:15 +05:30
parent 91aa25e055
commit f31adbc977
No known key found for this signature in database
GPG Key ID: 71C5AF46CCB28124
4 changed files with 134 additions and 21 deletions

View File

@ -26,7 +26,11 @@
// STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
// THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
/*
/*!
* \file electrum-words.cpp
*
* \brief Mnemonic seed generation and wallet restoration from them.
*
* This file and its header file are for translating Electrum-style word lists
* into their equivalent byte representations for cross-compatibility with
* that method of "backing up" one's wallet keys.
@ -56,11 +60,20 @@ namespace
const std::string LANGUAGES_DIRECTORY = "languages";
const std::string OLD_WORD_FILE = "old-word-list";
/*!
* Tells if the module hasn't been initialized with a word list file.
* \return Whether the module hasn't been initialized with a word list file.
*/
bool is_uninitialized()
{
return num_words == 0 ? true : false;
}
/*!
* Create word list map and array data structres for use during inter-conversion between
* words and secret key.
* \param word_file Path to the word list file from pwd.
*/
void create_data_structures(const std::string &word_file)
{
words_array.clear();
@ -82,6 +95,11 @@ namespace
input_stream.close();
}
/*!
* Tells if all the words passed in wlist was present in current word list file.
* \param wlist List of words to match.
* \return Whether they were all present or not.
*/
bool word_list_file_match(const std::vector<std::string> &wlist)
{
for (std::vector<std::string>::const_iterator it = wlist.begin(); it != wlist.end(); it++)
@ -95,15 +113,28 @@ namespace
}
}
/*!
* \namespace crypto
*/
namespace crypto
{
/*!
* \namespace ElectrumWords
*
* \brief Mnemonic seed word generation and wallet restoration.
*/
namespace ElectrumWords
{
/*!
* \brief Called to initialize it work with a word list file.
* \param language Language of the word list file.
* \param old_word_list Whether it is to use the old style word list file.
*/
void init(const std::string &language, bool old_word_list)
{
if (old_word_list)
{
// Use the old word list file if told to.
create_data_structures(WORD_LISTS_DIRECTORY + '/' + OLD_WORD_FILE);
is_old_style_mnemonics = true;
}
@ -119,6 +150,10 @@ namespace crypto
}
}
/*!
* \brief If the module is currenly using an old style word list.
* \return Whether it is currenly using an old style word list.
*/
bool get_is_old_style_mnemonics()
{
if (is_uninitialized())
@ -127,12 +162,12 @@ namespace crypto
}
return is_old_style_mnemonics;
}
/* convert words to bytes, 3 words -> 4 bytes
* returns:
* false if not a multiple of 3 words, or if a words is not in the
* words list
*
* true otherwise
/*!
* \brief Converts seed words to bytes (secret key).
* \param words String containing the words separated by spaces.
* \param dst To put the secret key restored from the words.
* \return false if not a multiple of 3 words, or if word is not in the words list
*/
bool words_to_bytes(const std::string& words, crypto::secret_key& dst)
{
@ -143,6 +178,7 @@ namespace crypto
std::vector<std::string> languages;
get_language_list(languages);
// Try to find a word list file that contains all the words in the word list.
std::vector<std::string>::iterator it;
for (it = languages.begin(); it != languages.end(); it++)
{
@ -152,6 +188,7 @@ namespace crypto
break;
}
}
// If no such file was found, see if the old style word list file has them all.
if (it == languages.end())
{
init("", true);
@ -192,10 +229,11 @@ namespace crypto
return true;
}
/* convert bytes to words, 4 bytes-> 3 words
* returns:
* false if wrong number of bytes (shouldn't be possible)
* true otherwise
/*!
* \brief Converts bytes (secret key) to seed words.
* \param src Secret key
* \param words Space separated words get copied here.
* \return Whether it was successful or not. Unsuccessful if wrong key size.
*/
bool bytes_to_words(const crypto::secret_key& src, std::string& words)
{
@ -229,6 +267,10 @@ namespace crypto
return false;
}
/*!
* \brief Gets a list of seed languages that are supported.
* \param languages The list gets added to this.
*/
void get_language_list(std::vector<std::string> &languages)
{
languages.clear();
@ -245,6 +287,6 @@ namespace crypto
}
}
} // namespace ElectrumWords
}
} // namespace crypto
}

View File

@ -26,7 +26,11 @@
// STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
// THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
/*
/*!
* \file electrum-words.h
*
* \brief Mnemonic seed generation and wallet restoration from them.
*
* This file and its cpp file are for translating Electrum-style word lists
* into their equivalent byte representations for cross-compatibility with
* that method of "backing up" one's wallet keys.
@ -37,14 +41,51 @@
#include <map>
#include "crypto/crypto.h" // for declaration of crypto::secret_key
/*!
* \namespace crypto
*/
namespace crypto
{
/*!
* \namespace ElectrumWords
*
* \brief Mnemonic seed word generation and wallet restoration.
*/
namespace ElectrumWords
{
/*!
* \brief Called to initialize it work with a word list file.
* \param language Language of the word list file.
* \param old_word_list Whether it is to use the old style word list file.
*/
void init(const std::string &language, bool old_word_list=false);
/*!
* \brief Converts seed words to bytes (secret key).
* \param words String containing the words separated by spaces.
* \param dst To put the secret key restored from the words.
* \return false if not a multiple of 3 words, or if word is not in the words list
*/
bool words_to_bytes(const std::string& words, crypto::secret_key& dst);
/*!
* \brief Converts bytes (secret key) to seed words.
* \param src Secret key
* \param words Space separated words get copied here.
* \return Whether it was successful or not. Unsuccessful if wrong key size.
*/
bool bytes_to_words(const crypto::secret_key& src, std::string& words);
/*!
* \brief Gets a list of seed languages that are supported.
* \param languages The list gets added to this.
*/
void get_language_list(std::vector<std::string> &languages);
/*!
* \brief If the module is currenly using an old style word list.
* \return Whether it is currenly using an old style word list.
*/
bool get_is_old_style_mnemonics();
}
}

View File

@ -28,6 +28,12 @@
//
// Parts of this file are originally copyright (c) 2012-2013 The Cryptonote developers
/*!
* \file simplewallet.cpp
*
* \brief Source file that defines simple_wallet class.
*/
#include <thread>
#include <iostream>
#include <boost/lexical_cast.hpp>
@ -438,6 +444,13 @@ bool simple_wallet::try_connect_to_daemon()
return true;
}
/*!
* \brief Gets the word seed language from the user.
*
* User is asked to choose from a list of supported languages.
*
* \return The chosen language.
*/
std::string simple_wallet::get_mnemonic_language()
{
std::vector<std::string> language_list;
@ -498,15 +511,16 @@ bool simple_wallet::new_wallet(const string &wallet_file, const std::string& pas
// convert rng value to electrum-style word list
std::string electrum_words;
// Ask for language if it is not a wallet restore or if the old version of the wallet
// had given the user an old style word list.
if (!m_restore_deterministic_wallet || crypto::ElectrumWords::get_is_old_style_mnemonics())
{
if (crypto::ElectrumWords::get_is_old_style_mnemonics())
{
// The user had used an older version of the wallet with old style mnemonics.
message_writer(epee::log_space::console_color_green, false) << "\nYou have been using " <<
"a deprecated word list file. Please use the new seed that we provide.\n";
}
// Ask for language if it is not a wallet restore or if the old version of the wallet
// had given the user an old style word list.
std::string mnemonic_language = get_mnemonic_language();
try
{

View File

@ -28,6 +28,11 @@
//
// Parts of this file are originally copyright (c) 2012-2013 The Cryptonote developers
/*!
* \file simplewallet.h
*
* \brief Header file that declares simple_wallet class.
*/
#pragma once
#include <memory>
@ -41,12 +46,15 @@
#include "password_container.h"
#include "crypto/crypto.h" // for definition of crypto::secret_key
/*!
* \namespace cryptonote
* \brief Holds cryptonote related classes and helpers.
*/
namespace cryptonote
{
/************************************************************************/
/* */
/************************************************************************/
/*!
* \brief Manages wallet operations. This is the most abstracted wallet class.
*/
class simple_wallet : public tools::i_wallet2_callback
{
public:
@ -92,6 +100,14 @@ namespace cryptonote
uint64_t get_daemon_blockchain_height(std::string& err);
bool try_connect_to_daemon();
bool ask_wallet_create_if_needed();
/*!
* \brief Gets the word seed language from the user.
*
* User is asked to choose from a list of supported languages.
*
* \return The chosen language.
*/
std::string get_mnemonic_language();
//----------------- i_wallet2_callback ---------------------