OnEnumerateDirectory event/delegate/callback


Pascal    C++ (Lib)    C++ (VCL)    C++ (.NET)    C#    VB.NET    Java 

CBFSConnect     See also    


The event is fired when the OS needs to enumerate directory contents.


    property OnEnumerateDirectory : TCBEnumerateDirectoryEvent;
    TCBEnumerateDirectoryEvent = procedure( Sender : TObject; DirectoryInfo: TCBFileInfo; HandleInfo: TCBHandleInfo; EnumerationInfo: TCBDirectoryEnumerationInfo; Mask: TCBString; Index: integer; Restart: boolean; var FileFound: Boolean; var FileName: TCBString; var ShortFileName: TCBString; var CreationTime: TDateTime; var LastAccessTime: TDateTime; var LastWriteTime: TDateTime; var ChangeTime: TDateTime; var EndOfFile: Int64; var AllocationSize: Int64; var FileId: Int64; var FileAttributes: LongWord; var ReparseTag: LongWord ) of object;
    type TCBString = {$ifdef UNICODE}UnicodeString{$else}WideString{$endif};

[C++ (Lib)]
    void (__stdcall *CBEnumerateDirectoryEvent)(void* Sender, CBFileInfo* DirectoryInfo, CBHandleInfo* HandleInfo, CBDirectoryEnumerationInfo* EnumerationInfo, LPCWSTR Mask, INT Index, BOOL Restart, LPBOOL FileFound, LPWSTR FileName, LPSHORT FileNameLength, LPWSTR ShortFileName, LPUCHAR ShortFileNameLength, FILETIME * CreationTime, FILETIME * LastAccessTime, FILETIME * LastWriteTime, FILETIME * ChangeTime, __int64 * EndOfFile, __int64 * AllocationSize, __int64 * FileId, PDWORD FileAttributes, PDWORD ReparseTag );

[C++ (VCL)]
    typedef void (__closure *TCBEnumerateDirectoryEvent)( System::TObject* Sender, TCBFileInfo* DirectoryInfo, TCBHandleInfo* HandleInfo, TCBDirectoryEnumerationInfo* EnumerationInfo, TCBString Mask, long Index, bool Restart, bool & FileFound, TCBString & FileName, TCBString & ShortFileName, TDateTime & CreationTime, TDateTime & LastAccessTime, TDateTime & LastWriteTime, TDateTime & ChangeTime, __int64 & EndOfFile, __int64 & AllocationSize, __int64 & FileId, unsigned long & FileAttributes, unsigned long & ReparseTag );

