FirebaseStorage Framework Reference

StorageReference

@available(iOS 13, tvOS 13, macOS 10.15, watchOS 7, *)
@objc(FIRStorageReference)
open class StorageReference : NSObject

StorageReference represents a reference to a Google Cloud Storage object. Developers can upload and download objects, as well as get/set object metadata, and delete an object at the path. See the Cloud docs for more details.

Public APIs

storage
The Storage service object which created this reference.
Declaration
Swift

@objc public let storage: Storage
bucket
The name of the Google Cloud Storage bucket associated with this reference. For example, in gs://bucket/path/to/object.txt, the bucket would be ‘bucket’.
Declaration
Swift

@objc public var bucket: String { get }
fullPath
The full path to this object, not including the Google Cloud Storage bucket. In gs://bucket/path/to/object.txt, the full path would be: path/to/object.txt.
Declaration
Swift

@objc public var fullPath: String { get }
name
The short name of the object associated with this reference.

In gs://bucket/path/to/object.txt, the name of the object would be object.txt.
Declaration
Swift

@objc public var name: String { get }
root()
Creates a new StorageReference pointing to the root object.
Declaration
Swift

@objc open func root() -> StorageReference
Return Value

A new StorageReference pointing to the root object.
parent()
Creates a new StorageReference pointing to the parent of the current reference or nil if this instance references the root location.
For example: path = foo/bar/baz parent = foo/bar path = foo parent = (root) path = (root) parent = nil
Declaration
Swift

@objc open func parent() -> StorageReference?
Return Value

A new StorageReference pointing to the parent of the current reference.


                    
                    
                    child(_:)

Creates a new StorageReference pointing to a child object of the current reference.

    path = foo      child = bar    newPath = foo/bar
    path = foo/bar  child = baz    ntask.impl.snapshotwPath = foo/bar/baz
All leading and trailing slashes will be removed, and consecutive slashes will be
compressed to single slashes. For example:
    child = /foo/bar     newPath = foo/bar
    child = foo/bar/     newPath = foo/bar
    child = foo///bar    newPath = foo/bar

Declaration

Swift

@objc(child:)
open func child(_ path: String) -> StorageReference

Parameters


                                path

The path to append to the current path.

Return Value

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

Uploads


                    
                    
                    putData(_:metadata:)

Asynchronously uploads data to the currently specified StorageReference, without additional metadata. This is not recommended for large files, and one should instead upload a file from disk.

Declaration

Swift

@discardableResult
@objc(putData:metadata:)
open func putData(_ uploadData: Data, metadata: StorageMetadata? = nil) -> StorageUploadTask

Parameters

`uploadData`	The data to upload.
`metadata`	`StorageMetadata` containing additional information (MIME type, etc.) about the object being uploaded.

Return Value

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

__putData(_:)
Asynchronously uploads data to the currently specified StorageReference. This is not recommended for large files, and one should instead upload a file from disk.
Declaration
Swift

@discardableResult @objc(putData:) open func __putData(_ uploadData: Data) -> StorageUploadTask
Return Value

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


                    
                    
                    putData(_:metadata:completion:)

Asynchronously uploads data to the currently specified StorageReference. This is not recommended for large files, and one should instead upload a file from disk.

Declaration

Swift

@discardableResult
@objc(putData:metadata:completion:)
open func putData(_ uploadData: Data,
                  metadata: StorageMetadata? = nil,
                  completion: ((_: StorageMetadata?, _: Error?) -> Void)?) -> StorageUploadTask

Parameters

`uploadData`	The data to upload.
`metadata`	`StorageMetadata` containing additional information (MIME type, etc.) about the object being uploaded.
`completion`	A closure that either returns the object metadata on success, or an error on failure.

Return Value

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


                    
                    
                    putFile(from:metadata:)

Asynchronously uploads a file to the currently specified StorageReference.

Declaration

Swift

@discardableResult
@objc(putFile:metadata:)
open func putFile(from fileURL: URL, metadata: StorageMetadata? = nil) -> StorageUploadTask

Parameters

`fileURL`	A URL representing the system file path of the object to be uploaded.
`metadata`	`StorageMetadata` containing additional information (MIME type, etc.) about the object being uploaded.

