# FLUIdS
API поиска:
Основные типы и структуры

- struct flu_searcher_t
- struct flu_searcher_indexfile_t
- struct flu_searcher_result_t
- flu_searcher_printerror_t
- flu_searcher_memfail_t
- flu_searcher_printresult_t

| struct flu_searcher_t |

flu_searcher_t - главная структура API поиска. Каждый вызов API содержит в качестве первого параметра указатель на эту структуру. В документации любой экземпляр этой структуры будет именоваться поисковиком.

Структура flu_searcher_t описывается в заголовочном файле fluidss.h таким образом:

      struct flu_searcher_t
      {
        struct zcontext_t *context;
        unsigned zint_t errorCode;
        int allocCount;

      /* User info */
        flu_searcher_printerror_t printError;
        flu_searcher_memfail_t memoryFail;
        unsigned int searchArea;
        unsigned int searchFlags;
        int startNumber;
        int resultCount;
        void *info;
        int step;
        const char *query;

      /* Index list */
        struct flu_searcher_indexfile_t *indexes;
        int indexCount;

      /* Search data */
        struct expression_t *q;
        struct ztimeval_t *startTime;
        struct ztimeval_t *endTime;
        int foundCount;
        int printCount;
        float maxRank;

      /* Main pointer */
        struct flu_searcher_data_t *ptr;
      };

Не следует напрямую изменять значения полей этой структуры. Для этого используются вызовы fluSearcherInit, fluSearcherSetParams и fluSearcherSetQuery.

Каждое поле структуры означает следующее:

struct zcontext_t *context
  Контекст текущей задачи; устанавливается при вызове fluSearcherInit. Для многопоточных приложений контекст задачи должен задаваться отдельно для каждого потока, поэтому один и тот же поисковик не должен применяться в различных потоках.

unsigned zint_t errorCode
  Код последней случившейся ошибки. Сами коды (константы zer* и err*) задаются также в заголовочном файле fluidss.h.

int allocCount
  Число неотмененных вызовов malloc() и пр. по запросу на выделение памяти. По окончании работы с поисковиком (т.е. после вызова fluSearcherFree) должно иметь нулевое значение. Применяется для контроля за выделением памяти (должен быть установлен параметр компиляции ALLOCATION_TEST).

flu_searcher_printerror_t printError
  Подпрограмма вывода сообщений об ошибках; устанавливается при вызове fluSearcherInit.

flu_searcher_memfail_t memoryFail
  Подпрограмма обработки "нештатной" ситуации нехватки свободной оперативной памяти; устанавливается при вызове fluSearcherInit. Обработка подобного события может заключаться, например, в возбуждении исключительной ситуации.

unsigned int searchArea
  Область поиска; устанавливается при вызове fluSearcherSetParams.

unsigned int searchFlags
  Флаги поиска; устанавливаются при вызове fluSearcherSetParams.

int startNumber
  Начальный номер результата поиска, с которого следует начать накопление результатов поиска (если нумерацию начинать с нуля; иными словами, startNumber - число первых результатов поиска, которые следует отбросить).

int resultCount
  Максимальное число результатов поиска, которые желательно зарегистрировать; устанавливается при вызове fluSearcherSetParams. Реальное число зарегистрированных результатов поиска определяется printCount.

void *info
  Пользовательские данные поисковика; устанавливается при вызове fluSearcherInit. Это могут быть абсолютно любые данные, которые могут быть востребованы в подпрограммах printError, memoryFail или printResult.

int step
  Определяет, на каком этапе поиска находится поисковик. Может понадобиться при возникновении ошибочных ситуаций (функции printError и memoryFail).
  step может принимать пять значений:
  - fssStepInit - идет инициализация поисковика (вызовы fluSearcherInit и fluSearcherSetParams);
  - fssStepCompile - происходит компиляция пользовательского запроса (вызов fluSearcherSetQuery);
  - fssStepSearch - совершается поиск (вызов fluSearcherMakeSearch);
  - fssStepPrinting - идет печать результатов поиска (вызовы fluSearcherPrintResults и fluSearcherNextResult)
  - fssStepDone - поиск окончен (такое значение step получает при вызове fluSearcherFree).

const char *query
  Копия пользовательского запроса; устанавливается при вызове fluSearcherSetQuery.

