# FLUIdS
API поиска:
Вызовы API

- fluSearcherInit
- fluSearcherFree
- fluSearcherSetParams
- fluSearcherSetQuery
- fluSearcherMakeSearch
- fluSearcherPrintResults
- fluSearcherInitResult
- fluSearcherNextResult
- fluSearcherErrorString

| fluSearcherInit |

Функция fluSearcherInit инициализирует поисковик:

      Boolean fluSearcherInit
      (
          struct flu_searcher_t *fs,
          flu_searcher_printerror_t printError,
          flu_searcher_memfail_t memoryFail,
          void *info
      );

Параметры:
  - fs - указатель на поисковик. Обратите внимание, что fluSearcherInit не выделяет память для самого поисковика, а только лишь для его внутренних данных. Выделение памяти под поисковик (и, возможно, ее высвобождение) возложено целиком на пользователя.
  - printError - пользовательская программа, ответственная за обработку ошибок. Значение этого параметра становится значением поля printError поисковика. Если при вызове fluSearcherInit этот параметр указан как NULL, то никакой особой обработки ошибок производиться не будет, вызов, при работе которого возникла ошибка, вернет False, а поле errorCode поисковика будет содержать код ошибки.
  - memoryFail - пользовательская программа, вызываемая в случае возникновения ситуации нехватки свободной оперативной памяти. Поле memoryFail поисковика устанавливается в значение этого параметра. memoryFail может принимать значение NULL, в таком случае при нехватке памяти вызовы API поиска просто будут возвращать False с установленным errorCode в zerNoMemory.
  - info - любые пользовательские данные. Ими можно воспользоваться в функциях printError, memoryFail или printResult.

Возвращаемые значения:
  - False - возвращается только в случае неудачного выделения памяти под внутренние данные поисковика.
  - True - инициализация поисковика прошла успешно.

Ниже представлен пример использования вызова fluSearcherInit с обработкой ошибок:

      ...
      #include "fluidss.h"
      ...

      static void myPrintError( struct flu_searcher_t *fs, unsigned zint_t errorCode, const char *name)
      {
        strncpy( (char *) fs->info, fluSearcherErrorString( fs, errorCode, name), 1024);
        ((char *) fs->info)[1023] = '\0';
      }

      static void myMemoryFail( struct flu_searcher_t *fs, const char *name)
      {
        fprintf( stderr, "No more free memory :(\n");
        exit( -1 );
      }

      int makeSearch( ..., char *errorBuf)
      {
        struct flu_searcher_t fluSearcher;
        ...
      /* Инициализируем поисковик */
        *errorBuf = '\0';
        if( !fluSearcherInit( &fluSearcher, myPrintError, myMemoryFail, errorBuf) ) return -1;
        ...
      /* Ищем */
        ...
        fluSearcherFree( &fluSearcher );
        ...
        return 0;
      }

      ...

В этом примере память под поисковик запасена в локальной автоматической переменной fluSearcher. В случае возникновении ошибки работы поисковика сообщение об этой ошибке сохраняется в буффере errorBuf, и выполнение программы не прерывается (из функции myPrintError не вызывается exit()). Если же возникла ситуация нехватки свободной оперативной памяти, то на STDERR будет выдано об этом сообщение, и работа программы будет аварийно прервана (вызовом exit() из функции myMemoryFail).

| fluSearcherFree |

Функция fluSearcherFree очищает и разрущает поисковик. При ее выполнении высвобождается вся ранее занятая под нужды поисковика память и закрываются индексные файлы, участвовавшие в поиске. Вызов fluSearcherFree нужно совершать не только по окончании работы поисковика, но и после возникновения любой критической ошибки. Прототип функции:

      void fluSearcherFree
      (
          struct flu_searcher_t *fs
      );

Параметры:
  - fs - указатель на поисковик.

Возвращаемые значения:
  - отсутствуют.

| fluSearcherSetParams |

Вызов fluSearcherSetParams устанавливает некоторые параметры, которые существенным образом влияют на накопление результатов поиска в поисковике:

      Boolean fluSearcherSetParams
      (
          struct flu_searcher_t *fs,
          unsigned int searchArea,
          unsigned int searchFlags,
          int startNumber,
          int resultCount
      );

