RDB 2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
changelog.hpp
Go to the documentation of this file.
1 /*
2  *******************************************************************************
3  *
4  * Copyright 2021 RIEGL Laser Measurement Systems
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  *
18  * SPDX-License-Identifier: Apache-2.0
19  *
20  *******************************************************************************
21  */
22 /*!
23  *******************************************************************************
24  *
25  * \file changelog.hpp
26  * \author RIEGL LMS GmbH, Austria
27  * \brief Manage point cloud changelog
28  * \version 2020-06-29/AW: Initial version
29  *
30  *******************************************************************************
31  */
32 
33 #ifndef RIEGL_RDB_POINTCLOUD_CHANGELOG_HPP
34 #define RIEGL_RDB_POINTCLOUD_CHANGELOG_HPP
35 
36 //---< INCLUDES >---------------------------------------------------------------
37 
38 #include <string>
39 #include <cstdint>
41 
42 //---< NAMESPACE >--------------------------------------------------------------
43 
44 namespace riegl {
45 namespace rdb {
46 namespace pointcloud {
47 
48 //---< CLASS Changelog >--------------------------------------------------------
49 /*!
50  * \brief Manage point cloud changelog
51  *
52  * Each database maintains a log of changes made to a point cloud.
53  *
54  * A separate log entry is created for each database transaction or management
55  * operation. A log entry contains log messages with high-level information
56  * about the modifications as follows:
57  *
58  * - current transaction number, title, agent, date and time
59  * - number of data points added, updated, removed
60  * - list of point attributes affected by point operations
61  * - list of point attributes added, updated, removed
62  * - list of metadata entries added, updated, removed
63  * - modification of level-of-detail parameters
64  * - management: restore transaction, finalize and vacuum database
65  * - optional: log messages (some text) provided by client software
66  *
67  * Details like actual point data, attribute definitions or metadata values are
68  * not recorded.
69  *
70  * \see riegl::rdb::Pointcloud::changelog()
71  *
72  * \since 2.3.0
73  */
74 class Changelog
75 {
76 public:
77  /*!
78  * \brief Constructor
79  * \note You cannot create new Changelog objects directly,
80  * use riegl::rdb::Pointcloud::changelog() instead.
81  */
82  explicit Changelog(riegl::rdb::PointcloudData* pointcloud);
83 
84  /*!
85  * \brief Append text to current log entry
86  *
87  * This function appends text message(s) to the log entry of the current
88  * database transaction. As with all strings in RDB, the characters are
89  * expected to be UTF-8 encoded. Line endings are normalized (i.e. CR+LF
90  * and CR are converted to LF).
91  *
92  * Calling this function while no transaction is active has no effect.
93  *
94  * \since 2.3.0
95  */
96  void appendMessage(const std::string &message);
97 
98  /*!
99  * \brief Verify log entry signature
100  *
101  * Returns 'false' if:
102  *
103  * - there is no signature for the log entry
104  * - the signature does not match the log messages
105  * - a wrong signature encryption key was given
106  *
107  * Otherwise returns 'true'.
108  *
109  * \since 2.3.0
110  */
111  static bool verifyLogEntry(
112  const std::string &entry, //!< [in] log entry messages to verify
113  const uint32_t method, //!< [in] signature method (1: default)
114  const uint32_t key_size, //!< [in] signature encryption key size (at least 32 byte)
115  const void* const key_data //!< [in] signature encryption key buffer
116  );
117 
118  /*!
119  * \brief Export changelog to text file
120  *
121  * This function exports the entire changelog to a single text file.
122  * The file is UTF-8 encoded and text lines are separated by a single
123  * line feed character (LF, ASCII 0x0A), regardless of the operating
124  * system the file was created on.
125  *
126  * \since 2.3.0
127  */
128  void exportToTextfile(
129  const std::string &filename //!< [in] output text filename
130  );
131 
132  /*!
133  * \brief Import changelog from database
134  *
135  * This function imports the entire changelog from an other database.
136  * This is intended for applications where a database is to be replaced
137  * by a new one (often derived from the old one) and the processing
138  * history is to be retained.
139  *
140  * \since 2.3.0
141  */
142  void importFromDatabase(
143  const std::string &filename //!< [in] input database filename
144  );
145 
146 private:
147  riegl::rdb::PointcloudData *data;
148 };
149 
150 }}} // namespace riegl::rdb::pointcloud
151 
152 #endif // RIEGL_RDB_POINTCLOUD_CHANGELOG_HPP
void appendMessage(const std::string &message)
Append text to current log entry.
void exportToTextfile(const std::string &filename)
Export changelog to text file.
void importFromDatabase(const std::string &filename)
Import changelog from database.
Changelog(riegl::rdb::PointcloudData *pointcloud)
Constructor.
Manage point cloud changelog.
Definition: changelog.hpp:74
Pointcloud class implementation details.
static bool verifyLogEntry(const std::string &entry, const uint32_t method, const uint32_t key_size, const void *const key_data)
Verify log entry signature.