Return Value

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

__putFile(from:)
Asynchronously uploads a file to the currently specified StorageReference, without additional metadata. @param fileURL A URL representing the system file path of the object to be uploaded. @return An instance of StorageUploadTask, which can be used to monitor or manage the upload.
Declaration
Swift

@discardableResult @objc(putFile:) open func __putFile(from fileURL: URL) -> StorageUploadTask


                    
                    
                    putFile(from:metadata:completion:)

Asynchronously uploads a file to the currently specified StorageReference.

Declaration

Swift

@discardableResult
@objc(putFile:metadata:completion:)
open func putFile(from fileURL: URL,
                  metadata: StorageMetadata? = nil,
                  completion: ((_: StorageMetadata?, _: Error?) -> Void)?) -> StorageUploadTask

Parameters

`fileURL`	A URL representing the system file path of the object to be uploaded.
`metadata`	`StorageMetadata` containing additional information (MIME type, etc.) about the object being uploaded.
`completion`	A completion block that either returns the object metadata on success, or an error on failure.

Return Value

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

Downloads


                    
                    
                    getData(maxSize:completion:)

Asynchronously downloads the object at the StorageReference to a Data instance in memory. A Data buffer of the provided max size will be allocated, so ensure that the device has enough free memory to complete the download. For downloading large files, write(toFile:) may be a better option.

Declaration

Swift

@discardableResult
@objc(dataWithMaxSize:completion:)
open func getData(maxSize: Int64,
                  completion: @escaping ((_: Data?, _: Error?) -> Void)) -> StorageDownloadTask

Parameters

`maxSize`	The maximum size in bytes to download. If the download exceeds this size, the task will be cancelled and an error will be returned.
`completion`	A completion block that either returns the object data on success, or an error on failure.

Return Value

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


                    
                    
                    downloadURL(completion:)

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.

Declaration

Swift

@objc(downloadURLWithCompletion:)
open func downloadURL(completion: @escaping ((URL?, Error?) -> Void))

Parameters


                                completion

A completion block that either returns the URL on success, or an error on failure.

downloadURL()
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.

Throws
An error if the download URL could not be retrieved.
Declaration
Swift

open func downloadURL() async throws -> URL
Return Value

The URL on success.


                    
                    
                    write(toFile:)

Asynchronously downloads the object at the current path to a specified system filepath.

Declaration

Swift

@discardableResult
@objc(writeToFile:)
open func write(toFile fileURL: URL) -> StorageDownloadTask

Parameters


                                fileURL

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


                    
                    
                    write(toFile:completion:)

Asynchronously downloads the object at the current path to a specified system filepath.

Declaration

Swift

@discardableResult
@objc(writeToFile:completion:)
open func write(toFile fileURL: URL,
                completion: ((_: URL?, _: Error?) -> Void)?) -> StorageDownloadTask

Parameters

`fileURL`	A file system URL representing the path the object should be downloaded to.
`completion`	A closure that fires when the file download completes, passed either a URL pointing to the file path of the downloaded file on success, or an error on failure.

Return Value

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

List Support


                    
                    
                    listAll(completion:)

Lists 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. All results are buffered in memory.

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

Declaration

Swift

@objc(listAllWithCompletion:)
open func listAll(completion: @escaping ((StorageListResult?, Error?) -> Void))

Parameters


                                completion

A completion handler that will be invoked with all items and prefixes under the current StorageReference.

listAll()
Lists 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. All results are buffered in memory. listAll() is only available for projects using Firebase Rules Version 2.

Throws
An error if the list operation failed.
Declaration
Swift

open func listAll() async throws -> StorageListResult
Return Value

All items and prefixes under the current StorageReference.


                    
                    
                    list(maxResults:completion:)

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

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

Only available for projects using Firebase Rules Version 2.

Declaration

Swift

@objc(listWithMaxResults:completion:)
open func list(maxResults: Int64,
               completion: @escaping ((_: StorageListResult?, _: Error?) -> Void))

Parameters

`maxResults`	The maximum number of results to return in a single page. Must be greater than 0 and at most 1000.
`completion`	A completion handler that will be invoked with up to `maxResults` items and prefixes under the current `StorageReference`.


                    
                    
                    list(maxResults:pageToken:completion:)

