Google Cloud Storage C++ Client  1.25.0
A C++ Client Library for Google Cloud Storage
Public Member Functions | List of all members
google::cloud::storage::v1::ObjectWriteStream Class Reference

Defines a std::basic_ostream<char> to write to a GCS Object. More...

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

Public Member Functions

 ObjectWriteStream ()
 Creates a stream not associated with any buffer. More...
 
 ObjectWriteStream (std::unique_ptr< internal::ObjectWriteStreambuf > buf)
 Creates a stream associated with the give request. More...
 
 ObjectWriteStream (ObjectWriteStream &&rhs) noexcept
 
ObjectWriteStreamoperator= (ObjectWriteStream &&rhs) noexcept
 
 ObjectWriteStream (ObjectWriteStream const &)=delete
 
ObjectWriteStreamoperator= (ObjectWriteStream const &)=delete
 
 ~ObjectWriteStream () override
 Closes the stream (if necessary). More...
 
bool IsOpen () const
 Return true if the stream is open to write more data. More...
 
void Close ()
 Close the stream, finalizing the upload. More...
 
StatusOr< ObjectMetadata > const & metadata () const &
 Access the upload results. More...
 
StatusOr< ObjectMetadata > && metadata () &&
 
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...
 
std::multimap< std::string, std::string > const & headers () const
 The headers returned by the service, for debugging only. More...
 
std::string const & payload () const
 The returned payload as a raw string, for debugging only. More...
 
std::string const & resumable_session_id () const
 Returns the resumable upload session id for this upload. More...
 
std::uint64_t next_expected_byte () const
 Returns the next expected byte. More...
 
void Suspend () &&
 Suspends an upload. More...
 
Status last_status () const
 Returns the status of partial errors. More...
 

Detailed Description

Defines a std::basic_ostream<char> to write to a GCS Object.

Definition at line 164 of file object_stream.h.

Constructor & Destructor Documentation

◆ ObjectWriteStream() [1/4]

google::cloud::storage::v1::ObjectWriteStream::ObjectWriteStream ( )
inline

Creates a stream not associated with any buffer.

Attempts to use this stream will result in failures.

Definition at line 171 of file object_stream.h.

◆ ObjectWriteStream() [2/4]

google::cloud::storage::v1::ObjectWriteStream::ObjectWriteStream ( std::unique_ptr< internal::ObjectWriteStreambuf >  buf)
explicit

Creates a stream associated with the give request.

Reading from the stream will result in http requests to get more data from the GCS object.

Parameters
bufan initialized ObjectWriteStreambuf to upload the data.

Definition at line 58 of file object_stream.cc.

◆ ObjectWriteStream() [3/4]

google::cloud::storage::v1::ObjectWriteStream::ObjectWriteStream ( ObjectWriteStream &&  rhs)
inlinenoexcept

Definition at line 184 of file object_stream.h.

◆ ObjectWriteStream() [4/4]

google::cloud::storage::v1::ObjectWriteStream::ObjectWriteStream ( ObjectWriteStream const &  )
delete

◆ ~ObjectWriteStream()

google::cloud::storage::v1::ObjectWriteStream::~ObjectWriteStream ( )
override

Closes the stream (if necessary).

Definition at line 69 of file object_stream.cc.

Member Function Documentation

◆ Close()

void google::cloud::storage::v1::ObjectWriteStream::Close ( )

Close the stream, finalizing the upload.

Closing a stream completes an upload and creates the uploaded object. On failure it sets the badbit of the stream.

The metadata of the uploaded object, or a detailed error status, is accessible via the metadata() member function. Note that the metadata may be empty if the application creates a stream with the Fields("") parameter, applications cannot assume that all fields in the metadata are filled on success.

Exceptions
Ifthe application has enabled the exception mask this function may throw std::ios_base::failure.

Definition at line 79 of file object_stream.cc.

◆ computed_hash()

std::string const& google::cloud::storage::v1::ObjectWriteStream::computed_hash ( ) const
inline

The locally computed checksum and hashes, as a string.

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

  • When performing resumable uploads the stream may not have had access to the full data.
  • 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 301 of file object_stream.h.

◆ headers()

std::multimap<std::string, std::string> const& google::cloud::storage::v1::ObjectWriteStream::headers ( ) const
inline

