Struct cbfsconnect::CBCache

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

cbfsconnect::CBCache

Remarks

The CBCache struct 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 struct 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 struct, 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 cache_file and cache_directory properties, respectively.

In terms of application architecture, the CBCache struct (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 struct's properties and methods, while the latter is "connected" through the struct's on_read_data and on_write_data events.

Here's how to get up and running:

1. Implement the on_read_data and on_write_data events so that they provide appropriate access to the external storage. The on_read_data event is mandatory. The on_write_data event is required only if the CBCache struct 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 struct by setting the reading_capabilities, writing_capabilities, and resizing_capabilities properties. This information is used by the CBCache struct to formulate a strategy for interacting with the external storage through the events mentioned in step 1.
3. Open the cache by setting the cache_directory and cache_file properties, and then calling the open_cache method.
4. When the struct opens an existing cache vault, it is recommended that applications use the enumerate_cached_files 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 file_open method.
6. While a cached file is open, it can be read from or written to using the file_read and file_write methods.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintainted by CBFSConnect. Due to this, the CBCache struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of CBCache when you have finished using the instance.

Property List

---

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

Method List

---

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

Event List

---

The following is the full list of the events fired by the struct with short descriptions. Click on the links for further details.

Config Settings

---

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

active Property (CBCache Struct)

This property describes whether the file cache is open.

Syntax

fn active(&self ) -> Result<bool, CBFSConnectError> 

Default Value

false

Remarks

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

This property is read-only.

Data Type

bool

auto_flush Property (CBCache Struct)

This property specifies whether automatic flushing is enabled.

Syntax

fn auto_flush(&self ) -> Result<bool, CBFSConnectError> 
fn set_auto_flush(&self, value : bool) ->  Option<CBFSConnectError> 

Default Value

false

Remarks

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

If this property is disabled, automatic flushing will never occur, regardless of the flush_policy setting; however, the file_flush 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

bool

cache_directory Property (CBCache Struct)

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

Syntax

fn cache_directory(&self ) -> Result<String, CBFSConnectError> 
fn set_cache_directory(&self, value : String) ->  Option<CBFSConnectError> 
fn set_cache_directory_ref(&self, value : &String) ->  Option<CBFSConnectError> 

Default Value

String::default()

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 cache_file property.

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

Data Type

String

cache_file Property (CBCache Struct)

This property includes the name of the file cache.

Syntax

fn cache_file(&self ) -> Result<String, CBFSConnectError> 
fn set_cache_file(&self, value : String) ->  Option<CBFSConnectError> 
fn set_cache_file_ref(&self, value : &String) ->  Option<CBFSConnectError> 

Default Value

String::default()

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 cache_directory property.

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

Data Type

String

cache_size_limit Property (CBCache Struct)

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

Syntax

fn cache_size_limit(&self ) -> Result<i32, CBFSConnectError> 
fn set_cache_size_limit(&self, value : i32) ->  Option<CBFSConnectError> 

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 purge_policy 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 purge_policy 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

i32

compressed Property (CBCache Struct)

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

Syntax

fn compressed(&self ) -> Result<bool, CBFSConnectError> 
fn set_compressed(&self, value : bool) ->  Option<CBFSConnectError> 

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

bool

flush_after_close_delay Property (CBCache Struct)

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

Syntax

fn flush_after_close_delay(&self ) -> Result<i32, CBFSConnectError> 
fn set_flush_after_close_delay(&self, value : i32) ->  Option<CBFSConnectError> 

Default Value

0

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

i32

flush_after_size Property (CBCache Struct)

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

Syntax

fn flush_after_size(&self ) -> Result<i32, CBFSConnectError> 
fn set_flush_after_size(&self, value : i32) ->  Option<CBFSConnectError> 

Default Value

0

Remarks

When the flush_policy 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

i32

flush_after_time Property (CBCache Struct)

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

Syntax

fn flush_after_time(&self ) -> Result<i32, CBFSConnectError> 
fn set_flush_after_time(&self, value : i32) ->  Option<CBFSConnectError> 

Default Value

0

Remarks

When the flush_policy 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

i32

flush_policy Property (CBCache Struct)

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

Syntax

fn flush_policy(&self ) -> Result<i32, CBFSConnectError> 
fn set_flush_policy(&self, value : i32) ->  Option<CBFSConnectError> 

Default Value

0

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:

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

Data Type

i32

has_orphans Property (CBCache Struct)

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

Syntax

fn has_orphans(&self ) -> Result<bool, CBFSConnectError> 

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.

Data Type

bool

max_cached_file_size Property (CBCache Struct)

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

Syntax

fn max_cached_file_size(&self ) -> Result<i64, CBFSConnectError> 
fn set_max_cached_file_size(&self, value : i64) ->  Option<CBFSConnectError> 

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

i64

mode Property (CBCache Struct)

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

Syntax

fn mode(&self ) -> Result<i32, CBFSConnectError> 
fn set_mode(&self, value : i32) ->  Option<CBFSConnectError> 

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:

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

Data Type

i32

offline Property (CBCache Struct)

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

Syntax

fn offline(&self ) -> Result<bool, CBFSConnectError> 
fn set_offline(&self, value : bool) ->  Option<CBFSConnectError> 

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 auto_flush: auto_flush 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

bool

purge_after_close_delay Property (CBCache Struct)

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

Syntax

fn purge_after_close_delay(&self ) -> Result<i32, CBFSConnectError> 
fn set_purge_after_close_delay(&self, value : i32) ->  Option<CBFSConnectError> 

Default Value

0

Remarks

When the purge_policy 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

i32

purge_after_time Property (CBCache Struct)

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

Syntax

fn purge_after_time(&self ) -> Result<i32, CBFSConnectError> 
fn set_purge_after_time(&self, value : i32) ->  Option<CBFSConnectError> 

Default Value

0

Remarks

When the purge_policy 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

i32

purge_policy Property (CBCache Struct)

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

Syntax

fn purge_policy(&self ) -> Result<i32, CBFSConnectError> 
fn set_purge_policy(&self, value : i32) ->  Option<CBFSConnectError> 

Default Value

0

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:

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

Data Type

i32

read_block_size Property (CBCache Struct)

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

Syntax

fn read_block_size(&self ) -> Result<i32, CBFSConnectError> 
fn set_read_block_size(&self, value : i32) ->  Option<CBFSConnectError> 

Default Value

0

Remarks

This property specifies the block size, in bytes, that the struct should use when reading data from external storage through the on_read_data 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 reading_capabilities property specifies that the external storage supports only whole-file reading.

This property may be overridden by the corresponding parameter of the file_open and file_set_size 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

i32

reading_capabilities Property (CBCache Struct)

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

Syntax

fn reading_capabilities(&self ) -> Result<i32, CBFSConnectError> 
fn set_reading_capabilities(&self, value : i32) ->  Option<CBFSConnectError> 

Default Value

0

Remarks

This property specifies any and all behaviors of the external storage that are relevant when reading data from it. The struct 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.

Reading and Writing Capability Flags (Position Related)

Reading and Writing Capability Flags (Size Related)

Reading and Writing Capability Flags (Write Related)

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

Data Type

i32

resizing_capabilities Property (CBCache Struct)

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

Syntax

fn resizing_capabilities(&self ) -> Result<i32, CBFSConnectError> 
fn set_resizing_capabilities(&self, value : i32) ->  Option<CBFSConnectError> 

Default Value

0

Remarks

This property specifies any and all behaviors of the external storage that are relevant when resizing files. The struct 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:

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

Data Type

i32

serialization Property (CBCache Struct)

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

Syntax

fn serialization(&self ) -> Result<i32, CBFSConnectError> 
fn set_serialization(&self, value : i32) ->  Option<CBFSConnectError> 

Default Value

0

Remarks

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

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

Data Type

i32

stats_cache_size Property (CBCache Struct)

This property contains the current size of the cache.

Syntax

fn stats_cache_size(&self ) -> Result<i64, CBFSConnectError> 

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 refresh_statistics method to force an immediate refresh.

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

This property is read-only.

Data Type

i64

stats_current_file_id Property (CBCache Struct)

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

Syntax

fn stats_current_file_id(&self ) -> Result<String, CBFSConnectError> 

Default Value

String::default()

Remarks

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

When stats_current_operation 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 refresh_statistics method to force an immediate refresh.

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

This property is read-only.

Data Type

String

stats_current_operation Property (CBCache Struct)

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

Syntax

fn stats_current_operation(&self ) -> Result<i32, CBFSConnectError> 

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:

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 refresh_statistics method to force an immediate refresh.

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

This property is read-only.

Data Type

i32

stats_total_data Property (CBCache Struct)

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

Syntax

fn stats_total_data(&self ) -> Result<i64, CBFSConnectError> 

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 refresh_statistics method to force an immediate refresh.

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

This property is read-only.

Data Type

i64

stats_unflushed_data Property (CBCache Struct)

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

Syntax

fn stats_unflushed_data(&self ) -> Result<i64, CBFSConnectError> 

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 refresh_statistics method to force an immediate refresh.

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

This property is read-only.

Data Type

i64

stats_unflushed_files Property (CBCache Struct)

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

Syntax

fn stats_unflushed_files(&self ) -> Result<i64, CBFSConnectError> 

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 refresh_statistics method to force an immediate refresh.

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

This property is read-only.

Data Type

i64

tag Property (CBCache Struct)

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

Syntax

fn tag(&self ) -> Result<i64, CBFSConnectError> 
fn set_tag(&self, value : i64) ->  Option<CBFSConnectError> 

Default Value

0

Remarks

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

Data Type

i64

write_block_size Property (CBCache Struct)

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

Syntax

fn write_block_size(&self ) -> Result<i32, CBFSConnectError> 
fn set_write_block_size(&self, value : i32) ->  Option<CBFSConnectError> 

Default Value

0

Remarks

This property specifies the block size, in bytes, that the struct should use when writing data to external storage via the on_write_data 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 writing_capabilities property specifies that the external storage only supports whole-file writing.

The property may be overridden by the corresponding parameter of the file_open and file_set_size 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

i32

writing_capabilities Property (CBCache Struct)

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

Syntax

fn writing_capabilities(&self ) -> Result<i32, CBFSConnectError> 
fn set_writing_capabilities(&self, value : i32) ->  Option<CBFSConnectError> 

Default Value

0

Remarks

This property specifies any and all behaviors of the external storage that are relevant when writing data to it. The struct 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.

Reading and Writing Capability Flags (Position Related)

Reading and Writing Capability Flags (Size Related)

Reading and Writing Capability Flags (Write Related)

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

Data Type

i32

cancel_cleanup Method (CBCache Struct)

This method cancels a background cleanup operation, if necessary.

Syntax

fn cancel_cleanup(&self) -> Option<CBFSConnectError>

Remarks

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

check_and_repair Method (CBCache Struct)

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

Syntax

fn check_and_repair(&self, encryption_password : &String, flags : i32) -> Option<CBFSConnectError>

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:

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

clear Method (CBCache Struct)

This method removes files from the cache.

Syntax

fn clear(&self, remove_orphans : bool, remove_locals : bool) -> Option<CBFSConnectError>

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 on_progress event will fire periodically to indicate progress.

close_cache Method (CBCache Struct)

This method closes the cache.

Syntax

fn close_cache(&self, flush_action : i32, purge_action : i32) -> Option<CBFSConnectError>

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:

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

close_enumeration Method (CBCache Struct)

This method closes the given file enumeration.

Syntax

fn close_enumeration(&self, enumeration_handle : i64) -> Option<CBFSConnectError>

Remarks

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

config Method (CBCache Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &String) ->  Result<String, CBFSConnectError>

Remarks

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

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

delete_cache Method (CBCache Struct)

This method deletes the cache completely.

Syntax

fn delete_cache(&self) -> Option<CBFSConnectError>

Remarks

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

enumerate_cached_files Method (CBCache Struct)

This method enumerates the files in the cache.

Syntax

fn enumerate_cached_files(&self, enumeration_mode : i32) ->  Result<i64, CBFSConnectError>

Remarks

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

This method returns a handle that can be passed to the get_next_enumerated_file 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 close_enumeration method to release the associated resources.

file_change_id Method (CBCache Struct)

This method changes the Id of a cached file.

Syntax

fn file_change_id(&self, file_id : &String, new_file_id : &String) -> Option<CBFSConnectError>

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.

file_close Method (CBCache Struct)

This method closes a cached file.

Syntax

fn file_close(&self, file_id : &String) -> Option<CBFSConnectError>

Remarks

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

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

file_close_ex Method (CBCache Struct)

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

Syntax

fn file_close_ex(&self, file_id : &String, flush_action : i32, purge_action : i32) -> Option<CBFSConnectError>

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:

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:

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

file_delete Method (CBCache Struct)

This method deletes a file from the cache.

Syntax

fn file_delete(&self, file_id : &String) -> Option<CBFSConnectError>

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.

file_exists Method (CBCache Struct)

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

Syntax

fn file_exists(&self, file_id : &String) ->  Result<bool, CBFSConnectError>

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.

file_flush Method (CBCache Struct)

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

Syntax

fn file_flush(&self, file_id : &String, flush_mode : i32, delay : i32, file_context : usize) ->  Result<i32, CBFSConnectError>

Remarks

This method flushes any modified data blocks for the file specified by FileId out to external storage via the on_write_data event (and possibly, the on_read_data 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:

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 on_write_data and on_read_data events' corresponding parameter. (If the file is already open, the value passed to file_open takes precedence).

This method will return one of the following values:

file_get_pinned Method (CBCache Struct)

This method returns the pinned state of a cached file.

Syntax

fn file_get_pinned(&self, file_id : &String) ->  Result<bool, CBFSConnectError>

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 file_purge method.

file_get_size Method (CBCache Struct)

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

Syntax

fn file_get_size(&self, file_id : &String) ->  Result<i64, CBFSConnectError>

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 file_open or file_set_size method; it does not necessarily correspond to the actual amount of data present in the cache for the file.

file_get_status Method (CBCache Struct)

This method gets the status of a cached file.

Syntax

fn file_get_status(&self, file_id : &String, status_kind : i32) ->  Result<bool, CBFSConnectError>

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_open Method (CBCache Struct)

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

Syntax

fn file_open(&self, file_id : &String, real_file_size : i64, prefetch_size : i64, file_context : usize) -> Option<CBFSConnectError>

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 file_set_size 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 on_read_data 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 on_read_data and on_write_data events fired for the file.

file_open_ex Method (CBCache Struct)

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

Syntax

fn file_open_ex(&self, file_id : &String, real_file_size : i64, is_local : bool, read_block_size : i32, write_block_size : i32, prefetch_size : i64, file_context : usize) -> Option<CBFSConnectError>

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 file_set_size 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 read_block_size and write_block_size properties for a specific file. Set the parameter to 0 to make the struct use the value from the corresponding property. The values of the parameters will be used when reading_capabilities or writing_capabilities 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 on_read_data 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 on_read_data and on_write_data events fired for the file.

file_purge Method (CBCache Struct)

This method purges unmodified data from the cache.

Syntax

fn file_purge(&self, file_id : &String) -> Option<CBFSConnectError>

Remarks

This method removes unmodified data from the cache.

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

file_read Method (CBCache Struct)

This method reads the specified part of a cached file.

Syntax

fn file_read(&self, file_id : &String, position : i64, buffer : &[u8], index : i32, count : i32) ->  Result<bool, CBFSConnectError>

Remarks

This method reads data from the cached file identified by FileId into the specified Buffer. The cached file must be opened using file_open 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.

file_set_pinned Method (CBCache Struct)

This method sets the pinned state of a cached file.

Syntax

fn file_set_pinned(&self, file_id : &String, pinned : bool) -> Option<CBFSConnectError>

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 file_purge method.

file_set_size Method (CBCache Struct)

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

Syntax

fn file_set_size(&self, file_id : &String, new_size : i64, fetch_missing_data : bool) -> Option<CBFSConnectError>

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 file_open 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 read_block_size and write_block_size properties for a specific file. Set the parameter to 0 to make the struct use the value from the corresponding property. The values of the parameters will be used when reading_capabilities or writing_capabilities 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).

file_set_size_ex Method (CBCache Struct)

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

Syntax

fn file_set_size_ex(&self, file_id : &String, new_size : i64, read_block_size : i32, write_block_size : i32, fetch_missing_data : bool) -> Option<CBFSConnectError>

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 file_open 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 read_block_size and write_block_size properties for a specific file. Set the parameter to 0 to make the struct use the value from the corresponding property. The values of the parameters will be used when reading_capabilities or writing_capabilities 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).

