Copyright© Kambiz R. Khojasteh. All rights reserved.
Get future component updates from http://www.delphiarea.com.

• Delphi 3
• Delphi 4
• Delphi 5
• Delphi 6
• Delphi 7
• Delphi 2005
• Delphi 2006
• Delphi 2007
• Delphi 2009
• Delphi 2010

DESCRIPTION

TFindFile is a non-visual component, which can be used for locating files or folders in the file system and directory tree with an extensive set of conditions.

TFindFile is capable to locate files based on:

• Location as local or UNC path with support for directory level confining
• Filename with wildcard support
• All documented NT file attributes
• Range of file size
• Range of file creation date and/or time
• Range of file last modification date and/or time
• Range of file last accessed date and/or time
• Content of the file with support for ASCII, Unicode (little and big endian), and UTF-8 encodings

In addition, TFindFile can use a separate and dedicated thread to do the search in background.

Note: If you have TNT Unicode Controls, you can install TFindFileW on Delphi 2007 and earlier. TFindFileW is the Unicode version of TFindFile.

PROPERTIES

• Criteria: TSearchCriteria
  Contains the search criteria.
  • Files: TFileCriteria
    Contains file and folder criteria.
    • Filename: String
      Specifies the target filenames separated by semicolon. The filenames can contain * and ? wildcards.
    • Location: String
      Determines the target folders separated by semicolon.
    • Paths: TStringList
      Contains the list of target files as full path. The filename part of the paths can contain * and ? wildcards. You may use this property alternative to or in conjunction with Filename and Location properties.
    • Filters: TStringList
      Contains list of wildcards that filter files based on their full path. Any file that matches a filter does not appear in the search result.

      You can put a right angle sign (>) in front of a filter to toggle its behavior. Any file that matches this kind of filters considers as accepted.

      Examples:

      >*delphi*		Includes all files that contain 'delphi' in their full path
      >\\Server\*.txt		Includes all text files on computer named 'Server'
      C:\Windows\*\*.txt		Excludes all text files in the second level subfolders of 'C:\Windows' directory
      >*\src\*.txt		Includes all text files in 'src' subfolder of any folder of any drive and network location
      ?:*\lib\*.txt		Excludes all text files in 'lib' subfolder of any folder of any drive
      ?*\readme.txt		Excludes all readme.txt files

      Note: Filters apply on the files in the order that they appear in the list.
      Note: Optionally you can use a left angle sign (<) in front of excluding filters.

    • Subfolders: Boolean
      If set to true, subfolders of the target folders specified in Location and Paths properties will be included in the search.
      To know how to include or exclude subfolders on every individual folder see Folder Meta Parameters.
    • MinLevel: Word
      Determines the minimum directory level from the base folder for the target files. Set this property to zero if you do not need this feature.
      To know how to set MinLevel on every individual folder see Folder Meta Parameters.
    • MaxLevel: Word
      Determines the maximum directory level from the base folder for the target files. Set this property to zero if you do not need this feature.
      To know how to set MinLevel on every individual folder see Folder Meta Parameters.
  • Attributes: TAttributesCriteria
    Contains file attributes criteria.

    Each subproperty of this property reperesents a single file attribute, and has a type of TFileAttributeStatus that is an enumeration type with the following values:

    fsIgnore		This file attribute has no effect on the search result.
    fsSet		The file must have this file attribute to satisfy the search conditions.
    fsUnset		The file must not have this file attribute to satisfy the search conditions.
    fsAnySet		The file must have at least one of the file attributes that are indicated by fsAnySet flag.
    fsAnyUnset		The file must not have at least one of the file attributes that are indicated by fsAnyUnset flag.

    • Readonly: TFileAttributeStatus
      TFileAttributeStatus = (fsIgnore, fsSet, fsUnset, fsAnySet, fsAnyUnset)
      Determines the desired status of the readonly attribute for the target files.
      This attribute means the file or directory is read-only.
    • Hidden: TFileAttributeStatus
      TFileAttributeStatus = (fsIgnore, fsSet, fsUnset, fsAnySet, fsAnyUnset)
      Determines the desired status of the hidden attribute for the target files.
      This attribute means the file or directory is hidden.
    • System: TFileAttributeStatus
      TFileAttributeStatus = (fsIgnore, fsSet, fsUnset, fsAnySet, fsAnyUnset)
      Determines the desired status of the system attribute for the target files.
      This attribute means the file or directory is part of operating system, or is used exclusively by the operating system.
    • Directory: TFileAttributeStatus
      TFileAttributeStatus = (fsIgnore, fsSet, fsUnset, fsAnySet, fsAnyUnset)
      Determines the desired status of the directory attribute for the target files.
      This attribute means the target identifies a directory.
    • Archive: TFileAttributeStatus
      TFileAttributeStatus = (fsIgnore, fsSet, fsUnset, fsAnySet, fsAnyUnset)
      Determines the desired status of the archive attribute for the target files.
      This attribute means the file or directory is an archive file.
    • Device: TFileAttributeStatus
      TFileAttributeStatus = (fsIgnore, fsSet, fsUnset, fsAnySet, fsAnyUnset)
      Determines the desired status of the device attribute for the target files.
      This attribute is a reserved attribute.
    • Normal: TFileAttributeStatus
      TFileAttributeStatus = (fsIgnore, fsSet, fsUnset, fsAnySet, fsAnyUnset)
      Determines the desired status of the normal attribute for the target files.
      This attribute means the file or directory does not have another attributes set and is valid only if used alone.
    • Temporary: TFileAttributeStatus
      TFileAttributeStatus = (fsIgnore, fsSet, fsUnset, fsAnySet, fsAnyUnset)
      Determines the desired status of the temporary attribute for the target files.
      This attribute means the file is being used for temporary storage.
    • SparseFile: TFileAttributeStatus
      TFileAttributeStatus = (fsIgnore, fsSet, fsUnset, fsAnySet, fsAnyUnset)
      Determines the desired status of the sparse file attribute for the target files.
      This attribute means the file is a sparse file.
    • ReparsePoint: TFileAttributeStatus
      TFileAttributeStatus = (fsIgnore, fsSet, fsUnset, fsAnySet, fsAnyUnset)
      Determines the desired status of the reparse point attribute for the target files.
      This attribute means the file or directory has an associated reparse point.
    • Compressed: TFileAttributeStatus
      TFileAttributeStatus = (fsIgnore, fsSet, fsUnset, fsAnySet, fsAnyUnset)
      Determines the desired status of the compressed attribute for the target files.
      This attribute means the file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
    • Offline: TFileAttributeStatus
      TFileAttributeStatus = (fsIgnore, fsSet, fsUnset, fsAnySet, fsAnyUnset)
      Determines the desired status of the offline attribute for the target files.
      This attribute means the data of the is not immediately available. This attribute indicates that the file data is physically moved to offline storage. This attribute is used by Remote Storage, the hierarchical storage management software.
    • NotContentIndex: TFileAttributeStatus
      TFileAttributeStatus = (fsIgnore, fsSet, fsUnset, fsAnySet, fsAnyUnset)
      Determines the desired status of the not content indexed attribute for the target files.
      This attribute means the file is not to be indexed by the content indexing service.
    • Encrypted: TFileAttributeStatus
      TFileAttributeStatus = (fsIgnore, fsSet, fsUnset, fsAnySet, fsAnyUnset)
      Determines the desired status of the encrypted attribute for the target files.
      This attribute means the file or directory is encrypted. For a file, this means that all data in the file is encrypted. For a directory, this means that encryption is the default for newly created files and subdirectories.
    • Virtual: TFileAttributeStatus
      TFileAttributeStatus = (fsIgnore, fsSet, fsUnset, fsAnySet, fsAnyUnset)
      Determines the desired status of the virtual attribute for the target files.
      This attribute means the file is a virtual file.
  • Size: TSizeCriteria
    Contains file size criteria.
    • Min: TFileSize
      TFileSize = Int64 { it is DWORD in Delphi 3 }
      Determines the lower range of the file size. Set this property to zero if you do not need this condition.
    • Max: TFileSize
      TFileSize = Int64 { it is DWORD in Delphi 3 }
      Determines the upper range of the file size. Set this property to zero if you do not need this condition.
  • TimeStamp: TDateTimeCriteria
    Contains file date and time criteria.
    • CreatedAfter: TDateTime
      Determines the lower range of the file creation date and time. To ignore lower date limit, set date part to zero and to ignore lower time limit, set time part to zero.
    • CreatedBefore: TDateTime
      Determines the upper range of the file creation date and time. To ignore upper date limit, set date part to zero and to ignore upper time limit, set time part to zero.
    • ModifiedAfter: TDateTime
      Determines the lower range of the file last modified date and time. To ignore lower date limit, set date part to zero and to ignore lower time limit, set time part to zero.
    • ModifiedBefore: TDateTime
      Determines the upper range of the file last modified date and time. To ignore upper date limit, set date part to zero and to ignore upper time limit, set time part to zero.
    • AccessedAfter: TDateTime
      Determines the lower range of the file last accessed date and time. To ignore lower date limit, set date part to zero and to ignore lower time limit, set time part to zero.
    • AccessedBefore: TDateTime
      Determines the upper range of the file last accessed date and time. To ignore upper date limit, set date part to zero and to ignore upper time limit, set time part to zero.
  • Content: TContentCriteria
    Contains criteria about the files content.
    • Phrase: String
      Specifies the text that should be in the content of the files. Set this property to empty if you do not need this condition.
    • Options: TContentSearchOptions
      TContentSearchOptions = set of (csoCaseSensitive, csoWholeWord);
      Specifies the options for content search.

      csoCaseSensitive		If this option is set, the component performs a case sensitive search to locate the phrase inside the files.
      csoWholeWord		If this option is set, the component searches for whole words only.
      csoNegate		If this option is set, the component accepts the files that do not contain the phrase.

