Search Engine API

Brief description

This is a full scale search engine, including the capabilities of on-the-fly archives unpacking (see the whole list of features), morphology support, indexer and so on. You can use it free-of-charge in any project provided the license conditions are met. There is another version of search engine component which may be preferable in your project - .NET component. The functionality of these components is almost equivalent except that Win32 DLL does not provide callback functions to indicate the progress of searching. It may be inappropriate for time-consuming search sessions (.NET component notifies the user code about the search process by delegates). We consider the question of supporting the callbacks in Win32 DLL, but if you don't want to wait then get source codes and build your own version of DLL (see instructions at this page)!


Library file faind.win32.dll as well as all necessary headers, libs and some samples can be downloaded here.

List of exported functions

Search engine initialization

Engine creation

HFAIND sol_CreateSearchEngine()

The function creates new new instance of the search engine and returns its handle.

Dictionary and other binary files are not loaded at the moment, because the search engine loads them when needed.

HFAIND sol_CreatePortableSearcher()

The function creates new instance of the portable search engine and returns its handle.

The portable searcher instance requires sol_AttachPortableIndex before any search query execution.


Load the configuration file

int sol_ReadIniW( HFAIND hEngine, const wchar_t* ini_filename )

int sol_ReadIniA( HFAIND hEngine, const char* ini_filename )

Engine tries to load config file. You can use the empty string as a filename for default initialization.

Return value:

0 - the configuration file is parsed successfully.

-1 - can not load the file.


Load the index database to portable searcher

int sol_AttachPortableIndex( HFAIND hEngine, const wchar_t* Folder )


hEngine - portable searcher instance descriptor, the result of sol_CreatePortableSearcher.

Folder - the location of the index database. The index database files can be create by console search tool or GUI desktop search system.

Return value:

0 - the index database is loaded.

-1 - error

Start writing debug messages to the logfile

int sol_OpenLogFileW( HFAIND hEngine, const wchar_t* log_filename )

int sol_OpenLogFileA( HFAIND hEngine, const char* log_filename )

Return value:

    0 - logging is enabled

    -1 - could not start logging

    -2 - logfile is already created


Stop writing debug message to the logfile, close the logfile

void sol_CloseLogFile( HFAIND hEngine )


Set up HTML format for search result pages

void sol_GenerateHtml( HFAIND hEngine )

The search results must be HTML formatted page, not XML by default. The text will be utf-8 encoded in both cases. The result extraction function can be used to obtain the data.

Set the XML format for subsequent search result pages

void sol_GenerateXml( HFAIND hEngine )

The search results will be formatted as XML pages. This is the default behaviour of the engine. It can be changed by sol_GenerateHtml or sol_NoResults.

The result extraction function can be used to obtain the data.

No result is required from subsequent queries

void sol_NoResults( HFAIND hEngine )

The engine stores the result of each query execution as HTML page. Use sol_NoResults to skip this data storage and to eliminate the unnecesary resource consumption.


Do not add standard prolog and epilog tags to the result page

void sol_StripHtml( HFAIND hEngine )

The generated result pages will not be decorated with standard <html>...<body> and </body></html> tags. It can be useful when placing the results into your own HTML page.



Setting call-back functions

void sol_SetCallback_StartFile( HFAIND hEngine, EngineCallbackProc_StartFile ptrFuction ) - set the callback function for start file processing event

void sol_SetCallback_StartFolder( HFAIND hEngine, EngineCallbackProc_StartFolder ptrFuction ) - set the callback function for start folder processing event

void sol_SetCallback_Success( HFAIND hEngine, EngineCallbackProc_Success ptrFuction ) - set the callback function for matching success event



Parameters block creation

HFAINDPARAMS sol_CreateParams( HFAIND hEngine )

Return value:

Handle to the list of parameters+values. This handle is passed to sol_ParseQueryWithParams and sol_ExecuteWithParam.

Each parameter is a combination of name and string value. Query string can refer the parameters by they names using question mark:

-dir ?1 -wordforms -sample ?2

'1' and '2' are the names of parameters which will be replaced by they values during query parsing.

The parameters block is filled by sol_AddParam calls.

Add new parameter and its value to the block

int sol_AddParamHFAINDPARAMS hParamsconst wchar_t* ParamNameconst wchar_t* ParamValue )

This function adds new parameters to the list. Redefinition of the parameters is not checked, in this case the result of parameter substitution is undefined.

Delete the parameters block

int sol_DeleteParamsHFAINDPARAMS hParams )

This function frees the memory allocated by sol_CreateParams.

Parse the query and prepare the execution context (see the query syntax).

HFAINDCMD sol_ParseQuery( HFAIND hEngine, const wchar_t* query )

HFAINDCMD sol_ParseQueryWithParams( HFAIND hEngine, const wchar_t*query, HFAINDPARAMS hParams )

Return value:

Handle of the query executor. This object holds all necessary buffers to perform the command in a separated thread.

sol_ExecuteQuery and sol_DeleteQuery perform the execution and free the context of the query.

For example, the sequence of the API calls:

HFAINDCMD hCmd = sol_ParseQuery( hEngine, L"-dir e:\\  -wordforms -sample \"spiral galaxy\"" );
  sol_ExecuteQuery( hEngine, hCmd );
  sol_DeleteQuery( hCmd );

searches the pattern 'spiral galaxy' in e:\


Execute the parsed query

int sol_ExecuteQuery( HFAIND hEngine, HFAINDCMD hCmd )

int sol_ExecuteWithParams( HFAIND hEngine, const wchar_t*query, HFAINDPARAMS hParams )

Return value:

0 - success;

-1 - error.

This procedure is called just after sol_ParseQuery.


Delete the parsed and executed query

void sol_DeleteQuery( HFAINDCMD hCmd )



Parse and execute the commands in query string

int sol_Execute( HFAIND hEngine, const wchar_t* query )

The syntax of the query is described here. This command is usually used to manipulate the index database, e.g.

sol_Execute( hEngine, L"-index create_domain test" );
   sol_Execute( hEngine, L"-index domain=test -mydocs" );

These commands create index for 'My Documents' folders.


0    success

-1   an error occurred (see sol_GetError function)


Search engine results

int sol_GetError( HFAIND hEngine, wchar_t* buffer, int buffer_len ) - return description of the last error.


int sol_GetResultLen( HFAINDCMD hCmd ) - return the length (number of characters) of the result page string.


void sol_GetResult( HFAINDCMD hCmd, char* buffer ) - copy the result page into the buffer. The text is encoded in utf-8. Tex format is XML by default, or HTML after sol_GenerateHtml called.


How does it work

Realized approach is quite simple. User code prepare the query string - it is formatted just like command line for FAIND tool (see details). Then it call sol_Search with this string and the search process is started. Search engine crawler scans defined domain and process files in it. Each match of the query pattern with text in a file causes the some information (file name and some other) is recorded in the internal buffer of search engine. This buffer can contain the information either as HTML page or as XML data block (and some other formats are available but less useful). Once the search process is completed, the sol_Search returns and user code calls sol_GetResult function. This API function copies the result (HTML or XML) into the user's buffer. After then HTML result can be shown as is, and XML data can be used as input data for other algorithms.


Additional information

Grammatical dictionary API

Search engine commands list

Search domain commands

Search query commands

Console full text search utility

Desktop search system

  © Козиев Илья 2019
last change 16-Aug-11