Studio Go to console

FirebaseStorage Framework Reference

StorageReference

@available(iOS13,tvOS13,macOS10.15,watchOS7,*)@objc(FIRStorageReference)openclassStorageReference: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

  • The Storage service object which created this reference.

    Declaration

    Swift

    @objcpublicletstorage: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

    @objcpublicvarbucket: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

    @objcpublicvarfullPath: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

    @objcpublicvarname:String{get}

  • Creates a new StorageReference pointing to the root object.

    Declaration

    Swift

    @objcopenfuncroot()->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.

    Forexample:path=foo/bar/baz parent = foo/barpath=fooparent=(root)path=(root)parent=nil

    Declaration

    Swift

    @objcopenfuncparent()->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=foochild=barnewPath=foo/barpath=foo/bar child = baz ntask.impl.snapshotwPath = foo/bar/bazAllleadingandtrailingslasheswillberemoved,andconsecutiveslasheswillbecompressedtosingleslashes.Forexample:child=/foo/bar newPath = foo/barchild=foo/bar/ newPath = foo/barchild=foo///bar newPath = foo/bar

    Declaration

    Swift

    @objc(child:)openfuncchild(_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

  • 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:)openfuncputData(_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:)openfunc__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:)openfuncputData(_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:)openfuncputFile(fromfileURL: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:)openfunc__putFile(fromfileURL:URL)->StorageUploadTask

  • Asynchronously uploads a file to the currently specified StorageReference.

    Declaration

    Swift

    @discardableResult@objc(putFile:metadata:completion:)openfuncputFile(fromfileURL: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

  • 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:)openfuncgetData(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:)openfuncdownloadURL(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

    openfuncdownloadURL()asyncthrows->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:)openfuncwrite(toFilefileURL: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:)openfuncwrite(toFilefileURL: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

  • 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:)openfunclistAll(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

    openfunclistAll()asyncthrows->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:)openfunclist(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:)openfunclist(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

  • Retrieves metadata associated with an object at the current path.

    Declaration

    Swift

    @objc(metadataWithCompletion:)openfuncgetMetadata(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

    openfuncgetMetadata()asyncthrows->StorageMetadata

    Return Value

    The object metadata on success.

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

    Declaration

    Swift

    @objc(updateMetadata:completion:)openfuncupdateMetadata(_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

    openfuncupdateMetadata(_metadata:StorageMetadata)asyncthrows->StorageMetadata

    Parameters

    metadata

    A StorageMetadata object with the metadata to update.

    Return Value

    The object metadata on success.

Delete

  • Deletes the object at the current path.

    Declaration

    Swift

    @objc(deleteWithCompletion:)openfuncdelete(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

    openfuncdelete()asyncthrows

NSObject overrides

  • NSObject override

    Declaration

    Swift

    overrideopenfunccopy()->Any

  • NSObject override

    Declaration

    Swift

    overrideopenfuncisEqual(_object:Any?)->Bool

  • NSObject override

    Declaration

    Swift

    overridepublicvarhash:Int{get}

  • NSObject override

    Declaration

    Swift

    overridepublicvardescription: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

    funcdata(maxSize:Int64)asyncthrows->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

    funcputDataAsync(_uploadData:Data,metadata:StorageMetadata?=nil,onProgress:((Progress?)->Void)?=nil)asyncthrows->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 specified url.

    Declaration

    Swift

    funcputFileAsync(fromurl:URL,metadata:StorageMetadata?=nil,onProgress:((Progress?)->Void)?=nil)asyncthrows->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

    funcwriteAsync(toFilefileURL:URL,onProgress:((Progress?)->Void)?=nil)asyncthrows->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

    funclist(maxResults:Int64)asyncthrows->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

    funclist(maxResults:Int64,pageToken:String)asyncthrows->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

    funcdownloadURL(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

    @discardableResultfuncgetData(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

    funcgetMetadata(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

    funclist(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

    funclist(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

    funclistAll(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

    @discardableResultfuncputData(_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

    @discardableResultfuncputFile(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

    funcupdateMetadata(_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

    @discardableResultfuncwrite(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.

close