Resumes a previous call to list(maxResults:completion:), starting after a pagination token.

Returns the next set of items (files) and prefixes (folders) under this StorageReference.

“/” is treated as a path delimiter. Storage does not support unsupported object paths that end with “/” or contain two consecutive “/"s. All invalid objects in GCS will be filtered.

list(maxResults:pageToken:completion:)is only available for projects using Firebase Rules Version 2.

Declaration

Swift

@objc(listWithMaxResults:pageToken:completion:)
open func list(maxResults: Int64,
               pageToken: String,
               completion: @escaping ((_: StorageListResult?, _: Error?) -> Void))

Parameters

`maxResults`	The maximum number of results to return in a single page. Must be greater than 0 and at most 1000.
`pageToken`	A page token from a previous call to list.
`completion`	A completion handler that will be invoked with the next items and prefixes under the current StorageReference.

Metadata Operations


                    
                    
                    getMetadata(completion:)

Retrieves metadata associated with an object at the current path.

Declaration

Swift

@objc(metadataWithCompletion:)
open func getMetadata(completion: @escaping ((StorageMetadata?, Error?) -> Void))

Parameters


                                completion

A completion block which returns the object metadata on success, or an error on failure.

getMetadata()
Retrieves metadata associated with an object at the current path.

Throws
An error if the object metadata could not be retrieved.
Declaration
Swift

open func getMetadata() async throws -> StorageMetadata
Return Value

The object metadata on success.


                    
                    
                    updateMetadata(_:completion:)

Updates the metadata associated with an object at the current path.

Declaration

Swift

@objc(updateMetadata:completion:)
open func updateMetadata(_ metadata: StorageMetadata,
                         completion: ((_: StorageMetadata?, _: Error?) -> Void)?)

Parameters

`metadata`	A `StorageMetadata` object with the metadata to update.
`completion`	A completion block which returns the `StorageMetadata` on success, or an error on failure.


                    
                    
                    updateMetadata(_:)

Updates the metadata associated with an object at the current path.

Throws

An error if the metadata update operation failed.

Declaration

Swift

open func updateMetadata(_ metadata: StorageMetadata) async throws -> StorageMetadata

Parameters


                                metadata

A StorageMetadata object with the metadata to update.

Return Value

The object metadata on success.

Delete


                    
                    
                    delete(completion:)

Deletes the object at the current path.

Declaration

Swift

@objc(deleteWithCompletion:)
open func delete(completion: ((Error?) -> Void)?)

Parameters


                                completion

A completion block which returns a nonnull error on failure.

delete()
Deletes the object at the current path.

Throws
An error if the delete operation failed.
Declaration
Swift

open func delete() async throws

NSObject overrides

copy()
NSObject override
Declaration
Swift

override open func copy() -> Any


                    
                    
                    isEqual(_:)

NSObject override

Declaration

Swift

override open func isEqual(_ object: Any?) -> Bool

hash
NSObject override
Declaration
Swift

override public var hash: Int { get }


                    
                    
                    description

NSObject override

Declaration

Swift

override public var description: String { get }


                    
                    
                    data(maxSize:)

Asynchronously downloads the object at the StorageReference to a Data object in memory. A Data object of the provided max size will be allocated, so ensure that the device has enough free memory to complete the download. For downloading large files, the write API may be a better option.

Throws

An error if the operation failed, for example if the data exceeded maxSize.

Declaration

Swift

func data(maxSize: Int64) async throws -> Data

Parameters


                                maxSize

The maximum size in bytes to download. If the download exceeds this size, the task will be cancelled and an error will be thrown.

Return Value

Data object.


                    
                    
                    putDataAsync(_:metadata:onProgress:)

Asynchronously uploads data to the currently specified StorageReference. This is not recommended for large files, and one should instead upload a file from disk from the Firebase Console.

Throws

An error if the operation failed, for example if Storage was unreachable.

Declaration

Swift

func putDataAsync(_ uploadData: Data,
                  metadata: StorageMetadata? = nil,
                  onProgress: ((Progress?) -> Void)? = nil) async throws -> StorageMetadata

Parameters

