Event Types
The events provided by the CBFS Filter classs generally fall into two categories: Control Events, which are synchronous; and Notification Events, which are asynchronous.
Control Events allow an application to control the execution of an operation. They are fired before a request reaches the applicable system component; and, for certain operations, are also fired after the request is handled (i.e., as its response comes back). Control Events have names like BeforeOperation and AfterOperation.
Notification Events, which have names like NotifyOperation, inform an application that an operation has been performed. They are fired as a response comes back (specifically, after the applicable AfterOperation event fires, if such an event exists).
To get a better idea of the general event flow for an operation, please refer to this diagram:
- A process sends a request, causing the corresponding BeforeOperation event to fire synchronously. The BeforeOperation events allow an application to do things like:
- Allow the request to continue, potentially after modifying its parameters/data.
- Handle the request itself.
- Deny the request entirely.
- Store information about the request in the event's contexts, so that it can be used during the AfterOperation event later.
- Once the request gets to the applicable system component, the requested operation will occur, and a response will be sent back to the process, causing the corresponding
AfterOperation event to fire synchronously. The AfterOperation events allow applications to do things like:
- Perform an action based on whether the operation succeeded or failed.
- Modify the response (if the operation supports doing so).
- Do something with the information stored in the event's contexts during the BeforeOperation event earlier.
- The response continues onwards toward the process, causing the corresponding NotifyOperation event to fire asynchronously. The NotifyOperation events cannot
be used to modify responses, nor do they include event contexts; they are best-suited for doing things like audit logging, change journaling, etc.
- More specifically, notification events are queued for delivery, and fired on a "best-effort" basis.
- The notification event queue's size is not artificially limited, it will continue to grow (if necessary) so long as the system has sufficient resources available.
Please note that the system can have multiple filter drivers loaded simultaneously, and any filter driver that a request or response "reaches" can do any of the things described above. Please refer to the Driver Altitudes topic for more information.
Each of the CBFS Filter classs provide a different set of events for each operation, so the event flow for a particular operation may be simpler than the one shown above depending which class is being used. Here's a quick summary of which events each class offers:
- The CBFilter class offers BeforeOperation, AfterOperation, and NotifyOperation events for almost all operations.
- The CBProcess class only offers BeforeOperation events (though for simplicity, their names don't use the "Before" prefix).
- The CBRegistry class offers BeforeOperation and AfterOperation events.
- The CBMonitor class, a "monitoring-only" subset of CBFilter, offers the same NotifyOperation events, plus the BeforeFilterAttachToVolume, AfterFilterAttachToVolume, and AfterFilterDetachFromVolume control events.
For more information about how to use event contexts in CBFilter, please refer to this topic; and for more information about how to use them in CBRegistry, please refer to this topic.