EnumerateDirectory Event

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

Syntax

ANSI (Cross Platform)
virtual int FireEnumerateDirectory(CBFSEnumerateDirectoryEventParams *e);
typedef struct {
const char *DirectoryName;
const char *Mask;
int CaseSensitive;
int Restart;
int FileFound;
char *FileName; int lenFileName;
char *ShortFileName; int lenShortFileName;
int64 *pCreationTime;
int64 *pLastAccessTime;
int64 *pLastWriteTime;
int64 *pChangeTime;
int64 *pSize;
int64 *pAllocationSize;
int64 *pFileId;
int64 *pAttributes;
int64 *pReparseTag;
int64 HandleInfo;
void *DirectoryContext;
void *HandleContext;
void *EnumerationContext;
int ResultCode; int reserved; } CBFSEnumerateDirectoryEventParams; Unicode (Windows) virtual INT FireEnumerateDirectory(CBFSEnumerateDirectoryEventParams *e);
typedef struct {
LPCWSTR DirectoryName;
LPCWSTR Mask;
BOOL CaseSensitive;
BOOL Restart;
BOOL FileFound;
LPWSTR FileName; INT lenFileName;
LPWSTR ShortFileName; INT lenShortFileName;
LONG64 *pCreationTime;
LONG64 *pLastAccessTime;
LONG64 *pLastWriteTime;
LONG64 *pChangeTime;
LONG64 *pSize;
LONG64 *pAllocationSize;
LONG64 *pFileId;
LONG64 *pAttributes;
LONG64 *pReparseTag;
LONG64 HandleInfo;
LPVOID DirectoryContext;
LPVOID HandleContext;
LPVOID EnumerationContext;
INT ResultCode; INT reserved; } CBFSEnumerateDirectoryEventParams;
#define EID_CBFS_ENUMERATEDIRECTORY 13

virtual INT CBFSCONNECT_CALL FireEnumerateDirectory(LPWSTR &lpszDirectoryName, LPWSTR &lpszMask, BOOL &bCaseSensitive, BOOL &bRestart, BOOL &bFileFound, LPWSTR &lpFileName, INT &lenFileName, LPWSTR &lpShortFileName, INT &lenShortFileName, LONG64 &lCreationTime, LONG64 &lLastAccessTime, LONG64 &lLastWriteTime, LONG64 &lChangeTime, LONG64 &lSize, LONG64 &lAllocationSize, LONG64 &lFileId, LONG64 &lAttributes, LONG64 &lReparseTag, LONG64 &lHandleInfo, LPVOID &lpDirectoryContext, LPVOID &lpHandleContext, LPVOID &lpEnumerationContext, INT &iResultCode);

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 name must be copied to FileName; set lenFileName to the length of the copied string (measured in char/wchar_t, not including terminating nulls).
    • 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 name must be copied to ShortFileName; set lenShortFileName to the length of the copied string (measured in char/wchar_t, not including terminating nulls).
    • 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 as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as FILETIME. Any time values not applicable to the entry can be left unchanged, or set to 0.
  • 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 C++ Edition - Version 20.0 [Build 8348]