Class ObjectReadStream (2.17.0)

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

Constructors

ObjectReadStream()

Creates a stream not associated with any buffer.

Attempts to use this stream will result in failures.

ObjectReadStream(std::unique_ptr< internal::ObjectReadStreambuf >)

Creates a stream associated with the given streambuf.

Parameter
Name Description
buf std::unique_ptr< internal::ObjectReadStreambuf >

ObjectReadStream(ObjectReadStream &&)

Parameter
Name Description
rhs ObjectReadStream &&

ObjectReadStream(ObjectReadStream const &)

Parameter
Name Description
ObjectReadStream const &

Operators

operator=(ObjectReadStream &&)

Parameter
Name Description
rhs ObjectReadStream &&
Returns
Type Description
ObjectReadStream &

operator=(ObjectReadStream const &)

Parameter
Name Description
ObjectReadStream const &
Returns
Type Description
ObjectReadStream &

Functions

generation() const

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

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.

Returns
Type Description
absl::optional< std::int64_t > const &

metageneration() const

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

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.

Returns
Type Description
absl::optional< std::int64_t > const &

storage_class() const

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

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.

Returns
Type Description
absl::optional< std::string > const &

size() const

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.

Returns
Type Description
absl::optional< std::uint64_t > const &

swap(ObjectReadStream &)

Parameter
Name Description
rhs ObjectReadStream &
Returns
Type Description
void

IsOpen() const

Returns
Type Description
bool

Close()

Terminate the download, possibly before completing it.

Returns
Type Description
void

status() const &

Report any download errors.

Note that errors may go undetected until the download completes.

Returns
Type Description
Status const &

received_hash() const

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.

Returns
Type Description
std::string const &

computed_hash() const

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.

Returns
Type Description
std::string const &

headers() const

The headers (if any) returned by the service.

For debugging only.

Returns
Type Description
HeadersMap const &