FindFirst Method
Searches for the first vault item that matches the specified name and attributes.
Syntax
public long findFirst(String fileMask, int attributes, int flags);
Remarks
This method initiates a search operation based on the specified FileMask, Attributes, and Flags. If there are any matching vault items (files, directories, symbolic links, or alternate streams), then a search operation handle pointing to the first result is returned. If there are no matching vault items, then -1 is returned.
To obtain information about a search result, pass the returned search handle to the following methods:
- GetSearchResultAttributes
- GetSearchResultCreationTime
- GetSearchResultFullName
- GetSearchResultLastAccessTime
- GetSearchResultLinkDestination
- GetSearchResultMetadataSize
- GetSearchResultModificationTime
- GetSearchResultName
- GetSearchResultSize
To retrieve the next search result, pass the returned search handle to the FindNext method. When an application is finished with (or wants to abandon) a search operation, it must pass the associated search handle to the FindClose method in order to release the resources associated with it.
Since each search operation is identified by the search handle associated with it, applications may initiate additional search operations at any time, and may process each operation's search results in any manner it desires (sequentially, round-robin, etc.).
The FileMask parameter specifies both the directory path to search within and the filename mask to match against; e.g., \directory\to\search\*.txt. (Or, when searching a file's alternate streams, the file path and stream name mask; e.g., \path\to\file:*.) Only the mask may contain wildcards, the path must be specified in vault-local absolute format. Also note that files without an extension will match *, but not *.*.
The Attributes parameter specifies the attributes to match against; items will only match if they have one or more of the specified attributes. The value passed for this parameter should be constructed by OR'ing together zero or more of the values shown below. Passing 0 will allow any file in a directory (or, any alternate stream in a file) to match; it's equivalent to CBFSSTORAGE_FATTR_FILE | CBFSSTORAGE_FATTR_DATA_STREAM.
| CBFSSTORAGE_FATTR_FILE | 0x00000001 | The entry is a file. |
| CBFSSTORAGE_FATTR_DIRECTORY | 0x00000002 | The entry is a directory. |
| CBFSSTORAGE_FATTR_DATA_STREAM | 0x00000004 | The entry is an alternate data stream. |
| CBFSSTORAGE_FATTR_COMPRESSED | 0x00000008 | The file or stream is compressed. |
| CBFSSTORAGE_FATTR_ENCRYPTED | 0x00000010 | The file or stream is encrypted. |
| CBFSSTORAGE_FATTR_SYMLINK | 0x00000020 | The entry is a symbolic link. |
| CBFSSTORAGE_FATTR_READONLY | 0x00000040 | The file is read-only.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
| CBFSSTORAGE_FATTR_ARCHIVE | 0x00000080 | The file requires archiving.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
| CBFSSTORAGE_FATTR_HIDDEN | 0x00000100 | The file is hidden.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
| CBFSSTORAGE_FATTR_SYSTEM | 0x00000200 | The file is a system file.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
| CBFSSTORAGE_FATTR_TEMPORARY | 0x00000400 | The file is temporary.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
| CBFSSTORAGE_FATTR_DELETE_ON_CLOSE | 0x00000800 | The file should be deleted when the last handle to the file is closed.
This attribute is currently not supported by CBFS Storage. |
| CBFSSTORAGE_FATTR_RESERVED_0 | 0x00001000 | Reserved. |
| CBFSSTORAGE_FATTR_RESERVED_1 | 0x00002000 | Reserved. |
| CBFSSTORAGE_FATTR_RESERVED_2 | 0x00004000 | Reserved. |
| CBFSSTORAGE_FATTR_RESERVED_3 | 0x00008000 | Reserved. |
| CBFSSTORAGE_FATTR_NO_USER_CHANGE | 0x0000F03F | A mask which includes all attributes that cannot be changed.
Applications cannot use the SetFileAttributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, RESERVED_3. |
| CBFSSTORAGE_FATTR_USER_DEFINED | 0x7FF00000 | A mask for application-defined attributes.
Applications can use the SetFileAttributes method to set custom attributes, so long as their values are covered by this mask. |
| CBFSSTORAGE_FATTR_ANY_FILE | 0x7FFFFFFF | A mask which includes any and all attributes. |
The Flags parameter controls search behavior. Among other things, it can be used to request that only specific pieces of information be returned, which can greatly improve performance. The value passed for this parameter should be constructed by OR'ing together zero or more of the following values:
| CBFSSTORAGE_FF_NEED_NAME | 0x00000001 | Include entry names (without paths) when returning search results. |
| CBFSSTORAGE_FF_NEED_FULL_NAME | 0x00000002 | Include fully-qualified entry names when returning search results. |
| CBFSSTORAGE_FF_NEED_ATTRIBUTES | 0x00000004 | Include entry attributes when returning search results. |
| CBFSSTORAGE_FF_NEED_SIZE | 0x00000008 | Include entry sizes when returning search results. |
| CBFSSTORAGE_FF_NEED_METADATA_SIZE | 0x00000010 | Include entry metadata sizes when returning search results. |
| CBFSSTORAGE_FF_NEED_TIMES | 0x00000020 | Include entry times when returning search results. |
| CBFSSTORAGE_FF_NEED_LINK_DEST | 0x00000040 | Include symbolic link destinations when returning search results. |
| CBFSSTORAGE_FF_EMULATE_FAT | 0x00001000 | Inserts . and .. pseudo-entries into search results for all directories except the root one. |
| CBFSSTORAGE_FF_RECURSIVE | 0x00002000 | Search recursively in all subdirectories. |
| CBFSSTORAGE_FF_CASE_INSENSITIVE | 0x00004000 | Forces case-insensitive search, even if the vault is case-sensitive. |
Note: This method can only be called when Active is true, and cannot be called within events.