`uploadData`	The Data to upload.
`metadata`	Optional StorageMetadata containing additional information (MIME type, etc.) about the object being uploaded.
`onProgress`	An optional closure function to return a `Progress` instance while the upload proceeds.

Return Value

StorageMetadata with additional information about the object being uploaded.


                    
                    
                    putFileAsync(from:metadata:onProgress:)

Asynchronously uploads a file to the currently specified StorageReference.

Throws

An error if the operation failed, for example if no file was present at the specified url.

Declaration

Swift

func putFileAsync(from url: URL,
                  metadata: StorageMetadata? = nil,
                  onProgress: ((Progress?) -> Void)? = nil) async throws -> StorageMetadata

Parameters

`url`	A URL representing the system file path of the object to be uploaded.
`metadata`	Optional StorageMetadata containing additional information (MIME type, etc.) about the object being uploaded.
`onProgress`	An optional closure function to return a `Progress` instance while the upload proceeds.

Return Value

StorageMetadata with additional information about the object being uploaded.


                    
                    
                    writeAsync(toFile:onProgress:)

Asynchronously downloads the object at the current path to a specified system filepath.

Throws

An error if the operation failed, for example if Storage was unreachable or fileURL did not reference a valid path on disk.

Declaration

Swift

func writeAsync(toFile fileURL: URL,
                onProgress: ((Progress?) -> Void)? = nil) async throws -> URL

Parameters

`fileURL`	A URL representing the system file path of the object to be uploaded.
`onProgress`	An optional closure function to return a `Progress` instance while the download proceeds.

Return Value

A URL pointing to the file path of the downloaded file.


                    
                    
                    list(maxResults:)

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

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

Only available for projects using Firebase Rules Version 2.

Throws

An error if the operation failed, for example if Storage was unreachable or the storage reference referenced an invalid path.

Declaration

Swift

func list(maxResults: Int64) async throws -> StorageListResult

Parameters


                                maxResults

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

Return Value

A StorageListResult containing the contents of the storage reference.


                    
                    
                    list(maxResults:pageToken:)

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

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

Only available for projects using Firebase Rules Version 2.

Throws

An error if the operation failed, for example if Storage was unreachable or the storage reference referenced an invalid path.

Declaration

Swift

func list(maxResults: Int64, pageToken: String) async throws -> StorageListResult

Parameters

`maxResults`	The maximum number of results to return in a single page. Must be greater than 0 and at most 1000.
`pageToken`	A page token from a previous call to list.

Return Value

completion A Result enum with either the list or an Error.


                    
                    
                    downloadURL(completion:)

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.

Declaration

Swift

func downloadURL(completion: @escaping (Result<URL, Error>) -> Void)

Parameters


                                completion

A completion block returning a Result enum with either a URL or an Error.


                    
                    
                    getData(maxSize:completion:)

Asynchronously downloads the object at the StorageReference to a Data object.

A Data of the provided max size will be allocated, so ensure that the device has enough memory to complete. For downloading large files, the write API may be a better option.

Declaration

Swift

@discardableResult
func getData(maxSize: Int64, completion: @escaping (Result<Data, Error>) -> Void)
  -> StorageDownloadTask

Parameters

`maxSize`	The maximum size in bytes to download.
`completion`	A completion block returning a `Result` enum with either a `Data` object or an `Error`.

Return Value

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


                    
                    
                    getMetadata(completion:)

Retrieves metadata associated with an object at the current path.

Declaration

Swift

func getMetadata(completion: @escaping (Result<StorageMetadata, Error>) -> Void)

Parameters


                                completion

A completion block which returns a Result enum with either the object metadata or an Error.


                    
                    
                    list(maxResults:pageToken:completion:)

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

Returns the next set of items (files) and prefixes (folders) under this StorageReference.

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

Only available for projects using Firebase Rules Version 2.

Declaration

Swift

func list(maxResults: Int64,
          pageToken: String,
          completion: @escaping (Result<StorageListResult, Error>) -> Void)

Parameters

`maxResults`	The maximum number of results to return in a single page. Must be greater than 0 and at most 1000.
`pageToken`	A page token from a previous call to list.
`completion`	A completion handler that will be invoked with the next items and prefixes under the current StorageReference. It returns a `Result` enum with either the list or an `Error`.


                    
                    
                    list(maxResults:completion:)

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

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

