API tools faq
paste
Guest User

Untitled

a guest
Feb 5th, 2017
198
0
Never
Add comment
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
text 89.62 KB | None | 0 0
raw download clone embed print report
  1. ---
  2. author:
  3. - 'version 1.0.4, UNRELEASED'
  4. title: ADC Protocol
  5. ---
  6.  
  7. > ADC is a text protocol for a client-server network similar to
  8. > Neo-Modus' Direct Connect (NMDC). The goal is to create a simple
  9. > protocol that doesn’t require much effort neither in hub nor client,
  10. > and is yet extensible. It addresses some of the issues in the NMDC
  11. > protocol, but not all.
  12. >
  13. > The same protocol structure is used both for client-hub and
  14. > client-client communication. This document is split into two parts;
  15. > the first shows the structure of the protocol, while the second
  16. > implements a specific system using this structure. ADC stands for
  17. > anything you would like it to stand for; Advanced Direct Connect is
  18. > the first neutral thing that springs to mind =).
  19. >
  20. > Many ideas for the protocol come from Jan Vidar Krey’s DCTNG draft.
  21. > Major contributors include Dustin Brody, Walter Doekes, Timmo Stange,
  22. > Fredrik Ullner, Fredrik Stenberg and others. Jon Hess contributed the
  23. > original Direct Connect idea through the Neo-Modus Direct Connect
  24. > client / hub.
  25.  
  26. Version history {#_version_history}
  27. ===============
  28.  
  29. The latest draft of the next version of this document as well as
  30. intermediate and older versions can be downloaded from \$URL:
  31. <https://svn.code.sf.net/p/adc/code/trunk/ADC.txt> \$. This version
  32. corresponds to \$Revision: 126 \$.
  33.  
  34. Version 1.0.4, UNRELEASED {#_version_1_0_4_unreleased}
  35. -------------------------
  36.  
  37. - Separators in the command description for GET, GFI and SND are now
  38. explicit.
  39.  
  40. - Clarified UTF-8 encoding note.
  41.  
  42. Version 1.0.3, 2013-06-30 {#_version_1_0_3_2013_06_30}
  43. -------------------------
  44.  
  45. Fredrik Ullner &lt;<ullner@gmail.com>&gt;
  46.  
  47. - Added examples for each command.
  48.  
  49. - Features are now described in its own section.
  50.  
  51. - Specified token use from server party in client-client connections.
  52.  
  53. - Changed size in file list schema to an unsigned long to manage files
  54. larger than 2 GiB.
  55.  
  56. Version 1.0.2, 2013-01-31 {#_version_1_0_2_2013_01_31}
  57. -------------------------
  58.  
  59. Fredrik Ullner &lt;<ullner@gmail.com>&gt;
  60.  
  61. - Editorial updates
  62.  
  63. - Added a terminology section
  64.  
  65. - Added note in STA, severity 2 (Fatal), on responsibility.
  66.  
  67. - State management is now its own section.
  68.  
  69. - The client in a client-client connection should send its INF first
  70. now.
  71.  
  72. Version 1.0.1, 2008-05-02 {#_version_1_0_1_2008_05_02}
  73. -------------------------
  74.  
  75. Jacek Sieka &lt;<arnetheduck@gmail.com>&gt;
  76.  
  77. - Moved extensions to a separate document
  78.  
  79. - Moved specification to a separate project on SourceForge
  80.  
  81. Version 1.0, 2007-12-01 {#_version_1_0_2007_12_01}
  82. -----------------------
  83.  
  84. Jacek Sieka &lt;<arnetheduck@gmail.com>&gt;
  85.  
  86. - Initial release
  87.  
  88. Line protocol {#_line_protocol}
  89. =============
  90.  
  91. General {#_general}
  92. -------
  93.  
  94. - All messages begin with a four-letter word (FOURCC). The first
  95. letter designates how the message should be sent and the other three
  96. specify what to do.
  97.  
  98. - Parameters are separated by space and a newline (codepoint 0x0a)
  99. ends each message. The string "\\s" escapes space, "\\n" newline and
  100. "\\\\" backslash. This version of the protocol reserves all other
  101. escapes for future use; any message containing unknown escapes must
  102. be discarded.
  103.  
  104. - All text must be sent as 1-to-4 byte, RFC 3629-compliant UTF-8
  105. encoded Unicode in normalization form C.
  106.  
  107. - Clients must ignore unknown/badly formatted messages. Hubs must
  108. ignore invalid messages and should dispatch unknown messages
  109. according to their type.
  110.  
  111. - Client addresses must be specified in dotted-decimal form
  112. ("x.x.x.x") for IPv4 and RFC 4291 form for IPv6. Hub addresses must
  113. be specified in URL form, with "adc" as protocol specifier
  114. ("adc://server:port/").
  115.  
  116. - Numbers are sent as strings in standard floating point notation,
  117. using *.* as the decimal separator and without a thousands
  118. separator. Integers are numbers with neither a decimal portion nor
  119. an exponent. Applications should be prepared to handle at least
  120. 64-bit signed integers and 64-bit floating point numbers. A *-*
  121. prefix negates.
  122.  
  123. - SIDs, PIDs, CIDs, and short binary data are sent as base32-encoded
  124. strings. Long binary data transfers should use the file transfer
  125. mechanism with named roots.
  126.  
  127. - Extension names, protocol names, and other text not entered by the
  128. user may only include viewable characters that can be encoded by one
  129. byte in the UTF-8 encoding (Unicode codepoints 33-127). ADC is
  130. case-sensitive, requiring upper case for command names.
  131.  
  132. - Some commands and functionality require the use of a hash function.
  133. The hash function is negotiated during session setup and stays the
  134. same for the duration of the session.
  135.  
  136. Message syntax {#_message_syntax}
  137. --------------
  138.  
  139. message ::= message_body? eol
  140. message_body ::= (b_message_header | cih_message_header | de_message_header | f_message_header | u_message_header)
  141. (separator positional_parameter)* (separator named_parameter)*
  142. b_message_header ::= 'B' command_name separator my_sid
  143. cih_message_header ::= ('C' | 'I' | 'H') command_name
  144. de_message_header ::= ('D' | 'E') command_name separator my_sid separator target_sid
  145. f_message_header ::= 'F' command_name separator my_sid separator (('+'|'-') feature_name)+
  146. u_message_header ::= 'U' command_name separator my_cid
  147. command_name ::= simple_alpha simple_alphanum simple_alphanum
  148. positional_parameter ::= parameter_value
  149. named_parameter ::= parameter_name parameter_value?
  150. parameter_name ::= simple_alpha simple_alphanum
  151. parameter_value ::= escaped_letter+
  152. target_sid ::= encoded_sid
  153. my_sid ::= encoded_sid
  154. encoded_sid ::= base32_character{4}
  155. my_cid ::= encoded_cid
  156. encoded_cid ::= base32_character+
  157. base32_character ::= simple_alpha | [2-7]
  158. feature_name ::= simple_alpha simple_alphanum{3}
  159. escaped_letter ::= [^ \#x0a] | escape 's' | escape 'n' | escape escape
  160. escape ::= '\'
  161. simple_alpha ::= [A-Z]
  162. simple_alphanum ::= [A-Z0-9]
  163. eol ::= #x0a
  164. separator ::= ' '
  165.  
  166. Message types {#_message_types}
  167. -------------
  168.  
  169. Message type specifies how messages should be routed and thus which
  170. additional fields can be found in the message header. Clients should use
  171. the most limiting type, in terms of recipients, that makes sense for a
  172. particular message when sending it to the hub for distribution. Clients
  173. should use the message type only to aid in parsing the message and
  174. otherwise ignore it. The following message types are defined:
  175.  
  176. +----------------------+----------------------+----------------------+
  177. | B | Broadcast | Hub must send |
  178. | | | message to all |
  179. | | | connected clients, |
  180. | | | including the sender |
  181. | | | of the message. |
  182. +----------------------+----------------------+----------------------+
  183. | C | Client message | Clients must use |
  184. | | | this message type |
  185. | | | when communicating |
  186. | | | directly over TCP. |
  187. +----------------------+----------------------+----------------------+
  188. | D | Direct message | The hub must send |
  189. | | | the message to the |
  190. | | | target\_sid user. |
  191. +----------------------+----------------------+----------------------+
  192. | E | Echo message | The hub must send |
  193. | | | the message to the |
  194. | | | target\_sid user and |
  195. | | | the my\_sid user. |
  196. +----------------------+----------------------+----------------------+
  197. | F | Feature broadcast | The hub must send |
  198. | | | message to all |
  199. | | | clients that support |
  200. | | | both all required |
  201. | | | (+) and no excluded |
  202. | | | (-) features named. |
  203. | | | The feature name is |
  204. | | | matched against the |
  205. | | | corresponding SU |
  206. | | | field in INF sent by |
  207. | | | each client. |
  208. +----------------------+----------------------+----------------------+
  209. | H | Hub message | Clients must use |
  210. | | | this message type |
  211. | | | when a message is |
  212. | | | intended for the hub |
  213. | | | only. |
  214. +----------------------+----------------------+----------------------+
  215. | I | Info message | Hubs must use this |
  216. | | | message type when |
  217. | | | sending a message to |
  218. | | | a client that didn’t |
  219. | | | come from another |
  220. | | | client. |
  221. +----------------------+----------------------+----------------------+
  222. | U | UDP message | Clients must use |
  223. | | | this message type |
  224. | | | when communicating |
  225. | | | directly over UDP. |
  226. +----------------------+----------------------+----------------------+
  227.  
  228. Session hash {#_session_hash}
  229. ------------
  230.  
  231. Certain commands require the use of a hash function. The hash function
  232. used is negotiated using the SUP mechanism each time a new connection is
  233. established. When a client first connects, it offers a set of hash
  234. functions as SUP features. The server picks one of the offered functions
  235. and communicates its choice to the client by placing it before any other
  236. hash features present in the first SUP from the server. Clients and hubs
  237. are required to support at least one hash function, used both for
  238. protocol purposes and file identification.
  239.  
  240. Client identification {#_client_identification}
  241. ---------------------
  242.  
  243. Each client is identified by three different IDs, Session ID (SID),
  244. Private ID (PID), and Client ID (CID).
  245.  
  246. ### Session ID {#_session_id}
  247.  
  248. Session IDs appear in all communication that interacts with the hub.
  249. They identify a unique user on a single hub and are assigned by the hub
  250. during initial protocol negotiation. SIDs are 20 bits long and encoded
  251. using a 4-byte base32 encoded string.
  252.  
  253. ### Private ID {#_private_id}
  254.  
  255. Private IDs globally identify a unique client. They function during
  256. initial protocol negotiation to generate the CID and are invisible to
  257. other clients. PIDs should be generated in a way to avoid collisions,
  258. for example using the hash of the current time and primary network card
  259. MAC address if sufficient randomness cannot be generated. Hubs and
  260. clients may not disclose PIDs to other clients; doing so weakens the
  261. security of the ADC network. Clients should should keep the same PID
  262. between sessions and hubs. PID length follows the length of the hash
  263. algorithm used for the session.
  264.  
  265. ### Client ID {#_client_id}
  266.  
  267. Client IDs globally and publicly identify a unique client and underlie
  268. client to client communication. They are generated by hashing the
  269. (unencoded) PID with the session hash algorithm. Hubs should register
  270. clients by CID. CID length follows the length of the hash algorithm used
  271. for the session. Clients must be prepared to handle CIDs of varying
  272. lengths.
  273.  
  274. Files {#_files}
  275. =====
  276.  
  277. File names and structure {#_file_names_and_structure}
  278. ------------------------
  279.  
  280. Filenames are relative to a fictive root in the user’s share. "/"
  281. separates directories; each file or directory name must be unique in a
  282. case-insensitive context. All printable characters, including
  283. whitespace, are valid names for files, the "/" and "\\" being escaped by
  284. "\\". Clients must then properly filter the filename for the target file
  285. system, as well as request filenames from other clients according to
  286. these rules. The special names "." and ".." may not occur as a directory
  287. or filename; any file list received containing those must be ignored.
  288. All directory names must end with a "/".
  289.  
  290. Shared files are identified relative to the unnamed root "/"
  291. ("/dir/subdir/filename.ext"), while extensions can add named roots to
  292. this namespace. For example, "TTH/…" from the TIGR extension uses the
  293. named root "TTH" to identify files by their Tiger tree hash. It is
  294. invalid for names from the unnamed root to appear in the share without
  295. also being identified by at least one hash value.
  296.  
  297. The rootless filename "files.xml" specifies the full file listing,
  298. uncompressed, in XML using the UTF-8 encoding. It is recommended that
  299. clients use an extension to transfer this list in compressed form.
  300.  
  301. Extensions may specify additional rootless filenames, but should
  302. generally avoid doing so to avoid name clashes.
  303.  
  304. The special type "list" is used to browse partial lists. A partial file
  305. list has the same structure as a normal list, but directories may be
  306. tagged with an attribute *Incomplete="1"* to specify that they have
  307. unexpanded sub-entries. Only directory names in the unnamed root may be
  308. requested, for instance "/" and "/share/". The content of that directory
  309. will then be sent to the requesting client to a depth chosen by the
  310. sending client (it should normally only send the directory level
  311. requested, but may choose to send more if there are few entries, for
  312. example a directory only containing a few files). The "Base" attribute
  313. of "FileListing" specifies which directory a particular file list
  314. represents.
  315.  
  316. File list {#_file_list}
  317. ---------
  318.  
  319. files.xml is the list of files intended for browsing. The file list must
  320. validate against the following XML schema:
  321.  
  322. <?xml version="1.0" encoding="UTF-8"?>
  323. <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  324. <xs:simpleType name="base32Binary">
  325. <xs:restriction base="xs:string">
  326. <xs:pattern value="[A-Za-z2-7]+"></xs:pattern>
  327. </xs:restriction>
  328. </xs:simpleType>
  329.  
  330. <xs:simpleType name="zeroOne">
  331. <xs:restriction base="xs:int">
  332. <xs:enumeration value="0"></xs:enumeration>
  333. <xs:enumeration value="1"></xs:enumeration>
  334. </xs:restriction>
  335. </xs:simpleType>
  336.  
  337. <xs:complexType name="ContainerType">
  338. <xs:sequence minOccurs="0" maxOccurs="unbounded">
  339. <xs:choice>
  340. <xs:element ref="Directory"></xs:element>
  341. <xs:element ref="File"></xs:element>
  342. <xs:any processContents="lax"></xs:any>
  343. </xs:choice>
  344. </xs:sequence>
  345. </xs:complexType>
  346.  
  347. <xs:attribute name="Base" type="xs:string"></xs:attribute>
  348. <xs:attribute name="CID" type="base32Binary"></xs:attribute>
  349. <xs:attribute name="Generator" type="xs:string"></xs:attribute>
  350. <xs:attribute name="Incomplete" type="zeroOne" default="0"></xs:attribute>
  351. <xs:attribute name="Name" type="xs:string"></xs:attribute>
  352. <xs:attribute name="Size" type="xs:unsignedLong"></xs:attribute>
  353. <xs:attribute name="Version" type="xs:int"></xs:attribute>
  354.  
  355. <xs:element name="FileListing">
  356. <xs:complexType>
  357. <xs:complexContent>
  358. <xs:extension base="ContainerType">
  359. <xs:attribute ref="CID" use="required"></xs:attribute>
  360. <xs:attribute ref="Version" use="required"></xs:attribute>
  361. <xs:attribute ref="Generator" use="optional"></xs:attribute>
  362. <xs:attribute ref="Base" use="required"></xs:attribute>
  363. <xs:anyAttribute processContents="lax"></xs:anyAttribute>
  364. </xs:extension>
  365. </xs:complexContent>
  366. </xs:complexType>
  367. </xs:element>
  368.  
  369. <xs:element name="Directory">
  370. <xs:complexType>
  371. <xs:complexContent>
  372. <xs:extension base="ContainerType">
  373. <xs:attribute ref="Name" use="required"></xs:attribute>
  374. <xs:attribute ref="Incomplete" use="optional"></xs:attribute>
  375. <xs:anyAttribute processContents="lax"></xs:anyAttribute>
  376. </xs:extension>
  377. </xs:complexContent>
  378. </xs:complexType>
  379. </xs:element>
  380.  
  381. <xs:element name="File">
  382. <xs:complexType>
  383. <xs:sequence>
  384. <xs:any minOccurs="0" maxOccurs="unbounded"></xs:any>
  385. </xs:sequence>
  386. <xs:attribute ref="Name" use="required"></xs:attribute>
  387. <xs:attribute ref="Size" use="required"></xs:attribute>
  388. <xs:anyAttribute processContents="lax"></xs:anyAttribute>
  389. </xs:complexType>
  390. </xs:element>
  391.  
  392. </xs:schema>
  393.  
  394. An example file list:
  395.  
  396. <?xml version="1.0" encoding="utf-8" standalone="yes"?>
  397. <FileListing Version="1" CID="mycid" Generator="DC++ 0.701" Base="/">
  398. <Directory Name="share">
  399. <Directory Name="DC++ Prerelease">
  400. <File Name="DCPlusPlus.pdb" Size="17648640" TTH="xxx" />
  401. <File Name="DCPlusPlus.exe" Size="946176" TTH="yyy" />
  402. </Directory>
  403. <File Name="ADC.txt" Size="154112" TTH="zzz" />
  404. </Directory>
  405. <!-- Only used by partial lists -->
  406. <Directory Name="share2" Incomplete="1"/>
  407. </FileListing>
  408.  
  409. "encoding" must always be set to UTF-8. Clients must be prepared to
  410. handle XML files both with and without a BOM (byte order mark), although
  411. should not output one.
  412.  
  413. "Version" will not change unless a breaking change is done to the
  414. structure of the file.
  415.  
  416. "CID" is the CID of the client that generated the list.
  417.  
  418. "Generator" is optional and for informative purposes only.
  419.  
  420. "Base" is used for partial file lists, but must be present even in the
  421. non-partial list.
  422.  
  423. "Incomplete" signals whether a directory in a partial file list contains
  424. unlisted items. "1" means the directory contains unlisted items, "0"
  425. that it does not. Incomplete="0" is the default and may thus be omitted.
  426.  
  427. "TTH" is used by the TIGR extension.
  428.  
  429. More information may be added to the file by extensions, but is not
  430. guaranteed to be interpreted by other clients.
  431.  
  432. BASE messages {#_base_messages}
  433. =============
  434.  
  435. ADC clients/hubs that support the following messages must advertise the
  436. feature "BASE" .
  437.  
  438. The connecting party will be known as client, the other as server. For
  439. each message, the action code and the message contexts under which it is
  440. valid are specified.
  441.  
  442. The message context specifies how the message may be received / sent.
  443. Hubs and clients may support using the message in additional contexts as
  444. well. The context codes are as follows:
  445.  
  446. +-----------------------------------+-----------------------------------+
  447. | F | From hub (hub-client TCP) |
  448. +-----------------------------------+-----------------------------------+
  449. | T | To hub (hub-client TCP) |
  450. +-----------------------------------+-----------------------------------+
  451. | C | Between clients (client-client |
  452. | | TCP) |
  453. +-----------------------------------+-----------------------------------+
  454. | U | Between clients (client-client |
  455. | | UDP) |
  456. +-----------------------------------+-----------------------------------+
  457.  
  458. When requesting a new client-client connection, this protocol is
  459. identified by "ADC/1.0".
  460.  
  461. In the descriptions of the commands, the message header and trailing
  462. named parameters have been omitted.
  463.  
  464. State management {#_state_management}
  465. ----------------
  466.  
  467. ADC defines a state machine to control flow and processing of messages.
  468. The receiving end must ensure, according to the state machine, that it
  469. does not parse or drop messages while it is in the process of another
  470. state where the message might be invalid.
  471.  
  472. +-----------------------------------+-----------------------------------+
  473. | State | Description |
  474. +===================================+===================================+
  475. | PROTOCOL | Feature support recovery |
  476. +-----------------------------------+-----------------------------------+
  477. | IDENTIFY | User identification and static |
  478. | | checks |
  479. +-----------------------------------+-----------------------------------+
  480. | VERIFY | Password check (does not exist in |
  481. | | C-C communication unless |
  482. | | announced by an extension) |
  483. +-----------------------------------+-----------------------------------+
  484. | NORMAL | Normal operation (end state) |
  485. +-----------------------------------+-----------------------------------+
  486. | DATA | Binary transfers. The state |
  487. | | changes back to NORMAL once the |
  488. | | transfer is complete. |
  489. +-----------------------------------+-----------------------------------+
  490.  
  491. The states presented are the login order, from top to bottom.
  492.  
  493. ### States {#_states}
  494.  
  495. #### PROTOCOL {#_protocol}
  496.  
  497. When the hub receives a SUP, it should reply with its own SUP followed
  498. by SID assignment. The hub transitions the state then to IDENTIFY.
  499.  
  500. When the server party receives a SUP in the client-client connection, it
  501. should reply with its own SUP. The server transitions the state then to
  502. IDENTIFY.
  503.  
  504. #### IDENTIFY {#_identify}
  505.  
  506. The hub may initiate this state by sending its own INF in this state but
  507. is not required. The client should send its INF whereupon the hub shall
  508. verify the PD and ID fields and other required fields. The hub
  509. transitions the state then to VERIFY if the user is registered or NORMAL
  510. if not.
  511.  
  512. The client party in the client-client connection shall send its INF
  513. whereupon the server party shall send its INF. The server transitions
  514. the state then to NORMAL (or VERIFY if an extension implements this).
  515.  
  516. #### VERIFY {#_verify}
  517.  
  518. The hub shall send a GPA whereupon the client will respond with a PAS.
  519. The server transitions the state then to NORMAL.
  520.  
  521. Client-client support for VERIFY must be signaled as an extension.
  522.  
  523. #### NORMAL {#_normal}
  524.  
  525. The hub should send its INF if not done already. The server shall send
  526. the INF of all connected clients whereupon the connecting client’s INF
  527. shall be last. Normal operation may then commence with chatting and file
  528. sharing.
  529.  
  530. Normal operation may commence immediately in a client-client connection.
  531. Typically, the downloading party sends a GET whereupon the other party
  532. sends a SND followed by a transition to the DATA state.
  533.  
  534. #### DATA {#_data}
  535.  
  536. The DATA state is an actual binary transfer state, it does not have any
  537. commands or other content beyond streaming data.
  538.  
  539. The DATA state exist only in the client-client communication, an
  540. extension can be used to add binary transfers between a client and a
  541. hub. The DATA state commence after a SND command.
  542.  
  543. The state transitions back to NORMAL once the correct amount of bytes
  544. are transferred (specified by a previous command).
  545.  
  546. ### Notes {#_notes}
  547.  
  548. State always transitions from PROTOCOL to IDENTIFY and never from
  549. IDENTIFY to PROTOCOL. Likewise apply between IDENTIFY, VERIFY and
  550. NORMAL. This does not apply between NORMAL and DATA.
  551.  
  552. Successful commands sent after a state transition indicate that the next
  553. state has been reached. For example, PROTOCOL begins a connection and
  554. state changes to IDENTIFY once the hub sends the SID.
  555.  
  556. The state is shared between the client and the server while the server
  557. (implicitly) controls state transitions.
  558.  
  559. The connecting party is known as the client and the other is known as
  560. the server (or hub). The client initiates the connection and state
  561. machine by sending its own SUP.
  562.  
  563. A STA is valid in all states (except DATA) and may require that messages
  564. are resent (i.e. that the state transition does not occur).
  565.  
  566. It is always the client party in a client-client connection that sent
  567. the connection request (CTM/RCM) command that is given control of the
  568. connection once the NORMAL state has been reached.
  569.  
  570. Any party may disconnect the connection if they receive invalid data or
  571. insufficient data. All implementations must therefore be prepared for a
  572. potential disconnection following each command, meaning that the
  573. following state is not achieved. A disconnection should be preceded by a
  574. STA or a QUI to indicate what was wrong.
  575.  
  576. The hub’s INF is optionally sent in IDENTIFY or in NORMAL.
  577.  
  578. +-----------------------------------+-----------------------------------+
  579. | State | Commands |
  580. +===================================+===================================+
  581. | PROTOCOL | STA, SUP, SID |
  582. +-----------------------------------+-----------------------------------+
  583. | IDENTIFY | STA, INF, QUI |
  584. +-----------------------------------+-----------------------------------+
  585. | VERIFY | STA, GPA, PAS, QUI |
  586. +-----------------------------------+-----------------------------------+
  587. | NORMAL | STA, SUP, INF, MSG, SCH, RES, |
  588. | | CTM, RCM, QUI, GET, GFI, SND |
  589. +-----------------------------------+-----------------------------------+
  590.  
  591. Features {#_features}
  592. --------
  593.  
  594. Features are used to indicate support for protocol commands or
  595. functionality.
  596.  
  597. The server may use any feature that the client indicates support for
  598. regardless of its own SUP and vice versa. A client can announce features
  599. in the SUP regardless of the INF’s SU field and vice versa.
  600.  
  601. A feature name consists of four uppercase letters, where the last letter
  602. may be changed to a number to indicate a revised version of the feature.
  603.  
  604. A central register of known features is kept to avoid clashes, see below
  605. features in this protocol and the features in the extension document.
  606.  
  607. ### BASE {#_base}
  608.  
  609. All clients must support the BASE feature (unless a future revision
  610. takes its place), which is this protocol.
  611.  
  612. Clients must add the feature to the INF’s SU field.
  613.  
  614. ### TCP4 / TCP6 {#_tcp4_tcp6}
  615.  
  616. The features TCP4 and TCP6 are used to indicate support for incoming TCP
  617. connections. The 4 and 6 indicate IPv4 and IPv6.
  618.  
  619. Clients should add the feature to the INF’s SU field.
  620.  
  621. Clients that support incoming TCP connections is referenced as *active*
  622. where the opposite is *passive*.
  623.  
  624. ### UDP4 / UDP6 {#_udp4_udp6}
  625.  
  626. The features UDP4 and UDP6 are used to indicate support for incoming UDP
  627. packets. The 4 and 6 indicate UDP with IPv4 and IPv6.
  628.  
  629. Clients should add the feature to the INF’s SU field.
  630.  
  631. Clients that support incoming UDP packets is referenced as *active*
  632. where the opposite is *passive*.
  633.  
  634. Actions {#_actions}
  635. -------
  636.  
  637. ### STA {#_sta}
  638.  
  639. STA code description
  640.  
  641. Contexts: F, T, C, U
  642.  
  643. States: PROTOCOL, IDENTIFY, VERIFY, NORMAL
  644.  
  645. Status code in the form "xyy" where x specifies severity and yy the
  646. specific error code. The severity and error code are treated separately,
  647. the same error could occur at different severity levels.
  648.  
  649. Severity values:
  650.  
  651. +-----------------------------------+-----------------------------------+
  652. | 0 | Success (used for confirming |
  653. | | commands), error code must be |
  654. | | "00", and an additional flag "FC" |
  655. | | contains the FOURCC of the |
  656. | | command being confirmed if |
  657. | | applicable. |
  658. +-----------------------------------+-----------------------------------+
  659. | 1 | Recoverable (error but no |
  660. | | disconnect) |
  661. +-----------------------------------+-----------------------------------+
  662. | 2 | Fatal (disconnect), sending party |
  663. | | is responsible for action. |
  664. +-----------------------------------+-----------------------------------+
  665.  
  666. Error codes:
  667.  
  668. +-----------------------------------+-----------------------------------+
  669. | 00 | Generic, show description |
  670. +-----------------------------------+-----------------------------------+
  671. | x0 | Same as 00, but categorized |
  672. | | according to the rough structure |
  673. | | set below |
  674. +-----------------------------------+-----------------------------------+
  675. | 10 | Generic hub error |
  676. +-----------------------------------+-----------------------------------+
  677. | 11 | Hub full |
  678. +-----------------------------------+-----------------------------------+
  679. | 12 | Hub disabled |
  680. +-----------------------------------+-----------------------------------+
  681. | 20 | Generic login/access error |
  682. +-----------------------------------+-----------------------------------+
  683. | 21 | Nick invalid |
  684. +-----------------------------------+-----------------------------------+
  685. | 22 | Nick taken |
  686. +-----------------------------------+-----------------------------------+
  687. | 23 | Invalid password |
  688. +-----------------------------------+-----------------------------------+
  689. | 24 | CID taken |
  690. +-----------------------------------+-----------------------------------+
  691. | 25 | Access denied, flag "FC" is the |
  692. | | FOURCC of the offending command. |
  693. | | Sent when a user is not allowed |
  694. | | to execute a particular command |
  695. +-----------------------------------+-----------------------------------+
  696. | 26 | Registered users only |
  697. +-----------------------------------+-----------------------------------+
  698. | 27 | Invalid PID supplied |
  699. +-----------------------------------+-----------------------------------+
  700. | 30 | Kicks/bans/disconnects generic |
  701. +-----------------------------------+-----------------------------------+
  702. | 31 | Permanently banned |
  703. +-----------------------------------+-----------------------------------+
  704. | 32 | Temporarily banned, flag "TL" is |
  705. | | an integer specifying the number |
  706. | | of seconds left until it expires |
  707. | | (This is used for kick as well…). |
  708. +-----------------------------------+-----------------------------------+
  709. | 40 | Protocol error |
  710. +-----------------------------------+-----------------------------------+
  711. | 41 | Transfer protocol unsupported, |
  712. | | flag "TO" the token, flag "PR" |
  713. | | the protocol string. The client |
  714. | | receiving a CTM or RCM should |
  715. | | send this if it doesn’t support |
  716. | | the C-C protocol. |
  717. +-----------------------------------+-----------------------------------+
  718. | 42 | Direct connection failed, flag |
  719. | | "TO" the token, flag "PR" the |
  720. | | protocol string. The client |
  721. | | receiving a CTM or RCM should |
  722. | | send this if it tried but |
  723. | | couldn’t connect. |
  724. +-----------------------------------+-----------------------------------+
  725. | 43 | Required INF field missing/bad, |
  726. | | flag "FM" specifies missing |
  727. | | field, "FB" specifies invalid |
  728. | | field. |
  729. +-----------------------------------+-----------------------------------+
  730. | 44 | Invalid state, flag "FC" the |
  731. | | FOURCC of the offending command. |
  732. +-----------------------------------+-----------------------------------+
  733. | 45 | Required feature missing, flag |
  734. | | "FC" specifies the FOURCC of the |
  735. | | missing feature. |
  736. +-----------------------------------+-----------------------------------+
  737. | 46 | Invalid IP supplied in INF, flag |
  738. | | "I4" or "I6" specifies the |
  739. | | correct IP. |
  740. +-----------------------------------+-----------------------------------+
  741. | 47 | No hash support overlap in SUP |
  742. | | between client and hub. |
  743. +-----------------------------------+-----------------------------------+
  744. | 50 | Client-client / file transfer |
  745. | | error |
  746. +-----------------------------------+-----------------------------------+
  747. | 51 | File not available |
  748. +-----------------------------------+-----------------------------------+
  749. | 52 | File part not available |
  750. +-----------------------------------+-----------------------------------+
  751. | 53 | Slots full |
  752. +-----------------------------------+-----------------------------------+
  753. | 54 | No hash support overlap in SUP |
  754. | | between clients. |
  755. +-----------------------------------+-----------------------------------+
  756.  
  757. Description: Description of the error, suitable for viewing directly by
  758. the user
  759.  
  760. Even if an error code is unknown by the client, it should display the
  761. text message alone. Error codes are used so that the client can take
  762. different action on different errors. Most error codes don’t have
  763. parameters and only make sense in C and I types.
  764.  
  765. ### SUP {#_sup}
  766.  
  767. SUP ('AD' | 'RM') feature (separator ('AD' | 'RM') feature)*
  768.  
  769. Contexts: F, T, C
  770.  
  771. States: PROTOCOL, NORMAL
  772.  
  773. This command identifies which features a specific client / hub supports.
  774.  
  775. This command can also be used to dynamically add / remove features, *AD*
  776. meaning add and *RM* meaning remove.
  777.  
  778. ### SID {#_sid}
  779.  
  780. SID sid
  781.  
  782. Contexts: F
  783.  
  784. States: PROTOCOL
  785.  
  786. This command assigns a SID to a user who is currently logging on.
  787.  
  788. ### INF {#_inf}
  789.  
  790. INF
  791.  
  792. Contexts: F, T, C
  793.  
  794. States: IDENTIFY, NORMAL
  795.  
  796. This command updates the information about a client. Each time this is
  797. received, it means that the fields specified have been added or updated.
  798. Each field is identified by two characters, directly followed by the
  799. data associated with that field. A field, and the effects of its
  800. presence, can be canceled by sending the field name without data.
  801. Clients must ignore fields they don’t recognize. Most of these fields
  802. are only interesting in the client-hub communication; during
  803. client-client this command is mainly used for identification purposes.
  804. Hubs can choose to require or ignore any or all of these fields; clients
  805. must work without any of them. Many of these fields, such as share size
  806. and client version, are purely informative, and should be taken with a
  807. grain of salt, as it is very easy to fake them. However, clients should
  808. strive to provide accurate data for the general health of the system, as
  809. providing invalid information probably will annoy a great deal of
  810. people. Updates are made in an incremental manner, by sending only the
  811. fields that have changed.
  812.  
  813. Fields:
  814.  
  815. +----------------------+----------------------+----------------------+
  816. | Code | Type | Description |
  817. +======================+======================+======================+
  818. | ID | base32 | The CID of the |
  819. | | | client. Mandatory |
  820. | | | for C-C connections. |
  821. +----------------------+----------------------+----------------------+
  822. | PD | base32 | The PID of the |
  823. | | | client. Hubs must |
  824. | | | check that the |
  825. | | | hash(PID) == CID and |
  826. | | | then discard the |
  827. | | | field before |
  828. | | | broadcasting it to |
  829. | | | other clients. Must |
  830. | | | not be sent in C-C |
  831. | | | connections. |
  832. +----------------------+----------------------+----------------------+
  833. | I4 | IPv4 | IPv4 address without |
  834. | | | port. A zero address |
  835. | | | (0.0.0.0) means that |
  836. | | | the server should |
  837. | | | replace it with the |
  838. | | | real IP of the |
  839. | | | client. Hubs must |
  840. | | | check that a |
  841. | | | specified address |
  842. | | | corresponds to what |
  843. | | | the client is |
  844. | | | connecting from to |
  845. | | | avoid DoS attacks |
  846. | | | and only allow |
  847. | | | trusted clients to |
  848. | | | specify a different |
  849. | | | address. Clients |
  850. | | | should use the zero |
  851. | | | address when |
  852. | | | connecting, but may |
  853. | | | opt not to do so at |
  854. | | | the user’s |
  855. | | | discretion. |
  856. +----------------------+----------------------+----------------------+
  857. | I6 | IPv6 | IPv6 address without |
  858. | | | port. A zero address |
  859. | | | (::) means that the |
  860. | | | server should |
  861. | | | replace it with the |
  862. | | | IP of the client. |
  863. +----------------------+----------------------+----------------------+
  864. | U4 | integer | Client UDP port. |
  865. +----------------------+----------------------+----------------------+
  866. | U6 | integer | Same as U4, but for |
  867. | | | IPv6. |
  868. +----------------------+----------------------+----------------------+
  869. | SS | integer | Share size in bytes |
  870. +----------------------+----------------------+----------------------+
  871. | SF | integer | Number of shared |
  872. | | | files |
  873. +----------------------+----------------------+----------------------+
  874. | VE | string | Client |
  875. | | | identification, |
  876. | | | version |
  877. | | | (client-specific, a |
  878. | | | short identifier |
  879. | | | then a dotted |
  880. | | | version number is |
  881. | | | recommended) |
  882. +----------------------+----------------------+----------------------+
  883. | US | integer | Maximum upload |
  884. | | | speed, bytes/second |
  885. +----------------------+----------------------+----------------------+
  886. | DS | integer | Maximum download |
  887. | | | speed, bytes/second |
  888. +----------------------+----------------------+----------------------+
  889. | SL | integer | Maximum simultaneous |
  890. | | | upload connections |
  891. | | | (slots) |
  892. +----------------------+----------------------+----------------------+
  893. | AS | integer | Automatic slot |
  894. | | | allocator speed |
  895. | | | limit, bytes/sec. |
  896. | | | The client keeps |
  897. | | | opening slots as |
  898. | | | long as its total |
  899. | | | upload speed doesn’t |
  900. | | | exceed this value. |
  901. +----------------------+----------------------+----------------------+
  902. | AM | integer | Minimum simultaneous |
  903. | | | upload connections |
  904. | | | in automatic slot |
  905. | | | manager mode |
  906. +----------------------+----------------------+----------------------+
  907. | EM | string | E-mail address |
  908. +----------------------+----------------------+----------------------+
  909. | NI | string | Nickname (or hub |
  910. | | | name). The hub must |
  911. | | | ensure that this is |
  912. | | | unique in the hub up |
  913. | | | to case-sensitivity. |
  914. | | | Valid are all |
  915. | | | characters in the |
  916. | | | Unicode character |
  917. | | | set with code point |
  918. | | | above 32, although |
  919. | | | hubs may limit this |
  920. | | | further as they like |
  921. | | | with an appropriate |
  922. | | | error message. |
  923. +----------------------+----------------------+----------------------+
  924. | DE | string | Description. Valid |
  925. | | | are all characters |
  926. | | | in the Unicode |
  927. | | | character set with |
  928. | | | code point equal to |
  929. | | | or greater than 32. |
  930. +----------------------+----------------------+----------------------+
  931. | HN | integer | Hubs where user is a |
  932. | | | normal user and in |
  933. | | | NORMAL state |
  934. +----------------------+----------------------+----------------------+
  935. | HR | integer | Hubs where user is |
  936. | | | registered (had to |
  937. | | | supply password) and |
  938. | | | in NORMAL state |
  939. +----------------------+----------------------+----------------------+
  940. | HO | integer | Hubs where user is |
  941. | | | op and in NORMAL |
  942. | | | state |
  943. +----------------------+----------------------+----------------------+
  944. | TO | string | Token, as received |
  945. | | | in RCM/CTM, when |
  946. | | | establishing a C-C |
  947. | | | connection. |
  948. +----------------------+----------------------+----------------------+
  949. | CT | integer | Client (user) type, |
  950. | | | 1=bot, 2=registered |
  951. | | | user, 4=operator, |
  952. | | | 8=super user, 16=hub |
  953. | | | owner, 32=hub (used |
  954. | | | when the hub sends |
  955. | | | an INF about |
  956. | | | itself). Multiple |
  957. | | | types are specified |
  958. | | | by adding the |
  959. | | | numbers together. |
  960. +----------------------+----------------------+----------------------+
  961. | AW | integer | 1=Away, 2=Extended |
  962. | | | away, not interested |
  963. | | | in hub chat (hubs |
  964. | | | may skip sending |
  965. | | | broadcast type MSG |
  966. | | | commands to clients |
  967. | | | with this flag) |
  968. +----------------------+----------------------+----------------------+
  969. | SU | string | Comma-separated list |
  970. | | | of feature FOURCC’s. |
  971. | | | This notifies other |
  972. | | | clients of extended |
  973. | | | capabilities of the |
  974. | | | connecting client. |
  975. +----------------------+----------------------+----------------------+
  976. | RF | string | URL of referrer (hub |
  977. | | | in case of redirect, |
  978. | | | web page) |
  979. +----------------------+----------------------+----------------------+
  980.  
  981. > **Note**
  982. >
  983. > Normally one would only accept an IP (I4 or I6) that is the same as
  984. > the source IP of the connecting peer. Use caution when accepting
  985. > unknown IPs. Only for trusted users one may allow a different IP or an
  986. > IP from a different domain (IPv4 or IPv6) to be specified. If you fail
  987. > to do this, your hub can be used as a medium for DDoS attacks.
  988.  
  989. When the hub sends an INF about itself, the NI becomes hub name, the VE
  990. the hub version, and DE the hub description.
  991.  
  992. ### MSG {#_msg}
  993.  
  994. MSG text
  995.  
  996. Contexts: F, T
  997.  
  998. States: NORMAL
  999.  
  1000. A chat message. The receiving clients should precede it with "&lt;" nick
  1001. "&gt;", to allow for uniform message displays.
  1002.  
  1003. Flags:
  1004.  
  1005. +-----------------------------------+-----------------------------------+
  1006. | PM&lt;group-SID&gt; | Private message, |
  1007. | | &lt;group-SID&gt; is the SID |
  1008. | | clients must send responses to. |
  1009. | | This field must contain the |
  1010. | | originating SID if this is a |
  1011. | | normal private conversation. |
  1012. +-----------------------------------+-----------------------------------+
  1013. | ME | Speak in third person, 1 = |
  1014. | | message should be displayed as |
  1015. | | /me in IRC ("\*nick text") |
  1016. +-----------------------------------+-----------------------------------+
  1017.  
  1018. ### SCH {#_sch}
  1019.  
  1020. SCH
  1021.  
  1022. Contexts: F, T, C, (U)
  1023.  
  1024. States: NORMAL
  1025.  
  1026. Search. Each parameter is an operator followed by a term. Each term is a
  1027. two-letter code followed by the data to search for. Clients must ignore
  1028. any unknown fields and complete the search request as if they were not
  1029. present, unless no known fields are present in which case the client
  1030. must ignore the search.
  1031.  
  1032. +-----------------------------------+-----------------------------------+
  1033. | AN, NO, EX | String search term, where AN is |
  1034. | | include (and), NO is exclude (and |
  1035. | | not), and EX is extension. Each |
  1036. | | filename (including the path to |
  1037. | | it) should be matched using case |
  1038. | | insensitive substring search as |
  1039. | | follows: match all AN, remove |
  1040. | | those that match any NO, and make |
  1041. | | sure the extension matches at |
  1042. | | least one of the EX (if it is |
  1043. | | present). Extensions must be sent |
  1044. | | without the leading period ('.'). |
  1045. +-----------------------------------+-----------------------------------+
  1046. | LE | Smaller (less) than or equal size |
  1047. | | in bytes |
  1048. +-----------------------------------+-----------------------------------+
  1049. | GE | Larger (greater) than or equal |
  1050. | | size in bytes |
  1051. +-----------------------------------+-----------------------------------+
  1052. | EQ | Exact size in bytes |
  1053. +-----------------------------------+-----------------------------------+
  1054. | TO | Token, string. Used by the client |
  1055. | | to tell one search from the |
  1056. | | other. If present, the responding |
  1057. | | client must copy this field to |
  1058. | | each search result. |
  1059. +-----------------------------------+-----------------------------------+
  1060. | TY | File type, to be chosen from the |
  1061. | | following (none specified = any |
  1062. | | type): 1 = File, 2 = Directory |
  1063. +-----------------------------------+-----------------------------------+
  1064.  
  1065. Searching by UDP is subject to IP spoofing; can thus be used to initiate
  1066. a DoS attack. Clients should only accept incoming UDP searches in a
  1067. trusted environment.
  1068.  
  1069. ### RES {#_res}
  1070.  
  1071. RES
  1072.  
  1073. Contexts: F, T, C, U
  1074.  
  1075. States: NORMAL
  1076.  
  1077. Search result, made up of fields syntactically and structurally similar
  1078. to the INF ones. Clients must provide filename, session hash, size and
  1079. token, but are encouraged to supply additional fields if available.
  1080. Passive results should be limited to 5 and active to 10.
  1081.  
  1082. +-----------------------------------+-----------------------------------+
  1083. | FN | Full filename including path in |
  1084. | | share |
  1085. +-----------------------------------+-----------------------------------+
  1086. | SI | Size, in bytes |
  1087. +-----------------------------------+-----------------------------------+
  1088. | SL | Slots currently available |
  1089. +-----------------------------------+-----------------------------------+
  1090. | TO | Token |
  1091. +-----------------------------------+-----------------------------------+
  1092.  
  1093. ### CTM {#_ctm}
  1094.  
  1095. CTM protocol separator port separator token
  1096.  
  1097. Contexts: F, T
  1098.  
  1099. States: NORMAL
  1100.  
  1101. Connect to me. Used by active clients that want to connect to someone,
  1102. or in response to RCM. Only TCP active clients may send this.
  1103. &lt;token&gt; is a string that identifies the incoming connection
  1104. triggered by this command and must be present in the INF command of the
  1105. connecting client. Implementations should not accept incoming
  1106. connections with a token that was not sent earlier. The server party
  1107. may, but should not, provide the token in its INF. &lt;protocol&gt; is
  1108. an arbitrary string specifying the protocol to connect with; in the case
  1109. of an ADC 1.0 compliant connection attempt, this should be the string
  1110. "ADC/1.0". If &lt;protocol&gt; is supported, a response to RCM must copy
  1111. the &lt;token&gt; and &lt;protocol&gt; fields directly. If a protocol is
  1112. not supported, a DSTA must be sent indicating this.
  1113.  
  1114. ### RCM {#_rcm}
  1115.  
  1116. RCM protocol separator token
  1117.  
  1118. Contexts: F, T
  1119.  
  1120. States: NORMAL
  1121.  
  1122. Reverse CTM. Used by passive clients to request a connection token from
  1123. an active client.
  1124.  
  1125. ### GPA {#_gpa}
  1126.  
  1127. GPA data
  1128.  
  1129. Contexts: F
  1130.  
  1131. States: VERIFY
  1132.  
  1133. Get Password. The data parameter is at least 24 random bytes (base32
  1134. encoded).
  1135.  
  1136. ### PAS {#_pas}
  1137.  
  1138. PAS password
  1139.  
  1140. Contexts: T
  1141.  
  1142. States: VERIFY
  1143.  
  1144. Password. The password (utf-8 encoded bytes), followed by the random
  1145. data (binary), passed through the session hash algorithm then converted
  1146. to base32.
  1147.  
  1148. ### QUI {#_qui}
  1149.  
  1150. QUI sid
  1151.  
  1152. Contexts: F
  1153.  
  1154. States: IDENTIFY, VERIFY, NORMAL
  1155.  
  1156. The client identified by &lt;sid&gt; disconnected from the hub. If the
  1157. SID belongs to the client receiving the QUI, it means that it should
  1158. take action according to the reason (i.e. redirect or not reconnect in
  1159. case of ban). The hub must not send data after the QUI to the client
  1160. being disconnected.
  1161.  
  1162. The following flags may be present:
  1163.  
  1164. +-----------------------------------+-----------------------------------+
  1165. | ID | SID of the initiator of the |
  1166. | | disconnect (for example the one |
  1167. | | that issued a kick). |
  1168. +-----------------------------------+-----------------------------------+
  1169. | TL | Time Left until reconnect is |
  1170. | | allowed, in seconds. -1 = |
  1171. | | forever. |
  1172. +-----------------------------------+-----------------------------------+
  1173. | MS | Message. |
  1174. +-----------------------------------+-----------------------------------+
  1175. | RD | Redirect server URL. |
  1176. +-----------------------------------+-----------------------------------+
  1177. | DI | Any client that has this flag in |
  1178. | | the QUI message should have its |
  1179. | | transfers terminated by other |
  1180. | | clients connected to it, as it is |
  1181. | | unwanted in the system. |
  1182. +-----------------------------------+-----------------------------------+
  1183.  
  1184. ### GET {#_get}
  1185.  
  1186. GET type separator identifier separator start_pos separator bytes
  1187.  
  1188. Contexts: C
  1189.  
  1190. States: NORMAL
  1191.  
  1192. Requests that a certain file or binary data be transmitted.
  1193. &lt;start\_pos&gt; counts 0 as the first byte. &lt;bytes&gt; may be set
  1194. to -1 to indicate that the sending client should fill it in with the
  1195. number of bytes needed to complete the file from &lt;start\_pos&gt;.
  1196. &lt;type&gt; is a \[a-zA-Z0-9\]+ string that specifies the namespace for
  1197. identifier and BASE requires that clients recognize the types "file" and
  1198. "list". Extensions may add to the identifier names as well as add new
  1199. types.
  1200.  
  1201. "file" transfers transfer the file data in binary, starting at
  1202. &lt;start\_pos&gt; and sending &lt;bytes&gt; bytes. Identifier must come
  1203. from the namespace of the current session hash.
  1204.  
  1205. "list" transfers are used for partial file lists and have a directory as
  1206. identifier. &lt;start\_pos&gt; is always 0 and &lt;bytes&gt; contains
  1207. the uncompressed length of the generated XML text in the corresponding
  1208. SND. An optional flag "RE1" means that the client is requesting a
  1209. recursive list and that the sending client should send the directory
  1210. itself and all subdirectories as well. If this is too much, the sending
  1211. client may choose to send only parts. The flag should be taken as a hint
  1212. that the requesting client will be getting the subdirectories as well,
  1213. so they might as well be sent in one go. Identifier must be a directory
  1214. in the unnamed root, ending (and beginning) with "/".
  1215.  
  1216. Note that GET can also be used by extensions for binary transfers
  1217. between hub and client.
  1218.  
  1219. ### GFI {#_gfi}
  1220.  
  1221. GFI type separator identifier
  1222.  
  1223. Contexts: C
  1224.  
  1225. States: NORMAL
  1226.  
  1227. Get File Information. Requests that the other client returns a RES about
  1228. the file as if it had responded to a SCH command. Type and identifier
  1229. are the same as for GET, but the identifier may come from any namespace,
  1230. including the unnamed root.
  1231.  
  1232. ### SND {#_snd}
  1233.  
  1234. SND type separator identifier separator start_pos separator bytes
  1235.  
  1236. Contexts: C
  1237.  
  1238. States: NORMAL
  1239.  
  1240. The sender will transmit until &lt;bytes&gt; bytes of binary data have
  1241. been sent. The parameters correspond to the GET parameters except that
  1242. if &lt;bytes&gt; equals -1 it must be replaced by the number of bytes
  1243. needed to complete the file starting at &lt;start\_pos&gt;.
  1244.  
  1245. Examples {#_examples}
  1246. ========
  1247.  
  1248. Note that examples listed here omit the trailing newline character that
  1249. shall always end a message.
  1250.  
  1251. Client – Hub connection {#_client_hub_connection}
  1252. -----------------------
  1253.  
  1254. +-----------------------------------+-----------------------------------+
  1255. | Client | Hub |
  1256. +===================================+===================================+
  1257. | HSUP ADBASE ADTIGR | |
  1258. +-----------------------------------+-----------------------------------+
  1259. | | ISUP ADBASE ADTIGR … |
  1260. +-----------------------------------+-----------------------------------+
  1261. | | ISID &lt;client-sid&gt; |
  1262. +-----------------------------------+-----------------------------------+
  1263. | | IINF CT32 … |
  1264. +-----------------------------------+-----------------------------------+
  1265. | BINF &lt;my-sid&gt; ID… PD… | |
  1266. +-----------------------------------+-----------------------------------+
  1267. | | IGPA … |
  1268. +-----------------------------------+-----------------------------------+
  1269. | HPAS … | |
  1270. +-----------------------------------+-----------------------------------+
  1271. | | BINF &lt;all clients&gt; |
  1272. +-----------------------------------+-----------------------------------+
  1273. | | BINF &lt;Client-SID&gt; |
  1274. +-----------------------------------+-----------------------------------+
  1275. | … | … |
  1276. +-----------------------------------+-----------------------------------+
  1277.  
  1278. Client – Client connection {#_client_client_connection}
  1279. --------------------------
  1280.  
  1281. +-----------------------------------+-----------------------------------+
  1282. | Client | Server |
  1283. +===================================+===================================+
  1284. | CSUP ADBASE ADTIGR … | |
  1285. +-----------------------------------+-----------------------------------+
  1286. | | CSUP ADBASE ADTIGR … |
  1287. +-----------------------------------+-----------------------------------+
  1288. | CINF IDxxx TO&lt;token&gt; | |
  1289. +-----------------------------------+-----------------------------------+
  1290. | | CINF IDxxx |
  1291. +-----------------------------------+-----------------------------------+
  1292. | | CGET … |
  1293. +-----------------------------------+-----------------------------------+
  1294. | CSND … | |
  1295. +-----------------------------------+-----------------------------------+
  1296. | &lt;data&gt; | |
  1297. +-----------------------------------+-----------------------------------+
  1298.  
  1299. Commands {#_commands}
  1300. --------
  1301.  
  1302. ### STA {#_sta_2}
  1303.  
  1304. +-----------------------------------+-----------------------------------+
  1305. | Example | Description |
  1306. +===================================+===================================+
  1307. | ISTA 211 Hub\\sfull | A STA sent from a hub with the |
  1308. | | severity Fatal (2) and the error |
  1309. | | code Hub full (11). The |
  1310. | | descriptive text afterward is to |
  1311. | | preferably be presented to the |
  1312. | | user. |
  1313. +-----------------------------------+-----------------------------------+
  1314. | CSTA 151 File\\snot\\savailable | A STA is sent in a client to |
  1315. | | client connection, indicating |
  1316. | | that the request for a file |
  1317. | | failed (error code 51), as the |
  1318. | | file was not vailable. The |
  1319. | | severity (Recoverable, 1) |
  1320. | | indicates that an error occured |
  1321. | | but that the connection will |
  1322. | | remain. |
  1323. +-----------------------------------+-----------------------------------+
  1324. | ESTA BBBB CCCC 142 | A STA is sent from one client to |
  1325. | Transfer\\sprotocol\\sunsupported | another client in a hub, routed |
  1326. | TO123456789 PRADC/0.5 | as a E-type message (meaning that |
  1327. | | the sender should receive it as |
  1328. | | well), as a response for not |
  1329. | | supporting transfers of the |
  1330. | | *protocol* kind. The token |
  1331. | | *123456789* is used and the |
  1332. | | protocol is "ADC/0.5" (see the |
  1333. | | command CTM for the version that |
  1334. | | shall be used in this protocol |
  1335. | | version). |
  1336. +-----------------------------------+-----------------------------------+
  1337.  
  1338. ### SUP {#_sup_2}
  1339.  
  1340. +-----------------------------------+-----------------------------------+
  1341. | Example | Description |
  1342. +===================================+===================================+
  1343. | ISUP ADBASE ADTIGR ADBLOM | A SUP sent from a hub indicating |
  1344. | | that the hub has added the |
  1345. | | features BASE, TIGR and BLOM. |
  1346. +-----------------------------------+-----------------------------------+
  1347. | HSUP RMBLOM ADZLIF | A SUP sent from a client to the |
  1348. | | hub indicating that the client |
  1349. | | has added the fature ZLIF and |
  1350. | | removed the feature BLOM. |
  1351. +-----------------------------------+-----------------------------------+
  1352.  
  1353. ### SID {#_sid_2}
  1354.  
  1355. +-----------------------------------+-----------------------------------+
  1356. | Example | Description |
  1357. +===================================+===================================+
  1358. | ISID BBBB | An SID is sent from the hub |
  1359. | | indicating that the client’s SID |
  1360. | | from then on shall be BBBB. |
  1361. +-----------------------------------+-----------------------------------+
  1362.  
  1363. ### INF {#_inf_2}
  1364.  
  1365. +-----------------------------------+-----------------------------------+
  1366. | Example | Description |
  1367. +===================================+===================================+
  1368. | IINF CT32 NIexample\_hub | An INF is sent from the hub |
  1369. | DEThe\\s\\simple\\shub | containing its own information: |
  1370. | | the name is "example\_hub" and |
  1371. | | description "The simple hub". |
  1372. +-----------------------------------+-----------------------------------+
  1373. | BINF BBBB HN0 HR1 HO2 | An INF sent from a client (with |
  1374. | NIsample\_user DEsample\\scontent | the SID BBBB) containing the |
  1375. | SF123456 SS42 I4192.168.0.1 | following information: the name |
  1376. | U46666 | is "sample\_user", the |
  1377. | IDIPJJWEPPPLCA3PF2ZCRRYO4F2ZX2EV2 | description is "sample content", |
  1378. | JMW2KC3I | in three hubs in total (one as |
  1379. | PDIJJJWEPPPLCA33F2ZCR7YO4F6ZXWE4N | registered and two as operator), |
  1380. | J3WQ3C3I | with a total share size of 42 |
  1381. | | bytes (with 123456 files) etc. |
  1382. +-----------------------------------+-----------------------------------+
  1383. | CINF | An INF is sent in a client to |
  1384. | IPJJWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JM | client connection indicating the |
  1385. | W2KC3I | CID and token. |
  1386. | TO123456789 | |
  1387. +-----------------------------------+-----------------------------------+
  1388.  
  1389. ### MSG {#_msg_2}
  1390.  
  1391. +-----------------------------------+-----------------------------------+
  1392. | Example | Description |
  1393. +===================================+===================================+
  1394. | IMSG | A MSG that is sent from the hub |
  1395. | There\\sare\\s42\\susers\\sonline | with the message "There are 42 |
  1396. | | users online". |
  1397. +-----------------------------------+-----------------------------------+
  1398. | BMSG BBBB likes\\scats ME1 | A MSG that is sent from a client |
  1399. | | (with SID BBBB), spoken in third |
  1400. | | person with the message "likes |
  1401. | | cats". This will appear like (or |
  1402. | | something similar) "john likes |
  1403. | | cats" (assuming that the user |
  1404. | | with BBBB has the name john). |
  1405. +-----------------------------------+-----------------------------------+
  1406. | DMSG CCCC BBBB I\\sprefer\\sdogs | A MSG is sent from a client to |
  1407. | PMCCCC | another client, spoken as a |
  1408. | | "private message", with the |
  1409. | | message "I prefer dogs". |
  1410. +-----------------------------------+-----------------------------------+
  1411.  
  1412. ### SCH {#_sch_2}
  1413.  
  1414. +-----------------------------------+-----------------------------------+
  1415. | Example | Description |
  1416. +===================================+===================================+
  1417. | BSCH BBBB ANubuntu ANlinux | A SCH that is sent from a client |
  1418. | NOgentoo EXISO EXIMG TO123456789 | where the search terms "ubuntu" |
  1419. | TY1 | and "linux" should be in the file |
  1420. | | (TY1) name, excluding files that |
  1421. | | have "gentoo" in them. The |
  1422. | | extension of the file should be |
  1423. | | ISO or IMG. The token "123456789" |
  1424. | | is used. |
  1425. +-----------------------------------+-----------------------------------+
  1426. | BSCH BBBB ANubuntu LE4294967296 | A SCH that is sent from a client |
  1427. | TO123456789 | where the search term "ubuntu" |
  1428. | | should be in the file (TY1) name. |
  1429. | | The token "123456789" is used. |
  1430. | | The file must be less than 4 GiB |
  1431. | | in size (4294967296 bytes). |
  1432. +-----------------------------------+-----------------------------------+
  1433. | FSCH BBBB +TCP4 ANubuntu | A SCH that is sent from a client |
  1434. | TO123456789 | where the search term "ubuntu" |
  1435. | | should be in the file (TY1) name. |
  1436. | | The token "123456789" is used. |
  1437. | | The hub should only route the SCH |
  1438. | | to clients that support the |
  1439. | | feature TCP4. |
  1440. +-----------------------------------+-----------------------------------+
  1441.  
  1442. ### RES {#_res_2}
  1443.  
  1444. +-----------------------------------+-----------------------------------+
  1445. | Example | Description |
  1446. +===================================+===================================+
  1447. | DRES CCCC BBBB | A RES that is sent from a client |
  1448. | FN/share/linux/ubuntu.iso SI42 | (through the hub) indicating a |
  1449. | SL1 TO123456789 | response with the file name |
  1450. | TRIPPPWEPPPLCA3PF2ZCRRYO4F2ZX2EV2 | "ubuntu.iso" (and its path within |
  1451. | JMW2KCII | the share), where the file sise |
  1452. | | is 42 bytes. The token |
  1453. | | "123456789" is used. The TR field |
  1454. | | indicate the hash of the file |
  1455. | | (see the TIGR extension). |
  1456. +-----------------------------------+-----------------------------------+
  1457. | URES | A RES that is sent from a client |
  1458. | IPJJWEPPPLCA3PF2ZCRRYO4F2ZX2EV2JM | (via UDP) indicating a response |
  1459. | W2KCII | with the file name "ubuntu.iso" |
  1460. | TRIPPPWEPPPLCA3PF2ZCRRYO4F2ZX2EV2 | (and its path within the share), |
  1461. | JMW2KCII | where the file sise is 42 bytes. |
  1462. | FN/share/linux/ubuntu.iso SI42 | The token "123456789" is used. |
  1463. | TO123456789 | The TR field indicate the hash of |
  1464. | | the file (see the TIGR |
  1465. | | extension). |
  1466. +-----------------------------------+-----------------------------------+
  1467. | CRES FN/share/linux/ubuntu.iso | A RES that is sent from a client |
  1468. | SI42 | indicating a response with the |
  1469. | | file name "ubuntu.iso" (and its |
  1470. | | path within the share), where the |
  1471. | | file sise is 42 bytes. |
  1472. +-----------------------------------+-----------------------------------+
  1473.  
  1474. ### CTM {#_ctm_2}
  1475.  
  1476. +-----------------------------------+-----------------------------------+
  1477. | Example | Description |
  1478. +===================================+===================================+
  1479. | DCTM BBBB CCCC ADC/1.0 6666 | A CTM that is sent from a client |
  1480. | 123456789 | to another client indicating that |
  1481. | | it wants to have a client to |
  1482. | | client connection. The protocol |
  1483. | | "ADC/1.0" is used. The port 6666 |
  1484. | | is used. The token is 123456789. |
  1485. | | The hub should only send this to |
  1486. | | the target user (with SID CCCC). |
  1487. +-----------------------------------+-----------------------------------+
  1488. | ECTM BBBB CCCC ADC/0.5 6666 | A CTM that is sent from a client |
  1489. | 123456789 | to another client indicating that |
  1490. | | it wants to have a client to |
  1491. | | client connection. The |
  1492. | | (fictional) protocol "ADC/1.0" is |
  1493. | | used. The port 6666 is used. The |
  1494. | | token is 123456789. The hub |
  1495. | | should send this to the target |
  1496. | | user (with SID CCCC) and to the |
  1497. | | originating party (with SID |
  1498. | | BBBB). |
  1499. +-----------------------------------+-----------------------------------+
  1500.  
  1501. ### RCM {#_rcm_2}
  1502.  
  1503. +-----------------------------------+-----------------------------------+
  1504. | Example | Description |
  1505. +===================================+===================================+
  1506. | DRCM BBBB CCCC ADC/1.0 123456789 | A RCM that is sent from a client |
  1507. | | to another client indicating that |
  1508. | | it wants to have a client to |
  1509. | | client connection. The protocol |
  1510. | | "ADC/1.0" is used. TThe token is |
  1511. | | 123456789. The hub should only |
  1512. | | send this to the target user |
  1513. | | (with SID CCCC). |
  1514. +-----------------------------------+-----------------------------------+
  1515. | ERCM BBBB CCCC ADC/0.5 123456789 | A RCM that is sent from a client |
  1516. | | to another client indicating that |
  1517. | | it wants to have a client to |
  1518. | | client connection. The |
  1519. | | (fictional) protocol "ADC/0.5" is |
  1520. | | used. TThe token is 123456789. |
  1521. | | The hub should send this to the |
  1522. | | target user (with SID CCCC) and |
  1523. | | to the originating party (with |
  1524. | | SID BBBB). |
  1525. +-----------------------------------+-----------------------------------+
  1526.  
  1527. ### GPA {#_gpa_2}
  1528.  
  1529. +-----------------------------------+-----------------------------------+
  1530. | Example | Description |
  1531. +===================================+===================================+
  1532. | IGPA JJWEPPPLCA3PF2ZCRRYO3333 | A GPA that is sent from the hub |
  1533. | | indicating the password-response |
  1534. | | sequence with the random data |
  1535. | | JJWEPPPLCA3PF2ZCRRYO3333. |
  1536. +-----------------------------------+-----------------------------------+
  1537.  
  1538. ### PAS {#_pas_2}
  1539.  
  1540. +-----------------------------------+-----------------------------------+
  1541. | Example | Description |
  1542. +===================================+===================================+
  1543. | HPAS YO4F2ZX2EV2JMW2KCIIYYYYY | A PAS that is sent from the |
  1544. | | client where the password and |
  1545. | | random data is hashed. |
  1546. +-----------------------------------+-----------------------------------+
  1547.  
  1548. ### QUI {#_qui_2}
  1549.  
  1550. +-----------------------------------+-----------------------------------+
  1551. | Example | Description |
  1552. +===================================+===================================+
  1553. | IQUI BBBB | A QUI that is sent from the hub |
  1554. | | indicating that the client BBBB |
  1555. | | has disconnected. |
  1556. +-----------------------------------+-----------------------------------+
  1557. | IQUI BBBB IDCCCC | A QUI that is sent from the hub |
  1558. | MSCats\\sare\\shorrible DI1 TL-1 | indicating that the client BBBB |
  1559. | | has disconnected. The originator |
  1560. | | of the action is the client with |
  1561. | | the SID CCCC. The message "Cats |
  1562. | | are horrible" is included. All |
  1563. | | clients should terminate their |
  1564. | | connections with the client BBBB |
  1565. | | (DI1). The client should never |
  1566. | | attempt to reconnect (TL-1). |
  1567. +-----------------------------------+-----------------------------------+
  1568.  
  1569. ### GET {#_get_2}
  1570.  
  1571. +-----------------------------------+-----------------------------------+
  1572. | Example | Description |
  1573. +===================================+===================================+
  1574. | CGET file | A GET that is sent from a client |
  1575. | TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2E | as a request for a file with the |
  1576. | V2JMW2KCII | identifier |
  1577. | 0 -1 | TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2E |
  1578. | | V2JMW2KCII |
  1579. | | (see TIGR extension). The sending |
  1580. | | client should send the entire |
  1581. | | file. |
  1582. +-----------------------------------+-----------------------------------+
  1583. | CGET list /share/ 0 -1 RE1 | A GET that is sent from a client |
  1584. | | as a request for a directory with |
  1585. | | the identifier /share/. The |
  1586. | | sending client should send the |
  1587. | | directory and its subdirectories. |
  1588. +-----------------------------------+-----------------------------------+
  1589. | CGET file | A GET that is sent from a client |
  1590. | TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2E | as a request for a file with the |
  1591. | V2JMW2KCII | identifier |
  1592. | 6666 3333 | TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2E |
  1593. | | V2JMW2KCII |
  1594. | | (see TIGR extension). The sending |
  1595. | | client should send the next 3333 |
  1596. | | bytes, starting at byte position |
  1597. | | 6666. |
  1598. +-----------------------------------+-----------------------------------+
  1599.  
  1600. ### GFI {#_gfi_2}
  1601.  
  1602. +-----------------------------------+-----------------------------------+
  1603. | Example | Description |
  1604. +===================================+===================================+
  1605. | CGFI file | A GFI that is sent from a client |
  1606. | TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2E | as a request for file information |
  1607. | V2JMW2KCII | for a file with the identifier |
  1608. | | TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2E |
  1609. | | V2JMW2KCII |
  1610. | | (see TIGR extension). |
  1611. +-----------------------------------+-----------------------------------+
  1612. | CGFI list /share/ | A GFI that is sent from a client |
  1613. | | as a request for directory |
  1614. | | information with the identifier |
  1615. | | /share/. |
  1616. +-----------------------------------+-----------------------------------+
  1617.  
  1618. ### SND {#_snd_2}
  1619.  
  1620. +-----------------------------------+-----------------------------------+
  1621. | Example | Description |
  1622. +===================================+===================================+
  1623. | CSND file | A SND that is sent from a client |
  1624. | TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2E | prior to streaming data for the |
  1625. | V2JMW2KCII | file with the identifier |
  1626. | 0 9999 | TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2E |
  1627. | | V2JMW2KCII |
  1628. | | (see TIGR extension). The sending |
  1629. | | client indicates that it will |
  1630. | | send 9999 bytes and start |
  1631. | | streaming at the byte position 0 |
  1632. | | (the beginning of the file). |
  1633. +-----------------------------------+-----------------------------------+
  1634. | CSND list /share/ 0 66 | A SND that is sent from a client |
  1635. | | prior to streaming data for the |
  1636. | | directory with the identifier |
  1637. | | /share/. The sending client |
  1638. | | indicates that it will send 66 |
  1639. | | bytes. |
  1640. +-----------------------------------+-----------------------------------+
  1641. | CSND file | A SND that is sent from a client |
  1642. | TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2E | prior to streaming data for the |
  1643. | V2JMW2KCII | file with the identifier |
  1644. | 6666 3333 | TTH/IPPPWEPPPLCA3PF2ZCRRYO4F2ZX2E |
  1645. | | V2JMW2KCII |
  1646. | | (see TIGR extension). The sending |
  1647. | | client indicates that it will |
  1648. | | send 3333 bytes and start |
  1649. | | streaming at the byte position |
  1650. | | 6666. |
  1651. +-----------------------------------+-----------------------------------+
  1652.  
  1653. Terminology {#_terminology}
  1654. ===========
  1655.  
  1656. +-----------------------------------+-----------------------------------+
  1657. | Term | Description |
  1658. +===================================+===================================+
  1659. | FOURCC | Four character code. This may be |
  1660. | | the message type followed by the |
  1661. | | command, e.g. "ISTA", "BMSG" etc. |
  1662. | | This may also be the name of a |
  1663. | | feature (BASE, TIGR etc). Any |
  1664. | | four character identification. |
  1665. +-----------------------------------+-----------------------------------+
  1666. | Server | The hub is the *server* in a |
  1667. | | client - hub context. The client |
  1668. | | receiving the incoming connection |
  1669. | | is the *server* in a client - |
  1670. | | client context. |
  1671. +-----------------------------------+-----------------------------------+
  1672. | Base32 | An encoding used by the protocol, |
  1673. | | see RFC 4648 for more information |
  1674. | | about Base32. Note that the |
  1675. | | Base32 implementation in ADC is |
  1676. | | never padded. |
  1677. +-----------------------------------+-----------------------------------+
  1678. | Context | When a command states a context, |
  1679. | | e.g. "T" (To hub), it defines an |
  1680. | | expectance on the flow of |
  1681. | | traffic. A context may refer to |
  1682. | | one or multiple message types. |
  1683. | | For example, for the context *T*, |
  1684. | | the message types "B", "C", "D", |
  1685. | | "E", "F" and "H" are valid. Note |
  1686. | | that the context is not a |
  1687. | | restriction in any way, |
  1688. | | implementations may further |
  1689. | | extend a command’s expected |
  1690. | | contexts. |
  1691. +-----------------------------------+-----------------------------------+
  1692.  
  1693. Standard Extensions {#_standard_extensions}
  1694. ===================
  1695.  
  1696. Apart from supporting BASE, clients may opt to implement one or more of
  1697. the following standard extensions. To be considered for addition, an
  1698. extension must be well documented and must be implemented and tested in
  1699. the real world.
  1700.  
  1701. While in development, extensions are tracked here:
  1702. <http://adc.sourceforge.net/wiki/index.php/Extensions>
  1703.  
  1704. Once they have been tried and accepted, they’re moved to the official
  1705. extensions document that accompanies this one.
Add Comment
Please, Sign In to add comment
Public Pastes
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy.  OK, I Understand
Not a member of Pastebin yet?
Sign Up, it unlocks many cool features!