file_tag_delete Method (CBCache Struct)

This method deletes a file tag.

Syntax

fn file_tag_delete(&self, file_id : &String, tag_id : i32) -> Option<CBFSConnectError>

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.

file_tag_exists Method (CBCache Struct)

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

Syntax

fn file_tag_exists(&self, file_id : &String, tag_id : i32) ->  Result<bool, CBFSConnectError>

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.

file_tag_get Method (CBCache Struct)

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

Syntax

fn file_tag_get(&self, file_id : &String, tag_id : i32) ->  Result<Vec<u8>, CBFSConnectError>

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 .

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.

file_tag_get_size Method (CBCache Struct)

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

Syntax

fn file_tag_get_size(&self, file_id : &String, tag_id : i32) ->  Result<i32, CBFSConnectError>

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.

file_tag_set Method (CBCache Struct)

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

Syntax

fn file_tag_set(&self, file_id : &String, tag_id : i32, data : &[u8]) -> Option<CBFSConnectError>

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.

file_touch Method (CBCache Struct)

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

Syntax

fn file_touch(&self, file_id : &String, position : i64, count : i32, flush : bool) -> Option<CBFSConnectError>

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 on_read_data, and then will write out all data in the touched range via on_write_data. 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.

file_write Method (CBCache Struct)

