firebase::storage::StorageReference

#include <storage_reference.h>

Represents a reference to a Cloud Storage object.

Summary

Developers can upload and download objects, get/set object metadata, and delete an object at a specified path.

Constructors and Destructors
StorageReference()
Default constructor.
StorageReference(const StorageReference & reference)
Copy constructor.
StorageReference(StorageReference && other)
Move constructor.
~StorageReference()

Public functions
Child(const char *path) const
Gets a reference to a location relative to this one.
Child(const std::string & path) const
Gets a reference to a location relative to this one.
Delete()
Future< void >
Deletes the object at the current path.
DeleteLastResult()
Future< void >
Returns the result of the most recent call to RemoveValue();.
GetBytes(void *buffer, size_t buffer_size, Listener *listener, Controller *controller_out)
Future< size_t >
Asynchronously downloads the object from this StorageReference.
GetBytesLastResult()
Future< size_t >
Returns the result of the most recent call to GetBytes();.
GetDownloadUrl()
Future< std::string >
Asynchronously retrieves a long lived download URL with a revokable token.
GetDownloadUrlLastResult()
Future< std::string >
Returns the result of the most recent call to GetDownloadUrl();.
GetFile(const char *path, Listener *listener, Controller *controller_out)
Future< size_t >
Asynchronously downloads the object from this StorageReference.
GetFileLastResult()
Future< size_t >
Returns the result of the most recent call to GetFile();.
GetMetadata()
Retrieves metadata associated with an object at this StorageReference.
GetMetadataLastResult()
Returns the result of the most recent call to GetMetadata();.
GetParent()
Returns a new instance of StorageReference pointing to the parent location or null if this instance references the root location.
PutBytes(const void *buffer, size_t buffer_size, Listener *listener, Controller *controller_out)
Asynchronously uploads data to the currently specified StorageReference, without additional metadata.
PutBytes(const void *buffer, size_t buffer_size, const Metadata & metadata, Listener *listener, Controller *controller_out)
Asynchronously uploads data to the currently specified StorageReference, without additional metadata.
PutBytesLastResult()
Returns the result of the most recent call to PutBytes();.
PutFile(const char *path, Listener *listener, Controller *controller_out)
Asynchronously uploads data to the currently specified StorageReference, without additional metadata.
PutFile(const char *path, const Metadata & metadata, Listener *listener, Controller *controller_out)
Asynchronously uploads data to the currently specified StorageReference, without additional metadata.
PutFileLastResult()
Returns the result of the most recent call to PutFile();.
UpdateMetadata(const Metadata & metadata)
Updates the metadata associated with this StorageReference.
UpdateMetadataLastResult()
Returns the result of the most recent call to UpdateMetadata();.
bucket()
std::string
Return the Google Cloud Storage bucket that holds this object.
full_path()
std::string
Return the full path of the storage reference, not including the Google Cloud Storage bucket.
is_valid() const
bool
Returns true if this StorageReference is valid, false if it is not valid.
name()
std::string
Returns the short name of this object.
operator=(const StorageReference & reference)
Copy assignment operator.
operator=(StorageReference && other)
Move assignment operator.
storage()
Gets the firebase::storage::Storage instance to which we refer.

Public functions

Child

StorageReference Child(
  const char *path
) const

Gets a reference to a location relative to this one.

Details
Parameters
path
Path relative to this reference's location. The pointer only needs to be valid during this call.
Returns
Child relative to this location.

Child

StorageReference Child(
  const std::string & path
) const

Gets a reference to a location relative to this one.

Details
Parameters
path
Path relative to this reference's location.
Returns
Child relative to this location.

Delete

Future< void > Delete()

Deletes the object at the current path.

Details
Returns
A Future result, which will complete when the operation either succeeds or fails. When the Future is completed, if its Error is kErrorNone, the operation succeeded.

DeleteLastResult

Future< void > DeleteLastResult()

Returns the result of the most recent call to RemoveValue();.

Details
Returns
The result of the most recent call to RemoveValue();

GetBytes

Future< size_t > GetBytes(
  void *buffer,
  size_t buffer_size,
  Listener *listener,
  Controller *controller_out
)

Asynchronously downloads the object from this StorageReference.

A byte array will be allocated large enough to hold the entire file in memory. Therefore, using this method will impact memory usage of your process.

