Описание Протокола NMDC, NeoModus Direct Connect Protocol Опции

[Setuper]

Protocol NMDC

Структурированное описание протокола NeoModus Direct Connect (NMDC), под управлением которого на сегодняшний день работает подавляющее большинство хабов. Хотя уже внедряется новый протокол ADC, однако, как говориться, всему своё время.

По мере написания, на каждую команду будет появляться ссылка на пост, описывающий эту команду.
Делаю тему закрытой, дабы структурировано описать команды.


О структуре команд

Все команды протокола начинаются с символа $. Исключение составляет команда сообщения чата, которая должна иметь следующую структуру:

Код

<Ник> Сообщение|

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

Символы-разделители протокола: $, | и пробел. Протокол не имеет экранирующих символов, поэтому для отсылки символов $ и | в параметрах команд нужно использовать их коды: &#36; и &#124;
Строка сообщения разделяется на команды по средствам символа |. Пример трёх команд, отосланных одной строкой:

Код

$Cmd1 параметр|$Cmd2|$Cmd3 параметр1 параметр2$параметр3|

Взаимодействие хаб-клиент


$BadPass
$Close
$ConnectToMe
$ForceMove
$GetINFO
$GetNickList
$GetPass
$Hello
$HubIsFull
$HubName
$HubTopic
$Key
$Kick
$Lock
$LogedIn
$MyINFO
$MyPass
$MultiConnectToMe
$MultiSearch
$NickList
$OpForceMove
$OpList
$Quit
$RevConnectToMe
$Search
$SR
$Supports
$UserCommand
$UserIP
$Version
$ValidateNick
$ValidateDenide


Взаимодействие клиент-клиент

$Cancel
$Canceled
$Direction
$Error
$Failed
$FileLength
$Get
$GetListLen
$Key
$Lock
$MaxedOut
$MyNick
$Ping
$Send
$To


Взаимодействие хаб-хаб

$FeaturedNetworks
$ConnectToMe
$Search
$SR
$Up
$UpToo




Взаимодействие хаб-хаблист

$Key
$Lock
$Supports


Взаимодействие пингер-хаб

$BotINFO
$HubINFO
$Key
$Lock
$Supports


Команды характеристик

$ADCGET / $ADCSND
$BotList
$Capabilities
$FeaturedNetworks
$GetZBlock
$MCTo
$Sending
$UGetBlock
$UGetZBlock
$Z
$ZOn


Разное

TTH
Lock2Key


Известные характеристики

Хаб-Клиент:
BotList
ClientID
Feed
HubTopic
IN
MCTo
NoGetINFO
NoHello
OpPlus
QuickList
TTHSearch
UserCommand
UserIP2
ZLine
ZPipe0

Клиент-Клиент:
ADCGet
BZList
CHUNK
ClientID
GetCID
GetTestZBlock
GetZBlock
MiniSlots
TTHL
TTHF
XmlBZList
ZLIG



Общая (обязательная) последовательность входа на хаб.
"Рукопожатие" между клиентом и хабом.

Общая (обязательная) последовательность входа на хаб

Хаб:

Код

$Lock [Код] Pk=[PrimaryKey]|

Клиент:

Код

$Key [Рассчитанный_ключ]|$ValidateNick [Ник]|

Хаб:

Код

$HubName [Имя_хаба]|$Hello [Ник]|

Клиент:

Код

$Version [Версия]|$GetNickList|$MyINFO [Строка]|

Хаб:

Код

Отсылает список пользователей.

Примечания:

1. Команда $HubName может "выпадать" из этой последовательности и отсылаться, например, после команды $Lock, или вовсе отсутствовать.
2. Если в начале параметра команды $Lock присутствует слово EXTENDEDPROTOCOL, то клиент должен отослать на хаб команду с поддерживаемыми им характеристиками $Supports. В ответ хаб должен отослать такую же команду со своими характеристиками. Однако, данный механизм обмена характеристиками фактически является не обязательным.
3. Также, вне зависимости от данной последовательности, в любом месте входа хаб может отослать клиенту команду чата: "<[Бот_хаба]> Этот хаб работает под управлением...".
4. При входе, клиент отошлёт команды $Version, $GetNickList и $MyINFO только после того, как получит от хаба команду $Hello [Ник], причём со своим ником, который он отсылал на хаб в команде $ValidateNick. Причем команда $GetNickList может и вовсе не отсылаться клиентом.
5. Команду $Version клиент может отослать и раньше указанного шага (например, непосредственно после $ValidateNick), однако она должна быть отослана до команды $MyINFO.
6. При отсылке хабом списка пользователей, хаб руководствуется поддержкой со стороны клиента той или иной характеристики. Подробности см. в описании характеристик NoHello и NoGetINFO.

