From c9287ee8e0d1b97fb5ba11d993ebf0a7ce4d5d11 Mon Sep 17 00:00:00 2001 From: john30 Date: Sat, 25 Mar 2017 16:50:43 +0100 Subject: [PATCH] added/updated documentation --- src/ebusd/bushandler.h | 3 +++ src/ebusd/main.cpp | 3 ++- src/ebusd/mainloop.cpp | 2 +- src/ebusd/mqtthandler.cpp | 4 ++-- src/lib/ebus/data.cpp | 2 +- src/lib/ebus/data.h | 4 ++-- src/lib/ebus/filereader.cpp | 11 ++++------- src/lib/ebus/filereader.h | 22 ++++++++++++++-------- src/lib/ebus/message.cpp | 5 +++-- src/lib/ebus/message.h | 36 +++++++++++++++++++++--------------- 10 files changed, 53 insertions(+), 39 deletions(-) diff --git a/src/ebusd/bushandler.h b/src/ebusd/bushandler.h index 0e5bee94..457f8afa 100644 --- a/src/ebusd/bushandler.h +++ b/src/ebusd/bushandler.h @@ -487,6 +487,8 @@ class BusHandler : public WaitThread { /** * Send a scan message on the bus and wait for the answer. * @param dstAddress the destination slave address to send to. + * @param loadScanConfig true to immediately load the message definitions matching the scan result. + * @param reload true to fully reload the scan results. * @return the result code. */ result_t scanAndWait(symbol_t dstAddress, bool loadScanConfig = false, bool reload = false); @@ -538,6 +540,7 @@ class BusHandler : public WaitThread { /** * Get the next slave address that still needs to be scanned or loaded. * @param lastAddress the last returned slave address, or 0 for returning the first one. + * @param onlyScanned true to return only already scanned addresses. * @return the next slave address that still needs to be scanned or loaded, or @a SYN. */ symbol_t getNextScanAddress(symbol_t lastAddress, bool onlyScanned = false); diff --git a/src/ebusd/main.cpp b/src/ebusd/main.cpp index f94b8a7f..4fe066c9 100644 --- a/src/ebusd/main.cpp +++ b/src/ebusd/main.cpp @@ -966,7 +966,8 @@ result_t loadScanConfigFile(MessageMap* messages, symbol_t address, string& rela symbol_t checkDest; unsigned int checkSw, checkHw; map defaults; - if (!messages->extractDefaultsFromFilename(name.substr(path.length()+1), defaults, &checkDest, &checkSw, &checkHw)) { + const string filename = name.substr(path.length()+1); + if (!messages->extractDefaultsFromFilename(filename, defaults, &checkDest, &checkSw, &checkHw)) { continue; } if (address != checkDest || (checkSw != UINT_MAX && sw != checkSw) || (checkHw != UINT_MAX && hw != checkHw)) { diff --git a/src/ebusd/mainloop.cpp b/src/ebusd/mainloop.cpp index 30bd42c5..5b44ded3 100644 --- a/src/ebusd/mainloop.cpp +++ b/src/ebusd/mainloop.cpp @@ -46,7 +46,7 @@ result_t UserList::getFieldMap(vector& row, string& errorDescription) { if (row.empty()) { row.push_back("name"); row.push_back("secret"); - row.push_back("*level"); // TODO last repeat is repeated as often as necessary in addFromFile... + row.push_back("*level"); return RESULT_OK; } map seen; diff --git a/src/ebusd/mqtthandler.cpp b/src/ebusd/mqtthandler.cpp index 1ebd2ba3..bb8583de 100644 --- a/src/ebusd/mqtthandler.cpp +++ b/src/ebusd/mqtthandler.cpp @@ -446,7 +446,7 @@ void MqttHandler::notifyTopic(string topic, string data) { name = field; break; case MESSAGEFIELD_DATAFIELDS: - //field = field; // TODO add support for writing a single field + // field = field; // TODO add support for writing a single field break; default: return; @@ -569,7 +569,7 @@ string MqttHandler::getTopic(Message* message, ssize_t fieldIndex) { } if (i < m_topicFields.size()) { if (m_topicFields[i] == MESSAGEFIELD_DATAFIELDS && fieldIndex >= 0) { - ret << message->getFieldName(fieldIndex); // TODO skip ignored fields + ret << message->getFieldName(fieldIndex); // TODO skip ignored fields } else { message->dumpField(ret, m_topicFields[i]); } diff --git a/src/lib/ebus/data.cpp b/src/lib/ebus/data.cpp index 3eca0dbc..7f8ac4ee 100644 --- a/src/lib/ebus/data.cpp +++ b/src/lib/ebus/data.cpp @@ -76,7 +76,7 @@ string getDataFieldName(const size_t fieldId) { return "comment"; default: return ""; - }; + } } result_t DataField::create(vector< map >& rows, string& errorDescription, diff --git a/src/lib/ebus/data.h b/src/lib/ebus/data.h index 6cf70f95..4175b6ca 100644 --- a/src/lib/ebus/data.h +++ b/src/lib/ebus/data.h @@ -117,8 +117,8 @@ class DataField { /** * Factory method for creating new instances. - * @param it the iterator to traverse for the definition parts. - * @param end the iterator pointing to the end of the definition parts. + * @param rows the mapped field definition rows. + * @param errorDescription a string in which to store the error description in case of error. * @param templates the @a DataFieldTemplates to be referenced by name, or NULL. * @param returnField the variable in which to store the created instance. * @param isWriteMessage whether the field is part of a write message (default false). diff --git a/src/lib/ebus/filereader.cpp b/src/lib/ebus/filereader.cpp index 11bb2245..e5e47275 100644 --- a/src/lib/ebus/filereader.cpp +++ b/src/lib/ebus/filereader.cpp @@ -19,6 +19,8 @@ #include "lib/ebus/filereader.h" #include #include +#include +#include #include #include #include @@ -35,7 +37,7 @@ using std::dec; result_t FileReader::readFromFile(const string filename, string& errorDescription, bool verbose, - map* defaults, size_t* hash, size_t* size, time_t* time) { //TODO use hash etc. + map* defaults, size_t* hash, size_t* size, time_t* time) { struct stat st; if (stat(filename.c_str(), &st) != 0) { errorDescription = filename; @@ -132,7 +134,7 @@ bool FileReader::splitFields(istream& ifs, vector& row, unsigned int& li *size += length + 1; // normalized with trailing endl } if (hash) { - *hash ^= (hashFunction(line) << 1) ^ (length << ( 7 * (lineNo % 5))); + *hash ^= (hashFunction(line) << 1) ^ (length << (7 * (lineNo % 5))); } if (!quotedText && (length == 0 || line[0] == '#' || (line.length() > 1 && line[0] == '/' && line[1] == '/'))) { if (lineNo == 1) { @@ -276,11 +278,6 @@ result_t MappedFileReader::addFromFile(vector& row, string& errorDescrip subRowsMapped.resize(subRowsMapped.size() - 1); } } -/*cout<<"row:"< #include +#include +#include #include #include #include "lib/ebus/symbol.h" @@ -92,6 +94,7 @@ class FileReader { * @param errorDescription a string in which to store the error description in case of error. * @param filename the name of the file being read. * @param lineNo the last line number (incremented with each line read). + * @param row the definition row to clear and update with the read data (for performance reasons only). * @param verbose whether to verbosely log problems. * @param hash optional pointer to a @a size_t value for updating with the hash of the line, or NULL. * @param size optional pointer to a @a size_t value for updating with the normalized length of the line, or NULL. @@ -147,13 +150,17 @@ class FileReader { }; +/** + * An abstract class derived from @a FileReader that additionally allows to using mapped name/value pairs with one + * main map and many sub maps. + */ class MappedFileReader : public FileReader { public: /** * Constructor. * @param supportsDefaults whether this instance supports rows with defaults (starting with a star). */ - MappedFileReader(bool supportsDefaults) : FileReader(), m_supportsDefaults(supportsDefaults) {} + explicit MappedFileReader(bool supportsDefaults) : FileReader(), m_supportsDefaults(supportsDefaults) {} /** * Destructor. @@ -170,10 +177,11 @@ class MappedFileReader : public FileReader { /** * Extract default values from the file name. - * @param name the name of the file (without path) + * @param filename the name of the file (without path) * @param defaults the default values by name to add to. - * @param software the variable in which to store the numeric software version, or NULL. - * @param hardware the variable in which to store the numeric software version, or NULL. + * @param destAddress a pointer to a variable in which to store the numeric destination address, or NULL. + * @param software a pointer to a in which to store the numeric software version, or NULL. + * @param hardware a pointer to a in which to store the numeric hardware version, or NULL. * @return true if the minimum parts were extracted, false otherwise. */ virtual bool extractDefaultsFromFilename(string filename, map& defaults, @@ -188,7 +196,7 @@ class MappedFileReader : public FileReader { /** * Get the field mapping from the given first line. * @param row the first line from which to extract the field mapping, or empty to use the default mapping. - * @param begin an iterator to the first column of the first line to read (for error reporting). + * @param errorDescription a string in which to store the error description in case of error. * @return @a RESULT_OK on success, or an error code. */ virtual result_t getFieldMap(vector& row, string& errorDescription) = 0; @@ -197,7 +205,7 @@ class MappedFileReader : public FileReader { * Add a default row that was read from a file. * @param row the default row by field name. * @param subRows the sub default rows, each by field name. - * @param subRowDefaults the sub default values by type and field name to add to. + * @param errorDescription a string in which to store the error description in case of error. * @param filename the name of the file being read. * @param lineNo the current line number in the file being read. * @return @a RESULT_OK on success, or an error code. @@ -212,8 +220,6 @@ class MappedFileReader : public FileReader { * Add a definition that was read from a file. * @param row the main definition row by field name. * @param subRows the sub definition rows, each by field name. - * @param rowDefaults all previously extracted default values by type and field name. - * @param subRowDefaults all previously extracted sub default values by type and field name. * @param errorDescription a string in which to store the error description in case of error. * @param filename the name of the file being read. * @param lineNo the current line number in the file being read. diff --git a/src/lib/ebus/message.cpp b/src/lib/ebus/message.cpp index a8d3822a..447e56d0 100644 --- a/src/lib/ebus/message.cpp +++ b/src/lib/ebus/message.cpp @@ -1413,7 +1413,7 @@ result_t Condition::create(const string condName, map row, map& row, string& errorDescription) { - // type (r[1-9];w;u),circuit,name,[comment],[QQ],ZZ,PBSB,[ID],field1,part (m/s),datatypes/templates,divider/values,unit,comment + // type (r[1-9];w;u),circuit,name,[comment],[QQ],ZZ,PBSB,[ID],field1,part (m/s),datatypes/templates,divider/values, + // unit,comment // minimum: type,name,PBSB,field,datatype if (row.empty()) { for (size_t fieldId = MESSAGEFIELD_RANGE_MIN; fieldId <= MESSAGEFIELD_RANGE_MAX; fieldId++) { diff --git a/src/lib/ebus/message.h b/src/lib/ebus/message.h index c9a67729..5a6cbb2e 100644 --- a/src/lib/ebus/message.h +++ b/src/lib/ebus/message.h @@ -201,9 +201,11 @@ class Message { /** * Factory method for creating new instances. - * @param it the iterator to traverse for the definition parts. - * @param end the iterator pointing to the end of the definition parts. - * @param defaultsRows a @a vector with rows containing defaults, or NULL. + * @param row the mapped message definition row. + * @param subRows the mapped field definition rows. + * @param rowDefaults the mapped message definition defaults. + * @param subRowDefaults the mapped field definition defaults. + * @param errorDescription a string in which to store the error description in case of error. * @param condition the @a Condition instance for the message, or NULL. * @param filename the name of the file being read. * @param templates the @a DataFieldTemplates to be referenced by name, or NULL. @@ -219,9 +221,17 @@ class Message { /** * Create a new scan @a Message instance. * @param broadcast true for broadcast scan message, false for scan message to be sent to a slave address. + * @return the new scan @a Message instance. */ static Message* createScanMessage(bool broadcast = false); + /** + * Extract the known field IDs from the input string. + * @param str the input string with the field names separated by @a FIELD_SEPARATOR. + * @param fields the vector to update with the extracted field IDs with. + * @param checkAbbreviated true to also check for abbreviated field names. + * @return true when all fields are valid. + */ static bool extractFieldIds(string str, vector& fields, bool checkAbbreviated = true); /** @@ -837,10 +847,8 @@ class Condition { /** * Factory method for creating a new instance. * @param condName the name of the condition. - * @param it the iterator to traverse for the definition parts. - * @param end the iterator pointing to the end of the definition parts. - * @param defaultDest the valid destination address extracted from the file name (from ZZ part), or empty. - * @param defaultCircuit the valid circuit name extracted from the file name (from IDENT part), or empty. + * @param row the mapped definition row. + * @param rowDefaults the mapped definition defaults. * @param returnValue the variable in which to store the created instance. * @return @a RESULT_OK on success, or an error code. */ @@ -1114,9 +1122,7 @@ class Instruction { * @param condition the @a Condition this instruction requires, or null. * @param singleton whether this @a Instruction belongs to a set of instructions of which only the first one may be * executed for the same source file. - * @param defaultDest the default destination address, or empty. - * @param defaultCircuit the default circuit name, or empty. - * @param defaultSuffix the default circuit name suffix (starting with a "."), or empty. + * @param defaults the mapped definition defaults. */ Instruction(Condition* condition, const bool singleton, map& defaults) : m_condition(condition), m_singleton(singleton), m_defaults(defaults) { } @@ -1195,10 +1201,7 @@ class LoadInstruction : public Instruction { * @param condition the @a Condition this instruction requires, or null. * @param singleton whether this @a Instruction belongs to a set of instructions of which only the first one may be * executed for the same source file. - * @param defaultDest the default destination address (may be overwritten by file name), or empty. - * @param defaultCircuit the default circuit name (may be overwritten by file name), or empty. - * @param defaultSuffix the default circuit name suffix (starting with a ".", may be overwritten by file name), or - * empty. + * @param defaults the mapped definition defaults. * @param filename the name of the file to load. */ LoadInstruction(Condition* condition, const bool singleton, map& defaults, const string filename) @@ -1293,13 +1296,14 @@ class MessageMap : public MappedFileReader { result_t getFieldMap(vector& row, string& errorDescription) override; // @copydoc - virtual result_t addDefaultFromFile(map& row, vector< map >& subRows, + result_t addDefaultFromFile(map& row, vector< map >& subRows, string& errorDescription, const string filename, unsigned int lineNo) override; /** * Read the @a Condition instance(s) from the types field. * @param types the field from which to read the @a Condition instance(s). * @param filename the name of the file being read. + * @param errorDescription a string in which to store the error description in case of error. * @param condition the variable in which to store the result. * @return @a RESULT_OK on success, or an error code. */ @@ -1332,6 +1336,7 @@ class MessageMap : public MappedFileReader { /** * Resolve all @a Condition instances. + * @param errorDescription a string in which to store the error description in case of error. * @param verbose whether to verbosely add all problems to the error message. * @return @a RESULT_OK on success, or an error code. */ @@ -1340,6 +1345,7 @@ class MessageMap : public MappedFileReader { /** * Resolve a @a Condition. * @param condition the @a Condition to resolve. + * @param errorDescription a string in which to store the error description in case of error. * @param readMessageFunc the function to call for immediate reading of a @a Message from the bus, or NULL. * @return @a RESULT_OK on success, or an error code. */