Callback Mode

As discussed in the Vaults topic, the CBFS Storage classs' default behavior is to create a vault using a real file on a local disk. However, the CBFS Storage engine doesn't actually require a vault to be a local file; it can be a remote file, a memory region, or anything else that the application can provide random read/write access to.

Applications that wish to use something other than a local file to store a vault must enable callback mode using the CBFS Storage classs' CallbackMode property. When callback mode is enabled, applications must handle the following events (which map closely to the Windows File API) in order for CBFS Storage to interact with the vault. For brevity, vaults created and accessed using callback mode are typically referred to as "callback mode vaults".

  • VaultClose: Fires when the currently-open vault should be closed.
  • VaultDelete: Fires when a callback mode vault (that is not open) should be deleted.
  • VaultFlush: Fires when any buffered vault data should be flushed out to storage.
  • VaultGetParentSize: Fires when CBFS Storage needs to know how much free space is available for the currently-open vault to use for automatic growth.
  • VaultGetSize: Fires when CBFS Storage needs to know the size of the currently-open vault.
  • VaultOpen: Fires when a callback mode vault should be opened (and, if necessary, created).
  • VaultRead: Fires when CBFS Storage needs to read one or more pages of vault data.
  • VaultSetSize: Fires when CBFS Storage needs to resize (i.e., shrink or grow) the currently-open vault.
  • VaultWrite: Fires when CBFS Storage needs to write one or more pages of vault data.
(Note: All API members discussed in this topic are available in both CBDrive and CBVault, unless otherwise noted.)

Callback mode is an extremely powerful feature for applications that want to fine-tune performance. For example, consider the following scenario: a help authoring tool that keeps a compound file in memory for fast operations. In this scenario, the vault itself would be a help project which the help authoring tool loads into memory and uses the above events to access. When a user needs to save the project, the vault is flushed and the data in memory is copied back to the help project on disk.

 
 
Copyright (c) 2020 Callback Technologies, Inc. - All rights reserved.
CBFS Storage 2020 Qt Edition - Version 20.0 [Build 7649]