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