• Aborted: Boolean ^(Read-only)
  When it is true, indicates that the current (or last) search has been cancelled.
• Busy: Boolean ^(Read-only)
  When it is true, means a search is running and it is not finished yet.
• CurrentLevel: Word ^(Read-only)
  Determines on which directory level the search is running now.
• Threaded: Boolean
  If it sets to true, the component uses a separated thread for its process.
• ThreadPriority: TThreadPriority
  Determines priority of the thread when component is in the threaded mode.

METHODS

• procedure Execute
  Starts the search process.
• procedure Abort
  Aborts the search and sets the Aborted property to true. Calling Abort method does not mean that it halts the search process immediately. You have to use OnSearchFinish event to know exactly when the process is stopped.

EVENTS

• OnFileMatch: TFileMatchEvent
  TFileMatchEvent = procedure (Sender: TObject; const FileInfo: TFileDetails) of object
  NOTE: The code of the event handler must be thread safe
  This event will be triggered when a file is matched with the search criteria. FileInfo parameter contains the information regarding the matched file.

  TFileDetails = record
    Location: String;
    Name: TFileName;
    Attributes: DWORD;
    Size: TFileSize;
    CreatedTime: TDateTime;
    ModifiedTime: TDateTime;
    AccessedTime: TDateTime;
  end;
  

