FindFirstByQuery Method

Searches for the first file or directory whose file tags match the specified query.

Syntax

ANSI (Cross Platform)
int64 FindFirstByQuery(const char* lpszDirectory, const char* lpszQuery, int iFlags);

Unicode (Windows)
LONG64 FindFirstByQuery(LPCWSTR lpszDirectory, LPCWSTR lpszQuery, INT iFlags);
- (long long)findFirstByQuery:(NSString*)directory :(NSString*)query :(int)flags;
#define MID_CBVAULT_FINDFIRSTBYQUERY 20

CBFSSTORAGE_EXTERNAL int CBFSSTORAGE_CALL CBFSStorage_CBVault_Do(void *lpObj, int methid, int cparam, void *param[], int cbparam[], int64 *lpllVal);

Remarks

This method initiates a search operation within the specified Directory for files and subdirectories whose typed file tags match the specified Query. If there are any matching files or directories, then a search operation handle pointing to the first result is returned. If there are no matching files or directories, then -1 is returned.

To obtain information about a search result, pass the returned search handle to the following methods:

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 value passed for Directory must be a vault-local absolute path.

The value passed for Query must be a search query constructed using the CBFS Storage Query Language; please refer to that topic for more information.

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_NAME0x00000001Include entry names (without paths) when returning search results.

CBFSSTORAGE_FF_NEED_FULL_NAME0x00000002Include fully-qualified entry names when returning search results.

CBFSSTORAGE_FF_NEED_ATTRIBUTES0x00000004Include entry attributes when returning search results.

CBFSSTORAGE_FF_NEED_SIZE0x00000008Include entry sizes when returning search results.

CBFSSTORAGE_FF_NEED_METADATA_SIZE0x00000010Include entry metadata sizes when returning search results.

CBFSSTORAGE_FF_NEED_TIMES0x00000020Include entry times when returning search results.

CBFSSTORAGE_FF_NEED_LINK_DEST0x00000040Include symbolic link destinations when returning search results.

CBFSSTORAGE_FF_EMULATE_FAT0x00001000Inserts . and .. pseudo-entries into search results for all directories except the root one.

CBFSSTORAGE_FF_RECURSIVE0x00002000Search recursively in all subdirectories.

CBFSSTORAGE_FF_CASE_INSENSITIVE0x00004000Forces case-insensitive search, even if the vault is case-sensitive.

If Flags is 0, the class uses 0x0000006F (i.e., all CBFSSTORAGE_FF_NEED_* flags except CBFSSTORAGE_FF_NEED_METADATA).

Note: This method can only be called when Active is true, and cannot be called within events.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Copyright (c) 2021 Callback Technologies, Inc. - All rights reserved.
CBFS Storage 2020 C++ Edition - Version 20.0 [Build 8031]