CBCache Class

Properties   Methods   Events   Config Settings   Errors  

The CBCache class allows applications to easily cache remote file data locally.

Syntax

CBCache

Remarks

The CBCache class provides a local file-caching implementation that helps applications easily cache the contents of files stored in some external storage, such as a cloud storage service. Once an application has informed the CBCache class of the external storage's file transfer capabilities, the hard work of reading data into and flushing data out of the cache is handled automatically.

Getting Started

Applications typically need only a single instance of the CBCache class, because it can handle caching and accessing multiple files at once in parallel. Each file in the cache is identified by its file Id, and all cached file data are stored in a single cache storage file, whose name and location are determined by the CacheFile and CacheDirectory properties, respectively.

In terms of application architecture, the CBCache class (or, more generally, the cache itself) should reside between application code that needs random access to files in the external storage, and the code that provides access to said external storage. The former makes use of the CBCache class's properties and methods, while the latter is "connected" through the class's ReadData and WriteData events.

Here's how to get up and running:

  1. Implement the ReadData and WriteData events so that they provide appropriate access to the external storage. The ReadData event is mandatory. The WriteData event is required only if the CBCache class is to be in charge of flushing changed data back to external storage. Refer to these events' documentation for more information about how to correctly implement them.
  2. "Describe" the reading, writing, and resizing capabilities of the external storage to the CBCache class by setting the ReadingCapabilities, WritingCapabilities, and ResizingCapabilities properties. This information is used by the CBCache class to formulate a strategy for interacting with the external storage through the events mentioned in step 1.
  3. Open the cache by setting the CacheDirectory and CacheFile properties, and then calling the OpenCache method.
  4. When the class opens an existing cache vault, it is recommended that applications use the EnumerateCachedFiles method to search for any Orphan Files (i.e., files that are not currently open have unflushed data). If any such files are found, applications may wish to open, flush, or delete them.
  5. To create or open a file in the cache (i.e., a cached file), call the FileOpen method.
  6. While a cached file is open, it can be read from or written to using the FileRead and FileWrite methods.

Property List


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

ActiveThis property describes whether the file cache is open.
AutoFlushThis property specifies whether automatic flushing is enabled.
CacheDirectoryThis property includes the directory in which the cache's storage file is located.
CacheFileThis property includes the name of the file cache.
CacheSizeLimitThis property includes the maximum size of the cache's storage file.
CompressedThis property specifies whether or not the cache's storage file should be compressed.
FlushAfterCloseDelayThis property includes the number of seconds to delay flushing after a file is closed.
FlushAfterSizeThis property includes the amount of data that must be changed for flushing to begin.
FlushAfterTimeThis property includes the inactivity timeout that must elapse for flushing to begin.
FlushPolicyThis property includes the file flushing strategy that the cache should use.
HasOrphansThis property notes whether or not the cache contains any orphan files.
MaxCachedFileSizeThis property includes the maximum amount of data that should be cached for any given file.
ModeThis property includes the mode in which the cache operates in regard to access to the external storage.
OfflineThis property specifies whether or not the cache works in Offline mode.
PurgeAfterCloseDelayThis property includes the number of seconds to delay purging for after a file is closed.
PurgeAfterTimeThis property includes the inactivity timeout that must elapse for purging to begin.
PurgePolicyThis property includes the file block purging strategy that the cache should use.
ReadBlockSizeThis property includes the block size to use when reading file data from external storage.
ReadingCapabilitiesThis property includes the reading capabilities supported by the external storage.
ResizingCapabilitiesThis property includes the file resizing capabilities supported by the external storage.
SerializationThis property specifies whether nonintersecting operations against the same file or cache should execute serially or in parallel.
StatsCacheSizeThis property contains the current size of the cache.
StatsCurrentFileIdThis property contains the file currently being read or written by the cache.
StatsCurrentOperationThis property contains the operation currently being performed by the cache.
StatsTotalDataThis property contains the total amount of data present in the cache.
StatsUnflushedDataThis property contains the amount of unflushed data present in the cache.
StatsUnflushedFilesThis property contains the number of unflushed files present in the cache.
TagThis property stores application-defined data specific to a particular instance of the class.
WriteBlockSizeThis property includes the block size to use when writing file data to external storage.
WritingCapabilitiesThis property includes the writing capabilities supported by the external storage.

Method List


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

CancelCleanupThis method cancels a background cleanup operation, if necessary.
CheckAndRepairThis method checks a cache vault's consistency and repairs it as necessary.
ClearThis method removes files from the cache.
CloseCacheThis method closes the cache.
CloseEnumerationThis method closes the given file enumeration.
ConfigSets or retrieves a configuration setting.
DeleteCacheThis method deletes the cache completely.
EnumerateCachedFilesThis method enumerates the files in the cache.
FileChangeIdThis method changes the Id of a cached file.
FileCloseThis method closes a cached file.
FileCloseExThis method closes a cached file, specifying flushing and purging behaviors explicitly.
FileDeleteThis method deletes a file from the cache.
FileExistsThis method checks if a file with the given Id is present in the cache.
FileFlushThis method flushes the specified file's modified blocks out to external storage.
FileGetPinnedThis method returns the pinned state of a cached file.
FileGetSizeThis method gets the "real size" of a cached file.
FileGetStatusThis method gets the status of a cached file.
FileOpenThis method opens the specified cached file, creating it if necessary.
FileOpenExThis method opens the specified cached file, creating it if necessary.
FilePurgeThis method purges unmodified data from the cache.
FileReadThis method reads the specified part of a cached file.
FileSetPinnedThis method sets the pinned state of a cached file.
FileSetSizeThis method sets the "real size" of a cached file.
FileSetSizeExThis method sets the "real size" of a cached file.
FileTagDeleteThis method deletes a file tag.
FileTagExistsThis method checks whether or not a file has a specific tag associated with it.
FileTagGetThis method retrieves the binary data held by a file tag attached to the specified cached file.
FileTagGetSizeThis method retrieves the size of a file tag attached to the specified cached file.
FileTagSetThis method attaches a file tag with binary data to the specified cached file.
FileTouchThis method touches a range of data in a cached file.
FileWriteThis method writes the specified part of a cached file.
GetNextEnumeratedFileThis method returns the next file in the list of enumeration results.
OpenCacheThis method opens the cache.
RefreshStatisticsThis method forces a refresh of the cache's statistics.
ResetErrorStateThis method resets any outstanding errors for a file or external storage.
StartCleanupThis method starts a background cleanup operation to remove unused files from the cache.

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.

BeforeFlushThis event fires to report the start of the asynchronous file flush procedure.
BeforePurgeThis event fires to report the start of the asynchronous file purge procedure.
EndCleanupThis event fires to report the beginning of the asynchronous cleanup procedure.
ErrorThis event fires if an unhandled error occurs during an event.
LogThis log reports events that occur in the class.
ProgressThis event fires to report the progress of an operation.
ReadDataThis event fires when the cache needs to read file data from external storage.
StartCleanupThis event fires to report the beginning of the asynchronous cleanup procedure.
StatusThis event fires to report the latest cache statistics.
WriteDataThis event fires when the cache needs to write file data to external storage.

Config Settings


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

BlockSizeThe size of the block, used to store the data.
JournalingModeSpecifies whether the main cache file uses journaling for increased data consistency.
LogLevelThe level of detail that is logged.
MaxReaderThreadsPerFileThe maximum number of reader threads to use to fire events.
StatsRefreshIntervalMinimum time period between cache statistics refreshes.
StoreDataInFilesSpecifies whether file data should be stored in the main cache file or in individual files.
BuildInfoInformation about the product's build.
LicenseInfoInformation about the current license.

Active Property (CBCache Class)

This property describes whether the file cache is open.

Syntax

ANSI (Cross Platform)
int GetActive();

Unicode (Windows)
BOOL GetActive();
int cbfsconnect_cbcache_getactive(void* lpObj);
bool GetActive();

Default Value

FALSE

Remarks

This property reflects whether the class has opened a file cache; it will be true once the OpenCache method has been called successfully.

This property is read-only and not available at design time.

Data Type

Boolean

AutoFlush Property (CBCache Class)

This property specifies whether automatic flushing is enabled.

Syntax

ANSI (Cross Platform)
int GetAutoFlush();
int SetAutoFlush(int bAutoFlush); Unicode (Windows) BOOL GetAutoFlush();
INT SetAutoFlush(BOOL bAutoFlush);
int cbfsconnect_cbcache_getautoflush(void* lpObj);
int cbfsconnect_cbcache_setautoflush(void* lpObj, int bAutoFlush);
bool GetAutoFlush();
int SetAutoFlush(bool bAutoFlush);

Default Value

TRUE

Remarks

This property specifies whether automatic flushing is enabled. When this property is enabled (default), automatic flushing will take place both according to the FlushPolicy setting, and when cached files are closed (after any delay specified by the FlushAfterCloseDelay property).

If this property is disabled, automatic flushing will never occur, regardless of the FlushPolicy setting; however, the FileFlush method can still be used to explicitly flush a cached file.

Typically, applications should disable this property only in cases in which they need to suspend background write operations for some reason (e.g., if connectivity with the external storage is temporarily lost).

Data Type

Boolean

CacheDirectory Property (CBCache Class)

This property includes the directory in which the cache's storage file is located.

Syntax

ANSI (Cross Platform)
char* GetCacheDirectory();
int SetCacheDirectory(const char* lpszCacheDirectory); Unicode (Windows) LPWSTR GetCacheDirectory();
INT SetCacheDirectory(LPCWSTR lpszCacheDirectory);
char* cbfsconnect_cbcache_getcachedirectory(void* lpObj);
int cbfsconnect_cbcache_setcachedirectory(void* lpObj, const char* lpszCacheDirectory);
QString GetCacheDirectory();
int SetCacheDirectory(QString qsCacheDirectory);

Default Value

""

Remarks

This property specifies the path of the directory in which the cache's storage file is located. The name of the cache's storage file is derived from the CacheFile property.

Note: This property cannot be changed when Active is true.

Data Type

String

CacheFile Property (CBCache Class)

This property includes the name of the file cache.

Syntax

ANSI (Cross Platform)
char* GetCacheFile();
int SetCacheFile(const char* lpszCacheFile); Unicode (Windows) LPWSTR GetCacheFile();
INT SetCacheFile(LPCWSTR lpszCacheFile);
char* cbfsconnect_cbcache_getcachefile(void* lpObj);
int cbfsconnect_cbcache_setcachefile(void* lpObj, const char* lpszCacheFile);
QString GetCacheFile();
int SetCacheFile(QString qsCacheFile);

Default Value

""

Remarks

This property specifies the name of the file cache. This name is used to create the cache's storage file in the directory specified by the CacheDirectory property.

Note: This property cannot be changed when Active is true.

Data Type

String

CacheSizeLimit Property (CBCache Class)

This property includes the maximum size of the cache's storage file.

Syntax

ANSI (Cross Platform)
int GetCacheSizeLimit();
int SetCacheSizeLimit(int iCacheSizeLimit); Unicode (Windows) INT GetCacheSizeLimit();
INT SetCacheSizeLimit(INT iCacheSizeLimit);
int cbfsconnect_cbcache_getcachesizelimit(void* lpObj);
int cbfsconnect_cbcache_setcachesizelimit(void* lpObj, int iCacheSizeLimit);
int GetCacheSizeLimit();
int SetCacheSizeLimit(int iCacheSizeLimit);

Default Value

0

Remarks

This property specifies the maximum size, in megabytes, that the cache's storage file is allowed to grow to. If this limit is reached, the cache will initiate a background cleanup operation automatically, purging file data according to the PurgePolicy and shrinking the cache storage file afterward. By default, this property is set to 0, which means "no limit".

Note: Any purging and shrinking attempts caused by this property's value are made on a "best effort" basis, which can be affected by the following:

  • The amount of unflushed data present in the cache (as indicated by the Stats property): if it is greater than the specified size limit, the cache will not be able to purge said data or shrink its storage file until enough data have been flushed.
  • The PurgePolicy property: certain values can make it impossible for the cache to immediately perform the required purging.

Note: This property cannot be changed when Active is true.

Data Type

Integer

Compressed Property (CBCache Class)

This property specifies whether or not the cache's storage file should be compressed.

Syntax

ANSI (Cross Platform)
int GetCompressed();
int SetCompressed(int bCompressed); Unicode (Windows) BOOL GetCompressed();
INT SetCompressed(BOOL bCompressed);
int cbfsconnect_cbcache_getcompressed(void* lpObj);
int cbfsconnect_cbcache_setcompressed(void* lpObj, int bCompressed);
bool GetCompressed();
int SetCompressed(bool bCompressed);

Default Value

FALSE

Remarks

This property specifies whether or not the cache's storage file should be compressed.

If the StoreDataInFiles configuration setting is enabled, the Compressed property affects only the main cache storage file and not the files used to store individual files' data.

Note: This property cannot be changed when Active is true.

Data Type

Boolean

FlushAfterCloseDelay Property (CBCache Class)

This property includes the number of seconds to delay flushing after a file is closed.

Syntax

ANSI (Cross Platform)
int GetFlushAfterCloseDelay();
int SetFlushAfterCloseDelay(int iFlushAfterCloseDelay); Unicode (Windows) INT GetFlushAfterCloseDelay();
INT SetFlushAfterCloseDelay(INT iFlushAfterCloseDelay);
int cbfsconnect_cbcache_getflushafterclosedelay(void* lpObj);
int cbfsconnect_cbcache_setflushafterclosedelay(void* lpObj, int iFlushAfterCloseDelay);
int GetFlushAfterCloseDelay();
int SetFlushAfterCloseDelay(int iFlushAfterCloseDelay);

