Google Cloud Storage C++ Client  1.32.1
A C++ Client Library for Google Cloud Storage
object_metadata.h
Go to the documentation of this file.
1 // Copyright 2018 Google LLC
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_OBJECT_METADATA_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_OBJECT_METADATA_H
17 
18 #include "google/cloud/storage/internal/common_metadata.h"
19 #include "google/cloud/storage/internal/complex_option.h"
20 #include "google/cloud/storage/object_access_control.h"
21 #include "google/cloud/storage/version.h"
22 #include "google/cloud/optional.h"
23 #include "google/cloud/status_or.h"
24 #include "absl/types/optional.h"
25 #include <chrono>
26 #include <map>
27 #include <string>
28 #include <vector>
29 
30 namespace google {
31 namespace cloud {
32 namespace storage {
33 inline namespace STORAGE_CLIENT_NS {
34 namespace internal {
35 struct ObjectMetadataParser;
36 class GrpcClient;
37 } // namespace internal
38 
39 /// A simple representation for the customerEncryption field.
41  // The encryption algorithm name.
42  std::string encryption_algorithm;
43  // The SHA256 hash of the encryption key.
44  std::string key_sha256;
45 };
46 
47 /// Defines one of the source objects for a compose operation.
49  std::string object_name;
50  absl::optional<std::int64_t> generation;
51  absl::optional<std::int64_t> if_generation_match;
52 };
53 
54 std::ostream& operator<<(std::ostream& os, ComposeSourceObject const& r);
55 
56 inline bool operator==(CustomerEncryption const& lhs,
57  CustomerEncryption const& rhs) {
58  return std::tie(lhs.encryption_algorithm, lhs.key_sha256) ==
59  std::tie(rhs.encryption_algorithm, rhs.key_sha256);
60 }
61 
62 inline bool operator<(CustomerEncryption const& lhs,
63  CustomerEncryption const& rhs) {
64  return std::tie(lhs.encryption_algorithm, lhs.key_sha256) <
65  std::tie(rhs.encryption_algorithm, rhs.key_sha256);
66 }
67 
68 inline bool operator!=(CustomerEncryption const& lhs,
69  CustomerEncryption const& rhs) {
70  return std::rel_ops::operator!=(lhs, rhs);
71 }
72 
73 inline bool operator>(CustomerEncryption const& lhs,
74  CustomerEncryption const& rhs) {
75  return std::rel_ops::operator>(lhs, rhs);
76 }
77 
78 inline bool operator<=(CustomerEncryption const& lhs,
79  CustomerEncryption const& rhs) {
80  return std::rel_ops::operator<=(lhs, rhs);
81 }
82 
83 inline bool operator>=(CustomerEncryption const& lhs,
84  CustomerEncryption const& rhs) {
85  return std::rel_ops::operator>=(lhs, rhs);
86 }
87 
88 /**
89  * Represents the metadata for a Google Cloud Storage Object.
90  */
91 class ObjectMetadata : private internal::CommonMetadata<ObjectMetadata> {
92  public:
93  ObjectMetadata() = default;
94 
95  // Please keep these in alphabetical order, that make it easier to verify we
96  // have actually implemented all of them.
97  std::vector<ObjectAccessControl> const& acl() const { return acl_; }
98  std::vector<ObjectAccessControl>& mutable_acl() { return acl_; }
100  acl_ = std::move(acl);
101  return *this;
102  }
103 
104  std::string const& bucket() const { return bucket_; }
105 
106  std::string const& cache_control() const { return cache_control_; }
107  ObjectMetadata& set_cache_control(std::string cache_control) {
108  cache_control_ = std::move(cache_control);
109  return *this;
110  }
111 
112  std::int32_t component_count() const { return component_count_; }
113 
114  std::string content_disposition() const { return content_disposition_; }
116  content_disposition_ = std::move(value);
117  return *this;
118  }
119 
120  std::string content_encoding() const { return content_encoding_; }
121  ObjectMetadata& set_content_encoding(std::string value) {
122  content_encoding_ = std::move(value);
123  return *this;
124  }
125 
126  std::string content_language() const { return content_language_; }
127  ObjectMetadata& set_content_language(std::string value) {
128  content_language_ = std::move(value);
129  return *this;
130  }
131 
132  std::string content_type() const { return content_type_; }
133  ObjectMetadata& set_content_type(std::string value) {
134  content_type_ = std::move(value);
135  return *this;
136  }
137 
138  std::string const& crc32c() const { return crc32c_; }
139 
140  bool has_customer_encryption() const {
141  return customer_encryption_.has_value();
142  }
144  return customer_encryption_.value();
145  }
146 
147  using CommonMetadata::etag;
148 
149  bool event_based_hold() const { return event_based_hold_; }
151  event_based_hold_ = v;
152  return *this;
153  }
154 
155  std::int64_t generation() const { return generation_; }
156 
157  using CommonMetadata::id;
158  using CommonMetadata::kind;
159 
160  std::string const& kms_key_name() const { return kms_key_name_; }
161  std::string const& md5_hash() const { return md5_hash_; }
162  std::string const& media_link() const { return media_link_; }
163 
164  //@{
165  /// @name Accessors and modifiers to the `metadata` labels.
166  bool has_metadata(std::string const& key) const {
167  return metadata_.end() != metadata_.find(key);
168  }
169  std::string const& metadata(std::string const& key) const {
170  return metadata_.at(key);
171  }
172 
173  /// Delete a metadata entry. This is a no-op if the key does not exist.
174  ObjectMetadata& delete_metadata(std::string const& key) {
175  auto i = metadata_.find(key);
176  if (i == metadata_.end()) {
177  return *this;
178  }
179  metadata_.erase(i);
180  return *this;
181  }
182 
183  /// Insert or update the metadata entry.
184  ObjectMetadata& upsert_metadata(std::string key, std::string value) {
185  auto i = metadata_.lower_bound(key);
186  if (i == metadata_.end() || i->first != key) {
187  metadata_.emplace_hint(i, std::move(key), std::move(value));
188  } else {
189  i->second = std::move(value);
190  }
191  return *this;
192  }
193 
194  std::map<std::string, std::string> const& metadata() const {
195  return metadata_;
196  }
197  std::map<std::string, std::string>& mutable_metadata() { return metadata_; }
198  //@}
199 
200  using CommonMetadata::has_owner;
201  using CommonMetadata::metageneration;
202  using CommonMetadata::name;
203  using CommonMetadata::owner;
204 
205  std::chrono::system_clock::time_point retention_expiration_time() const {
206  return retention_expiration_time_;
207  }
208 
209  using CommonMetadata::self_link;
210 
211  std::uint64_t size() const { return size_; }
212 
213  using CommonMetadata::storage_class;
215  CommonMetadata::set_storage_class(std::move(v));
216  return *this;
217  }
218 
219  bool temporary_hold() const { return temporary_hold_; }
221  temporary_hold_ = v;
222  return *this;
223  }
224 
225  using CommonMetadata::time_created;
226 
227  std::chrono::system_clock::time_point time_deleted() const {
228  return time_deleted_;
229  }
230  std::chrono::system_clock::time_point time_storage_class_updated() const {
231  return time_storage_class_updated_;
232  }
233 
234  using CommonMetadata::updated;
235 
236  bool has_custom_time() const { return custom_time_.has_value(); }
237  std::chrono::system_clock::time_point custom_time() const {
238  return custom_time_.value_or(std::chrono::system_clock::time_point{});
239  }
240  ObjectMetadata& set_custom_time(std::chrono::system_clock::time_point v) {
241  custom_time_ = v;
242  return *this;
243  }
245  custom_time_.reset();
246  return *this;
247  }
248 
249  friend bool operator==(ObjectMetadata const& lhs, ObjectMetadata const& rhs);
250  friend bool operator!=(ObjectMetadata const& lhs, ObjectMetadata const& rhs) {
251  return !(lhs == rhs);
252  }
253 
254  private:
255  friend struct internal::ObjectMetadataParser;
256  friend class internal::GrpcClient;
257 
258  friend std::ostream& operator<<(std::ostream& os, ObjectMetadata const& rhs);
259  // Keep the fields in alphabetical order.
260  std::vector<ObjectAccessControl> acl_;
261  std::string bucket_;
262  std::string cache_control_;
263  std::int32_t component_count_{0};
264  std::string content_disposition_;
265  std::string content_encoding_;
266  std::string content_language_;
267  std::string content_type_;
268  std::string crc32c_;
269  absl::optional<CustomerEncryption> customer_encryption_;
270  bool event_based_hold_{false};
271  std::int64_t generation_{0};
272  std::string kms_key_name_;
273  std::string md5_hash_;
274  std::string media_link_;
275  std::map<std::string, std::string> metadata_;
276  std::chrono::system_clock::time_point retention_expiration_time_;
277  std::uint64_t size_{0};
278  bool temporary_hold_{false};
279  std::chrono::system_clock::time_point time_deleted_;
280  std::chrono::system_clock::time_point time_storage_class_updated_;
281  absl::optional<std::chrono::system_clock::time_point> custom_time_;
282 };
283 
284 std::ostream& operator<<(std::ostream& os, ObjectMetadata const& rhs);
285 
286 /**
287  * Prepares a patch for the Bucket resource.
288  *
289  * The Bucket resource has many modifiable fields. The application may send a
290  * patch request to change (or delete) a small fraction of these fields by using
291  * this object.
292  *
293  * @see
294  * https://cloud.google.com/storage/docs/json_api/v1/how-tos/performance#patch
295  * for general information on PATCH requests for the Google Cloud Storage
296  * JSON API.
297  */
299  public:
301 
302  std::string BuildPatch() const;
303 
304  ObjectMetadataPatchBuilder& SetAcl(std::vector<ObjectAccessControl> const& v);
305 
306  /**
307  * Clears the ACL.
308  *
309  * @warning Currently the server ignores requests to reset the full ACL.
310  */
312 
313  ObjectMetadataPatchBuilder& SetCacheControl(std::string const& v);
315  ObjectMetadataPatchBuilder& SetContentDisposition(std::string const& v);
317  ObjectMetadataPatchBuilder& SetContentEncoding(std::string const& v);
319  ObjectMetadataPatchBuilder& SetContentLanguage(std::string const& v);
321  ObjectMetadataPatchBuilder& SetContentType(std::string const& v);
325 
326  ObjectMetadataPatchBuilder& SetMetadata(std::string const& key,
327  std::string const& value);
328  ObjectMetadataPatchBuilder& ResetMetadata(std::string const& key);
330 
333 
334  /**
335  * Change the `custom_time` field.
336  *
337  * @par Example
338  * @snippet storage_object_samples.cc object custom time
339  */
341  std::chrono::system_clock::time_point tp);
343 
344  private:
345  internal::PatchBuilder impl_;
346  bool metadata_subpatch_dirty_{false};
347  internal::PatchBuilder metadata_subpatch_;
348 };
349 
350 /**
351  * A request option to define the object metadata attributes.
352  */
354  : public internal::ComplexOption<WithObjectMetadata, ObjectMetadata> {
355  using ComplexOption<WithObjectMetadata, ObjectMetadata>::ComplexOption;
356  // GCC <= 7.0 does not use the inherited default constructor, redeclare it
357  // explicitly
358  WithObjectMetadata() = default;
359  static char const* name() { return "object-metadata"; }
360 };
361 
362 } // namespace STORAGE_CLIENT_NS
363 } // namespace storage
364 } // namespace cloud
365 } // namespace google
366 
367 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_OBJECT_METADATA_H