StorageReference

class StorageReference : Comparable


Represents a reference to a Google Cloud Storage object. Developers can upload and download objects, get/set object metadata, and delete an object at a specified path. (see Google Cloud Storage)

Summary

Public functions

StorageReference
child(pathString: String)

Returns a new instance of StorageReference pointing to a child location of the current reference.

Int
Task<Void!>

Deletes the object at this StorageReference.

Boolean
equals(other: Any!)
(Mutable)List<FileDownloadTask!>
(Mutable)List<UploadTask!>
String

Return the Google Cloud Storage bucket that holds this object.

Task<ByteArray<Byte>!>
getBytes(maxDownloadSizeBytes: Long)

Asynchronously downloads the object from this StorageReference A byte array will be allocated large enough to hold the entire file in memory.

Task<Uri!>

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

FileDownloadTask
getFile(destinationFile: File)

Asynchronously downloads the object at this StorageReference to a specified system filepath.

FileDownloadTask
getFile(destinationUri: Uri)

Asynchronously downloads the object at this StorageReference to a specified system filepath.

Task<StorageMetadata!>

Retrieves metadata associated with an object at this StorageReference.

String

Returns the short name of this object.

StorageReference?

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

String

Returns the full path to this object, not including the Google Cloud Storage bucket.

StorageReference

Returns a new instance of StorageReference pointing to the root location.

FirebaseStorage

Returns the FirebaseStorage service which created this reference.

StreamDownloadTask

Asynchronously downloads the object at this StorageReference via a InputStream.

StreamDownloadTask

Asynchronously downloads the object at this StorageReference via a InputStream.

Int
Task<ListResult!>
list(maxResults: Int)

List up to maxResults items (files) and prefixes (folders) under this StorageReference.

Task<ListResult!>
list(maxResults: Int, pageToken: String)

Resumes a previous call to list, starting after a pagination token.

Task<ListResult!>

List all items (files) and prefixes (folders) under this StorageReference.

UploadTask

Asynchronously uploads byte data to this StorageReference.

UploadTask
putBytes(bytes: ByteArray, metadata: StorageMetadata)

Asynchronously uploads byte data to this StorageReference.

UploadTask
putFile(uri: Uri)

Asynchronously uploads from a content URI to this StorageReference.

UploadTask
putFile(uri: Uri, metadata: StorageMetadata)

Asynchronously uploads from a content URI to this StorageReference.

UploadTask
putFile(uri: Uri, metadata: StorageMetadata?, existingUploadUri: Uri?)

Asynchronously uploads from a content URI to this StorageReference.

UploadTask

Asynchronously uploads a stream of data to this StorageReference.

UploadTask
putStream(stream: InputStream, metadata: StorageMetadata)

Asynchronously uploads a stream of data to this StorageReference.

String!
Task<StorageMetadata!>

Updates the metadata associated with this StorageReference.

Public functions

child

fun child(pathString: String): StorageReference

Returns a new instance of StorageReference pointing to a child location of the current reference. All leading and trailing slashes will be removed, and consecutive slashes will be compressed to single slashes. For example:

child = /foo/bar     path = foo/bar
child = foo/bar/     path = foo/bar
child = foo///bar    path = foo/bar
Parameters
pathString: String

The relative path from this reference.

Returns
StorageReference

the child StorageReference.

compareTo

fun compareTo(other: StorageReference): Int

delete

fun delete(): Task<Void!>

Deletes the object at this StorageReference.

Returns
Task<Void!>

A Task that indicates whether the operation succeeded or failed.

equals

fun equals(other: Any!): Boolean

getActiveDownloadTasks

fun getActiveDownloadTasks(): (Mutable)List<FileDownloadTask!>
Returns
(Mutable)List<FileDownloadTask!>

the set of active download tasks currently in progress or recently completed.

getActiveUploadTasks

fun getActiveUploadTasks(): (Mutable)List<UploadTask!>
Returns
(Mutable)List<UploadTask!>

the set of active upload tasks currently in progress or recently completed.

getBucket

fun getBucket(): String

Return the Google Cloud Storage bucket that holds this object.

Returns
String

the bucket.

getBytes