Details
Parameters
buffer
A byte buffer to read the data into. This buffer must be valid for the duration of the transfer.
buffer_size
The size of the byte buffer.
listener
A listener that will respond to events on this read operation. If not nullptr, a listener that will respond to events on this read operation. The caller is responsible for allocating and deallocating the listener. The same listener can be used for multiple operations.
controller_out
Controls the write operation, providing the ability to pause, resume or cancel an ongoing write operation. If not nullptr, this method will output a Controller here that you can use to control the write operation.
Returns
A future that returns the number of bytes read.

GetBytesLastResult

Future< size_t > GetBytesLastResult()

Returns the result of the most recent call to GetBytes();.

Details
Returns
The result of the most recent call to GetBytes();

GetDownloadUrl

Future< std::string > GetDownloadUrl()

Asynchronously retrieves a long lived download URL with a revokable token.

This can be used to share the file with others, but can be revoked by a developer in the Firebase Console if desired.

Details
Returns
A Future result, which will complete when the operation either succeeds or fails. When the Future is completed, if its Error is kErrorNone, the operation succeeded and the URL is returned.

GetDownloadUrlLastResult

Future< std::string > GetDownloadUrlLastResult()

Returns the result of the most recent call to GetDownloadUrl();.

Details
Returns
The result of the most recent call to GetDownloadUrl();

GetFile

Future< size_t > GetFile(
  const char *path,
  Listener *listener,
  Controller *controller_out
)

Asynchronously downloads the object from this StorageReference.

A byte array will be allocated large enough to hold the entire file in memory. Therefore, using this method will impact memory usage of your process.

Details
Parameters
path
Path to local file on device to download into.
listener
A listener that will respond to events on this read operation. If not nullptr, a listener that will respond to events on this read operation. The caller is responsible for allocating and deallocating the listener. The same listener can be used for multiple operations.
controller_out
Controls the write operation, providing the ability to pause, resume or cancel an ongoing write operation. If not nullptr, this method will output a Controller here that you can use to control the write operation.
Returns
A future that returns the number of bytes read.

GetFileLastResult

Future< size_t > GetFileLastResult()

Returns the result of the most recent call to GetFile();.

Details
Returns
The result of the most recent call to GetFile();

GetMetadata

Future< Metadata > GetMetadata()

Retrieves metadata associated with an object at this StorageReference.

Details
Returns
A Future result, which will complete when the operation either succeeds or fails. When the Future is completed, if its Error is kErrorNone, the operation succeeded and the Metadata is returned.

GetMetadataLastResult

Future< Metadata > GetMetadataLastResult()

Returns the result of the most recent call to GetMetadata();.

Details
Returns
The result of the most recent call to GetMetadata();

GetParent

StorageReference GetParent()

Returns a new instance of StorageReference pointing to the parent location or null if this instance references the root location.

Details
Returns
The parent StorageReference.

PutBytes

Future< Metadata > PutBytes(
  const void *buffer,
  size_t buffer_size,
  Listener *listener,
  Controller *controller_out
)

Asynchronously uploads data to the currently specified StorageReference, without additional metadata.

Details
Parameters
buffer
A byte buffer to write data from. This buffer must be valid for the duration of the transfer.
buffer_size
The size of the byte buffer.
listener
A listener that will respond to events on this read operation. If not nullptr, a listener that will respond to events on this write operation. The caller is responsible for allocating and deallocating the listener. The same listener can be used for multiple operations.
controller_out
Controls the write operation, providing the ability to pause, resume or cancel an ongoing write operation. If not nullptr, this method will output a Controller here that you can use to control the write operation.
Returns
A future that returns the Metadata.

PutBytes

Future< Metadata > PutBytes(
  const void *buffer,
  size_t buffer_size,
  const Metadata & metadata,
  Listener *listener,
  Controller *controller_out
)

Asynchronously uploads data to the currently specified StorageReference, without additional metadata.

Details
Parameters
buffer
A byte buffer to write data from. This buffer must be valid for the duration of the transfer.
buffer_size
The number of bytes to write.
metadata
Metadata containing additional information (MIME type, etc.) about the object being uploaded.
listener
A listener that will respond to events on this read operation. If not nullptr, a listener that will respond to events on this write operation. The caller is responsible for allocating and deallocating the listener. The same listener can be used for multiple operations.
controller_out
Controls the write operation, providing the ability to pause, resume or cancel an ongoing write operation. If not nullptr, this method will output a Controller here that you can use to control the write operation.
Returns
A future that returns the Metadata.

PutBytesLastResult

