FB4D Reference IFirebaseStorage

Interface IFirebaseStorage

This interface provides all functions for accessing the Firestore Cloud Storage. The interface will be created by the constructor of the class TFirebaseStorage in the unit FB4D.Storage. The constructor expects as a parameter the Bucket Name of the Firebase Project and an instance of the interface IFirebaseAuthentication that is in the state signed-in. You will find the bucket name in the Firebase Console in the storage tab. The bucket name is the storage address gs://<your bucket name> thereby you must remove the prefix gs://.

var
  Storage: IFirebaseStorage;
begin
  Storage := TFirebaseStorage.Create(<BucketName: string>, <IFirebaseAuthentication>);

Alternatively, you can use the class factory TFirebaseConfiguration.Storage to get an instance of TFirebaseStorage.

Get Storage Object

The method Get retrieves the file header record as IStorageObject from one single file object of the storage. The ObjectName of type TObjectName which is a proxy for a string contains the filename with path.

function GetSynchronous(const ObjectName: TObjectName): IStorageObject;

The following method is provided for asynchronous access:

procedure Get(const ObjectName: TObjectName; OnGetStorage: TOnStorage; OnGetError: TOnStorageError); 

type
  TOnStorage = procedure(const ObjectName: TObjectName; Obj: IStorageObject) of object;
  TOnStorageError = procedure(const ObjectName: TObjectName; const ErrMsg: string) of object;

Hints:

In the former version until V1.2 this method was provided with an additional RequestID parameter so that in the two callback functions the get request could be assigned on the basis of this ID. This interface is now simplified and in the callback, the object name with path references the request. The previous method is marked as deprecated and will be removed with version 1.3.
In the call chain of the asynchronous calls Get and DownloadToStream it could happen up to version 1.2 that IStorageObject objects were released too early and that results in sporadical errors that were difficult to find. To avoid this, the TFirebaseStorage class now manages a list of storage object references, and only releases them when the IStorageObject is deleted or the class FirebaseStorage gets free.

Upload Storage Files from Stream

To upload a new file the method UploadFromStream or UploadSynchronousFromStream takes a stream and stores it into the storage by the given ObjectName. If the file or object already exists, it will be overwritten by this method. The ContentType defines the file type.

function UploadSynchronousFromStream(Stream: TStream;
  const ObjectName: TObjectName; ContentType: TRESTContentType): IStorageObject;

procedure UploadFromStream(Stream: TStream; const ObjectName: TObjectName;
  ContentType: TRESTContentType; OnUpload: TOnStorage; OnUploadError: TOnStorageError);

Delete Storage Files

Use one of the following methods to delete a file from the storage addressed by the ObjectName:

procedure DeleteSynchronous(const ObjectName: TObjectName);

procedure Delete(const ObjectName: TObjectName; OnDelete: TOnDeleteStorage; OnDelError: TOnRequestError);

Optional Cache for Storage Objects

Version 1.2 brings new long-term storage of loaded memory files so that the heavy objects do not have to be reloaded from the Google Server at every application start. Each time an object is accessed, a check is made to see whether a newer version is available on the server than the one in the cache. This function is deliberately kept as an option. The use of the cache for the Storage does not make sense for all applications. To use this storage cache, the SetupCacheFolder method must be called before the first storage access can be done. This method scans the contents of the entire Storage Folder and generates the MD5 hash code for each file, which takes some time. But this job is done in a background thread so that the application remains responsive.

procedure SetupCacheFolder(const FolderName: string;
  MaxCacheSpaceInBytes: int64 = cDefaultCacheSpaceInBytes);

It is recommended to pass a hidden folder in the FolderName parameter so that an average user does not come into contact with the contents of this folder. For this purpose e.g. TPath.GetHomePath + '\<ApplicationName>' can be used as FolderName. The default cache size is currently set to 500 MByte. Change and set this parameter carefully if necessary, because a cache that is too small in normal operation will only slow down your application. On the other hand, it is important that files that are no longer needed over a long period of operation are also removed from the cash. For this, the method SetupCacheFolder removes the oldest files from the cache when the memory size is exceeded the specified amount. Also with new uploads and downloads, the memory size is supervised, and if necessary older files are removed again. Note that the entire folder is managed by TFirebaseStorage and therefore no additional files may be stored in this folder. The background thread started by _SetupCacheFolder _ takes a moment depending on content size and access speed. Although the later access to the cache is secured with a Critical Section, it is strongly recommended to wait for the end of the scan and their following cleanup before the application starts accessing the storage. For this purpose, the following function can be queried to display an animation during startup.

function IsCacheScanFinished: boolean;

To clear the cache in the rare cases during the program runtime, the following function is available.

procedure ClearCache;

To know the cache load, the following function can be used.

function CacheUsageInPercent: extended;

To detect a cache overflow, the following flag informs when a newly loaded file must already be removed again due to too-small cache size. You can check this flag after each storage download.

function IsCacheOverflowed: boolean;

Internally, the FirebaseStorage needs to know if the cache is being used. The following function, which can also be called from the application, serves this purpose.