CBMemoryDrive Component

Properties   Methods   Events   Config Settings   Errors  

The CBMemoryDrive component lets applications create an in-memory vault, accessible to all or some processes as a regular disk.

Syntax

callback.CBFSStorage.Cbmemorydrive

Remarks

The CBMemoryDrive component allows applications to create an in-memory vault and interact with its contents directly. A vault can contain any number of files, directories, alternate streams, and symbolic links; so long as it has sufficient capacity to store them. For more information about using CBFS Storage's many features, please refer to the extensive General Information topics.

No data is ever stored on disk, all data is stored in memory.

Getting Started

Each CBMemoryDrive component instance can control a single vault at once. Applications can use multiple instances of the CBMemoryDrive component if their use-case requires multiple vaults.

Here's how to get up and running:

1. Create or open a vault by calling the CreateVault method.
2. Interact with the vault, and its contents, using the CBMemoryDrive component's API methods.
3. When done, call the CloseVault method to close the vault.

Property List

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

Method List

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

Event List

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

Config Settings

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

AccessDeniedProcesses Property (CBMemoryDrive Component)

Collection of access rules that define which processes may not access the virtual drive.

Syntax

• C#
• VB.NET

public ProcessAccessRuleList AccessDeniedProcesses { get; }

Public ReadOnly Property AccessDeniedProcesses As ProcessAccessRuleList

Remarks

This property holds a collection of ProcessAccessRule objects representing rules that deny processes certain kinds of access to the virtual drive.

Please refer to the AddDeniedProcess and RemoveDeniedProcess methods for more information.

Note: The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

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

AccessGrantedProcesses Property (CBMemoryDrive Component)

Collection of access rules that define which processes may access the virtual drive.

Syntax

• C#
• VB.NET

public ProcessAccessRuleList AccessGrantedProcesses { get; }

Public ReadOnly Property AccessGrantedProcesses As ProcessAccessRuleList

Remarks

This property holds a collection of ProcessAccessRule objects representing rules that grant processes certain kinds of access to the virtual drive.

Please refer to the AddGrantedProcess and RemoveGrantedProcess methods for more information.

Note: The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

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

Active Property (CBMemoryDrive Component)

Whether a vault has been opened and mounted as a virtual drive.

Syntax

• C#
• VB.NET

public bool Active { get; }

Public ReadOnly Property Active As Boolean

Default Value

False

Remarks

This property reflects whether the component has opened a vault and mounted a virtual drive for it; it will be true once the CreateVault LoadFromFile method has been called successfully.

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

AutoCompactAt Property (CBMemoryDrive Component)

This property specifies the free space percentage threshold a vault must reach to be eligible for automatic compaction.

Syntax

• C#
• VB.NET

public int AutoCompactAt { get; set; }

Public Property AutoCompactAt As Integer

Default Value

25

Remarks

This property specifies the percentage of free space a vault must have, at minimum, for it to be eligible for automatic vault compaction. An eligible vault may be compacted automatically in the background at any time. Please refer to the CompactVault method for more information about the compacting process.

To guard against excessive automatic compaction operations, applications can set the AutoCompactDelay configuration setting to a nonzero value. Alternatively, this property can be set to 0 to disable automatic compaction completely.

A vault opened in ReadOnly mode will never be compacted, regardless of this property's value.

Note: This property cannot be changed within events.

CaseSensitive Property (CBMemoryDrive Component)

This property specifies whether the component should open a vault in case-sensitive mode.

Syntax

• C#
• VB.NET

public bool CaseSensitive { get; set; }

Public Property CaseSensitive As Boolean

Default Value

False

Remarks

This property specifies whether the component should open a vault in case-sensitive mode. Enabling this property causes all file, directory, symbolic link, alternate stream, and file tag names to be treated as case sensitive.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

DefaultFileAccessPassword Property (CBMemoryDrive Component)

This property specifies the default encryption password to use when opening files and alternate streams.

Syntax

• C#
• VB.NET

public string DefaultFileAccessPassword { get; set; }

Public Property DefaultFileAccessPassword As String

Default Value

""

Remarks

This property specifies the default encryption password that the component should use when opening files and alternate streams.

Please refer to the Encryption topic for more information.

As an alternative to using this property, applications may call the CacheFilePassword method (before a file is opened) to specify a one-time-use password or may specify file encryption passwords dynamically using the FilePasswordNeeded event.

DefaultFileCompression Property (CBMemoryDrive Component)

This property specifies the default compression mode to use when creating files and alternate streams.

Syntax

• C#
• VB.NET

public int DefaultFileCompression { get; set; }

Public Property DefaultFileCompression As Integer

Default Value

0

Remarks

This property specifies the default compression mode that the component should use when creating files and alternate streams. Valid values are as follows:

Applications that use custom compression must implement the DataCompress and DataDecompress events. Please refer to the Compression topic for more information.

Applications can also specify a default compression level using the DefaultFileCompressionLevel configuration setting, if desired.

DefaultFileCreatePassword Property (CBMemoryDrive Component)

This property specifies the default encryption password to use when creating new files and alternate streams.

Syntax

• C#
• VB.NET

public string DefaultFileCreatePassword { get; set; }

Public Property DefaultFileCreatePassword As String

Default Value

""

Remarks

This property specifies the default encryption password that the component should use when creating new files and alternate streams.

Please refer to the Encryption topic for more information.

DefaultFileEncryption Property (CBMemoryDrive Component)

This property specifies the default encryption mode to use when creating files and alternate streams.

Syntax

• C#
• VB.NET

public int DefaultFileEncryption { get; set; }

Public Property DefaultFileEncryption As Integer

Default Value

0

Remarks

This property specifies the default encryption mode that the component should use when creating files and alternate streams. Valid values are as follows:

Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive event be implemented as well. Please refer to the Encryption topic for more information.

Applications that set this property to a value other than VAULT_EM_NONE (the default) should also specify a default encryption password using the DefaultFileCreatePassword property.

FileSystemName Property (CBMemoryDrive Component)

The name of the virtual filesystem.

Syntax

• C#
• VB.NET

public string FileSystemName { get; set; }

Public Property FileSystemName As String

Default Value

"FAT32"

Remarks

This property specifies the name of the virtual filesystem. Windows, and some other applications, use this name to identify the filesystem.

In general, the filesystem name can be any reasonable string up to 10 characters in length. However, some versions of Windows and some third-party programs may behave differently when they encounter an unknown filesystem name (i.e., anything other than FAT, FAT32, exFAT, NTFS, etc.). Applications should keep this restriction in mind when choosing a filesystem name.

This property is set to FAT32 by default, which may cause some applications to fail when attempting to copy large (>4GB) files to and from the virtual drive. It is recommended that applications set this property to exFAT if such issues occur.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

IsCorrupted Property (CBMemoryDrive Component)

This property specifies whether the vault is corrupted.

Syntax

• C#
• VB.NET

public bool IsCorrupted { get; }

Public ReadOnly Property IsCorrupted As Boolean

Default Value

False

Remarks

This property reflects whether the currently open vault is corrupted, as indicated by the presence of the VAULT_ST_CORRUPTED flag in the VaultState property.

The VAULT_ST_CORRUPTED flag is set automatically anytime the component detects that a vault's integrity has been compromised. Calling the CheckAndRepair method for a corrupted vault will clear the flag.

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

LastWriteTime Property (CBMemoryDrive Component)

This property specifies the last modification time of the vault.

Syntax

• C#
• VB.NET

public DateTime LastWriteTime { get; }

Public ReadOnly Property LastWriteTime As DateTime

Default Value

0

Remarks

This property reflects the vault's last modification time, specified in UTC.

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

Logo Property (CBMemoryDrive Component)

This property specifies an application-defined text-based logo stored in the second page of a vault.

Syntax

• C#
• VB.NET

public string Logo { get; set; }

Public Property Logo As String

Default Value

"CBFS Vault"

Remarks

This property is used to control a vault's logo, which is a UTF-16LE string stored in the second page of a vault. A vault's logo is visible to anyone who inspects its raw data and thus can be used to provide information about the vault itself.

Vault logos can be up to 127 characters long (not including the null terminator).

Note: This property cannot be changed within events.

MountingPoints Property (CBMemoryDrive Component)

Collection of mounting points for the virtual drive.

Syntax

• C#
• VB.NET

public MountingPointList MountingPoints { get; }

Public ReadOnly Property MountingPoints As MountingPointList

Remarks

This property holds a collection of MountingPoint objects, each of which represents an available mounting point for the virtual drive.

Please refer to the AddMountingPoint and RemoveMountingPoint methods for more information.

Note: The methods and properties related to mounting points are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of mounting points occurs in a thread-safe manner.

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

OpenFiles Property (CBMemoryDrive Component)

Collection of information about the objects in the virtual drive that are currently open.

Syntax

• C#
• VB.NET

public OpenFileList OpenFiles { get; }

Public ReadOnly Property OpenFiles As OpenFileList

Remarks

This property holds a collection of OpenFile objects representing filesystem objects (files, directories, etc.) from the virtual drive that are currently open. The collection is populated anytime CreateOpenedFilesSnapshot is called, and cleared when CloseOpenedFilesSnapshot is called; please refer to those methods for more information.

Note: The methods and properties related to open files snapshots are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that creation, use, and cleanup of open files snapshots occurs in a thread-safe manner.

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

PageSize Property (CBMemoryDrive Component)

This property specifies the vault's page size.

Syntax

• C#
• VB.NET

public int PageSize { get; set; }

Public Property PageSize As Integer

Default Value

4096

Remarks

This property controls the page size used when creating new vaults and reflects the page size of the currently open vault. Valid values are 256 through 65536 bytes (inclusive).

A vault's page size is permanent, it cannot be changed after the vault is created. Please refer to the Vaults topic for more information.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

PathSeparator Property (CBMemoryDrive Component)

This property specifies the path separator character to use when returning vault paths.

Syntax

• C#
• VB.NET

public int PathSeparator { get; set; }

Public Property PathSeparator As Integer

Default Value

92

Remarks

This property specifies the path separator character that the component APIs should use when returning a vault path. Valid values are as follows:

Note: This property is just a convenience; applications are free to use either of the above characters as path separators when passing path strings to the component's APIs.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

PossibleFreeSpace Property (CBMemoryDrive Component)

This property specifies the maximum amount of free space the vault could possibly have available.

Syntax

• C#
• VB.NET

public long PossibleFreeSpace { get; }

Public ReadOnly Property PossibleFreeSpace As Long

Default Value

0

Remarks

This property reflects the maximum amount of free space, in bytes, that the vault could possibly have available. That is, it is the amount of free space that would be available if the vault automatically grew to its maximum PossibleSize right now, without any additional data being written to it. Therefore:

• If VaultSizeMax is 0 (unlimited): this property is equivalent to VaultFreeSpace + parent_free_space.
• If VaultSizeMax is not 0: this property is equivalent to VaultFreeSpace + min(parent_free_space, (VaultSizeMax - VaultSize)).

In both cases, parent_free_space is the amount of free space available for the vault to use for automatic growth. For a file-based vault, this is the total amount of free space on the disk where the vault's storage file (i.e., VaultFile) resides, as reported by the OS. For a Callback Mode vault, this is whatever value the application provides through the VaultGetParentSize event.

Please refer to the Vault Size topic for more information.

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

PossibleSize Property (CBMemoryDrive Component)

This property specifies the maximum size the vault could possibly be.

Syntax

• C#
• VB.NET

public long PossibleSize { get; }

Public ReadOnly Property PossibleSize As Long

Default Value

0

Remarks

This property reflects the maximum size, in bytes, that the vault could possibly be. That is, it is the size that the vault would be if it automatically grew as much as possible right now, without any additional data being written to it. Therefore:

• If VaultSizeMax is 0 (unlimited): this property is equivalent to VaultFreeSpace + parent_free_space.
• If VaultSizeMax is not 0: this property matches VaultSizeMax.

In the former case, parent_free_space is the amount of free space available for the vault to use for automatic growth. For a file-based vault, this is the total amount of free space on the disk where the vault's storage file (i.e., VaultFile) resides, as reported by the OS. For a Callback Mode vault, this is whatever value the application provides through the VaultGetParentSize event.

Please refer to the VaultSize topic for more information.

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

ProcessRestrictionsEnabled Property (CBMemoryDrive Component)

Whether process access restrictions are enabled.

Syntax

• C#
• VB.NET

public bool ProcessRestrictionsEnabled { get; set; }

Public Property ProcessRestrictionsEnabled As Boolean

Default Value

False

Remarks

This property controls whether the component should enforce per-process access restrictions; by default, it is disabled. When enabled, the AddGrantedProcess and AddDeniedProcess methods can be used to add process-specific access rules for the component to enforce across the entire virtual drive.

When an application enables this propery, it should use the AddGrantedProcess method to add at least one pocess as allowed; otherwise, the data will be inaccessible.

The current process access rules are reflected by the AccessGrantedProcesses and AccessDeniedProcesses collection properties.

Note: The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

ReadOnly Property (CBMemoryDrive Component)

This property specifies whether the component should open a vault in read-only mode.

Syntax

• C#
• VB.NET

public bool ReadOnly { get; set; }

Public Property ReadOnly As Boolean

Default Value

False

Remarks

This property specifies whether the component should open a vault in read-only mode. When a vault is opened in read-only mode, the following restrictions apply:

• No new vault items (e.g., files, directories, symbolic links, and alternate streams) may be created.
• No existing vault items may be modified, renamed, moved, or deleted. This includes updating access times.
• The vault cannot be resized or compacted (automatically or explicitly).
• Vault corruption cannot be repaired using CheckAndRepair.

Note: This list may not necessarily be exhaustive.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

ReportPossibleSize Property (CBMemoryDrive Component)

How the component should report the virtual drive's size and free space to the OS.

Syntax

• C#
• VB.NET

public bool ReportPossibleSize { get; set; }

Public Property ReportPossibleSize As Boolean

Default Value

True

Remarks

This property controls which pair of values the component should use when reporting the virtual drive's size and free space to the OS.

When this property is enabled (default), the component will use the values of the PossibleSize and PossibleFreeSpace properties. When this property is disabled, the component will use the values of the VaultSize and PossibleSize properties.

To ensure correct operation, it is recommended that applications keep this property enabled, unless a vault's size has been fixed by setting the VaultSizeMin and VaultSizeMax properties equal to each other.

Please refer to the documentation of the properties mentioned above, as well as the Vault Size topic, for more information.

Note: This property cannot be changed within events.

StorageCharacteristics Property (CBMemoryDrive Component)

The characteristic flags to create the virtual drive with (Windows only).

Syntax

• C#
• VB.NET

public int StorageCharacteristics { get; set; }

Public Property StorageCharacteristics As Integer

Default Value

16

Remarks

The system, as well as other applications, use these flags to optimize their use of the virtual drive. This property should be set by OR'ing together zero or more of the following flags:

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

StorageGUID Property (CBMemoryDrive Component)

The GUID to create the virtual drive with.

Syntax

• C#
• VB.NET

public string StorageGUID { get; set; }

Public Property StorageGUID As String

Default Value

""

Remarks

When the StorageType property is set to STGT_DISK_PNP, this property is used to specify a GUID for the virtual drive, and must be set to GUID-formatted string (e.g., {676D0357-A23A-49c3-B433-65AAD72DD282}). Otherwise, this property may be left empty; in the latter case, the driver will generate a unique value when a drive is mounted.

Some software uses a drive's GUID for the purpose of setting and maintaining certain configuration parameters. Therefore, applications are expected to use the same GUID when repeatedly creating a virtual drive that represents the same data.

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

StorageType Property (CBMemoryDrive Component)

The type of virtual drive to create (Windows only).

Syntax

• C#
• VB.NET

public int StorageType { get; set; }

Public Property StorageType As Integer

Default Value

0

Remarks

This property specifies what type of virtual drive should be created. Windows Explorer uses this information to display the appropriate icon and apply the appropriate security settings for the virtual drive. Other applications may also make use of this information in various ways.

Possible values are:

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

Plug-and-play Virtual Drives

Virtual drives created as plug-and-play (STGT_DISK_PNP) require that a "physical device" be visible in the Disk Manager snap-in of the Microsoft Management Console (mmc.exe). This can be accomplished by calling the AddMountingPoint method and including the STGMP_MOUNT_MANAGER flag in the value passed for its Flags parameter.

In addition to supporting the STGC_REMOVABLE_MEDIA StorageCharacteristics flag, which specifies whether a virtual drive's media is removable or non-removable, plug-and-play virtual drives also support the STGC_ALLOW_EJECTION flag, which specifies whether a virtual drive itself is removable or non-removable.

Tag Property (CBMemoryDrive Component)

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

Syntax

• C#
• VB.NET

public long Tag { get; set; }

Public Property Tag As Long

Default Value

0

Remarks

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

Timeout Property (CBMemoryDrive Component)

How long vault events may execute before timing out.

Syntax

• C#
• VB.NET

public int Timeout { get; set; }

Public Property Timeout As Integer

Default Value

0

Remarks

This property specifies how long the events may execute before timing out.

When this property is set to a non-zero value, and an event executes long enough for its timeout to expire, the driver cancels the underlying request by reporting an error to the OS. The tardy event still runs to completion, but any results it returns once finished are ignored since the underlying request has already been handled.

Setting this property to 0 disables event timeouts, which allows events to take as long as necessary to execute.

Note: This property cannot be changed within events.

UseAccessTime Property (CBMemoryDrive Component)

This property specifies whether the component should keep track of last access times for vault items.

Syntax

• C#
• VB.NET

public bool UseAccessTime { get; set; }

Public Property UseAccessTime As Boolean

Default Value

False

Remarks

This property specifies whether the component should update the last access time for vault items (e.g., files, directories, symbolic links, and alternate streams) every time they are accessed.

Note: Keeping track of access times will slow down operations.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

VaultEncryption Property (CBMemoryDrive Component)

This property specifies the whole-vault encryption mode.

Syntax

• C#
• VB.NET

public int VaultEncryption { get; set; }

Public Property VaultEncryption As Integer

Default Value

0

Remarks

This property controls the whole-vault encryption mode used when creating new vaults and reflects the whole-vault encryption mode of the currently open vault. Valid values are as follows:

Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive event be implemented as well. Please refer to the Encryption topic for more information.

To create a new vault with whole-vault encryption enabled, the VaultPassword property must be set as well.

When an existing vault is opened, the component updates VaultEncryption automatically based on the detected whole-vault encryption mode. If the vault is encrypted, the component will attempt to access it using the password specified by VaultPassword. If VaultPassword is incorrect, the attempt will fail and the vault will not be opened.

The VaultEncryption and VaultPassword properties cannot be used to change an open vault's whole-vault encryption mode or password; use the UpdateVaultEncryption method.

Please refer to the Encryption topic for more information.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

VaultFreeSpace Property (CBMemoryDrive Component)

This property reflects the actual amount of free space the vault has available.

Syntax

• C#
• VB.NET

public long VaultFreeSpace { get; }

Public ReadOnly Property VaultFreeSpace As Long

Default Value

0

Remarks

This property reflects the actual amount of free space, in bytes, that the vault currently has available. A vault's actual free space is based on its actual size, which is reflected by the VaultSize property.

Applications can also determine the maximum amount of free space the vault could possibly have by querying the PossibleFreeSpace property; please refer to its documentation, as well as the Vault Size topic, for more information.

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

VaultPassword Property (CBMemoryDrive Component)

This property specifies the whole-vault encryption password.

Syntax

• C#
• VB.NET

public string VaultPassword { get; set; }

Public Property VaultPassword As String

Default Value

""

Remarks

This property specifies the whole-vault encryption password to use when creating new vaults and opening existing vaults.

To create a new vault with whole-vault encryption enabled, the VaultEncryption property must be set as well.

When an existing vault is opened, the component updates VaultEncryption automatically based on the detected whole-vault encryption mode. If the vault is encrypted, the component will attempt to access it using the password specified by VaultPassword. If VaultPassword is incorrect, the attempt will fail and the vault will not be opened.

The VaultEncryption and VaultPassword properties cannot be used to change an open vault's whole-vault encryption mode or password; use the UpdateVaultEncryption method.

Please refer to the Encryption topic for more information.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

VaultSize Property (CBMemoryDrive Component)

This property specifies the actual size of the vault.

Syntax

• C#
• VB.NET

public long VaultSize { get; set; }

Public Property VaultSize As Long

Default Value

0

Remarks

This property specifies the actual size of the vault, in bytes.

Applications may use this property to explicitly resize a vault, keeping in mind the following:

• A vault cannot shrink more than its available free space allows (i.e., not by more than VaultFreeSpace bytes).
• A vault cannot shrink beyond VaultSizeMin bytes.
• If VaultSizeMax is not 0 (unlimited), a vault cannot grow beyond VaultSizeMax bytes.
• If a vault grows enough to reach or exceed its AutoCompactAt threshold, it will automatically shrink again when the next automatic compaction occurs.

Applications can determine the maximum size a vault could possibly be by querying the PossibleSize property. Please refer to the Vault Size topic for more information.

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

This property is not available at design time.

VaultSizeMax Property (CBMemoryDrive Component)

This property specifies the maximum size a vault can be.

Syntax

• C#
• VB.NET

public long VaultSizeMax { get; set; }

Public Property VaultSizeMax As Long

Default Value

0

Remarks

This property specifies the maximum size, in bytes, that a vault can be. This property must be set to 0 (unlimited), or a number greater than or equal to 8 * PageSize or VaultSizeMin (whichever is greater).

The limit imposed by this property, if any, applies to both explicit growth of a vault via the VaultSize property, and implicit growth of a vault due to storage load. Please refer to the Vault Size topic for more information.

Note: This property cannot be changed within events.

VaultSizeMin Property (CBMemoryDrive Component)

This property specifies the minimum size a vault can be.

Syntax

• C#
• VB.NET

public long VaultSizeMin { get; set; }

Public Property VaultSizeMin As Long

Default Value

0

Remarks

This property specifies the minimum size, in bytes, that a vault can be. This property's value must be less than or equal to VaultSizeMax, unless VaultSizeMax is set to 0 (unlimited).

The limit imposed by this property applies to both explicit shrinking of a vault via the VaultSize property or the CompactVault method, and implicit shrinking of a vault via automatic compaction. Please refer to the Vault Size topic for more information.

Note: This property cannot be changed within events.

VaultState Property (CBMemoryDrive Component)

This property specifies information about the state of the vault.

Syntax

• C#
• VB.NET

public int VaultState { get; }

Public ReadOnly Property VaultState As Integer

Default Value

0

Remarks

This property reflects the current state of the vault; its value consists of one or more of the following flags, ORed together:

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

AddDeniedProcess Method (CBMemoryDrive Component)

Adds a rule that prevents a process from accessing the virtual drive.

Syntax

• C#
• VB.NET

public void AddDeniedProcess(string processFileName, int processId, bool childProcesses, int desiredAccess);

Public Sub AddDeniedProcess(ByVal ProcessFileName As String, ByVal ProcessId As Integer, ByVal ChildProcesses As Boolean, ByVal DesiredAccess As Integer)

Remarks

When the ProcessRestrictionsEnabled property is enabled, this method can be used to add an access rule that denies the process specified by ProcessFileName or ProcessId the access right specified by DesiredAccess.

Processes that are already running can be specified by passing their process Id (PID) for the ProcessId parameter (in which case ProcessFileName should be empty). Processes that have not yet started can be specified by passing the full filename of the process's executable file for ProcessFileName (in which case ProcessId should be set to 0). If ProcessName is empty, and ProcessId is -1, the new rule will apply to all processes. When adding a PID-based rule, you need to be aware of the PID Reuse behavior of Windows.

ChildProcesses controls whether the rule also applies to children of the target process.

DesiredAccess specifies the access right to deny; valid values are:

To remove the process access rule later, pass the same ProcessFileName and ProcessId values to the RemoveDeniedProcess method.

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

The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

AddGrantedProcess Method (CBMemoryDrive Component)

Adds a rule that allows a process to access the virtual drive.

Syntax

• C#
• VB.NET

public void AddGrantedProcess(string processFileName, int processId, bool childProcesses, int desiredAccess);

Public Sub AddGrantedProcess(ByVal ProcessFileName As String, ByVal ProcessId As Integer, ByVal ChildProcesses As Boolean, ByVal DesiredAccess As Integer)

Remarks

When the ProcessRestrictionsEnabled property is enabled, this method can be used to add an access rule that grants the process specified by ProcessFileName or ProcessId the access right specified by DesiredAccess.

Processes that are already running can be specified by passing their process Id (PID) for the ProcessId parameter (in which case ProcessFileName should be empty). Processes that have not yet started can be specified by passing the full filename of the process's executable file for ProcessFileName (in which case ProcessId should be set to 0). If ProcessName is empty, and ProcessId is -1, the new rule will apply to all processes. When adding a PID-based rule, you need to be aware of the PID Reuse behavior of Windows.

ChildProcesses controls whether the rule also applies to children of the target process.

DesiredAccess specifies the access right to grant; valid values are:

To remove the process access rule later, pass the same ProcessFileName and ProcessId values to the RemoveGrantedProcess method.

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

The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

AddMountingPoint Method (CBMemoryDrive Component)

Adds a mounting point for the virtual drive.

Syntax

• C#
• VB.NET

public void AddMountingPoint(string mountingPoint, int flags, long authenticationId);

Public Sub AddMountingPoint(ByVal MountingPoint As String, ByVal Flags As Integer, ByVal AuthenticationId As Long)

Remarks

This method adds a new mounting point for the virtual drive (which must have already been created using OpenVault). Virtual drives may have as many mounting points as desired.

MountingPoint should be set to the name/path of the mounting point. The format of this value varies based what type of mounting point the application wishes to create; please refer to the Mounting Points topic for more information.

The Flags parameter is used to specify properties for the mounting point, and should be set by OR'ing together zero or more of the following flags:

Windows:

Linux and macOS:

For more information about the "-olocal" option of macFUSE, please refer to the macFUSE FAQ.

Windows:

If the STGMP_LOCAL flag is set, the AuthenticationId parameter should be set to the Authentication ID of the user session the mounting point should visible in; or to 0 to make the mounting point visible in the current user session. If the aforementioned flag is not set and AuthenticationId is 0, the mounting point will be global (i.e., visible in all user sessions). When AuthenticationId is set to a non-zero value, STGMP_LOCAL is implied. Please refer to the Mounting Points topic for more information.

Linux, macOS: The AuthenticationId parameter is ignored.

Note: This method cannot be called within events.

The methods and properties related to mounting points are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of mounting points occurs in a thread-safe manner.

Virtual Drives and Mounting Points

When applications call the OpenVault (CBVaultDrive) or CreateVault method, the specified vault is opened and used to create and mount a virtual drive. This virtual drive is created without a drive letter.

To add a drive letter for the virtual drive, applications have to call the AddMountingPoint method. Once a drive letter is assigned, the virtual drive will be visible to the system and other applications, allowing them to start accessing its files and directories.

CacheFilePassword Method (CBMemoryDrive Component)

This method caches an encryption password to use the next time a file or alternate stream is accessed or removes the cached password.

Syntax

• C#
• VB.NET

public void CacheFilePassword(string fileName, string password, int TTLInCache, bool removeFromCache);

Public Sub CacheFilePassword(ByVal FileName As String, ByVal Password As String, ByVal TTLInCache As Integer, ByVal RemoveFromCache As Boolean)

Remarks

This method temporarily caches an encryption password so that it can be used the next time the file or alternate stream specified by FileName is accessed.

The value passed for FileName must be a vault-local absolute path.

The Password parameter specifies the password to cache. It must match the one last used to encrypt the specified file or the alternate stream; otherwise, this method throws an exception.

The specified password is automatically removed from the cache as soon as one of the following things occur:

• The password is used to access the file or alternate stream and the value of the TTLInCache parameter is 0.
• The password for the file or alternate stream is changed.
• The vault is closed.
• The timeout expires.

To remove the previously cached password from the cache, set the RemoveFromCache parameter to true. When it is set so, the value of the Password parameter is ignored.

The TTLInCache parameter specifies time to seconds that the component keeps the password in the internal cache to reduce the number of requests for a password. The value of 0 tells the component to discard the password after the first use.

As an alternative to using this method, applications can provide a default file encryption password using the DefaultFileAccessPassword property or provide such passwords dynamically using the FilePasswordNeeded event.

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

CheckAndRepair Method (CBMemoryDrive Component)

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

Syntax

• C#
• VB.NET

public void CheckAndRepair(int flags);

Public Sub CheckAndRepair(ByVal Flags As Integer)

Remarks

This method checks the consistency of a vault and attempts to repair it as necessary.

Applications should call this method if a vault has become corrupted (i.e., if the IsCorrupted property is true, or if a vault operation fails with a "Vault Corrupted" error). Be sure to make a vault backup before calling this method, because its repair efforts may cause data loss in cases of severe corruption. Please refer to the Vault Corruption topic for more information.

The Flags parameter is used to specify additional options, and it should be set by ORing 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.

CheckFilePassword Method (CBMemoryDrive Component)

This method verifies whether a particular file password is correct.

Syntax

• C#
• VB.NET

public bool CheckFilePassword(string fileName, string password);

Public Function CheckFilePassword(ByVal FileName As String, ByVal Password As String) As Boolean

Remarks

This method verifies whether the specified Password matches the one used to encrypt the file or alternate stream specified by FileName. If the password is correct, this method returns true; otherwise, it returns false.

The value passed for FileName must be a vault-local absolute path.

Please refer to the Encryption topic for more information.

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

CheckVaultPassword Method (CBMemoryDrive Component)

This method verifies whether a particular vault password is correct.

Syntax

• C#
• VB.NET

public bool CheckVaultPassword(string password);

Public Function CheckVaultPassword(ByVal Password As String) As Boolean

Remarks

This method verifies whether the specified Password matches the one used to encrypt the vault. If the password is correct, this method returns true; otherwise, it returns false.

Please refer to the Encryption topic for more information.

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

CloseOpenedFilesSnapshot Method (CBMemoryDrive Component)

Closes the previously-created opened files snapshot.

Syntax

• C#
• VB.NET

public void CloseOpenedFilesSnapshot();

Public Sub CloseOpenedFilesSnapshot()

Remarks

This method closes the opened files snapshot previously created by CreateOpenedFilesSnapshot, releasing the memory associated with it. Please refer to that method's documentation for more information.

Note: This method cannot be called within events.

The methods and properties related to open files snapshots are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that creation, use, and cleanup of open files snapshots occurs in a thread-safe manner.

CloseVault Method (CBMemoryDrive Component)

Closes the vault.

Syntax

• C#
• VB.NET

public void CloseVault(bool force);

Public Sub CloseVault(ByVal Force As Boolean)

Remarks

This method closes the currently-open vault.

For CBVaultDrive, the Force parameter specifies whether to forcefully close any file or directory handles open currently. If Force is false, this method will fail if any handles are currently open.

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

CompactVault Method (CBMemoryDrive Component)

This method compacts the vault.

Syntax

• C#
• VB.NET

public bool CompactVault();

Public Function CompactVault() As Boolean

Remarks

This method triggers vault compaction, which is a process that shrinks a vault's overall size by truncating its free space. If the compacting operation completes successfully, this method returns true; otherwise, it returns false.

Compaction involves physically moving a vault's occupied pages to the beginning of the vault, and then truncating the unoccupied pages from the end of the vault. The runtime of a compacting operation depends on a number of factors, and it is possible for it to be interrupted by other vault operations.

Compaction occurs automatically when the vault's free space percentage exceeds the threshold specified by the AutoCompactAt property. Applications can also use the AutoCompactDelay configuration setting to add a delay to the automatic compaction trigger.

Note: A vault opened in ReadOnly mode cannot be compacted, either automatically or explicitly.

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

Config Method (CBMemoryDrive Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Public Function Config(ByVal ConfigurationString As String) As String

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

ConvertToDrivePath Method (CBMemoryDrive Component)

Converts a vault-local vault item path to a virtual drive file path (Windows only).

Syntax

• C#
• VB.NET

public string ConvertToDrivePath(string vaultFilePath);

Public Function ConvertToDrivePath(ByVal VaultFilePath As String) As String

Remarks

This method returns a virtual drive file path that corresponds to the vault item (file, directory, or symbolic link) specified by VaultFilePath.

The value passed for VaultFilePath must be a vault-local absolute path.

The value returned by this method is a fully-qualified file path formatted according to OS conventions, suitable for passing to system file APIs and/or external applications.

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

ConvertToVaultPath Method (CBMemoryDrive Component)

Converts a virtual drive file path to a vault-local vault item path (Windows only).

Syntax

• C#
• VB.NET

public string ConvertToVaultPath(string virtualFilePath);

Public Function ConvertToVaultPath(ByVal VirtualFilePath As String) As String

Remarks

This method returns the vault-local absolute path of the vault item (file, directory, or symbolic link) that corresponds to the virtual drive file path specified by VirtualFilePath.

The value passed for VirtualFilePath must be a fully-qualified file path formatted according to OS conventions.

The value returned by this method can be used to access the corresponding vault item using the component APIs.

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

CreateDirectory Method (CBMemoryDrive Component)

This method creates a new directory in the vault.

Syntax

• C#
• VB.NET

public void CreateDirectory(string directory, bool createParents);

Public Sub CreateDirectory(ByVal Directory As String, ByVal CreateParents As Boolean)

Remarks

This method creates a new directory in the vault at the path specified by Directory.

The value passed for Directory must be a vault-local absolute path.

The CreateParents parameter specifies whether nonexistent parent directories in the specified path should be created as well. If this parameter is false, and one or more parent directories are missing, this method throws an exception.

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

CreateLink Method (CBMemoryDrive Component)

This method creates a symbolic link to another file in the vault.

Syntax

• C#
• VB.NET

public void CreateLink(string linkName, string destinationName);

Public Sub CreateLink(ByVal LinkName As String, ByVal DestinationName As String)

Remarks

This method creates a new symbolic link named LinkName that points to the file specified by DestinationName.

The value passed for LinkName must be a vault-local absolute path. The value passed for DestinationName must also be a vault-local path, but it may be absolute or relative to LinkName.

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

CreateOpenedFilesSnapshot Method (CBMemoryDrive Component)

Creates a snapshot of information about files that are currently open.

Syntax

• C#
• VB.NET

public void CreateOpenedFilesSnapshot();

Public Sub CreateOpenedFilesSnapshot()

Remarks

This method creates a snapshot of information about all files and directories in the virtual filesystem that are currently open. This information is then used to populate the OpenFiles collection property.

Note that there will always be at least one item in the OpenFiles collection property since the virtual volume itself is always inherently open.

When the application is finished working with the opened files snapshot, it must close it by calling the CloseOpenedFilesSnapshot method in order to release the associated memory. If this method is called again before an existing snapshot is closed, the component will attempt to close it before creating a new one.

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

The methods and properties related to open files snapshots are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that creation, use, and cleanup of open files snapshots occurs in a thread-safe manner.

CreateVault Method (CBMemoryDrive Component)

Creates an in-memory vault.

Syntax

• C#
• VB.NET

public void CreateVault();

Public Sub CreateVault()

Remarks

This method creates a vault in memory using the properties and configuration settings, listed below. Please refer to each one's documentation for more information, including usage restrictions.

• AutoCompactAt property
• AutoCompactDelay configuration setting
• CaseSensitive property
• Logo property
• MaxNonPagedNameLength configuration setting
• PageSize property
• PathSeparator property
• ReadOnly property
• UseAccessTime property

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

DeleteFile Method (CBMemoryDrive Component)

This method deletes a vault item.

Syntax

• C#
• VB.NET

public void DeleteFile(string fileName);

Public Sub DeleteFile(ByVal FileName As String)

Remarks

This method deletes the vault item (file, directory, symbolic link, or alternate stream) specified by FileName from the vault.

The value passed for FileName must be a vault-local absolute path.

Please note the following:

• When a file is deleted, any alternate streams it contains are deleted as well.
• Directories must be empty to be deleted; otherwise, this method throws an exception. Use the IsDirectoryEmpty method to check whether a directory is empty.
• Deleting a symbolic link only deletes the link itself, not the file it points to.

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

DeleteFileTag Method (CBMemoryDrive Component)

This method deletes a file tag.

Syntax

• C#
• VB.NET

public void DeleteFileTag(string fileName, int tagId, string tagName);

Public Sub DeleteFileTag(ByVal FileName As String, ByVal TagId As Integer, ByVal TagName As String)

Remarks

This method deletes the file tag identified by TagId or TagName from the file, directory, or alternate stream specified by FileName.

The value passed for FileName must be a vault-local absolute path.

To delete a raw file tag, pass its Id for TagId and pass an empty string for TagName. To delete a typed file tag, pass its name for TagName and pass 0 for TagId. If values are provided for both TagId and TagName, this method throws an exception.

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.

FileExists Method (CBMemoryDrive Component)

This method checks whether a vault item exists.

Syntax

• C#
• VB.NET

public bool FileExists(string fileName);

Public Function FileExists(ByVal FileName As String) As Boolean

Remarks

This method checks whether a vault item (file, directory, symbolic link, or alternate stream) with the specified FileName exists in the vault. If the specified vault item exists, this method returns true; otherwise, it returns false.

The value passed for FileName must be a vault-local absolute path.

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

FileMatchesMask Method (CBMemoryDrive Component)

This method checks whether a particular file or directory name matches the specified mask.

Syntax

• C#
• VB.NET

public bool FileMatchesMask(string mask, string fileName, bool caseSensitive);

Public Function FileMatchesMask(ByVal Mask As String, ByVal FileName As String, ByVal CaseSensitive As Boolean) As Boolean

Remarks

This method checks whether the file or directory name specified by FileName matches Mask; if it does, this method returns true. The CaseSensitive parameter controls whether a case-sensitive match should be performed.

Note: This method does not handle so-called DOS_* wildcards (DOS_STAR, DOS_QM, DOS_DOT). The explanation about the characters can be found in the MSDN article. If you have a mask that includes one of those characters on Windows, you can use the RtlIsNameInExpression function of Windows API.

Note: As the explanation states, "When you do a case-insensitive search and do not provide a translation table, the name is converted to uppercase."

FileTagExists Method (CBMemoryDrive Component)

This method checks whether a file tag exists.

Syntax

• C#
• VB.NET

public bool FileTagExists(string fileName, int tagId, string tagName);

Public Function FileTagExists(ByVal FileName As String, ByVal TagId As Integer, ByVal TagName As String) As Boolean

Remarks

This method checks whether a file tag with the specified TagId or TagName is attached to the file, directory, or alternate stream specified by FileName. If the specified file tag exists, this method returns true; otherwise, it returns false.

The value passed for FileName must be a vault-local absolute path.

To check for a raw file tag, pass its Id for TagId and pass an empty string for TagName. To check for a typed file tag, pass its name for TagName and pass 0 for TagId. If values are provided for both TagId and TagName, this method throws an exception.

Please refer to the File Tags topic for more information.

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

FileTimeToNanoseconds Method (CBMemoryDrive Component)

This method returns the subsecond part of the time expressed in nanoseconds.

Syntax

• C#
• VB.NET

public int FileTimeToNanoseconds(DateTime fileTime);

Public Function FileTimeToNanoseconds(ByVal FileTime As DateTime) As Integer

Remarks

Use this method to obtain the subsecond part of the FileTime value, expressed in nanoseconds.

FileTimeToUnixTime Method (CBMemoryDrive Component)

This method converts FileTime to Unix time format.

Syntax

• C#
• VB.NET

public long FileTimeToUnixTime(DateTime fileTime);

Public Function FileTimeToUnixTime(ByVal FileTime As DateTime) As Long

Remarks

Use this method to convert the FileTime value to Unix time format. The subsecond part of the value is not preserved; to obtain it, use the FileTimeToNanoseconds method.

FindClose Method (CBMemoryDrive Component)

This method closes a search operation and releases any associated resources.

Syntax

• C#
• VB.NET

public void FindClose(long searchId);

Public Sub FindClose(ByVal SearchId As Long)

Remarks

This method closes the search operation identified by SearchId, releasing any previously allocated resources associated with it.

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

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

FindFirst Method (CBMemoryDrive Component)

This method searches for the first vault item that matches the specified name and attributes.

Syntax

• C#
• VB.NET

public long FindFirst(string fileMask, int attributes, int flags);

Public Function FindFirst(ByVal FileMask As String, ByVal Attributes As Integer, ByVal Flags As Integer) As Long

Remarks

This method initiates a search operation based on the specified FileMask, Attributes, and Flags. If there are any matching vault items (files, directories, symbolic links, or alternate streams), then a search operation Id is returned. If there are no matching vault items, then -1 is returned.

To obtain information about a search result, pass the returned search handle to the following methods:

• GetSearchResultAttributes
• GetSearchResultCreationTime
• GetSearchResultFullName
• GetSearchResultLastAccessTime
• GetSearchResultLinkDestination
• GetSearchResultMetadataSize
• GetSearchResultModificationTime
• GetSearchResultName
• GetSearchResultSize

To retrieve the next search result, pass the returned search handle to the FindNext method. When an application is finished with (or wants to abandon) a search operation, it must pass the associated search handle to the FindClose method to release the resources associated with it.

Because each search operation is identified by the search handle associated with it, applications may initiate additional search operations at any time and may process each operation's search results in any manner it desires (e.g., sequentially, round robin).

The FileMask parameter specifies both the directory path to search within and the filename mask to match against (e.g., \directory\to\search\*.txt). Or, when searching a file's alternate streams, it specifies the file path and stream name mask (e.g., \path\to\file:*). Only the mask may contain wildcards. The path must be specified in vault-local absolute format. Also note that files without an extension will match *, but not *.*.

The Attributes parameter specifies the attributes to match against; items will match only if they have one or more of the specified attributes. The value passed for this parameter should be constructed by ORing together zero or more of the following values. Passing 0 will allow any file in a directory (or, any alternate stream in a file) to match; it is equivalent to VAULT_FATTR_FILE | VAULT_FATTR_DATA_STREAM.

The Flags parameter controls search behavior. Among other things, it can be used to request that only specific pieces of information be returned, which can greatly improve performance. The value passed for this parameter should be constructed by ORing together zero or more of the following values:

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

FindFirstByQuery Method (CBMemoryDrive Component)

This method searches for the first file or directory whose file tags match the specified query.

Syntax

• C#
• VB.NET

public long FindFirstByQuery(string directory, string query, int flags);

Public Function FindFirstByQuery(ByVal Directory As String, ByVal Query As String, ByVal Flags As Integer) As Long

Remarks

This method initiates a search operation within the specified Directory for files and subdirectories whose typed file tags match the specified Query. If there are any matching files or directories, then a search operation Id is returned. If there are no matching files or directories, then -1 is returned.

To obtain information about a search result, pass the returned search handle to the following methods:

• GetSearchResultAttributes
• GetSearchResultCreationTime
• GetSearchResultFullName
• GetSearchResultLastAccessTime
• GetSearchResultLinkDestination
• GetSearchResultMetadataSize
• GetSearchResultModificationTime
• GetSearchResultName
• GetSearchResultSize

To retrieve the next search result, pass the returned search handle to the FindNext method. When an application is finished with (or wants to abandon) a search operation, it must pass the associated search handle to the FindClose method to release the resources associated with it.

Because each search operation is identified by the search handle associated with it, applications may initiate additional search operations at any time and may process each operation's search results in any manner it desires (e.g., sequentially, round robin).

The value passed for Directory must be a vault-local absolute path.

The value passed for Query must be a search query constructed using the CBFS Storage Query Language; please refer to that topic for more information.

The Flags parameter controls search behavior. Among other things, it can be used to request that only specific pieces of information be returned, which can greatly improve performance. The value passed for this parameter should be constructed by ORing together zero or more of the following values:

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

FindNext Method (CBMemoryDrive Component)

This method searches for the next vault item that matches an ongoing search operation.

Syntax

• C#
• VB.NET

public bool FindNext(long searchId);

Public Function FindNext(ByVal SearchId As Long) As Boolean

Remarks

This method searches for the next vault item (file, directory, symbolic link, or alternate stream) that matches the ongoing search operation identified by SearchId. If a matching vault item is found, this method returns true; otherwise, it returns false.

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery. Please refer to the methods' documentation for more information about search operations.

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

GetDriverStatus Method (CBMemoryDrive Component)

Retrieves the status of the system driver.

Syntax

• C#
• VB.NET

public int GetDriverStatus(string productGUID, int module);

Public Function GetDriverStatus(ByVal ProductGUID As String, ByVal Module As Integer) As Integer

Remarks

This method retrieves the status of the system driver module specified by Module. This status can then be used to verify whether it has been properly installed and is ready for use.

The value returned by the method corresponds to the dwCurrentState field of the SERVICE_STATUS structure from the Windows API. It will be one of the following:

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• Install
• Uninstall
• GetDriverStatus
• GetModuleVersion
• RegisterIcon
• UnregisterIcon
• Initialize

The Module parameter specifies which driver module to query the status of. Possible values are:

This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation in Windows topic for more information about the latter.

Note: This method cannot be called within events.

GetFileAttributes Method (CBMemoryDrive Component)

This method retrieves the attributes of a vault item.

Syntax

• C#
• VB.NET

public int GetFileAttributes(string fileName);

Public Function GetFileAttributes(ByVal FileName As String) As Integer

Remarks

This method retrieves the attributes of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The specified vault item's attributes are returned as a 32-bit integer composed of one or more of the following values:

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

GetFileCompression Method (CBMemoryDrive Component)

This method retrieves the compression mode of a file or alternate stream.

Syntax

• C#
• VB.NET

public int GetFileCompression(string fileName);

Public Function GetFileCompression(ByVal FileName As String) As Integer

Remarks

This method retrieves the compression mode of the file or alternate stream specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The returned compression mode will be one of the following values:

Applications that use custom compression must implement the DataCompress and DataDecompress events. Please refer to the Compression topic for more information.

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

GetFileCreationTime Method (CBMemoryDrive Component)

This method retrieves the creation time of a vault item.

Syntax

• C#
• VB.NET

public DateTime GetFileCreationTime(string fileName);

Public Function GetFileCreationTime(ByVal FileName As String) As DateTime

Remarks

This method retrieves the creation time of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName. The timestamps returned by this method are specified in UTC.

The value passed for FileName must be a vault-local absolute path.

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

GetFileEncryption Method (CBMemoryDrive Component)

This method retrieves the encryption mode of a file or alternate stream.

Syntax

• C#
• VB.NET

public int GetFileEncryption(string fileName);

Public Function GetFileEncryption(ByVal FileName As String) As Integer

Remarks

This method retrieves the encryption mode of the file or alternate stream specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The returned encryption mode will be one of the following values:

Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive event be implemented as well. Please refer to the Encryption topic for more information.

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

GetFileLastAccessTime Method (CBMemoryDrive Component)

This method retrieves the last access time of a vault item.

Syntax

• C#
• VB.NET

public DateTime GetFileLastAccessTime(string fileName);

Public Function GetFileLastAccessTime(ByVal FileName As String) As DateTime

Remarks

This method retrieves the creation time of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName. The timestamps returned by this method are specified in UTC.

Note: Vault items' last access times are updated only if the UseAccessTime property is enabled.

The value passed for FileName must be a vault-local absolute path.

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

GetFileModificationTime Method (CBMemoryDrive Component)

This method retrieves the modification time of a vault item.

Syntax

• C#
• VB.NET

public DateTime GetFileModificationTime(string fileName);

Public Function GetFileModificationTime(ByVal FileName As String) As DateTime

Remarks

This method retrieves the modification time of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName. The timestamps returned by this method are specified in UTC.

The value passed for FileName must be a vault-local absolute path.

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

GetFileSize Method (CBMemoryDrive Component)

This method retrieves the size of a file or alternate stream.

Syntax

• C#
• VB.NET

public long GetFileSize(string fileName);

Public Function GetFileSize(ByVal FileName As String) As Long

Remarks

This method retrieves the size, in bytes, of the file or alternate stream specified by FileName.

Note: For files, the returned value reflects only the size of the file's immediate contents, it does not account for any alternate streams the file may or may not contain.

The value passed for FileName must be a vault-local absolute path.

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

GetFileTag Method (CBMemoryDrive Component)

This method retrieves the binary data held by a raw file tag attached to the specified vault item.

Syntax

• C#
• VB.NET

public byte[] GetFileTag(string fileName, int tagId);

Public Function GetFileTag(ByVal FileName As String, ByVal TagId As Integer) As String

Remarks

This method retrieves the binary data held by a raw file tag, identified by TagId, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If a raw file tag with the specified TagId is not attached to the specified vault item, this method throws an exception.

The value passed for FileName must be a vault-local absolute path. The value passed for TagId must be in the range 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.

GetFileTagAsAnsiString Method (CBMemoryDrive Component)

This method retrieves the value of an AnsiString-typed file tag attached to the specified vault item.

Syntax

• C#
• VB.NET

public string GetFileTagAsAnsiString(string fileName, string tagName);

Public Function GetFileTagAsAnsiString(ByVal FileName As String, ByVal TagName As String) As String

Remarks

This method retrieves the value of an AnsiString-typed file tag, identified by TagName, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If an AnsiString-typed file tag with the specified TagName is not attached to the specified vault item, this method throws an exception.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

Please refer to the File Tags topic for more information.

This method can only retrieve typed file tags created with the SetFileTagAsAnsiString method. Typed file tags created with the SetFileTagAsString method must be retrieved using the GetFileTagAsString method.

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

GetFileTagAsBoolean Method (CBMemoryDrive Component)

This method retrieves the value of a Boolean-typed file tag attached to the specified vault item.

Syntax

• C#
• VB.NET

public bool GetFileTagAsBoolean(string fileName, string tagName);

Public Function GetFileTagAsBoolean(ByVal FileName As String, ByVal TagName As String) As Boolean

Remarks

This method retrieves the value of a Boolean-typed file tag, identified by TagName, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If a Boolean-typed file tag with the specified TagName is not attached to the specified vault item, this method throws an exception.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

Please refer to the File Tags topic for more information.

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

GetFileTagAsDateTime Method (CBMemoryDrive Component)

This method retrieves the value of a DateTime-typed file tag attached to the specified vault item.

Syntax

• C#
• VB.NET

public DateTime GetFileTagAsDateTime(string fileName, string tagName);

Public Function GetFileTagAsDateTime(ByVal FileName As String, ByVal TagName As String) As DateTime

Remarks

This method retrieves the value of a DateTime-typed file tag, identified by TagName, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If a DateTime-typed file tag with the specified TagName is not attached to the specified vault item, this method throws an exception.

The timestamps returned by this method are specified in UTC.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

Please refer to the File Tags topic for more information.

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

GetFileTagAsNumber Method (CBMemoryDrive Component)

This method retrieves the value of a Number-typed file tag attached to the specified vault item.

Syntax

• C#
• VB.NET

public long GetFileTagAsNumber(string fileName, string tagName);

Public Function GetFileTagAsNumber(ByVal FileName As String, ByVal TagName As String) As Long

Remarks

This method retrieves the value of a Number-typed file tag, identified by TagName, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If a Number-typed file tag with the specified TagName is not attached to the specified vault item, this method throws an exception.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

Please refer to the File Tags topic for more information.

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

GetFileTagAsString Method (CBMemoryDrive Component)

This method retrieves the value of a String-typed file tag attached to the specified vault item.

Syntax

• C#
• VB.NET

public string GetFileTagAsString(string fileName, string tagName);

Public Function GetFileTagAsString(ByVal FileName As String, ByVal TagName As String) As String

Remarks

This method retrieves the value of a String-typed file tag, identified by TagName, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If a String-typed file tag with the specified TagName is not attached to the specified vault item, this method throws an exception.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

Please refer to the File Tags topic for more information.

This method can only retrieve typed file tags created with the SetFileTagAsString method. Typed file tags created with the SetFileTagAsAnsiString method must be retrieved using the GetFileTagAsAnsiString method.

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

GetFileTagDataType Method (CBMemoryDrive Component)

This method retrieves the data type of a typed file tag attached to a specific vault item.

Syntax

• C#
• VB.NET

public int GetFileTagDataType(string fileName, string tagName);

Public Function GetFileTagDataType(ByVal FileName As String, ByVal TagName As String) As Integer

Remarks

This method retrieves the data type of a typed file tag, identified by TagName, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If a typed file tag with the specified TagName is not attached to the specified vault item, this method throws an exception.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

The value returned by this method will be one of the following (except VAULT_TDT_RAWDATA, which is not applicable):

Please refer to the File Tags topic for more information.

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

GetFileTagSize Method (CBMemoryDrive Component)

This method retrieves the size of a raw file tag attached to the specified vault item.

Syntax

• C#
• VB.NET

public int GetFileTagSize(string fileName, int tagId);

Public Function GetFileTagSize(ByVal FileName As String, ByVal TagId As Integer) As Integer

Remarks

This method retrieves the size of the binary data held by a raw file tag, identified by TagId, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If a raw file tag with the specified TagId is not attached to the specified vault item, this method returns 0 as the tag size.

The value passed for FileName must be a vault-local absolute path. The value passed for TagId must be in the range 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.

GetModuleVersion Method (CBMemoryDrive Component)

Retrieves the version of a given product module.

Syntax

• C#
• VB.NET

public long GetModuleVersion(string productGUID, int module);

Public Function GetModuleVersion(ByVal ProductGUID As String, ByVal Module As Integer) As Long

Remarks

This method retrieves the version of the product module specified by Module. The value is returned as a 64-bit integer composed of four 16-bit words that each correspond to a piece of the overall module version. For example, a version of 2.32.6.28 would cause the value 0x000200200006001C to be returned.

If the specified module is not installed, this method returns 0.

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• Install
• Uninstall
• GetDriverStatus
• GetModuleVersion
• RegisterIcon
• UnregisterIcon
• Initialize

The Module parameter specifies which driver module to query the status of. Possible values are:

This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation in Windows topic for more information about the latter.

Note: This method cannot be called within events.

GetOriginatorProcessId Method (CBMemoryDrive Component)

Retrieves the Id of the process (PID) that initiated the operation.

Syntax

• C#
• VB.NET

public int GetOriginatorProcessId();

Public Function GetOriginatorProcessId() As Integer

Remarks

This method can be called within the FilePasswordNeeded and FileAccess events to retrieve the Id of the process (PID) that initiated the operation. If the query fails, this method returns 0.

Please note that PIDs are not unique, and may be reused by different processes over time (though in practice, this is uncommon).

CBVaultDrive/Windows-specific: Applications cannot use this method to retrieve information about remote processes accessing virtual drives shared on the network. Windows does not provide such information due to the nature of remote access.

GetOriginatorProcessName Method (CBMemoryDrive Component)

Retrieves the name of the process that initiated the operation.

Syntax

• C#
• VB.NET

public string GetOriginatorProcessName();

Public Function GetOriginatorProcessName() As String

Remarks

This method can be called within the FilePasswordNeeded and and FileAccess events to retrieve the name of the process that initiated the operation. If the query fails, this method returns empty string.

CBVaultDrive/Windows-specific: Applications cannot use this method to retrieve information about remote processes accessing virtual drives shared on the network. Windows does not provide such information due to the nature of remote access.

GetOriginatorThreadId Method (CBMemoryDrive Component)

Retrieves the Id of the thread that initiated the operation (Windows only).

Syntax

• C#
• VB.NET

public int GetOriginatorThreadId();

Public Function GetOriginatorThreadId() As Integer

Remarks

This method can be called within the FilePasswordNeeded and FileAccess events to retrieve the Id of the thread that initiated the operation. If the query fails, this method returns 0.

Please note that thread Ids are not unique, and may be reused by different threads over time.

GetOriginatorToken Method (CBMemoryDrive Component)

Retrieves the security token associated with the process that initiated the operation (Windows only).

Syntax

• C#
• VB.NET

public long GetOriginatorToken();

Public Function GetOriginatorToken() As Long

Remarks

This method can be called within the FilePasswordNeeded event to retrieve the security token associated with the process that initiated the operation. If the query fails, this method returns INVALID_HANDLE_VALUE.

The security token returned by this method can be passed to the Windows API's GetTokenInformation function to obtain more information about the process.

Important: When applications are finished using the returned security token, they must close it using the Windows API's CloseHandle function.

Network Access Notes (CBVaultDrive-specific)

For virtual drives shared on the network, applications may wish to obtain information about the network users accessing it (e.g., account names). Drives can be shared in several modes in Windows, which can affect the information retrievable via the security token this method returns:

• Authenticated mode, in which case the Helper DLL (which, in general, is responsible for relaying remote drive requests to and from the system driver) will impersonate the network user, allowing that account's actual information to be retrieved.
• Guest mode, in which case the retrievable information is for the system's GUEST account.
• Administrative shares (those which exist by default and whose names end with '$'; e.g., C$, ADMIN$, etc.), in which case the retrievable information is for the LOCAL_SYSTEM account.

GetSearchResultAttributes Method (CBMemoryDrive Component)

This method retrieves the attributes of a vault item found during a search operation.

Syntax

• C#
• VB.NET

public int GetSearchResultAttributes(long searchId);

Public Function GetSearchResultAttributes(ByVal SearchId As Long) As Integer

Remarks

This method retrieves the attributes of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

The vault item's attributes are returned as a 32-bit integer composed of one or more of the following values:

If, however, attributes were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_ATTRIBUTES for the FindFirst/FindFirstByQuery method's Flags parameter), this method will always return 0. Please refer to the documentation for these methods for more information.

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

GetSearchResultCreationTime Method (CBMemoryDrive Component)

This method retrieves the creation time of a vault item found during a search operation.

Syntax

• C#
• VB.NET

public DateTime GetSearchResultCreationTime(long searchId);

Public Function GetSearchResultCreationTime(ByVal SearchId As Long) As DateTime

Remarks

This method retrieves the creation time of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

The timestamps returned by this method are specified in UTC.

If times were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_TIMES for the FindFirst/FindFirstByQuery method's Flags parameter), this method will always return January 1, 1601 00:00:00 UTC. Please refer to the documentation for these methods for more information.

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

GetSearchResultFullName Method (CBMemoryDrive Component)

This method retrieves the fully qualified name of a vault item found during a search operation.

Syntax

• C#
• VB.NET

public string GetSearchResultFullName(long searchId);

Public Function GetSearchResultFullName(ByVal SearchId As Long) As String

Remarks

This method retrieves the fully qualified name of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext as part of the search operation identified by SearchId (i.e., the vault item's vault-local absolute path). Please refer to those methods' documentation for more information.

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

If fully qualified names were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_FULL_NAME for the FindFirst/FindFirstByQuery method's Flags parameter), this method will always return an empty string. Please refer to the documentation for these methods for more information.

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

GetSearchResultLastAccessTime Method (CBMemoryDrive Component)

This method retrieves the last access time of a vault item found during a search operation.

Syntax

• C#
• VB.NET

public DateTime GetSearchResultLastAccessTime(long searchId);

Public Function GetSearchResultLastAccessTime(ByVal SearchId As Long) As DateTime

Remarks

This method retrieves the creation time of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

The timestamps returned by this method are specified in UTC.

If times were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_TIMES for the FindFirst/FindFirstByQuery method's Flags parameter), this method will always return January 1, 1601 00:00:00 UTC. Please refer to the documentation for these methods for more information.

Note: Vault items' last access times are updated only if the UseAccessTime property is enabled.

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

GetSearchResultLinkDestination Method (CBMemoryDrive Component)

This method retrieves the destination of a symbolic link found during a search operation.

Syntax

• C#
• VB.NET

public string GetSearchResultLinkDestination(long searchId);

Public Function GetSearchResultLinkDestination(ByVal SearchId As Long) As String

Remarks

This method retrieves the fully qualified name of a symbolic link found via FindFirst/FindFirstByQuery/FindNext as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

If the most recently found vault item is not a symbolic link, or if symbolic link destinations were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_LINK_DEST for the FindFirst/FindFirstByQuery method's Flags parameter), this method will always return an empty string. Please refer to the documentation for these methods for more information.

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

GetSearchResultMetadataSize Method (CBMemoryDrive Component)

This method retrieves the size of the metadata associated with a vault item found during a search operation.

Syntax

• C#
• VB.NET

public long GetSearchResultMetadataSize(long searchId);

Public Function GetSearchResultMetadataSize(ByVal SearchId As Long) As Long

Remarks

This method retrieves the size of the metadata associated with a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

The metadata size of a vault item reflects the total size of all vault pages associated with it that do not contain actual file/stream data; this includes file tags (both internal and application defined), index pages, B-trees, and all other "filesystem information".

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

If metadata sizes were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_METADATA_SIZE for the FindFirst/FindFirstByQuery method's Flags parameter), this method will always return 0. Please refer to the documentation for these methods for more information.

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

GetSearchResultModificationTime Method (CBMemoryDrive Component)

This method retrieves the modification time of a vault item found during a search operation.

Syntax

• C#
• VB.NET

public DateTime GetSearchResultModificationTime(long searchId);

Public Function GetSearchResultModificationTime(ByVal SearchId As Long) As DateTime

Remarks

This method retrieves the modification time of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

The timestamps returned by this method are specified in UTC.

If times were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_TIMES for the FindFirst/FindFirstByQuery method's Flags parameter), this method will always return January 1, 1601 00:00:00 UTC. Please refer to the documentation for these methods for more information.

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

GetSearchResultName Method (CBMemoryDrive Component)

This method retrieves the name of a vault item found during a search operation.

Syntax

• C#
• VB.NET

public string GetSearchResultName(long searchId);

Public Function GetSearchResultName(ByVal SearchId As Long) As String

Remarks

This method retrieves the name of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

The names returned by this method do not include a path; use GetSearchResultFullName if a path is needed.

If names were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_NAME for the FindFirst/FindFirstByQuery method's Flags parameter), this method will always return an empty string. Please refer to the documentation for these methods for more information.

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

GetSearchResultSize Method (CBMemoryDrive Component)

This method retrieves the size of a vault item found during a search operation.

Syntax

• C#
• VB.NET

public long GetSearchResultSize(long searchId);

Public Function GetSearchResultSize(ByVal SearchId As Long) As Long

Remarks

This method retrieves the size of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

Note: For files, the returned value reflects only the size of the file's immediate contents; it does not account for any alternate streams the file may or may not contain.

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

If the vault item is a directory, or if sizes were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_SIZE for the FindFirst/FindFirstByQuery method's Flags parameter), this method will always return 0. Please refer to the documentation for these methods for more information.

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

Initialize Method (CBMemoryDrive Component)

This method initializes the component.

Syntax

• C#
• VB.NET

public void Initialize(string productGUID);

Public Sub Initialize(ByVal ProductGUID As String)

Remarks

This method initializes the component and must be called each time the application starts before attempting to call any of the component's other methods with the exception of installation-related methods.

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• Install
• Uninstall
• GetDriverStatus
• GetModuleVersion
• RegisterIcon
• UnregisterIcon
• Initialize

If the required driver was not installed using the Install method with the same value of ProductGUID, Initialize will return a ERROR_FILE_NOT_FOUND error (Win32 error code 2).

If the loaded kernel-mode driver is older than the user-mode API, Initialize will return a ERROR_INVALID_KERNEL_INFO_VERSION error (Win32 error code 340). In this situation, an update of the driver using the Install method is required before the component can be used.

Install Method (CBMemoryDrive Component)

Installs (or upgrades) the product's system drivers and/or the helper DLL (Windows only).

Syntax

• C#
• VB.NET

public int Install(string cabFileName, string productGUID, string pathToInstall, int modulesToInstall, int flags);

Public Function Install(ByVal CabFileName As String, ByVal ProductGUID As String, ByVal PathToInstall As String, ByVal ModulesToInstall As Integer, ByVal Flags As Integer) As Integer

Remarks

This method is used to install or upgrade the product's various modules (i.e., the system drivers and the Helper DLL). The ModulesToInstall parameter selects which modules should be installed. If the system must be rebooted to complete the installation process, this method will return a non-zero value indicating which module(s) requested the reboot (out of those initially selected).

Important: To upgrade the product's modules, use only the Install method. Previously installed versions of the modules should not be uninstalled first. Calling the Install method will upgrade the previously installed version.

Please refer to the Driver Installation in Windows topic for more information.

CabFileName must be the path of the .cab file containing the product modules. Important: This .cab file must remain on the target system (or be available in some other way) after installation, as it is required for uninstalling the modules from the system.

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• Install
• Uninstall
• GetDriverStatus
• GetModuleVersion
• RegisterIcon
• UnregisterIcon
• Initialize

PathToInstall controls where the modules are installed. Pass empty string (highly recommended) to automatically install them to the appropriate Windows system directory.

ModulesToInstall should contain one or more of the following flags, OR'd together:

Flags specifies various installation options, and should contain zero or more of the following flags, OR'd together:

This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation in Windows topic for more information about the latter.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

Note: This method cannot be called within events.

IsDirectoryEmpty Method (CBMemoryDrive Component)

This method checks whether a directory is empty.

Syntax

• C#
• VB.NET

public bool IsDirectoryEmpty(string directory);

Public Function IsDirectoryEmpty(ByVal Directory As String) As Boolean

Remarks

This method checks whether the directory specified by Directory is empty (i.e., does not contain any files, subdirectories, or symbolic links). If the specified directory is empty, this method returns true; otherwise, it returns false.

The value passed for Directory must be a vault-local absolute path.

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

IsIconRegistered Method (CBMemoryDrive Component)

Checks whether the specified icon is registered (Windows only).

Syntax

• C#
• VB.NET

public bool IsIconRegistered(string iconId);

Public Function IsIconRegistered(ByVal IconId As String) As Boolean

Remarks

This method checks whether an icon with the specified IconId has been registered. If such an icon has been registered, this method returns true; otherwise it returns false.

Icons can be registered using the RegisterIcon method. Please refer to that method's documentation, as well as the Custom Drive Icons topic, for more information.

The Helper DLL must be installed in order for this method to function correctly. Applications can check to see whether the Helper DLL is installed using the GetModuleVersion method, and install it using the Install method if necessary.

LoadFromFile Method (CBMemoryDrive Component)

Copies contents of a file-based vault into the in-memory vault.

Syntax

• C#
• VB.NET

public void LoadFromFile(string fileName);

Public Sub LoadFromFile(ByVal FileName As String)

Remarks

This method loads the contents of the vault, specified by FileName, into the component.

If the in-memory vault is not opened, LoadFromFileopens an in-memory vault. If the in-memory vault is already opened, it is closed by this method.

If the vault is encrypted, then before calling LoadFromFile, the application should set proper values to VaultEncryption and VaultPassword properties.

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

MoveFile Method (CBMemoryDrive Component)

This method renames or moves a vault item.

Syntax

• C#
• VB.NET

public void MoveFile(string oldFileName, string newFileName, bool overwrite);

Public Sub MoveFile(ByVal OldFileName As String, ByVal NewFileName As String, ByVal Overwrite As Boolean)

Remarks

This method renames or moves a vault item (e.g., file, directory, symbolic link, or alternate stream) from the specified OldFileName to the specified NewFileName. For alternate streams, renaming is always possible, but moving them from one file to another is allowed only if the AllowMoveStreamsBetweenFiles configuration setting is enabled.

The values passed for OldFileName and NewFileName must both be vault-local absolute paths (including the item's old and new names, respectively) in the same vault.

The Overwrite parameter specifies what to do if a vault item with the specified NewFileName already exists. If Overwrite is true, and such an item exists, it will be overwritten by the item specified by OldFileName. But if such an item exists, and Overwrite is false, this method throws an exception.

Note: The usual rules of deletion still apply for an item being overwritten. Notably, a nonempty directory cannot be overwritten.

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

OpenFile Method (CBMemoryDrive Component)

This method opens a new or existing file or alternate stream in the vault.

Syntax

• C#
• VB.NET

public CBFSStorageStream OpenFile(string fileName, int openMode, bool readEnabled, bool writeEnabled, string password);

Public Function OpenFile(ByVal FileName As String, ByVal OpenMode As Integer, ByVal ReadEnabled As Boolean, ByVal WriteEnabled As Boolean, ByVal Password As String) As CBFSStorageStream

Remarks

This method opens the file or alternate stream specified by FileName, creating it if necessary based on the specified OpenMode, and returns a stream object that provides access to its data.

Note: Files and alternate streams cannot be created or written to if the vault is open in ReadOnly mode.

The value passed for FileName must be a vault-local absolute path.

The OpenMode parameter specifies what behavior to use when opening a file or alternate stream. Valid values are as follows:

The ReadEnabled and WriteEnabled parameters specify which kinds of access the returned stream object should permit.

Note: WriteEnabled is ignored if ReadOnly is true.

The Password parameter works as follows:

• If the specified file or alternate stream already exists and is encrypted, the specified Password is used to decrypt and access its data.
• If a new file or alternate stream is created, and the DefaultFileEncryption property is not VAULT_EM_NONE, the specified Password is used to encrypt it.

Internally, this method simply calls OpenFileEx, passing on all shared parameters' values and using the following defaults for the others:

• ShareDenyRead and ShareDenyWrite use true.
• Encryption uses the current DefaultFileEncryption value.
• Compression and CompressionLevel use the current DefaultFileCompression and DefaultFileCompressionLevel values, respectively.
• PagesPerBlock uses 16.

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

OpenFileEx Method (CBMemoryDrive Component)

This method opens a new or existing file or alternate stream in the vault.

Syntax

• C#
• VB.NET

public CBFSStorageStream OpenFileEx(string fileName, int openMode, bool readEnabled, bool writeEnabled, bool shareDenyRead, bool shareDenyWrite, int encryption, string password, int compression, int compressionLevel, int pagesPerBlock);

Public Function OpenFileEx(ByVal FileName As String, ByVal OpenMode As Integer, ByVal ReadEnabled As Boolean, ByVal WriteEnabled As Boolean, ByVal ShareDenyRead As Boolean, ByVal ShareDenyWrite As Boolean, ByVal Encryption As Integer, ByVal Password As String, ByVal Compression As Integer, ByVal CompressionLevel As Integer, ByVal PagesPerBlock As Integer) As CBFSStorageStream

Remarks

This method opens the file or alternate stream specified by FileName, creating it if necessary based on the specified OpenMode, and returns a stream object that provides access to its data.

Note: Files and alternate streams cannot be created or written to if the vault is open in ReadOnly mode.

The value passed for FileName must be a vault-local absolute path.

The OpenMode parameter specifies what behavior to use when opening a file or alternate stream. Valid values are as follows:

The ReadEnabled and WriteEnabled parameters specify which kinds of access the returned stream object should permit.

Note: WriteEnabled is ignored if ReadOnly is true.

The ShareDenyRead and ShareDenyWrite parameters specify whether other accessors may read and/or write the specified file or alternate stream simultaneously. To prevent simultaneous read and/or write access, pass true; to allow it, pass false.

The Encryption parameter specifies the encryption mode to use when creating a file or alternate stream. Valid values are as follows:

Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive event be implemented as well. Please refer to the Encryption topic for more information.

The Password parameter works as follows:

• If the specified file or alternate stream already exists and is encrypted, the specified Password is used to decrypt and access its data.
• If a file or alternate stream is created, and Encryption is not VAULT_EM_NONE, the specified Password is used to encrypt it.

The Compression parameter specifies the compression mode to use when creating a file or alternate stream. Valid values are as follows:

Applications that use custom compression must implement the DataCompress and DataDecompress events. Please refer to the Compression topic for more information.

The CompressionLevel parameter specifies the compression level to use, if applicable.

The PagesPerBlock parameter specifies how many pages should be compressed as a single block, if applicable. Valid values are powers of 2 up to and including 128 (i.e., 2, 4, 8, 16, 32, 64, or 128), or 0, which is interpreted as "default" (currently 16 for both zlib and run-length encoding [RLE]). Larger values allow for more efficient compression; however, because a block must be decompressed (and, for writes, recompressed) anytime its data are accessed, larger values can also cause excessive slowdown, especially for random access.

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

OpenRootData Method (CBMemoryDrive Component)

This method opens the vault's root data stream.

Syntax

• C#
• VB.NET

public CBFSStorageStream OpenRootData();

Public Function OpenRootData() As CBFSStorageStream

Remarks

This method opens the vault's root data stream, returning a stream object that provides access to its data.

Please refer to the Using RootData topic for more information.

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

RegisterIcon Method (CBMemoryDrive Component)

Registers an icon that can be displayed as an overlay on the virtual drive in Windows Explorer (Windows only).

Syntax

• C#
• VB.NET

public bool RegisterIcon(string iconPath, string productGUID, string iconId);

Public Function RegisterIcon(ByVal IconPath As String, ByVal ProductGUID As String, ByVal IconId As String) As Boolean

Remarks

This method registers an icon in the file specified by IconPath so that it can later be used to display an overlay on the virtual drive in Windows Explorer. If the system must be rebooted before the icon can be used, this method returns true, otherwise it returns false.

Please note that this method only registers overlay icons; Applications should call the SetIcon and ResetIcon methods to select an icon for display. Please refer to the Custom Drive Icons topic for more information.

IconPath must be the full path and file name of the .ico file whose icon should be registered. The file must exist and remain available in order for the icon to be used until the icon is unregistered using UnregisterIcon.

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• Install
• Uninstall
• GetDriverStatus
• GetModuleVersion
• RegisterIcon
• UnregisterIcon
• Initialize

IconId specifies an identifier that can later be passed to the SetIcon and UnregisterIcon methods. Each registered icon should have a unique IconId value; if a value is passed that is already in use, the existing icon will be removed (by calling UnregisterIcon internally) before the new one is registered.

This method is available in both the component API and the Installer DLL included with the product; please refer to the Driver Installation in Windows topic for more information about the latter. The Helper DLL must be installed in order for this method to function correctly. Applications can check to see whether the Helper DLL is installed using the GetModuleVersion method, and install it using the Install method if necessary.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

Note: This method cannot be called within events.

RemoveDeniedProcess Method (CBMemoryDrive Component)

Removes a rule that prevents a process from accessing the virtual drive.

Syntax

• C#
• VB.NET

public void RemoveDeniedProcess(string processFileName, int processId);

Public Sub RemoveDeniedProcess(ByVal ProcessFileName As String, ByVal ProcessId As Integer)

Remarks

When the ProcessRestrictionsEnabled property is enabled, this method can be used to remove an access rule previously added with the AddDeniedProcess method.

Pass the same values for ProcessFileName and ProcessId as were used to add the rule when AddDeniedProcess was called previously. Please refer to that method's documentation for more information.

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

The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

RemoveGrantedProcess Method (CBMemoryDrive Component)

Removes a rule that allows a process to access the virtual drive.

Syntax

• C#
• VB.NET

public void RemoveGrantedProcess(string processFileName, int processId);

Public Sub RemoveGrantedProcess(ByVal ProcessFileName As String, ByVal ProcessId As Integer)

Remarks

When the ProcessRestrictionsEnabled property is enabled, this method can be used to remove an access rule previously added with the AddGrantedProcess method.

Pass the same values for ProcessFileName and ProcessId as were used to add the rule when AddGrantedProcess was called previously. Please refer to that method's documentation for more information.

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

The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

RemoveMountingPoint Method (CBMemoryDrive Component)

Removes a mounting point for the virtual drive.

Syntax

• C#
• VB.NET

public void RemoveMountingPoint(int index, string mountingPoint, int flags, long authenticationId);

Public Sub RemoveMountingPoint(ByVal Index As Integer, ByVal MountingPoint As String, ByVal Flags As Integer, ByVal AuthenticationId As Long)

Remarks

This method removes a previously-created mounting point for the virtual drive.

Index must be set to the index of an item in the MountingPoints collection property, or to -1 to remove an item based on the other method parameters.

If Index is -1, then the same values must be passed for MountingPoint, Flags, AuthenticationId as were used to add the mounting point when AddMountingPoint was called previously. Please refer to that method's documentation for more information. (If Index is not -1, these parameters are ignored.)

The sgSTGMPDRIVELETTERNOTIFYASYNC; flag may be passed in Flags to send notifications about removal of the mounting point asynchronously. Do not use this flag if the process quits right after a call to this method because asynchronous delivery involves a secondary thread, which will be terminated when the process quits.

Note: This method cannot be called within events.

The methods and properties related to mounting points are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of mounting points occurs in a thread-safe manner.

ResetIcon Method (CBMemoryDrive Component)

Resets the virtual drive's icon back to default by deselecting the active overlay icon (Windows only).

Syntax

• C#
• VB.NET

public void ResetIcon();

Public Sub ResetIcon()

Remarks

This method deselects the overlay icon currently in use, thus resetting the virtual drive's icon back to its default state (i.e., displayed without any overlay icons).

Please refer to the SetIcon method, as well as the Custom Drive Icons topic, for more information.

The Helper DLL must be installed in order for this method to function correctly. Applications can check to see whether the Helper DLL is installed using the GetModuleVersion method, and install it using the Install method if necessary.

Note: This method can be called only after creating a virtual drive, and it cannot be called within events.

ResolveLink Method (CBMemoryDrive Component)

This method retrieves the destination of a symbolic link.

Syntax

• C#
• VB.NET

public string ResolveLink(string linkName, bool normalize);

Public Function ResolveLink(ByVal LinkName As String, ByVal Normalize As Boolean) As String

Remarks

This method retrieves the destination pointed to by the symbolic link specified by LinkName.

The value passed for LinkName must be a vault-local absolute path.

As the CreateLink method's documentation describes, symbolic links can be created with either relative or absolute vault-local paths. The Normalize parameter specifies whether the component should normalize the specified link's destination before returning it. Passing true will ensure a vault-local absolute path is always returned; passing false will cause the original destination path to be returned.

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

SaveToFile Method (CBMemoryDrive Component)

Copies contents of the in-memory vault into a file-based vault.

Syntax

• C#
• VB.NET

public void SaveToFile(string fileName);

Public Sub SaveToFile(ByVal FileName As String)

Remarks

This method saves the in-memory vault into the file specified by the FileName parameter.

The vault is saved "as is", with all parameters including encryption which were set for the in-memory vault.

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

SetFileAttributes Method (CBMemoryDrive Component)

This method sets the attributes of a vault item.

Syntax

• C#
• VB.NET

public void SetFileAttributes(string fileName, int attributes);

Public Sub SetFileAttributes(ByVal FileName As String, ByVal Attributes As Integer)

Remarks

This method sets the attributes of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The Attributes parameter specifies the new attributes for the vault item, which should be constructed by ORing together one or more of the following values:

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

SetFileCompression Method (CBMemoryDrive Component)

This method compresses or decompresses a file or alternate stream.

Syntax

• C#
• VB.NET

public void SetFileCompression(string fileName, int compression, int compressionLevel, int pagesPerBlock, string password);

Public Sub SetFileCompression(ByVal FileName As String, ByVal Compression As Integer, ByVal CompressionLevel As Integer, ByVal PagesPerBlock As Integer, ByVal Password As String)

Remarks

This method changes the compression mode used to compress the file or alternate stream specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The Compression parameter specifies the new compression mode to use. Valid values are as follows:

Applications that use custom compression must implement the DataCompress and DataDecompress events. Please refer to the Compression topic for more information.

The CompressionLevel parameter specifies the compression level to use, if applicable.

The PagesPerBlock parameter specifies how many pages should be compressed as a single block, if applicable. Valid values are powers of 2 up to and including 128 (i.e., 2, 4, 8, 16, 32, 64, or 128), or 0, which is interpreted as "default" (currently 16 for both zlib and run-length encoding [RLE]). Larger values allow for more efficient compression; however, because a block must be decompressed (and, for writes, recompressed) anytime its data are accessed, larger values can also cause excessive slowdown, especially for random access.

The Password parameter specifies the password to use to access the file's data, if it is encrypted.

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

SetFileCreationTime Method (CBMemoryDrive Component)

This method sets the creation time of a vault item.

Syntax

• C#
• VB.NET

public void SetFileCreationTime(string fileName, DateTime creationTime);

Public Sub SetFileCreationTime(ByVal FileName As String, ByVal CreationTime As DateTime)

Remarks

This method sets the creation time of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The CreationTime parameter specifies the new creation time for the vault item, which must be specified in UTC.

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

SetFileEncryption Method (CBMemoryDrive Component)

This method encrypts, decrypts, or changes the encryption password of a file or alternate stream.

Syntax

• C#
• VB.NET

public void SetFileEncryption(string fileName, int encryption, string oldPassword, string newPassword);

Public Sub SetFileEncryption(ByVal FileName As String, ByVal Encryption As Integer, ByVal OldPassword As String, ByVal NewPassword As String)

Remarks

This method changes the encryption mode or password used to encrypt the file or alternate stream specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The Encryption parameter specifies the new encryption mode to use. Valid values are as follows:

Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive event be implemented as well. Please refer to the Encryption topic for more information.

The OldPassword parameter specifies the current encryption password, if applicable.

The NewPassword parameter specifies the new encryption password to use, if applicable.

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

SetFileLastAccessTime Method (CBMemoryDrive Component)

This method sets the last access time of a vault item.

Syntax

• C#
• VB.NET

public void SetFileLastAccessTime(string fileName, DateTime lastAccessTime);

Public Sub SetFileLastAccessTime(ByVal FileName As String, ByVal LastAccessTime As DateTime)

Remarks

This method sets the last access time of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The LastAccessTime parameter specifies the new last access time for the vault item, which must be specified in UTC.

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

SetFileModificationTime Method (CBMemoryDrive Component)

This method sets the modification time of a vault item.

Syntax

• C#
• VB.NET

public void SetFileModificationTime(string fileName, DateTime modificationTime);

Public Sub SetFileModificationTime(ByVal FileName As String, ByVal ModificationTime As DateTime)

Remarks

This method sets the modification time of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The ModificationTime parameter specifies the new modification time for the vault item, which must be specified in UTC.

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

SetFileSize Method (CBMemoryDrive Component)

This method sets the size of a file or alternate stream.

Syntax

• C#
• VB.NET

public void SetFileSize(string fileName, long size, string password);

Public Sub SetFileSize(ByVal FileName As String, ByVal Size As Long, ByVal Password As String)

Remarks

This method sets the size of the file or alternate stream specified by FileName.

The value passed for FileName must be a vault-local absolute path.