Default Value

30

Remarks

This property specifies the number of seconds that flushing will be delayed after a file with unflushed blocks is closed. A value of 0 will cause such files to be flushed immediately upon close.

Flush-after-close delays are intended to prevent excessive flushing operations in cases in which a file is opened, written to, and closed many times in succession within the delay period.

Note: This property cannot be changed when Active is true.

Data Type

Integer

FlushAfterSize Property (CBCache Class)

This property includes the amount of data that must be changed for flushing to begin.

Syntax

ANSI (Cross Platform)
int GetFlushAfterSize();
int SetFlushAfterSize(int iFlushAfterSize); Unicode (Windows) INT GetFlushAfterSize();
INT SetFlushAfterSize(INT iFlushAfterSize);
int cbfsconnect_cbcache_getflushaftersize(void* lpObj);
int cbfsconnect_cbcache_setflushaftersize(void* lpObj, int iFlushAfterSize);
int GetFlushAfterSize();
int SetFlushAfterSize(int iFlushAfterSize);

Default Value

1

Remarks

When the FlushPolicy property is set to fpSize, fpSizeOrTime, or fpSizeAndTime, this property specifies how many megabytes of a file's data must be changed for flushing to begin.

Changed data thresholds are intended to prevent excessive flushing in cases in which data are written to the same range of a file many times in succession.

Note: This property cannot be changed when Active is true.

Data Type

Integer

FlushAfterTime Property (CBCache Class)

This property includes the inactivity timeout that must elapse for flushing to begin.

Syntax

ANSI (Cross Platform)
int GetFlushAfterTime();
int SetFlushAfterTime(int iFlushAfterTime); Unicode (Windows) INT GetFlushAfterTime();
INT SetFlushAfterTime(INT iFlushAfterTime);
int cbfsconnect_cbcache_getflushaftertime(void* lpObj);
int cbfsconnect_cbcache_setflushaftertime(void* lpObj, int iFlushAfterTime);
int GetFlushAfterTime();
int SetFlushAfterTime(int iFlushAfterTime);

Default Value

30

Remarks

When the FlushPolicy property is set to fpTime, fpSizeOrTime, or fpSizeAndTime, this property specifies how many seconds of inactivity (i.e., time with no writes) must elapse for a file before flushing can begin.

Inactivity delays are intended to prevent excessive flushing in cases in which data are written to a file many times in succession within the inactivity period.

Note: This property cannot be changed when Active is true.

Data Type

Integer

FlushPolicy Property (CBCache Class)

This property includes the file flushing strategy that the cache should use.

Syntax

ANSI (Cross Platform)
int GetFlushPolicy();
int SetFlushPolicy(int iFlushPolicy); Unicode (Windows) INT GetFlushPolicy();
INT SetFlushPolicy(INT iFlushPolicy);

Possible Values

FP_NONE(0), 
FP_SIZE(1),
FP_TIME(2),
FP_SIZE_OR_TIME(3),
FP_SIZE_AND_TIME(4)
int cbfsconnect_cbcache_getflushpolicy(void* lpObj);
int cbfsconnect_cbcache_setflushpolicy(void* lpObj, int iFlushPolicy);
int GetFlushPolicy();
int SetFlushPolicy(int iFlushPolicy);

Default Value

2

Remarks

This property specifies the strategy that the cache should use for flushing-changed file data of the opened file out to external storage. It must be set to one of the following values:

fpNone (0) No automatic flushing. Use this setting to have the file written only after it is closed. Use the FlushAfterCloseDelay property to control the delay between file closing and writing of file data.
fpSize (1) Flush a file when the amount of changed data exceeds a certain limit. The FlushAfterSize property specifies the size limit.
fpTime (2) (default) Flush a file when it has not been written to for a certain amount of time. The FlushAfterTime property specifies the time limit.
fpSizeOrTime (3) Flush a file when the amount of changed data exceeds a certain limit OR when it has not been written to for a certain amount of time. The FlushAfterSize and FlushAfterTime properties specify the size and time limits, respectively.
fpSizeAndTime (4) Flush a file when the amount of changed data exceeds a certain limit AND when it has not been written to for a certain amount of time. The FlushAfterSize and FlushAfterTime properties specify the size and time limits, respectively.

Note: This property cannot be changed when Active is true.

Data Type

Integer

HasOrphans Property (CBCache Class)

This property notes whether or not the cache contains any orphan files.

Syntax

ANSI (Cross Platform)
int GetHasOrphans();

Unicode (Windows)
BOOL GetHasOrphans();
int cbfsconnect_cbcache_gethasorphans(void* lpObj);
bool GetHasOrphans();

Default Value

FALSE

Remarks

This property specifies whether or not the cache contains any Orphan Files, returning true if so or false otherwise.

Note: This property returns a valid value only when Active is true.

This property is read-only and not available at design time.

Data Type

Boolean

MaxCachedFileSize Property (CBCache Class)

This property includes the maximum amount of data that should be cached for any given file.

Syntax

ANSI (Cross Platform)
int64 GetMaxCachedFileSize();
int SetMaxCachedFileSize(int64 lMaxCachedFileSize); Unicode (Windows) LONG64 GetMaxCachedFileSize();
INT SetMaxCachedFileSize(LONG64 lMaxCachedFileSize);
int64 cbfsconnect_cbcache_getmaxcachedfilesize(void* lpObj);
int cbfsconnect_cbcache_setmaxcachedfilesize(void* lpObj, int64 lMaxCachedFileSize);
qint64 GetMaxCachedFileSize();
int SetMaxCachedFileSize(qint64 lMaxCachedFileSize);

Default Value

0

Remarks

This property specifies the maximum amount of data, in bytes, that the cache should store for any given file. When a file reaches this limit, the cache will start dropping its least-recently accessed unchanged blocks.

The default value of 0 means "no limit", causing all file data to be kept in the cache at least until the file is closed (and possibly longer, depending on how the cache is configured).

Data Type

Long64

Mode Property (CBCache Class)

This property includes the mode in which the cache operates in regard to access to the external storage.

Syntax

ANSI (Cross Platform)
int GetMode();
int SetMode(int iMode); Unicode (Windows) INT GetMode();
INT SetMode(INT iMode);

Possible Values

CM_NORMAL(0), 
CM_SHADOW(1),
CM_PASSTHROUGH(2),
CM_MIRROR(3)
int cbfsconnect_cbcache_getmode(void* lpObj);
int cbfsconnect_cbcache_setmode(void* lpObj, int iMode);
int GetMode();
int SetMode(int iMode);

Default Value

0

Remarks

This property specifies the mode of operations that the cache should use for reading and writing the data. Possible values are as follows:

cmNormal (0) (default) Regular cached reading and writing are performed.
cmShadow (1) The cache reads the data from the external storage, but it does not do any writes.
cmPassthrough (2) The cache does not store file data locally and serves read/write requests by firing the corresponding events synchronously.
cmMirror (3) Reading is performed as in the Normal mode. Writing is done synchronously both to the local cache and to the external storage. The FileWrite method returns when the data are flushed to the external storage or if the error occurs during this operation.

Note: This property cannot be changed when Active is true.

Data Type

Integer

Offline Property (CBCache Class)

This property specifies whether or not the cache works in Offline mode.

Syntax

ANSI (Cross Platform)
int GetOffline();
int SetOffline(int bOffline); Unicode (Windows) BOOL GetOffline();
INT SetOffline(BOOL bOffline);
int cbfsconnect_cbcache_getoffline(void* lpObj);
int cbfsconnect_cbcache_setoffline(void* lpObj, int bOffline);
bool GetOffline();
int SetOffline(bool bOffline);

Default Value

FALSE

Remarks

This property specifies whether or not the cache works in Offline mode. When in this mode, no events are fired to read or write data from/to the external storage.

This property is different from AutoFlush: AutoFlush prevents automated flushing but allows reading and manual flushing, whereas the Offline mode prevents both reading and writing, which means that application-initiated flushing does nothing as well.

Data Type

Boolean

PurgeAfterCloseDelay Property (CBCache Class)

This property includes the number of seconds to delay purging for after a file is closed.

Syntax

ANSI (Cross Platform)
int GetPurgeAfterCloseDelay();
int SetPurgeAfterCloseDelay(int iPurgeAfterCloseDelay); Unicode (Windows) INT GetPurgeAfterCloseDelay();
INT SetPurgeAfterCloseDelay(INT iPurgeAfterCloseDelay);
int cbfsconnect_cbcache_getpurgeafterclosedelay(void* lpObj);
int cbfsconnect_cbcache_setpurgeafterclosedelay(void* lpObj, int iPurgeAfterCloseDelay);
int GetPurgeAfterCloseDelay();
int SetPurgeAfterCloseDelay(int iPurgeAfterCloseDelay);

Default Value

30

Remarks

When the PurgePolicy property is set to ppFileClose, this property specifies the number of seconds that purging will be delayed for after a file without any unflushed blocks is closed. A value of 0 will cause such files to be purged immediately on close.

Purge-after-close delays are intended to prevent excessive fetching of data from external storage in cases in which a file is opened and closed many times in succession within the delay period.

Note: This property cannot be changed when Active is true.

Data Type

Integer

PurgeAfterTime Property (CBCache Class)

This property includes the inactivity timeout that must elapse for purging to begin.

Syntax

ANSI (Cross Platform)
int GetPurgeAfterTime();
int SetPurgeAfterTime(int iPurgeAfterTime); Unicode (Windows) INT GetPurgeAfterTime();
INT SetPurgeAfterTime(INT iPurgeAfterTime);
int cbfsconnect_cbcache_getpurgeaftertime(void* lpObj);
int cbfsconnect_cbcache_setpurgeaftertime(void* lpObj, int iPurgeAfterTime);
int GetPurgeAfterTime();
int SetPurgeAfterTime(int iPurgeAfterTime);

Default Value

2592000

Remarks

When the PurgePolicy property is set to ppTime, this property specifies the number of seconds that a file data block must remain unchanged for before it is purged from the cache. Because the cache is intended for longer-time data storage and all data survive cache restart, the default value is 30 days.

Note: This property cannot be changed when Active is true.

Data Type

Integer

PurgePolicy Property (CBCache Class)

This property includes the file block purging strategy that the cache should use.

Syntax

ANSI (Cross Platform)
int GetPurgePolicy();
int SetPurgePolicy(int iPurgePolicy); Unicode (Windows) INT GetPurgePolicy();
INT SetPurgePolicy(INT iPurgePolicy);

Possible Values

PP_NONE(0), 
PP_FILE_CLOSE(1),
PP_CACHE_CLOSE(2),
PP_TIME(3)
int cbfsconnect_cbcache_getpurgepolicy(void* lpObj);
int cbfsconnect_cbcache_setpurgepolicy(void* lpObj, int iPurgePolicy);
int GetPurgePolicy();
int SetPurgePolicy(int iPurgePolicy);

Default Value

3

Remarks

This property specifies the strategy that the cache should use for purging unmodified blocks of file data from the cache. It must be set to one of the following values:

ppNone (0) (default) No automatic purging. Use the StartCleanup method to perform cache cleanup.
ppFileClose (1) Purge files as they are closed (after a delay). The PurgeAfterCloseDelay property specifies the delay interval.
ppCacheClose (2) Purge files when the cache is closed (without a delay).
ppTime (3) Purge files when they have not been accessed for a certain time. The PurgeAfterTime property specifies the time a file must not be accessed for it to be purged.

Note: This property cannot be changed when Active is true.

Data Type

Integer

ReadBlockSize Property (CBCache Class)

This property includes the block size to use when reading file data from external storage.

Syntax

ANSI (Cross Platform)
int GetReadBlockSize();
int SetReadBlockSize(int iReadBlockSize); Unicode (Windows) INT GetReadBlockSize();
INT SetReadBlockSize(INT iReadBlockSize);
int cbfsconnect_cbcache_getreadblocksize(void* lpObj);
int cbfsconnect_cbcache_setreadblocksize(void* lpObj, int iReadBlockSize);
int GetReadBlockSize();
int SetReadBlockSize(int iReadBlockSize);

Default Value

1048576

Remarks

This property specifies the block size, in bytes, that the class should use when reading data from external storage through the ReadData event.

Note: In some cases (e.g., when reading the last part of a file), the amount of requested data may be less than the value specified by this property.

Applications should always set this property to a reasonable value (or use the default value), even if the ReadingCapabilities property specifies that the external storage supports only whole-file reading.

This property may be overridden by the corresponding parameter of the FileOpen and FileSetSize methods.

Changing this property causes the BlockSize configuration setting's value to be recalculated.

Note: This property cannot be changed when Active is true.

Data Type

Integer

ReadingCapabilities Property (CBCache Class)

This property includes the reading capabilities supported by the external storage.

Syntax

ANSI (Cross Platform)
int GetReadingCapabilities();
int SetReadingCapabilities(int iReadingCapabilities); Unicode (Windows) INT GetReadingCapabilities();
INT SetReadingCapabilities(INT iReadingCapabilities);
int cbfsconnect_cbcache_getreadingcapabilities(void* lpObj);
int cbfsconnect_cbcache_setreadingcapabilities(void* lpObj, int iReadingCapabilities);
int GetReadingCapabilities();
int SetReadingCapabilities(int iReadingCapabilities);

Default Value

1048

Remarks

This property specifies any and all behaviors of the external storage that are relevant when reading data from it. The class will automatically alter its behavior based on this property's "description" of how the external storage is able to provide file data.

This property should be set by ORing together zero or more of the flags defined in the following. These flags are grouped by name to specify the operations to which they apply.

