RDB 2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
metaData.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 metaData.hpp
26  * \author RIEGL LMS GmbH, Austria
27  * \brief Manage point cloud meta data
28  * \version 2015-10-14/AW: Initial version
29  * \version 2017-11-24/AW: Constructors declared as "explicit" (#2825)
30  * \version 2018-06-01/AW: New function to validate metadata entry (#3109)
31  * \version 2020-03-30/AW: New functions for metadata signatures (#3570)
32  *
33  *******************************************************************************
34  */
35 
36 #ifndef RIEGL_RDB_POINTCLOUD_METADATA_HPP
37 #define RIEGL_RDB_POINTCLOUD_METADATA_HPP
38 
39 //---< INCLUDES >---------------------------------------------------------------
40 
41 #include <memory>
42 #include <string>
43 #include <vector>
44 #include <cstdlib>
45 #include <cstdint>
46 
48 
49 //---< NAMESPACE >--------------------------------------------------------------
50 
51 namespace riegl {
52 namespace rdb {
53 namespace pointcloud {
54 
55 //---< CLASS MetaData >---------------------------------------------------------
56 /*!
57  * \brief Manage point cloud meta data
58  *
59  * This class allows to manage database-wide properties (aka. "meta-data").
60  * Arbitrary properties can be stored in key-value manner along with the
61  * point cloud in the database. This might be used for example to store
62  * comments, operator/software name or georeferencing information.
63  *
64  * \see riegl::rdb::Pointcloud::metaData()
65  */
66 class MetaData
67 {
68 public:
69  /*!
70  * \brief Constructor
71  * \note You cannot create new MetaData objects directly,
72  * use riegl::rdb::Pointcloud::metaData() instead.
73  */
74  explicit MetaData(riegl::rdb::PointcloudData* pointcloud);
75 
76  /*!
77  * \brief Query property names
78  *
79  * \returns a list of property names
80  */
81  std::vector<std::string> list() const;
82 
83  /*!
84  * \brief Check if property exists
85  *
86  * \note Property names are case sensitive (i.e. "name" and "NAME" are different properties).
87  * \returns true if a property with given name exists
88  */
89  bool exists(
90  const std::string &name //!< [in] property name
91  ) const;
92 
93  /*!
94  * \brief Set property value
95  *
96  * \note Strings are truncated before the first zero byte (if any).
97  */
98  void set(
99  const std::string &name, //!< [in] property name
100  const std::string &value //!< [in] property value
101  );
102 
103  /*!
104  * \brief Get property value
105  *
106  * If the given property name could not be found, the function returns
107  * the given default value.
108  */
109  std::string get(
110  const std::string &name, //!< [in] property name
111  const std::string &defaultValue = "" //!< [in] default value
112  ) const;
113 
114  /*!
115  * \brief Delete property
116  *
117  * If the given property name could not be found, this function does not fail.
118  */
119  void remove(
120  const std::string &name //!< [in] property name
121  );
122 
123  /*!
124  * \brief Validate property value
125  *
126  * This function validates the property given by 'name' against the
127  * corresponding built-in schema for RIEGL default metadata entries.
128  *
129  * If the value does not correspond to the schema, an exception
130  * is thrown and the reason can be found in the exception details.
131  */
132  void validate(
133  const std::string &name //!< [in] name of property to be validated
134  );
135 
136  /*!
137  * \brief Validate value
138  *
139  * This function validates the given JSON value against the JSON schema.
140  *
141  * If the value does not correspond to the schema, an exception
142  * is thrown and the reason can be found in the exception details.
143  */
144  void validate(
145  const std::string &value, //!< [in] value to be validated
146  const std::string &schema //!< [in] schema to be validated against
147  );
148 
149  /*!
150  * \brief Create a signature for a metadata entry.
151  *
152  * The signature is stored next to the metadata entry in the database file
153  * and cannot be read out or modified. A transaction must be started first.
154  *
155  * Set 'method' to 0 to delete an existing signature ('key_size' and
156  * 'key_data' are ignored in this case).
157  *
158  * \since 2.3.0
159  */
160  void createSignature(
161  const std::string &name, //!< [in] name of metadata entry to sign
162  const std::uint32_t method, //!< [in] signature method (0: delete, 1: default)
163  const std::uint32_t key_size, //!< [in] signature encryption key size (at least 32 byte)
164  const void* const key_data //!< [in] signature encryption key buffer
165  );
166 
167  /*!
168  * \brief Verify the signature of a metadata entry.
169  *
170  * Returns 'false' if:
171  *
172  * - there is no signature for the metadata entry
173  * - the signature does not match the current value
174  * - a wrong signature encryption key was given
175  *
176  * Otherwise returns 'true'.
177  *
178  * Set 'method' to 0 to check if a signature exists, no matter if it is
179  * valid or not ('key_size' and 'key_data' are ignored in this case).
180  *
181  * \since 2.3.0
182  */
183  bool verifySignature(
184  const std::string &name, //!< [in] name of metadata entry to verify
185  const std::uint32_t method, //!< [in] signature method (0: exists, 1: default)
186  const std::uint32_t key_size, //!< [in] signature encryption key size (at least 32 byte)
187  const void* const key_data //!< [in] signature encryption key buffer
188  ) const;
189 
190 private:
191  riegl::rdb::PointcloudData *data;
192 };
193 
194 }}} // namespace riegl::rdb::pointcloud
195 
196 #endif // RIEGL_RDB_POINTCLOUD_METADATA_HPP
std::vector< std::string > list() const
Query property names.
bool verifySignature(const std::string &name, const std::uint32_t method, const std::uint32_t key_size, const void *const key_data) const
Verify the signature of a metadata entry.
void createSignature(const std::string &name, const std::uint32_t method, const std::uint32_t key_size, const void *const key_data)
Create a signature for a metadata entry.
bool exists(const std::string &name) const
Check if property exists.
MetaData(riegl::rdb::PointcloudData *pointcloud)
Constructor.
Pointcloud class implementation details.
void validate(const std::string &name)
Validate property value.
void set(const std::string &name, const std::string &value)
Set property value.
Manage point cloud meta data.
Definition: metaData.hpp:66