← kolan.mobi
     хоумпэйдж 		 Главная

← ksoftware.ya.ru
     блог
 

Содержание

Протокол 2

Это описание второй версии протокола для доступа к форуму www.delphimaster.ru. Первую версию протокола можно найти на самом форуме.

Этот протокол будет полезен всем разработчикам клиентов для форума. ДМКлиент тоже использует его.

Вежливые вопросы и предложения по клиентскому протоколу и форуму можно писать на http://dev2.delphimaster.ru/forum/other/ 

основано на версии от 18.02.02. дополнения -- Gero, Ketmar.
оформление в более-менее читабельный текст -- Ketmar.
-----------------------------------------------------------------------------
 
весь обмен идёт в кодировке windows-1251.

Ответы скрипта

скрипт возвращает данные в переменных. выглядит это так:
name=value<tab>name=value<tab>...
<tab> -- это символ #9.
 
в первой строке ответа всегда находится или
ERROR=текст сообщения об ошибке по-русски
или
Allcount=x
при ERROR всё очевидно -- кирдык. Allcount же показывает, сколько строк
данных вернул скрипт. что находится в строках данных -- зависит от запроса.
x -- это целое число.
 
имена переменных лучше проверять не обращая внимания на регистр.

Запросы

1. Запрос о доступных конференциях

http://www.delphimaster.ru/cgi-bin/client.pl?getforums=1
переменные в ответах:
 n=x
 title=str
 dsc=str
 
n: номер конференции (в дальнейшем используется везде, где нужно
  подставлять "n=")
title: краткое название конференции
dsc: развёрнутое описание конференции
 
пример ответа:
Allcount=2
n=0 title=Общие вопросы dsc=любые вопросы по программированию в Дельфи
n=1 title= Вопросы по базам данных  dsc=любые вопросы по использованию и программированию БД

2. Запрос о новых заголовках

http://www.delphimaster.ru/cgi-bin/client.pl?getnew=lastmod&n=0
Где lastmod=-1 в первом случае, в последующих -- брать максимальный lastmod из полученых ответов
(и приплюсовывать единицу? тогда потеряем ответы в то же время; иначе -- получим дубликаты;
сами смотрите, что выгодней).
n - номер конференции
 
переменные в ответах:
id: идентификатор ветки
name: имя задавшего вопрос
email: email задавшего вопрос
title: заголовок вопроса
count: число ответов
answers: список ников, ответивших на вопрос
        (ники разделены ", "; следует заметить, что присылаются не
         ники всех, кто ответил, а только несколько последних;
         это поле только визуально-информативное -- посмотрите на сайт,
         увидите)
dsc: краткое описание самого вопроса (то, что вы видите серым цветом
    на каждой странице в форумах)
date: дата последнего ответа (как хранятся даты -- я опишу позже)
lastmod: дата последнего ответа в формате понятном скрипту.
vd: Версия Delphi, какая БД и т.д. То что в форуме выводится красненьким :) [D5, Win2k]
    в общем и целом может быть любым набором слов, разделённых запятыми.
loginid: номер анкеты спрашивающего. если 0 -- юзер не зарегистрирован.
 
пример ответа:
Allcount=2
id=992553967    name=Adoliks    title=Рисование таблиц в Word средствами Delphi answers=Shtukos email=guru@nord.ptt.ru  count=1 dsc=Господа, подскажите, как из-под Дельфей нарисовать таблицу в Ворде и вставить в неё текст. Просто экспорт текста делал ...  date=24.06.01 23:36 lastmod=992554939 vd=D2, IB4.x  loginid=997732577
id=992553968    name=Merlin . . .
 
замечу, что как в name, так и в title могут быть html-тэги. это надо учитывать при
разборе и выводе.

3. Запрос о полной информации о ветви

Еще смотри расширенный запрос об ответах 

(также см. пункт 8)
http://www.delphimaster.ru/cgi-bin/client.pl?getconf=id&n=0&from=0&to=-1
Где: id - номер запрашиваемой ветви
n - номер конференции
from - с какой позиции выдавать ответы.
Если мы ранее уже получали эту ветвь, то нет необходимости грузить все еще раз,
потому запрашиваем только то, что после.
Если это первый запрос, то from=0
to - до какой позиции выдавать ответы. Если указано -1, то все до конца.
Если from=to, то выдается один ответ. На первом месте from=to=0 находится сам вопрос.
 
