7.3. Формирование страниц с результатами поиска

sub UserInit

Используется только для языка Perl. Вызывается только один раз при старте поискового сервера для инициализации перловых переменных.

int UserHttpHeaders(ISearchContext* ysc)
sub UserHttpHeaders

Вызывается в самом начале формирования страницы с результатами поиска для установки дополнительных HTTP-заголовков.

void UserRequest(ISearchContext* ysc)
sub UserRequest

Вызывается до выполнения поискового запроса. Предназначена для преобразования полей поисковой формы в строку запроса на языке запросов Яндекса. Использование этой функции полезно, если пользователи системы не знакомы с языком запросов и используют переключатели формы для уточнения области поиска. В этой функции также можно установить поля запроса, влияющие на сортировку и группировку с помощью вызова FormFieldInsert. На C++ текст запроса следует установить с помощью функции void IReqResults::SetUserRequest(const char *req), на Perl запрос является возвращаемым значением.

int UserReport(ISearchContext* ysc)
sub UserReport

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

void HitStartBody(ISearchContext* ysc)
Hit::StartBody()

Верхняя вывеска-табличка в подсвеченном документе.

void HitEndBody(ISearchContext* ysc, int DocChanged, int FoundInBody, int FoundInCData)
Hit::EndBody(DocChanged, FoundInBody, FoundInCData)

Нижняя вывеска-табличка в подсвеченном документе.

DocChanged - равен 0, если документ не был изменен с момента последнего индексирования, в противном случае равен 1.

FoundInBody - найдено слов в теле документа (можно подсветить)

FoundInCData - найдено слов в области, не разрешающей подсветку (заголовок документа, меню, многострочные области ввода)

void HitFirst(ISearchContext* ysc)
Hit::First()

Стрелочка-ссылка на первое найденное слово.

void HitLast(ISearchContext* ysc)
Hit::Last()

Стрелочка-ссылка на последнее найденное слово.

void HitLeft(ISearchContext* ysc, int word_num, int word_prev_num)
Hit::Left(word_num, word_prev_num)

Стрелочка-ссылка на предыдущее найденное слово.

word_num - номер найденного слова

word_prev_num - номер предыдущего найденного слова

void HitRight(ISearchContext* ysc, int word_num)
Hit::Right(word_num)

Стрелочка-ссылка на следующее найденное слово.

word_num - номер найденного слова

Свойства поисковой сессии, независимые от данного поиска

int IIndexProperty::AttrCount()
Yx::AttrCount()

Возвращает число атрибутов в базе группировочных атрибутов.

const char *IIndexProperty::Attr(int attrnum)
Yx::Attr(attrnum)

Возвращает имя каждого группировочного атрибута.

attrnum - номер атрибута по-порядку, от нуля до значения, возвращаемого AttrCount().

const char *IIndexProperty::CategName(const char *attr, long cat)
Yx::CategName(attr, cat)

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

attr - имя группировочного атрибута

cat - числовое значение атрибута

Функцию можно использовать, если в индексной директории есть файл attr.c2n, где attr - значение первого аргумента функции (подробности см. в разделеБаза группировочных атрибутов).

long IIndexProperty::CategParent(const char *attr, long cat)
Yx::CategParent(attr, cat)

Возвращает родительское значение данного значения иерархического группировочного атрибута.

attr - имя группировочного атрибута

cat - числовое значение атрибута

Функцию можно использовать, если в индексной директории есть файл attr.c2p, где attr - значение первого аргумента функции (подробности см. в разделеБаза группировочных атрибутов).

time_t IIndexProperty::IndexModTime()
Yx::IndexModTime()

Возвращает время создания индекса в секундах от 00:00:00 1 января 1970 до момента последней модификации файла indexkey.

const char *IIndexProperty::ImagesUrl()
Yx::ImagesUrl()

Возвращает веб-адрес встроенной директории с картинками. Возвращаемое значение можно использовать, если в дизайне страниц результатов и подсветки используются изображения, выдаваемые Яndex.Server. Фактически функция возвращает строку вида http://host:port/images/, где host - значение директивы Host, а port - значение директивы Port секции Server конфигурационного файла Яndex.Server.

const char *IReqEnv::SearchUrl()
Yx::SearchUrl()