• OnFolderChange: TFolderChangeEvent
  TFolderChangeEvent = procedure (Sender: TObject; const Folder: String; var IgnoreFolder: TFolderIgnore) of object
  NOTE: The code of the event handler must be thread safe
  This event helps you to monitor the current search location and will be triggered when component begins to search in a new folder. To bypass a folder of its subfoders, set IgnoreFolder parameter as follow:

  fiNone (Default)		Search continues into Folder and its subfolders
  fiJustThis		Folder will be ignored but search continies into its subfolders
  fiJustSubfolders		Folder will be searched but its subfolders will be ignored
  fiThisAndSubfolders		Folder and its subfolders will not be searched

• OnSearchBegin: TNotifyEvent
  Actually, when Execute method is called, the component prepares the search criteria and after that begins the search. This event is just triggered when the search process is about to begin.
• OnSearchFinish: TNotifyEvent
  This event is triggered when search is finished. Search can be finished because of either completion or calling Abort method.

FOLDER META PARAMETERS

Sometimes you may need to exclude subfolders of some folders while you keep searching in subfolders of the other specified folders, or vice versa. In this case, Criteria.Files.Subfolders property does not help anymore. The same is true when you need to set different MinLevel/MaxLevel values for folders you specified.

To solve this problem, this components accepts some special characters in front of each folder or path that you enter in Criteria.Files.Location and Criteria.Files.Paths properties.