The headers returned by the service, for debugging only.

Definition at line 304 of file object_stream.h.

◆ IsOpen()

bool google::cloud::storage::v1::ObjectWriteStream::IsOpen ( ) const
inline

Return true if the stream is open to write more data.

Note
write streams can be "born closed" when created using a previously finalized upload session. Applications that restore a previous session should check the state, for example:
auto stream = client.WriteObject(...,
if (!stream.IsOpen() && stream.metadata().ok()) {
std::cout << "Yay! The upload was finalized previously.\n";
return;
}

Definition at line 237 of file object_stream.h.

◆ last_status()

Status google::cloud::storage::v1::ObjectWriteStream::last_status ( ) const
inline

Returns the status of partial errors.

Application may write multiple times before closing the stream, this function gives the capability to find out status even before stream closure.

This function is different than metadata() as calling metadata() before Close() is undefined.

Definition at line 356 of file object_stream.h.

◆ metadata() [1/2]

StatusOr<ObjectMetadata>&& google::cloud::storage::v1::ObjectWriteStream::metadata ( ) &&
inline

Definition at line 264 of file object_stream.h.

◆ metadata() [2/2]

StatusOr<ObjectMetadata> const& google::cloud::storage::v1::ObjectWriteStream::metadata ( ) const &
inline

Access the upload results.

Note that calling these member functions before Close() is undefined behavior.

Definition at line 263 of file object_stream.h.

◆ next_expected_byte()

std::uint64_t google::cloud::storage::v1::ObjectWriteStream::next_expected_byte ( ) const
inline

Returns the next expected byte.

For non-resumable uploads this is always zero. Applications that use resumable uploads can use this value to resend any data not committed in the GCS.

Definition at line 332 of file object_stream.h.

◆ operator=() [1/2]

ObjectWriteStream& google::cloud::storage::v1::ObjectWriteStream::operator= ( ObjectWriteStream &&  rhs)
inlinenoexcept

Definition at line 198 of file object_stream.h.

◆ operator=() [2/2]

ObjectWriteStream& google::cloud::storage::v1::ObjectWriteStream::operator= ( ObjectWriteStream const &  )
delete

◆ payload()

std::string const& google::cloud::storage::v1::ObjectWriteStream::payload ( ) const
inline

The returned payload as a raw string, for debugging only.

Definition at line 309 of file object_stream.h.

◆ received_hash()

std::string const& google::cloud::storage::v1::ObjectWriteStream::received_hash ( ) const
inline

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

When the upload is finalized (via Close()) the GCS server reports the CRC32C checksum and, if the object is not a composite object, the MDF hash of the uploaded data. This class compares the reported hashes against locally computed hash values, and reports an error if they do not match.

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 282 of file object_stream.h.

◆ resumable_session_id()

std::string const& google::cloud::storage::v1::ObjectWriteStream::resumable_session_id ( ) const
inline

Returns the resumable upload session id for this upload.

Note that this is an empty string for uploads that do not use resumable upload session ids. Client::WriteObject() enables resumable uploads based on the options set by the application.

Furthermore, this value might change during an upload.

Definition at line 321 of file object_stream.h.

◆ Suspend()

void google::cloud::storage::v1::ObjectWriteStream::Suspend ( ) &&

Suspends an upload.

This is a destructive operation. Using this object after calling this function results in undefined behavior. Applications should copy any necessary state (such as the value resumable_session_id()) before calling this function.

Definition at line 102 of file object_stream.cc.

google::cloud::storage::v1::Client::WriteObject
ObjectWriteStream WriteObject(std::string const &bucket_name, std::string const &object_name, Options &&... options)
Writes contents into an object.
Definition: client.h:1199
google::cloud::storage::v1::ObjectWriteStream::IsOpen
bool IsOpen() const
Return true if the stream is open to write more data.
Definition: object_stream.h:237
google::cloud::storage::v1::RestoreResumableUploadSession
UseResumableUploadSession RestoreResumableUploadSession(std::string session_id)
Create a UseResumableUploadSession option that restores previous sessions.
Definition: upload_options.h:48
google::cloud::storage::v1::ObjectWriteStream::metadata
StatusOr< ObjectMetadata > const & metadata() const &
Access the upload results.
Definition: object_stream.h:263