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.
-
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 }
-
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 }
-
The short name of the object associated with this reference.
In
gs://bucket/path/to/object.txt
, the name of the object would beobject.txt
.Declaration
Swift
@objc public var name: String { get }
-
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. -
Creates a new
StorageReference
pointing to the parent of the current reference ornil
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. -
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.
-
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. -
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. -
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. -
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. -
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
-
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.
-
Asynchronously downloads the object at the
StorageReference
to aData
instance in memory. AData
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. -
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.
-
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.
-
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.
-
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.
-
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
. -
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 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 currentStorageReference
. -
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.
-
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.
-
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.
-
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. -
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.
-
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.
-
Deletes the object at the current path.
Throws
An error if the delete operation failed.Declaration
Swift
open func delete() async throws
-
NSObject override
Declaration
Swift
override open func copy() -> Any
-
NSObject override
Declaration
Swift
override open func isEqual(_ object: Any?) -> Bool
-
NSObject override
Declaration
Swift
override public var hash: Int { get }
-
NSObject override
Declaration
Swift
override public var description: String { get }
-
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 exceededmaxSize
.Declaration
Swift
func data(maxSize: Int64) async throws -> Data
Parameters
size
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.
-
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.
-
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 specifiedurl
.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. -
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 orfileURL
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 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 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 anError
.
-
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 anError
. -
Asynchronously downloads the object at the
StorageReference
to aData
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, thewrite
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 aData
object or anError
.Return Value
A StorageDownloadTask that can be used to monitor or manage the download.
-
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 anError
. -
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 anError
. -
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 aResult
enum with either the list or anError
. -
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 anError
. -
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 anError
.Return Value
An instance of
StorageUploadTask
, which can be used to monitor or manage the upload. -
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 anError
.Return Value
An instance of
StorageUploadTask
, which can be used to monitor or manage the upload. -
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 anError
. -
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 anError
.Return Value
A
StorageDownloadTask
that can be used to monitor or manage the download.