Using Callback Mode in CBFS Vault

What is Callback Mode?

CBFS Vault's default behavior is to create and store a Vault as a real file on a local disk. However, the CBFS Vault engine doesn't actually require that a Vault be persisted in this manner. The ability to store a Vault as a file on disk comes built-in because it's the most common use-case; but CBFS Vault actually allows you to have complete control over where and how a Vault is persisted, if so desired, using callback mode.

The purpose of this article is to discuss what callback mode is, and describe how it can be used. However, before we dive into that, it's helpful to fist understand the basics of how CBFS Vault actually manages a Vault's data. CBFS Vault works by embedding a complete filesystem into some kind of container (be it a file, a physical storage volume/partition, or—as we'll discuss in this article—something else), and we call such containers "Vaults".

CBFS Vault, like most filesystem engines, tracks and manages the filesystem's contents in fixed-size chunks called pages. However, these pages are not involved in the filesystem hierarchy itself, they just store its contents as raw data, and can thus be persisted anywhere. As mentioned above, CBFS Vault provides built-in support for two methods of storing these pages: in a real file on a local disk, and persisting a Vault's pages in "callback mode". A "callback mode Vault" is one whose pages are persisted by your application's code rather than by the CBFS Vault engine itself. That is to say, your application has complete control over how and where each page is stored. At this point it should be clear that callback mode is an extremely powerful feature. So, how do you use it?

Using Callback Mode

As its name implies, callback mode works by delegating persistence-related tasks to your application. To handle these tasks, your application must implement the following events:

• 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 Vault needs to know how much free space is available for the currently-open Vault to use for automatic growth.
• VaultGetSize: Fires when CBFS Vault 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 Vault needs to read one or more pages of Vault data.
• VaultSetSize: Fires when CBFS Vault needs to resize (i.e., shrink or grow) the currently-open Vault.
• VaultWrite: Fires when CBFS Vault needs to write one or more pages of Vault data.

We won't discuss how to correctly handle each and every one of these events here (refer to their documentation for that information), but even just seeing the names of the events should communicate how simple it is to use callback mode. It's up to your application how and where to store the Vault's pages; many advanced strategies (on-the-fly Vault mirroring, in-memory Vaults, advanced hardening techniques, etc.) are possible using callback mode.

Once you've implemented the aforementioned events, just enable the CallbackMode property and use the component the same way as always; CBFS Vault will take care of routing all of the necessary calls to your application via the events.