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

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.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

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.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

Tag Property (CBDirect Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetTag();
int SetTag(int64 lTag);

Unicode (Windows)
LONG64 GetTag();
INT SetTag(LONG64 lTag);

int64 cbfsdirect_cbdirect_gettag(void* lpObj);
int cbfsdirect_cbdirect_settag(void* lpObj, int64 lTag);

qint64 GetTag();
int SetTag(qint64 lTag);

Default Value

0

Remarks

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

Data Type

Long64

Config Method (CBDirect Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* cbfsdirect_cbdirect_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

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.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateFile Method (CBDirect Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 CreateFile(const char* lpszFileName, int iDesiredAccess, int iCreationDisposition, int iFlagsAndAttributes);

Unicode (Windows)
LONG64 CreateFile(LPCWSTR lpszFileName, INT iDesiredAccess, INT iCreationDisposition, INT iFlagsAndAttributes);

int64 cbfsdirect_cbdirect_createfile(void* lpObj, const char* lpszFileName, int iDesiredAccess, int iCreationDisposition, int iFlagsAndAttributes);

qint64 CreateFile(const QString& qsFileName, int iDesiredAccess, int iCreationDisposition, int iFlagsAndAttributes);

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.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateFileAsStream Method (CBDirect Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
CBFSDirectStream* CreateFileAsStream(const char* lpszFileName, int iDesiredAccess, int iCreationDisposition, int iFlagsAndAttributes);

Unicode (Windows)
CBFSDirectStream* CreateFileAsStream(LPCWSTR lpszFileName, INT iDesiredAccess, INT iCreationDisposition, INT iFlagsAndAttributes);

CBFSDirectStream* cbfsdirect_cbdirect_createfileasstream(void* lpObj, const char* lpszFileName, int iDesiredAccess, int iCreationDisposition, int iFlagsAndAttributes);

CBFSDirectStream* CreateFileAsStream(const QString& qsFileName, int iDesiredAccess, int iCreationDisposition, int iFlagsAndAttributes);

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.

Error Handling (C++)

This method returns a Stream; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DeleteFile Method (CBDirect Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DeleteFile(const char* lpszFileName, int bCloseOpenHandles);

Unicode (Windows)
INT DeleteFile(LPCWSTR lpszFileName, BOOL bCloseOpenHandles);

int cbfsdirect_cbdirect_deletefile(void* lpObj, const char* lpszFileName, int bCloseOpenHandles);

int DeleteFile(const QString& qsFileName, bool bCloseOpenHandles);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

GetDriverStatus Method (CBDirect Class)

Retrieves the status of the class's system driver.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetDriverStatus(const char* lpszProductGUID);

Unicode (Windows)
INT GetDriverStatus(LPCWSTR lpszProductGUID);

int cbfsdirect_cbdirect_getdriverstatus(void* lpObj, const char* lpszProductGUID);

int GetDriverStatus(const QString& qsProductGUID);

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:

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.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetDriverVersion Method (CBDirect Class)

Retrieves the version of the class's system driver.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetDriverVersion(const char* lpszProductGUID);

Unicode (Windows)
LONG64 GetDriverVersion(LPCWSTR lpszProductGUID);

int64 cbfsdirect_cbdirect_getdriverversion(void* lpObj, const char* lpszProductGUID);

qint64 GetDriverVersion(const QString& qsProductGUID);

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.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetSectorCount Method (CBDirect Class)

Returns the number of sectors on the specified disk device.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetSectorCount(int64 lVolumeHandle);

Unicode (Windows)
LONG64 GetSectorCount(LONG64 lVolumeHandle);

int64 cbfsdirect_cbdirect_getsectorcount(void* lpObj, int64 lVolumeHandle);

qint64 GetSectorCount(qint64 lVolumeHandle);

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.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetSectorSize Method (CBDirect Class)

Returns the sector size used by the specified disk device.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSectorSize(int64 lVolumeHandle);

Unicode (Windows)
INT GetSectorSize(LONG64 lVolumeHandle);

int cbfsdirect_cbdirect_getsectorsize(void* lpObj, int64 lVolumeHandle);

int GetSectorSize(qint64 lVolumeHandle);

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.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Initialize Method (CBDirect Class)

Initializes the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Initialize(const char* lpszProductGUID);

Unicode (Windows)
INT Initialize(LPCWSTR lpszProductGUID);

int cbfsdirect_cbdirect_initialize(void* lpObj, const char* lpszProductGUID);

int Initialize(const QString& qsProductGUID);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Install Method (CBDirect Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Install(const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszPathToInstall, int iFlags);

Unicode (Windows)
INT Install(LPCWSTR lpszCabFileName, LPCWSTR lpszProductGUID, LPCWSTR lpszPathToInstall, INT iFlags);

int cbfsdirect_cbdirect_install(void* lpObj, const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszPathToInstall, int iFlags);

bool Install(const QString& qsCabFileName, const QString& qsProductGUID, const QString& qsPathToInstall, int iFlags);

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:

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.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

OpenMemory Method (CBDirect Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 OpenMemory();

Unicode (Windows)
LONG64 OpenMemory();

int64 cbfsdirect_cbdirect_openmemory(void* lpObj);

qint64 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.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

OpenMemoryAsStream Method (CBDirect Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
CBFSDirectStream* OpenMemoryAsStream();

Unicode (Windows)
CBFSDirectStream* OpenMemoryAsStream();

CBFSDirectStream* cbfsdirect_cbdirect_openmemoryasstream(void* lpObj);

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.

Error Handling (C++)

This method returns a Stream; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

OpenVolume Method (CBDirect Class)

Opens a volume.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 OpenVolume(const char* lpszVolumeName, int iDesiredAccess, int bForceUnmount);

Unicode (Windows)
LONG64 OpenVolume(LPCWSTR lpszVolumeName, INT iDesiredAccess, BOOL bForceUnmount);

int64 cbfsdirect_cbdirect_openvolume(void* lpObj, const char* lpszVolumeName, int iDesiredAccess, int bForceUnmount);

qint64 OpenVolume(const QString& qsVolumeName, int iDesiredAccess, bool bForceUnmount);

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

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

OpenVolumeAsStream Method (CBDirect Class)

Opens a volume as a stream.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
CBFSDirectStream* OpenVolumeAsStream(const char* lpszVolumeName, int iDesiredAccess, int bForceUnmount);

Unicode (Windows)
CBFSDirectStream* OpenVolumeAsStream(LPCWSTR lpszVolumeName, INT iDesiredAccess, BOOL bForceUnmount);

CBFSDirectStream* cbfsdirect_cbdirect_openvolumeasstream(void* lpObj, const char* lpszVolumeName, int iDesiredAccess, int bForceUnmount);

CBFSDirectStream* OpenVolumeAsStream(const QString& qsVolumeName, int iDesiredAccess, bool bForceUnmount);

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

Error Handling (C++)

This method returns a Stream; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

ReadSectors Method (CBDirect Class)

Reads data from sectors of a disk.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ReadSectors(int64 lVolumeHandle, int64 lStartingSector, int iSectorCount, void* lpBuffer, int lenBuffer);

Unicode (Windows)
INT ReadSectors(LONG64 lVolumeHandle, LONG64 lStartingSector, INT iSectorCount, LPVOID lpBuffer, INT lenBuffer);

int cbfsdirect_cbdirect_readsectors(void* lpObj, int64 lVolumeHandle, int64 lStartingSector, int iSectorCount, void* lpBuffer, int lenBuffer);

int ReadSectors(qint64 lVolumeHandle, qint64 lStartingSector, int iSectorCount, void* qbaBuffer);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ShutdownSystem Method (CBDirect Class)

Shuts down or reboots the operating system.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ShutdownSystem(const char* lpszShutdownPrompt, int iTimeout, int bForceCloseApps, int bReboot);

Unicode (Windows)
INT ShutdownSystem(LPCWSTR lpszShutdownPrompt, INT iTimeout, BOOL bForceCloseApps, BOOL bReboot);

int cbfsdirect_cbdirect_shutdownsystem(void* lpObj, const char* lpszShutdownPrompt, int iTimeout, int bForceCloseApps, int bReboot);

bool ShutdownSystem(const QString& qsShutdownPrompt, int iTimeout, bool bForceCloseApps, bool bReboot);

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.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Uninstall Method (CBDirect Class)

Uninstalls the class's system driver.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Uninstall(const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszInstalledPath, int iFlags);

Unicode (Windows)
INT Uninstall(LPCWSTR lpszCabFileName, LPCWSTR lpszProductGUID, LPCWSTR lpszInstalledPath, INT iFlags);

int cbfsdirect_cbdirect_uninstall(void* lpObj, const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszInstalledPath, int iFlags);

bool Uninstall(const QString& qsCabFileName, const QString& qsProductGUID, const QString& qsInstalledPath, int iFlags);

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:

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.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

WriteSectors Method (CBDirect Class)

Writes data to sectors on a disk.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int WriteSectors(int64 lVolumeHandle, int64 lStartingSector, int iSectorCount, const char* lpBuffer, int lenBuffer);

Unicode (Windows)
INT WriteSectors(LONG64 lVolumeHandle, LONG64 lStartingSector, INT iSectorCount, LPCSTR lpBuffer, INT lenBuffer);

int cbfsdirect_cbdirect_writesectors(void* lpObj, int64 lVolumeHandle, int64 lStartingSector, int iSectorCount, const char* lpBuffer, int lenBuffer);

int WriteSectors(qint64 lVolumeHandle, qint64 lStartingSector, int iSectorCount, QByteArray qbaBuffer);

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 Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Error Event (CBDirect Class)

Fires if an unhandled error occurs during an event.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(CBDirectErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} CBDirectErrorEventParams;


Unicode (Windows)
virtual INT FireError(CBDirectErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} CBDirectErrorEventParams;

#define EID_CBDIRECT_ERROR 1

virtual INT CBFSDIRECT_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class CBDirectErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Error(CBDirectErrorEventParams *e);

// Or, subclass CBDirect and override this emitter function.
virtual int FireError(CBDirectErrorEventParams *e) {...}

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

CBFSDirectStream (declared in cbfsdirect.h)

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.

Properties
Length	Gets or sets the length of the stream, in bytes. int64 GetLength(); void SetLength(int64 length);
Position	Gets or sets the current position within the stream. int64 GetPosition(); void SetPosition(int64 position);
Methods
Close	Closes the stream, releasing all resources currently allocated for it. void Close(); This method is called automatically when a CBFSDirectStream object is deleted.
Flush	Forces all data held by the stream's buffers to be written out to storage. void Flush();
GetLastError	If the previous operation failed, returns the associated error message, if any. char* GetLastError();
GetLastErrorCode	If the previous operation failed, returns a non-zero error code; otherwise returns zero. int GetLastErrorCode(); This method will always return -1 after Close has been called.
Read	Reads a sequence of bytes from the stream and advances the current position within the stream by the number of bytes read. int Read(void* buffer, int count); Buffer specifies the buffer to populate with 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. int64 Seek(int64 offset, SeekOrigin origin); enum SeekOrigin { soFromBeginning = 0, soFromCurrent = 1, soFromEnd = 2 }; Offset specifies the offset in the stream to seek to, relative to Origin. SeekOrigin is an enum declared alongside 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. int Write(void* buffer, int count); Buffer specifies the buffer with data to write to the stream. Count specifies the number of bytes that should be written to the stream. Returns the total number of bytes written to the stream.

Config Settings (CBDirect Class)

Trappable Errors (CBDirect Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

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.