EnumerateDirectory Event

Fires when the OS wants to enumerate a directory's contents.

Syntax

class CBFSEnumerateDirectoryEventParams {
public:
  const QString &DirectoryName();
  const QString &Mask();
  bool CaseSensitive();
  bool Restart();
  bool FileFound();
  void SetFileFound(bool bFileFound);
  const QString &FileName();
  bool SetFileName(const QString &lpFileName);
  const QString &ShortFileName();
  bool SetShortFileName(const QString &lpShortFileName);
  const QDateTime &CreationTime();
  void SetCreationTime(const QDateTime &qdtCreationTime);
  const QDateTime &LastAccessTime();
  void SetLastAccessTime(const QDateTime &qdtLastAccessTime);
  const QDateTime &LastWriteTime();
  void SetLastWriteTime(const QDateTime &qdtLastWriteTime);
  const QDateTime &ChangeTime();
  void SetChangeTime(const QDateTime &qdtChangeTime);
  qint64 Size();
  void SetSize(qint64 lSize);
  qint64 AllocationSize();
  void SetAllocationSize(qint64 lAllocationSize);
  qint64 FileId();
  void SetFileId(qint64 lFileId);
  qint64 Attributes();
  void SetAttributes(qint64 lAttributes);
  qint64 ReparseTag();
  void SetReparseTag(qint64 lReparseTag);
  qint64 HandleInfo();
  void *DirectoryContext();
  void SetDirectoryContext(void *lpDirectoryContext);
  void *HandleContext();
  void SetHandleContext(void *lpHandleContext);
  void *EnumerationContext();
  void SetEnumerationContext(void *lpEnumerationContext);
  int ResultCode();
  void SetResultCode(int iResultCode);
  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void EnumerateDirectory(CBFSEnumerateDirectoryEventParams *e);
// Or, subclass CBFS and override this emitter function. virtual int FireEnumerateDirectory(CBFSEnumerateDirectoryEventParams *e) {...}

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

To handle this event properly, applications must return information about each directory entry (file, subdirectory, link) that matches the specified Mask. For each matching entry found, set FileFound to true 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.
    • The parameter's setter function will return false if the specified value is too long.
  • 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.
    • The parameter's setter function will return false if the specified value is too long.
  • 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.
  • 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.
  • ReparseTag: If the UseReparsePoints property is enabled, and the entry is a reparse point, set to the reparse point's tag.
    • Also, be sure 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.

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. When TranslateDOSCharsInEnumMasks is false, this parameter may contain so called DOS wildcard (please, refer to the description of this setting for more information).

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: 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 via the virtual disk), your application needs to track the changes and use NotifyDirectoryChange as needed; this 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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Copyright (c) 2022 Callback Technologies, Inc. - All rights reserved.
CBFS Connect 2020 Qt Edition - Version 20.0 [Build 8348]