fun getBytes(maxDownloadSizeBytes: Long): Task<ByteArray<Byte>!>

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. If you are downloading many large files, getStream may be a better option.

Parameters
maxDownloadSizeBytes: Long

The maximum allowed size in bytes that will be allocated. Set this parameter to prevent out of memory conditions from occurring. If the download exceeds this limit, the task will fail and an IndexOutOfBoundsException will be returned.

Returns
Task<ByteArray<Byte>!>

The bytes downloaded.

getDownloadUrl

fun getDownloadUrl(): Task<Uri!>

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.

Returns
Task<Uri!>

The Uri representing the download URL. You can feed this URL into a URL and download the object via openStream.

getFile

fun getFile(destinationFile: File): FileDownloadTask

Asynchronously downloads the object at this StorageReference to a specified system filepath.

Parameters
destinationFile: File

A File representing the path the object should be downloaded to.

Returns
FileDownloadTask

A FileDownloadTask that can be used to monitor or manage the download.

getFile

fun getFile(destinationUri: Uri): FileDownloadTask

Asynchronously downloads the object at this StorageReference to a specified system filepath.

Parameters
destinationUri: Uri

A file system URI representing the path the object should be downloaded to.

Returns
FileDownloadTask

A FileDownloadTask that can be used to monitor or manage the download.

getMetadata

fun getMetadata(): Task<StorageMetadata!>

Retrieves metadata associated with an object at this StorageReference.

Returns
Task<StorageMetadata!>

the metadata.

getName

fun getName(): String

Returns the short name of this object.

Returns
String

the name.

getParent

fun getParent(): StorageReference?

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

path = foo/bar/baz   parent = foo/bar
path = foo           parent = (root)
path = (root)        parent = (null)
Returns
StorageReference?

the parent StorageReference.

getPath

fun getPath(): String

Returns the full path to this object, not including the Google Cloud Storage bucket.

Returns
String

the path.

getRoot

fun getRoot(): StorageReference

Returns a new instance of StorageReference pointing to the root location.

getStorage

fun getStorage(): FirebaseStorage

Returns the FirebaseStorage service which created this reference.

Returns
FirebaseStorage

The FirebaseStorage service.

getStream

fun getStream(): StreamDownloadTask

Asynchronously downloads the object at this StorageReference via a InputStream. The InputStream should be read on an OnSuccessListener registered to run on a background thread via addOnSuccessListener

Returns
StreamDownloadTask

A FileDownloadTask that can be used to monitor or manage the download.

getStream

fun getStream(processor: StreamDownloadTask.StreamProcessor): StreamDownloadTask

Asynchronously downloads the object at this StorageReference via a InputStream.

Parameters
processor: StreamDownloadTask.StreamProcessor

A StreamDownloadTask.StreamProcessor that is responsible for reading data from the InputStream. The StreamDownloadTask.StreamProcessor is called on a background thread and checked exceptions thrown from this object will be returned as a failure to the OnFailureListener registered on the StreamDownloadTask.

Returns
StreamDownloadTask

A FileDownloadTask that can be used to monitor or manage the download.

hashCode

fun hashCode(): Int

list

fun list(maxResults: Int): Task<ListResult!>

List up to maxResults items (files) and prefixes (folders) under this StorageReference.

"/" is treated as a path delimiter. Cloud Storage for Firebase does not support object paths that end with "/" or contain two consecutive "/"s. All invalid objects in Google Cloud Storage will be filtered.

list() is only available for projects using Firebase Rules Version 2.

Parameters
maxResults: Int

The maximum number of results to return in a single page. Must be greater than 0 and at most 1000.

Returns
Task<ListResult!>

A a Task that returns up to maxResults items and prefixes under the current StorageReference.

list

fun list(maxResults: Int, pageToken: String): Task<ListResult!>

Resumes a previous call to list, starting after a pagination token. Returns the next set of items (files) and prefixes (folders) under this StorageReference.

"/" is treated as a path delimiter. Cloud Storage for Firebase does not support object paths that end with "/" or contain two consecutive "/"s. All invalid objects in Google Cloud Storage will be filtered.

list() is only available for projects using Firebase Rules Version 2.

Parameters
maxResults: Int