Параметры:
  - fs - указатель на поисковик.
  - searchArea - область поиска. Представляет собой набор битов:
    - FS_AREA_CONTENT - осуществлять поиск в контенте проиндексированных документов;
    - FS_AREA_TITLE - поиск вести в заглавиях документов;
    - FS_AREA_FILENAME - производить поиск в файловых именах проиндексированных документов.
  - searchFlags - флаги поиска, которые формируются сочетанием следующих битов:
    - fsfCaseDepend - учитывать регистр букв в запросе;
    - fsfStopOnError - если произошла ошибка открытия одного из индексных файлов, участвующих в поиске, то прервать процесс поиска в функции fluSearcherMakeSearch и вернуть False;
    - fsfUnsorted - не производить сортировку результатов поиска.
  - startNumber - начальный порядковый номер результата поиска, начиная с которого регистрируются результаты поиска (если нумерацию вести с нуля). Поле startNumber поисковика принимает значение этого параметра.
  - resultCount - число результатов поиска, которые следует зарегистрировать. Значение этого параметра присваивается полю startNumber поисковика. Если resultCount имеет отрицательное значение, то зарегистрированы будут все результаты поиска, чьи порядковые номера больше или равны startNumber.

Возвращаемые значения:
  - False - произошла ошибка выделения памяти под окно результатов.
  - True - установка параметров прошла без проблем.

В приведенном ниже фрагменте кода, демонстрирующего применение fluSearcherSetParams, для поисковика устанавливается область поиска в контент и заглавие документов; декларируется, что поиск будет вестись с учетом регистра букв в запросе; первые (по значимости) десять результатов поиска будут пропущены; остальные же будут зарегистрированы (сколько бы их там не было; об этом можно судить по отрицательному значению параметра resultCount):

        ...
        if( !fluSearcherSetParams( fs, FS_AREA_CONTENT | FS_AREA_TITLE, fsfCaseDepend, 10, -1) )
        {
          fluSearcherFree( fs );
          exit( -1 );
        }
        ...

| fluSearcherSetQuery |

Вызов fluSearcherSetQuery предназначен для компиляции пользовательского запроса:

      Boolean fluSearcherSetQuery
      (
          struct flu_searcher_t *fs,
          const char *query
      );

Копия пользовательского запроса и результат его компиляции сохраняется в поисковике в полях query и q соответственно.

Параметры:
  - fs - указатель на поисковик.
  - query - пользовательский запрос.

Возвращаемые значения:
  - False - вызов закончился неудачей. Ее причиной может послужить нехватка свободной оперативной память или же неверно сформулированный запрос.
  - True - компиляция запроса и его сохранение в поисковике прошли успешно.

| fluSearcherMakeSearch |

Вызов fluSearcherMakeSearch непосредственно осуществляет поиск:

      Boolean fluSearcherMakeSearch
      (
          struct flu_searcher_t *fs,
          int count,
          const char **indexes,
          const char **aliases,
          void **infos
      );

Параметры:
  - fs - указатель на поисковик.
  - count - число индексных файлов (число элементов в списках indexes, aliases и infos).
  - indexes - список реальных файловых имен индексов, которые будут участвовать в поиске.
  - aliases - список псевдонимов индексных файлов. Если нет необходимости в псевдонимах, можно установить в NULL. Псевдоним вместо реального имени файла используется при возникновении ошибки работы с индексным файлом для генерации сообщения об этой ошибке, истинное же имя файла при этом остается скрытым.
  - infos - список указателей к дополнительной информации для каждого индексного файла, участвующего в поиске. Если дополнительная информация не нужна, то указатель может быть установлен в NULL. В дальнейшем эта информация становится доступной в поле indexFile->info результата поиска. По данной информации, например, можно судить о принадлежности результата поиска тому или иному индексному файлу.

Возвращаемые значения:
  - False - поиск прошел неуспешно. Причиной неудачи может послужить нехватка свободной оперативной памяти; отсутствие пользовательского запроса (не было вызова fluSearcherSetQuery или же он закончился неудачей); ошибка открытия одного из индексных файлов, если был задан флаг поиска fsfStopOnError; отсутствие индекса для поиска (ни один индексный файл, участвующий в поиске, не удалось безошибочно открыть).
  - True - поиск прошел успешно.

