Это описание второй версии протокола для доступа к форуму 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 -- это целое число. имена переменных лучше проверять не обращая внимания на регистр.
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=любые вопросы по использованию и программированию БД
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-тэги. это надо учитывать при разборе и выводе.
Еще смотри расширенный запрос об ответах
(также см. пункт 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>
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-текст. даты -- в обычном формате (см. ниже).
Есть опасения, что с введением данного клиента резко упадет посещаемость самого сайта, а значит и наша позиция в рейтингах, что только отрицательно отразится на популярности. Поэтому прошу в клиенте при запросе новых вопросов в конференции вызывать и счетчик, лишние 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. Ответ нигде показывать не надо.
Предполагается, что при первом запуске клиента, он должен по жестко прописанному 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 - номер конференции
Для ведения логов использования клиентов чтения форумов подставляйте во *все* запросы к серверу 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 -- версия).
Еще смотри запрос о полной информации о ветви
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", а только потом упасть.
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, то ошибка отсылки.
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, то ошибка отсылки.
длина сабжа: не знаю. %-) размер поста: 7 килобайт (7168). рекомендовано 5 (5120). можно 6 (6144). %-)
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
Участникам проекта ДМКлиент доступно много другой технической документации.