Callback Mode

As discussed in the Vaults topic, the default behavior of CBVault class and its relatives, CBDrive and CBMemDrive classes is to create a vault using a real file on a local disk. However, the filesystem engine behind these classes doesn't 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 class's CallbackMode property. When callback mode is enabled, applications must handle the following events (which map closely to the Windows File API) in order for the class 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 the class needs to know how much free space is available for the currently-open vault to use for automatic growth.
  • VaultGetSize: Fires when the class 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 the class needs to read one or more pages of vault data.
  • VaultSetSize: Fires when the class needs to resize (i.e., shrink or grow) the currently-open vault.
  • VaultWrite: Fires when the class needs to write one or more pages of vault data.
(Note: All API members discussed in this topic are available in both CBDrive, CBMemDrive, 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.

Note: An application should not attempt to call class's methods from handlers of the listed events. Doing this is guaranteed to cause a deadlock.

Copyright (c) 2021 Callback Technologies, Inc. - All rights reserved.
CBFS Storage 2020 C++ Edition - Version 20.0 [Build 8031]