struct flu_searcher_indexfile_t *indexes
  Список индексных файлов, участвующих в поиске; устанавливается при вызове fluSearcherMakeSearch.

int indexCount
  Число индексных файлов, участвующих в поиске; устанавливается при вызове fluSearcherMakeSearch.

struct expression_t *q
  Откомпилированный пользовательский запрос; устанавливается при вызове fluSearcherSetQuery.

struct ztimeval_t *startTime
  Указатель на момент времени, в который начался процесс поиска; устанавливается при вызове fluSearcherMakeSearch.

struct ztimeval_t *endTime
  Указатель на момент времени, в который закончился процесс поиска; устанавливается при вызове fluSearcherMakeSearch.
  Разница между endTime и startTime составляет время поиска.

int foundCount
  Общее число результатов поиска, удовлетворяющих пользовательскому запросу; устанавливается при вызове fluSearcherMakeSearch.

int printCount
  Число зарегистрированных результатов поиска (т.е. тех, чей порядковый номер больше startCount и меньше или равен startCount + resultCount); устанавливается при вызове fluSearcherMakeSearch.
  Может равняться нулю, если число результатов поиска меньше или равно startCount (или они вообще отсутствуют); максимальное значение - resultCount (если результатов поиска достаточно много).
  Именно это число результатов поиска будет передано вызывами fluSearcherPrintResults и fluSearcherNextResult.

float maxRank
  Максимальный ранг результата поиска (среди всех результатов поиска, отвечающих пользовательскому запросу); устанавливается при вызове fluSearcherMakeSearch. Необходим для нормирования результатов поиска.
  Может равняться нулю, если запросу не отвечает ни один документ в индекных файлах, участвующих в поиске. Результат поиска с максимальным рангом не обязан находится в списке регистрируемых результатов поиска.

struct flu_searcher_data_t *ptr
  Скрытые данные поисковика.

| struct flu_searcher_indexfile_t |

Структура flu_searcher_indexfile_t описывает индексный файл, участвующий в поиске:

      struct flu_searcher_indexfile_t
      {
      /* Index file */
        struct indexfile_t *pif;
        Boolean isOpen;
        Boolean wasOpen;
        Boolean wasError;

      /* Other */
        int number;
        void *info;
        int foundCount;
      };

Здесь:

struct indexfile_t *pif
  Структура для низкоуровневых функций, работающих с индексным файлом.

Boolean isOpen
  Определяет, открыт ли до сих пор этот индексный файл. Не следует производить каких-либо операций чтения с закрытым файлом :)

Boolean wasOpen
  Определяет, был ли вообще открыт данный индексный файл. Если был, то в indexFile сохранились данные заголовка индекса.

Boolean wasError
  Произошла ли какая-либо ошибка при работе с данным индексом (тогда о нем лучше всего позабыть).

int number
  Порядковый номер индекса в списке индексных файлов, участвующих в поиске.

void *info
  Пользовательские данные, индивидуальные для этого индекса. Если не заданы, то это поле устанавливается в NULL.

int foundCount
  Сколько результатов поиска принадлежит именно этому индексу (из общего числа результатов поиска, отвечающих пользовательскому запросу).

| struct flu_searcher_result_t |

Структура flu_searcher_result_t непосредственно описывает результат поиска. С экземплярами этой структуры работают вызовы fluSearcherPrintResults и fluSearcherNextResult. Определение структуры представлено ниже:

      struct flu_searcher_result_t
      {
      /* External data */
        Boolean wasError;
        int number;
        struct flu_searcher_indexfile_t *indexFile;

      /* Internal data */
        int rank;
        char *url;
        char *title;
        char *content;
        int urlLength;
        int titleLength;
        int contentLength;
        zoff_t size;
        ztime_t lastModified;
        Boolean allContent;
      };

Boolean wasError
  Определяет, возникла ли ошибка при чтении данных из индексного файла, относящихся к данному результату поиска. Если таковая произошла, то из всех полей структуры flu_searcher_result_t можно полагаться только на number, indexFile и rank.

int number
  Порядковый номер результата поиска (в общем списке результатов поиска). Отсчет ведется от нуля (т.е. самый первый результат поиска имеет номер "ноль").

struct flu_searcher_indexfile_t *indexFile
  Индексный файл, которому принадлежит данный результат поиска.

