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 2023 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 <cstdlib>
40 #include <cstdint>
41 
43 
44 //---< NAMESPACE >--------------------------------------------------------------
45 
46 namespace riegl {
47 namespace rdb {
48 namespace pointcloud {
49 
50 //---< CLASS Changelog >--------------------------------------------------------
51 /*!
52  * \brief Manage point cloud changelog
53  *
54  * Each database maintains a log of changes made to a point cloud.
55  *
56  * A separate log entry is created for each database transaction or management
57  * operation. A log entry contains log messages with high-level information
58  * about the modifications as follows:
59  *
60  * - current transaction number, title, agent, date and time
61  * - number of data points added, updated, removed
62  * - list of point attributes affected by point operations
63  * - list of point attributes added, updated, removed
64  * - list of metadata entries added, updated, removed
65  * - modification of level-of-detail parameters
66  * - management: restore transaction, finalize and vacuum database
67  * - optional: log messages (some text) provided by client software
68  *
69  * Details like actual point data, attribute definitions or metadata values are
70  * not recorded.
71  *
72  * \see riegl::rdb::Pointcloud::changelog()
73  *
74  * \since 2.3.0
75  */
76 class Changelog
77 {
78 public:
79  /*!
80  * \brief Constructor
81  * \note You cannot create new Changelog objects directly,
82  * use riegl::rdb::Pointcloud::changelog() instead.
83  */
84  explicit Changelog(riegl::rdb::PointcloudData* pointcloud);
85 
86  /*!
87  * \brief Append text to current log entry
88  *
89  * This function appends text message(s) to the log entry of the current
90  * database transaction. As with all strings in RDB, the characters are
91  * expected to be UTF-8 encoded. Line endings are normalized (i.e. CR+LF
92  * and CR are converted to LF).
93  *
94  * Calling this function while no transaction is active has no effect.
95  *
96  * \since 2.3.0
97  */
98  void appendMessage(const std::string &message);
99 
100  /*!
101  * \brief Verify log entry signature
102  *
103  * Returns 'false' if:
104  *
105  * - there is no signature for the log entry
106  * - the signature does not match the log messages
107  * - a wrong signature encryption key was given
108  *
109  * Otherwise returns 'true'.
110  *
111  * \since 2.3.0
112  */
113  static bool verifyLogEntry(
114  const std::string &entry, //!< [in] log entry messages to verify
115  const std::uint32_t method, //!< [in] signature method (1: default)
116  const std::uint32_t key_size, //!< [in] signature encryption key size (at least 32 byte)
117  const void* const key_data //!< [in] signature encryption key buffer
118  );
119 
120  /*!
121  * \brief Export changelog to text file
122  *
123  * This function exports the entire changelog to a single text file.
124  * The file is UTF-8 encoded and text lines are separated by a single
125  * line feed character (LF, ASCII 0x0A), regardless of the operating
126  * system the file was created on.
127  *
128  * \since 2.3.0
129  */
130  void exportToTextfile(
131  const std::string &filename //!< [in] output text filename
132  );
133 
134  /*!
135  * \brief Import changelog from database
136  *
137  * This function imports the entire changelog from an other database.
138  * This is intended for applications where a database is to be replaced
139  * by a new one (often derived from the old one) and the processing
140  * history is to be retained.
141  *
142  * \since 2.3.0
143  */
144  void importFromDatabase(
145  const std::string &filename //!< [in] input database filename
146  );
147 
148 private:
149  riegl::rdb::PointcloudData *data;
150 };
151 
152 }}} // namespace riegl::rdb::pointcloud
153 
154 #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.
static bool verifyLogEntry(const std::string &entry, const std::uint32_t method, const std::uint32_t key_size, const void *const key_data)
Verify log entry signature.
void importFromDatabase(const std::string &filename)
Import changelog from database.
Changelog(riegl::rdb::PointcloudData *pointcloud)
Constructor.
Manage point cloud changelog.
Definition: changelog.hpp:76
Pointcloud class implementation details.