Google Cloud Storage C++ Client  1.32.1
A C++ Client Library for Google Cloud Storage
object_read_stream.h
Go to the documentation of this file.
1 // Copyright 2021 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_READ_STREAM_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_OBJECT_READ_STREAM_H
17 
18 #include "google/cloud/storage/internal/object_read_streambuf.h"
19 #include "google/cloud/storage/version.h"
20 #include <istream>
21 #include <map>
22 #include <memory>
23 #include <string>
24 
25 namespace google {
26 namespace cloud {
27 namespace storage {
28 inline namespace STORAGE_CLIENT_NS {
29 
30 /// Represents the headers returned in a streaming upload or download operation.
31 using HeadersMap = std::multimap<std::string, std::string>;
32 
33 /**
34  * Defines a `std::basic_istream<char>` to read from a GCS Object.
35  */
36 class ObjectReadStream : public std::basic_istream<char> {
37  public:
38  /**
39  * Creates a stream not associated with any buffer.
40  *
41  * Attempts to use this stream will result in failures.
42  */
44 
45  /**
46  * Creates a stream associated with the given `streambuf`.
47  */
48  explicit ObjectReadStream(std::unique_ptr<internal::ObjectReadStreambuf> buf)
49  : std::basic_istream<char>(nullptr), buf_(std::move(buf)) {
50  // Initialize the basic_ios<> class
51  init(buf_.get());
52  }
53 
54  ObjectReadStream(ObjectReadStream&& rhs) noexcept;
55 
57  ObjectReadStream tmp(std::move(rhs));
58  swap(tmp);
59  return *this;
60  }
61 
62  void swap(ObjectReadStream& rhs) {
63  std::basic_istream<char>::swap(rhs);
64  std::swap(buf_, rhs.buf_);
65  rhs.set_rdbuf(rhs.buf_.get());
66  set_rdbuf(buf_.get());
67  }
68 
71 
72  /// Closes the stream (if necessary).
73  ~ObjectReadStream() override;
74 
75  bool IsOpen() const { return static_cast<bool>(buf_) && buf_->IsOpen(); }
76 
77  /**
78  * Terminate the download, possibly before completing it.
79  */
80  void Close();
81 
82  //@{
83  /**
84  * Report any download errors.
85  *
86  * Note that errors may go undetected until the download completes.
87  */
88  Status const& status() const& { return buf_->status(); }
89 
90  /**
91  * The received CRC32C checksum and the MD5 hash values as reported by GCS.
92  *
93  * When the download is finalized (via `Close()` or the end of file) the GCS
94  * server reports the CRC32C checksum and, except for composite objects, the
95  * MD5 hash of the data. This class compares the locally computed and received
96  * hashes so applications can detect data download errors.
97  *
98  * The values are reported as comma separated `tag=value` pairs, e.g.
99  * `crc32c=AAAAAA==,md5=1B2M2Y8AsgTpgAmY7PhCfg==`. The format of this string
100  * is subject to change without notice, they are provided for informational
101  * purposes only.
102  *
103  * @see https://cloud.google.com/storage/docs/hashes-etags for more
104  * information on checksums and hashes in GCS.
105  */
106  std::string const& received_hash() const { return buf_->received_hash(); }
107 
108  /**
109  * The locally computed checksum and hashes, as a string.
110  *
111  * This object computes the CRC32C checksum and MD5 hash of the downloaded
112  * data. Note that there are several cases where these values may be empty or
113  * irrelevant, for example:
114  * - When reading only a portion of a blob the hash of that portion is
115  * irrelevant, note that GCS only reports the hashes for the full blob.
116  * - The application may disable the CRC32C and/or the MD5 hash computation.
117  *
118  * The string has the same format as the value returned by `received_hash()`.
119  * Note that the format of this string is also subject to change without
120  * notice.
121  *
122  * @see https://cloud.google.com/storage/docs/hashes-etags for more
123  * information on checksums and hashes in GCS.
124  */
125  std::string const& computed_hash() const { return buf_->computed_hash(); }
126 
127  /**
128  * The headers (if any) returned by the service. For debugging only.
129  *
130  * @warning The contents of these headers may change without notice. Unless
131  * documented in the API, headers may be removed or added by the service.
132  * Also note that the client library uses both the XML and JSON API,
133  * choosing between them based on the feature set (some functionality is
134  * only available through the JSON API), and performance. Consequently,
135  * the headers may be different on requests using different features.
136  * Likewise, the headers may change from one version of the library to the
137  * next, as we find more (or different) opportunities for optimization.
138  */
139  HeadersMap const& headers() const { return buf_->headers(); }
140  //@}
141 
142  private:
143  std::unique_ptr<internal::ObjectReadStreambuf> buf_;
144 };
145 
146 } // namespace STORAGE_CLIENT_NS
147 } // namespace storage
148 } // namespace cloud
149 } // namespace google
150 
151 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_OBJECT_READ_STREAM_H