Flag Group Description
Position Flags with POS in the name describe where read and writes can occur from.
Size Flags with SIZE in the name describe the sizes of read and writes the external data source supports.
Write Flags with WRITE in the name describe flags that are specific to write operations.
Supplemental Flags with SUPPL in the name describe flags that are used to further specify the expectations of the external data source.

Reading and Writing Capability Flags (Position Related)

RWCAP_POS_SEQUENTIAL_FROM_BOF0x00000001No random access allowed; read/write operations must start at the beginning of a file.

When this flag is used in writing capabilities, the class can initiate reading of missing data before writing the changes to build the complete dataset, which is required for correct write operations.

RWCAP_POS_BLOCK_MULTIPLE0x00000004Reading/writing is possible at positions that are multiple of the corresponding block size.

The read and write block sizes are specified by the ReadBlockSize and WriteBlockSize properties . When this flag is used in writing capabilities, the class can initiate reading of missing data before writing the changes to build the complete dataset, which is required for correct write operations.

RWCAP_POS_RANDOM0x00000008Reading/writing is possible at any position.

When this flag is used, other flags can still alter the positions at which reading/writing are possible.

RWCAP_POS_SUPPL_ONLY_WITHIN_FILE0x00000010File position must remain in the range: 0 <= FilePos < FileSize

Reading and Writing Capability Flags (Size Related)

RWCAP_SIZE_WHOLE_FILE0x00000100Only whole-file reads/writes are possible; partial reads/writes are not supported.

Note:

  • The ReadBlockSize and WriteBlockSize properties should still be set to reasonable values when using this flag.
  • Use one of the other RWCAP_SIZE_* flags instead of this one if the external storage supports reading subsets of the file.
When this flag is used in writing capabilities, the class can initiate reading of missing data before writing the changes to build the complete dataset, which is required for correct write operations.

RWCAP_SIZE_FIXED_BLOCKS_WITH_TAIL0x00000200Reads/writes must be done in blocks of a fixed size, except for the last block, which may be of any size.

When this flag is used in writing capabilities, the class can initiate reading of missing data before writing the changes to build the complete dataset, which is required for correct write operations.

RWCAP_SIZE_FIXED_BLOCKS_NO_TAIL0x00000400Reads/writes must be done in blocks of a fixed size, including the last block.

Note: Real file sizes, if needed, must be stored elsewhere when using the cache with an external storage medium that has this characteristic.

When this flag is used in writing capabilities, the class can initiate reading of missing data before writing the changes to build the complete dataset, which is required for correct write operations.

RWCAP_SIZE_ANY0x00000800Reads/writes may be done in blocks of any size.

Reading and Writing Capability Flags (Write Related)

RWCAP_WRITE_APPEND_ONLY0x00000002Append only; write operations must start at the end of a file.

To overwrite a file, it must first be truncated, and then written to. (Truncation behavior is defined by the corresponding flags.)

RWCAP_WRITE_SUPPL_NOT_BEYOND_EOF0x00000020File position remain in the range: 0 <= FilePos <= FileSize

When writing, appending to the end of the file is supported, but writing at positions past the end of the file is not.

RWCAP_WRITE_TRUNCATES_FILE0x00001000When writes occur, the last data written becomes the new end of the file.

Any overwritten data, and any data previously present after the written range, are lost.

