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.

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.

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.

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.

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. Furthermore, the headers may change from one version of the library to the next, as we find more (or different) opportunities for optimization.

IsOpen()

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

inline

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.

operator=() [1/2]

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

inlinenoexcept

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.

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.

status()

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

inline

Report any download errors.

Note that errors may go undetected until the download completes.

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.

swap()

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

inline