По окончании работы вызова некоторые поля поисковика приобретают действительные значения:
  - startTime и endTime - моменты времени начала и окончания процесса поиска. Для того, чтобы узнать время поиска, можно воспользоваться функциями zSubTimeValue и/или zGetTimeValue.
  - foundCount - общее число результатов поиска.
  - printCount - число зарегистрированных резильтатов поиска. Регистрируются только те результаты поиска, чьи порядковые номера попадают в заказанный диапазон значений:
    при неотрицательном resultCount - это

    `startNumber <= N < startNumber + resultCount`

    при отрицательном же значении resultCount - это

    `startNumber <= N`

    (если отсчет порядковых нумеров N вести с нуля).

  - maxRank - максимальный ранг результата поиска (из всех результатов поиска, удовлетворяющих запросу).

Пример:

      int makeSearch( struct flu_searcher_t *fs, ...)
      {
        const char *indexes[3];
        void *infos[3];
        int nums[3];
        int secs, msecs;
        ...
        indexes[0] = "index1.flu";
        nums[0] = 1;
        infos[0] = &nums[0];
        indexes[1] = "index2.flu";
        nums[1] = 2;
        infos[1] = &nums[1];
        indexes[2] = "index3.flu";
        nums[2] = 3;
        infos[2] = &nums[2];
        if( !fluSearcherMakeSearch( fs, 3, indexes, NULL, infos) )
        {
          fluSearcherFree( fs );
          return -1;
        }
        zSubTimeValue( fs->endTime, fs->startTime, &secs, &msecs);
        printf( "Время поиска - %d.%.3d секунд\n", secs, msecs);
        printf( "Найдено результатов поиска - %u\n", (unsigned int) fs->foundCount);
        ...
        return 0;
      }

В этом примере осуществляется поиск по трем индексным файлам, по окончании которого на экран печатается время поиска и общее число результатов поиска.

| fluSearcherPrintResults |

Вызов fluSearcherPrintResults, как и пара вызовов fluSearcherInitResult/fluSearcherNextResult, предназначен для выдачи запрошенных результатов поиска:

      Boolean fluSearcherPrintResults
      (
          struct flu_searcher_t *fs,
          flu_searcher_printresult_t printResult,
          unsigned int flags
      );

| fluSearcherInitResult |

Вызов fluSearcherInitResult подготавливает поисковик к выдаче запрошенных результатов поиска:

      Boolean fluSearcherInitResult
      (
          struct flu_searcher_t *fs,
          unsigned int flags
      );

Параметры:
  - fs - указатель на поисковик.
  - flags - флаги, влияющие на выдачу результатов:
    - fsfShortForm - не заботиться о заголовке и отрывке текста проиндексированного документа, соответствующего результату поиска.

Возвращаемые значения:
  - False - отсутствуют зарегистрированные результаты поиска;
  - True - можно приступать к выборке результатов поиска.

| fluSearcherNextResult |

Последовательные вызовы fluSearcherNextResult позволяют получить все зарегистрированные результаты поиска:

      struct flu_searcher_result_t *fluSearcherNextResult
      (
          struct flu_searcher_t *fs
      );

Параметры:
  - fs - указатель на поисковик.

Возвращаемые значения:
  - NULL - закончились зарегистрированные результаты поиска;
  - иначе - указатель на текущий результат поиска.

Перед тем, как осуществлять вызовы fluSearcherNextResult, поисковик нужно подготовить вызовом fluSearcherInitResult:

      fluSearcherInitResult( &searcher, 0);
      while( (result = fluSearcherNextResult( &searcher )) != NULL )
      {
        /* Выдаем данные результата поиска */
      }

| fluSearcherErrorString |

Вызов fluSearcherErrorString используется для получения строки сообщения о произошедшей ошибке:

      const char *fluSearcherErrorString
      (
          struct flu_searcher_t *fs,
          unsigned zint_t errorCode,
          const char *name
      );

Параметры:
  - fs - указатель на поисковик.
  - errorCode - код ошибки.
  - name - дополнительный строковый параметр, относящийся к ошибке.

Возвращаемые значения:
  - NULL - закончились зарегистрированные результаты поиска;
  - иначе - указатель на текущий результат поиска.

Вызов fluSearcherErrorString предназначен для применения исключительно внутри функции printError, поскольку fluSearcherErrorString при генерации сообщения использует дополнительные данные поисковика, запасенные в поле context. При этом параметры errorCode и name без изменения передаются от printError к 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 с заданными errorCode и name может закончиться крушением поисковика.

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