RWCAP_WRITE_KEEPS_FILESIZE0x00002000Normal writing behavior (i.e., writes do not alter a file's size, except possibly to expand it).

RWCAP_WRITE_NOT_BEYOND_EOF0x00004000Writes may not extend past the end of a file's current size (i.e., cannot cause a file to grow).

Applications may still adjust the file size beforehand.

Note: This property cannot be changed when Active is true.

Data Type

Integer

ResizingCapabilities Property (CBCache Class)

This property includes the file resizing capabilities supported by the external storage.

Syntax

ANSI (Cross Platform)
int GetResizingCapabilities();
int SetResizingCapabilities(int iResizingCapabilities); Unicode (Windows) INT GetResizingCapabilities();
INT SetResizingCapabilities(INT iResizingCapabilities);
int cbfsconnect_cbcache_getresizingcapabilities(void* lpObj);
int cbfsconnect_cbcache_setresizingcapabilities(void* lpObj, int iResizingCapabilities);
int GetResizingCapabilities();
int SetResizingCapabilities(int iResizingCapabilities);

Default Value

51

Remarks

This property specifies any and all behaviors of the external storage that are relevant when resizing files. The class will automatically alter its behavior based on this property's "description" of how the external storage is able to resize files.

This property should be set by ORing together zero or more of the following flags:

RSZCAP_GROW_TO_ANY0x00000001Files can grow to any size.

RSZCAP_SHRINK_TO_ANY0x00000002Files can shrink to any size.

RSZCAP_GROW_TO_BLOCK_MULTIPLE0x00000004Files can grow to sizes that are a multiple of the block size.

RSZCAP_SHRINK_TO_BLOCK_MULTIPLE0x00000008Files can shrink to sizes that are a multiple of the block size.

RSZCAP_TRUNCATE_ON_OPEN0x00000010The external storage (or application itself) supports truncating a file when it is opened for writing.

RSZCAP_TRUNCATE_AT_ZERO0x00000020The external storage (or application itself) supports truncating a file to zero at any time (not just when it is being opened).

Note: This property cannot be changed when Active is true.

Data Type

Integer

Serialization Property (CBCache Class)

This property specifies whether nonintersecting operations against the same file or cache should execute serially or in parallel.

Syntax

ANSI (Cross Platform)
int GetSerialization();
int SetSerialization(int iSerialization); Unicode (Windows) INT GetSerialization();
INT SetSerialization(INT iSerialization);

Possible Values

SM_NONE(0), 
SM_GLOBAL(1),
SM_PER_FILE_ALL_OPERATIONS(2),
SM_PER_FILE_READING_WRITING_CONCURRENT(3),
SM_PER_FILE_READING_CONCURRENT(4)
int cbfsconnect_cbcache_getserialization(void* lpObj);
int cbfsconnect_cbcache_setserialization(void* lpObj, int iSerialization);
int GetSerialization();
int SetSerialization(int iSerialization);

Default Value

3

Remarks

This property specifies whether the class should force nonintersecting operations against a single file or whole cache to execute serially, or allow them to execute in parallel.

smNone (0) "No serialization", the component does not serialize anything and leaves this task to the user. The same as smPerFileReadingWritingConcurrent serialization mode.
smGlobal (1) "Global", all events are serialized; it is assumed that the user has one instance of code (e.g., class, component) that is capable of handling one request at a time.
smPerFileAllOperations (2) "Per-file, all operations", all operations on a single file are serialized; however, operations with different files may be concurrent.
smPerFileReadingWritingConcurrent (3)(default)"Per-file, reading and writing concurrent", reading and writing to a single file may be concurrent, but access to different ranges is serialized.
smPerFileReadingConcurrent (4) "Per-file, reading concurrent", reading of different ranges of the same file may be concurrent, while writing of different blocks of the file will be serialized.

Note: This property cannot be changed when Active is true.

Data Type

Integer

StatsCacheSize Property (CBCache Class)

This property contains the current size of the cache.

Syntax

ANSI (Cross Platform)
int64 GetStatsCacheSize();

Unicode (Windows)
LONG64 GetStatsCacheSize();
int64 cbfsconnect_cbcache_getstatscachesize(void* lpObj);
qint64 GetStatsCacheSize();

Default Value

0

Remarks

This property contains the current size of the cache.

This property reflects the current size, in bytes, of the file cache.

Properties related to cache statistics are refreshed periodically based on the interval specified by the StatsRefreshInterval configuration setting. Applications that need fresher data can either decrease the update refresh, or call the RefreshStatistics method to force an immediate refresh.

Note: This property returns a valid value only when Active is true.

This property is read-only and not available at design time.

Data Type

Long64

StatsCurrentFileId Property (CBCache Class)

This property contains the file currently being read or written by the cache.

Syntax

ANSI (Cross Platform)
char* GetStatsCurrentFileId();

Unicode (Windows)
LPWSTR GetStatsCurrentFileId();
char* cbfsconnect_cbcache_getstatscurrentfileid(void* lpObj);
QString GetStatsCurrentFileId();

Default Value

""

Remarks

This property contains the file currently being read or written by the cache.

When StatsCurrentOperation is CACHE_OP_READ or CACHE_OP_WRITE, this property will reflect the Id of the file being read or written. Otherwise, it will return an empty string.

Properties related to cache statistics are refreshed periodically based on the interval specified by the StatsRefreshInterval configuration setting. Applications that need fresher data can either decrease the update refresh, or call the RefreshStatistics method to force an immediate refresh.

Note: This property returns a valid value only when Active is true.

This property is read-only and not available at design time.

Data Type

String

StatsCurrentOperation Property (CBCache Class)

This property contains the operation currently being performed by the cache.

Syntax

ANSI (Cross Platform)
int GetStatsCurrentOperation();

Unicode (Windows)
INT GetStatsCurrentOperation();
int cbfsconnect_cbcache_getstatscurrentoperation(void* lpObj);
int GetStatsCurrentOperation();

Default Value

0

Remarks

This property contains the operation currently being performed by the cache.

This property reflects the operation currently being performed by the cache. It will be one of the following values:

CACHE_OP_IDLE0The cache is idle.

CACHE_OP_CLEANUP2Cache cleanup is being performed.

CACHE_OP_COMPACT3The cache's storage file is being compacted.

CACHE_OP_READ4The cache is reading some file's data.

CACHE_OP_WRITE5The cache is writing some file's data.

Properties related to cache statistics are refreshed periodically based on the interval specified by the StatsRefreshInterval configuration setting. Applications that need fresher data can either decrease the update refresh, or call the RefreshStatistics method to force an immediate refresh.

Note: This property returns a valid value only when Active is true.

This property is read-only and not available at design time.

Data Type

Integer

StatsTotalData Property (CBCache Class)

This property contains the total amount of data present in the cache.

Syntax

ANSI (Cross Platform)
int64 GetStatsTotalData();

Unicode (Windows)
LONG64 GetStatsTotalData();
int64 cbfsconnect_cbcache_getstatstotaldata(void* lpObj);
qint64 GetStatsTotalData();

Default Value

0

Remarks

This property contains the total amount of data present in the cache.

This property reflects the total amount of data, in bytes, currently present in the cache.

Properties related to cache statistics are refreshed periodically based on the interval specified by the StatsRefreshInterval configuration setting. Applications that need fresher data can either decrease the update refresh, or call the RefreshStatistics method to force an immediate refresh.

Note: This property returns a valid value only when Active is true.

This property is read-only and not available at design time.

Data Type

Long64

StatsUnflushedData Property (CBCache Class)

This property contains the amount of unflushed data present in the cache.

Syntax

ANSI (Cross Platform)
int64 GetStatsUnflushedData();

Unicode (Windows)
LONG64 GetStatsUnflushedData();
int64 cbfsconnect_cbcache_getstatsunflusheddata(void* lpObj);
qint64 GetStatsUnflushedData();

Default Value

0

Remarks

This property contains the amount of unflushed data present in the cache.

This property reflects the amount of unflushed or modified data, in bytes, currently present in the cache.

Properties related to cache statistics are refreshed periodically based on the interval specified by the StatsRefreshInterval configuration setting. Applications that need fresher data can either decrease the update refresh, or call the RefreshStatistics method to force an immediate refresh.

Note: This property returns a valid value only when Active is true.

This property is read-only and not available at design time.

Data Type

Long64

StatsUnflushedFiles Property (CBCache Class)

This property contains the number of unflushed files present in the cache.

Syntax

ANSI (Cross Platform)
int64 GetStatsUnflushedFiles();

Unicode (Windows)
LONG64 GetStatsUnflushedFiles();
int64 cbfsconnect_cbcache_getstatsunflushedfiles(void* lpObj);
qint64 GetStatsUnflushedFiles();

Default Value

0

Remarks

This property contains the number of unflushed files present in the cache.

This property reflects the number of files with unflushed or modified data currently present in the cache.

Properties related to cache statistics are refreshed periodically based on the interval specified by the StatsRefreshInterval configuration setting. Applications that need fresher data can either decrease the update refresh, or call the RefreshStatistics method to force an immediate refresh.

Note: This property returns a valid value only when Active is true.

This property is read-only and not available at design time.

Data Type

Long64

Tag Property (CBCache Class)

This property stores application-defined data specific to a particular instance of the class.

Syntax

ANSI (Cross Platform)
int64 GetTag();
int SetTag(int64 lTag); Unicode (Windows) LONG64 GetTag();
INT SetTag(LONG64 lTag);
int64 cbfsconnect_cbcache_gettag(void* lpObj);
int cbfsconnect_cbcache_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

WriteBlockSize Property (CBCache Class)

This property includes the block size to use when writing file data to external storage.

Syntax

ANSI (Cross Platform)
int GetWriteBlockSize();
int SetWriteBlockSize(int iWriteBlockSize); Unicode (Windows) INT GetWriteBlockSize();
INT SetWriteBlockSize(INT iWriteBlockSize);
int cbfsconnect_cbcache_getwriteblocksize(void* lpObj);
int cbfsconnect_cbcache_setwriteblocksize(void* lpObj, int iWriteBlockSize);
int GetWriteBlockSize();
int SetWriteBlockSize(int iWriteBlockSize);

Default Value

1048576

Remarks

This property specifies the block size, in bytes, that the class should use when writing data to external storage via the WriteData event.

Note: In some cases (e.g., when writing the last part of a file), the amount of data being written may be less than the value specified by this property.

Applications should always set this property to a reasonable value (or use the default value), even if the WritingCapabilities property specifies that the external storage only supports whole-file writing.

The property may be overridden by the corresponding parameter of the FileOpen and FileSetSize methods.

Changing this property causes the BlockSize configuration setting's value to be recalculated.

Note: This property cannot be changed when Active is true.

Data Type

Integer

WritingCapabilities Property (CBCache Class)

This property includes the writing capabilities supported by the external storage.

Syntax

ANSI (Cross Platform)
int GetWritingCapabilities();
int SetWritingCapabilities(int iWritingCapabilities); Unicode (Windows) INT GetWritingCapabilities();
INT SetWritingCapabilities(INT iWritingCapabilities);
int cbfsconnect_cbcache_getwritingcapabilities(void* lpObj);
int cbfsconnect_cbcache_setwritingcapabilities(void* lpObj, int iWritingCapabilities);
int GetWritingCapabilities();
int SetWritingCapabilities(int iWritingCapabilities);

Default Value

9256

Remarks

This property specifies any and all behaviors of the external storage that are relevant when writing data to it. The class will automatically alter its behavior based on this property's "description" of how the external storage is able to write file data.

This property should be set by ORing together zero or more of the flags defined as follows. The flags are grouped by name to specify the operations to which they apply.

Flag Group Description
Position Flags with POS in the name describe where read and writes can occur from.
Size Flags with SIZE in the name describe the sizes of read and writes the external data source supports.
Write Flags with WRITE in the name describe flags that are specific to write operations.
Supplemental Flags with SUPPL in the name describe flags that are used to further specify the expectations of the external data source.

Reading and Writing Capability Flags (Position Related)

RWCAP_POS_SEQUENTIAL_FROM_BOF0x00000001No random access allowed; read/write operations must start at the beginning of a file.

When this flag is used in writing capabilities, the class can initiate reading of missing data before writing the changes to build the complete dataset, which is required for correct write operations.

RWCAP_POS_BLOCK_MULTIPLE0x00000004Reading/writing is possible at positions that are multiple of the corresponding block size.

The read and write block sizes are specified by the ReadBlockSize and WriteBlockSize properties . When this flag is used in writing capabilities, the class can initiate reading of missing data before writing the changes to build the complete dataset, which is required for correct write operations.

RWCAP_POS_RANDOM0x00000008Reading/writing is possible at any position.

When this flag is used, other flags can still alter the positions at which reading/writing are possible.

RWCAP_POS_SUPPL_ONLY_WITHIN_FILE0x00000010File position must remain in the range: 0 <= FilePos < FileSize

Reading and Writing Capability Flags (Size Related)

RWCAP_SIZE_WHOLE_FILE0x00000100Only whole-file reads/writes are possible; partial reads/writes are not supported.

Note:

  • The ReadBlockSize and WriteBlockSize properties should still be set to reasonable values when using this flag.
  • Use one of the other RWCAP_SIZE_* flags instead of this one if the external storage supports reading subsets of the file.
When this flag is used in writing capabilities, the class can initiate reading of missing data before writing the changes to build the complete dataset, which is required for correct write operations.

RWCAP_SIZE_FIXED_BLOCKS_WITH_TAIL0x00000200Reads/writes must be done in blocks of a fixed size, except for the last block, which may be of any size.

When this flag is used in writing capabilities, the class can initiate reading of missing data before writing the changes to build the complete dataset, which is required for correct write operations.

RWCAP_SIZE_FIXED_BLOCKS_NO_TAIL0x00000400Reads/writes must be done in blocks of a fixed size, including the last block.

Note: Real file sizes, if needed, must be stored elsewhere when using the cache with an external storage medium that has this characteristic.

When this flag is used in writing capabilities, the class can initiate reading of missing data before writing the changes to build the complete dataset, which is required for correct write operations.

RWCAP_SIZE_ANY0x00000800Reads/writes may be done in blocks of any size.

Reading and Writing Capability Flags (Write Related)

RWCAP_WRITE_APPEND_ONLY0x00000002Append only; write operations must start at the end of a file.

To overwrite a file, it must first be truncated, and then written to. (Truncation behavior is defined by the corresponding flags.)

RWCAP_WRITE_SUPPL_NOT_BEYOND_EOF0x00000020File position remain in the range: 0 <= FilePos <= FileSize

When writing, appending to the end of the file is supported, but writing at positions past the end of the file is not.

RWCAP_WRITE_TRUNCATES_FILE0x00001000When writes occur, the last data written becomes the new end of the file.

Any overwritten data, and any data previously present after the written range, are lost.

RWCAP_WRITE_KEEPS_FILESIZE0x00002000Normal writing behavior (i.e., writes do not alter a file's size, except possibly to expand it).

RWCAP_WRITE_NOT_BEYOND_EOF0x00004000Writes may not extend past the end of a file's current size (i.e., cannot cause a file to grow).

Applications may still adjust the file size beforehand.

Note: This property cannot be changed when Active is true.

Data Type

Integer

CancelCleanup Method (CBCache Class)

This method cancels a background cleanup operation, if necessary.

Syntax

ANSI (Cross Platform)
int CancelCleanup();

Unicode (Windows)
INT CancelCleanup();
int cbfsconnect_cbcache_cancelcleanup(void* lpObj);
int CancelCleanup();

Remarks

This method cancels any cleanup operation currently being performed in the background. If no such operation is running, this method does nothing.

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

CheckAndRepair Method (CBCache Class)

This method checks a cache vault's consistency and repairs it as necessary.

Syntax

ANSI (Cross Platform)
int CheckAndRepair(const char* lpszEncryptionPassword, int iFlags);

Unicode (Windows)
INT CheckAndRepair(LPCWSTR lpszEncryptionPassword, INT iFlags);
int cbfsconnect_cbcache_checkandrepair(void* lpObj, const char* lpszEncryptionPassword, int iFlags);
int CheckAndRepair(const QString& qsEncryptionPassword, int iFlags);

Remarks

This method checks the consistency of a cache vault and attempts to repair it as necessary. Please refer to the Cache Corruption topic for more information.

Applications should call this method if a vault has become corrupted (if a cache operation fails with a ERROR_INTERNAL_VAULT_CORRUPTED error). Be sure to make a vault backup before calling this method, as its repair efforts may cause data loss in cases of severe corruption.

The Flags parameter is used to specify additional options and should be set by OR-ing together zero or more of the following flags:

CACHE_CHECK_NO_RECREATE_VAULT0x00000000If the vault is damaged beyond repair, report an error.

When this flag is used, the CheckAndRepair will return an error if the vault could not be repaired.

CACHE_CHECK_RECREATE_VAULT0x00000001If the vault is damaged beyond repair, recreate the vault automatically.

When this flag is used, the CheckAndRepair will delete the damaged vault and create a new one instead.

Note: This method cannot be called when Active is true, and it cannot be called within events.

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

Clear Method (CBCache Class)

This method removes files from the cache.

Syntax

ANSI (Cross Platform)
int Clear(int bRemoveOrphans, int bRemoveLocals);

Unicode (Windows)
INT Clear(BOOL bRemoveOrphans, BOOL bRemoveLocals);
int cbfsconnect_cbcache_clear(void* lpObj, int bRemoveOrphans, int bRemoveLocals);
int Clear(bool bRemoveOrphans, bool bRemoveLocals);

Remarks

This method removes all files from the cache that are fully flushed and currently closed. Depending on the value passed for RemoveOrphans and RemoveLocals, Orphan Files and/or Local Files also may be removed as well.

The operation is performed synchronously, so this method returns once all applicable files have been removed. During the operation, the Progress event will fire periodically to indicate progress.

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

CloseCache Method (CBCache Class)

This method closes the cache.

Syntax

ANSI (Cross Platform)
int CloseCache(int iFlushAction, int iPurgeAction);

Unicode (Windows)
INT CloseCache(INT iFlushAction, INT iPurgeAction);
int cbfsconnect_cbcache_closecache(void* lpObj, int iFlushAction, int iPurgeAction);
int CloseCache(int iFlushAction, int iPurgeAction);

Remarks

This method closes the cache, optionally performing file flushing and purging operations before doing so.

The FlushAction parameter specifies what kind of flushing to perform, if any. It must be one of the following values:

FLUSH_DELAYED0Flush as usual, taking into account any specified delay.

The FlushAfterCloseDelay property specifies the delay. Passing this value to FileClose or FileCloseEx will cause the method to return immediately; flushing is performed in the background. Passing this value to CloseCache has no effect (i.e., the cache is not flushed before being closed).

FLUSH_NONE1Do not flush anything.

FLUSH_IMMEDIATE2Flush immediately.

Passing this value to FileClose, FileCloseEx, and CloseCache will cause the method to return only after all flushing operations are complete.

The PurgeAction parameter specifies what kind of purging to perform, if any. It must be one of the following values:

PURGE_DELAYED0Purge as usual, taking into account any specified delay.

The PurgeAfterCloseDelay property specifies the delay. Passing this value to FileClose or FileCloseEx will cause the method to return immediately; purging is performed in the background. Passing this value to CloseCache has no effect; the cache is not purged before being closed.

PURGE_NONE1Do not purge anything.

PURGE_IMMEDIATE2Purge immediately.

Passing this value to FileClose, FileCloseEx, or CloseCache will cause the method to return only after all purging operations are complete.

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

CloseEnumeration Method (CBCache Class)

This method closes the given file enumeration.

Syntax

ANSI (Cross Platform)
int CloseEnumeration(int64 lEnumerationHandle);

Unicode (Windows)
INT CloseEnumeration(LONG64 lEnumerationHandle);
int cbfsconnect_cbcache_closeenumeration(void* lpObj, int64 lEnumerationHandle);
int CloseEnumeration(qint64 lEnumerationHandle);

Remarks

This method closes the file enumeration identified by EnumerationHandle and releases any associated resources.

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

Config Method (CBCache Class)

Sets or retrieves a configuration setting.

Syntax

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

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);
char* cbfsconnect_cbcache_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.

DeleteCache Method (CBCache Class)

This method deletes the cache completely.

Syntax

ANSI (Cross Platform)
int DeleteCache();

Unicode (Windows)
INT DeleteCache();
int cbfsconnect_cbcache_deletecache(void* lpObj);
int DeleteCache();

Remarks

This method deletes the cache specified by the CacheFile property completely, removing its storage file from the directory specified by the CacheDirectory property. If the cache is currently open, it is closed first.

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

EnumerateCachedFiles Method (CBCache Class)

This method enumerates the files in the cache.

Syntax

ANSI (Cross Platform)
int64 EnumerateCachedFiles(int iEnumerationMode);

Unicode (Windows)
LONG64 EnumerateCachedFiles(INT iEnumerationMode);
int64 cbfsconnect_cbcache_enumeratecachedfiles(void* lpObj, int iEnumerationMode);
qint64 EnumerateCachedFiles(int iEnumerationMode);

Remarks

This method initiates a enumeration operation for cached files that match the specified EnunmerationMode, which must be take of the following values:

ENUM_MODE_ALL0Enumerate all files.

ENUM_MODE_CHANGED1Enumerate files with changed blocks.

ENUM_MODE_UNCHANGED2Enumerate files with no changed blocks.

ENUM_MODE_LOCAL4Enumerate local files.

Refer to the Local Files topic for more information.

ENUM_MODE_ORPHAN8Enumerate orphan files.

Refer to the Orphan Files topic for more information.

ENUM_MODE_PINNED16Enumerate pinned files.

This method returns a handle that can be passed to the GetNextEnumeratedFile method to retrieve the results of the enumeration. If no matching files are found, -1 is returned instead.

When an application is finished enumerating files, it must call the CloseEnumeration method to release the associated resources.

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.

FileChangeId Method (CBCache Class)

This method changes the Id of a cached file.

Syntax

ANSI (Cross Platform)
int FileChangeId(const char* lpszFileId, const char* lpszNewFileId);

Unicode (Windows)
INT FileChangeId(LPCWSTR lpszFileId, LPCWSTR lpszNewFileId);
int cbfsconnect_cbcache_filechangeid(void* lpObj, const char* lpszFileId, const char* lpszNewFileId);
int FileChangeId(const QString& qsFileId, const QString& qsNewFileId);

Remarks

This method changes the Id of the cached file identified by FileId to NewFileId. Applications that use file paths as Ids may need to use this method if a path element is renamed.

This method fails with an error if no file with the specified FileId is present in the cache, or if another file is already present in the cache with NewFileId.

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

FileClose Method (CBCache Class)

This method closes a cached file.

Syntax

ANSI (Cross Platform)
int FileClose(const char* lpszFileId);

Unicode (Windows)
INT FileClose(LPCWSTR lpszFileId);
int cbfsconnect_cbcache_fileclose(void* lpObj, const char* lpszFileId);
int FileClose(const QString& qsFileId);

Remarks

This method closes the cached file identified by FileId, performing any of the flushing and/or purging operations specified by the class's other properties. (To override the configured flushing and purging behaviors, use the FileCloseEx method instead.)

This method returns immediately, and any flushing and/or purging operations are performed in the background.

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

FileCloseEx Method (CBCache Class)

This method closes a cached file, specifying flushing and purging behaviors explicitly.

Syntax

ANSI (Cross Platform)
int FileCloseEx(const char* lpszFileId, int iFlushAction, int iPurgeAction);

Unicode (Windows)
INT FileCloseEx(LPCWSTR lpszFileId, INT iFlushAction, INT iPurgeAction);
int cbfsconnect_cbcache_filecloseex(void* lpObj, const char* lpszFileId, int iFlushAction, int iPurgeAction);
int FileCloseEx(const QString& qsFileId, int iFlushAction, int iPurgeAction);

Remarks

This method closes the cached file identified by FileId, performing any flushing and/or purging operations specified by the FlushAction and PurgeAction parameters.

The FlushAction parameter must be passed by one of the following values:

FLUSH_DELAYED0Flush as usual, taking into account any specified delay.

The FlushAfterCloseDelay property specifies the delay. Passing this value to FileClose or FileCloseEx will cause the method to return immediately; flushing is performed in the background. Passing this value to CloseCache has no effect (i.e., the cache is not flushed before being closed).

FLUSH_NONE1Do not flush anything.

FLUSH_IMMEDIATE2Flush immediately.

Passing this value to FileClose, FileCloseEx, and CloseCache will cause the method to return only after all flushing operations are complete.

Note: Passing FLUSH_NONE will cause all background reading and writing threads for the file (if any) to be stopped.

The PurgeAction parameter must be passed by one of the following values:

PURGE_DELAYED0Purge as usual, taking into account any specified delay.

The PurgeAfterCloseDelay property specifies the delay. Passing this value to FileClose or FileCloseEx will cause the method to return immediately; purging is performed in the background. Passing this value to CloseCache has no effect; the cache is not purged before being closed.

PURGE_NONE1Do not purge anything.

PURGE_IMMEDIATE2Purge immediately.

Passing this value to FileClose, FileCloseEx, or CloseCache will cause the method to return only after all purging operations are complete.

This method returns immediately, and any flushing and/or purging operations are performed in the background.

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

FileDelete Method (CBCache Class)

This method deletes a file from the cache.

Syntax

ANSI (Cross Platform)
int FileDelete(const char* lpszFileId);

Unicode (Windows)
INT FileDelete(LPCWSTR lpszFileId);
int cbfsconnect_cbcache_filedelete(void* lpObj, const char* lpszFileId);
int FileDelete(const QString& qsFileId);

Remarks

This method deletes the cached file identified by FileId, removing all of its data from the cache. If the specified file is currently open, it is closed first.

Note: The specified file is not flushed to external storage before being deleted; any unflushed data will be lost.

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

FileExists Method (CBCache Class)

This method checks if a file with the given Id is present in the cache.

Syntax

ANSI (Cross Platform)
int FileExists(const char* lpszFileId);

Unicode (Windows)
INT FileExists(LPCWSTR lpszFileId);
int cbfsconnect_cbcache_fileexists(void* lpObj, const char* lpszFileId);
bool FileExists(const QString& qsFileId);

Remarks

This method checks to see whether a file with the specified FileId is present in the cache; returning true if so or false otherwise.

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.

FileFlush Method (CBCache Class)

This method flushes the specified file's modified blocks out to external storage.

Syntax

ANSI (Cross Platform)
int FileFlush(const char* lpszFileId, int iFlushMode, int iDelay, void* lpFileContext);

Unicode (Windows)
INT FileFlush(LPCWSTR lpszFileId, INT iFlushMode, INT iDelay, LPVOID lpFileContext);
int cbfsconnect_cbcache_fileflush(void* lpObj, const char* lpszFileId, int iFlushMode, int iDelay, void* lpFileContext);
int FileFlush(const QString& qsFileId, int iFlushMode, int iDelay, void* lpFileContext);

Remarks

This method flushes any modified data blocks for the file specified by FileId out to external storage via the WriteData event (and possibly, the ReadData event, if the cache is forced to retrieve data from external storage before writing it back). The FlushMode parameter specifies what kind of flushing should be performed. It must take one of the following values:

FLUSH_MODE_SYNC0Flush file data synchronously, blocking until finished.

FLUSH_MODE_ASYNC1Flush file data in the background; do not wait until the flush operation completes.

FLUSH_MODE_TEST2Check to see if file data exists and needs to be flushed, but do not actually flush anything.

The Delay parameter may be passed a non-zero number of seconds to delay the flushing operation.

The FileContext parameter may be passed any application-defined value. If the flushing operation causes the file to be opened, the specified value will be passed through to the WriteData and ReadData events' corresponding parameter. (If the file is already open, the value passed to FileOpen takes precedence).

This method will return one of the following values:

FLUSH_RESULT_NOTHING0The file has no data that need flushing.

FLUSH_RESULT_DIRTY1Data in the file need flushing, but no flush operation is running yet.

FLUSH_RESULT_RUNNING2Data in the file are in the process of being flushed.

FLUSH_RESULT_SUCCESS3Data in the file have been flushed successfully.

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.

FileGetPinned Method (CBCache Class)

This method returns the pinned state of a cached file.

Syntax

ANSI (Cross Platform)
int FileGetPinned(const char* lpszFileId);

Unicode (Windows)
INT FileGetPinned(LPCWSTR lpszFileId);
int cbfsconnect_cbcache_filegetpinned(void* lpObj, const char* lpszFileId);
bool FileGetPinned(const QString& qsFileId);

Remarks

This method indicates whether the cached file identified by FileId is pinned (or reports an error if no such file is present in the cache).

Pinned files are the files whose data are not purged automatically. If you need to remove the local data of a pinned file, use the FilePurge method.

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.

FileGetSize Method (CBCache Class)

This method gets the "real size" of a cached file.

Syntax

ANSI (Cross Platform)
int64 FileGetSize(const char* lpszFileId);

Unicode (Windows)
LONG64 FileGetSize(LPCWSTR lpszFileId);
int64 cbfsconnect_cbcache_filegetsize(void* lpObj, const char* lpszFileId);
qint64 FileGetSize(const QString& qsFileId);

Remarks

This method returns the application-reported File Sizes for the cached file identified by FileId (or reports an error if no such file is present in the cache).

Note: The size value returned by this method is the one previously set by the application through the FileOpen or FileSetSize method; it does not necessarily correspond to the actual amount of data present in the cache for the file.

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.

FileGetStatus Method (CBCache Class)

This method gets the status of a cached file.

Syntax

ANSI (Cross Platform)
int FileGetStatus(const char* lpszFileId, int iStatusKind);

Unicode (Windows)
INT FileGetStatus(LPCWSTR lpszFileId, INT iStatusKind);
int cbfsconnect_cbcache_filegetstatus(void* lpObj, const char* lpszFileId, int iStatusKind);
bool FileGetStatus(const QString& qsFileId, int iStatusKind);

Remarks

This method returns the status of the cached file identified by FileId (or reports an error if no such file is present in the cache). StatusKind must be one of the following:

FILE_STATUS_CHANGED1Retrieves the value of the Changed state of the file.

FILE_STATUS_UNCHANGED2Retrieves the value of the Unchanged state of the file.

FILE_STATUS_LOCAL3Retrieves the value that indicates whether the file is Local.

Refer to the Local Files topic for more information.

FILE_STATUS_ORPHAN4Retrieves the value that indicates whether the file is Orphan.

Refer to the Orphan Files topic for more information.

FILE_STATUS_OPEN5Retrieves the value of the Open state of the file.

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.

FileOpen Method (CBCache Class)

This method opens the specified cached file, creating it if necessary.

Syntax

ANSI (Cross Platform)
int FileOpen(const char* lpszFileId, int64 lRealFileSize, int64 lPrefetchSize, void* lpFileContext);

Unicode (Windows)
INT FileOpen(LPCWSTR lpszFileId, LONG64 lRealFileSize, LONG64 lPrefetchSize, LPVOID lpFileContext);
int cbfsconnect_cbcache_fileopen(void* lpObj, const char* lpszFileId, int64 lRealFileSize, int64 lPrefetchSize, void* lpFileContext);
int FileOpen(const QString& qsFileId, qint64 lRealFileSize, qint64 lPrefetchSize, void* lpFileContext);

Remarks

This method opens the cached file identified by FileId, creating it if necessary.

The RealFileSize parameter informs the cache of the File Sizes (in bytes) of the real file (i.e., the one in external storage); this size can be changed later using the FileSetSize method. For existing cached files, -1 may be passed to instruct the cache to use the previously set real file size instead.

The PrefetchSize parameter specifies how many bytes of data the cache should prefetch, from external storage, for the file via the ReadData event (which will fire on a background thread). Pass PREFETCH_ALL to prefetch the entire fire, or PREFETCH_NOTHING to prefetch none of it.

The FileContext may be passed to any application-defined value; this value will then be passed through to any ReadData and WriteData events fired for the file.

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

FileOpenEx Method (CBCache Class)

This method opens the specified cached file, creating it if necessary.

Syntax

ANSI (Cross Platform)
int FileOpenEx(const char* lpszFileId, int64 lRealFileSize, int bIsLocal, int iReadBlockSize, int iWriteBlockSize, int64 lPrefetchSize, void* lpFileContext);

Unicode (Windows)
INT FileOpenEx(LPCWSTR lpszFileId, LONG64 lRealFileSize, BOOL bIsLocal, INT iReadBlockSize, INT iWriteBlockSize, LONG64 lPrefetchSize, LPVOID lpFileContext);
int cbfsconnect_cbcache_fileopenex(void* lpObj, const char* lpszFileId, int64 lRealFileSize, int bIsLocal, int iReadBlockSize, int iWriteBlockSize, int64 lPrefetchSize, void* lpFileContext);
int FileOpenEx(const QString& qsFileId, qint64 lRealFileSize, bool bIsLocal, int iReadBlockSize, int iWriteBlockSize, qint64 lPrefetchSize, void* lpFileContext);

Remarks

This method opens the cached file identified by FileId, creating it if necessary.

The RealFileSize parameter informs the cache of the File Sizes (in bytes) of the real file (i.e., the one in external storage); this size can be changed later using the FileSetSize method. For existing cached files, -1 may be passed to instruct the cache to use the previously set real file size instead.

The IsLocal parameter specifies whether the file is a local to the cache and does not exist in external storage; refer to the Local Files topic for more information.

ReadBlockSize and WriteBlockSize parameters make it possible for the application to configure the size of the block for reading and writing, respectively, thus overriding the values specified in the ReadBlockSize and WriteBlockSize properties for a specific file. Set the parameter to 0 to make the class use the value from the corresponding property. The values of the parameters will be used when ReadingCapabilities or WritingCapabilities properties indicate that reading or writing should be performed in blocks of a specific size (or when the whole file should be read or written using sequential block operations).

The PrefetchSize parameter specifies how many bytes of data the cache should prefetch, from external storage, for the file through the ReadData event (which will fire on a background thread). Pass PREFETCH_ALL to prefetch the entire fire, or PREFETCH_NOTHING to prefetch none of it. This parameter is ignored if IsLocal is true.

The FileContext may be passed to any application-defined value; this value will then be passed through to any ReadData and WriteData events fired for the file.

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

FilePurge Method (CBCache Class)

This method purges unmodified data from the cache.

Syntax

ANSI (Cross Platform)
int FilePurge(const char* lpszFileId);

Unicode (Windows)
INT FilePurge(LPCWSTR lpszFileId);
int cbfsconnect_cbcache_filepurge(void* lpObj, const char* lpszFileId);
int FilePurge(const QString& qsFileId);

Remarks

This method removes unmodified data from the cache.

Use FilePurge with pinned files to free space or after the pinned attribute has been removed and you need to remove the data immediately.

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

FileRead Method (CBCache Class)

This method reads the specified part of a cached file.

Syntax

ANSI (Cross Platform)
int FileRead(const char* lpszFileId, int64 lPosition, void* lpBuffer, int lenBuffer, int iIndex, int iCount);

Unicode (Windows)
INT FileRead(LPCWSTR lpszFileId, LONG64 lPosition, LPVOID lpBuffer, INT lenBuffer, INT iIndex, INT iCount);
int cbfsconnect_cbcache_fileread(void* lpObj, const char* lpszFileId, int64 lPosition, void* lpBuffer, int lenBuffer, int iIndex, int iCount);
bool FileRead(const QString& qsFileId, qint64 lPosition, void* qbaBuffer, int iIndex, int iCount);

Remarks

This method reads data from the cached file identified by FileId into the specified Buffer. The cached file must be opened using FileOpen before it can be read from.

Count bytes of data will be read from the cached file, starting from the specified Position, into the given Buffer. The data are written to Buffer starting at the given Index.

The method returns false if any errors happened during reading and returns true if everything went fine.

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.

FileSetPinned Method (CBCache Class)

This method sets the pinned state of a cached file.

Syntax

ANSI (Cross Platform)
int FileSetPinned(const char* lpszFileId, int bPinned);

Unicode (Windows)
INT FileSetPinned(LPCWSTR lpszFileId, BOOL bPinned);
int cbfsconnect_cbcache_filesetpinned(void* lpObj, const char* lpszFileId, int bPinned);
int FileSetPinned(const QString& qsFileId, bool bPinned);

Remarks

This method specifies whether the cached file identified by FileId should be treated as pinned.

Pinned files are the files whose data are not purged automatically. If you need to remove the local data of a pinned file, use the FilePurge method.

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

FileSetSize Method (CBCache Class)

This method sets the "real size" of a cached file.

Syntax

ANSI (Cross Platform)
int FileSetSize(const char* lpszFileId, int64 lNewSize, int bFetchMissingData);

Unicode (Windows)
INT FileSetSize(LPCWSTR lpszFileId, LONG64 lNewSize, BOOL bFetchMissingData);
int cbfsconnect_cbcache_filesetsize(void* lpObj, const char* lpszFileId, int64 lNewSize, int bFetchMissingData);
int FileSetSize(const QString& qsFileId, qint64 lNewSize, bool bFetchMissingData);

Remarks

This method changes the "real size" of the cached file identified by FileId to the number of bytes specified by NewSize. The cached file must be opened using FileOpen before its real size can be changed.

ReadBlockSize and WriteBlockSize parameters make it possible for the application to configure the size of the block for reading and writing, respectively, thus overriding the values specified in the ReadBlockSize and WriteBlockSize properties for a specific file. Set the parameter to 0 to make the class use the value from the corresponding property. The values of the parameters will be used when ReadingCapabilities or WritingCapabilities properties indicate that reading or writing should be performed in blocks of a specific size (or when the whole file should be read or written using sequential block operations).

The FetchMissingData parameter controls how the cache initializes new file space in cases in which the file's real size is increased. If FetchMissingData is true, the new file space is filled with real data fetched from external storage. Otherwise, the new file space is marked as zero-filled (although no actual data writing occurs).

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

FileSetSizeEx Method (CBCache Class)

This method sets the "real size" of a cached file.

Syntax

ANSI (Cross Platform)
int FileSetSizeEx(const char* lpszFileId, int64 lNewSize, int iReadBlockSize, int iWriteBlockSize, int bFetchMissingData);

Unicode (Windows)
INT FileSetSizeEx(LPCWSTR lpszFileId, LONG64 lNewSize, INT iReadBlockSize, INT iWriteBlockSize, BOOL bFetchMissingData);
int cbfsconnect_cbcache_filesetsizeex(void* lpObj, const char* lpszFileId, int64 lNewSize, int iReadBlockSize, int iWriteBlockSize, int bFetchMissingData);
int FileSetSizeEx(const QString& qsFileId, qint64 lNewSize, int iReadBlockSize, int iWriteBlockSize, bool bFetchMissingData);

Remarks

This method changes the "real size" of the cached file identified by FileId to the number of bytes specified by NewSize. The cached file must be opened using FileOpen before its real size can be changed.

ReadBlockSize and WriteBlockSize parameters make it possible for the application to configure the size of the block for reading and writing, respectively, thus overriding the values specified in the ReadBlockSize and WriteBlockSize properties for a specific file. Set the parameter to 0 to make the class use the value from the corresponding property. The values of the parameters will be used when ReadingCapabilities or WritingCapabilities properties indicate that reading or writing should be performed in blocks of a specific size (or when the whole file should be read or written using sequential block operations).

The FetchMissingData parameter controls how the cache initializes new file space in cases in which the file's real size is increased. If FetchMissingData is true, the new file space is filled with real data fetched from external storage. Otherwise, the new file space is marked as zero-filled (although no actual data writing occurs).

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

FileTagDelete Method (CBCache Class)

This method deletes a file tag.

Syntax

ANSI (Cross Platform)
int FileTagDelete(const char* lpszFileId, int iTagId);

Unicode (Windows)
INT FileTagDelete(LPCWSTR lpszFileId, INT iTagId);
int cbfsconnect_cbcache_filetagdelete(void* lpObj, const char* lpszFileId, int iTagId);
int FileTagDelete(const QString& qsFileId, int iTagId);

Remarks

This method deletes the file tag identified by TagId from the cached file specified by FileId.

Please refer to the File Tags topic for more information.

Note: This method can be called only when Active is true, and it cannot be called within events.

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

FileTagExists Method (CBCache Class)

This method checks whether or not a file has a specific tag associated with it.

Syntax

ANSI (Cross Platform)
int FileTagExists(const char* lpszFileId, int iTagId);

Unicode (Windows)
INT FileTagExists(LPCWSTR lpszFileId, INT iTagId);
int cbfsconnect_cbcache_filetagexists(void* lpObj, const char* lpszFileId, int iTagId);
bool FileTagExists(const QString& qsFileId, int iTagId);

Remarks

This method returns true if a file identified by FileId has an associated tag identified by TagId; otherwise, it returns false.

The value passed for TagId must be in the range from 0x0001 to 0xCFFF (inclusive).

Please refer to the File Tags topic for more information.

Note: This method can be called only when Active is true, and it 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.

FileTagGet Method (CBCache Class)

This method retrieves the binary data held by a file tag attached to the specified cached file.

Syntax

ANSI (Cross Platform)
char* FileTagGet(const char* lpszFileId, int iTagId, int *lpSize = NULL);

Unicode (Windows)
LPSTR FileTagGet(LPCWSTR lpszFileId, INT iTagId, LPINT lpSize = NULL);
char* cbfsconnect_cbcache_filetagget(void* lpObj, const char* lpszFileId, int iTagId, int *lpSize);
QByteArray FileTagGet(const QString& qsFileId, int iTagId);

Remarks

This method retrieves the binary data stored in a file tag, identified by TagId attached to the file identified by FileId. If a file tag with the specified TagId is not attached to the specified file, this method fails with an error.

The value passed for TagId must be in the range from 0x0001 to 0xCFFF (inclusive).

Please refer to the File Tags topic for more information.

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a Binary String value (with length lpSize); 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.

FileTagGetSize Method (CBCache Class)

This method retrieves the size of a file tag attached to the specified cached file.

Syntax

ANSI (Cross Platform)
int FileTagGetSize(const char* lpszFileId, int iTagId);

Unicode (Windows)
INT FileTagGetSize(LPCWSTR lpszFileId, INT iTagId);
int cbfsconnect_cbcache_filetaggetsize(void* lpObj, const char* lpszFileId, int iTagId);
int FileTagGetSize(const QString& qsFileId, int iTagId);

Remarks

This method retrieves the size of the binary data stored in a file tag, identified by TagId, attached to the cached file identified by FileId. If a file tag with the specified TagId is not attached to the specified file, this method returns 0 as the tag size.

The value passed for TagId must be in the range from 0x0001 to 0xCFFF (inclusive).

Please refer to the File Tags topic for more information.

Note: This method can be called only when Active is true.

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.

FileTagSet Method (CBCache Class)

This method attaches a file tag with binary data to the specified cached file.

Syntax

ANSI (Cross Platform)
int FileTagSet(const char* lpszFileId, int iTagId, const char* lpData, int lenData);

Unicode (Windows)
INT FileTagSet(LPCWSTR lpszFileId, INT iTagId, LPCSTR lpData, INT lenData);
int cbfsconnect_cbcache_filetagset(void* lpObj, const char* lpszFileId, int iTagId, const char* lpData, int lenData);
int FileTagSet(const QString& qsFileId, int iTagId, QByteArray qbaData);

Remarks

This method attaches a file tag with binary data to the cached file identified by FileId using the specified TagId. If a file tag with the specified TagId is already attached to the specified file, it is replaced.

The value passed for TagId must be in the range from 0x0001 to 0xCFFF (inclusive).

The Data parameter specifies the raw binary data to store in the file tag; it may be up to 65531 bytes in length.

Please refer to the File Tags topic for more information.

Note: This method can be called only when Active is true, and it cannot be called within events.

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

FileTouch Method (CBCache Class)

This method touches a range of data in a cached file.

Syntax

ANSI (Cross Platform)
int FileTouch(const char* lpszFileId, int64 lPosition, int iCount, int bFlush);

Unicode (Windows)
INT FileTouch(LPCWSTR lpszFileId, LONG64 lPosition, INT iCount, BOOL bFlush);
int cbfsconnect_cbcache_filetouch(void* lpObj, const char* lpszFileId, int64 lPosition, int iCount, int bFlush);
int FileTouch(const QString& qsFileId, qint64 lPosition, int iCount, bool bFlush);

Remarks

This method touches a range of data in the cached file identified by FileId, thereby marking it as changed and in need of flushing. The range of data to be touched starts at the specified Position and extends for Count bytes.

The cache will automatically attempt to read in any unavailable data in the touched range via ReadData, and then will write out all data in the touched range via WriteData. If the Flush parameter is true, these operations will take place synchronously and block return of this method; otherwise, they will take place in the background and this method will return immediately.

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

FileWrite Method (CBCache Class)

This method writes the specified part of a cached file.

Syntax

ANSI (Cross Platform)
int FileWrite(const char* lpszFileId, int64 lPosition, const char* lpBuffer, int lenBuffer, int iIndex, int iCount);

Unicode (Windows)
INT FileWrite(LPCWSTR lpszFileId, LONG64 lPosition, LPCSTR lpBuffer, INT lenBuffer, INT iIndex, INT iCount);
int cbfsconnect_cbcache_filewrite(void* lpObj, const char* lpszFileId, int64 lPosition, const char* lpBuffer, int lenBuffer, int iIndex, int iCount);
bool FileWrite(const QString& qsFileId, qint64 lPosition, QByteArray qbaBuffer, int iIndex, int iCount);

Remarks

This method writes data to the cached file identified by FileId from the specified Buffer. The cached file must be opened using FileOpen before it can be written to.

Count bytes of data will be read from the given Buffer, starting at the given Index, and written into the cached file. The data are written to the cached file starting at the given Position.

If any amount of data is written beyond the known file size, such writing causes the file to grow unless the RWCAP_WRITE_NOT_BEYOND_EOF flag is specified. When the file grows, the known file size value for the file is updated and all the data are eventually flushed (written) to the external storage via the WriteData event. The RWCAP_WRITE_NOT_BEYOND_EOF flag indicates that no writing should occur beyond the known file size, thus preventing the file from growth.

The method returns false if any errors happened during writing and returns true if everything went fine.

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.

GetNextEnumeratedFile Method (CBCache Class)

This method returns the next file in the list of enumeration results.

Syntax

ANSI (Cross Platform)
char* GetNextEnumeratedFile(int64 lEnumerationHandle);

Unicode (Windows)
LPWSTR GetNextEnumeratedFile(LONG64 lEnumerationHandle);
char* cbfsconnect_cbcache_getnextenumeratedfile(void* lpObj, int64 lEnumerationHandle);
QString GetNextEnumeratedFile(qint64 lEnumerationHandle);

Remarks

This method returns the Id of the next file in the list of enumeration results identified by the EnumerationHandle parameter. If the list does not have any more files, an empty string is returned.

When an empty string is returned because the end of the list has been reached, the class will close the enumeration automatically by calling CloseEnumeration. If the application finishes enumeration without reaching the end of the list, it must call the CloseEnumeration method to release any associated resources.

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.

OpenCache Method (CBCache Class)

This method opens the cache.

Syntax

ANSI (Cross Platform)
int OpenCache(const char* lpszEncryptionPassword, int bCaseSensitive);

Unicode (Windows)
INT OpenCache(LPCWSTR lpszEncryptionPassword, BOOL bCaseSensitive);
int cbfsconnect_cbcache_opencache(void* lpObj, const char* lpszEncryptionPassword, int bCaseSensitive);
int OpenCache(const QString& qsEncryptionPassword, bool bCaseSensitive);

Remarks

This method opens the cache specified by the CacheFile property; creating a storage file for it in the directory specified by the CacheDirectory property, if necessary.

To encrypt the cache, pass a nonempty string for the EncryptionPassword parameter the first time it is created. The same value will need to be passed any time the cache is opened again in the future.

If the StoreDataInFiles configuration setting is enabled, encryption affects only the main cache storage file and not the files that are used to store individual files' data.

The CaseSensitive parameter specifies whether the cache should treat its File Ids as case-sensitive or case-insensitive.

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

RefreshStatistics Method (CBCache Class)

This method forces a refresh of the cache's statistics.

Syntax

ANSI (Cross Platform)
int RefreshStatistics();

Unicode (Windows)
INT RefreshStatistics();
int cbfsconnect_cbcache_refreshstatistics(void* lpObj);
int RefreshStatistics();

Remarks

This method forces the cache to immediately refresh its statistics. The refreshed statistics will be reported through the Status event and will be used to update the Stats property.

This method needs to be called only if the applications needs to update the cache's statistics sooner than the end of the current StatsRefreshInterval.

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

ResetErrorState Method (CBCache Class)

This method resets any outstanding errors for a file or external storage.

Syntax

ANSI (Cross Platform)
int ResetErrorState(const char* lpszFileId);

Unicode (Windows)
INT ResetErrorState(LPCWSTR lpszFileId);
int cbfsconnect_cbcache_reseterrorstate(void* lpObj, const char* lpszFileId);
int ResetErrorState(const QString& qsFileId);

Remarks

If FileId is specified, this method resets any outstanding file errors, related to the cached file identified by FileId, previously reported via ReadData and/or WriteData events, thus allowing operations on the file to continue. If there are no outstanding errors for the specified file, this method does nothing.

If FileId is empty, this method resets any outstanding external-storage-related error previously reported via a ReadData or WriteData event, thus allowing external I/O operations to continue. If there are no outstanding external storage errors, this method does nothing.

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

StartCleanup Method (CBCache Class)

This method starts a background cleanup operation to remove unused files from the cache.

Syntax

ANSI (Cross Platform)
int StartCleanup(int iMaxAge);

Unicode (Windows)
INT StartCleanup(INT iMaxAge);
int cbfsconnect_cbcache_startcleanup(void* lpObj, int iMaxAge);
int StartCleanup(int iMaxAge);

Remarks

This method starts a cleanup operation to remove unused files from the cache. Files used earlier than MaxAge hours ago will be removed (passing 0 will cause all files to be removed).

The cleanup operation is performed asynchronously in a background thread, so this method returns immediately. To cancel a cleanup operation, use the CancelCleanup method.

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

BeforeFlush Event (CBCache Class)

This event fires to report the start of the asynchronous file flush procedure.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeFlush(CBCacheBeforeFlushEventParams *e);
typedef struct {
const char *FileId;
void *FileContext;
int64 LastUseTime;
int PostponeTime; int reserved; } CBCacheBeforeFlushEventParams;
Unicode (Windows) virtual INT FireBeforeFlush(CBCacheBeforeFlushEventParams *e);
typedef struct {
LPCWSTR FileId;
LPVOID FileContext;
LONG64 LastUseTime;
INT PostponeTime; INT reserved; } CBCacheBeforeFlushEventParams;
#define EID_CBCACHE_BEFOREFLUSH 1

virtual INT CBFSCONNECT_CALL FireBeforeFlush(LPWSTR &lpszFileId, LPVOID &lpFileContext, LONG64 &lLastUseTime, INT &iPostponeTime);
class CBCacheBeforeFlushEventParams {
public:
  const QString &FileId();

  void *FileContext();

  const QDateTime &LastUseTime();

  int PostponeTime();
  void SetPostponeTime(int iPostponeTime);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeFlush(CBCacheBeforeFlushEventParams *e);
// Or, subclass CBCache and override this emitter function. virtual int FireBeforeFlush(CBCacheBeforeFlushEventParams *e) {...}

Remarks

This event fires when the asynchronous file flush procedure starts for the cached file identified by FileId. This event does not fire if the flush procedure is initiated by the application using FileFlush, FileClose, or FileCloseEx methods.

Note: This event will fire in the context of a dedicated worker thread that performs cache maintenance. Keep handling of this event as quick as possible.

Use the PostponeTime parameter to specify time in seconds to postpone automatic flush operation for this file.

BeforePurge Event (CBCache Class)

This event fires to report the start of the asynchronous file purge procedure.

Syntax

ANSI (Cross Platform)
virtual int FireBeforePurge(CBCacheBeforePurgeEventParams *e);
typedef struct {
const char *FileId;
void *FileContext;
int64 LastUseTime;
int PostponeTime; int reserved; } CBCacheBeforePurgeEventParams;
Unicode (Windows) virtual INT FireBeforePurge(CBCacheBeforePurgeEventParams *e);
typedef struct {
LPCWSTR FileId;
LPVOID FileContext;
LONG64 LastUseTime;
INT PostponeTime; INT reserved; } CBCacheBeforePurgeEventParams;
#define EID_CBCACHE_BEFOREPURGE 2

virtual INT CBFSCONNECT_CALL FireBeforePurge(LPWSTR &lpszFileId, LPVOID &lpFileContext, LONG64 &lLastUseTime, INT &iPostponeTime);
class CBCacheBeforePurgeEventParams {
public:
  const QString &FileId();

  void *FileContext();

  const QDateTime &LastUseTime();

  int PostponeTime();
  void SetPostponeTime(int iPostponeTime);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforePurge(CBCacheBeforePurgeEventParams *e);
// Or, subclass CBCache and override this emitter function. virtual int FireBeforePurge(CBCacheBeforePurgeEventParams *e) {...}

Remarks

This event fires when the asynchronous file purge procedure starts for the cached file identified by FileId. This event does not fire if the purge procedure is initiated by the application using the FileFlush, FileClose, or FileCloseEx methods.

Note: This event will fire in the context of a dedicated worker thread that performs cache maintenance. Keep handling of this event as quick as possible.

Use the PostponeTime parameter to specify time in seconds to postpone automatic purge operation for this file.

EndCleanup Event (CBCache Class)

This event fires to report the beginning of the asynchronous cleanup procedure.

Syntax

ANSI (Cross Platform)
virtual int FireEndCleanup(CBCacheEndCleanupEventParams *e);
typedef struct { int reserved; } CBCacheEndCleanupEventParams;
Unicode (Windows) virtual INT FireEndCleanup(CBCacheEndCleanupEventParams *e);
typedef struct { INT reserved; } CBCacheEndCleanupEventParams;
#define EID_CBCACHE_ENDCLEANUP 3

virtual INT CBFSCONNECT_CALL FireEndCleanup();
class CBCacheEndCleanupEventParams {
public:
  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void EndCleanup(CBCacheEndCleanupEventParams *e);
// Or, subclass CBCache and override this emitter function. virtual int FireEndCleanup(CBCacheEndCleanupEventParams *e) {...}

Remarks

This event fires when the asynchronous cleanup procedure ends.

Note: This event will fire in the context of a dedicated worker thread that performs cache maintenance. Keep handling of this event as quick as possible.

Error Event (CBCache Class)

This event fires if an unhandled error occurs during an event.

Syntax

ANSI (Cross Platform)
virtual int FireError(CBCacheErrorEventParams *e);
typedef struct {
int ErrorCode;
const char *Description; int reserved; } CBCacheErrorEventParams;
Unicode (Windows) virtual INT FireError(CBCacheErrorEventParams *e);
typedef struct {
INT ErrorCode;
LPCWSTR Description; INT reserved; } CBCacheErrorEventParams;
#define EID_CBCACHE_ERROR 4

virtual INT CBFSCONNECT_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);
class CBCacheErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void Error(CBCacheErrorEventParams *e);
// Or, subclass CBCache and override this emitter function. virtual int FireError(CBCacheErrorEventParams *e) {...}

Remarks

This event fires if an unhandled error occurs during another event. Developers can use this information to track down unhandled errors in an application's event handlers.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

Log Event (CBCache Class)

This log reports events that occur in the class.

Syntax

ANSI (Cross Platform)
virtual int FireLog(CBCacheLogEventParams *e);
typedef struct {
int Level;
const char *Message; int reserved; } CBCacheLogEventParams;
Unicode (Windows) virtual INT FireLog(CBCacheLogEventParams *e);
typedef struct {
INT Level;
LPCWSTR Message; INT reserved; } CBCacheLogEventParams;
#define EID_CBCACHE_LOG 5

virtual INT CBFSCONNECT_CALL FireLog(INT &iLevel, LPWSTR &lpszMessage);
class CBCacheLogEventParams {
public:
  int Level();

  const QString &Message();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void Log(CBCacheLogEventParams *e);
// Or, subclass CBCache and override this emitter function. virtual int FireLog(CBCacheLogEventParams *e) {...}

Remarks

This event fires when the class needs to notify an application or developers about something that happened internally. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of the message. Possible values are as follows:

0 (None) No information is logged.
1 (Errors) Only errors are logged.
2 (Warnings) Errors and warnings are logged.
3 (Information - Default) Errors, warnings, and informational messages are logged.
4 (Debug) Debug data are logged.

Message is the log entry.

Note: This event will fire in the context of a dedicated worker thread. Keep handling of this event as quick as possible.

Progress Event (CBCache Class)

This event fires to report the progress of an operation.

Syntax

ANSI (Cross Platform)
virtual int FireProgress(CBCacheProgressEventParams *e);
typedef struct {
int Operation;
int64 Current;
int64 Total;
int Interrupt; int reserved; } CBCacheProgressEventParams;
Unicode (Windows) virtual INT FireProgress(CBCacheProgressEventParams *e);
typedef struct {
INT Operation;
LONG64 Current;
LONG64 Total;
BOOL Interrupt; INT reserved; } CBCacheProgressEventParams;
#define EID_CBCACHE_PROGRESS 6

virtual INT CBFSCONNECT_CALL FireProgress(INT &iOperation, LONG64 &lCurrent, LONG64 &lTotal, BOOL &bInterrupt);
class CBCacheProgressEventParams {
public:
  int Operation();

  qint64 Current();

  qint64 Total();

  bool Interrupt();
  void SetInterrupt(bool bInterrupt);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void Progress(CBCacheProgressEventParams *e);
// Or, subclass CBCache and override this emitter function. virtual int FireProgress(CBCacheProgressEventParams *e) {...}

Remarks

This event fires when the cache wants to report the progress of the operation specified by Operation. Possible values are as follows:

CACHE_PO_CLEANUP1Cache cleanup

The Current and Total parameters specify the number of the item being processed, and the total number of items being processed, respectively. For some operations, these parameters may be 0 or -1.

The Interrupt parameter can be set to true to stop the operation.

ReadData Event (CBCache Class)

This event fires when the cache needs to read file data from external storage.

Syntax

ANSI (Cross Platform)
virtual int FireReadData(CBCacheReadDataEventParams *e);
typedef struct {
const char *FileId;
int64 Size;
int64 Position;
int Flags;
void *Buffer;
int BytesToRead;
int BytesRead;
void *FileContext;
int ResultCode; int reserved; } CBCacheReadDataEventParams;
Unicode (Windows) virtual INT FireReadData(CBCacheReadDataEventParams *e);
typedef struct {
LPCWSTR FileId;
LONG64 Size;
LONG64 Position;
INT Flags;
LPVOID Buffer;
INT BytesToRead;
INT BytesRead;
LPVOID FileContext;
INT ResultCode; INT reserved; } CBCacheReadDataEventParams;
#define EID_CBCACHE_READDATA 7

virtual INT CBFSCONNECT_CALL FireReadData(LPWSTR &lpszFileId, LONG64 &lSize, LONG64 &lPosition, INT &iFlags, LPVOID &lpBuffer, INT &iBytesToRead, INT &iBytesRead, LPVOID &lpFileContext, INT &iResultCode);
class CBCacheReadDataEventParams {
public:
  const QString &FileId();

  qint64 Size();

  qint64 Position();

  int Flags();

  void *Buffer();

  int BytesToRead();

  int BytesRead();
  void SetBytesRead(int iBytesRead);

  void *FileContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void ReadData(CBCacheReadDataEventParams *e);
// Or, subclass CBCache and override this emitter function. virtual int FireReadData(CBCacheReadDataEventParams *e) {...}

Remarks

This event fires when the cache needs to read data for the cached file identified by FileId from an external storage.

The Size parameter reflects the specified file's "real size" as it is currently known by the cache.

The Position parameter reflects the byte offset in the real file (i.e., the one in the external storage) from which the handler should start reading data.

The Flags parameter provides supplementary information about the nature of the request. This parameter, along with the Size and Position parameters, helps the event handler to determine, which part of the file Buffer represents and whether additional ReadData events should be expected. It will include a combination of one or more of the following flags:

RWEVENT_IN_PROGRESS0x00000001A file's data are being transferred into or out of the cache.

RWEVENT_CANCELED0x00000002A data transfer has been canceled for some reason.

RWEVENT_WHOLE_FILE0x00000004The entire file is being transferred.

RWEVENT_CONTINUOUS_STARTED0x00000010A continuous transfer has started.

RWEVENT_CONTINUOUS_RESTARTED0x00000020A continuous transfer has restarted from the beginning.

RWEVENT_CONTINUOUS_FINISHED0x00000040A continuous transfer is finishing (i.e., the current block is the final one).

RWEVENT_RANDOM_STARTED0x00000100A random-access transfer has started.

RWEVENT_RANDOM_FINISHED0x00000200A random-access transfer is finishing (i.e., the current block is the final one).

RWEVENT_BEFORE_END0x00001000The current transfer will finish before the end of the file.

RWEVENT_TIL_END0x00002000The current transfer will last until the end of the file.

To handle this event property, a handler must read BytesToRead bytes of data from the real file in external storage, starting at the specified Position, into Buffer.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

Note: If Flags contains RWEVENT_CANCELED, the transfer is being canceled and no data should be read; the Buffer is not provided and both Position and BytesToRead parameters are set to 0.

When reading is complete, a handler must set BytesRead to reflect the actual number of bytes read from the real file. A handler must not attempt to copy more than BytesToRead bytes of data into Buffer.

The FileContext parameter reflects the application-defined value passed when FileOpen was called.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available, security checks failed), set it to one of the following values to report an appropriate error:

RWRESULT_SUCCESS0x00000000Success.

Returning this code indicates that all data were successfully transferred.

RWRESULT_PARTIAL0x00000080Partial success.

Returning this code indicates that some, but not all, data were successfully transferred. i.e., when BytesRead < BytesToRead (for ReadData), or BytesWritten < BytesToWrite (for WriteData).

RWRESULT_RANGE_BEYOND_EOF0x00000081Specified range is beyond the end of the file (EOF).

For the ReadData event, returning this code indicates to the cache that there is no need to request data beyond (Position + BytesRead), and that the tail should be zeroed instead.

RWRESULT_FILE_MODIFIED_EXTERNALLY0x00000082The specified file's size was modified externally.

Returning this code indicates that the operation was not completed successfully because of this conflicting situation.

RWRESULT_FILE_MODIFIED_LOCALLY0x00000083The requested file's size was modified locally.

RWRESULT_FAILURE0x0000008DThe operation failed for some transient reason.

Returning this code indicates that, even though the current request failed, it is safe to continue sending requests for both the specified file and others. (Other operations may continue.)

RWRESULT_FILE_FAILURE0x0000008EThe operation failed for some external-file-related reason.

Returning this code indicates that some failure related to the external file has occurred, and it is expected that any further requests made against that file will also fail. The class will not send any more requests for the specified file until the file-specific error is reset as described in Reporting Transfer Errors.

RWRESULT_PERMANENT_FAILURE0x0000008FThe operation failed for some external-storage-related reason.

Returning this code indicates that some failure related to the external storage has occurred, and it is expected that all further requests will also fail. The class will not send any more requests for any file until the global error is reset as described in Reporting Transfer Errors.

Please refer to the Error Reporting and Handling topic for more information.

StartCleanup Event (CBCache Class)

This event fires to report the beginning of the asynchronous cleanup procedure.

Syntax

ANSI (Cross Platform)
virtual int FireStartCleanup(CBCacheStartCleanupEventParams *e);
typedef struct { int reserved; } CBCacheStartCleanupEventParams;
Unicode (Windows) virtual INT FireStartCleanup(CBCacheStartCleanupEventParams *e);
typedef struct { INT reserved; } CBCacheStartCleanupEventParams;
#define EID_CBCACHE_STARTCLEANUP 8

virtual INT CBFSCONNECT_CALL FireStartCleanup();
class CBCacheStartCleanupEventParams {
public:
  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void StartCleanup(CBCacheStartCleanupEventParams *e);
// Or, subclass CBCache and override this emitter function. virtual int FireStartCleanup(CBCacheStartCleanupEventParams *e) {...}

Remarks

This event fires when the asynchronous cleanup procedure starts.

Note: This event will fire in the context of a dedicated worker thread that performs cache maintenance. Keep handling of this event as quick as possible.

Status Event (CBCache Class)

This event fires to report the latest cache statistics.

Syntax

ANSI (Cross Platform)
virtual int FireStatus(CBCacheStatusEventParams *e);
typedef struct {
int64 CacheSize;
int64 TotalData;
int64 UnflushedData;
int UnflushedFiles;
int CurrentOperation;
const char *CurrentFileId; int reserved; } CBCacheStatusEventParams;
Unicode (Windows) virtual INT FireStatus(CBCacheStatusEventParams *e);
typedef struct {
LONG64 CacheSize;
LONG64 TotalData;
LONG64 UnflushedData;
INT UnflushedFiles;
INT CurrentOperation;
LPCWSTR CurrentFileId; INT reserved; } CBCacheStatusEventParams;
#define EID_CBCACHE_STATUS 9

virtual INT CBFSCONNECT_CALL FireStatus(LONG64 &lCacheSize, LONG64 &lTotalData, LONG64 &lUnflushedData, INT &iUnflushedFiles, INT &iCurrentOperation, LPWSTR &lpszCurrentFileId);
class CBCacheStatusEventParams {
public:
  qint64 CacheSize();

  qint64 TotalData();

  qint64 UnflushedData();

  int UnflushedFiles();

  int CurrentOperation();

  const QString &CurrentFileId();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void Status(CBCacheStatusEventParams *e);
// Or, subclass CBCache and override this emitter function. virtual int FireStatus(CBCacheStatusEventParams *e) {...}

Remarks

This event fires once every StatsRefreshInterval to provide the application with the latest cache statistics, as well as information about any in-progress cache operation.

The CacheSize parameter reflects the current size of the cache, in bytes.

The TotalData parameter reflects the total amount of data present in the cache, in bytes.

The UnflushedData parameter reflects the amount of unflushed data present in the cache, in bytes.

The UnflushedFiles parameter reflects the number of unflushed files present in the cache.

The CurrentOperation parameter reflects the cache's current operations; it will take one of the following values:

CACHE_OP_IDLE0The cache is idle.

CACHE_OP_CLEANUP2Cache cleanup is being performed.

CACHE_OP_COMPACT3The cache's storage file is being compacted.

CACHE_OP_READ4The cache is reading some file's data.

CACHE_OP_WRITE5The cache is writing some file's data.

When CurrentOperation is CACHE_OP_READ or CACHE_OP_WRITE, the CurrentFileId parameter will reflect the Id of the cached file being processed.

Note: This event can fire in the context of any thread.

WriteData Event (CBCache Class)

This event fires when the cache needs to write file data to external storage.

Syntax

ANSI (Cross Platform)
virtual int FireWriteData(CBCacheWriteDataEventParams *e);
typedef struct {
const char *FileId;
int64 Size;
int64 Position;
int Flags;
const void *Buffer;
int BytesToWrite;
int BytesWritten;
void *FileContext;
int ResultCode; int reserved; } CBCacheWriteDataEventParams;
Unicode (Windows) virtual INT FireWriteData(CBCacheWriteDataEventParams *e);
typedef struct {
LPCWSTR FileId;
LONG64 Size;
LONG64 Position;
INT Flags;
LPCVOID Buffer;
INT BytesToWrite;
INT BytesWritten;
LPVOID FileContext;
INT ResultCode; INT reserved; } CBCacheWriteDataEventParams;
#define EID_CBCACHE_WRITEDATA 10

virtual INT CBFSCONNECT_CALL FireWriteData(LPWSTR &lpszFileId, LONG64 &lSize, LONG64 &lPosition, INT &iFlags, LPVOID &lpBuffer, INT &iBytesToWrite, INT &iBytesWritten, LPVOID &lpFileContext, INT &iResultCode);
class CBCacheWriteDataEventParams {
public:
  const QString &FileId();

  qint64 Size();

  qint64 Position();

  int Flags();

  const void *Buffer();

  int BytesToWrite();

  int BytesWritten();
  void SetBytesWritten(int iBytesWritten);

  void *FileContext();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void WriteData(CBCacheWriteDataEventParams *e);
// Or, subclass CBCache and override this emitter function. virtual int FireWriteData(CBCacheWriteDataEventParams *e) {...}

Remarks

This event fires when the cache needs to write data for the cached file identified by FileId to external storage.

The Size parameter reflects the specified file's "real size" as it is currently known by the cache.

The Position parameter reflects the byte offset in the real file (i.e., the one in external storage) at which the application should start writing data.

The Flags parameter provides supplementary information about the nature of the request. This parameter, along with the Size and Position parameters, helps the application to determine which part of the file Buffer represents, and whether additional WriteData events should be expected. It will include a combination of one or more of the following flags:

RWEVENT_IN_PROGRESS0x00000001A file's data are being transferred into or out of the cache.

RWEVENT_CANCELED0x00000002A data transfer has been canceled for some reason.

RWEVENT_WHOLE_FILE0x00000004The entire file is being transferred.

RWEVENT_CONTINUOUS_STARTED0x00000010A continuous transfer has started.

RWEVENT_CONTINUOUS_RESTARTED0x00000020A continuous transfer has restarted from the beginning.

RWEVENT_CONTINUOUS_FINISHED0x00000040A continuous transfer is finishing (i.e., the current block is the final one).

RWEVENT_RANDOM_STARTED0x00000100A random-access transfer has started.

RWEVENT_RANDOM_FINISHED0x00000200A random-access transfer is finishing (i.e., the current block is the final one).

RWEVENT_BEFORE_END0x00001000The current transfer will finish before the end of the file.

RWEVENT_TIL_END0x00002000The current transfer will last until the end of the file.

To handle this event properly, applications must write BytesToWrite bytes of data from Buffer to the real file in external storage, starting at the specified Position.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

Note: If Flags contains RWEVENT_CANCELED, the transfer is being canceled and no data should be written; the Buffer is not provided and both Position and BytesToWrite parameters are set to 0.

When writing is complete, applications must set BytesWritten to reflect the actual number of bytes written to the real file. Applications must not attempt to copy more than BytesToWrite bytes of data from Buffer.

The FileContext parameter reflects the application-defined value passed when FileOpen was called.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available, security checks failed), set it to one of the following values to report an appropriate error:

RWRESULT_SUCCESS0x00000000Success.

Returning this code indicates that all data were successfully transferred.

RWRESULT_PARTIAL0x00000080Partial success.

Returning this code indicates that some, but not all, data were successfully transferred. i.e., when BytesRead < BytesToRead (for ReadData), or BytesWritten < BytesToWrite (for WriteData).

RWRESULT_RANGE_BEYOND_EOF0x00000081Specified range is beyond the end of the file (EOF).

For the ReadData event, returning this code indicates to the cache that there is no need to request data beyond (Position + BytesRead), and that the tail should be zeroed instead.

RWRESULT_FILE_MODIFIED_EXTERNALLY0x00000082The specified file's size was modified externally.

Returning this code indicates that the operation was not completed successfully because of this conflicting situation.

RWRESULT_FILE_MODIFIED_LOCALLY0x00000083The requested file's size was modified locally.

RWRESULT_FAILURE0x0000008DThe operation failed for some transient reason.

Returning this code indicates that, even though the current request failed, it is safe to continue sending requests for both the specified file and others. (Other operations may continue.)

RWRESULT_FILE_FAILURE0x0000008EThe operation failed for some external-file-related reason.

Returning this code indicates that some failure related to the external file has occurred, and it is expected that any further requests made against that file will also fail. The class will not send any more requests for the specified file until the file-specific error is reset as described in Reporting Transfer Errors.

RWRESULT_PERMANENT_FAILURE0x0000008FThe operation failed for some external-storage-related reason.

Returning this code indicates that some failure related to the external storage has occurred, and it is expected that all further requests will also fail. The class will not send any more requests for any file until the global error is reset as described in Reporting Transfer Errors.

Please refer to the Error Reporting and Handling topic for more information.

Config Settings (CBCache 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.

CBCache Config Settings

BlockSize:   The size of the block, used to store the data.

This read-only configuration setting returns the size of the block, used by the cache to store and transfer the data. The initial value is 0. It is recalculated depending on the capabilities of the application and the supported size of the reading and writing blocks.

JournalingMode:   Specifies whether the main cache file uses journaling for increased data consistency.

This configuration setting specifies whether the filesystem behind the main cache file should use journaling for metadata and main file data. Possible values are:

VAULT_JM_NONE0No journaling is used.

This mode ensures the fastest operations, but if the application crashes, corruption of the vault is possible.

VAULT_JM_METADATA1Journaling is used only for metadata (filesystem structure and directory contents).

This mode is a balance between speed and reliability.

VAULT_JM_FULL2Journaling is used for both filesystem structure and file data and metadata.

This mode is the slowest but the most reliable option.

LogLevel:   The level of detail that is logged.

This configuration setting controls the level of detail that is logged through the Log event. Possible values are as follows:

0 (None) No information is logged.
1 (Errors) Only errors are logged.
2 (Warnings) Errors and warnings are logged.
3 (Information - Default) Errors, warnings, and informational messages are logged.
4 (Debug) Debug data are logged.

MaxReaderThreadsPerFile:   The maximum number of reader threads to use to fire events.

This configuration setting specifies the maximum number of reader threads per file the class may create to fire events when the Serialization property is set to smPerFileReadingWritingConcurrent value.

By default, this configuration setting is set to 4 threads per file.

StatsRefreshInterval:   Minimum time period between cache statistics refreshes.

This configuration setting specifies the minimum time period, in milliseconds, between automatic cache statistics refreshes. Each statistics refresh causes the Status event to fire and updates the values in the Stats property.

The statistics refresh interval is intended to prevent excessive user interface changes. Set the value to 0 to disable automatic refresh. The default value is 100 ms.

Note: Applications may call RefreshStatistics at any time to explicitly refresh the cache's statistics.

StoreDataInFiles:   Specifies whether file data should be stored in the main cache file or in individual files.

When this configuration setting is disabled (default), the cache stores all data in one file with encryption and compression applied (when they are enabled through the corresponding properties).

When this configuration setting is enabled, the cache stores individual files' data in separate files and uses the main cache file to store various metadata. This option makes the main cache file smaller and opening of the cache file becomes faster. Also, the speed of intensive write operations of large files is increased. The cache in this mode, however, does not provide encryption or compression of file data and journaling of file data does not take place either.

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 (CBCache 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.

Cache errors Errors

0x48000001   ERROR_ALREADY_OPENED: The requested operation cannot be performed while the cache is open.
0x48000002   ERROR_NOT_OPENED: The cache must be open before attempting to perform the requested operation.
0x48000003   ERROR_REQ_PARAM_MISSING: The requested operation cannot be performed because a required property has not been set.
0x48000004   ERROR_WRONG_ARGUMENT: An invalid value has been passed for the method parameter specified in the error message.
0x48000005   ERROR_BACKEND_FAILURE: The cache cannot read data from or write data to external storage because an event handler has reported an error. Once the error state has been reset using ResetErrorState, try again.
0x48000006   ERROR_BACKEND_FILE_FAILURE: The cache cannot read data from or write data to external storage because an event handler has reported a file error. Once the error state has been reset using ResetErrorState, try again.
0x48000007   ERROR_INVALID_OPERATION: The requested operation is not valid in current context. Refer to the error message for additional information.
0x48000008   ERROR_STORAGE_FAILURE: An operation involving the cache storage file has failed.
0x48000009   ERROR_WRONG_ENCRYPTION_KEY: The specified cache encryption key is incorrect.
0x4800000A   ERROR_DIR_NOT_EMPTY: The cache has failed to delete all blocks from the cache storage file.
0x4800000B   ERROR_FILE_NOT_OPEN: The requested operation cannot be completed because the specified file is not open. Open it using FileOpen, and then try again.
0x4800000C   ERROR_PATH_NOT_FOUND: The requested operation cannot be completed because the specified path is not found.
0x4800000D   ERROR_FILE_NOT_FOUND: The requested operation cannot be completed because the specified file is not found.
0x4800000E   ERROR_FILE_ALREADY_EXISTS: The requested operation cannot be completed because the specified file already exists.
0x4800000F   ERROR_INVALID_FILE_STATE: The requested operation cannot be completed because the specified file is in an invalid state. Close it using FileClose, and then try again.
0x48000010   ERROR_READWRITE_FAILURE: An operation of reading or writing the data from/to the cache has failed.
0x48000011   ERROR_OFFLINE: The requested operation cannot be completed because the external storage is offline.
0x48000012   ERROR_UNSUPPORTED: The specified combination of external storage capabilities is not supported by the cache. Please double-check that the ReadingCapabilities, WritingCapabilities, and ResizingCapabilities properties are set correctly.
0x48000013   ERROR_INTERNAL_OPERATION_CANCELED: The requested operation cannot be completed because it was canceled.
0x48000014   ERROR_INTERNAL_VAULT_CORRUPTED: The cache vault is corrupted. CheckAndRepair should be used to attempt to fix the vault.
0x48000015   ERROR_INTERNAL_VAULT_RECREATED: The cache vault has been corrupted beyond repair and has been recreated. This is not strictly an error but a nonplanned outcome.
0x49000001   ERROR_INTERNAL_ERROR_FIRST: An internal error has occurred. Please report the error details to the Callback Technologies support team.
0x4900000B   ERROR_INTERNAL_ERROR_LAST: An internal error has occurred. Please report the error details to the Callback Technologies support team.