Future< Metadata > PutBytesLastResult()

Returns the result of the most recent call to PutBytes();.

Details
Returns
The result of the most recent call to PutBytes();

PutFile

Future< Metadata > PutFile(
  const char *path,
  Listener *listener,
  Controller *controller_out
)

Asynchronously uploads data to the currently specified StorageReference, without additional metadata.

Details
Parameters
path
Path to local file on device to upload to Firebase Storage.
listener
A listener that will respond to events on this read operation. If not nullptr, a listener that will respond to events on this write operation. The caller is responsible for allocating and deallocating the listener. The same listener can be used for multiple operations.
controller_out
Controls the write operation, providing the ability to pause, resume or cancel an ongoing write operation. If not nullptr, this method will output a Controller here that you can use to control the write operation.
Returns
A future that returns the Metadata.

PutFile

Future< Metadata > PutFile(
  const char *path,
  const Metadata & metadata,
  Listener *listener,
  Controller *controller_out
)

Asynchronously uploads data to the currently specified StorageReference, without additional metadata.

Details
Parameters
path
Path to local file on device to upload to Firebase Storage.
metadata
Metadata containing additional information (MIME type, etc.) about the object being uploaded.
listener
A listener that will respond to events on this read operation. If not nullptr, a listener that will respond to events on this write operation. The caller is responsible for allocating and deallocating the listener. The same listener can be used for multiple operations.
controller_out
Controls the write operation, providing the ability to pause, resume or cancel an ongoing write operation. If not nullptr, this method will output a Controller here that you can use to control the write operation.
Returns
A future that returns the Metadata.

PutFileLastResult

Future< Metadata > PutFileLastResult()

Returns the result of the most recent call to PutFile();.

Details
Returns
The result of the most recent call to PutFile();

StorageReference

 StorageReference()

Default constructor.

This creates an invalid StorageReference. Attempting to perform any operations on this reference will fail unless a valid StorageReference has been assigned to it.

StorageReference

 StorageReference(
  const StorageReference & reference
)

Copy constructor.

It's totally okay (and efficient) to copy StorageReference instances, as they simply point to the same location.

Details
Parameters
reference
StorageReference to copy from.

StorageReference

 StorageReference(
  StorageReference && other
)

Move constructor.

Moving is an efficient operation for StorageReference instances.

Details
Parameters
other
StorageReference to move data from.

UpdateMetadata

Future< Metadata > UpdateMetadata(
  const Metadata & metadata
)

Updates the metadata associated with this StorageReference.

Details
Returns
A Future result, which will complete when the operation either succeeds or fails. When the Future is completed, if its Error is kErrorNone, the operation succeeded and the Metadata is returned.

UpdateMetadataLastResult

Future< Metadata > UpdateMetadataLastResult()

Returns the result of the most recent call to UpdateMetadata();.

Details
Returns
The result of the most recent call to UpdateMetadata();

bucket

std::string bucket()

Return the Google Cloud Storage bucket that holds this object.

Details
Returns
The bucket.

full_path

std::string full_path()

Return the full path of the storage reference, not including the Google Cloud Storage bucket.

Details
Returns
Full path to the storage reference, not including GCS bucket. For example, for the reference "gs://bucket/path/to/object.txt", the full path would be "path/to/object.txt".

is_valid

bool is_valid() const

Returns true if this StorageReference is valid, false if it is not valid.

An invalid StorageReference indicates that the reference is uninitialized (created with the default constructor) or that there was an error retrieving the reference.

Details
Returns
true if this StorageReference is valid, false if this StorageReference is invalid.

name

std::string name()

Returns the short name of this object.

Details
Returns
the short name of this object.

operator=

StorageReference & operator=(
  const StorageReference & reference
)

Copy assignment operator.

It's totally okay (and efficient) to copy StorageReference instances, as they simply point to the same location.

Details
Parameters
reference
StorageReference to copy from.
Returns
Reference to the destination StorageReference.

operator=

StorageReference & operator=(
  StorageReference && other
)

Move assignment operator.

Moving is an efficient operation for StorageReference instances.

Details
Parameters
other
StorageReference to move data from.
Returns
Reference to the destination StorageReference.

storage

Storage * storage()

Gets the firebase::storage::Storage instance to which we refer.

The pointer will remain valid indefinitely.

Details
Returns
The firebase::storage::Storage instance that this StorageReference refers to.

~StorageReference

 ~StorageReference()