The format is quite simple. If you insert a left angle (<) character in front of a folder or path, its subfolders will be excluded from the search. in the other hand, by putting a right angle (>) character in front of a folder or path, its subfolders will be searched.

When you include subfolders of a folder or path, you can specify which directory level is your interest. For this purpose, before the right angle character insert minimum and maximum levels separated by a dash (-) character. If you skip any value, its appropriate property value will be used.

Here are some examples:

<C:\Windows		Searches only 'C:\Windows' directroy without considering its subfolders
>C:\Program Files		Searches 'C:\Program Files' directroy as well as its subfolders
1-2>C:\Program Files		Searches 'C:\Program Files' directroy and its immediate subfolders
2-2>C:\Windows		Searches only immediate subfolders of 'C:\Windows' directroy without considering itself

HISTORY

• 4.12 (August 10, 2010)
  - Added new option csoNegate to property Criteria.Content.Options. When this option is on, the component accepts the files NOT containing the search phrase.
• 4.11 (April 30, 2010)
  - Fixed the bug in FileContains function.
• 4.10 (February 6, 2010)
  - The OnSearchAbort method removed. Having this useless event needed lot of attention just to prevent deadlock.
  - The compatibility issue of the component on Delphi 5 and earlier resolved (Thanks to Lars).
  - The component is friend with Windows 9x again. :)
• 4.02 (January 22, 2009)
  - Another bug in exclusion filter is fixed.
• 4.01 (December 11, 2008)
  - Bug in exclusion filter fixed.
• 4.00 (November 14, 2008)
  This version of TFindFile is not compatible with the older versions, sorry.
  - Merged Criteria.Attribute and Criteria.AttributeEx properties in Criteria.Attributes property.
  - Renamed Criteria.Files.Included property to Criteria.Files.Paths.
  - Renamed Criteria.Files.Excluded property to Criteria.Files.Filters.
  - Merged Criteria.Content.IgnoreCase and Criteria.Content.WholeWord properties in Criteria.Content.Options property.
  - Changed definition of OnFileMatch event.
  - The search criteria for attributes now supports all documented NT file attributes.
  - The component can search inside files with Unicode (big and little endian) and UTF-8 encodings.
  - Each folder or path can have its on min/max subfolder level condition.
  - Exclusion and inclusion filters can use wildcards in entire path (before wildcards were allowed only on filename and drive parts, and only for exclusion).
  - Can use exclusion and inclusion filters freely on any custom order.
  - In addition to file modification time, OnFileMatch event reports file creation and last access times, and in TDateTime format.
  - Support for Delphi 2009 added.
• 3.53 (January 24, 2007)
  - To support Windows NT file attributes, the new AttributeEx criteria is introduced (Thanks to Florian Schick).
  - The Size criteria can now manage huge file sizes (Thanks to Florian Schick).
• 3.52 (January 18, 2007)
  - A memory leak bug is fixed.
• 3.51 (February 25, 2006)
  - A potential deadlock while aborting the search is fixed.
• 3.50 (July 26, 2005)
  - The ANSI string matching problem fixed.
• 3.40 (May 20, 2004)
  - The new property WholeWord added to the content criteria.
  - The file content search algorithm speeded up.
  - Now, in threaded mode, the code for both OnFileMatch and OnFolderChange event handlers run inside the search thread.
  - Some minor tweaks and bug fixes.
• 3.32 (May 7, 2004)
  - Bug in the file content search algorithm fixed.
  - Some minor tweaks.
