google::cloud::storage::ObjectReadStream Class Reference

Defines a std::basic_istream<char> to read from a GCS Object. More...

#include <google/cloud/storage/object_read_stream.h>

Public Member Functions
	ObjectReadStream ()
	Creates a stream not associated with any buffer. More...
	ObjectReadStream (std::unique_ptr< internal::ObjectReadStreambuf > buf)
	Creates a stream associated with the given streambuf. More...
	ObjectReadStream (ObjectReadStream &&rhs) noexcept
ObjectReadStream &	operator= (ObjectReadStream &&rhs) noexcept
void	swap (ObjectReadStream &rhs)
	ObjectReadStream (ObjectReadStream const &)=delete
ObjectReadStream &	operator= (ObjectReadStream const &)=delete
	~ObjectReadStream () override
	Closes the stream (if necessary). More...
bool	IsOpen () const
void	Close ()
	Terminate the download, possibly before completing it. More...
Status const &	status () const &
	Report any download errors. More...
std::string const &	received_hash () const
	The received CRC32C checksum and the MD5 hash values as reported by GCS. More...
std::string const &	computed_hash () const
	The locally computed checksum and hashes, as a string. More...
HeadersMap const &	headers () const
	The headers (if any) returned by the service. More...

Object metadata information.
When downloading an object a limited amount of information about the object's metadata is returned as part of the download. Some of this information is important for applications performing multiple downloads (maybe of different ranges) of the same object. Such applications may want to use the generation number to guarantee all the downloads are actually referencing the same object. One could do this by first querying the metadata before the first download, but this is less efficient as it requires one additional server round trip. Note that all these attributes are absl::optional<>, as the attributes may not be known (or exist) if there is an error during the download. If the attribute is needed for the application's correctness the application should fetch the object metadata when the attribute is not available.
absl::optional< std::int64_t > const &	generation () const
	The object's generation at the time of the download, if known. More...
absl::optional< std::int64_t > const &	metageneration () const
	The object's metageneration at the time of the download, if known. More...
absl::optional< std::string > const &	storage_class () const
	The object's storage class at the time of the download, if known. More...
absl::optional< std::uint64_t > const &	size () const
	The object's size at the time of the download, if known. More...

Detailed Description

Defines a std::basic_istream<char> to read from a GCS Object.

Definition at line 33 of file object_read_stream.h.

Constructor & Destructor Documentation

ObjectReadStream() [1/4]

google::cloud::storage::ObjectReadStream::ObjectReadStream

(

)

Creates a stream not associated with any buffer.

Attempts to use this stream will result in failures.

ObjectReadStream() [2/4]

google::cloud::storage::ObjectReadStream::ObjectReadStream ( std::unique_ptr< internal::ObjectReadStreambuf >  buf )

inlineexplicit

Creates a stream associated with the given streambuf.

Definition at line 45 of file object_read_stream.h.

ObjectReadStream() [3/4]

google::cloud::storage::ObjectReadStream::ObjectReadStream ( ObjectReadStream &&  rhs )

noexcept

ObjectReadStream() [4/4]

google::cloud::storage::ObjectReadStream::ObjectReadStream ( ObjectReadStream const &  )

delete

~ObjectReadStream()

google::cloud::storage::ObjectReadStream::~ObjectReadStream ( )

override

Closes the stream (if necessary).

Member Function Documentation

Close()

void google::cloud::storage::ObjectReadStream::Close

(

)

Terminate the download, possibly before completing it.

computed_hash()

std::string const& google::cloud::storage::ObjectReadStream::computed_hash ( ) const

inline

The locally computed checksum and hashes, as a string.

This object computes the CRC32C checksum and MD5 hash of the downloaded data. Note that there are several cases where these values may be empty or irrelevant, for example:

• When reading only a portion of a blob the hash of that portion is irrelevant, note that GCS only reports the hashes for the full blob.
• The application may disable the CRC32C and/or the MD5 hash computation.

The string has the same format as the value returned by received_hash(). Note that the format of this string is also subject to change without notice.

See also

https://cloud.google.com/storage/docs/hashes-etags for more information on checksums and hashes in GCS.

Definition at line 121 of file object_read_stream.h.

generation()

absl::optional<std::int64_t> const& google::cloud::storage::ObjectReadStream::generation ( ) const

inline

The object's generation at the time of the download, if known.

Definition at line 156 of file object_read_stream.h.

headers()

HeadersMap const& google::cloud::storage::ObjectReadStream::headers ( ) const

inline

The headers (if any) returned by the service.

For debugging only.

Warning

The contents of these headers may change without notice. Unless documented in the API, headers may be removed or added by the service. Also note that the client library uses both the XML and JSON API, choosing between them based on the feature set (some functionality is only available through the JSON API), and performance. Consequently, the headers may be different on requests using different features. Likewise, the headers may change from one version of the library to the next, as we find more (or different) opportunities for optimization.

Definition at line 135 of file object_read_stream.h.

IsOpen()

bool google::cloud::storage::ObjectReadStream::IsOpen ( ) const

inline

Definition at line 72 of file object_read_stream.h.

metageneration()

absl::optional<std::int64_t> const& google::cloud::storage::ObjectReadStream::metageneration ( ) const

inline

The object's metageneration at the time of the download, if known.

Definition at line 161 of file object_read_stream.h.

operator=() [1/2]

ObjectReadStream& google::cloud::storage::ObjectReadStream::operator= ( ObjectReadStream &&  rhs )

inlinenoexcept

Definition at line 53 of file object_read_stream.h.

operator=() [2/2]

ObjectReadStream& google::cloud::storage::ObjectReadStream::operator= ( ObjectReadStream const &  )

delete

received_hash()

std::string const& google::cloud::storage::ObjectReadStream::received_hash ( ) const

inline

The received CRC32C checksum and the MD5 hash values as reported by GCS.

When the download is finalized (via Close() or the end of file) the GCS server reports the CRC32C checksum and, except for composite objects, the MD5 hash of the data. This class compares the locally computed and received hashes so applications can detect data download errors.

The values are reported as comma separated tag=value pairs, e.g. crc32c=AAAAAA==,md5=1B2M2Y8AsgTpgAmY7PhCfg==. The format of this string is subject to change without notice, they are provided for informational purposes only.

See also

https://cloud.google.com/storage/docs/hashes-etags for more information on checksums and hashes in GCS.

Definition at line 102 of file object_read_stream.h.

size()

absl::optional<std::uint64_t> const& google::cloud::storage::ObjectReadStream::size ( ) const

inline

The object's size at the time of the download, if known.

If you are using object transcoding this represents the stored size of the object, the number of downloaded bytes (after decompression) may be larger.

Definition at line 179 of file object_read_stream.h.

status()

Status const& google::cloud::storage::ObjectReadStream::status ( ) const &

inline

Report any download errors.

Note that errors may go undetected until the download completes.

Definition at line 84 of file object_read_stream.h.

storage_class()

absl::optional<std::string> const& google::cloud::storage::ObjectReadStream::storage_class ( ) const

inline

The object's storage class at the time of the download, if known.

Definition at line 166 of file object_read_stream.h.

swap()

void google::cloud::storage::ObjectReadStream::swap ( ObjectReadStream &  rhs )

inline

Definition at line 59 of file object_read_stream.h.