# files.h

Interface for asyncronous reading and writing of files in an <app-instance>.files folder. The file to be read/written is identified by a ulong64 id, which is converted to a filename with _sprintf(name, "%llu", id).

Note: currently the implementation is blocking, but could be changed to non-blocking without change to the app.

## File information

File | common/interface/files.h
Public functions | CreateFilesProvider CreateTempFilesProvider
Classes | IFilesProvider IFiles IFilesWrite IFilesRead IFilesDel IFilesWrite ITempFilesProvider ITempFiles

# Public functions

## CreateFilesProvider

    class IFilesProvider * CreateFilesProvider(class IIoMux * iomux);

Function to allocate the FilesProvider resource, to be called from the app-main, so that the real FileProvider can be replaced by a unit-test implementation.

## CreateTempFilesProvider

    class ITempFilesProvider * CreateTempFilesProvider(class IIoMux * iomux);

Function to allocate the TempFilesProvider Resource, to be called from the app-main, so that the read Fileprovider could be replaced by a unit-test implementation

# Classes

## IFilesProvider

    class IFilesProvider {
    public:
        virtual ~IFilesProvider() {}
        virtual class IFiles * CreateFiles(class IInstanceLog * const log, const char * serviceId, const char * path) = 0;
    };

### ITempFiles::CreateTempFiles

Allocate the FilesProvider for a given instance. serviceId should be AppService->GetAppServiceId(), path should be the same as the dbName, it is used to create the actual path on the system for the files in the form /apps/<serviceId>/<dbName>.files, which is a folder created by the taskmanager for the app. log is used to log dependent of the log flag LOG_FILES.

## IFiles

    class IFiles {
    public:
        virtual ~IFiles() {}
        virtual class IFilesWrite * Write(class UTask * user, ulong64 id, compress = false) = 0;
        virtual class IFilesRead * Read(class UTask * user, ulong64 id, unsigned length, unsigned offset = 0, bool progress = false, decompress = false) = 0;
        virtual class IFilesDel * Del(class UTask * user, ulong64 id) = 0;
    };

Interface class to initiate the read and write operations

### IFiles::Write

Initiates a write operation. The allocated IFilesWrite class is derived from ITask, so the ITask/UTask mechanisms are used for progress and completion. The optional parameter compress enables compression in gzip format.

### IFiles::Read

Initiates a read operation. The allocated IFilesRead class is derived from ITask, so the ITask/UTask mechanisms are used for progress and completion. length is the length of the initial block, to be read. This block is available at the first TaskProgress callback. offset is the offset inside the file from which reading should start. progress indicates that a TaskProgress call should be used always when the data is available, even if this is the last data. In this case TaskComplete is called after the next read, when the file is closed. The optional parameter decompress enables decompression from gzip format.

### IFiles::Del

Initiates a delete operation. The allocated IFilesDel class is derived from ITask, so the ITask/UTask mechanisms are used for completion.

## IFilesWrite

    class IFilesWrite : public ITask {
    public:
        virtual void Write(const byte * data, unsigned length, bool last) = 0;
        virtual ulong64 GetId() const = 0;
        virtual const char * GetAbsoluteFileName() const = 0;
        virtual void Close() = 0;
    };

### IFilesWrite::Write

Write a block of data to the file. This function may be called in the TaskProgress callback or assynchronously after the first TaskProgress call. The passed buffer may be freed on return from the call. last indicates the last block of data, when set the file is closed and the task completes.

### IFilesWrite::GetId

Returns the id of the file.

### IFilesWrite::GetAbsoluteFileName

### IFilesWrite::Close

Returns the absolute path file name of the file, if needed for a command execution.

## IFilesRead

    class IFilesRead : public ITask {
    public:
        virtual void Read(unsigned length, bool last) = 0;
        virtual void Get(const byte * & data, unsigned & length) const = 0;
        virtual void Close() = 0;
    };

### IFilesWrite::Read

Initiates reading of the next block. May be called after TaskProgress for the previous block.

last
  Indicates that this is the last block of data to read. The task terminates after this, even if there is more data available

### IFilesWrite::GetId

Get a pointer to the read block of data. May be called after the TaskProgress for the read operation. The pointer is valid until the next call to Read. A length of 0 indicates the end of file.

### IFilesWrite::Close

Returns the absolute path file name of the file, if needed for a command execution.

## IFilesDel

    class IFilesDel : public ITask {
    public:
    };

ITask class for a delete operation

## ITempFilesProvider

    class ITempFilesProvider {
    public:
        virtual ~ITempFilesProvider() {}
        virtual class ITempFiles * CreateTempFiles(class IInstanceLog * const log, const char * serviceId, const char * path) = 0;
    };

Interface for asyncronous reading and writing of files in an <app-instance>.temp folder. The file to be read/written is identified by a ulong64 id, which is converted to a filename with _sprintf(name, "%llu", id).

Note: Currently the implementation is blocking, but could be changed to non-blocking without change to the app.

### ITempFiles::CreateTempFiles

Allocate the TempFilesProvider for a given instance.
serviceId should be AppService->GetAppServiceId(), path should be the same as the dbName, it is used to create the actual path on the system for the files in the form /apps/<serviceId>/<dbName>.temp, which is a folder created by the taskmanager for the app. log is used to log dependent of the log flag LOG_FILES.

## ITempFiles

    class ITempFiles {
    public:
        virtual ~ITempFiles() {}
        virtual class IFilesWrite * Write(class UTask * user, bool compress = false) = 0;
        virtual class IFilesRead * Read(class UTask * user, ulong64 id, unsigned length, unsigned offset = 0, bool progress = false, bool decompress = false) = 0;
        virtual class IFilesDel * Del(class UTask * user, ulong64 id) = 0;
    };

Interface class to initiate the read and write operations. IFilesWrite, IFilesRead and IFilesDel are defined in files.htm

### ITempFiles::Write

Initiates a write operation. The allocated IFilesWrite class is derived from ITask, so the ITask/UTask mechanisms are used for progress and completion. The optional parameter compress enables compression in gzip format.

### ITempFiles::Read

Initiates a read operation. The allocated IFilesRead class is derived from ITask, so the ITask/UTask mechanisms are used for progress and completion. length is the length of the initial block, to be read. This block is available at the first TaskProgress callback. The optional parameter decompress enables decompression of files written in gzip format.

### ITempFiles::Del

Initiates a delete operation. The allocated IFilesDel class is derived from ITask, so the ITask/UTask mechanisms are used for completion.