CBDirect Class

Properties   Methods   Events   Config Settings   Errors  

The CBDirect class provides applications with low-level, direct access to disks and memory in Windows.

Syntax

cbfsdirect.Cbdirect

Remarks

The CBDirect class is used to gain low-level, direct access to disks and memory in Windows. The class allows bypassing certain Windows access restrictions, even under limited user accounts.

Getting Started

All of the CBDirect class's methods are independent, and can be called immediately after creating an instance of the class.

Here's how to get up and running:

1. 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.
2. Call the class's methods as needed.
3. 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 class with short descriptions. Click on the links for further details.

Tag	Stores application-defined data specific to this instance of the class.

Method List

---

The following is the full list of the methods of the class 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 class's system driver.
GetDriverVersion	Retrieves the version of the class'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 class.
Install	Installs (or upgrades) the class'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 class'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 class 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 class 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 Class)

Stores application-defined data specific to this instance of the class.

Syntax

public long getTag();


public void setTag(long tag);

Default Value

0

Remarks

This property can be used to store data specific to a particular instance of the class.

Config Method (Cbdirect Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, 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 Class)

Creates or opens a file or directory by passing the request directly to the filesystem.

Syntax

public long createFile(String fileName, int desiredAccess, int creationDisposition, int flagsAndAttributes);

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 Class)

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);

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 Class)

Deletes a file by passing the request directly to the filesystem.

Syntax

public void deleteFile(String fileName, boolean closeOpenHandles);

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 Class)

Retrieves the status of the class's system driver.

Syntax

public int getDriverStatus(String productGUID);

Remarks

This method retrieves the status of the class'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 class 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 Class)

Retrieves the version of the class's system driver.

Syntax

public long getDriverVersion(String productGUID);

Remarks

This method retrieves the version of the class'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 class'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 class 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 Class)

Returns the number of sectors on the specified disk device.

Syntax

public long getSectorCount(long volumeHandle);

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 Class)

Returns the sector size used by the specified disk device.

Syntax

public int getSectorSize(long volumeHandle);

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 Class)

Initializes the class.

Syntax

public void initialize(String productGUID);

Remarks

This method initializes the class and must be called each time the application starts before attempting to call any of the class'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 Class)

Installs (or upgrades) the class's system driver.

Syntax

public boolean install(String cabFileName, String productGUID, String pathToInstall, int flags);

Remarks

This method is used to install or upgrade the class'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 class'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:

• Install
• Uninstall
• GetDriverStatus
• GetDriverVersion
• Initialize

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 class 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 class 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 Class)

Provides raw, read-only access to the system's physical memory.

Syntax

public long openMemory();

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 Class)

Provides raw, read-only access to the system's physical memory as a stream.

Syntax

public CBFSDirectStream openMemoryAsStream();

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 Class)

Opens a volume.

Syntax

public long openVolume(String volumeName, int desiredAccess, boolean forceUnmount);

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 class'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 Class)

Opens a volume as a stream.

Syntax

public CBFSDirectStream openVolumeAsStream(String volumeName, int desiredAccess, boolean forceUnmount);

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 class'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 Class)

Reads data from sectors of a disk.

Syntax

public void readSectors(long volumeHandle, long startingSector, int sectorCount, byte[] buffer);

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 Class)

Shuts down or reboots the operating system.

Syntax

public boolean shutdownSystem(String shutdownPrompt, int timeout, boolean forceCloseApps, boolean reboot);

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 class 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 Class)

Uninstalls the class's system driver.

Syntax

public boolean uninstall(String cabFileName, String productGUID, String installedPath, int flags);

Remarks

This method is used to uninstall the class'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 class'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 class 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 Class)

Writes data to sectors on a disk.

Syntax

public void writeSectors(long volumeHandle, long startingSector, int sectorCount, byte[] buffer);

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 Class)

Fires if an unhandled error occurs during an event.

Syntax

public class DefaultCbdirectEventListener implements CbdirectEventListener {
  ...
  public void error(CbdirectErrorEvent e) {}
  ...
}

public class CbdirectErrorEvent {
  public int errorCode;
  public String description;
}

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

cbfsdirect.CBFSDirectStream

Remarks

The CBFSDirectStream type is returned by some of the CBDirect class's methods. All stream types in CBFS Direct share a common API, documented below.

This type provides a custom streaming API with full read, write, and seek functionality; and implements Closable in order to be compatible with the try-with-resources pattern. To interact with a stream via conventional Java streaming APIs, use the GetInputStream and GetOutputStream methods to obtain an InputStream or OutputStream object.

Properties
Length	Gets or sets the length of the stream, in bytes. public long getLength(); public void setLength(long value);
Position	Gets or sets the current position within the stream. public long getPosition(); public void setPosition(long value);
Methods
Close	Closes the stream, releasing all resources currently allocated for it. public void close(); Closing a CBFSDirectStream instance also closes all Java stream objects that have been created using its GetInputStream and GetOutputStream methods.
Flush	Forces all data held by the stream's buffers to be written out to storage. public void flush();
GetInputStream	Creates a standard Java InputStream tied to the current CBFSDirectStream instance. public InputStream getInputStream(); When an InputStream obtained from this method is closed, the CBFSDirectStream instance that created it is also closed (which, as Close describes, causes all other Java stream objects tied to that CBFSDirectStream instance to be closed as well).
GetOutputStream	Creates a standard Java OutputStream tied to the current CBFSDirectStream instance. public OutputStream getOutputStream(); When an OutputStream obtained from this method is closed, the CBFSDirectStream instance that created it is also closed (which, as Close describes, causes all other Java stream objects tied to that CBFSDirectStream instance to be closed as well).
Read	Reads a sequence of bytes from the stream and advances the current position within the stream by the number of bytes read. public byte[] read(int count); Count specifies the number of bytes that should be read from the stream. Returns a byte array containing the data read from the stream. The length of the returned byte array 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, CBFSDirectStream.SeekOrigin origin); public enum SeekOrigin { FROM_BEGIN(0), FROM_CURRENT(1), FROM_END(2); } Offset specifies the offset in the stream to seek to, relative to Origin. SeekOrigin is an enum declared within the CBFSDirectStream class as shown above. Returns the new position within the stream.
Write	Writes a sequence of bytes to the stream and advances the current position within the stream by the number of bytes written. public int write(byte[] data); Data specifies the data to write to the stream. Returns the total number of bytes written to the stream.

Config Settings (Cbdirect Class)

The class 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 class, 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 class is using. It will return the following information: Product: The product the license is for. Product Key: The key the license was generated from. License Source: Where the license was found (e.g. RuntimeLicense, License File). License Type: The type of license installed (e.g. Royalty Free, Single Server).

Trappable Errors (Cbdirect Class)

Special Use Errors

	21   ERROR_NOT_READY: Reported by the methods of the class if Initialize has not been called or did not succeed.
	575   ERROR_APP_INIT_FAILURE: Reported by the methods of the class 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.