Вход на пальцах выглядит так: Клиент коннектится, сервер отвечает командой $Lock, что мол я такой-то сервер, на что клиент отвечает: ок раз ты такой-то сервер - вот тебе ключ ($Key) и проверь мой ник ($ValidateNick), сервер проверяет ник и отправляет клиенту приглашение на вход под этим ником ($Hello), на что клиент отправляет на сервер внутреннюю версию ($Version), запрашивает список пользователей ($GetNickList) и отправляет информацию о себе ($MyINFO), а сервер отсылает ему список пользователей хаба.

Последовательность входа на хаб, который поддерживает характеристику QuickList.

Входа на хаб при поддержке характеристики QuickList (быстрый вход)

Хаб:

Код

$Lock EXTENDEDPROTOCOL[Код] Pk=[PrimaryKey]|

Клиент:

Код

$Supports QuickList|$Key [Рассчитанный_ключ]|

Хаб:

Код

$Supports QuickList|

Клиент:

Код

$MyINFO [Строка]|$GetNickList|

Хаб:

Код

Отсылает список пользователей.

См. подробности в характеристике QuickList

Последовательность действий хаба при регистрации в хаб-листе

Последовательность действий хаба при регистрации в хаб-листе

Хаб коннектится к хаб-листу.

Хаб-лист:

Код

$Lock [Код] Pk=[PrimaryKey]|

Хаб:

Код

$Key [Рассчитанный_ключ]|[Имя_хаба]|[Хост_хаба(:порт)]|[Описание_хаба]|[Число_юзеров]|[Текущая_шара]|

Тут хаб выступает в роли клиента. Он коннектится к прописанным в настройках хаб-листам и передаёт им текущую информацию о себе.
Коннект к хаб листу должен производится не чаще чем раз в 15 минут, в противном случае, хаб может быть забанен хаб-листом)).

Последовательность входа на хаб PtokaX
(последовательные команды могут отсылаться одной строкой, разделённой символом | )

Последовательность входа на хаб PtokaX

Хаб -> Клиент: ---> $Lock EXTENDEDPROTOCOL[некий_ключ_хаба] Pk=PtokaX
Клиент -> Хаб: ---> $Supports UserCommand NoGetINFO NoHello UserIP2 TTHSearch ZPipe0 |$Key [ключ_сгенерированный_по_полученному_ключу_хаба]|$ValidateNick [Мой_ник]|
Выполнение скриптовой функции SupportsArrival
Выполнение скриптовой функции KeyArrival (выполнение не происходит, если проверка ключа отключена)
Выполнение скриптовой функции ValidateNickArrival
Хаб -> Клиент: ---> $Supports NoHello|$GetPass|
Клиент -> Хаб: ---> $MyPass [Мой_пароль]|
Выполнение скриптовой функции PasswordArrival
Хаб -> Клиент: ---> $Hello [Мой_ник]|
Клиент -> Хаб: ---> $Version 1,0091|$GetNickList|$MyINFO $ALL [Мой_ник] [Описание]<[Клиент] V:[Версия],M:[Режим],H:[Хабы],S:[Слоты]>$[EMail]$[Соедиение][Магический_байт]$ $[Шара]$|
Выполнение скриптовой функции VersionArrival
Выполнение скриптовой функции GetNickListArrival
Выполнение скриптовой функции MyINFOArrival
Хаб -> Клиент: ---> $LogedIn [Мой_ник]|$HubName [Имя_хаба] - [Топик]|<[Бот_хаба]> Этот хаб работает под управлением PtokaX DC Hub ...
Хаб -> Клиент: ---> $ZOn
Хаб -> Клиент: ---> $MyINFO $ALL [Бот_хаба] [Описание]$ $$[EMail]$0$|$MyINFO $ALL [Ник1] [Описание]<[Клиент] V:[Версия],M:[Режим],H:[Хабы],S:[Слоты]>$[EMail]$[Соедиение][Магический_байт]$ $[Шара]$|$MyINFO $ALL [Ник2] [Описание]<[Клиент] V:[Версия],M:[Режим],H:[Хабы],S:[Слоты]>$[EMail]$[Соедиение][Магический_байт]$ $[Шара]$|
...
$MyINFO $ALL [Мой_ник] [Описание]<[Клиент] V:[Версия],M:[Режим],H:[Хабы],S:[Слоты]>$[EMail]$[Соедиение][Магический_байт]$ $[Шара]$|$OpList [Оператор1]$$[Оператор2]$$[Оператор3]$$ ... $$[ОператорN]$$|$UserIP [Ник1] [IP1]$$[Ник2] [IP2]$$ ... $$[НикN] [IPN]$$|
Выполнение скриптовых функций UserConnected, RegConnected и OpConnected