• 3.31 (April 23, 2004)
  - Bug in comparing file's attributes fixed (Thanks to Sohnel-Software - SUPPORT).
• 3.30 (April 10, 2004)
  - UNC path support added (Thanks to Roman Olexa).
  - Bug in comparing file's attributes fixed (Thanks to Sohnel-Software - SUPPORT).
• 3.22 (March 21, 2003)
  - Bug related to Min/Max folder level criteria fixed (Thanks to Maurizio Mutti).
• 3.21 (January 13, 2003)
  - Bug at finding index of a folder in the list of target folders fixed (Thanks to Fritz).
• 3.20 (November 24, 2002)
  - New read-only property CurrentLevel added.
  - Parameter definition of OnFolderChange event changed.
• 3.10 (November 17, 2002)
  - New properties MinLevel and MaxLevel added to file criteria (Thanks to Nitin Chandra).
• 3.02 (August 25, 2002)
  - Some minor changes in interface of classes.
• 3.01 (August 1, 2002)
  - The code of text lookup function changed.
  - The bug in file attribute comparison fixed.
• 3.00 (May 4, 2002)
  - The new version does not support 16bit Delphi.
  - This version is not compatible with the older versions. The name and structure of properties and events has changed.
  - The search process is faster, particularly when criteria contains multiple file masks or component is searching for a text inside files.
  - Now, included file list accepts wildcards.
• 2.30 (March 7, 2002)
  - The bug on look up for folders that their names begin with a dot fixed (Thanks to Frederik Decoster).
  - Now, the FileName property can accept multiple files.
• 2.22 (December 26, 2001)
  - A bug on 16bit version fixed.
• 2.21 (April 16, 2000)
  - A minor bug fixed.
• 2.20 (April 15, 2000)
  - All reported bugs fixed.
• 2.11 (March 20, 2000)
  - In the previous version of the component, TFindFile ignores the files with normal attribute. In the current version the bug is fixed.
• 2.10 (March 18, 2000)
  - Two new properties IncludeFiles and ExcludeFiles added to the component.
• 2.00 (February 25, 2000)
  - ffNormal was a meaningless attribute and removed. When no any attribute is selected, it means Normal.
  - Files can be found by specifying the range of size, creation date and time, last modified date and time, last accessed date and time, and containing text.
  - Component improved to accept all or any of the selected attributes for the file.
  - Now, search location can contain multiple folders.
• 1.10 (February 1, 2000)
  - Now the search process can be done in a separated thread (32bit Only).
  - Threaded, ThreadPriority, and Busy properties and OnComplete event added.
• 1.00 (January 14, 2000)
  - Initial release.

ACKNOWLEDGEMENT

Special thanks to:

• Frederik Decoster <essevee@yahoo.com> for fixing folder look up bug.
• Nitin Chandra <nitin@spectranet.com> for the idea of dir level criterion.
• Roman Olexa <systech@systech.sk> for adding UNC path support.
• Sohnel-Software - SUPPORT <support@soehnel-software.de> for fixing a bug.
• Florian Schick for fixing the big file size issue and adding NT file attributes.
• Lars <mailto:lars.w@onlinehome.de> for his great support on resolving compatibility issues on old versions of Delphi/BCB.

LICENSE

TFindFile component is freeware. You may copy component's files AS LONG AS YOU COPY ALL OF THEM. If you want to change the source code in order to improve the component's features, performance, etc. please send me the new source code so that I can have a look at it. The changed source code should contain descriptions what you have changed, and of course your name. The only thing you MAY NOT CHANGE is the ORIGINAL COPYRIGHT INFORMATION.

DISCLAIMER

TFindFile is provided "AS IS" without any warranty of any kind, either express or implied. The entire risk as to the quality and performance of the software is with you. The author is NOT liable for any DAMAGES resulting from the use and misuse of the component, especially he is NOT liable for DAMAGES that were caused BY ANY VERSION WHICH HAS NOT BEEN PROGRAMMED BY THE AUTHOR HIMSELF.