FirebaseStorage Framework Reference

StorageReference

@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 Storage service object which created this reference.

    Declaration

    Swift

    @objc
    public let storage: Storage
  • 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 be object.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 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.

  • 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. putData should be used instead of putFile in Extensions.

    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. putData should be used instead of putFile in Extensions. @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. putData should be used instead of putFile in Extensions.

    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 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.

  • 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

    @available(iOS 13, tvOS 13, macOS 10.15, watchOS 8, *)
    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

    @available(iOS 13, tvOS 13, macOS 10.15, watchOS 8, *)
    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 current StorageReference.

  • 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

    @available(iOS 13, tvOS 13, macOS 10.15, watchOS 8, *)
    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

    @available(iOS 13, tvOS 13, macOS 10.15, watchOS 8, *)
    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

    @available(iOS 13, tvOS 13, macOS 10.15, watchOS 8, *)
    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 exceeded maxSize.

    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. putDataAsync should be used instead of putFileAsync in Extensions.

    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.

  • 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 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 an Error.

  • 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.

  • 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.

  • 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.

  • 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 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.