firebase::storage::StorageReference

#include <storage_reference.h>

Represents a reference to a CloudStorage 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(constStorageReference & 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 thisStorageReference.
GetBytesLastResult()
Future< size_t >
Returns the result of the most recent call toGetBytes();.
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 toGetDownloadUrl();.
GetFile(const char *path,Listener *listener,Controller *controller_out)
Future< size_t >
Asynchronously downloads the object from thisStorageReference.
GetFileLastResult()
Future< size_t >
Returns the result of the most recent call toGetFile();.
GetMetadata()
Retrieves metadata associated with an object at thisStorageReference.
GetMetadataLastResult()
Returns the result of the most recent call toGetMetadata();.
GetParent()
Returns a new instance ofStorageReference 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 specifiedStorageReference, without additional metadata.
PutBytes(const void *buffer, size_t buffer_size, constMetadata & metadata,Listener *listener,Controller *controller_out)
Asynchronously uploads data to the currently specifiedStorageReference, without additional metadata.
PutBytesLastResult()
Returns the result of the most recent call toPutBytes();.
PutFile(const char *path,Listener *listener,Controller *controller_out)
Asynchronously uploads data to the currently specifiedStorageReference, without additional metadata.
PutFile(const char *path, constMetadata & metadata,Listener *listener,Controller *controller_out)
Asynchronously uploads data to the currently specifiedStorageReference, without additional metadata.
PutFileLastResult()
Returns the result of the most recent call toPutFile();.
UpdateMetadata(constMetadata & metadata)
Updates the metadata associated with thisStorageReference.
UpdateMetadataLastResult()
Returns the result of the most recent call toUpdateMetadata();.
bucket()
std::string
Return the Google CloudStorage bucket that holds this object.
full_path()
std::string
Return the full path of the storage reference, not including the Google CloudStorage bucket.
is_valid() const
bool
Returns true if thisStorageReference is valid, false if it is not valid.
name()
std::string
Returns the short name of this object.
operator=(constStorageReference & reference)
Copy assignment operator.
operator=(StorageReference && other)
Move assignment operator.
storage()
Gets thefirebase::storage::Storage instance to which we refer.

Public functions

Child

StorageReferenceChild(constchar*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

StorageReferenceChild(conststd::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
AFuture result, which will complete when the operation either succeeds or fails. When theFuture 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_tbuffer_size,Listener*listener,Controller*controller_out)

Asynchronously downloads the object from thisStorageReference.

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 aController 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 toGetBytes();.

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

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
AFuture result, which will complete when the operation either succeeds or fails. When theFuture 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 toGetDownloadUrl();.

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

GetFile

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

Asynchronously downloads the object from thisStorageReference.

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 aController 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 toGetFile();.

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

GetMetadata

Future<Metadata>GetMetadata()

Retrieves metadata associated with an object at thisStorageReference.

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

GetMetadataLastResult

Future<Metadata>GetMetadataLastResult()

Returns the result of the most recent call toGetMetadata();.

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

GetParent

StorageReferenceGetParent()

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

Details
Returns
The parentStorageReference.

PutBytes

Future<Metadata>PutBytes(constvoid*buffer,size_tbuffer_size,Listener*listener,Controller*controller_out)

Asynchronously uploads data to the currently specifiedStorageReference, 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 aController here that you can use to control the write operation.
Returns
A future that returns theMetadata.

PutBytes

Future<Metadata>PutBytes(constvoid*buffer,size_tbuffer_size,constMetadata&metadata,Listener*listener,Controller*controller_out)

Asynchronously uploads data to the currently specifiedStorageReference, 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 aController here that you can use to control the write operation.
Returns
A future that returns theMetadata.

PutBytesLastResult

Future<Metadata>PutBytesLastResult()

Returns the result of the most recent call toPutBytes();.

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

PutFile

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

Asynchronously uploads data to the currently specifiedStorageReference, without additional metadata.

Details
Parameters
path
Path to local file on device to upload to FirebaseStorage.
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 aController here that you can use to control the write operation.
Returns
A future that returns theMetadata.

PutFile

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

Asynchronously uploads data to the currently specifiedStorageReference, without additional metadata.

Details
Parameters
path
Path to local file on device to upload to FirebaseStorage.
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 aController here that you can use to control the write operation.
Returns
A future that returns theMetadata.

PutFileLastResult

Future<Metadata>PutFileLastResult()

Returns the result of the most recent call toPutFile();.

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

StorageReference

StorageReference()

Default constructor.

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

StorageReference

StorageReference(constStorageReference&reference)

Copy constructor.

It's totally okay (and efficient) to copyStorageReference 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 forStorageReference instances.

Details
Parameters
other
StorageReference to move data from.

UpdateMetadata

Future<Metadata>UpdateMetadata(constMetadata&metadata)

Updates the metadata associated with thisStorageReference.

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

UpdateMetadataLastResult

Future<Metadata>UpdateMetadataLastResult()

Returns the result of the most recent call toUpdateMetadata();.

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

bucket

std::stringbucket()

Return the Google CloudStorage bucket that holds this object.

Details
Returns
The bucket.

full_path

std::stringfull_path()

Return the full path of the storage reference, not including the Google CloudStorage 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

boolis_valid()const

Returns true if thisStorageReference is valid, false if it is not valid.

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

Details
Returns
true if thisStorageReference is valid, false if thisStorageReference is invalid.

name

std::stringname()

Returns the short name of this object.

Details
Returns
the short name of this object.

operator=

StorageReference&operator=(constStorageReference&reference)

Copy assignment operator.

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

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

operator=

StorageReference&operator=(StorageReference&&other)

Move assignment operator.

Moving is an efficient operation forStorageReference instances.

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

storage

Storage*storage()

Gets thefirebase::storage::Storage instance to which we refer.

The pointer will remain valid indefinitely.

Details
Returns
Thefirebase::storage::Storage instance that thisStorageReference refers to.

~StorageReference

~StorageReference()

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2024-01-23 UTC.