Solid File System

Virtual file system enigne that can be embedded into your software.

Use callback mode to keep storage in custom places or to obfuscate the storage

By default SolFS keeps the storage in the file located on the disk. However, SolFS engine doesn't really care about where the data is stored. You can keep the storage in the file or on raw disk partition, in memory or somewhere across network. The only thing SolFS needs is possibility to get random access to the pages of the storage.

To keep the storage in other locations, you need to use so-called callback mode (read general introduction to callback mode online in SolFS knowledgebase). In this mode SolFS will fire various OnFile* events (see the event list below) which you must handle. The events are not hard to handle and they all map quite closely to Windows File API. The events were designed to be very easy to implement. Actual processing of each of the 10 events that you need to handle can take as little as one call to the underlying API.

One of scenarios for use of callback mode is keeping the compound file in memory for fast operations. For example, help authoring tool, used to create this Help file, stores all topics in separate files in SolFS storage. The storage itself is a help project. Help authoring tool loads the help project to a memory stream and uses callback mode to work with the storage. When the user needs to save the project, the storage is flushed and memory stream is copied to disk file.

In APIs that have events (VCL, .NET, C++ class) the event handlers are set by assigning them to events, exposed by SolFSStorage class. Alternatively you can pass the event handlers as parameters to CreateOpenCB() constructor.

In DLL/Lib API you pass the addresses of callback functions as parameters to StorageCreateOpenCB(), StorageFormatFixedSizeCB() and StorageCheckAndRepairCB() functions.

Here's the list of events that your application needs to handle:

  • OnFileCreate. You must create new storage. You can use the storage name, passed to SolFSStorage Constructor to identify the storage.
  • OnFileOpen. You must open existing storage. You can use the storage name, passed to SolFSStorage Constructor to identify the storage.
  • OnFileClose. You must close the storage and invalidate the storage handle.
  • OnFileFlush. You must save all cached data to the media (this includes transferring the data to the remote system if needed) and, if possible or necessary, call the corresponding Flush procedure on the underlying media.
  • OnFileDelete. You must delete the storage.
  • OnFileGetSize. You must return the size of the storage in bytes to SolFS.
  • OnFileSetSzie. You must resize the storage according to the request. You don't need to clean newly allocated space if the storage size was increased.
  • OnFileSeek. You must adjust file pointer position according to the event parameters. File pointer position is position at which the reading or writing operation is performed. This position is adjusted before OnFileRead or OnFileWrite events are fired.
  • OnFileRead. You must read the requested amount of data from the storage, starting from file pointer position. File pointer position is adjusted using OnFileSeek event. Reading is always performed in chunks having size of multiple of storage page size.
    If the event handler can't read all of the requested data, the non-zero error code must be returned.
  • OnFileWrite. You must write the requested amount of data to the storage, starting from file pointer position. File pointer position is adjusted using OnFileSeek event. Writing is always performed in chunks having size of multiple of storage page size.
    If the event handler can't write all of the requested data, the non-zero error code must be returned.

Back to top