Возвращает префикс веб-страницы, принимающей поисковые запросы. Возвращаемое значение нужно использовать в качестве значения атрибута action html-тага form. Фактически функция возвращает строку вида http://host:port/id, где host и port - значения директив Host и Port секции Server конфигурационного файла Яndex.Server, а id - идентификатор коллекции документов, то есть значение одноименного атрибута секции Collection конфигурационного файла Яndex.Server.

Данные о поисковом запросе

const char *IReqEnv::HeaderIn(const char* key)
Yx::HeaderIn(key)

Возвращает значение HTTP-заголовка key, переданного клиентом в запросе к поисковому веб-серверу. Если указанного заголовка нет, возвращает 0 (C++) или неопределенное (undef) значение (Perl).

key - название HTTP-заголовка в запросе

const char *IReqEnv::Environment(const char* key)
Yx::GetEnv(key)

Возвращает значение одной из переменных окружения, указанных ниже. Если указанной переменной нет, возвращает 0 (C++) или неопределенное (undef) значение (Perl). В переменной key может передаваться одна из следующих строк

"QUERY_STRING" - часть URL поисковой страницы после знака вопроса, содержащая значения полей поисковой формы.

"SERVER_NAME" - доменное имя поискового сервера.

"SERVER_PORT" - порт, на котором работает поисковый сервер.

"SCRIPT_NAME" - часть относительного URL поисковой страницы до знака вопроса, abs_path в терминах RFC 2616.

"REMOTE_ADDR" - если в поисковом запросе есть HTTP-заголовок "X-Real-IP", будет возвращено значение этого заголовка, в противном случае - IP-адрес клиента, задавшего поисковый запрос.

int IReqEnv::FormFieldTest(const char* key, const char* value)
Yx::FormFieldTest(key, value)

Возвращает 1, если есть поле формы key со значением value, в противном случае - 0.

key - имя поля формы

value - значение поля формы

int IReqEnv::FormFieldCount(const char* key)
Yx::FormFieldCount(key)

Возвращает число одноименных полей.

key - имя поля формы

const char *IReqEnv::FormField(const char* key, int num, bool encode = false)
Yx::FormField(key, num = 0)

Возвращает значение поля формы key. Если запрашиваемого поля нет, возвращает 0 (C++) или неопределенное (undef) значение (Perl).

key - имя поля формы

num - номер значения, начиная с 0

encode - флаг, указывающий, нужно ли перекодировать запрещенные в HTML символы

const char *IReqEnv::QueryString()
Yx::QueryString()

Возвращает все поля поисковой формы в формате адреса веб-страницы. Возвращаемое значение может отличаться от значения Environment("QUERY_STRING"), так как учитывает результаты вызовов FormFieldInsert и FormFieldRemove из UserRequest.

void IReqEnv::FormFieldInsert(const char* key, const char* value)
Yx::FormFieldInsert(key, value)

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

key - имя поля формы

value - значение поля формы, которое нужно вставить

void IReqEnv::FormFieldRemove(const char *key, int num)
Yx::FormFieldRemove(key, num)

Функция удаляет данное поле из списка переданных полей.

key - имя поля формы

num - номер значения, которое надо удалить, начиная с 0

Статистика, относящаяся к запросу в целом

const char *IReqResults::ReqId()
Yx::ReqId()

Возвращает идентификатор запроса, назначенный поисковым сервером.

const char *IReqResults::Request()
Yx::Request()

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

int IReqResults::Status()
Yx::Status()

Возвращает статус выполненного запроса. При успешном поиске - 0.

int IReqResults::ErrorCode()
Yx::ErrorCode()

При неудачном поиске возвращает код ошибки.

const char *IReqResults::ErrorText(const char* lang = "ru")
Yx::ErrorText(lang)

При неудачном поиске возвращает описание ошибки.

lang - строка-идентификатор языка

const char *IReqResults::WordStat()
Yx::WordStat()

Возвращает строку со статистикой найденных слов в формате слово:количество.

int ICluster::TotalDocCount(int prior)
Yx::TotalDocCount(prior = 0)

Возвращает число найденных документов с данным приоритетом релевантности.

prior - приоритет релевантности. Значение 2 соответствуют совпадению фразы, 1 - строгому соответствию запросу, 0 - нестрогому соответствию запросу. В числе, возвращаемом при меньшем значении параметра, суммируется количество документов с худшим приоритетом, так что при значении 0 функция возвращает полное число найденных документов.