Only available for projects using Firebase Rules Version 2.

Declaration

Swift

func list(maxResults: Int64,
          completion: @escaping (Result<StorageListResult, Error>) -> Void)

Parameters

`maxResults`	The maximum number of results to return in a single page. Must be greater than 0 and at most 1000.
`completion`	A completion handler that will be invoked with the next items and prefixes under the current `StorageReference`. It returns a `Result` enum with either the list or an `Error`.


                    
                    
                    listAll(completion:)

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. All results are buffered in memory.

Only available for projects using Firebase Rules Version 2.

Declaration

Swift

func listAll(completion: @escaping (Result<StorageListResult, Error>) -> Void)

Parameters


                                completion

A completion handler that will be invoked with all items and prefixes under the current StorageReference. It returns a Result enum with either the list or an Error.


                    
                    
                    putData(_:metadata:completion:)

Asynchronously uploads data to the currently specified StorageReference. This is not recommended for large files, and one should instead upload a file from disk.

Declaration

Swift

@discardableResult
func putData(_ uploadData: Data,
             metadata: StorageMetadata? = nil,
             completion: @escaping (Result<StorageMetadata, Error>) -> Void)
  -> StorageUploadTask

Parameters

`uploadData`	The `Data` to upload.
`metadata`	`StorageMetadata` containing additional information (MIME type, etc.) about the object being uploaded.
`completion`	A completion block that returns a `Result` enum with either the object metadata or an `Error`.

Return Value

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


                    
                    
                    putFile(from:metadata:completion:)

Asynchronously uploads a file to the currently specified StorageReference.

Declaration

Swift

@discardableResult
func putFile(from: URL,
             metadata: StorageMetadata? = nil,
             completion: @escaping (Result<StorageMetadata, Error>) -> Void)
  -> StorageUploadTask

Parameters

`from`	A URL representing the system file path of the object to be uploaded.
`metadata`	`StorageMetadata` containing additional information (MIME type, etc.) about the object being uploaded.
`completion`	A completion block that returns a `Result` enum with either the object metadata or an `Error`.

Return Value

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


                    
                    
                    updateMetadata(_:completion:)

Updates the metadata associated with an object at the current path.

Declaration

Swift

func updateMetadata(_ metadata: StorageMetadata,
                    completion: @escaping (Result<StorageMetadata, Error>) -> Void)

Parameters

`metadata`	A `StorageMetadata` object with the metadata to update.
`completion`	A completion block which returns a `Result` enum with either the object metadata or an `Error`.


                    
                    
                    write(toFile:completion:)

Asynchronously downloads the object at the current path to a specified system filepath.

Declaration

Swift

@discardableResult
func write(toFile: URL, completion: @escaping (Result<URL, Error>)
  -> Void) -> StorageDownloadTask

Parameters

`toFile`	A file system URL representing the path the object should be downloaded to.
`completion`	A completion block that fires when the file download completes. The block returns a `Result` enum with either an NSURL pointing to the file path of the downloaded file or an `Error`.

Return Value

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

FirebaseStorage Framework Reference Stay organized with collections Save and categorize content based on your preferences.

StorageReference

Public APIs

Declaration

Declaration

Declaration

Declaration

Declaration

Return Value

Declaration

Return Value

Declaration

Parameters

Return Value

Uploads

Declaration

Parameters

Return Value

Declaration

Return Value

Declaration

Parameters

Return Value

Declaration

Parameters

Return Value

Declaration

Declaration

Parameters

Return Value

Downloads

Declaration

Parameters

Return Value

Declaration

Parameters

Declaration

Return Value

Declaration

Parameters

Declaration

Parameters

Return Value

List Support

Declaration

Parameters

Declaration

Return Value

Declaration

Parameters

Declaration

Parameters

Metadata Operations

Declaration

Parameters

Declaration

Return Value

Declaration

Parameters

Declaration

Parameters

Return Value

Delete

Declaration

Parameters

Declaration

NSObject overrides

Declaration

Declaration

Declaration

Declaration

Declaration

Parameters

Return Value

Declaration

Parameters

Return Value

Declaration

Parameters

Return Value

FirebaseStorage Framework Reference