int rank
  Ранг результата поиска. Представляет собой число от 0 до 1000. Чем выше ранг, тем релевантнее результат поиска запросу.

char *url
  Интернет-адрес документа, отвечающего результату поиска.

char *title
  Заглавие документа, отвечающего результату поиска. Представляет собой пустую строку, если у документа отсутствует заглавие.

char *content
  Фрагмент текта (первые MAX_CONTENT_LENGTH значащих символов) документа, отвечающего результату поиска. Представляет собой пустую строку, если документ пустой или нетекстовый.

int urlLength
  Длина url в байтах.

int titleLength
  Длина title в байтах.

int contentLength
  Длина content в байтах.

zoff_t size
  Размер документа, отвечающего результату поиска.

ztime_t lastModified
  Дата последней модификации документа, отвечающего результату поиска. ztime_t представляет собой битовый массив, с которым работают макросы zTime* (где * заменяет Year, Month и т.д.) Сейчас дата последней модификации хранится в индексных файлах как местное время; предполагается, что в дальнейшем эта дата будет пониматься как время по Гринвичу.

Boolean allContent
  Определяет, что все содержимое проиндексированного документа, отвечающего данному результату поиска, помещается в content.

| flu_searcher_printerror_t |

Тип flu_searcher_printerror_t определяет пользовательскую функцию, которая будет вызываться при возникновении какой-либо ошибки в вызывах API (кроме ситуации нехватки памяти) - ошибки чтения/записи файлов, некоректности индекных файлов, ошибок в запросе и т.д. Сама функция обработки ошибок установливется при инициальзации поисковика (вызов fluSearcherInit).

Тип определен как

      typedef void (*flu_searcher_printerror_t)
      (
          struct flu_searcher_t *fs,
          unsigned zint_t errorCode,
          const char *name
      );

Первый параметр функции - непосредственно поисковик, поэтому при написании конкретной функции обработки ошибочных ситуаций возможно использование собственных данных (поле info поисковика).

Второй параметр функции - собственно код ошибки, который представляет собой смесь битов и численого значения кода ошибки. name задает дополнительный строковый параметр к коду ошибки. Это может быть, например, имя файла, при работе с которым произошла ошибка.

Сами по себе errorCode и name мало пригодны для написания функции обработки ошибок. Однако с помощью вызова fluSearcherErrorString можно получить строку, описывающую возникшую ошибку, например:

      void myPrintError( struct flu_searcher_t *fs, unsigned zint_t errorCode, const char *name)
      {
        const char *errorString = fluSearcherErrorString( fs, errorCode, name);
        fprintf( stderr, "ERROR: %s\n", errorString);
      }

Внимание! Вызов fluSearcherErrorString можно осуществлять только изнутри printError, поскольку он помимо name использует дополнительные параметры, запасенные в fs->context, и которые будут являться действительными только на момент выполнения функции printError.

| flu_searcher_memfail_t |

flu_searcher_memfail_t задает прототип пользовательской фукнкции, вызываемой при возникновении ситуации нехватки свободной оперативной памяти:

      typedef void (*flu_searcher_memfail_t)
      (
          struct flu_searcher_t *fs,
          const char *name
      );

Первый параметр, fs, как обычно, задает поисковик, второй (name) - имя библиотечной функции, при вызове которой возникла ситуация нехватки памяти (обычно это malloc). Реакцией на нехватку памяти может являться, например, возбуждение исключительной ситуации или же вывод простого сообщения на экран.

Необходимо отметить, что сам поисковик достаточно корректно обрабатывает подобную ситуацию. В начале каждого вызыва API поиска сохраняется состояние программы через библиотечную функцию setjmp. В дальнейшем, при возникновении ситуации нехватки памяти, библиотечная функция longjmp восстанавливает первоначальное состояние программы, сигнализируя о возникновении ошибки, и вызов API заканчивается неудачно (возвращается False с установленным errorCode в zerNoMemory).

| flu_searcher_printresult_t |

Тип flu_searcher_printresult_t определяет пользовательскую функцию по выводу данных зарегистрированных результатов поиска (на экран, в память и пр.):

      typedef Boolean (*flu_searcher_printresult_t)
      (
          struct flu_searcher_t *fs,
          struct flu_searcher_result_t *pr
      );

На предыдущую страницу | valera@sbnet.ru