[C++ (.NET)]
    public __delegate void CBEnumerateDirectoryEvent( CBFSConnect^ Sender, CBFileInfo^ DirectoryInfo, CBHandleInfo^ HandleInfo, CBDirectoryEnumerationInfo^ EnumerationInfo, String^ Mask, long Index, bool Restart, bool% FileFound, String^% FileName, String^% ShortFileName, DateTime% CreationTime, DateTime% LastAccessTime, DateTime% LastWriteTime, DateTime% ChangeTime, Int64% EndOfFile, Int64% AllocationSize, Int64% FileId, UInt32% FileAttributes, UInt32% ReparseTag );

    public void CBEnumerateDirectoryEvent( CBFSConnect Sender, CBFileInfo DirectoryInfo, CBHandleInfo HandleInfo, CBDirectoryEnumerationInfo EnumerationInfo, String Mask, int Index, bool Restart, ref bool FileFound, ref String FileName, ref String ShortFileName, ref DateTime CreationTime, ref DateTime LastAccessTime, ref DateTime LastWriteTime, ref DateTime ChangeTime, ref Int64 EndOfFile, ref Int64 AllocationSize, ref Int64 FileId, ref UInt32 FileAttributes, ref UInt32 ReparseTag );

    Sub CBEnumerateDirectoryEvent( ByVal Sender As CBFSConnect, ByVal DirectoryInfo As TCBFileInfo, ByVal HandleInfo As CBHandleInfo, ByVal EnumerationInfo As CBDirectoryEnumerationInfo, ByVal Mask As String, ByVal Index As Integer, ByVal Restart As Boolean, ByRef FileFound As Boolean, ByRef FileName As String, ByRef ShortFileName As String, ByRef CreationTime As DateTime, ByRef LastAccessTime As DateTime, ByRef LastWriteTime As DateTime, ByRef ChangeTime As DateTime, ByRef EndOfFile As Int64, ByRef AllocationSize As Int64, ByRef FileId As Int64, ByRef FileAttributes As UInt32, ByRef ReparseTag As UInt32 )

    void ICbFsEnumerateEvents.onEnumerateDirectory( String fileName, CBFileInfo directoryInfo, CBHandleInfo handleInfo, CBDirectoryEnumerationInfo enumerationInfo, String mask, int index, boolean restart, boolRef fileFound, stringRef LongFileName, stringRef shortLongFileName, dateRef creationTime, dateRef lastAccessTime, dateRef lastWriteTime, dateRef changeTime, longRef endOfFile, longRef allocationSize, longRef fileId, longRef fileAttributes, longRef ReparseTag );


  • Sender - reference to the class that called the delegate/event handler.
  • DirectoryInfo - information about the directory which is being read. This structure is common to all directory operations that occur at the same time in parallel.
  • HandleInfo - information about particular directory handle which was opened for the purpose of directory enumeration
  • EnumerationInfo - information about current enumeration
  • Mask - the file mask to search the files
  • Index - the index of the directory entry, for which the information is requested. In modern OS this parameter is not used and -1 is passed.
  • Restart - signals that the request for the entry was already done, but the entry should be searched for once again, starting at the beginning of the directory
  • FileFound - set this parameter to true if the file exists and the information is provided and false otherwise
  • FileName - set this parameter to the name of the found file or directory.
    [C++ (Lib)] The buffer of size MaxFileNameLength +1 characters is passed by the caller. The event handler must put the file name to this buffer.
  • FileNameLength - place the length of the file name (in characters without trailing NULL), stored in FileName, in this parameter
  • ShortFileName - if short file name support is enabled, place the short name of the file in this parameter
  • ShortFileNameLength - place the length of the file name (in characters without trailing NULL), stored in ShortFileName, in this parameter
  • CreationTime - place the time of the object creation in this parameter. The value can be empty (zero in VCL, DateTime.MinValue in .NET) if the parameter is not supported.
  • LastAccessTime - place the time of last access to the object in this parameter. The value can be empty (zero in VCL, DateTime.MinValue in .NET) or equal if the parameter is not supported.
  • LastWriteTime - place the time of last modification of the object in this parameter. The value can be empty (zero in VCL, DateTime.MinValue in .NET) if the parameter is not supported.
  • ChangeTime - place the time of last change of the object contents or metadata (eg. security attributes) in this parameter.
    Set ChangeTimeAttributeSupported property to true if you plan to use this parameter.
    Keep the parameter unchanged if you don't want to set the time. In this case the last modification time is used.
  • EndOfFile - place the size of the file data in bytes in this parameter.
  • AllocationSize - place the size of the space in bytes, allocated for the file, in this parameter. The allocation size is usually a multiple of the allocation unit size.
  • FileId - Currently unused.
  • FileAttributes - place the file attributes in this parameter
  • ReparseTag - if the entry is a reparse point, place its tag in this parameter


This event is fired when the OS wants to enumerate the directory entries by mask.

The mask can (but not necessarily does) include wildcard characters ("*" and "?") and any characters, allowed in file names, in any combination. Eg. you can recieve masks like "smth?*.abc?e?*" and other complex combinations.

The application must report information about the entry (file, directory, link) in the directory specified by DirectoryInfo. If the entry is present, FileFound must be set to true and the information about the entry must be included. If the entry is not present, FileFound must be set to false.

Time-related parameters (CreationTime, LastAccessTime, LastWriteTime) are in UTC timezone.

This event can be fired in some other cases, such as when the application uses FindFirtFile with file name (i.e. no wildcards in Mask) to get information provided about the file during enumeration or even before opening the file. So you must be ready to handle any mask (and just a file name without wildcard characters), and not just "*" or "*.*".

Context in EnumerationInfo can be used to store information, which speeds up subsequent enumeration calls. The application can use this context to store the reference to some information, identifying the search (such as directory handle or database record ID etc). The value, set in the event handler, is later passed to all operations, related to this enumeration, i.e. subsequent calls to OnEnumerateDirectory and OnCloseEnumeration event handlers.
Read more about contexts.

The entry to be reported is identified by the data that the application stores in Enumeration Context. It is the application's job to track what entry it needs to report next.

If you have enabled short file name support, your callback can receive a short directory name in DirectoryInfo. Also if you support short file names, you should provide the short file name via ShortFileName parameter. To speed-up operations (save one string length measurement) CBFS doesn't measure the length of the passed short file name (you will know it when putting it to ShortFileName) so your code must put the length of the passed short file name into ShortFileNameLength.

If your application supports reparse points, and the entry is a reparse point, then you need to place the tag of this point, which you have stored when the reparse point was created, to ReparseTag parameter, and return FILE_ATTRIBUTE_REPARSE_POINT in FileAttributes parameter along with other attributes. Read more about reparse points.

Error handling

See Error handling topic for detailed information about how to report errors, which occur in the event handlers, back to CBFS Connect.

See also

ChangeTimeAttributeSupported property     OnCloseDirectoryEnumeration event