const char *IReqResults::Charset()
Yx::Charset()

Возвращает кодировку, в которой печатается страница с результатами поиска. По умолчанию, страница печатается в кодировке запроса, которая может быть задана в директиве QueryCharset. Кодировка выходной страницы может быть переопределена с помощью параметра charset поисковой формы.

Свойства группировки

long ICluster::CurCateg(const char *attr, int gMode)
Yx::CurCateg(attr, gMode)

Возвращает текущую группу (числовое значение атрибута), заданную при определении группировки.

attr - имя группировочного атрибута

gMode - тип группировки, 1 - плоская или глубокая, если атрибут иерархический, 2 - широкая, имеет смысл только для иерархического атрибута

int ICluster::GroupsOnPageCount(const char *attr, int gMode)
Yx::GroupsOnPageCount(attr, gMode)

Возвращает максимальное число групп на странице, заданное при определении группировки.

int ICluster::DocsInGroupCount(const char *attr, int gMode)
Yx::DocsInGroupCount(attr, gMode)

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

const char *IReqEnv::SearchPageUrl(int npage, const char *attr)
Yx::SearchPageUrl(npage, attr)

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

npage - номер страницы по-порядку, начиная с нуля

attr - имя группировочного атрибута

int ICluster::Count(int prior, const char *attr, int gMode)
Yx::Count(prior, attr, gMode)

Возвращает число найденных групп в данной группировке, полученное в процессе выполнения запроса.

prior - приоритет релевантности, как описано для функции TotalDocCount.

Свойства группы в данной группировке

long ICluster::GroupCateg(int nGroup, const char *attr, int gMode)
Yx::GroupCateg(nGroup, attr, gMode)

Возвращает числовое значение группировочного атрибута, соответствующее данной группе.

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

attr - имя группировочного атрибута

gMode - тип группировки, 1 - плоская или глубокая, если атрибут иерархический, 2 - широкая, имеет смысл только для иерархического атрибута

int ICluster::GroupDocCount(int prior, int nGroup, const char *attr, int gMode)
Yx::GroupDocCount(prior, nGroup, attr, gMode)

Возвращает число документов, попавших в данную группу в процесе группировки. Так как запоминаются данные не более чем N первых документов, где N - число, возвращаемое функцией DocsInGroupCount(...), то для определения числа документов, которое можно показать для данной группы, надо взять минимум из этих двух чисел.

prior - приоритет релевантности, как описано для функции TotalDocCount. Полному числу документов в группе соответствует значение 0.

int ICluster::GroupRelevance(int nGroup, const char *attr, int gMode)
Yx::GroupRelevance(nGroup, attr, gMode)

Возвращает релевантность группы в виде положительного целого числа.

int ICluster::GroupPriority(int nGroup, const char *attr, int gMode)
Yx::GroupPriority(nGroup, attr, gMode)

Возвращает приоритет релевантности группы. Значения 5, 6, 7 соответствуют совпадению фразы, 2, 3, 4 - строгому соответствию запросу, 0, 1 - нестрогому соответствию запросу.

Свойства документа в данной группе

long ICluster::DocId(int nGroup, int nDoc, const char *attr, int gMode)
Yx::DocId(nGroup, nDoc, attr, gMode)

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

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

nDoc - номер документа в группе по-порядку, от нуля до значения GroupDocCount(...)-1 включительно.

attr - имя группировочного атрибута

gMode - тип группировки, 1 - плоская или глубокая, если атрибут иерархический, 2 - широкая, имеет смысл только для иерархического атрибута

int ICluster::DocPriority(int nGroup, int nDoc, const char *attr, int gMode)
Yx::DocPriority(nGroup, nDoc, attr, gMode)

Возвращает приоритет релевантности документа, как описано для функции GroupPriority.

long ICluster::DocRelevance(int nGroup, int nDoc, const char *attr, int gMode)
Yx::DocRelevance(nGroup, nDoc, attr, gMode)

Возвращает релевантность документа в виде положительного целого числа.

double ICluster::DocRelevanceNormalized(int nGroup, int nDoc, const char *attr, int gMode)
Yx::DocRelevanceNormalized(nGroup, nDoc, attr, gMode)

Возвращает релевантность документа, приведенную к диапазону от 0 до 1.