The maximum number of results to return in a single page. Must be greater than 0 and at most 1000.

pageToken: String

A page token from a previous call to list.

Returns
Task<ListResult!>

A a Task that returns the next items and prefixes under the current StorageReference.

listAll

fun listAll(): Task<ListResult!>

List all items (files) and prefixes (folders) under this StorageReference.

This is a helper method for calling list() repeatedly until there are no more results. Consistency of the result is not guaranteed if objects are inserted or removed while this operation is executing.

listAll() is only available for projects using Firebase Rules Version 2.

Returns
Task<ListResult!>

A Task that returns all items and prefixes under the current StorageReference.

Throws
java.lang.OutOfMemoryError: java.lang.OutOfMemoryError

If there are too many items at this location.

putBytes

fun putBytes(bytes: ByteArray): UploadTask

Asynchronously uploads byte data to this StorageReference. This is not recommended for large files. Instead upload a file via putFile or an InputStream via putStream.

Parameters
bytes: ByteArray

The byte array to upload.

Returns
UploadTask

An instance of UploadTask which can be used to monitor and manage the upload.

putBytes

fun putBytes(bytes: ByteArray, metadata: StorageMetadata): UploadTask

Asynchronously uploads byte data to this StorageReference. This is not recommended for large files. Instead upload a file via putFile or a Stream via putStream.

Parameters
bytes: ByteArray

The byte[] to upload.

metadata: StorageMetadata

StorageMetadata containing additional information (MIME type, etc.) about the object being uploaded.

Returns
UploadTask

An instance of UploadTask which can be used to monitor and manage the upload.

putFile

fun putFile(uri: Uri): UploadTask

Asynchronously uploads from a content URI to this StorageReference.

Parameters
uri: Uri

The source of the upload. This can be a file:// scheme or any content URI. A content resolver will be used to load the data.

Returns
UploadTask

An instance of UploadTask which can be used to monitor or manage the upload.

putFile

fun putFile(uri: Uri, metadata: StorageMetadata): UploadTask

Asynchronously uploads from a content URI to this StorageReference.

Parameters
uri: Uri

The source of the upload. This can be a file:// scheme or any content URI. A content resolver will be used to load the data.

metadata: StorageMetadata

StorageMetadata containing additional information (MIME type, etc.) about the object being uploaded.

Returns
UploadTask

An instance of UploadTask which can be used to monitor or manage the upload.

putFile

fun putFile(uri: Uri, metadata: StorageMetadata?, existingUploadUri: Uri?): UploadTask

Asynchronously uploads from a content URI to this StorageReference.

Parameters
uri: Uri

The source of the upload. This can be a file:// scheme or any content URI. A content resolver will be used to load the data.

metadata: StorageMetadata?

StorageMetadata containing additional information (MIME type, etc.) about the object being uploaded.

existingUploadUri: Uri?

If set, an attempt is made to resume an existing upload session as defined by getUploadSessionUri.

Returns
UploadTask

An instance of UploadTask which can be used to monitor or manage the upload.

putStream

fun putStream(stream: InputStream): UploadTask

Asynchronously uploads a stream of data to this StorageReference. The stream will remain open at the end of the upload.

Parameters
stream: InputStream

The InputStream to upload.

Returns
UploadTask

An instance of UploadTask which can be used to monitor and manage the upload.

putStream

fun putStream(stream: InputStream, metadata: StorageMetadata): UploadTask

Asynchronously uploads a stream of data to this StorageReference. The stream will remain open at the end of the upload.

Parameters
stream: InputStream

The InputStream to upload.

metadata: StorageMetadata

StorageMetadata containing additional information (MIME type, etc.) about the object being uploaded.

Returns
UploadTask

An instance of UploadTask which can be used to monitor and manage the upload.

toString

fun toString(): String!
Returns
String!

This object in URI form, which can then be shared and passed into getReferenceFromUrl.

updateMetadata

fun updateMetadata(metadata: StorageMetadata): Task<StorageMetadata!>

Updates the metadata associated with this StorageReference.

Parameters
metadata: StorageMetadata

A StorageMetadata object with the metadata to update.

Returns
Task<StorageMetadata!>

a Task that will return the final StorageMetadata once the operation is complete.