OnEnumerateDirectory event/delegate/callback
Filter:
Pascal C++ (Lib) C++ (VCL) C++ (.NET) C# VB.NET JavaOverview
The event is fired when the OS needs to enumerate directory contents.
Declaration
[Pascal]
property OnEnumerateDirectory : TCbFsEnumerateDirectoryEvent;
TCbFsEnumerateDirectoryEvent = procedure(
Sender : TObject;
DirectoryInfo: TCbFsFileInfo;
var EnumerationContext: pointer;
Mask: TCBString;
Index: integer;
Restart: boolean;
var FileFound: Boolean;
var FileName: TCBString;
var FileNameLength: word;
var ShortFileName: TCBString;
var ShortFileNameLength: byte;
var CreationTime: TDateTime;
var LastAccessTime: TDateTime;
var LastWriteTime: TDateTime;
var EndOfFile: Int64;
var AllocationSize: Int64;
var FileId: Int64;
var FileAttributes: LongWord
) of object;
type TCBString = {$ifdef UNICODE}UnicodeString{$else}WideString{$endif};
[C++ (Lib)]
void (__stdcall *CbFsEnumerateDirectoryEvent)(void* Sender,
CbFsFileInfo* DirectoryInfo,
PVOID* EnumerationContext,
LPCWSTR Mask,
INT Index,
BOOL Restart,
LPBOOL FileFound,
LPWSTR FileName,
LPSHORT FileNameLength,
LPWSTR ShortFileName,
LPUCHAR ShortFileNameLength,
FILETIME * CreationTime,
FILETIME * LastAccessTime,
FILETIME * LastWriteTime,
__int64 * EndOfFile,
__int64 * AllocationSize,
__int64 * FileId,
DWORD * FileAttributes
);
[C++ (VCL)]
typedef void (__closure *TCbFsEnumerateDirectoryEvent)(
System::TObject* Sender,
CbFsFileInfo* DirectoryInfo,
void ** EnumerationContext,
WideString Mask,
long Index,
bool Restart,
bool & FileFound,
WideString & FileName,
unsigned short & FileNameLength,
WideString & ShortFileName,
unsigned char & ShortFileNameLength,
TDateTime & CreationTime,
TDateTime & LastAccessTime,
TDateTime & LastWriteTime,
__int64 & EndOfFile,
__int64 & AllocationSize,
__int64 & FileId,
unsigned long & FileAttributes
);
[C++ (.NET)]
public __delegate void CbFsEnumerateDirectoryEvent(
CallbackFileSystem^ Sender,
CbFsFileInfo^ DirectoryInfo,
IntPtr% EnumerationContext,
String^ Mask,
long Index,
bool Restart,
bool% FileFound,
String^% FileName,
UInt16% FileNameLength,
String^% ShortFileName,
Byte% ShortFileNameLength,
DateTime% CreationTime,
DateTime% LastAccessTime,
DateTime% LastWriteTime,
Int64% EndOfFile,
Int64% AllocationSize,
Int64% FileId,
UInt32% FileAttributes
);
[C#]
public void CbFsEnumerateDirectoryEvent(
CallbackFileSystem Sender,
CbFsFileInfo DirectoryInfo,
ref IntPtr EnumerationContext,
String Mask,
int Index,
bool Restart,
ref bool FileFound,
ref String FileName,
ref UInt16 FileNameLength,
ref String ShortFileName,
ref Byte ShortFileNameLength,
ref DateTime CreationTime,
ref DateTime LastAccessTime,
ref DateTime LastWriteTime,
ref Int64 EndOfFile,
ref Int64 AllocationSize,
ref Int64 FileId,
ref UInt32 FileAttributes
);
[VB.NET]
Sub CbFsEnumerateDirectoryEvent(
ByVal Sender As CallbackFileSystem,
ByRef DirectoryInfo As TCbFsFileInfo,
ByRef EnumerationContext As IntPtr,
ByVal Mask As String,
ByVal Index As Integer,
ByVal Restart As Boolean,
ByRef FileFound As Boolean,
ByRef FileName As String,
ByRef FileNameLength As UInt16,
ByRef ShortFileName As String,
ByRef ShortFileNameLength As Byte,
ByRef CreationTime As DateTime,
ByRef LastAccessTime As DateTime,
ByRef LastWriteTime As DateTime,
ByRef EndOfFile As Int64,
ByRef AllocationSize As Int64,
ByRef FileId As Int64,
ByRef FileAttributes As UInt32
)
[Java]
void ICbFsEnumerateEvents.onEnumerateDirectory(
String fileName,
CbFsFileInfo directoryInfo,
byteArrayRef enumerationContext,
String mask,
int index,
boolean restart,
boolRef fileFound,
stringRef LongFileName,
intRef fileNameLength,
stringRef shortLongFileName,
byteRef shortFileNameLength,
dateRef creationTime,
dateRef lastAccessTime,
dateRef lastWriteTime,
longRef endOfFile,
longRef allocationSize,
longRef fileId,
longRef fileAttributes
);
Parameters
- Sender - reference to the class that called the delegate/event handler.
- DirectoryInfo - the information about the directory which is being read
- EnumerationContext - the placeholder for the application-defined data
- 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 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, stored in FileName, to this parameter
- ShortFileName - if short file name support is enabled, place the short name of the file to this parameter
- ShortFileNameLength - place the length of the file name, stored in ShortFileName, to this parameter
- CreationTime - place the time of the object creation to 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 to 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 to this parameter. The value can be empty (zero in VCL, DateTime.MinValue in .NET) if the parameter is not supported.
- EndOfFile - place the size of the file data in bytes to this parameter.
- AllocationSize - place the size of the space in bytes, allocated for the file, to this parameter. The allocation size is usually a multiple of the allocation unit size.
- FileId - Currently unused.
- FileAttributes - place the file attributes to this parameter
Description
This event is fired when the OS wants to enumerate the directory entries by mask.
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.
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. So you must be ready to handle any mask, and not just "*" or "*.*".
If this is the first call to enumerate the directory entries, EnumerationContext can be used to store information, which speeds up subsequent enumeration calls.
The application can use EnumerateContext 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.
Error handling
See Error handling topic for detailed information about how to report errors, which occur in the event handlers, back to Callback File System.
See also
Got questions or comments about this topic? Tell us about them.