CBDirect Component
Properties Methods Events Config Settings Errors
The CBDirect component provides applications with low-level, direct access to disks and memory in Windows.
Syntax
callback.CBFSDirect.Cbdirect
Remarks
The CBDirect component is used to gain low-level, direct access to disks and memory in Windows. The component allows bypassing certain Windows access restrictions, even under limited user accounts.
Getting Started
All of the CBDirect component's methods are independent, and can be called immediately after creating an instance of the component.
Here's how to get up and running:
- If the system driver hasn't been installed yet, call the Install method to do so. This only needs to be done once.
- In production, the system driver can be installed (or updated) ahead-of-time by the application's installation script using the Installer DLL. Please refer to the Driver Installation topic for more information.
- Call the component's methods as needed.
- To uninstall the system driver, call the Uninstall method. This should not be done as part of the driver upgrade process.
- In production, the system driver can be uninstalled by the application's uninstallation script using the Installer DLL. Please refer to the Driver Installation topic for more information.
Property List
The following is the full list of the properties of the component with short descriptions. Click on the links for further details.
Tag | Stores application-defined data specific to this instance of the component. |
Method List
The following is the full list of the methods of the component with short descriptions. Click on the links for further details.
Config | Sets or retrieves a configuration setting. |
CreateFile | Creates or opens a file or directory by passing the request directly to the filesystem. |
CreateFileAsStream | Creates or opens a file as a stream by passing the request directly to the filesystem. |
DeleteFile | Deletes a file by passing the request directly to the filesystem. |
GetDriverStatus | Retrieves the status of the component's system driver. |
GetDriverVersion | Retrieves the version of the component's system driver. |
GetSectorCount | Returns the number of sectors on the specified disk device. |
GetSectorSize | Returns the sector size used by the specified disk device. |
Initialize | Initializes the component. |
Install | Installs (or upgrades) the component's system driver. |
OpenMemory | Provides raw, read-only access to the system's physical memory. |
OpenMemoryAsStream | Provides raw, read-only access to the system's physical memory as a stream. |
OpenVolume | Opens a volume. |
OpenVolumeAsStream | Opens a volume as a stream. |
ReadSectors | Reads data from sectors of a disk. |
ShutdownSystem | Shuts down or reboots the operating system. |
Uninstall | Uninstalls the component's system driver. |
WriteSectors | Writes data to sectors on a disk. |
Event List
The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.
Error | Fires if an unhandled error occurs during an event. |
Config Settings
The following is a list of config settings for the component with short descriptions. Click on the links for further details.
BuildInfo | Information about the product's build. |
LicenseInfo | Information about the current license. |
Tag Property (CBDirect Component)
Stores application-defined data specific to this instance of the component.
Syntax
Default Value
0
Remarks
This property can be used to store data specific to a particular instance of the component.
Config Method (CBDirect Component)
Sets or retrieves a configuration setting.
Syntax
Remarks
Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.
These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.
To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).
To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.
CreateFile Method (CBDirect Component)
Creates or opens a file or directory by passing the request directly to the filesystem.
Syntax
Remarks
This method should be used instead of the Windows API's CreateFile function to create or open the file or directory specified by FileName when some other process has it open exclusively, or when the application doesn't have sufficient security rights/permissions to access it in a "standard" way.
If the file or directory is created or opened successfully, this method returns a file handle for it; otherwise, it returns INVALID_HANDLE_VALUE. The returned handle, if valid, must be closed using the Windows API's CloseHandle function when the application is finished with it.
The returned handle can be used with the Windows API's ReadFile and WriteFile functions.
The FileName, DesiredAccess, CreationDisposition, and FlagsAndAttributes parameters correspond to the lpFileName, dwDesiredAccess, dwCreationDisposition, and dwFlagsAndAttributes parameters of the Windows API's CreateFile function (respectively). Please refer to Microsoft's documentation for more information on how to set these parameters appropriately.
CreateFileAsStream Method (CBDirect Component)
Creates or opens a file as a stream by passing the request directly to the filesystem.
Syntax
public CBFSDirectStream CreateFileAsStream(string fileName, int desiredAccess, int creationDisposition, int flagsAndAttributes);
Public Function CreateFileAsStream(ByVal FileName As String, ByVal DesiredAccess As Integer, ByVal CreationDisposition As Integer, ByVal FlagsAndAttributes As Integer) As CBFSDirectStream
Remarks
This method should be used instead of the Windows API's CreateFile function to create or open the file specified by FileName when some other process has it open exclusively, or when the application doesn't have sufficient security rights/permissions to access it in a "standard" way.
If the file is created or opened successfully, this method returns a stream object that provides access to its data; otherwise, it returns null.
The FileName, DesiredAccess, CreationDisposition, and FlagsAndAttributes parameters correspond to the lpFileName, dwDesiredAccess, dwCreationDisposition, and dwFlagsAndAttributes parameters of the Windows API's CreateFile function (respectively). Please refer to Microsoft's documentation for more information on how to set these parameters appropriately.
DeleteFile Method (CBDirect Component)
Deletes a file by passing the request directly to the filesystem.
Syntax
Remarks
This method should be used instead of the Windows API's DeleteFile function to delete the file specified by FileName when some other process has it open exclusively, or when the application doesn't have sufficient security rights/permissions to access it in a "standard" way.
If CloseOpenHandles is true, this method closes and invalidates all opened handles to the file before deleting it.
GetDriverStatus Method (CBDirect Component)
Retrieves the status of the component's system driver.
Syntax
Remarks
This method retrieves the status of the component's system driver. This status can then be used to verify whether it has been properly installed and is ready for use.
The value returned by the method corresponds to the dwCurrentState field of the SERVICE_STATUS structure from the Windows API. It will be one of the following:
MODULE_STATUS_NOT_PRESENT | 0x00000000 | The specified module is not present on the system. |
MODULE_STATUS_STOPPED | 0x00000001 | The specified module is in the Stopped state. |
MODULE_STATUS_RUNNING | 0x00000004 | The specified module is loaded and running. |
ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.
Therefore, to ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:
- Install
- Uninstall
- GetDriverStatus
- GetDriverVersion
- Initialize
This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.
Note: This method cannot be called within events.
GetDriverVersion Method (CBDirect Component)
Retrieves the version of the component's system driver.
Syntax
Remarks
This method retrieves the version of the component's system driver. The value is returned as a 64-bit integer composed of four 16-bit words that each correspond to a piece of the overall module version. For example, a version of 2.32.6.28 would cause the value 0x000200200006001C to be returned.
If the component's system driver is not installed, this method returns 0.
ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.
Therefore, to ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:
- Install
- Uninstall
- GetDriverStatus
- GetDriverVersion
- Initialize
This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.
Note: This method cannot be called within events.
GetSectorCount Method (CBDirect Component)
Returns the number of sectors on the specified disk device.
Syntax
Remarks
This method returns the number of sectors on the disk device identified by VolumeHandle. The value passed for VolumeHandle must be a volume handle obtained from the OpenVolume method; refer to its documentation for more information.
GetSectorSize Method (CBDirect Component)
Returns the sector size used by the specified disk device.
Syntax
Remarks
This method returns the sector size, in bytes, that is used by the disk device identified by VolumeHandle. The value passed for VolumeHandle must be a volume handle obtained from the OpenVolume method; refer to its documentation for more information.
Initialize Method (CBDirect Component)
Initializes the component.
Syntax
Remarks
This method initializes the component and must be called each time the application starts before attempting to call any of the component's other methods with the exception of installation-related methods.
ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.
The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.
To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:
- Install
- Uninstall
- GetDriverStatus
- GetModuleVersion
- RegisterIcon
- UnregisterIcon
- Initialize
If the required driver was not installed using the Install method with the same value of ProductGUID, Initialize will return a ERROR_FILE_NOT_FOUND error (Win32 error code 2).
Install Method (CBDirect Component)
Installs (or upgrades) the component's system driver.
Syntax
Remarks
This method is used to install or upgrade the component's system driver. If the system must be rebooted to complete the installation process, this method returns true; otherwise, it returns false.
Important: To upgrade the product's modules, use only the Install method. Previously installed versions of the modules should not be uninstalled first. Calling the Install method will upgrade the previously installed version.
Please refer to the Driver Installation topic for more information.
CabFileName must be the path of the .cab file containing the component's system driver. Important: This .cab file must remain on the target system (or be available in some other way) after installation, as it is required for uninstalling the driver from the system.
ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.
Therefore, to ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:
PathToInstall controls where the driver is installed. Pass empty string (highly recommended) to automatically install the driver to the appropriate Windows system directory.
Flags specifies various installation options, and should contain zero or more of the following flags, OR'd together:
INSTALL_REMOVE_OLD_VERSIONS | 0x00000001 | Uninstall drivers and helper DLLs from previous component versions (e.g., 2017). |
INSTALL_KEEP_START_TYPE | 0x00000002 | Keep the driver's current start type setting in the registry.
If this flag is not set (default), the installation logic will reset the driver's start type setting in the Windows registry to the default value. Setting this flag causes the installation logic to preserve the current value, which may be necessary if the user (or the application itself) set it previously. |
INSTALL_OVERWRITE_SAME_VERSION | 0x00000004 | Install files when their version is the same as the version of already installed files.
If this flag is not set (default), the installation logic will overwrite the existing file only if the version number of the file being installed is larger than the version of the file being overwritten. Setting this flag causes the installation logic to overwrite the file even when it has the same version. |
This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.
This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.
Note: This method cannot be called within events.
OpenMemory Method (CBDirect Component)
Provides raw, read-only access to the system's physical memory.
Syntax
Remarks
This method returns a handle that provides raw, read-only access to the system's physical memory.
If the memory is opened successfully, this method returns a handle for it; otherwise, if returns INVALID_HANDLE_VALUE. The returned handle, if valid, must be closed using the Windows API's CloseHandle function when the application is finished with it.
The returned handle can be used with the Windows API's ReadFile function.
OpenMemoryAsStream Method (CBDirect Component)
Provides raw, read-only access to the system's physical memory as a stream.
Syntax
public CBFSDirectStream OpenMemoryAsStream();
Public Function OpenMemoryAsStream() As CBFSDirectStream
Remarks
This method returns a stream object that provides raw, read-only access to the system's physical memory.
If the memory is opened successfully, this method returns a stream object that provides access to its data; otherwise, it returns null.
OpenVolume Method (CBDirect Component)
Opens a volume.
Syntax
Remarks
This method should be used instead of the Windows API's CreateFile function to open the volume specified by VolumeName when an application needs to access it directly, bypassing the system's access control mechanisms.
If the volume is opened successfully, this method returns a volume handle for it; otherwise, if returns INVALID_HANDLE_VALUE. The returned handle, if valid, must be closed using the Windows API's CloseHandle function when the application is finished with it.
The VolumeName and DesiredAccess parameters correspond to the lpFileName and dwDesiredAccess parameters of the Windows API's CreateFile function (respectively). The value passed for VolumeName may be in WinAPI or NT-native format. Please refer to Microsoft's documentation for more information on how to set these parameters appropriately.
For the volume to be opened, it must be locked. As per MSDN, if the specified volume is a system volume or contains a page file, the [Lock] operation fails. The operation will also fail if there are open files on the drive.
When the ForceUnmount parameter is false, the component's driver returns an error when it cannot open the drive. When ForceUnmount is true, the driver will attempt to unmount a volume (which may not work as well for a system volume or a volume with a pagefile on it).
OpenVolumeAsStream Method (CBDirect Component)
Opens a volume as a stream.
Syntax
public CBFSDirectStream OpenVolumeAsStream(string volumeName, int desiredAccess, bool forceUnmount);
Public Function OpenVolumeAsStream(ByVal VolumeName As String, ByVal DesiredAccess As Integer, ByVal ForceUnmount As Boolean) As CBFSDirectStream
Remarks
This method should be used instead of the Windows API's CreateFile function to open the volume specified by VolumeName when an application needs to access it directly, bypassing the system's access control mechanisms.
If the volume is opened successfully, this method returns a stream object that provides access to its data; otherwise, it returns null.
The VolumeName and DesiredAccess parameters correspond to the lpFileName and dwDesiredAccess parameters of the Windows API's CreateFile function (respectively). The value passed for VolumeName may be in WinAPI or NT-native format. Please refer to Microsoft's documentation for more information on how to set these parameters appropriately.
For the volume to be opened, it must be locked. As per MSDN, if the specified volume is a system volume or contains a page file, the [Lock] operation fails. The operation will also fail if there are open files on the drive.
When the ForceUnmount parameter is false, the component's driver returns an error when it cannot open the drive. When ForceUnmount is true, the driver will attempt to unmount a volume (which may not work as well for a system volume or a volume with a pagefile on it).
ReadSectors Method (CBDirect Component)
Reads data from sectors of a disk.
Syntax
Remarks
This method reads data from sectors of the disk identified by VolumeHandle.
The value passed for VolumeHandle must be a volume handle obtained from the OpenVolume method; refer to its documentation for more information.
The StartingSector parameter specifies which sector to begin reading data from.
The SectorCount parameter specifies how many sectors of data to read.
The data from the disk is read into Buffer, which must be large enough to contain all of the requested data; i.e., SectorCount * SectorSize, where SectorSize is the value returned by GetSectorSize.
ShutdownSystem Method (CBDirect Component)
Shuts down or reboots the operating system.
Syntax
Remarks
This method shuts down or (if Reboot is true) reboots the operating system. If the appropriate privileges cannot be obtained, or if the InitiateSystemShutdown system call returns false, then this method will return false; otherwise, it returns true. This method can be used if the installation or uninstallation function requires the system to be rebooted in order to complete.
ShutdownPrompt, if non-empty, specifies a message that the OS should display to the user for Timeout seconds. If empty string is passed for ShutdownPrompt, no message is displayed and the Timeout parameter's value is ignored.
ForceCloseApps specifies whether the OS should forcefully close all applications. Please keep in mind that forceful closing of applications with unsaved data can lead to data loss.
Reboot specifies whether the OS should reboot (true) or just shut down (false).
This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.
Note: This method cannot be called within events.
Uninstall Method (CBDirect Component)
Uninstalls the component's system driver.
Syntax
Remarks
This method is used to uninstall the component's system driver. If the system must be rebooted to complete the uninstallation process, this method returns true; otherwise, it returns false.
Important: To upgrade the product's modules, use only the Install method. Previously installed versions of the modules should not be uninstalled first. Calling the Install method will upgrade the previously installed version.
Please refer to the Driver Installation topic for more information.
The same values must be passed for the CabFileName, ProductGUID, and InstalledPath parameters as were passed when Install was called; please refer to its documentation for more information.
Flags specifies which versions of the component's system driver should be uninstalled, and should be set by OR'ing together one or more of the following values:
UNINSTALL_VERSION_PREVIOUS | 0x00000001 | Uninstall modules from previous product versions. |
UNINSTALL_VERSION_CURRENT | 0x00000002 | Uninstall modules from the current product version. |
UNINSTALL_VERSION_ALL | 0x00000003 | Uninstall modules from all product versions. |
This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.
This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.
Note: This method cannot be called within events.
WriteSectors Method (CBDirect Component)
Writes data to sectors on a disk.
Syntax
Remarks
This method writes data to sectors of the disk identified by VolumeHandle.
The value passed for VolumeHandle must be a volume handle obtained from the OpenVolume method; refer to its documentation for more information.
The StartingSector parameter specifies which sector to begin writing data to.
The SectorCount parameter specifies the number of sectors to write data to.
The data to write to the disk must be passed in Buffer, whose size must be at least as large as the amount of data that is to be written; i.e., SectorCount * SectorSize, where SectorSize is the value returned by GetSectorSize.
Error Event (CBDirect Component)
Fires if an unhandled error occurs during an event.
Syntax
public event OnErrorHandler OnError; public delegate void OnErrorHandler(object sender, CbdirectErrorEventArgs e); public class CbdirectErrorEventArgs : EventArgs { public int ErrorCode { get; } public string Description { get; } }
Public Event OnError As OnErrorHandler Public Delegate Sub OnErrorHandler(sender As Object, e As CbdirectErrorEventArgs) Public Class CbdirectErrorEventArgs Inherits EventArgs Public ReadOnly Property ErrorCode As Integer Public ReadOnly Property Description As String End Class
Remarks
This event fires if an unhandled error occurs during another event. Developers can use this information to help track down unhandled errors in an application's event handlers.
CBFSDirectStream Type
Syntax
callback.CBFSDirect.CBFSDirectStream
Remarks
The CBFSDirectStream type is returned by some of the CBDirect component's methods. All stream types in CBFS Direct share a common API, inherited from the System.IO.Stream class, documented below.
Note that, for brevity, many of the properties and methods offered by System.IO.Stream are not documented here; please refer to Microsoft's documentation for more information.
Properties | |
CanRead |
Whether the stream supports reading.
|
CanSeek |
Whether the stream supports seeking.
|
CanWrite |
Whether the stream supports writing.
|
Length |
The length of the stream, in bytes.
|
Position |
Gets or sets the current position within the stream.
|
Methods | |
Dispose |
Releases all resources used by the stream.
public void Dispose(); Public Sub Dispose() |
Flush |
Forces all data held by the stream's buffers to be written out to storage.
public void Flush(); Public Sub Flush() |
Read |
Reads a sequence of bytes from the stream and advances the current position within the stream by the number of bytes read.
Buffer specifies the array of bytes to populate with data from the stream. Offset specifies the offset into Buffer at which to begin storing the data from the stream. Count specifies the number of bytes that should be read from the stream. Returns the total number of bytes read into Buffer. This may be less than Count if that many bytes are not currently available, or may be 0 if the end of the stream has been reached. |
Seek |
Sets the current position within the stream based on a particular point of origin.
public long Seek(long offset, System.IO.SeekOrigin origin); Public Function Seek(ByVal Offset As Long, ByVal Origin As System.IO.SeekOrigin) As Long Offset specifies the offset in the stream to seek to, relative to Origin. Returns the new position within the stream. |
SetLength |
Sets the length of the current stream.
Value specifies the desired length of the stream, in bytes. |
Write |
Writes a sequence of bytes to the stream and advances the current position within the stream by the number of bytes written.
Buffer specifies an array of bytes with data to write to the stream. Offset specifies the offset into Buffer at which to begin copying data from. Count specifies the number of bytes that should be written to the stream. |
Config Settings (CBDirect Component)
The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.Base Config Settings
BuildInfo: Information about the product's build.When queried, this setting will return a string containing information about the product's build. | |
LicenseInfo:
Information about the current license.When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information:
|
Trappable Errors (CBDirect Component)
Special Use Errors
21 ERROR_NOT_READY: Reported by the methods of the component if Initialize has not been called or did not succeed. | |
575 ERROR_APP_INIT_FAILURE: Reported by the methods of the component if Initialize has not been called or did not succeed. Differs from ERROR_NOT_READY (21) in that it indicates a specific situation in the internal code. | |
588 ERROR_FS_DRIVER_REQUIRED: Reported if the required system module was not correctly installed for the given ProductGUID. | |
614 ERROR_NO_CALLBACK_ACTIVE: Reported by any method that can only be called within event handlers if it is called outside an event handler. | |
1292 ERROR_IMPLEMENTATION_LIMIT: Reported when the timeout value provided is less than 3 seconds. | |
1314 ERROR_PRIVILEGE_NOT_HELD: Reported by any method that requires elevated permissions if it is called without such permissions. |