This method writes the specified part of a cached file.

Syntax

fn file_write(&self, file_id : &String, position : i64, buffer : &[u8], index : i32, count : i32) ->  Result<bool, CBFSConnectError>

Remarks

This method writes data to the cached file identified by FileId from the specified Buffer. The cached file must be opened using file_open 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 on_write_data 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.

get_next_enumerated_file Method (CBCache Struct)

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

Syntax

fn get_next_enumerated_file(&self, enumeration_handle : i64) ->  Result<String, CBFSConnectError>

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 struct will close the enumeration automatically by calling close_enumeration. If the application finishes enumeration without reaching the end of the list, it must call the close_enumeration method to release any associated resources.

open_cache Method (CBCache Struct)

This method opens the cache.

Syntax

fn open_cache(&self, encryption_password : &String, case_sensitive : bool) -> Option<CBFSConnectError>

Remarks

This method opens the cache specified by the cache_file property; creating a storage file for it in the directory specified by the cache_directory 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.

refresh_statistics Method (CBCache Struct)

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

Syntax

fn refresh_statistics(&self) -> Option<CBFSConnectError>

Remarks

This method forces the cache to immediately refresh its statistics. The refreshed statistics will be reported through the on_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.

reset_error_state Method (CBCache Struct)

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

Syntax