возвращает просто строку с html-кодом. если надо из неё добыть разные поля -- строку
следует "разобрать на кусочки". %-)
примечания по разбору:
 начального {<a href="mailto} может и не быть, если юзер не указал мыло.
 после ника может идти
{<a href="http://www.delphimaster.ru/cgi-bin/anketa.pl?id=1125495517" target=_blank>©</a>}
 это значок (c). но может и  не идти, если юзер не зарегистрирован.
 также перед "©" может стоять {<font color} -- для "штанов особого цвета".
 текст ответа всегда начинается с тэга {<p}. заканчивается, соответственно, {</p>}
 
 если в тексте ответа встретилось {<font color=red>} -- это значит, что ответ
 удалён модератором. в тэгах {<small>}...{</small>} следует камент модератора.
 если встретилось {<font color="#} (это может быть и после камента модератора на
 удалённый пост!) -- ветка помечена "синим карандашиком".
 
 примерно так.
 
пример ответа:
Allcount=2
<a href="mailto:zeerg@chat.ru">ZEE</a>   <font color=green><small>(22.06.01 11:13)</small></font><p style="margin-left: 20; margin-right: 20">Народ, помогите с фильтрацией в SQL по дате.<br>Ну то есть выводить записи, в которых значение поля дата лежит в пределах от "одна дата" до "другая дата".</P>
<a href="mailto:udb@mailru.com">Deniz</a>   <font color=green><small>(22.06.01 12:33)</small></font><p style="margin-left: 20; margin-right: 20">Лучше с параметрами:<br>Query1.SQL.Clear;<br>Query1.SQL.Add('select * from table');<br>Query1.SQL.Add('where (date1 >=:param1)');<br>Query1.SQL.Add('and (date1 <=:param2)');<br>Query1.Prepare;<br>Query1.ParamByName('param1').asDateTime:= ...<br>Query1.ParamByName('param2').asDateTime:=...<br>Query1.Open;</P>

4. Данные анкеты

http://www.delphimaster.ru/cgi-bin/client.pl?anketa=id
id - идентификатор юзера
 
Ответ сервера:
id -- id анкеты
login -- ник
sex -- "Мужской"/"Женский" (я проверяю по первой букве, не учитываю регистр)
name
hobby
homepage
city
about
education
date -- когда зарегистрировался
email
0day -- день рождения
icq
 
в hobby и about может быть html-текст.
 
даты -- в обычном формате (см. ниже).

5. Счётчики

Есть опасения, что с введением данного клиента резко упадет посещаемость самого сайта,
а значит и наша позиция в рейтингах, что только отрицательно отразится на популярности.
Поэтому прошу в клиенте при запросе новых вопросов в конференции вызывать и счетчик,
лишние 200 байт погоды не сделают, а польза будет большая.
URL счетчика можно узнать так:
http://www.delphimaster.ru/cgi-bin/client.pl?counter=1
меняться он будет редко, так что перепрочитывать его стоит не чаще чем раз в неделю.
 
пример ответа:
Allcount=1
url=http://top.list.ru/counter?id=53505;js=13;r=;j=true;s=800*600;d=16;rand=%rand%  referrer=http://www.delphimaster.ru/forum/index.html
 
Здесь вместо %rand% стоит подставить случайное число < 1, например:
0.18421077203239022
И просто запросить этот URL, только обязательно !!! укажите referrer.
Ответ нигде показывать не надо.

6. Запрос о доступных серверах

Предполагается, что при первом запуске клиента, он должен по жестко прописанному URL
(http://www.delphimaster.ru/cgi-bin/client.pl)  запросить список доступных серверов,
названия и URL-ы клиентов, для получения конф. от них.
 
(Ketmar: лично я -- как, полагаю, и все остальные -- этого не делаю)
 
http://www.delphimaster.ru/cgi-bin/client.pl?allservers=1
 
пример ответа:
Allcount=1
name=Мастера DELPHI	url=http://www.delphimaster.ru	client=http://www.delphimaster.ru/cgi-bin/client.pl	answer=http://www.delphimaster.ru/cgi-bin/forum.pl?id=%id&n=%n#answer
Здесь:
name - название сервера
url - адрес самого сайта
client - URL клиента, от которого и требовать все данные
answer - формат вызова странички для ответа на вопрос. Т.к. на разных серверах, все,
возможно, будет располагаться в разных местах, то это необходимо. Вам нужно только
подставить вместо %id - номер вопроса, вместо %n - номер конференции

7. Про user agent

Для ведения логов использования клиентов чтения форумов подставляйте во
*все* запросы к серверу UserAgent=Название.Версия
Например:
http://www.delphimaster.ru/cgi-bin/client.pl?getnew=lastmod&n=0&UserAgent=Название.Версия
или, можете указывать агента в заголовке запроса, в стандартном поле
HTTP_USER_AGENT (User-agent: xxx).
(Ketmar: CDM отрекомендовывается как "CDM_by_Ketmar.X", где X -- версия).

8. Расширеный запрос об ответах

Еще смотри запрос о полной информации о ветви 

http://www.delphimaster.ru/cgi-bin/client.pl?getconf2=id&n=0...
см. пункт 3. разница: в первой строке кроме переменной Allcount могут быть ещё:
 state:
   =closed: обсуждение закрыто.
   =moved(n,id): перемещена. n -- номер конференции (куда), id -- id ветки
                 (куда).
 del:
   =...: перечисление удалённых веток. перечисление -- это просто числа,
         разделённые запятой. там ещё встречаются пробелы, "+" и "-". лично
         я (Ketmar) не знаю, что они значат, потому просто игнорирую.
         число -- это номер ответа (как обычно: 0 -- ответ, и далее по возрастанию).
         Gero:
         Пробелов там не встречается.
         + возле цифры ставится, если удален не только текст сообщения, но и ник.
         - на данный момент быть не может, но ситуация, надеюсь, вскоре изменится,
         так как это диапазон, который Максим почему-то не прикрутил, хотя я был
         уверен, что прикрутил.
 pen:
   =...: ветки, помеченые "карандашиком". формат аналогичен "del".

 стоит учесть, что у вышеуказаных переменных могут быть и пустые значения.

к этому запросу можно добавлять "&list=2,3,7-9", например. что вернёт информацию
только об указаных ветках (обратим внимание на возможность указывания диапазонов).

Максим рекомендует сделать галку, которая отключит запросы "getconf2". также при
ошибке можно запросить просто "getconf", а только потом упасть.

9. Создание новой темы

POST на http://www.delphimaster.ru/cgi-bin/forum.pl
содержимое (по полям, url-кодированое, поля объединены "&"):
  add=%C4%EE%E1%E0%E2%E8%F2%FC
  p=1
  name=<uname>
  topsw=<upass>
  n=<forum-id>
  icon=<icon-number(13)>
  title=<subj>
  text=<post-text>
  <env>
 
<env>: переменные vd{1-9a-f}, которые содержат по слову. то, что возвращается в
       поле vd запроса getnew.
 
если код возврата не 3xx, то ошибка отсылки.

a. Отсылка ответа

POST на http://www.delphimaster.ru/cgi-bin/forum.pl
содержимое (по полям, url-кодированое, поля объединены "&"):
  add2=%C4%EE%E1%E0%E2%E8%F2%FC
  p=1
  name=<uname>
  topsw=<upass>
  n=<forum-id>
  id=<topic-id>
  text=<post-text>
 
если код возврата не 3xx, то ошибка отсылки.

b. Ограничения

длина сабжа: не знаю. %-)
 
размер поста: 7 килобайт (7168). рекомендовано 5 (5120). можно 6 (6144). %-)

10. Дополнение от McSimm

getconf2 не документирован. это костыли, поддержка которых не гарантируется, но, вероятнее всего, сохранится.
 
вызов getconf2:
getconf2=1211126613&n=3&from=5&to=7
или
getconf2=1211126613&n=3&list=2,4,7
 
при наличии list= параметры from и to не учитываются
 
ответ аналогичен get_conf, но добавляет к первой строке дополнительную информацию о номерах удаленных сообщений и состоянии ветки:
Allcount=3\tdels=...\tpen=...\tstate=...
\t - символ табуляции
любой из dels,pen,state необязателен (может отсутствовать)
значения:
 
dels=1,3+,7 - означает, что удалены сообщения 1, 3 и 7, причем в 3м удален логин.
 
pen=2,5 - означает, что во 2м и 5м сообщении есть примечание (синий карандаш)
 
state=closed - обсуждение закрыто
state=moved(18,1211126613) - ветка перемещена в конференцию n=0&id=1211126613

См. также

Участникам проекта ДМКлиент доступно много другой технической документации.