Примечание: Команда $LogedIn отсылается только в случае если у вас есть ключ (операторские права).

Внимание! Последовательность входа указана для одного потока. Для разных потоков она может быть произвольной, поэтому никогда не используйте глобальные таблицы пользователей, дабы сохранить принцип многопоточности.

Последовательность команд при получении списка пользователей (GetNickList) на хабе PtokaX

Последовательность команд при получении списка пользователей (GetNickList) на хабе PtokaX

Клиент -> Хаб: ---> $GetNickList|
Выполнение скриптовой функции GetNickListArrival
Хаб -> Клиент: ---> $MyINFO $ALL [Бот_хаба] [Описание]$ $$[EMail]$0$
Хаб -> Клиент: ---> $MyINFO $ALL [Ник1] [Описание]<[Клиент] V:[Версия],M:[Режим],H:[Хабы],S:[Слоты]>$[EMail]$[Соедиение][Магический_байт]$ $[Шара]$|
Хаб -> Клиент: ---> $MyINFO $ALL [Ник2] [Описание]<[Клиент] V:[Версия],M:[Режим],H:[Хабы],S:[Слоты]>$[EMail]$[Соедиение][Магический_байт]$ $[Шара]$|
...
Хаб -> Клиент: ---> $MyINFO $ALL [Мой_ник] [Описание]<[Клиент] V:[Версия],M:[Режим],H:[Хабы],S:[Слоты]>$[EMail]$[Соедиение][Магический_байт]$ $[Шара]$|
Хаб -> Клиент: ---> $OpList [Оператор1]$$[Оператор2]$$[Оператор3]$$ ... $$[ОператорN]$$

Последовательность входа на хаб HeX
(последовательные команды могут отсылаться одной строкой, разделённой символом | )

Последовательность входа на хаб HeX

Хаб -> Клиент: ---> $Lock EXTENDEDPROTOCOL[некий_ключ_хаба] Pk=versiunea5.03
Клиент -> Хаб: ---> $Supports UserCommand NoGetINFO NoHello UserIP2 TTHSearch ZPipe0 |$Key [ключ_сгенерированный_по_полученному_ключу_хаба]|$ValidateNick [Мой_ник]|
Хаб -> Клиент: ---> $HubName [Имя_хаба] - [Топик]|$HubTopic [Топик]|<[Бот_хаба]> HeXHub 5.03a Firewall 1.09 Hex Script 1.1.0.2 ...|
Обработка команды $Supports скриптовой функцией OnCommand
Хаб -> Клиент: ---> $Supports UserCommand NoGetINFO NoHello|
Обработка команды $Key скриптовой функцией OnCommand
Обработка команды $ValidateNick скриптовой функцией OnCommand

Хаб -> Клиент: ---> *** Your nickname is already taken by someone else|*** Current nickname: [Мой_ник]_1|*** This nick is also taken...|*** Current nickname: [Мой_ник]_2|<[Бот_хаба]> Your nickname is registered, please enter a password|$GetPass|
Клиент -> Хаб: ---> $MyPass [Мой_пароль]|
Обработка команды $MyPass скриптовой функцией OnCommand
Хаб -> Клиент: ---> $LogedIn [Мой_ник]|$Hello [Мой_ник]|
Клиент -> Хаб: ---> $Version 1,0091|$GetNickList|$MyINFO $ALL [Мой_ник] [Описание]<[Клиент] V:[Версия],M:[Режим],H:[Хабы],S:[Слоты]>$[EMail]$[Соедиение][Магический_байт]$ $[Шара]$|
Хаб -> Клиент: ---> $Hello [Мой_ник]|
Обработка команды $Version скриптовой функцией OnCommand
Обработка команды $GetNickList скриптовой функцией OnCommand
Обработка команды $MyINFO скриптовой функцией OnCommand
Хаб -> Клиент: ---> $MyINFO $ALL [Бот_хаба] [Описание]$ $$[EMail]$0$|$MyINFO $ALL [Ник1] [Описание]<[Клиент] V:[Версия],M:[Режим],H:[Хабы],S:[Слоты]>$[EMail]$[Соедиение][Магический_байт]$ $[Шара]$|$MyINFO $ALL [Ник2] [Описание]<[Клиент] V:[Версия],M:[Режим],H:[Хабы],S:[Слоты]>$[EMail]$[Соедиение][Магический_байт]$ $[Шара]$|
...
$MyINFO $ALL [Мой_ник]_2 [Описание]<[Клиент] V:[Версия],M:[Режим],H:[Хабы],S:[Слоты]>$[EMail]$[Соедиение][Магический_байт]$ $[Шара]$|$OpList [Оператор1]$$[Оператор2]$$[Оператор3]$$ ... $$[ОператорN]$$|$UserIP [Ник1] [IP1]$$[Ник2] [IP2]$$ ... $$[НикN] [IPN]$$|
Выполнение скриптовой функции OnUserJoined

Примечание: Данный хаб различает вход и переподключение к хабу! Это достигается с помощью задержки в отправлении команды $Quit.

Материал из этой темы перенесён в вики: http://wiki.mydc.ru/Описание_протокола_NMDC

Сообщение отредактировал Setuper - 18.1.2012, 21:48

[Setuper]

BotList

Описание:

Характеристика хаба/клиента. Данная характеристика указывает на поддержку команды $BotList.

Для полного понимания, данная характеристика должна присутствовать в команде $Supports как хаба, так и клиента.

[Setuper]

ClientID

Описание:

Характеристика клиента. Данная характеристика указывает на поддержку команды $ClientID.
Характеристику поддерживают следующие клиенты: BlackDC, iDC++, dDC++, Zion++

[Setuper]

Feed

Описание:

Характеристика хаба.
Данная характеристика позволяет использовать дополнительные протокольные команды уведомления. Характеристика позволяет отслеживать все действия отдельных или всех пользователей, логировать эти действия, а также оповещать операторов хаба о совершённых действиях через отдельно созданную чат-комнату.

На данный момент характеристику Feed поддерживает YnHub.

[Setuper]

HubTopic

Описание:

Характеристика хаба. Указывает на поддержку команды $HubTopic. Данная характеристика является не обязательной, то есть хаб может поддерживать данную команду и без указания данной характеристики.

[Setuper]

IN

Описание:

Пока неизвестная характеристика.

[Setuper]

MCTo

Описание:

Характеристика хаба.
Данная характеристика указывает на поддержку команды $MCTo.
На данный момент характеристику поддерживает хаб YnHub.

[Setuper]

NoGetINFO

Описание:

Характеристика хаба/клиента.
Характеристика указывает на то, что хабу не нужно получать от клиента команды $GetINFO для того, чтобы отсылать ему команды $MyINFO и $NickList. Это некое подобие характеристики QuickList, которая позволяет осуществлять быстрые получения списков пользователей.

Важное замечание!
При отсутствии у клиента характеристики NoHello и при наличии характеристики NoGetINFO хаб должен отсылать клиенту список пользователей при помощи команд $MyINFO и $NickList одновременно. При отсутствии обеих характеристик список пользователей отсылается по средствам команды $NickList, а список пользователей с участием команд $MyINFO можно будет получить только после отсылки на хаб команды $GetINFO.

Характеристика поддерживается клиентами DC++, начиная с версии 0.302.

[Setuper]

NoHello

Описание:

Характеристика хаба/клиента.
Характеристика говорит о том, что при входе нового юзера на хаб, клиенту, уже находящемуся на хабе, не нужно отсылать оповещение о входе юзера в виде команды $Hello. Кроме этого, данная характеристика указывает на то, что хаб не должен отсылать клиенту при коннекте команду $NickList, которая отвечает за получение клиентом ников всех пользователей хаба, а клиент не должен отсылать на хаб команду $GetINFO для получения списка пользователей хаба. Для заполнения списка пользователей хаб должен отослать команду $MyINFO. Клиент отсылает команду $GetNickList для указания того, что он заинтересован в получении списка пользователей, однако, хаб не обязан ждать эту команду и должен отослать список пользователей в любом случае.

Важное замечание!
При наличии у клиента этой характеристики хаб при входе этого клиента будет отсылать клиенту список пользователей командами $MyINFO. Так как команда $MyINFO содержит ники пользователей, то получение ников командой $NickList является лишним действием. Поэтому данная характеристика является самым информативным и оптимальным вариантом.

Характеристика поддерживается клиентами DC++, начиная с версии 0.305.

[Setuper]

OpPlus

Описание:

Характеристика хаба. Указывает на то, что на хабе используются дополнительные команды для операторов. Например: $Ban, $TempBan, $UnBan, $GetBanList, $WhoIP, $Banned, $GetTopic, $SetTopic и тд.

На данный момент команду поддерживает хаб VerliHub.

[Setuper]

QuickList

Описание:

Характеристика хаба/клиента.
Позволяет быстро входить на хаб, экономя трафик и снижая нагрузку на сервер при входе.


Сравнение последовательностей входов с и без характеристики QuickList:

Обозначения:
H - хаб
C - клиент

С характеристикой QuickList

Код

H: $Lock EXTENDEDPROTOCOL[Код] Pk=[PrimaryKey]|
C: $Supports NoHello QuickList|
C: $Key [Рассчитанный_ключ]|
H: $Supports NoHello QuickList|
C: $MyINFO [Строка]|
C: $GetNickList|
H: Отсылает список пользователей.

Без характеристики QuickList

Код

H: $Lock EXTENDEDPROTOCOL[Код] Pk=[PrimaryKey]|
C: $Supports NoHello|
C: $Key [Рассчитанный_ключ]|
H: $Supports NoHello|
C: $ValidateNick [Ник]|
H: $Hello [Ник]|
C: $Version [Версия]|
C: $GetNickList|
C: $MyINFO [Строка]|
H: Отсылает список пользователей.

Поддержка характеристики:

Полноценно данную характеристику поддерживает хаб PtokaX.
Со стороны клиентов, данную характеристику поддерживают следующие клиенты: CZDC, BCDC

Внимание! Так как в данной характеристике отсутствуют шаги валидации ника и проверки версии, то при поддержке со стороны клиента данной характеристики на хабе PtokaX скриптовые функции ValidateNickArrival и VersionArrival для этого клиента выполняться не будут!

[Setuper]

TTHSearch

Описание:

Характеристика клиента.
Эта характеристика указывает на то, что клиент поддерживает поиск файлов по уникальному идентификатору TTH. Поиск по TTH является наиболее эффективным. Для получения большей информации по поиску смотрите описание команды $Search.

Характеристика поддерживается клиентами DC++, начиная с версии 0.307.

[Setuper]

UserCommand

Описание:

Характеристика хаба/клиента.
Данная характеристика указывает на поддержку со стороны хаба или клиента команды $UserCommand, которая позволяет клиенту создавать контекстные менюшки. Наличие этой характеристики в команде $Supports является не обязательным из-за большой распространённости команды.

Характеристика поддерживается клиентами DC++, начиная с версии 0.300.

[Setuper]

UserIP2

Описание:

Характеристика хаба/клиента.
Указывает на то, что хабом (клиентом) поддерживается вторая версия команды $UserIP.
Вторая версия отличается от первой тем, что входящему на хаб пользователю всегда отсылается команда $UserIP с его ником и ip адресом. Ip адреса остальных же пользователей отсылаются в зависимости от статуса пользователя на хабе.

Характеристика поддерживается DC++ клиентами, начиная с версии 0.305.

[Setuper]

ZLine

Описание:

Характеристика хаба/клиента.
Характеристика указывает на поддержку команды сжатия $Z.