fn reset_error_state(&self, file_id : &String) -> Option<CBFSConnectError>

Remarks

If FileId is specified, this method resets any outstanding file errors, related to the cached file identified by FileId, previously reported via on_read_data and/or on_write_data 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 on_read_data or on_write_data event, thus allowing external I/O operations to continue. If there are no outstanding external storage errors, this method does nothing.

start_cleanup Method (CBCache Struct)

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

Syntax

fn start_cleanup(&self, max_age : i32) -> Option<CBFSConnectError>

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 cancel_cleanup method.

on_before_flush Event (CBCache Struct)

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

Syntax

// CBCacheBeforeFlushEventArgs carries the CBCache BeforeFlush event's parameters.
pub struct CBCacheBeforeFlushEventArgs {
  fn file_id(&self) -> &String
  fn file_context(&self) -> usize
  fn last_use_time(&self) -> &chrono::DateTime<Utc>
  fn postpone_time(&self) -> i32
  fn set_postpone_time(&self, value : i32)
}

// CBCacheBeforeFlushEvent defines the signature of the CBCache BeforeFlush event's handler function.
pub trait CBCacheBeforeFlushEvent {
  fn on_before_flush(&self, sender : CBCache, e : &mut CBCacheBeforeFlushEventArgs);
}

impl <'a> CBCache<'a> {
  pub fn on_before_flush(&self) -> &'a dyn CBCacheBeforeFlushEvent;
  pub fn set_on_before_flush(&mut self, value : &'a dyn CBCacheBeforeFlushEvent);
  ...
}

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 file_flush, file_close, or file_close_ex 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.

on_before_purge Event (CBCache Struct)

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

Syntax

// CBCacheBeforePurgeEventArgs carries the CBCache BeforePurge event's parameters.
pub struct CBCacheBeforePurgeEventArgs {
  fn file_id(&self) -> &String
  fn file_context(&self) -> usize
  fn last_use_time(&self) -> &chrono::DateTime<Utc>
  fn postpone_time(&self) -> i32
  fn set_postpone_time(&self, value : i32)
}

// CBCacheBeforePurgeEvent defines the signature of the CBCache BeforePurge event's handler function.
pub trait CBCacheBeforePurgeEvent {
  fn on_before_purge(&self, sender : CBCache, e : &mut CBCacheBeforePurgeEventArgs);
}

impl <'a> CBCache<'a> {
  pub fn on_before_purge(&self) -> &'a dyn CBCacheBeforePurgeEvent;
  pub fn set_on_before_purge(&mut self, value : &'a dyn CBCacheBeforePurgeEvent);
  ...
}

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 file_flush, file_close, or file_close_ex 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.

on_end_cleanup Event (CBCache Struct)

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

Syntax

// CBCacheEndCleanupEventArgs carries the CBCache EndCleanup event's parameters.
pub struct CBCacheEndCleanupEventArgs {
}

// CBCacheEndCleanupEvent defines the signature of the CBCache EndCleanup event's handler function.
pub trait CBCacheEndCleanupEvent {
  fn on_end_cleanup(&self, sender : CBCache, e : &mut CBCacheEndCleanupEventArgs);
}

impl <'a> CBCache<'a> {
  pub fn on_end_cleanup(&self) -> &'a dyn CBCacheEndCleanupEvent;
  pub fn set_on_end_cleanup(&mut self, value : &'a dyn CBCacheEndCleanupEvent);
  ...
}

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.

on_error Event (CBCache Struct)

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

Syntax

// CBCacheErrorEventArgs carries the CBCache Error event's parameters.
pub struct CBCacheErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// CBCacheErrorEvent defines the signature of the CBCache Error event's handler function.
pub trait CBCacheErrorEvent {
  fn on_error(&self, sender : CBCache, e : &mut CBCacheErrorEventArgs);
}

impl <'a> CBCache<'a> {
  pub fn on_error(&self) -> &'a dyn CBCacheErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn CBCacheErrorEvent);
  ...
}

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.

on_log Event (CBCache Struct)

This log reports events that occur in the struct.

Syntax

// CBCacheLogEventArgs carries the CBCache Log event's parameters.
pub struct CBCacheLogEventArgs {
  fn level(&self) -> i32
  fn message(&self) -> &String
}

// CBCacheLogEvent defines the signature of the CBCache Log event's handler function.
pub trait CBCacheLogEvent {
  fn on_log(&self, sender : CBCache, e : &mut CBCacheLogEventArgs);
}

impl <'a> CBCache<'a> {
  pub fn on_log(&self) -> &'a dyn CBCacheLogEvent;
  pub fn set_on_log(&mut self, value : &'a dyn CBCacheLogEvent);
  ...
}

Remarks

This event fires when the struct 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:

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.

on_progress Event (CBCache Struct)

This event fires to report the progress of an operation.

Syntax

// CBCacheProgressEventArgs carries the CBCache Progress event's parameters.
pub struct CBCacheProgressEventArgs {
  fn operation(&self) -> i32
  fn current(&self) -> i64
  fn total(&self) -> i64
  fn interrupt(&self) -> bool
  fn set_interrupt(&self, value : bool)
}

// CBCacheProgressEvent defines the signature of the CBCache Progress event's handler function.
pub trait CBCacheProgressEvent {
  fn on_progress(&self, sender : CBCache, e : &mut CBCacheProgressEventArgs);
}

impl <'a> CBCache<'a> {
  pub fn on_progress(&self) -> &'a dyn CBCacheProgressEvent;
  pub fn set_on_progress(&mut self, value : &'a dyn CBCacheProgressEvent);
  ...
}

Remarks

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

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.

on_read_data Event (CBCache Struct)

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

Syntax

// CBCacheReadDataEventArgs carries the CBCache ReadData event's parameters.
pub struct CBCacheReadDataEventArgs {
  fn file_id(&self) -> &String
  fn size(&self) -> i64
  fn position(&self) -> i64
  fn flags(&self) -> i32
  fn buffer(&self) -> *mut u8
  fn bytes_to_read(&self) -> i32
  fn bytes_read(&self) -> i32
  fn set_bytes_read(&self, value : i32)
  fn file_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBCacheReadDataEvent defines the signature of the CBCache ReadData event's handler function.
pub trait CBCacheReadDataEvent {
  fn on_read_data(&self, sender : CBCache, e : &mut CBCacheReadDataEventArgs);
}

impl <'a> CBCache<'a> {
  pub fn on_read_data(&self) -> &'a dyn CBCacheReadDataEvent;
  pub fn set_on_read_data(&mut self, value : &'a dyn CBCacheReadDataEvent);
  ...
}

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 on_read_data events should be expected. It will include a combination of one or more of the following flags:

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 file_open 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:

Please refer to the Error Handling topic for more information.

on_start_cleanup Event (CBCache Struct)

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

Syntax

// CBCacheStartCleanupEventArgs carries the CBCache StartCleanup event's parameters.
pub struct CBCacheStartCleanupEventArgs {
}

// CBCacheStartCleanupEvent defines the signature of the CBCache StartCleanup event's handler function.
pub trait CBCacheStartCleanupEvent {
  fn on_start_cleanup(&self, sender : CBCache, e : &mut CBCacheStartCleanupEventArgs);
}

impl <'a> CBCache<'a> {
  pub fn on_start_cleanup(&self) -> &'a dyn CBCacheStartCleanupEvent;
  pub fn set_on_start_cleanup(&mut self, value : &'a dyn CBCacheStartCleanupEvent);
  ...
}

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.

on_status Event (CBCache Struct)

This event fires to report the latest cache statistics.

Syntax

// CBCacheStatusEventArgs carries the CBCache Status event's parameters.
pub struct CBCacheStatusEventArgs {
  fn cache_size(&self) -> i64
  fn total_data(&self) -> i64
  fn unflushed_data(&self) -> i64
  fn unflushed_files(&self) -> i32
  fn current_operation(&self) -> i32
  fn current_file_id(&self) -> &String
}

// CBCacheStatusEvent defines the signature of the CBCache Status event's handler function.
pub trait CBCacheStatusEvent {
  fn on_status(&self, sender : CBCache, e : &mut CBCacheStatusEventArgs);
}

impl <'a> CBCache<'a> {
  pub fn on_status(&self) -> &'a dyn CBCacheStatusEvent;
  pub fn set_on_status(&mut self, value : &'a dyn CBCacheStatusEvent);
  ...
}

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:

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.

on_write_data Event (CBCache Struct)

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

Syntax

// CBCacheWriteDataEventArgs carries the CBCache WriteData event's parameters.
pub struct CBCacheWriteDataEventArgs {
  fn file_id(&self) -> &String
  fn size(&self) -> i64
  fn position(&self) -> i64
  fn flags(&self) -> i32
  fn buffer(&self) -> *mut u8
  fn bytes_to_write(&self) -> i32
  fn bytes_written(&self) -> i32
  fn set_bytes_written(&self, value : i32)
  fn file_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBCacheWriteDataEvent defines the signature of the CBCache WriteData event's handler function.
pub trait CBCacheWriteDataEvent {
  fn on_write_data(&self, sender : CBCache, e : &mut CBCacheWriteDataEventArgs);
}

impl <'a> CBCache<'a> {
  pub fn on_write_data(&self) -> &'a dyn CBCacheWriteDataEvent;
  pub fn set_on_write_data(&mut self, value : &'a dyn CBCacheWriteDataEvent);
  ...
}

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 on_write_data events should be expected. It will include a combination of one or more of the following flags:

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 file_open 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:

Please refer to the Error Handling topic for more information.

Config Settings (CBCache Struct)

The struct 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 struct, access to these internal properties is provided through the config method.

CBCache Config Settings

Base Config Settings

Trappable Errors (CBCache Struct)

Cache errors Errors