Commit bd0c9cd7 authored by Axel Auweter's avatar Axel Auweter
Browse files

Some more doxygenization of DCDBLib.

parent e566984a
......@@ -37,7 +37,7 @@
* - knc_id
*/
typedef union {
uint64_t raw;
uint64_t raw; /** The raw bit-field representing the DeviceLocation */
struct {
uint8_t knc_id;
uint8_t bnc_id;
......@@ -61,9 +61,9 @@ typedef union {
* approach is, for example, to use MAC addresses as the device_id.
*/
typedef struct {
uint64_t sensor_number : 16;
uint64_t rsvd : 16;
uint64_t device_id : 32;
uint64_t sensor_number : 16; /** The sensor_number of the sensor */
uint64_t rsvd : 16; /** Reserved */
uint64_t device_id : 32; /** The location-independent device_id */
} DeviceSensorId;
/**
......
......@@ -21,14 +21,46 @@ class SensorDataStoreImpl
{
protected:
CassandraBackend* csBackend;
/**
* @brief This function returns a "key" string which
* corresponds to the supplied SensorId object.
* @param sid The SensorId object to convert
* @return Returns the serialized string that can be used by Cassandra as row key.
*/
std::string sidConvert(SensorId *sid);
public:
/**
* @brief This function connects to the database and initializes keyspaces and column families
* @param hostname The hostname of a Cassandra front-end node
* @param port The port number of the Cassandra front-end node
*/
void init(std::string hostname, int port);
/**
* @brief This function converts a MQTT topic string to a SensorId object
* @param topic The MQTT topic string to convert
* @param sid A preallocated SensorId object to fill
*/
bool topicToSid(SensorId* sid, std::string topic);
/**
* @brief This function inserts a sensor reading into the database
* @param sid The SensorId object representing the sensor (typically obtained from topicToSid)
* @param ts The timestamp of the reading (nanoseconds since Unix epoch)
* @param value The sensor reading as 64-bit unsigned integer
*/
void insert(SensorId* sid, uint64_t ts, uint64_t value);
/**
* @brief This is the standard constructor of the SensorDataStoreImpl class.
* @param csb A CassandraBackend object to do the raw database access.
*/
SensorDataStoreImpl(CassandraBackend *csb);
/**
* @brief The standard desctructor of SensorDataStoreImpl.
*/
virtual ~SensorDataStoreImpl();
};
......
......@@ -31,6 +31,12 @@
#include "sensordatastore_internal.h"
/**
* @details
* This function serializes a SensorId object into a
* big-endian 128-bit character array represented as
* std::string.
*/
string SensorDataStoreImpl::sidConvert(SensorId *sid)
{
uint64_t ll[2];
......@@ -39,6 +45,19 @@ string SensorDataStoreImpl::sidConvert(SensorId *sid)
return string((char*)ll, 16);
}
/**
* @details
* The conversion of a MQTT message topic to a SensorId
* object is performed by byte-wise scanning of the string,
* and skipping of all characters except for those in the
* range [0-9,a-f,A-F]. Each character is then turned from
* hex string into its binary representation an OR'ed into
* the 128-bit raw fields of the SensorId object.
*
* Applications should not call this function directly, but
* use the topicToSid function provided by the
* SensorDataStore class.
*/
bool SensorDataStoreImpl::topicToSid(SensorId* sid, string topic)
{
uint64_t pos = 0;
......@@ -63,6 +82,17 @@ bool SensorDataStoreImpl::topicToSid(SensorId* sid, string topic)
return pos == 128;
}
/**
* @details
* Initialization of the SensorDataStore happens in three
* steps:
* - Establish Connection
* - Check if all keyspaces are present and create them if not
* - Check if all column families are present and create them if not
*
* Applications should not call this function directly, but
* use the init function provideed by the SensorDataStore class.
*/
void SensorDataStoreImpl::init(string hostname, int port) {
/*
......@@ -106,6 +136,20 @@ void SensorDataStoreImpl::init(string hostname, int port) {
}
}
/**
* @details
* To insert a sensor reading, the Rsvd field of the SensorId must
* be filled with a time component that ensures that the maximum
* number of 2^32 columns per key is not exceeded while still
* allowing relatively easy retrieval of data.
*
* We achieve this by using a "week-stamp" (i.e. number of weeks
* since Unix epoch) within the Rsvd field of the SensorId before
* calling the Cassandra Backend to do the raw insert.
*
* Applications should not call this function directly, but
* use the insert function provided by the SensorDataStore class.
*/
void SensorDataStoreImpl::insert(SensorId* sid, uint64_t ts, uint64_t value)
{
/* Calculate and insert week number */
......@@ -116,11 +160,20 @@ void SensorDataStoreImpl::insert(SensorId* sid, uint64_t ts, uint64_t value)
csBackend->insert(CF_SENSORDATA, sidConvert(sid), ts, value);
}
/**
* @details
* This constructor only sets the internal csBackend variable to
* the externally provided CassandraBackend object.
*/
SensorDataStoreImpl::SensorDataStoreImpl(CassandraBackend *csb)
{
csBackend = csb;
}
/**
* @details
* Due to the simplicity of the class, the destructor is left empty.
*/
SensorDataStoreImpl::~SensorDataStoreImpl()
{
}
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment