CBFS Class

Properties   Methods   Events   Config Settings   Errors  

The CBFS class gives applications the ability to create a virtual filesystem.

Syntax

cbfsconnect.Cbfs

Remarks

The CBFS class is used to create a virtual filesystem whose contents are stored and exposed in an application-defined manner. The CBFS class's unique and powerful event-based design gives applications the flexibility needed to support a wide range of use cases, ranging from something as simple as translating filesystem calls to files and directories on another storage medium, to something as complex as generating the entire contents of the virtual filesystem on the fly based on some application-specific data source.

Getting Started

Each CBFS class instance controls a single virtual filesystem, and therefore a single virtual drive. Applications can use multiple instances of the CBFS class if their use case requires the creation of multiple virtual drives; the class's Tag property can be used to distinguish between instances during event handlers.

Here's how to get up and running:

1. If the system driver has not been installed yet, call the Install method to do so. This needs to be done only once.
   • In production, the system driver can be installed (or updated) ahead of time by the application's installation script using the Installer DLL. Please refer to the Driver Installation topic for more information.
2. Call the Initialize method to initialize the CBFS class. This must be done each time the application starts (if the application is using multiple CBFS class instances, only the first instance created should be used to call Initialize).
3. Ensure that all of the necessary event handlers have been implemented. Some event handlers, such as OpenFile, ReadFile, GetFileInfo, and EnumerateDirectory are mandatory and must be implemented by all applications (this is not an exhaustive list). Others are optional, and only need to be implemented when certain features are enabled. Please refer to the event's documentation for more information.
4. Create a virtual drive by calling the CreateStorage method.
5. Call the MountMedia method to "insert storage media" into the virtual drive. (This "media" can be changed at any time later using the UnmountMedia and MountMedia methods.)
6. Create one or more Mounting Points for the virtual drive using the AddMountingPoint method. A mounting point can be a drive letter, a UNC path, or a directory on an existing NTFS-formatted drive.
7. Later, the application can unmount the "media" from the virtual drive using the UnmountMedia method. At this point, the application could call the MountMedia method again to "insert different storage media".
8. To delete the virtual drive entirely, call the DeleteStorage method.
9. To uninstall the system driver, call the Uninstall method. This should not be done as part of the driver upgrade process.
   • In production, the system driver can be uninstalled by the application's uninstallation script using the Installer DLL. Please refer to the Driver Installation topic for more information.

Property List

---

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

Method List

---

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

Event List

---

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

Config Settings

---

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

AccessDeniedProcesses Property (CBFS Class)

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

Syntax

public ProcessAccessRuleList getAccessDeniedProcesses();

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.

Please refer to the ProcessAccessRule type for a complete list of fields.

AccessGrantedProcesses Property (CBFS Class)

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

Syntax

public ProcessAccessRuleList getAccessGrantedProcesses();

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.

Please refer to the ProcessAccessRule type for a complete list of fields.

Active Property (CBFS Class)

This property specifies whether the class is active and handling OS requests.

Syntax

public boolean isActive();

Default Value

False

Remarks

This property reflects whether the class is currently active and handling OS requests.

The property will be true once both CreateStorage and MountMedia have been called.

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

FileCache Property (CBFS Class)

This property specifies which file data cache implementation to use.

Syntax

public int getFileCache();


public void setFileCache(int fileCache);


Enumerated values:
  public final static int fcNone = 0;
  public final static int fcSystem = 1;
  public final static int fcInternalKernelMode = 2;
  public final static int fcInternalUserMode = 3;

Default Value

1

Remarks

This property specifies which file data cache implementation a virtual drive should use, if any. Possible values are as follows:

• fcNone (0): Do not use file data caching.
• fcSystem (1, default): Delegate file data caching to the Windows file management system cache (recommended).
• fcInternalKernelMode (2): Use the CBFS kernel mode file data cache implementation.
• fcInternalUserMode (3): Use the CBFS user mode file data cache implementation.

When the cache is enabled, commonly used file data will be cached to help reduce the number of times the ReadFile and WriteFile events are fired.

When set to fcInternalUserMode (3), the UserModeFileCacheSize configuration setting can be used to control the cache size.

Please refer to the Caching topic for detailed information on each of the cache implementations.

Note: This property cannot be changed within events.

FileSystemName Property (CBFS Class)

The name of the virtual filesystem.

Syntax

public String getFileSystemName();


public void setFileSystemName(String fileSystemName);

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.

FireAllOpenCloseEvents Property (CBFS Class)

This property specifies whether to fire events for all file open/close operations, or just the first and last.

Syntax

public boolean isFireAllOpenCloseEvents();


public void setFireAllOpenCloseEvents(boolean fireAllOpenCloseEvents);

Default Value

False

Remarks

This property specifies when the class should fire the CreateFile/OpenFile and CleanupFile/CloseFile events.

When this property is disabled (default), the class will not fire CreateFile/OpenFile for a file if another handle is already open for it. Similarly, the CleanupFile/CloseFile events will not be fired unless the handle being closed is the last handle open for the file in question. This behavior results in better overall performance because the number of event firings is minimized, but there are some drawbacks as well:

• If the file is opened only for reading initially, and then another process opens it for writing, the application will not be notified about the new mode, and may not be prepared to respond to the "unexpected" WriteFile events that will arrive should the second process start writing to the file. (Such an application may be able to mitigate this issue by always opening the file data from the backend store in read-write mode.)
• The HandleInfo parameter of various events has no effect; they carry handle-specific information that is not accessible to the application if this property is disabled.

When this property is enabled, the class fires the CreateFile/OpenFile and CleanupFile/CloseFile events every time a file handle is opened or closed.

This table shows when events will fire based on how this property is set:

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

HandleAllFsctls Property (CBFS Class)

This property specifies whether or not to fire the Fsctl event for all FSCTL_* requests.

Syntax

public boolean isHandleAllFsctls();


public void setHandleAllFsctls(boolean handleAllFsctls);

Default Value

False

Remarks

This property specifies when the class should fire the Fsctl event. When disabled (default), the Fsctl event will fire only for FSCTLs whose function codes are in the 2400-4096 range (these codes are reserved by CBFS Connect for application use). When enabled, this Fsctl will fire for every FSCTL, except those processed by CBFS Connect itself.

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

MaxFileNameLength Property (CBFS Class)

This property includes the maximum filename length supported by the virtual filesystem.

Syntax

public int getMaxFileNameLength();


public void setMaxFileNameLength(int maxFileNameLength);

Default Value

260

Remarks

This property specifies the virtual filesystem's maximum supported filename length, measured in characters. Setting this property to a value less than its default of 260 characters, which corresponds to Windows' MAX_PATH constant, is not recommended.

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

MaxFilePathLength Property (CBFS Class)

This property includes the maximum file path length supported by the virtual filesystem.

Syntax

public int getMaxFilePathLength();


public void setMaxFilePathLength(int maxFilePathLength);

Default Value

32767

Remarks

This property specifies the virtual filesystem's maximum supported file path length, measured in characters; where file path means "a string containing all directory names plus the name of the file itself". Setting this property to a value of less than 260 characters, which corresponds to Windows' MAX_PATH constant, is not recommended.

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

MaxFileSize Property (CBFS Class)

This property includes the maximum file size supported by the virtual filesystem.

Syntax

public long getMaxFileSize();


public void setMaxFileSize(long maxFileSize);

Default Value

0

Remarks

This property specifies the maximum file size, in bytes, supported by the virtual filesystem. The default value of 0 means "no limit".

Note: This property cannot be changed within events.

MetadataCacheEnabled Property (CBFS Class)

This property specifies whether or not the metadata cache should be used.

Syntax

public boolean isMetadataCacheEnabled();


public void setMetadataCacheEnabled(boolean metadataCacheEnabled);

Default Value

True

Remarks

This property controls whether the file metadata cache is enabled for a virtual drive. The size of the file metadata cache can be controlled using the MetadataCacheSize property.

When enabled, the class caches file information obtained via EnumerateDirectory and GetFileInfo events and uses the cached metadata to serve operating system requests, thus reducing how often the GetFileInfo events fire.

While a file or directory is open, its metadata is kept available in a special record called a File Control Block, regardless of whether or not the metadata cache is enabled.

For closed files and directories, the metadata is kept in the cache for the time, defined by the UnusedMetadataLifetime configuration setting.

Please refer to the Caching topic for more information.

Note: This property cannot be changed within events.

MetadataCacheSize Property (CBFS Class)

This property includes the size of the metadata cache.

Syntax

public int getMetadataCacheSize();


public void setMetadataCacheSize(int metadataCacheSize);

Default Value

2048

Remarks

This property specifies the size of the file metadata cache as a number of entries. The value must be a positive number. The maximum valid value is 65536.

Please refer to the MetadataCacheEnabled property, as well as the Caching topic, for more information.

Note: This property cannot be changed within events.

MountingPoints Property (CBFS Class)

Collection of mounting points for the virtual drive.

Syntax

public MountingPointList getMountingPoints();

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.

Please refer to the MountingPoint type for a complete list of fields.

NonExistentFilesCacheEnabled Property (CBFS Class)

This property specifies whether or not the nonexistent files cache should be used.

Syntax

public boolean isNonExistentFilesCacheEnabled();


public void setNonExistentFilesCacheEnabled(boolean nonExistentFilesCacheEnabled);

Default Value

True

Remarks

This property controls whether the nonexistent files cache is enabled for a virtual drive. The size of the nonexistent files cache can be controlled using the NonExistentFilesCacheSize property.

When enabled, the class will cache any GetFileInfo responses that indicate that the requested file does not exist. If another request is later made for the same file, the class will use this information to automatically report a file not found error rather than firing the GetFileInfo event again.

Please refer to the Caching topic for more information.

Note: This property cannot be changed within events.

NonExistentFilesCacheSize Property (CBFS Class)

This property includes the size of the nonexistent files cache.

Syntax

public int getNonExistentFilesCacheSize();


public void setNonExistentFilesCacheSize(int nonExistentFilesCacheSize);

Default Value

2048

Remarks

This property specifies the maximum size of the nonexistent files cache as a number of entries. The value must be a positive number. The maximum valid value is 65536.

Please refer to the NonExistentFilesCacheEnabled property, as well as the Caching topic, for more information.

Note: This property cannot be changed within events.

OpenFiles Property (CBFS Class)

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

Syntax

public OpenFileList getOpenFiles();

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.

Please refer to the OpenFile type for a complete list of fields.

OpenHandlesCount Property (CBFS Class)

This property includes the number of handles to filesystem objects in the virtual drive that are currently open.

Syntax

public int getOpenHandlesCount();

Default Value

0

Remarks

This property reflects the number of handles to filesystem objects (e.g., files, directories) in the virtual drive that are currently open. It is populated when CreateOpenedFilesSnapshot is called, and cleared when CloseOpenedFilesSnapshot is called; please refer to those methods for more information.

This property's value may differ from that of the OpenObjectsCount property, and from the number of items in the OpenFiles collection property. This occurs because each object can be opened several times, and because the OS may keep files open even after all handles to them have been closed.

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.

OpenObjectsCount Property (CBFS Class)

This property includes the number of filesystem objects in the virtual drive that are currently open.

Syntax

public int getOpenObjectsCount();

Default Value

0

Remarks

This property reflects the number of filesystem objects (e.g., files, directories) in the virtual drive that are currently open. It is populated when CreateOpenedFilesSnapshot is called and cleared when CloseOpenedFilesSnapshot is called; please refer to those methods for more information.

This property's value may differ from that of the OpenHandlesCount property, and from the number of items in the OpenFiles collection property. This occurs because each object can be opened several times, and because the OS may keep files open even after all handles to them have been closed.

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.

ProcessRestrictionsEnabled Property (CBFS Class)

Whether process access restrictions are enabled.

Syntax

public boolean isProcessRestrictionsEnabled();


public void setProcessRestrictionsEnabled(boolean processRestrictionsEnabled);

Default Value

False

Remarks

This property controls whether the class 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 class 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.

SerializeAccess Property (CBFS Class)

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

Syntax

public boolean isSerializeAccess();


public void setSerializeAccess(boolean serializeAccess);

Default Value

True

Remarks

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

Parallel processing can speed up operations, to a certain extent. When this property is disabled, and two or more requests (which do not change filesystem information) are made against the same file or directory, those requests are surfaced in parallel through the appropriate events (assuming that enough worker threads are available to service them at the time). By default, this property is enabled, and such requests are serialized. Please refer to the Threading and Concurrency topic for more information.

Note: For parallel processing to work, the SerializeEvents property must be disabled, and the MinWorkerThreadCount and MaxWorkerThreadCount configuration settings must be set such that parallel processing can actually occur.

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

SerializeEvents Property (CBFS Class)

Whether events should be fired on a single worker thread, or many.

Syntax

public int getSerializeEvents();


public void setSerializeEvents(int serializeEvents);


Enumerated values:
  public final static int seOnMultipleThreads = 0;
  public final static int seOnOneWorkerThread = 1;

Default Value

0

Remarks

This property specifies whether the class should fire all events serially on a single worker thread, or concurrently on multiple worker threads. The possible values are:

Please note that, in general, the class will always fire events related to a single file sequentially (though not necessarily on the same worker thread all the time), regardless of how this property is set. The one exception is that, if this property is set to seOnMultipleThreads, the SerializeAccess property can be enabled to allow multiple read requests made against a single file to execute concurrently. Please refer to the Threading and Concurrency topic for more information.

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

StorageCharacteristics Property (CBFS Class)

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

Syntax

public int getStorageCharacteristics();


public void setStorageCharacteristics(int storageCharacteristics);

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

The GUID to create the virtual drive with.

Syntax

public String getStorageGUID();


public void setStorageGUID(String storageGUID);

Default Value

""

Remarks

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.

In multiuser environments (Terminal Server, Citrix and similar software) where the application may be run concurrently by different users, using the same GUID for all users will cause a name conflict. To avoid it, mix the constant GUID value with the user-unique information such as the hash of the username or SID. This way, each user will use a constant but distinct GUID for their virtual drive.

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

StoragePresent Property (CBFS Class)

This property specifies whether a virtual drive has been created.

Syntax

public boolean isStoragePresent();

Default Value

False

Remarks

This property reflects whether a virtual drive has been created; it is automatically updated by the class whenever the virtual drive's presence changes (e.g., due to calls to CreateStorage, DeleteStorage).

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

StorageType Property (CBFS Class)

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

Syntax

public int getStorageType();


public void setStorageType(int storageType);

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.

SupportChangeTimeAttribute Property (CBFS Class)

This property specifies whether the virtual filesystem supports the ChangeTime file attribute.

Syntax

public boolean isSupportChangeTimeAttribute();


public void setSupportChangeTimeAttribute(boolean supportChangeTimeAttribute);

Default Value

False

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports the ChangeTime file attribute, which tracks the last time a file's metadata (e.g., permissions) or content was changed. The ChangeTime attribute is optional, and applications can choose not to handle it in events by simply leaving the value of the corresponding parameter unchanged.

Note: If the application is identifying its virtual filesystem (via FileSystemName) as NTFS, and this property is disabled, the class will still handle the ChangeTime attribute implicitly by setting it equal to LastWriteTime.

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

SupportCompressedAttribute Property (CBFS Class)

This property specifies whether the virtual filesystem supports the Compressed file attribute.

Syntax

public boolean isSupportCompressedAttribute();


public void setSupportCompressedAttribute(boolean supportCompressedAttribute);

Default Value

False

Remarks

When enabled, this property tells the driver to report support of compression to the operating system. When such a support is reported, processes may read or change the Compressed attribute of a file. An implementation of a virtual filesystem should provide the Compressed status through the file attributes in the GetFileInfo and EnumerateDirectory events. The attribute may be changed by the system, and such a change is communicated to the implementation by the Attributes parameter in the SetFileAttributes event.

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

SupportLastAccessTimeAttribute Property (CBFS Class)

This property specifies whether the virtual filesystem supports the LastAccessTime file attribute.

Syntax

public boolean isSupportLastAccessTimeAttribute();


public void setSupportLastAccessTimeAttribute(boolean supportLastAccessTimeAttribute);

Default Value

True

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports the LastAccessTime file attribute, which tracks the last time a file's contents were accessed.

When this property is enabled (default), a file's LastAccessTime attribute gets updated whenever the file is closed (unless fewer than 60 seconds have elapsed since the previous LastAccessTime). When this property is disabled, a file's LastAccessTime is still tracked and passed along with its LastWriteTime when the latter is changed, but it is not updated separately when the file is closed.

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

SupportODXReadWrite Property (CBFS Class)

This property specifies whether the virtual filesystem supports ODX (Offloaded Data Transfer) operations.

Syntax

public boolean isSupportODXReadWrite();


public void setSupportODXReadWrite(boolean supportODXReadWrite);

Default Value

False

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports ODX (Offloaded Data Transfer) operations. Please refer to Microsoft's Offloaded Data Transfer article for more information.

If this property is enabled, the application must properly handle the OffloadReadFile and OffloadWriteFile events, which will fire anytime the OS sends an offload read or offload write request to the virtual filesystem.

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

Tag Property (CBFS Class)

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

Syntax

public long getTag();


public void setTag(long tag);

Default Value

0

Remarks

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

UseAlternateDataStreams Property (CBFS Class)

This property specifies whether or not the virtual filesystem supports alternate data streams.

Syntax

public boolean isUseAlternateDataStreams();


public void setUseAlternateDataStreams(boolean useAlternateDataStreams);

Default Value

False

Remarks

This property specifies whether or not the virtual filesystem should indicate to the system that it supports alternate data streams (ADS, otherwise known as "named streams"). Alternate data streams can be present in both files and directories.

If this property is enabled, the application must properly handle the EnumerateNamedStreams and CloseNamedStreamsEnumeration events for alternate data streams to function correctly. Additionally, the application's GetFileInfo and EnumerateDirectory event handlers must take into account requests made by the OS to work with the alternate data streams.

Note: Alternate data streams are an expected feature of the NTFS filesystem; if the application is identifying its virtual filesystem (via FileSystemName) as NTFS, supporting alternate data streams is recommended.

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

UseCaseSensitiveFileNames Property (CBFS Class)

This property specifies whether the virtual filesystem is case-sensitive or just case-preserving.

Syntax

public boolean isUseCaseSensitiveFileNames();


public void setUseCaseSensitiveFileNames(boolean useCaseSensitiveFileNames);

Default Value

False

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it is case-sensitive (true) or just case-preserving (false; default).

Traditionally, Windows uses a case-insensitive filesystem architecture. The NTFS filesystem has a case-sensitive mode, however, to support a POSIX subsystem; enabling this property will make the class behave in a manner similar to NTFS with regards to case-sensitivity by doing the following:

• Informing Windows that it supports preserving filename casing (which the application must actually do in its code).
• Working in a case-sensitive manner when managing caches.
• Firing the GetFileInfo event to obtain a real filename if a mixed-case name is encountered.

In addition to enabling this property, a flag must be set in the registry for case-sensitive filename support to work. Specifically, in the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\kernel registry key, the DWORD ObCaseInsensitive must be set to 0.

Note: The class always attempts to work with case-sensitive filenames, regardless of how this property is set. When a file is being opened, the CBFS Connect driver looks for the name of the file in the metadata cache, if an exact match is not found, the GetFileInfo event is fired to allow the application to supply a corrected filename through the RealFileName parameter. If the application chooses not to do so, the case-insensitive name will be used.

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

UseDirectoryEmptyCheck Property (CBFS Class)

This property specifies whether the IsDirectoryEmpty event should be used.

Syntax

public boolean isUseDirectoryEmptyCheck();


public void setUseDirectoryEmptyCheck(boolean useDirectoryEmptyCheck);

Default Value

True

Remarks

This property specifies whether the class should fire the IsDirectoryEmpty event when the OS needs to check whether a directory is empty. Such checks typically are performed just before the OS requests that a directory be deleted.

If this property is enabled (default), the application must properly handle the IsDirectoryEmpty event.

Note: Use of the IsDirectoryEmpty event is efficient only if the virtual filesystem has a fast way to check whether directories contain any entries (e.g., files, subdirectories, links). If such a check would require enumerating child entries, it is more efficient for the application to disable this property and perform the check directly within the CanFileBeDeleted event instead.

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

UseDiskQuotas Property (CBFS Class)

This property specifies whether the virtual filesystem supports disk quotas.

Syntax

public boolean isUseDiskQuotas();


public void setUseDiskQuotas(boolean useDiskQuotas);

Default Value

False

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports disk quota management.

If this property is enabled, the application must properly handle the QueryQuotas, SetQuotas, GetDefaultQuotaInfo, and SetDefaultQuotaInfo events for quota management to function correctly. The GetFileNameByFileId event must be handled as well.

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

UseFileIds Property (CBFS Class)

This property specifies whether the virtual filesystem supports file Ids.

Syntax

public boolean isUseFileIds();


public void setUseFileIds(boolean useFileIds);

Default Value

True

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports File IDs.

If this property is enabled, the application must properly handle the GetFileInfo and EnumerateDirectory events and return proper file Ids for files and directories. The GetFileNameByFileId event must be handled as well.

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

UseHardLinks Property (CBFS Class)

This property specifies whether the virtual filesystem supports hard links.

Syntax

public boolean isUseHardLinks();


public void setUseHardLinks(boolean useHardLinks);

Default Value

False

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports hard links to files.

If this property is enabled, the application must properly handle the CreateHardLink, EnumerateHardLinks, and CloseHardLinksEnumeration events for hard links to function correctly. The GetFileNameByFileId event must be handled as well, and the GetFileInfo must always be sure to return the number of hard links a file has by setting the HardLinkCount event parameter appropriately.

Note: Hard links are an expected feature of the NTFS filesystem; if the application is identifying its virtual filesystem (via FileSystemName) as NTFS, supporting hard links is recommended.

Please refer to the Hard Links topic for more information.

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

UseObjectIds Property (CBFS Class)

This property specifies whether the virtual filesystem supports a volume object Id.

Syntax

public boolean isUseObjectIds();


public void setUseObjectIds(boolean useObjectIds);

Default Value

True

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports a volume object Id.

If this property is true, the application must properly handle the GetVolumeObjectId and SetVolumeObjectId events. Set this property to false to tell the OS that the volume object Id is not supported.

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

UseReparsePoints Property (CBFS Class)

This property specifies whether the virtual filesystem supports reparse points.

Syntax

public boolean isUseReparsePoints();


public void setUseReparsePoints(boolean useReparsePoints);

Default Value

False

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports reparse points.

If this property is enabled, the application must properly handle the SetReparsePoint, GetReparsePoint, and DeleteReparsePoint events for reparse points to function correctly.

Note: Reparse points are an expected feature of the NTFS filesystem; if the application is identifying its virtual filesystem (via FileSystemName) as NTFS, supporting reparse points is recommended. Reparse point support is also expected by the NFS sharing components of the OS.

Please refer to the Reparse Points topic for more information.

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

UseShortFileNames Property (CBFS Class)

This property specifies whether the virtual filesystem supports short (8.3) filenames.

Syntax

public boolean isUseShortFileNames();


public void setUseShortFileNames(boolean useShortFileNames);

Default Value

False

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports short filenames (also known as 8.3 filenames). Short filename support may be necessary for some older third-party applications to be able to access the virtual filesystem's files.

If this property is enabled, the application must be sure to return short filenames when handling the EnumerateDirectory and GetFileInfo events; and must be able to handle any event firing with a short filename rather than a normal one.

Please refer to the Short File Names topic for more information.

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

UseWindowsSecurity Property (CBFS Class)

This property specifies whether the virtual filesystem supports Windows' ACL-based security mechanisms.

Syntax

public boolean isUseWindowsSecurity();


public void setUseWindowsSecurity(boolean useWindowsSecurity);

Default Value

False

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports Windows' standard security mechanisms, which are based on ACLs (access control lists).

If this property is enabled, the application must properly handle the GetFileSecurity and SetFileSecurity events for Windows' security mechanisms to function properly.

Note: Windows' security attributes are an expected feature of the NTFS filesystem; if the application is identifying its virtual filesystem (via FileSystemName) as NTFS, supporting Windows' security attributes is recommended.

Please refer to the Security Checks topic for more information.

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

AddDeniedProcess Method (Cbfs Class)

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

Syntax

public void addDeniedProcess(String processFileName, int processId, boolean childProcesses, int desiredAccess);

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

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

Syntax

public void addGrantedProcess(String processFileName, int processId, boolean childProcesses, int desiredAccess);

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

Adds a mounting point for the virtual drive.

Syntax

public void addMountingPoint(String mountingPoint, int flags, long authenticationId);

Remarks

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

Typically, mounting points may be added before or after MountMedia is called. However, for plug-and-play virtual drives with non-removable media (see StorageType), AddMountingPoint must not be called until after the MountMedia method has been called successfully, otherwise an error will occur.

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:

If no flags are specified, the STGMP_SIMPLE flag is assumed.

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.

To create a virtual drive in a container from the host, set the container's Id via the DockerContainerId configuration setting prior to calling AddMountingPoint. Note: not all mounting point types are supported when a mounting point is created in a container. Please refer to the Docker Containers for more information.

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, Media, and Mounting Points

In the FUSE class, a mount point is specified as a parameter of the Mount method. Mounting includes both creation of a drive (virtual device) and mounting a media into this device.

The information below applies to the CBFS class.

When applications call the CreateStorage method, a virtual drive is created. Virtual drives are created without any "media" in them (like a CD drive without a CD inserted), and without any mounting points (drive letters, UNC paths, etc.).

After creating a virtual drive, applications should call MountMedia to "insert" virtual storage media into the virtual drive. This call will cause the class's events to start firing; applications must handle these events correctly, or the MountMedia call will fail.

Once media has been mounted in the virtual drive, applications should use the AddMountingPoint method to add one or more mounting points for the virtual drive. These mounting points make the virtual drive, visible to the system and other applications, allowing them to start accessing the contents of the CBFS-based virtual filesystem.

Note that applications can technically call AddMountingPoint before MountMedia (except for plug-and-play virtual drives with non-removable media; see StorageType), but any attempts to access a virtual drive with no media mounted will result in a "no media" error.

CloseOpenedFilesSnapshot Method (Cbfs Class)

Closes the previously-created opened files snapshot.

Syntax

public void 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.

Config Method (Cbfs Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

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

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

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

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

CreateOpenedFilesSnapshot Method (Cbfs Class)

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

Syntax

public void 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, as well as the OpenHandlesCount and OpenObjectsCount properties.

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

CreateStorage Method (Cbfs Class)

This method creates the virtual drive.

Syntax

public void createStorage();

Remarks

This method creates the virtual drive (without mounting points) based on the following properties and configuration settings, which cannot be changed once the virtual storage has been created:

• StorageType
• StorageCharacteristics
• StorageGUID (if applicable)
• SectorSize

Note: Many other properties, although not directly used by this method, nonetheless cannot be changed once a virtual drive is created. Such restrictions are noted where applicable.

After the virtual drive is created, use the MountMedia method to "insert storage media" into the virtual drive, and use the AddMountingPoint method to create one or more mounting points for it.

The Initialize method must have been called by some class instance in the application before calling this method.

Note: This method cannot be called within events.

Virtual Drives, Media, and Mounting Points

In the FUSE class, a mount point is specified as a parameter of the Mount method. Mounting includes both creation of a drive (virtual device) and mounting a media into this device.

The information below applies to the CBFS class.

When applications call the CreateStorage method, a virtual drive is created. Virtual drives are created without any "media" in them (like a CD drive without a CD inserted), and without any mounting points (drive letters, UNC paths, etc.).

After creating a virtual drive, applications should call MountMedia to "insert" virtual storage media into the virtual drive. This call will cause the class's events to start firing; applications must handle these events correctly, or the MountMedia call will fail.

Once media has been mounted in the virtual drive, applications should use the AddMountingPoint method to add one or more mounting points for the virtual drive. These mounting points make the virtual drive, visible to the system and other applications, allowing them to start accessing the contents of the CBFS-based virtual filesystem.

Note that applications can technically call AddMountingPoint before MountMedia (except for plug-and-play virtual drives with non-removable media; see StorageType), but any attempts to access a virtual drive with no media mounted will result in a "no media" error.

DeleteStorage Method (Cbfs Class)

This method deletes the virtual drive.

Syntax

public void deleteStorage(boolean forceUnmount);

Remarks

This method attempts to delete the virtual drive. The ForceUnmount parameter controls how this method behaves if any mounting points currently exist for the virtual drive.

If ForceUnmount is true, any existing mounting points are forcibly removed (and any open handles are closed along the way). If ForceUnmount is false and any mounting points exist for it, this method throws an exception.

Note: This method cannot be called within events.

DisableRouteCache Method (Cbfs Class)

This method disables the automatic routing of requests to local files.

Syntax

public void disableRouteCache(boolean invalidateRoutedFiles);

Remarks

This method disables the automatic routing of requests to files in the directory specified by a previous call to EnableRouteCache. Please refer to that method for more information about said request routing.

The InvalidateRoutedFiles parameter controls what happens to any handles currently open for files in the aforementioned directory: passing true will allow them to continue being used, whereas passing false will invalidate them immediately.

Note: This method cannot be called within events.

DispatchEvents Method (Cbfs Class)

Reserved, do not use.

Syntax

public void dispatchEvents();

Remarks

Reserved, do not use.

EnableRouteCache Method (Cbfs Class)

This method enables the automatic routing of requests to local files.

Syntax

public void enableRouteCache(String location, int flags);

Remarks

This method enables the automatic routing of requests to files that exist in the directory specified by Location. The Flags parameter is used to specify which kinds of requests should not be routed automatically (see below).

When automatic request routing is enabled, and a file in the virtual drive is opened, the class will immediately check the cache directory to see if a file with the same path and name exists. If such a file is found, all operations will be performed on it directly and the corresponding events will not fire (except for the operations excluded from routing by the specified Flags).

When attempting to find a matching file, the class assumes that the contents of the specified cache directory mirror that of the virtual drive. That is, the cache directory corresponds to the root of the virtual drive, and the files and directory structure are the same in each. If the class fails to find a matching file (or if the operation in question is excluded from routing), then the applicable events fire as usual.

The Flags value should be created by ORing together zero or more of the following flags:

Note: This method cannot be called within events.

FileMatchesMask Method (Cbfs Class)

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

Syntax

public boolean fileMatchesMask(String mask, String fileName, boolean caseSensitive);

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

GetDriverStatus Method (Cbfs Class)

Retrieves the status of the system driver.

Syntax

public int getDriverStatus(String productGUID, int module);

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 class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

Note: This method cannot be called within events.

GetEventFilename Method (Cbfs Class)

This method retrieves the name of the file or directory, to which the event applies.

Syntax

public String getEventFilename();

Remarks

This method can be called within event handlers of events, related to the file or directory operations, to retrieve the name of the file or directory, to which the operation applies. If the query fails or an event does not have an associated filename, this method returns an empty string.

GetHandleCreatorProcessId Method (Cbfs Class)

This method retrieves the Id of the process (PID) that opened the specified file handle.

Syntax

public int getHandleCreatorProcessId(long handleInfo);

Remarks

This method can be called within certain events to retrieve the Id of the process (PID) that opened the file handle specified by HandleInfo. The value to pass for HandleInfo should be obtained directly from the event. If the query fails, this method returns 0.

Note: PIDs are not unique and may be reused by different processes over time (although in practice, this is uncommon).

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.

Note: This method can be called only within events that expose a HandleInfo parameter, and must be called in the same thread that the event was originally fired on.

GetHandleCreatorProcessName Method (Cbfs Class)

This method retrieves the name of the process that opened the specified file handle.

Syntax

public String getHandleCreatorProcessName(long handleInfo);

Remarks

This method can be called within certain events to retrieve the name of the process that opened the file handle specified by HandleInfo. The value to pass for HandleInfo should be obtained directly from the event. If the query fails, this method returns an empty string.

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.

Note: This method can be called only within events that expose a HandleInfo parameter, and must be called in the same thread that the event was originally fired on.

GetHandleCreatorThreadId Method (Cbfs Class)

This method retrieves the Id of the thread that opened the specified file handle.

Syntax

public int getHandleCreatorThreadId(long handleInfo);

Remarks

This method can be called within certain events to retrieve the Id of the thread that opened the file handle specified by HandleInfo. The value to pass for HandleInfo should be obtained directly from the event. If the query fails, this method returns 0.

Notes: Thread Ids are not unique and may be reused by different threads over time.

Note: This method can be called only within events that expose a HandleInfo parameter, and must be called in the same thread that the event was originally fired on.

GetHandleCreatorToken Method (Cbfs Class)

This method retrieves the security token associated with the process that opened the specified file handle.

Syntax

public long getHandleCreatorToken(long handleInfo);

Remarks

This method can be called within certain events to retrieve the security token associated with the process that opened the file handle specified by HandleInfo. The value to pass for HandleInfo should be obtained directly from the event. 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. This is particularly useful for implementing custom security checks; please refer to the Security Checks topic for more information.

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

Network Access Notes

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.

Note: This method can be called only within events that expose a HandleInfo parameter, and must be called in the same thread that the event was originally fired on.

GetModuleVersion Method (Cbfs Class)

Retrieves the version of a given product module.

Syntax

public long getModuleVersion(String productGUID, int module);

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 class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

Note: This method cannot be called within events.

GetOriginatorProcessId Method (Cbfs Class)

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

Syntax

public int getOriginatorProcessId();

Remarks

This method can be called within certain 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).

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.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files , such as ReadFile and WriteFile, since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

1. Call this method within the CreateFile or OpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information via the reference stored in HandleContext.

Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

GetOriginatorProcessName Method (Cbfs Class)

Retrieves the name of the process that initiated the operation.

Syntax

public String getOriginatorProcessName();

Remarks

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

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.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files , such as ReadFile and WriteFile, since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

1. Call this method within the CreateFile or OpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information via the reference stored in HandleContext.

Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

GetOriginatorThreadId Method (Cbfs Class)

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

Syntax

public int getOriginatorThreadId();

Remarks

This method can be called within certain 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.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files , such as ReadFile and WriteFile, since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

1. Call this method within the CreateFile or OpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information via the reference stored in HandleContext.

Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

GetOriginatorToken Method (Cbfs Class)

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

Syntax

public long getOriginatorToken();

Remarks

This method can be called within certain events 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. This is particularly useful for implementing custom security checks; please refer to the Security Checks topic for more information.

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

Network Access Notes

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.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files , such as ReadFile and WriteFile, since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

1. Call this method within the CreateFile or OpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information via the reference stored in HandleContext.

Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Initialize Method (Cbfs Class)

This method initializes the class.

Syntax

public void initialize(String productGUID);

Remarks

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

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

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

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

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

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

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 class can be used.

Install Method (Cbfs Class)

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

Syntax

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

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 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 class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

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

Note: This method cannot be called within events.

IsCBFSVolume Method (Cbfs Class)

This method checks whether the specified volume is powered by CBFS.

Syntax

public boolean isCBFSVolume(String volumePath);

Remarks

This method checks to see whether the volume specified by VolumePath is powered by CBFS; if it is, this method returns true.

Valid formats for VolumePath include the following:

• Drive letters, like X:.
• Volume GUIDs, like Volume{676D0357-A23A-49C3-B433-65AAD72DD282}.

IsIconRegistered Method (Cbfs Class)

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

Syntax

public boolean isIconRegistered(String iconId);

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.

MountMedia Method (Cbfs Class)

This method mounts media in the virtual drive, making it accessible for reading and writing.

Syntax

public void mountMedia(int timeout);

Remarks

After using CreateStorage to create a virtual drive, applications should call this method to "insert storage media" into it. For plug-and-play virtual drives with nonremovable media (see StorageType), this method must be called before AddMountingPoint is called. For all other virtual drives, AddMountingPoint can be called before or after calling this method.

Timeout specifies how many milliseconds the driver will wait for events to execute before canceling the underlying OS requests ; please refer to the Timeouts topic for more information . Valid values are 0, which disables event timeouts, and values greater than or equal to 3000. (Passing a nonzero value less than 3000 will cause this method to fail with an ERROR_IMPLEMENTATION_LIMIT (1292, 0x50C) error code.)

When event timeouts are in effect, event handlers can call ResetTimeout to reset the timer if they require additional time to complete an operation.

Note: A number of properties cannot be changed once media is mounted. Such restrictions are noted in properties' documentation as applicable.

If this method encounters any issues during its execution, it throws an exception, and additional information is logged to the Windows system log as described in the Error Reporting and Handling topic.

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

Virtual Drives, Media, and Mounting Points

In the FUSE class, a mount point is specified as a parameter of the Mount method. Mounting includes both creation of a drive (virtual device) and mounting a media into this device.

The information below applies to the CBFS class.

When applications call the CreateStorage method, a virtual drive is created. Virtual drives are created without any "media" in them (like a CD drive without a CD inserted), and without any mounting points (drive letters, UNC paths, etc.).

After creating a virtual drive, applications should call MountMedia to "insert" virtual storage media into the virtual drive. This call will cause the class's events to start firing; applications must handle these events correctly, or the MountMedia call will fail.

Once media has been mounted in the virtual drive, applications should use the AddMountingPoint method to add one or more mounting points for the virtual drive. These mounting points make the virtual drive, visible to the system and other applications, allowing them to start accessing the contents of the CBFS-based virtual filesystem.

Note that applications can technically call AddMountingPoint before MountMedia (except for plug-and-play virtual drives with non-removable media; see StorageType), but any attempts to access a virtual drive with no media mounted will result in a "no media" error.

NotifyDirectoryChange Method (Cbfs Class)

This method notifies the OS that a file or directory has changed.

Syntax

public boolean notifyDirectoryChange(String fileName, int action, String newFileName, boolean wait);

Remarks

If a file or directory is modified by some means external to the virtual filesystem, this method should be called to notify the OS. Doing so prompts the OS to make any requests necessary to obtain the most up-to-date information, which in turn fires the relevant class events. This method returns either true or false to indicate whether it executed successfully.

Applications must be careful to call this method only when some changes have occurred that the OS has no possibility of detecting on its own. Said another way, applications should not call this method to notify the OS of changes made by invoking filesystem APIs on files or directories in the virtual filesystem; such changes are inherently visible to OS.

For further clarity, the following examples describe scenarios in which NotifyDirectoryChange should and should not be called:

• DO call NotifyDirectoryChange if, for example, the application is in charge of mapping the contents of some database to its virtual filesystem, and an external process changes the database's contents directly. The OS only knows about the filesystem, it does not know or care about the database contents; thus, the application must notify it that "something has changed".
• DO NOT call NotifyDirectoryChange if, for example, the application has created a virtual drive Z:, and either it or some other process makes a filesystem call against the virtual drive's contents; for example, DeleteFile("Z:\SomeFile.txt"). The OS detects such a change automatically because it was made through the filesystem APIs.

FileName specifies the path to the file or directory (in the virtual drive) that has changed. This path must not include a mounting point name.

Several files or directories may be referenced in this parameter at once. To specify the exact names, join the paths with CRLF (characters with codes #13 and #10) and pass the final string to FileName. The paths may reference files and directories in different parent directories.

An application also may specify the path with a mask. When passing a mask, only the filename portion of the mask may contain wildcard characters (* and ?). Such mask will denote multiple entries in a single directory. The class will fire the EnumerateDirectory event with the specified mask to collect the names of files and subdirectories, next they will be reported as changed.

Note: When the EnumerateDirectory event is fired, its HandleInfo, DirectoryContext, and HandleContext parameters will be empty because no system-initiated enumeration takes place and the directory is not opened.

Action specifies the type of change so that the OS knows what kind of information it needs to request. Possible values are as follows:

NewFileName specifies the new path/name of the file or directory (in the virtual drive) if the rename operation was performed. In other cases, the value is ignored.

Wait specifies whether this method should wait until the OS has finished making all of the requests necessary to handle the notification sent by this method. Passing true will cause this method to block until all requests are complete. Passing false will cause it to send the notification to the OS and return immediately, letting the OS make the necessary requests in the background. In the latter case, this method returns false.

Note: This method can be called only when Active is true. It may be called both within and outside of events; when called within an event, the Wait parameter is ignored and is assumed to be set to false.

If this method encounters any issues during its execution, it throws an exception.

RegisterIcon Method (Cbfs Class)

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

Syntax

public boolean registerIcon(String iconPath, String productGUID, String iconId);

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 class API and the Installer DLL included with the product; please refer to the Driver Installation 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.

ReleaseUnusedFiles Method (Cbfs Class)

This method instructs the OS to release any files kept open by the cache manager.

Syntax

public boolean releaseUnusedFiles();

Remarks

This method instructs the OS to release any files that the system cache manager has kept open, and returns either true or false to indicate whether the files were released successfully. Having the OS release open files can be useful in situations in which operations need to be performed while the filesystem is not in use.

Note: The OS may open additional files during the execution of this method. To guard against this, it is recommended that application use a critical section (or other synchronization object) when calling this method, and use the same one in the OpenFile event handler. Such an approach ensures that the cache manager has no files open after calling this method.

Note: This method can be called only when Active is true. It may be called both within and outside of events; when called within an event, it is executed asynchronously on another thread (causing the call to return immediately, and an ERROR_IO_PENDING result code to be reported to the OS).

RemoveDeniedProcess Method (Cbfs Class)

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

Syntax

public void removeDeniedProcess(String processFileName, int processId);

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

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

Syntax

public void removeGrantedProcess(String processFileName, int processId);

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

Removes a mounting point for the virtual drive.

Syntax

public void removeMountingPoint(int index, String mountingPoint, int flags, long authenticationId);

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.

To remove a virtual drive, created in a container from the host, set the container's Id via the DockerContainerId configuration setting prior to calling RemoveMountingPoint.

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

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

Syntax

public void 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.

ResetTimeout Method (Cbfs Class)

This method resets the timeout duration for the current event handler.

Syntax

public boolean resetTimeout(int timeout);

Remarks

When event timeouts are being enforced, this method can be called within an event handler to inform the class that request processing is taking longer than expected.

If called successfully, this method returns true, and the current event handler's timeout timer is immediately reset to 0; when it reaches the number of milliseconds specified by Timeout, the driver will cancel the underlying OS request. Please refer to the Timeouts topic for more information.

Passing 0 for Timeout disables the timeout timer for the current event handler, allowing it to take as long as it needs to complete.

Note: When several events are fired for the same file concurrently (if the SerializeAccess property is set to false), and ResetTimeout is called from one of the handlers of these events, this method will reset the timer for all currently executed event handlers.

Note: This method can be called only within events.

RouteToFile Method (Cbfs Class)

This method instructs the class to route future requests directly to a given file.

Syntax

public boolean routeToFile(long fileInfo, String fileName, int flags);

Remarks

This method can be called from within the CreateFile or OpenFile event to instruct the class to route any future requests against the file specified by FileInfo directly to the file at the path specified by FileName instead of firing the corresponding events. The Flags parameter is used to specify which kinds of requests should not be routed automatically (see below).

Pass the value obtained from the CreateFile or OpenFile event's FileInfo parameter for this method's FileInfo parameter.

This method returns either true or false to indicate whether routing was set up successfully. If, after this method is called successfully, the application later wishes for routing to cease, it may do one of the following:

• Call the NotifyDirectoryChange method, passing CBFS_NOTIFY_FLAG_METADATA_MODIFIED for its Action parameter, and the same FileName value as received in the original CreateFile or OpenFile event.
• Disable the metadata cache entirely using the MetadataCacheEnabled property.

The Flags value should be created by ORing together zero or more of the following flags:

Note: This method can be called only within the CreateFile and OpenFile event handlers.

SetIcon Method (Cbfs Class)

Selects a registered overlay icon for display on the virtual drive in Windows Explorer (Windows only).

Syntax

public void setIcon(String iconId);

Remarks

This method selects the overlay icon specified by IconId for display, causing it to be shown on the virtual drive in Windows Explorer. The desired icon must have already been registered using the RegisterIcon method, and the value passed for IconId must match the one passed RegisterIcon at that time.

To switch to a different overlay icon later, call this method again with a different IconId. To reset the virtual drive's icon back to its default state (i.e., displayed without any overlay icons), call the ResetIcon method. Please refer to 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. Also, note that the effects of this method only last until the virtual drive is destroyed; applications that always want to have some overlay icon displayed must call this method each time the virtual drive is created.

ShutdownSystem Method (Cbfs Class)

Shuts down or reboots the operating system.

Syntax

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

Remarks

This method shuts down or (if Reboot is true) reboots the operating system. If the appropriate privileges cannot be obtained, or if the InitiateSystemShutdown system call returns false, then this method will return false; otherwise, it returns true. This method can be used if the installation or uninstallation function requires the system to be rebooted in order to complete.

ShutdownPrompt, if non-empty, specifies a message that the OS should display to the user for Timeout seconds. If empty string is passed for ShutdownPrompt, no message is displayed and the Timeout parameter's value is ignored.

ForceCloseApps specifies whether the OS should forcefully close all applications. Please keep in mind that forceful closing of applications with unsaved data can lead to data loss.

Reboot specifies whether the OS should reboot (true) or just shut down (false).

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

Note: This method cannot be called within events.

Uninstall Method (Cbfs Class)

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

Syntax

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

Remarks

This method is used to uninstall the product's various modules (i.e., the system drivers and Helper DLL). If the system must be rebooted to complete the uninstallation process, this method will return a non-zero value indicating which module(s) requested the reboot (see Install for possible values).

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

Please refer to the Driver Installation topic for more information.

The same values must be passed for the CabFileName, ProductGUID, and InstalledPath parameters as were passed when Install was called; please refer to its documentation for more information.

Flags specifies which versions of the product's modules should be uninstalled, and should be set by OR'ing together one or more of the following values:

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

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

Note: This method cannot be called within events.

UnmountMedia Method (Cbfs Class)

This method unmounts media from the virtual drive.

Syntax

public void unmountMedia(boolean forceUnmount);

Remarks

This method unmounts the virtual storage media from the virtual drive. The virtual drive, as well as any existing mounting points, remain present.

If ForceUnmount is true, all open files are forcefully closed. If ForceUnmount is false and open files or directories are detected, this method throws an exception.

This method must not be called for plug-and-play virtual drives with nonremovable media (see StorageType); attempting to do so will cause the call will fail with an "access denied" error.

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

UnregisterIcon Method (Cbfs Class)

Unregisters an existing overlay icon (Windows only).

Syntax

public boolean unregisterIcon(String productGUID, String iconId);

Remarks

This method unregisters the overlay icon identified by IconId. If the system must be rebooted to completely remove the icon, this method returns true, otherwise it returns false.

The same values must be passed for the ProductGUID and IconId parameters as were passed when RegisterIcon was called; please refer to its documentation, as well as the Custom Drive Icons topic, for more information.

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter. 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.

CanFileBeDeleted Event (Cbfs Class)

This event fires when the driver needs to know whether a file or directory can be deleted.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void canFileBeDeleted(CbfsCanFileBeDeletedEvent e) {}
  ...
}

public class CbfsCanFileBeDeletedEvent {
  public String fileName;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public boolean canBeDeleted;
  public int resultCode;
}

Remarks

This event fires when the driver needs to know whether the file or directory specified by FileName can be deleted.

To handle this event properly, applications must set the CanBeDeleted parameter appropriately.

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

Note: The firing of this event does not necessarily mean the specified file or directory will be deleted if CanBeDeleted is set to true. It means only that the OS needs to know whether or not it can be deleted.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

CleanupFile Event (Cbfs Class)

This event fires when the OS needs to clean up a file.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void cleanupFile(CbfsCleanupFileEvent e) {}
  ...
}

public class CbfsCleanupFileEvent {
  public String fileName;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS needs to close a handle to the currently open file specified by FileName. This event differs from CloseFile in that CleanupFile fires immediately when an open handle to the specified file is closed by a process, whereas CloseFile may be fired much later when the OS itself decides that the file can be formally closed. Similar to CloseFile, however, this event will fire only for the last handle to a file if the FireAllOpenCloseEvents property is disabled.

Other events may fire for the file handle in the time between when this event fires and when the CloseFile event fires. For example, system components such as the memory manager or cache manager may cause the ReadFile and WriteFile events to fire.

This event is optional; it is provided to give applications a chance to, for example, free up resources associated with a file before it's formally closed.

When the FireAllOpenCloseEvents is set to false, this event is fired each time the file is closed by the application. When the file is opened and closed by some process multiple times consequently, the event handler can end up being called multiple times seemingly without a match with the OpenFile and CloseFile . However, such behavior is correct. The exact order of Open/Cleanup/Close events cannot be guaranteed because of the way Windows closes files.

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

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

CloseDirectoryEnumeration Event (Cbfs Class)

This event fires when the OS is finished enumerating a directory's contents.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void closeDirectoryEnumeration(CbfsCloseDirectoryEnumerationEvent e) {}
  ...
}

public class CbfsCloseDirectoryEnumerationEvent {
  public String directoryName;
  public long directoryContext;
  public long enumerationContext;
  public int resultCode;
}

Remarks

This event fires when the OS is finished enumerating the contents of the directory specified by DirectoryName.

To handle this event properly, applications must release any resources that were allocated for/by the directory enumeration in earlier EnumerateDirectory events.

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

The DirectoryContext and EnumerationContext parameters are placeholders for application-defined data associated with the directory and enumeration, respectively. Please refer to the Contexts topic for more information about them.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

CloseFile Event (Cbfs Class)

This event fires when the OS needs to close a file.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void closeFile(CbfsCloseFileEvent e) {}
  ...
}

public class CbfsCloseFileEvent {
  public String fileName;
  public boolean pendingDeletion;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS needs to close the file specified by FileName. If the FireAllOpenCloseEvents property is disabled, this event will fire only after the last handle to the specified file is closed.

To handle this event properly, applications can (if necessary/applicable) check to see if any other handles are open for the file, and if not, close whatever backend resources are currently open for it.

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

The PendingDeletion parameter indicates whether the file should be deleted; if it's true, the DeleteFile event will fire immediately after this event. The application may delete the file from either event handler.

If an application uses some object to store user context, uses FileContext to store the reference to this object, and deletes an object referenced in FileContext, the pointer stored in FileContext becomes invalid. In this scenario, if the PendingDeletion parameter is true, the DeleteFile event will fire with the invalid value in its FileContext parameter. The solution to this issue is to inspect the value of the DeleteFile parameter and if it is true, postpone deletion of the object referenced in FileContext until the DeleteFile event. Alternatively, an event handler may set FileContext to an empty value, in which case, a DeleteFile event handler will receive that empty value as a file context.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

Note: The OS sends a file close request asynchronously, which is later than a process closes its handle(s) to the opened file. Because of this, the result code returned by the event handler does not get back to the process that closed the file handle.

CloseHardLinksEnumeration Event (Cbfs Class)

This event fires when the OS is finished enumerating a file's hard links.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void closeHardLinksEnumeration(CbfsCloseHardLinksEnumerationEvent e) {}
  ...
}

public class CbfsCloseHardLinksEnumerationEvent {
  public String fileName;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public long enumerationContext;
  public int resultCode;
}

Remarks

This event fires when the OS is finished enumerating the hard links of the file specified by FileName.

This event needs to be handled only if the UseHardLinks property is enabled. To handle this event properly, applications must release any resources that were allocated for/by the hard link enumeration in earlier EnumerateHardLinks events.

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

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext, HandleContext, and EnumerationContext parameters are placeholders for application-defined data associated with the file, specific handle, and enumeration, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

CloseNamedStreamsEnumeration Event (Cbfs Class)

This event fires when the OS is finished enumerating a file's named streams.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void closeNamedStreamsEnumeration(CbfsCloseNamedStreamsEnumerationEvent e) {}
  ...
}

public class CbfsCloseNamedStreamsEnumerationEvent {
  public String fileName;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public long enumerationContext;
  public int resultCode;
}

Remarks

This event fires when the OS is finished enumerating the named streams of the file specified by FileName.

This event needs to be handled only if the UseAlternateDataStreams property is enabled. To handle this event properly, applications must release any resources that were allocated for/by the named stream enumeration in earlier EnumerateNamedStreams events.

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

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext, HandleContext, and EnumerationContext parameters are placeholders for application-defined data associated with the file, specific handle, and enumeration, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

CloseQuotasEnumeration Event (Cbfs Class)

This event fires when the OS is finished reading or updating quota information.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void closeQuotasEnumeration(CbfsCloseQuotasEnumerationEvent e) {}
  ...
}

public class CbfsCloseQuotasEnumerationEvent {
  public long enumerationContext;
  public int resultCode;
}

Remarks

This event fires when the OS is finished reading or updating quota information.

This event only needs to be handled if the UseDiskQuotas property is enabled. To handle this event properly, applications must release any resources that were allocated for/by the quota enumeration in earlier QueryQuotas or SetQuotas events.

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

The EnumerationContext parameter is a placeholder for application-defined data associated with the enumeration. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

CreateFile Event (Cbfs Class)

This event fires when the OS wants to create a file or directory.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void createFile(CbfsCreateFileEvent e) {}
  ...
}

public class CbfsCreateFileEvent {
  public String fileName;
  public int desiredAccess;
  public int attributes;
  public int shareMode;
  public int NTCreateDisposition;
  public int NTDesiredAccess;
  public long fileInfo;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS wants to create a file or directory named FileName using the creation options reflected in Attributes. If the FireAllOpenCloseEvents property is disabled, this event will fire only when the first handle to the specified file or directory is opened. To determine whether the request is for a file or a directory, compare Attributes against the FILE_SYS_ATTR_DIRECTORY constant, as follows: // Check whether the request is for a file or a directory. bool isDirectory = Attributes & FILE_SYS_ATTR_DIRECTORY == FILE_SYS_ATTR_DIRECTORY;

If the UseAlternateDataStreams property is enabled, this event also fires any time the OS wants to create a named datastream in a file. Such requests are distinguished by the presence of a colon (:) in the FileName value; the text before the colon is the name of the file itself, and the text after the colon is the name of the stream to create.

To handle this event properly, applications should (at least) perform any actions needed to create and/or open the requested file, directory, or named stream in their backend storage. Applications are also responsible for validating the access rights of the process that initiated the request before performing the requested operation; please refer to the Security Checks topic for more information.

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

If an existing local file corresponds to the virtual one specified by FileName, the application may call RouteToFile to have the class route future requests directly to that file. This event's FileInfo value must be passed to RouteToFile to request routing to be configured successfully.

In certain cases, a request to open an existing file may unexpectedly be surfaced through this event instead of through OpenFile. Normally, this will not happen, as the OS already knows which files exist (based on information obtained via GetFileInfo/EnumerateDirectory) before it sends the create or open request. If, however, a file is created externally, a rare condition may occur in which said file exists but is not known to the OS or the virtual filesystem yet. In such cases, the application must decide how to handle the unexpected CreateFile event; it can either truncate the existing file, or return the ERROR_ALREADY_EXISTS error code via ResultCode.

If an original call to CreateFile() or a similar Windows API function included security attributes, the SetFileSecurity event will immediately follow this CreateFile event, and the mentioned security attributes will be passed via SetFileSecurity.

The DesiredAccess parameter specifies the access mode desired by the process that initiated the request; it may contain one or more of the following access flags:

This value may differ from the one originally passed to the OS; the class alters it in the following cases:

• The DELETE flag is added if the requested CreateDisposition is FILE_SUPERSEDE.
• The FILE_WRITE_DATA, FILE_WRITE_EA, and FILE_WRITE_ATTRIBUTES flags are added if the requested CreateDisposition is FILE_OVERWRITE or FILE_OVERWRITE_IF.

The original CreateDisposition and DesiredAccess values are exposed through the NTCreateDisposition and NTDesiredAccess parameters.

Note: These values are in NT format; that is, as expected by the Windows API's ZwCreateFile function.

The Attributes parameter contains file attributes; it may contain one or more of the following attributes:

Attributes specifies both the attributes and create/open options for the new file. Some options, such as FILE_FLAG_SEQUENTIAL_SCAN, FILE_FLAG_WRITE_THROUGH, and FILE_FLAG_RANDOM_ACCESS, may be useful for applications that wish to fine-tune their performance. For example, such information could be used to decide whether it is necessary to locally cache some amount of data that is stored remotely.

The ShareMode parameter specifies the access sharing mode desired by the process that initiated the request; it may contain zero or more of the following share mode flags:

Please refer to the Windows API's ZwCreateFile function for detailed information about possible values for the DesiredAccess, Attributes, ShareMode, NTCreateDisposition, and NTDesiredAccess parameters.

The FileInfo parameter carries a handle to an object with information about the file. As mentioned earlier, this value should be used if the application chooses to call the RouteToFile method.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

CreateHardLink Event (Cbfs Class)

This event fires when the OS wants to create a new hard link to an existing file.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void createHardLink(CbfsCreateHardLinkEvent e) {}
  ...
}

public class CbfsCreateHardLinkEvent {
  public String fileName;
  public String linkName;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS wants to create a new hard link that points to the existing file specified by FileName. The LinkName parameter specifies the absolute path (including filename) of the link to be created.

This event needs to be handled only if the UseHardLinks property is enabled. To handle this event properly, applications should perform any actions needed to create an additional hard link to the specified file in their backend storage.

Please refer to the Hard Links topic for more information.

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

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

DeleteFile Event (Cbfs Class)

This event fires when the OS needs to delete a file or directory.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void deleteFile(CbfsDeleteFileEvent e) {}
  ...
}

public class CbfsDeleteFileEvent {
  public String fileName;
  public long fileContext;
  public int resultCode;
}

Remarks

This event fires when the OS has decided to delete the file or directory specified by FileName.

To handle this event properly, applications must perform any actions needed to delete the specified file or directory from their backend storage. If the UseHardLinks property is enabled, a file's data should be deleted only when its last hard link has been deleted; please refer to the Hard Links topic for more information.

Note:

• A deletion cannot be canceled from this event; applications that wish to prevent a deletion must do so via the CanFileBeDeleted event.
• This event fires immediately after the last CloseFile event. If the application disposes of the FileContext in the CloseFile event handler, it will be invalid when this event fires. The CloseFile event includes a DeleteFile parameter that helps address this situation.

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

The FileContext parameter is a placeholder for application-defined data associated with the file. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

DeleteReparsePoint Event (Cbfs Class)

This event fires when the OS wants to delete a reparse point from a file or directory.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void deleteReparsePoint(CbfsDeleteReparsePointEvent e) {}
  ...
}

public class CbfsDeleteReparsePointEvent {
  public String fileName;
  public ByteBuffer reparseBuffer;
  public int reparseBufferLength;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS wants to delete a reparse point from the file or directory specified by FileName.

This event needs to be handled only if the UseReparsePoints property is enabled.

Note: NFS sharing makes use of reparse points.

To handle this event properly, applications must delete the reparse point data (and tag) stored previously for the specified file or directory. Any other actions taken in an earlier SetReparsePoint event also should be reversed appropriately.

Note: The file or directory itself should not be deleted.

Please refer to the Reparse Points topic for more information.

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

The existing reparse point data are provided in this event as a convenience for use-cases that wish to utilize it.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

Ejected Event (Cbfs Class)

Fires when the media and virtual drive have been ejected (Windows only).

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void ejected(CbfsEjectedEvent e) {}
  ...
}

public class CbfsEjectedEvent {
  public int resultCode;
}

Remarks

This event fires when a user has ejected the media and virtual drive using the Eject command in Windows Explorer.

For ejection via the system notification area (tray) to work correctly, the StorageType property must be set to STGT_DISK_PNP, and the StorageCharacteristics property must include ejection-related flags.

This event is optional; it is provided to give applications a chance to, e.g., free up resources associated with the virtual drive. Since the virtual drive has already been destroyed by the time this event fires, applications must not call UnmountMedia or DeleteStorage (the latter is called automatically with its ForceUnmount parameter set to true) .

The ResultCode parameter will always be initially set to the result of a storage deletion operation. The expected value is 0. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Note that as ejection has already occured, this non-zero value will not have effect on the media's state. Please refer to the Error Reporting and Handling topic for more information.

EnumerateDirectory Event (Cbfs Class)

This event fires when the OS wants to enumerate a directory's contents.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void enumerateDirectory(CbfsEnumerateDirectoryEvent e) {}
  ...
}

public class CbfsEnumerateDirectoryEvent {
  public String directoryName;
  public String mask;
  public boolean caseSensitive;
  public boolean restart;
  public int requestedInfo;
  public boolean fileFound;
  public String fileName;
  public String shortFileName;
  public java.util.Date creationTime;
  public java.util.Date lastAccessTime;
  public java.util.Date lastWriteTime;
  public java.util.Date changeTime;
  public long size;
  public long allocationSize;
  public long fileId;
  public long attributes;
  public long reparseTag;
  public long handleInfo;
  public long directoryContext;
  public long handleContext;
  public long enumerationContext;
  public int resultCode;
}

Remarks

This event fires when the OS wants to enumerate the contents of the directory specified by DirectoryName (which will have been opened via OpenFile).

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

To handle this event properly, applications must return information about each directory entry (e.g., file, subdirectory, link) that matches the specified Mask.

For each matching entry found, set FileFound to true, inspect the RequestedInfo parameter for the types of information required, and supply the entry's information using the following parameters:

• FileName: Set to the name of the entry (not including its path).
  • The length of the returned name must not exceed the value of the MaxFileNameLength property.
• ShortFileName: If the UseShortFileNames property is enabled, set to the short (8.3) name of the entry.
  • The short name must adhere to the 8.3 name format; please refer to the Short File Names topic for more information.
• CreationTime, LastAccessTime, LastWriteTime, ChangeTime: Set to the entry's corresponding time values, specified in UTC. Any time values not applicable to the entry can be left unchanged, or set to January 1, 1601 00:00:00 UTC.
  • Leave LastAccessTime unchanged if the SupportLastAccessTimeAttribute property is disabled.
  • Leave ChangeTime unchanged if the SupportChangeTimeAttribute property is disabled.
• Size: For file entries, set to the size of the file, in bytes; for other entries, set to 0.
• AllocationSize: For file entries, set to the number of bytes allocated locally for the file; for other entries, set to 0. The allocation size is typically a multiple of the ClusterSize.
• FileId: Set to the unique Id of the file or directory represented by the entry. Please refer to the File IDs topic for more information.
• Attributes: Set to the file or directory attributes of the entry. If the SupportCompressedAttribute property is set to true, an event handler should properly set or clear the FILE_ATTRIBUTE_COMPRESSED in the Attributes parameter.
• ReparseTag: If the UseReparsePoints property is enabled, and the entry is a reparse point, set to the reparse point's tag.
  • Ensure that the FILE_ATTRIBUTE_REPARSE_POINT attribute is included in the value supplied for the Attributes parameter.
  • The tag should have been stored when the reparse point was created (i.e., during an earlier SetReparsePoint event).
  • Please refer to the Reparse Points topic for more information.

If there are no more matching entries present, set FileFound to false and leave the above parameters unchanged. When the OS is finished with the directory enumeration, the CloseDirectoryEnumeration event will fire.

RequestedInfo: This value specifies which kinds of information the class is interested in. Use this information as a hint to save some CPU ticks. Providing unrequested information will not cause a problem, but this information will be ignored, thus wasting the time used to obtain it. The value is a combination of the following flags:

The Mask parameter specifies the filename mask that should be used to filter the results. This value may contain any combination of valid filename characters and wildcards (the * and ? characters). Alternatively, it may be an exact filename (i.e., a value without any wildcards), as some applications query file information by specifying an exact filename in an enumeration. Note: When a request for directory enumeration passes Windows network redirector, it always uses the mask * regardless of what the original mask was.

The CaseSensitive parameter indicates whether entry names should be matched against the specified Mask in a case-sensitive manner. It will always be false if the UseCaseSensitiveFileNames property is disabled.

Note: This parameter is not currently used; the search is always case-insensitive.

The Restart parameter, if true, indicates that the enumeration should be restarted from the beginning of the directory. Any previously reported entries that still exist should be reported again.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The DirectoryContext, HandleContext, and EnumerationContext parameters are placeholders for application-defined data associated with the directory, specific handle, and enumeration, respectively. (For general-purpose events, the DirectoryContext is called FileContext instead.) DirectoryContext corresponds to the FileContext in the file/directory creation, opening, and closing events. Please refer to the Contexts topic for more information.

Note: If an application calls the NotifyDirectoryChange method and passes a mask instead of a filename, the class will fire this EnumerateDirectory event to collect the names of files and subdirectories, and in this case, the HandleInfo, DirectoryContext, and HandleContext parameters will be empty.

Note: To avoid unexpected delays and slowdown, enumeration does not refresh the metadata cache or nonexistent file cache. If your data may be altered on the backend side (i.e., not through the virtual disk), your application needs to track the changes and use NotifyDirectoryChange, as needed, which will update the mentioned caches. Alternatively, you may disable either or both of the caches.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

Note: For this event, returning ERROR_FILE_INVALID has no effect.

EnumerateHardLinks Event (Cbfs Class)

This event fires when the OS needs to enumerate a file's hard links.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void enumerateHardLinks(CbfsEnumerateHardLinksEvent e) {}
  ...
}

public class CbfsEnumerateHardLinksEvent {
  public String fileName;
  public boolean linkFound;
  public String linkName;
  public long parentId;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public long enumerationContext;
  public int resultCode;
}

Remarks

This event fires when the OS needs to enumerate the hard links of the file specified by FileName (which will have been opened via OpenFile).

This event needs to be handled only if the UseHardLinks property is enabled.

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

To handle this event properly, applications must return information about each of the file's hard links.

Note: A file's "primary" name (i.e., the one contained in FileName) is itself one of the hard links that must be reported; please refer to the Hard Links topic for more information.

For each hard link, set LinkFound to true and supply the hard link's information using the following parameters:

• LinkName: Set to the name of the hard link (not including its path).
  • The length of the returned name must not exceed the value of the MaxFileNameLength property.
• ParentId: Set to the unique Id of the directory the hard link resides in (this Id should not change over time). Always use 0x7FFFFFFFFFFFFFFF if the hard link resides in the root directory (\).

If there are no more hard links present, set LinkFound to false and leave the above parameters unchanged. When the OS is finished with the hard links enumeration, the CloseHardLinksEnumeration event will fire.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext, HandleContext, and EnumerationContext parameters are placeholders for application-defined data associated with the file, specific handle, and enumeration, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

EnumerateNamedStreams Event (Cbfs Class)

This event fires when the OS needs to enumerate a file's named streams.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void enumerateNamedStreams(CbfsEnumerateNamedStreamsEvent e) {}
  ...
}

public class CbfsEnumerateNamedStreamsEvent {
  public String fileName;
  public boolean namedStreamFound;
  public String streamName;
  public long streamSize;
  public long streamAllocationSize;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public long enumerationContext;
  public int resultCode;
}

Remarks

This event fires when the OS needs to enumerate the named streams of the file specified by FileName (which will have been opened via OpenFile).

This event needs to be handled only if the UseAlternateDataStreams property is enabled.

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

To handle this event properly, applications must return information about each of the file's named streams. For each named stream, set StreamNameFound to true and supply the named stream's information using the following parameters:

• StreamName: Set to the name of the named stream, prefixed with : (e.g. :MyStreamName). For more information about stream naming conventions, refer to Microsoft's Naming Conventions for Streams information.
  • The length of the returned name must not exceed the value of the MaxFileNameLength property.
• StreamSize: Set the size, in bytes, of the named stream's data.
• StreamAllocationSize: Set to the number of bytes allocated locally for the named stream. This is typically a multiple of the ClusterSize.

If there are no more named streams present, set StreamNameFound to false and leave the above parameters unchanged. When the OS is finished with the named streams enumeration, the CloseNamedStreamsEnumeration event will fire.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext, HandleContext, and EnumerationContext parameters are placeholders for application-defined data associated with the file, specific handle, and enumeration, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

Error Event (Cbfs Class)

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

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void error(CbfsErrorEvent e) {}
  ...
}

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

Remarks

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

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

FlushFile Event (Cbfs Class)

This event fires when the OS needs to flush an open file's data out to storage.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void flushFile(CbfsFlushFileEvent e) {}
  ...
}

public class CbfsFlushFileEvent {
  public String fileName;
  public long fileContext;
  public int resultCode;
}

Remarks

This event fires any time the OS needs the virtual filesystem to flush data out to storage. If the FileName parameter is nonempty, then all data related to the specified file (i.e., contents and all metadata) should be flushed. If FileName is empty, everything related to the virtual drive should be flushed.

To handle this event properly, applications must flush the requested data, writing it out to their backend storage.

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

The FileContext parameter is a placeholder for application-defined data associated with the file. Please refer to the Contexts topic for more information. (Not applicable if FileName is empty.)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

Fsctl Event (Cbfs Class)

This event fires when the virtual filesystem receives a nonstandard request (filesystem control code).

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void fsctl(CbfsFsctlEvent e) {}
  ...
}

public class CbfsFsctlEvent {
  public String fileName;
  public int code;
  public ByteBuffer inputBuffer;
  public int inputBufferLength;
  public ByteBuffer outputBuffer;
  public int outputBufferLength;
  public int bytesReturned;
  public long fileContext;
  public int resultCode;
}

Remarks

An FSCTL is a system call for filesystem-specific I/O operations as well as for other operations that cannot be expressed through regular filesystem calls. Such calls carry a control code, and the effects of the call depend entirely on how a filesystem handles that control code. A control code is composed of, among other things, a function code and flags that describe how data are passed.

CBFS Connect reserves function codes 2400-4096 for applications' use, and normally fires this event only for control codes containing a function code from that range. If, however, the HandleAllFsctls property is enabled, the class will fire this event for all FSCTLs other than those processed by CBFS Connect itself.

This event is optional. Applications that choose to implement it are free to do so in any manner they desire based on the control code received.

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

An application can send a custom FSCTL by defining a control code with the following macro and then using that control code to call the Windows API's DeviceIoControl function. #define CTL_CODE( DeviceType, Function, Method, Access ) \ ( ((DeviceType) << 16) | ((Access) << 14) | ((Function) << 2) | (Method) )

• DeviceType: Must always be FILE_DEVICE_FILE_SYSTEM (9).
• Function: Must be an integer in the range 2400-4096.
• Method ("TransferType"): Specifies how data are passed between the caller and the driver. Possible values are as follows:
  • METHOD_BUFFERED (0)
  • METHOD_IN_DIRECT (1)
  • METHOD_OUT_DIRECT (2)
  • METHOD_NEITHER (3)
  For small amounts of data (1-4096 bytes), it is best to use METHOD_BUFFERED (0); otherwise, use METHOD_NEITHER (3) or one of the other values.
• Access ("RequiredAccess"): Indicates the type(s) of access the caller must request when opening a handle to the target filesystem object (i.e., the handle passed for the hDevice parameter of the DeviceIoControl function). The system's I/O manager will block the request if the caller did not open the specified handle with the required access rights. Possible values are as follows:
  • FILE_ANY_ACCESS (0) (i.e., the caller can send the FSCTL regardless of access rights)
  • FILE_READ_ACCESS (1)
  • FILE_WRITE_ACCESS (2)
  The latter two options can be ORed together to require the caller to have both read and write access.

Please refer to Microsoft's Defining I/O Control Codes article for more information.

The FileName parameter identifies the file or directory targeted by the request. It may be empty if the request is targeting the virtual drive.

The Code parameter reflects the control code received. If the specified control code is unrecognized or unsupported (either in general, or for the filesystem object specified by FileName), return the ERROR_INVALID_FUNCTION error code via ResultCode.

The InputBuffer parameter points to the memory buffer containing the data required to perform the operation. The format of this data depends on the specified Code; it may be empty. The InputBufferLength parameter specifies the length, in bytes, of InputBuffer.

The OutputBuffer parameter points to the memory buffer that receives the data returned by the operation. The format of this data depends on the specified Code; it may be empty. The OutputBufferLength parameter specifies the capacity, in bytes, of OutputBuffer; applications should set the BytesReturned parameter to the number of bytes written to OutputBuffer.

If the application needs to return more than OutputBufferLength bytes of data, it should do one of the following:

1. If OutputBuffer is too small to hold all of the data, but can hold some entries, then the application should write as much data to it as possible, set BytesReturned appropriately, and return the ERROR_MORE_DATA error code via ResultCode.
2. If OutputBuffer is too small to hold any data, then the application should set BytesReturned to 0, and return the ERROR_INSUFFICIENT_BUFFER error code via ResultCode.

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

The FileContext parameter is a placeholder for application-defined data associated with the file. Please refer to the Contexts topic for more information.

Initially, the Result parameter will be set to ERROR_INVALID_FUNCTION. If an event handler processes the request in a meaningful way (i.e., the requestor will receive an expected result), the event handler should set Result to 0 or another error code that should reach the requestor. Please refer to the Error Reporting and Handling topic for more information.

GetDefaultQuotaInfo Event (Cbfs Class)

This event fires when the OS needs the virtual drive's default quota information.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void getDefaultQuotaInfo(CbfsGetDefaultQuotaInfoEvent e) {}
  ...
}

public class CbfsGetDefaultQuotaInfoEvent {
  public long defaultQuotaThreshold;
  public long defaultQuotaLimit;
  public long fileSystemControlFlags;
  public int resultCode;
}

Remarks

This event fires when the OS needs the default quota information, set during an earlier SetDefaultQuotaInfo event, for the virtual drive.

This event needs to be handled only if the UseDiskQuotas property is enabled. To handle this event properly, applications must return the virtual drive's default quota information by setting DefaultQuotaThreshold, DefaultQuotaLimit, and FileSystemControlFlags.

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

Descriptions of the DefaultQuotaThreshold, DefaultQuotaLimit, and FileSystemControlFlags parameters can be found in the Windows API's FILE_FS_CONTROL_INFORMATION structure documentation.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

GetFileInfo Event (Cbfs Class)

This event fires when the OS needs information about a file or directory.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void getFileInfo(CbfsGetFileInfoEvent e) {}
  ...
}

public class CbfsGetFileInfoEvent {
  public String fileName;
  public int requestedInfo;
  public boolean fileExists;
  public java.util.Date creationTime;
  public java.util.Date lastAccessTime;
  public java.util.Date lastWriteTime;
  public java.util.Date changeTime;
  public long size;
  public long allocationSize;
  public long fileId;
  public long attributes;
  public long reparseTag;
  public int hardLinkCount;
  public String shortFileName;
  public String realFileName;
  public int resultCode;
}

Remarks

This event fires when the OS needs information about the file or directory specified by FileName and in some other cases (see the following notes for details).

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

To handle this event properly, applications should first check whether the specified file or directory exists, and set FileExists accordingly. If no such file or directory exists, set FileExists to false. If the file or directory exists, set FileExists to true, inspect the RequestedInfo parameter for the types of information required, and supply its information using the following parameters:

• CreationTime, LastAccessTime, LastWriteTime, ChangeTime: Set to the corresponding time values of the file or directory, specified in UTC. Any nonapplicable time values can be left unchanged, or set to January 1, 1601 00:00:00 UTC.
  • Leave LastAccessTime unchanged if the SupportLastAccessTimeAttribute property is disabled.
  • Leave ChangeTime unchanged if the SupportChangeTimeAttribute property is disabled.
• Size: For files, set to the size of the file, in bytes; for directories, set to 0.
• AllocationSize: For files, set to the number of bytes allocated locally for the file; for directories, set to 0. The allocation size is typically a multiple of the ClusterSize.
• FileId: Set to the unique Id of the file or directory. Please refer to the File IDs topic for more information.
• Attributes: Set to the attributes of the file or directory. If the SupportCompressedAttribute property is set to true, an event handler should properly set or clear the FILE_ATTRIBUTE_COMPRESSED in the Attributes parameter.
• ReparseTag: If the UseReparsePoints property is enabled, and the entry is a reparse point, set to the reparse point's tag.
  • Ensure that the FILE_ATTRIBUTE_REPARSE_POINT attribute is included in the value supplied for the Attributes parameter.
  • The tag should have been stored when the reparse point was created (i.e., during an earlier SetReparsePoint event).
  • Please refer to the Reparse Points topic for more information.
• HardLinkCount: If the UseHardLinks property is enabled, set to the number of hard links that point to the file. The default value is 1 (which is also the only valid value for directories). Please refer to the Hard Links topic for more information.
• ShortFileName: If the UseShortFileNames property is enabled, set to the short (8.3) name of the file.
  • If UseShortFileNames is enabled, it is possible that FileName is already a short name. In such cases, return the same name in ShortFileName.
  • The short name must adhere to the 8.3 name format; please refer to the Short File Names topic for more information.
• RealFileName: If the UseCaseSensitiveFileNames property is enabled, and FileName's casing differs from that of the actual file or directory name, set to the real name of said file or directory.
  • For example, if the requested FileName is QWERTY.txt, but the only similarly named file in the virtual filesystem is qwErTy.TxT, then this parameter should be set to the latter.
  • If the specified FileName includes a path, it must be preserved in the value returned via RealFileName; only the casing of the filename and extension may be corrected.
  • The length of the returned name (and path, if applicable) must not exceed the value of the MaxFilePathLength property.

RequestedInfo: This value specifies which kinds of information the class is interested in. Use this information as a hint to save some CPU ticks. Providing unrequested information will not cause a problem, but this information will be ignored, thus wasting the time used to obtain it. The value is a combination of the following flags:

Notes:

1. if the UseCaseSensitiveFileNames and UseAlternateDataStreams properties are both enabled, this event may also be used to obtain the real name of a named stream. When returning the name of a named stream via the RealFileName parameter, prepend a colon (:) to the stream's name so that it looks like this: :Zone.Identifier.
2. if the UpdateFileMetadataOnOpen config setting is true, this event will fire right after the OpenFile event but only if the file was fully closed before OpenFile.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

Note: For this event, returning ERROR_FILE_INVALID has no effect.

GetFileNameByFileId Event (Cbfs Class)

This event fires when the class needs to translate a file Id to a file or directory path.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void getFileNameByFileId(CbfsGetFileNameByFileIdEvent e) {}
  ...
}

public class CbfsGetFileNameByFileIdEvent {
  public long fileId;
  public String filePath;
  public int resultCode;
}

Remarks

This event fires any time the class needs a specified FileId translated to a file or directory path. This typically occurs when a process tries to open a file or directory by Id rather than by name (e.g., if FILE_OPEN_BY_FILE_ID is used when calling the Windows API's ZwCreateFile function); the OpenFile event fires after the path is obtained from this event.

This event must be handled if one of the UseDiskQuotas or UseHardLinks properties is enabled; otherwise, it is optional, and applications need not implement it if the virtual filesystem doesn't support file Ids.

Note: NFS sharing makes use of file IDs.

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

To handle this event properly, applications must set FilePath to the absolute path of the file or directory associated with the specified FileId. The length of the path must not exceed the value of the MaxFilePathLength property.

The root directory (\) always uses the predefined Id 0x7FFFFFFFFFFFFFFF.

Please refer to the File IDs topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

GetFileSecurity Event (Cbfs Class)

This event fires when the OS needs to read the Windows security attributes of a file or directory.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void getFileSecurity(CbfsGetFileSecurityEvent e) {}
  ...
}

public class CbfsGetFileSecurityEvent {
  public String fileName;
  public int securityInformation;
  public ByteBuffer securityDescriptor;
  public int bufferLength;
  public int descriptorLength;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS needs to read the Windows security attributes of the file or directory specified by FileName.

This event only needs to be handled if the UseWindowsSecurity property is enabled.

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

To handle this event properly, applications must return the requested pieces of security information, specified by SecurityInformation, via the SecurityDescriptor buffer. Please refer to the following parameter descriptions, as well as the Security Checks topic, for more information.

The SecurityInformation parameter indicates which pieces of security information must be provided. This value is a bitfield; possible flags include (but are not limited to) the following:

• OWNER_SECURITY_INFORMATION
• GROUP_SECURITY_INFORMATION
• DACL_SECURITY_INFORMATION
• SACL_SECURITY_INFORMATION

Please refer to Microsoft's SECURITY_INFORMATION data type documentation for more information about possible values.

The SecurityDescriptor parameter points to the memory buffer that receives the requested data. It is available only if BufferLength is greater than 0. The data must be formatted as a SECURITY_DESCRIPTOR structure in self-relative format. Please refer to these articles for more information about self-relative security descriptors.

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

The BufferLength parameter specifies the capacity, in bytes, of the SecurityDescriptor buffer; and the DescriptorLength parameter specifies, in bytes, the length of the security descriptor.

If the SecurityDescriptor buffer has enough capacity to accommodate the entire security descriptor, DescriptorLength must be set to the length of the data copied to SecurityDescriptor. If the SecurityDescriptor buffer is too small (or, in cases in which BufferLength is 0, unavailable), do not write any data to it; instead, set DescriptorLength to the number of bytes required to hold the requested data, and return the ERROR_INSUFFICIENT_BUFFER error code via ResultCode.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

GetReparsePoint Event (Cbfs Class)

This event fires when the OS wants to read a reparse point for a file or directory.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void getReparsePoint(CbfsGetReparsePointEvent e) {}
  ...
}

public class CbfsGetReparsePointEvent {
  public String fileName;
  public ByteBuffer reparseBuffer;
  public int reparseBufferLength;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS wants to read a reparse point for the file or directory specified by FileName.

This event only needs to be handled if the UseReparsePoints property is enabled.

Note: NFS sharing makes use of reparse points.

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

To handle this event properly, applications must populate ReparseBuffer with the reparse point data associated with the specified file or directory (i.e., the data stored during an earlier SetReparsePoint event), and set ReparseBufferLength to the number of bytes written.

Please refer to the Reparse Points topic for more information.

The ReparseBufferLength parameter's initial value reflects the capacity of the memory buffer pointed to by ReparseBuffer. If the buffer is too small to hold all of the reparse point data, then the application should write as much data to it as possible, set ReparseBufferLength appropriately, and return the ERROR_MORE_DATA error code via ResultCode.

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

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

Depending on how the request originator accessed the specified file or directory, it may or may not currently be open. The HandleInfo, FileContext, and HandleContext parameters will be absent if it is not open, in which case, they will be 0.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

GetVolumeId Event (Cbfs Class)

This event fires when the class needs the volume Id.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void getVolumeId(CbfsGetVolumeIdEvent e) {}
  ...
}

public class CbfsGetVolumeIdEvent {
  public int volumeId;
  public int resultCode;
}

Remarks

This event fires any time the class needs to retrieve the volume Id of the virtual drive. Ideally, each drive's volume Id should be globally unique.

To handle this event properly, applications must return the virtual drive's volume Id via the VolumeId parameter.

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

GetVolumeLabel Event (Cbfs Class)

This event fires when the OS needs the volume label.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void getVolumeLabel(CbfsGetVolumeLabelEvent e) {}
  ...
}

public class CbfsGetVolumeLabelEvent {
  public String buffer;
  public int resultCode;
}

Remarks

This event fires any time the OS needs to retrieve the volume label of the virtual drive.

To handle this event properly, applications must set Buffer to the most recent value obtained via SetVolumeLabel.

The length of the returned volume label must not exceed 32 characters, which is the maximum length supported by the OS.

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

GetVolumeObjectId Event (Cbfs Class)

This event fires when the OS needs the volume object Id and extended information.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void getVolumeObjectId(CbfsGetVolumeObjectIdEvent e) {}
  ...
}

public class CbfsGetVolumeObjectIdEvent {
  public ByteBuffer objectId;
  public int objectIdLength;
  public ByteBuffer extendedInformation;
  public int extendedInformationLength;
  public int resultCode;
}

Remarks

This event fires any time the OS needs to retrieve the volume object Id and extended information for the virtual drive.

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

To handle this event properly, applications must populate the ObjectId and ExtendedInformation buffers with the most recent values obtained via SetVolumeObjectId.

The ObjectIdLength and ExtendedInformationLength values are specified by the OS; they will always be 16 and 48 bytes, respectively.

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

GetVolumeSize Event (Cbfs Class)

This event fires when the OS needs information about the virtual drive's capacity and free space.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void getVolumeSize(CbfsGetVolumeSizeEvent e) {}
  ...
}

public class CbfsGetVolumeSizeEvent {
  public long totalSectors;
  public long availableSectors;
  public int resultCode;
}

Remarks

This event fires any time the OS needs to retrieve the virtual drive's total storage capacity and free space, measured in sectors. The virtual drive's sector size is defined by the SectorSize configuration setting.

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

To handle this event properly, applications must set TotalSectors to the total number of sectors on the drive, and set AvailableSectors to the number of sectors that are available to the OS for storing filesystem objects.

The minimum drive size accepted by Windows is 6144 bytes (based on a 3072-byte sector, 1 sector per cluster and 2 clusters per drive). The class adjusts the minimum size to be at least 16 sectors (49152 bytes) to ensure compatibility with possible changes in future Windows updates.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

Ioctl Event (Cbfs Class)

This event fires when the disk behind the virtual filesystem receives a nonstandard request (I/O control code).

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void ioctl(CbfsIoctlEvent e) {}
  ...
}

public class CbfsIoctlEvent {
  public String fileName;
  public int code;
  public ByteBuffer inputBuffer;
  public int inputBufferLength;
  public ByteBuffer outputBuffer;
  public int outputBufferLength;
  public int bytesReturned;
  public int resultCode;
}

Remarks

An IOCTL is a system call for device-specific I/O operations, as well as other operations that cannot be expressed through regular API calls. Such calls carry a control code, and the effects of the call depend entirely on how a device driver handles that control code. A control code is composed of, among other things, a function code and flags that describe how data are passed.

This event is optional. Applications that choose to implement it are free to do so in any manner they desire based on the control code received.

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

The FileName parameter identifies the file or directory targeted by the request. It may be empty if the request is targeting the virtual drive.

The Code parameter reflects the control code received. If the specified control code is unrecognized or unsupported, return the ERROR_INVALID_FUNCTION error code via ResultCode.

The InputBuffer parameter points to the memory buffer containing the data required to perform the operation. The format of this data depends on the specified Code; it may be empty. The InputBufferLength parameter specifies the length, in bytes, of InputBuffer.

The OutputBuffer parameter points to the memory buffer that receives the data returned by the operation. The format of this data depends on the specified Code; it may be empty. The OutputBufferLength parameter specifies the capacity, in bytes, of OutputBuffer; applications should set the BytesReturned parameter to the number of bytes written to OutputBuffer.

If the application needs to return more than OutputBufferLength bytes of data, it should do one of the following:

1. If OutputBuffer is too small to hold all of the data, but can hold some entries, then the application should write as much data to it as possible, set BytesReturned appropriately, and return the ERROR_MORE_DATA error code via ResultCode.
2. If OutputBuffer is too small to hold any data, then the application should set BytesReturned to 0, and return the ERROR_INSUFFICIENT_BUFFER error code via ResultCode.

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

Initially, the Result parameter will be set to ERROR_INVALID_FUNCTION. If an event handler processes the request in a meaningful way (i.e., the requestor will receive an expected result), the event handler should set Result to 0 or another error code that should reach the requestor. Please refer to the Error Reporting and Handling topic for more information.

IsDirectoryEmpty Event (Cbfs Class)

This event fires when the OS needs to know whether a directory is empty.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void isDirectoryEmpty(CbfsIsDirectoryEmptyEvent e) {}
  ...
}

public class CbfsIsDirectoryEmptyEvent {
  public String directoryName;
  public boolean isEmpty;
  public long directoryContext;
  public int resultCode;
}

Remarks

This event fires when the OS needs to know whether the directory specified by DirectoryName is empty.

This event needs to be handled only if the UseDirectoryEmptyCheck property is enabled. To handle this event properly, applications must set the IsEmpty parameter appropriately.

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

The DirectoryContext parameter is a placeholder for application-defined data associated with the directory (for "general-purpose" events, it is called FileContext instead). Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

LockFile Event (Cbfs Class)

This event fires when the OS needs to lock a range of bytes in a file.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void lockFile(CbfsLockFileEvent e) {}
  ...
}

public class CbfsLockFileEvent {
  public String fileName;
  public long byteOffset;
  public long length;
  public int key;
  public boolean exclusiveLock;
  public boolean failImmediately;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS needs to lock a range of bytes in the file specified by FileName. Typically, such requests originate from the Windows API's LockFile and LockFileEx functions.

This event is optional. The CBFS class automatically manages file locks in the virtual filesystem. If the resources an application uses for backend storage (e.g., files, memory, a database) are never directly accessed by anything other than the application itself, then there is no reason to implement this event.

If, however, an application's backend storage involves shared resources (i.e., those that could be accessed by something other than the application at any time), this event should be used to perform any actions needed to propagate the requested lock onto those resources.

For example, if an application's backend storage implementation involves files stored on a network server, then the locking request should be communicated to that server so that it can prevent other accessors from using the locked data.

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

Applications that implement this event must also implement the UnlockFile event.

The ByteOffset and Length parameters specify the starting position of the range being locked, and the length of that range, respectively.

The Key parameter reflects the key that the byte range lock is associated with. This key is used to identify the byte range lock in later unlock-by-key requests.

The ExclusiveLock and FailImmediately parameters are described in-depth in the LockFileEx function's documentation.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

An event handler may return ERROR_RETRY to signal that locking cannot be done immediately but a retry is required a bit later. The time until the next attempt is set via the LockRetryInterval setting. This behavior requires that the UserModeLockFirst setting is enabled.

Mount Event (Cbfs Class)

This event fires after the class mounts media into the virtual drive, making it available.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void mount(CbfsMountEvent e) {}
  ...
}

public class CbfsMountEvent {
  public int resultCode;
}

Remarks

This event fires once the class has mounted media into the virtual drive, making it available. Please refer to MountMedia for more information.

This event is optional; it is provided to give applications a chance to perform additional processing when the virtual filesystem is made available.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

OffloadReadFile Event (Cbfs Class)

This event fires when the OS wants the virtual filesystem to perform an offloaded data transfer (ODX) read operation.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void offloadReadFile(CbfsOffloadReadFileEvent e) {}
  ...
}

public class CbfsOffloadReadFileEvent {
  public String fileName;
  public int tokenTimeToLive;
  public long position;
  public long copyLength;
  public long transferLength;
  public int tokenType;
  public ByteBuffer tokenBuffer;
  public long bufferLength;
  public int tokenLength;
  public int resultFlags;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This events fires when the OS wants the virtual filesystem to perform an offloaded read for the file specified by FileName as part of an offloaded data transfer.

To handle this event properly, applications should first verify whether the specified file supports offload operations, returning the ERROR_OFFLOAD_READ_FILE_NOT_SUPPORTED error code via ResultCode if not. Assuming the file does support offload operations, the application should perform any actions needed to prepare for the offloaded read based on the specified parameters, and then return the requested information. Please refer to the following parameter descriptions for more information.

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

The TokenTimeToLive parameter indicates the duration, in milliseconds, that the offloaded read operation remains valid. Multiple writes can be performed with the token returned in TokenBuffer until this time expires.

The Position and CopyLength parameters specify the byte offset and length (respectively) of a data chunk in the specified file that should be read, or in some other way prepared, for transferring.

The TransferLength parameter must be set to the number of bytes actually read/prepared as a result of this request. It may be less than CopyLength.

The TokenType parameter must be set to either (1) the Microsoft-defined value of STORAGE_OFFLOAD_TOKEN_TYPE_ZERO_DATA (0xFFFF0001) if the token represents data that are all zeros, or (2) an application-defined value outside of the reserved range 0xFFFF0002 to 0xFFFFFFFF to denote an application-defined token format.

Note: Use of the STORAGE_OFFLOAD_TOKEN_TYPE_ZERO_DATA token type is not required.

The TokenBuffer parameter points to a memory buffer that receives some application-defined token that identifies the data that have been read or prepared for transfer. The returned token will be passed to an offloaded write operation to actually transfer the data it represents. The BufferLength parameter specifies the capacity, in bytes, of TokenBuffer; applications must set the TokenLength parameter to the number of bytes written to TokenBuffer.

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

The ResultFlags parameter must be set to a combination of zero or more of the flags described in the FSCTL_OFFLOAD_READ_OUTPUT structure's documentation.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken. (This parameter may be absent, in which case it will be 0.)

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (HandleContext may be absent, in which case it will be 0.)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

OffloadWriteFile Event (Cbfs Class)

This event fires when the OS wants the virtual filesystem to perform an offloaded data transfer (ODX) write operation.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void offloadWriteFile(CbfsOffloadWriteFileEvent e) {}
  ...
}

public class CbfsOffloadWriteFileEvent {
  public String fileName;
  public long position;
  public long copyLength;
  public long transferOffset;
  public long transferLength;
  public int tokenType;
  public ByteBuffer token;
  public long tokenLength;
  public int resultFlags;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS wants the virtual filesystem to perform an offloaded write for the file specified by FileName as part of an offloaded data transfer.

To handle this event properly, applications should perform any actions needed to handle the offloaded write based on the specified parameters, and then return the result information. Please refer to the following parameter descriptions for more information.

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

The Position and CopyLength parameters specify the byte offset and length, respectively, of the data chunk that should be written in the specified file. The CopyLength parameter's value may be smaller than the total amount of data represented by the token (in which case TransferOffset may be greater than 0).

The TransferOffset parameters specifies the byte offset, in the chunk of data represented by the token, from which to begin writing.

The TransferLength parameter must be set to the number of bytes actually written as a result of this request. It may be less than CopyLength.

The TokenType parameter indicates the type of token stored in the Token buffer. A value of STORAGE_OFFLOAD_TOKEN_TYPE_ZERO_DATA (0xFFFF0001) indicates that the token represents data that are all zeros. Any other value (outside of the reserved range 0xFFFF0002 to 0xFFFFFFFF) indicates an application-defined token format.

The Token parameter points to a memory buffer that contains the token returned in response to an earlier offloaded read request. The token identifies the chunk of data that has been read or prepared for transfer; refer to the OffloadReadFile event for more information. The TokenLength parameter specifies the length, in bytes, of the data in Token.

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

The ResultFlags parameter must be set to a combination of zero or more of the flags described in the FSCTL_OFFLOAD_WRITE_OUTPUT structure's documentation.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken. (This parameter may be absent, in which case it will be 0.)

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (HandleContext may be absent, in which case it will be 0.)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

OpenFile Event (Cbfs Class)

This event fires when the OS wants to open a file or directory.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void openFile(CbfsOpenFileEvent e) {}
  ...
}

public class CbfsOpenFileEvent {
  public String fileName;
  public int desiredAccess;
  public int attributes;
  public int shareMode;
  public int NTCreateDisposition;
  public int NTDesiredAccess;
  public long fileInfo;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS wants to open the existing file or directory specified by FileName using the open options reflected in Attributes. If the FireAllOpenCloseEvents property is disabled, this event will fire only when the first handle to the specified file or directory is opened. To determine whether the request is for a file or a directory, compare Attributes against the FILE_SYS_ATTR_DIRECTORY constant, as follows: // Check whether the request is for a file or a directory. bool isDirectory = Attributes & FILE_SYS_ATTR_DIRECTORY == FILE_SYS_ATTR_DIRECTORY;

If the UseAlternateDataStreams property is enabled, this event also fires anytime the OS wants to open a named data stream in a file. Such requests are distinguished by the presence of a colon (:) in the FileName value; the text before the colon is the name of the file itself, and the text after the colon is the name of the stream to open.

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

To handle this event properly, applications should perform any actions needed to open the requested file, directory, or named stream in their backend storage. Applications are also responsible for validating the access rights of the process that initiated the request before performing the requested operation; please refer to the Security Checks topic for more information.

If there is an existing local file that corresponds to the virtual one specified by FileName, the application may call RouteToFile to have the class route future requests directly to that file. This event's FileInfo value must be passed to RouteToFile for request routing to be configured successfully.

In certain cases, this event may fire for a file or directory that no longer exists. Normally this will not happen, as the OS already knows which files exist (based on information obtained via GetFileInfo/EnumerateDirectory) before it sends the open request. If, however, a file or directory is deleted externally, a race condition may occur where said deletion is not detected by the OS or virtual filesystem before the open request arrives. In such cases, applications must return the ERROR_FILE_NOT_FOUND error code via ResultCode.

The DesiredAccess parameter specifies the access mode desired by the process that initiated the request; it may contain one or more of the following access flags:

This value may differ from the one originally passed to the OS; the class alters it in the following cases:

• The DELETE flag is added if the requested CreateDisposition is FILE_SUPERSEDE.
• The FILE_WRITE_DATA, FILE_WRITE_EA, and FILE_WRITE_ATTRIBUTES flags are added if the requested CreateDisposition is FILE_OVERWRITE or FILE_OVERWRITE_IF.

The original CreateDisposition and DesiredAccess values are exposed through the NTCreateDisposition and NTDesiredAccess parameters.

Note: These values are in NT format; that is, as expected by the Windows API's ZwCreateFile function.

The Attributes parameter contains file attributes; it may contain one or more of the following attributes:

Attributes specifies both the attributes and create/open options for the new file. Some options, such as FILE_FLAG_SEQUENTIAL_SCAN, FILE_FLAG_WRITE_THROUGH, and FILE_FLAG_RANDOM_ACCESS, may be useful for applications that wish to fine-tune their performance. For example, such information could be used to decide whether it is necessary to locally cache some amount of data that is stored remotely.

The ShareMode parameter specifies the access sharing mode desired by the process that initiated the request; it may contain zero or more of the following share mode flags:

Please refer to the Windows API's ZwCreateFile function for detailed information about possible values for the DesiredAccess, Attributes, ShareMode, NTCreateDisposition, and NTDesiredAccess parameters.

The FileInfo parameter carries a handle to an object with information about the file. As mentioned earlier, this value should be used if the application chooses to call the RouteToFile method.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

QueryQuotas Event (Cbfs Class)

This event fires when the OS needs to read quota information.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void queryQuotas(CbfsQueryQuotasEvent e) {}
  ...
}

public class CbfsQueryQuotasEvent {
  public ByteBuffer SID;
  public int SIDLength;
  public int index;
  public boolean quotaFound;
  public long quotaUsed;
  public long quotaThreshold;
  public long quotaLimit;
  public ByteBuffer SIDOut;
  public int SIDOutLength;
  public long enumerationContext;
  public int resultCode;
}

Remarks

This event fires when the OS needs to read quota information, set during earlier SetQuotas events, for one or more security identifiers (SIDs).

This event needs to be handled only if the UseDiskQuotas property is enabled.

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

Quota information is read by the OS in one of two ways. To handle this event properly, applications must be able to handle both kinds of requests by doing the following:

1. When the OS needs a specific SID's quota information, SID will point to a memory buffer that contains that SID (in binary form, with length SIDLength).
   • If the application has a quota stored for the specified SID, set QuotaFound to true, and return its information by setting QuotaUsed, QuotaThreshold, and QuotaLimit.
   • If the application does not have quota information stored for the SID, set QuotaFound to false and leave the other parameters unchanged.
   • For such requests, Index is always -1, no SIDOut buffer is available, and SIDOutLength is 0.
2. When the OS needs all of the quota information the application has stored, this event fires with Index set to 0 first, then continues to fire with increasing indices until all quotas have been returned.
   • For each quota the application has stored, set QuotaFound to true, and return its information by setting QuotaUsed, QuotaThreshold, and QuotaLimit. Return the SID associated with the quota by copying it, in binary form, to the memory buffer pointed to by SIDOut. The capacity of the SIDOut buffer is specified by SIDOutLength.
   • If there are more quotas to return, set QuotaFound to false and leave the other parameters unchanged.
   • For such requests, no SID buffer is available, and SIDLength is 0.

Both this event and SetQuotas cause a quota enumeration to be started; the CloseQuotasEnumeration event will fire when the OS has finished reading quota information (this applies for both of the cases described above).

Descriptions of the QuotaUsed, QuotaThreshold, and QuotaLimit parameters can be found in the Windows API's DISKQUOTA_USER_INFORMATION structure documentation.

The EnumerationContext parameter is a placeholder for application-defined data associated with the enumeration. Please refer to the Contexts topic for more information.

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

ReadFile Event (Cbfs Class)

This event fires when the OS needs to read data from an open file.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void readFile(CbfsReadFileEvent e) {}
  ...
}

public class CbfsReadFileEvent {
  public String fileName;
  public long position;
  public ByteBuffer buffer;
  public long bytesToRead;
  public long bytesRead;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS needs to read data from the already open file specified by FileName.

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

To handle this event properly, applications should read BytesToRead bytes of data from the specified file into the memory region pointed to by Buffer. Reading must begin at the specified Position in the file, and when reading is complete, applications must set BytesRead to reflect the actual number of bytes copied into Buffer. Applications must not attempt to copy more than BytesToRead bytes of data into Buffer.

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

Note: Although it is technically possible for an application to return fewer than BytesToRead bytes of data, doing so is abnormal, and should be avoided. Most processes treat read requests as "all or nothing", so returning less data than requested is likely to cause an ungraceful failure.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken. (This parameter may be absent, in which case it will be 0.)

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (HandleContext may be absent, in which case it will be 0.)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

RenameOrMoveFile Event (Cbfs Class)

This event fires when the OS wants to rename or move a file or directory within the virtual filesystem.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void renameOrMoveFile(CbfsRenameOrMoveFileEvent e) {}
  ...
}

public class CbfsRenameOrMoveFileEvent {
  public String fileName;
  public String newFileName;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS wants to rename or move the specified file or directory from FileName to NewFileName, both of which are fully qualified and located in the virtual filesystem.

This event fires only if a file or directory with the specified NewFileName does not exist; or if such a file does exist, and an overwrite was requested. Cases in which a file with the specified NewFileName exists, and an overwrite was not requested, are handled by the class internally.

Note: Windows only allows files to be overwritten and denies a rename or move request automatically if the destination is an existing directory.

To handle this event properly, applications must perform any actions needed to rename or move the specified file or directory in their backend storage, overwriting the destination file if necessary. An application may also, for its own reasons, decide not to overwrite a destination file, in which case it must deny the operation by returning an appropriate error code via ResultCode.

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

When the FastRenameMove configuration setting is disabled, any handles to the file being renamed are closed before the rename operation and re-opened after the operation. If the rename operation fails, then the file handles are re-opened using the old name. If any of re-open operations fail, the re-opening process is stopped, and any handles that have been re-opened already are closed again.

In any case, the value specified by the ResultCode parameter is passed back to the system.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

Note: If the FastRenameMove config setting is disabled, all handles would be closed before the event fires; so, both HandleInfo, FileContext, and HandleContext will be empty. To receive the correct values in these parameters, you need to enable the FastRenameMove config setting.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

SetAllocationSize Event (Cbfs Class)

This event fires when the OS needs to set a file's allocation size.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void setAllocationSize(CbfsSetAllocationSizeEvent e) {}
  ...
}

public class CbfsSetAllocationSizeEvent {
  public String fileName;
  public long allocationSize;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS (or the class, if the CorrectAllocationSizes configuration setting is enabled) needs to set the allocation size of the file specified by FileName. All files have the following three sizes associated with them:

To handle this event properly, applications must perform any actions needed to allocate the specified amount of space for the file in their backend storage.

Note: The file's actual size should not be changed; applications that do not track allocation size separately from file size should do nothing.

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

The AllocationSize parameter specifies the new allocation size of the file, in bytes. This value is typically larger than the file's actual size, as some file operations reserve space for the file before any data are actually written. Applications should track such situations and avoid reallocating file space when possible to improve performance.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken. (This parameter may be absent, in which case it will be 0.)

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (HandleContext may be absent, in which case it will be 0.)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

SetDefaultQuotaInfo Event (Cbfs Class)

This event fires when the OS needs to set the virtual drive's default quota information.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void setDefaultQuotaInfo(CbfsSetDefaultQuotaInfoEvent e) {}
  ...
}

public class CbfsSetDefaultQuotaInfoEvent {
  public long defaultQuotaThreshold;
  public long defaultQuotaLimit;
  public long fileSystemControlFlags;
  public int resultCode;
}

Remarks

This event fires when the OS needs to set the virtual drive's default quota information.

This event needs to be handled only if the UseDiskQuotas property is enabled.

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

To handle this event properly, applications must store the virtual drive's default quota information using the value specified by DefaultQuotaThreshold, DefaultQuotaLimit, and FileSystemControlFlags.

Descriptions of the DefaultQuotaThreshold, DefaultQuotaLimit, and FileSystemControlFlags parameters can be found in the Windows API's FILE_FS_CONTROL_INFORMATION structure documentation.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

SetFileAttributes Event (Cbfs Class)

This event fires when the OS needs to change the attributes of an open file or directory.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void setFileAttributes(CbfsSetFileAttributesEvent e) {}
  ...
}

public class CbfsSetFileAttributesEvent {
  public String fileName;
  public java.util.Date creationTime;
  public java.util.Date lastAccessTime;
  public java.util.Date lastWriteTime;
  public java.util.Date changeTime;
  public int attributes;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS needs to change the attributes of the already-open file or directory specified by FileName.

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

To handle this event properly, applications must update the attributes of the specified file or directory in their backend storage using the following parameters:

• Attributes: The new attributes of the file or directory, or 0 to indicate that the existing attributes must remain unchanged.
  • FILE_ATTRIBUTE_NORMAL: This attribute is valid only when used alone; it "resets" a file's attributes.
  • Please refer to Microsoft's File Attribute Constants article for attribute descriptions.
  If the SupportCompressedAttribute property is set to true, an event handler should properly handle the presence or absence of the FILE_ATTRIBUTE_COMPRESSED in the Attributes parameter, possibly compressing or decompressing the file.
• CreationTime, LastAccessTime, LastWriteTime, ChangeTime: The new time values for the file or directory, any of which may be January 1, 1601 00:00:00 UTC to indicate that the existing value of the corresponding time must remain unchanged.
  • If the SupportLastAccessTimeAttribute property is disabled, LastAccessTime will always be January 1, 1601 00:00:00 UTC.
  • If the SupportChangeTimeAttribute property is disabled, ChangeTime will always be January 1, 1601 00:00:00 UTC.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

SetFileSecurity Event (Cbfs Class)

This event fires when the OS wants to change the Windows security attributes of a file or directory.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void setFileSecurity(CbfsSetFileSecurityEvent e) {}
  ...
}

public class CbfsSetFileSecurityEvent {
  public String fileName;
  public int securityInformation;
  public ByteBuffer securityDescriptor;
  public int length;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS wants to change the Windows security attributes of the file or directory specified by FileName.

This event needs to be handled only if the UseWindowsSecurity property is enabled.

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

To handle this event properly, applications must update the pieces of security information, specified by SecurityInformation, on the specified file or directory in their backend storage. Please refer to the following parameter descriptions, as well as the Security Checks topic, for more information.

The SecurityInformation parameter indicates which pieces of security information must be set. This value is a bitfield; possible flags include (but are not limited to):

• OWNER_SECURITY_INFORMATION
• GROUP_SECURITY_INFORMATION
• DACL_SECURITY_INFORMATION
• SACL_SECURITY_INFORMATION

Please refer to Microsoft's SECURITY_INFORMATION data-type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that contains data indicated by SecurityInformation. The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format. Please refer to those articles for more information about self-relative security descriptors.

The Length parameter specifies the length, in bytes, of SecurityDescriptor.

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

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

SetFileSize Event (Cbfs Class)

This event fires when the OS needs to change the size of an open file.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void setFileSize(CbfsSetFileSizeEvent e) {}
  ...
}

public class CbfsSetFileSizeEvent {
  public String fileName;
  public long size;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS needs to change the size of the already-open file specified by FileName. All files have the following three sizes associated with them:

To handle this event properly, applications must perform any actions needed to resize the specified file in their backend storage.

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

The Size parameter specifies the new size of the file, in bytes. Extending a file does not require actual space to be allocated; however, NTFS allocates and zeroes the newly added space, and some third-party applications might expect such behavior if the virtual filesystem is identified (via FileSystemName) as NTFS.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

SetQuotas Event (Cbfs Class)

This event fires when the OS needs to update quota information.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void setQuotas(CbfsSetQuotasEvent e) {}
  ...
}

public class CbfsSetQuotasEvent {
  public ByteBuffer SID;
  public int SIDLength;
  public boolean removeQuota;
  public boolean quotaFound;
  public long quotaUsed;
  public long quotaThreshold;
  public long quotaLimit;
  public long enumerationContext;
  public int resultCode;
}

Remarks

This event fires when the OS needs to set, update, or remove quota information for the security identifier specified by SID. If quota information needs to be set/updated/removed for multiple security identifiers (SIDs), this event will fire multiple times in succession.

This event needs to be handled only if the UseDiskQuotas property is enabled.

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

To handle this event properly, applications must either store or remove the quota information for the security identifier specified by SID:

• If RemoveQuota is false, set or update the SID's quota information using the values specified by QuotaUsed, QuotaFound, and QuotaLimit.
• If RemoveQuota is true, and the application has quota information stored for the SID, remove that information and set QuotaFound to true. If the application does not have quota information stored for the SID, set QuotaFound to false.

Both this event and QueryQuotas cause a quota enumeration to be started; the CloseQuotasEnumeration event will fire when the OS has finished setting/updating/removing quota information.

Descriptions of the QuotaUsed, QuotaThreshold, and QuotaLimit parameters can be found in the Windows API's DISKQUOTA_USER_INFORMATION structure documentation.

The EnumerationContext parameter is a placeholder for application-defined data associated with the enumeration. Please refer to the Contexts topic for more information.

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

SetReparsePoint Event (Cbfs Class)

This event fires when the OS wants to create or update a reparse point on a file or directory.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void setReparsePoint(CbfsSetReparsePointEvent e) {}
  ...
}

public class CbfsSetReparsePointEvent {
  public String fileName;
  public long reparseTag;
  public ByteBuffer reparseBuffer;
  public int reparseBufferLength;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS wants to create or update a reparse point on the file or directory specified by FileName.

This event needs to be handled only if the UseReparsePoints property is enabled.

Note: Network file sharing (NFS) makes use of reparse points.

To handle this event properly, applications must store the given reparse point data and tag, and associate them with the specified file or directory, in their backend storage. Both pieces of information are needed for the application to correctly handle any future GetFileInfo and EnumerateDirectory events concerning the specified file or directory.

Please refer to the Reparse Points topic for more information.

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

The ReparseTag parameter specifies the reparse point's tag, which is the value the system uses to identify the format of the reparse point data. This value is also present in the ReparseBuffer data; the class extracts it and provides it separately for convenience.

The ReparseBuffer parameter points to a memory buffer that contains the full reparse point data. The ReparseBufferLength parameter specifies the length, in bytes, of ReparseBuffer.

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

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

SetValidDataLength Event (Cbfs Class)

This event fires when the OS needs to set a file's valid data length.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void setValidDataLength(CbfsSetValidDataLengthEvent e) {}
  ...
}

public class CbfsSetValidDataLengthEvent {
  public String fileName;
  public long validDataLength;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS needs to set the valid data length of the file specified by FileName. All files have the following three sizes associated with them:

Typically, a file's valid data length is explicitly changed only when a process wishes to quickly allocate large amounts of storage space. In such cases, the SetFileSize event will fire first to set the desired file size, and then this event will fire to inform the virtual filesystem that it does not need to fill that space with zeros. Please refer to the Windows API's SetFileValidData function documentation for more information.

To handle this event properly, applications must perform any actions needed to update the specified file's valid data length.

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

The ValidDataLength parameter specifies the new valid data length, in bytes, for the file. This is the same value as passed to the Windows API's SetFileValidData function.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken. (This parameter may be absent, in which case it will be 0.)

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (HandleContext may be absent, in which case it will be 0.)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

SetVolumeLabel Event (Cbfs Class)

This event fires when the OS wants to change the volume label.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void setVolumeLabel(CbfsSetVolumeLabelEvent e) {}
  ...
}

public class CbfsSetVolumeLabelEvent {
  public String volumeLabel;
  public int resultCode;
}

Remarks

This event fires when the OS wants to change the volume label of the virtual drive.

To handle this event properly, applications must store the new volume label specified by VolumeLabel.

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

SetVolumeObjectId Event (Cbfs Class)

This event fires when the OS needs to set the volume object Id and extended information.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void setVolumeObjectId(CbfsSetVolumeObjectIdEvent e) {}
  ...
}

public class CbfsSetVolumeObjectIdEvent {
  public ByteBuffer objectId;
  public int objectIdLength;
  public ByteBuffer extendedInformation;
  public int extendedInformationLength;
  public int resultCode;
}

Remarks

This event fires when the OS needs to set the volume object Id and extended information for the virtual drive.

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

To handle this event properly, applications must store the values specified by ObjectId and ExtendedInformation.

The ObjectIdLength and ExtendedInformationLength values are specified by the OS; they will always be 16 and 48 bytes, respectively.

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

UnlockFile Event (Cbfs Class)

This event fires when the OS needs to unlock a range of bytes in a file.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void unlockFile(CbfsUnlockFileEvent e) {}
  ...
}

public class CbfsUnlockFileEvent {
  public String fileName;
  public long byteOffset;
  public long length;
  public int key;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS needs to unlock a range of bytes in the file specified by FileName. Typically, such requests originate from the Windows API's UnlockFile and UnlockFileEx functions.

This event is optional. The CBFS class automatically manages file locks in the virtual filesystem. So, if the resources an application uses for backend storage (e.g., files, memory, a database) are never directly accessed by anything other than the application itself, then there is no reason to implement this event.

If, however, an application's backend storage involves shared resources (i.e., those that could be accessed by something other than the application at any time), then this event should be used to perform any actions needed to propagate the unlock request.

For example, if an application's backend storage implementation involves files stored on a network server, then the unlock request should be communicated to that server.

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

Applications that implement this event must also implement the LockFile event.

The ByteOffset and Length parameters specify the starting position of the range being unlocked, and the length of that range, respectively. If both values are set to -1, the system has sent IRP_MN_UNLOCK_ALL request and all regions must be unlocked. The latter behavior is used only when the SupportUnlockAllRequests configuration setting is explicitly enabled by the application.

The Key parameter reflects the key that the byte range lock is associated with. This key is used to identify the byte range lock. The value is the same that was passed in the Lock request that locked the region, which currently is unlocked using this request.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

Note: The OS does not expect the file unlock request to fail and ignores the error code that is returned by the class.

Unmount Event (Cbfs Class)

This event fires after the class unmounts media from the virtual drive, making it unavailable.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void unmount(CbfsUnmountEvent e) {}
  ...
}

public class CbfsUnmountEvent {
  public int resultCode;
}

Remarks

This event fires once the class has unmounted media from the virtual drive, making it unavailable. Please refer to UnmountMedia and DeleteStorage for more information.

This event is optional; it is provided to give applications a chance to perform additional processing when the virtual filesystem becomes unavailable.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

WorkerThreadCreation Event (Cbfs Class)

Fires just after a new worker thread is created.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void workerThreadCreation(CbfsWorkerThreadCreationEvent e) {}
  ...
}

public class CbfsWorkerThreadCreationEvent {
  public int resultCode;
}

Remarks

This event fires just after a worker thread is created, in the context of that worker thread.

This event is optional; it is provided to give applications a chance to perform additional processing when a new worker thread is created, such as allocating per-thread objects.

The class maintains a pool of worker threads and uses them to fire events; please refer to the Threading and Concurrency topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

WorkerThreadTermination Event (Cbfs Class)

Fires just before a worker thread is terminated.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void workerThreadTermination(CbfsWorkerThreadTerminationEvent e) {}
  ...
}

public class CbfsWorkerThreadTerminationEvent {
}

Remarks

This event fires just before a worker thread is terminated, in the context of that worker thread.

This event is optional; it is provided to give applications a chance to perform additional processing before a worker thread is terminated, such as deallocating per-thread objects.

The class maintains a pool of worker threads and uses them to fire events; please refer to the Threading and Concurrency topic for more information.

Any errors that occur during this event are ignored.

WriteFile Event (Cbfs Class)

This event fires when the OS needs to write data to an open file.

Syntax

public class DefaultCbfsEventListener implements CbfsEventListener {
  ...
  public void writeFile(CbfsWriteFileEvent e) {}
  ...
}

public class CbfsWriteFileEvent {
  public String fileName;
  public long position;
  public ByteBuffer buffer;
  public long bytesToWrite;
  public long bytesWritten;
  public long handleInfo;
  public long fileContext;
  public long handleContext;
  public int resultCode;
}

Remarks

This event fires when the OS needs to write data to the already-open file specified by FileName.

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

To handle this event properly, applications should write BytesToWrite bytes of data to the specified file, copying it from the memory region pointed to by Buffer. Writing must begin at the specified Position in the file, and when writing is complete, applications must set BytesWritten to reflect the actual number of bytes written to the file. Applications must not attempt to copy more than BytesToWrite bytes of data from Buffer.

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

Note: Although it is technically possible for an application to write fewer than BytesToWrite bytes of data, doing so is abnormal, and should be avoided. Most processes treat write requests as "all or nothing", so writing less data than requested is likely to cause an ungraceful failure.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: GetHandleCreatorProcessId, GetHandleCreatorProcessName, GetHandleCreatorThreadId, or GetHandleCreatorToken. (This parameter may be absent, in which case it will be 0.)

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (HandleContext may be absent, in which case it will be 0.)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

Note: In most cases, the event is fired when the cache needs to write the data to the filesystem. This happens asynchronously, later than process(es) called the WriteFile() function or alternatives. For such asynchronous write events, the result code returned by the event handler does not get back to the process or processes that wrote the data.

MountingPoint Type

Represents a mounting point for the virtual drive.

Remarks

This type represents a mounting point for the virtual drive.

Fields

OpenFile Type

This type represents an open filesystem object from the virtual drive.

Remarks

This type represents an open filesystem object (e.g., file, directory) from the virtual drive.

Fields

ProcessAccessRule Type

Represents an access rule granting or denying some process a specific access right.

Remarks

This type represents an access rule that grants or denies some process a specific access right.

Fields

Config Settings (Cbfs Class)

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

CBFS Config Settings

Base Config Settings

Trappable Errors (Cbfs Class)

The class uses Windows error codes during operation as necessary. Please refer to the Error Reporting and Handling topic for more information.

Special Use Errors

	21   ERROR_NOT_READY: Reported by the methods of the class if Initialize has not been called or did not succeed.
	400   ERROR_THREAD_MODE_ALREADY_BACKGROUND: Reported by DispatchEvents when the class is not in a single-threaded mode.
	575   ERROR_APP_INIT_FAILURE: Reported by the methods of the class if Initialize has not been called or did not succeed. Differs from ERROR_NOT_READY (21) in that it indicates a specific situation in the internal code.
	588   ERROR_FS_DRIVER_REQUIRED: Reported if the required system module was not correctly installed for the given ProductGUID.
	614   ERROR_NO_CALLBACK_ACTIVE: Reported by any method that can only be called within event handlers if it is called outside an event handler.
	1006   ERROR_FILE_INVALID: Event handlers may return this error code to tell the driver that the file or directory, to which the operation is related, has been changed externally. Doing this will fail the operation with the corresponding error code and tell the driver to update the information it has about the file or directory. This special handling is not available for GetFileInformation and EnumerateDirectory events.
	1292   ERROR_IMPLEMENTATION_LIMIT: Reported when the timeout value provided is less than 3 seconds.
	1314   ERROR_PRIVILEGE_NOT_HELD: Reported by any method that requires elevated permissions if it is called without such permissions.