const char *IReqEnv::HighlightedDocUrl(int nGroup, int nDoc, const char *attr, int gMode)
Yx::HighlightedDocUrl(nGroup, nDoc, attr, gMode)

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

int ICluster::DocPropertyCount(int nGroup, int nDoc, const char *attr, int gMode, const char* property)
Yx::DocPropertyCount(nGroup, nDoc, attr, gMode, property)

Возвращает число различных значений свойства документа, указанного в аргументе property.

property - название свойства в виде строки.

В качестве свойства можно передавать следующие значения.

• Название группировочного атрибута, которое возвращается функцией Attr(attrnum). В этом случае функция вернет 0, если у данного документа указанный группировочный атрибут отсутствует, 1, если атрибут имеется, или значение, большее 1, если имеется несколько значений иерархического атрибута.

• Один из аргументов директивы DocProperty конфигурации индексатора. В этом случае функция вернет 0, если у данного документа указанный поисковый атрибут отсутствует, и 1, если атрибут имеется.

• Одно из следующих значений.

  "_Url" - URL документа.

  "_ModTime" - время в секундах, прошедшее с 00:00:00 1 января 1970 года до момента последнего изменения файла с документом.

  "_ModTimeStr" - то же, что и "_ModTime", но в виде строки формата 18 Aug 2000, 08:52.

  "_Size" - размер файла с документом в байтах.

  "_Charset" - кодировка документа.

  "_MimeType" - медиа-тип документа.

  "_Title" - заголовок документа.

  "_HeadLine" - краткое содержание документа или первые 200 символов текста.

  "_Passage" - отрывок текста документа, содержащий искомые слова.

  Функция вернет 1, кроме свойства "_Passage", значений которого может быть несколько, но не больше, чем указано в параметре поисковой формы t.

const char *ICluster::DocProperty(int nGroup, int nDoc, const char *attr, int gMode, const char* property, unsigned index)
Yx::DocProperty(nGroup, nDoc, attr, gMode, property, index)

Возвращает значение указанного свойства документа.

property - название свойства в виде строки, возможные значения перечислены в описании функции DocPropertyCount.

index - номер значения свойства от нуля до значения, возвращаемого функцией DocPropertyCount.

Для свойств "_Title", "_HeadLine" и "_Passage" функция возвращает строку, размеченную специальным символом BEL (символ с кодом 7) следующим образом.

• "BEL{" и "BEL}" окружают слова с приоритетом "совпадение фразы"

• "BEL[" и "BEL]" окружают слова с приоритетом "строгое соответствие";

• "BEL(" и "BEL)" окружают слова с приоритетом "нестрогое соответствие".

Размеченные таким образом строки могут быть преобразованы с помощью функции ConvertArchiveText.

const char* IReqEnv::ConvertArchiveText(const char* rawtext, unsigned maxLen, int mode, const char *Open1, const char *Open2, const char *Open3, const char *Close1, const char *Close2, const char *Close3)
Yx::ConvertArchiveText(rawtext, maxLen, mode, Open1, Open2, Open3, Close1, Close2, Close3)

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

rawtext - размеченный текст, выданный функцией DocProperty,который надо обработать.

maxLen - длина, до которой надо укоротить rawtext, если этот параметр равен 0, то текст не укорачивается.

mode - вид обработки. 0 - запрещенные в HTML cимволы заменяются на соответсвующие последовательности, а специальная разметка слов - на указанные теги. 1 - запрещенные в HTML cимволы заменяются на соответсвующие последовательности, а специальная разметка слов выбрасывается. 2 - запрещенные в HTML cимволы не заменяются, специальная разметка слов выбрасывается.

Open1, Close1 - Открывающий и закрывающий теги для слов, найденных с нестрогим соответствием.

Open2, Close2 - Открывающий и закрывающий теги для слов, найденных со строгим соответствием.

Open3, Close3 - Открывающий и закрывающий теги для слов, найденных с совпадением фразы.

Функции формирования HTTP-заголовков на Perl

Yx::HeaderOut(header, value)

Функция печатает HTTP-заголовок header со значением value.

header - HTTP-заголовок

value - значение HTTP-заголовка

Yx::ContentType(value)

value - значение заголовка

Функция печатает HTTP-заголовок Content-Type со значением value.

Yx::SetLastModified()

Функция печатает HTTP-заголовок Last-Modified со временем изменения индексных файлов в качестве значения заголовка.