Using Callback Mode in CBFS Storage
What is Callback Mode?
CBFS Storage's default behavior is to create and store a vault as a real file on a local disk. However, the CBFS Storage 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 Storage 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 Storage actually manages a vault's data. CBFS Storage 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 Storage, 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 Storage provides built-in support for two methods of storing these pages: in a real file on a local disk, and as a physical storage volume or partition (though the latter is a feature unique to the CBDrive component).
The "third option" for persisting a vault's pages is to use callback mode. A "callback mode vault" is one whose pages are persisted by your application's code rather than by the CBFS Storage 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 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.
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 Storage will take care of routing all of the necessary calls to your application via the events.
We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at firstname.lastname@example.org.