Menu
▾
▴
[Dcplusplus-commit] SF.net SVN: adc:[18] trunk/ADC-EXT.txt
|
From: <ul...@us...> - 2010-07-12 09:53:42
|
Revision: 18
http://adc.svn.sourceforge.net/adc/?rev=18&view=rev
Author: ullner
Date: 2010-07-12 09:53:35 +0000 (Mon, 12 Jul 2010)
Log Message:
-----------
Add basic NATT (will get a slight update in its text later on).
Removed old style tables.
Made proper hyper links in the document.
General cleanup in terms of document structure and style.
Modified Paths:
--------------
trunk/ADC-EXT.txt
Modified: trunk/ADC-EXT.txt
===================================================================
--- trunk/ADC-EXT.txt 2010-07-11 21:42:47 UTC (rev 17)
+++ trunk/ADC-EXT.txt 2010-07-12 09:53:35 UTC (rev 18)
@@ -4,7 +4,7 @@
== Abstract
These are the official extensions to ADC. This document is based on the
-information contained in the ADC wiki - spefications from there are moved here
+information contained in the ADC wiki and ADC forum - spefications from there are moved here
when they are mature and stable enough.
== Version history
@@ -26,11 +26,12 @@
* Added UCMD extension
=== Version 1.0.3
-* Removed 'optional' keywords from UCMD
+* Removed optional keywords from UCMD
* Added BLOM extension
=== Version 1.0.4 UNRELEASED
-* Added magnet link extension to UCMD
+* Added magnet link extension to 'UCMD'
+* Added NAT traversal extension 'NATT'
== Extensions
@@ -79,11 +80,10 @@
In SCH and GFI, the following attributes are added:
-[separator="|"]
-``_
-TR | Tiger tree Hash root, encoded with base32.
-TD | Tree depth, index of the highest level of tree data available, root-only = 0, first level (2 leaves) = 1, second level = 2, etc...
-___
+|=====
+|TR |Tiger tree Hash root, encoded with base32.
+|TD |Tree depth, index of the highest level of tree data available, root-only = 0, first level (2 leaves) = 1, second level = 2, etc...
+|=====
=== BZIP - File list compressed with bzip2
This extension adds a special file "files.xml.bz2" in the unnamed root of the
@@ -112,8 +112,6 @@
uncompressed bytes to be transferred.
=== PING - Pinger extension
-Added 2008-03-14, based on ADC 1.0
-
This extension can be supported by both clients and hubs, and when present, if hub
supports it, it must send additional information to the client ( otherwise normal
base client).
@@ -130,33 +128,32 @@
normal INF along with the following added fields ( none mandatory, if not present,
it means hub has no restrictions in that matter, or non existent):
-[separator="|"]
-```_
-Code | Type | Description
-___
-HH | string | Hub Host address ( DNS or IP )
-WS | url | Hub Website
-NE | string | Hub Network
-OW | string | Hub Owner name
-UC | integer | Current User count
-SS | integer | Total share size
-SF | integer | Total files shared
-MS | integer | Minimum share required to enter hub ( bytes )
-XS | integer | Maximum share for entering hub ( bytes )
-ML | integer | Minimum slots required to enter hub
-XL | integer | Maximum slots for entering hub
-MU | integer | Minimum hubs connected where clients can be users
-MR | integer | Minimum hubs connected where client can be registered
-MO | integer | Minimum hubs connected where client can be operators
-XU | integer | Maximum hubs connected where clients can be users
-XR | integer | Maximum hubs connected where client can be registered
-XO | integer | Maximum hubs connected where client can be operators
-MC | integer | Maximum possible clients ( users ) who can connect
-UP | integer | Hub uptime (seconds)
-NI | string | Hub name (from BASE)
-DE | string | Hub description (from BASE)
-VE | string | Hub software version (from BASE)
-___
+[options="header"]
+|=====
+|Code | Type | Description
+|HH |string |Hub Host address ( DNS or IP )
+|WS |url |Hub Website
+|NE |string |Hub Network
+|OW |string |Hub Owner name
+|UC |integer |Current User count
+|SS |integer |Total share size
+|SF |integer |Total files shared
+|MS |integer |Minimum share required to enter hub ( bytes )
+|XS |integer |Maximum share for entering hub ( bytes )
+|ML |integer |Minimum slots required to enter hub
+|XL |integer |Maximum slots for entering hub
+|MU |integer |Minimum hubs connected where clients can be users
+|MR |integer |Minimum hubs connected where client can be registered
+|MO |integer |Minimum hubs connected where client can be operators
+|XU |integer |Maximum hubs connected where clients can be users
+|XR |integer |Maximum hubs connected where client can be registered
+|XO |integer |Maximum hubs connected where client can be operators
+|MC |integer |Maximum possible clients ( users ) who can connect
+|UP |integer |Hub uptime (seconds)
+|NI |string |Hub name (from BASE)
+|DE |string |Hub description (from BASE)
+VE |string |Hub software version (from BASE)
+|=====
The hub must continue to send the user list as for a normal user (move to
NORMAL state). The pinger may decide to go through or disconnect (eg. if it
@@ -196,24 +193,27 @@
The idea behind this extension is to generate a public hublist from the users favorite hublist. Implementations should separate between public and private hubs in the favorite hublist of an user, in order not to distribute private hubs where one can not connect to anyway.
==== GFA
+ GFA
Contexts: T, C
Asks all users within the same hub with the correct feature to send all publicly available hubs, in their favorite hub list to the requesting client.
==== RFA
+ RFA
Contexts: C
Response of a client.
-HA | Hub address
+|=====
+|HA |Hub address
+|LG |Last succesfull login time ( number of seconds since the epoch (1970), (UTC) )
+|=====
-LG | Last succesfull login time ( number of seconds since the epoch (1970), (UTC) )
-
All INF fields from BASE are inherited. All INF fields from PING extension are inherited.
-=== UCMD
+=== UCMD - User commands
CMD name
@@ -225,14 +225,13 @@
Name uniquely (per hub) identifies a particular user command. The name may contain "/" to indicate a logical structure on the viewing client, where each "/" introduces a new submenu level. Other than name, the command also has a number of flags that further detail what to do with it.
-[separator="|"]
-``_
-RM | 1 = Remove Command
-CT | Message Category, 1 = Hub command, client parameters only, 2 = User list command, client and user parameters, 4 = Search result command, client, user and file parameters, 8 = File list command, client, user and file parameters. Multiple types are specified by adding the numbers together.
-TT | The full text to be sent to hub, including FOURCC, parameters and keywords.
-CO | 1 = Constrained, when sending this command on multiple users (for example in search results), constrain it to once per CID only
-SP | 1 = Insert separator instead of command name (name must still be present to uniquely identify the command).
-___
+|=====
+|RM |1 = Remove Command
+|CT |Message Category, 1 = Hub command, client parameters only, 2 = User list command, client and user parameters, 4 = Search result command, client, user and file parameters, 8 = File list command, client, user and file parameters. Multiple types are specified by adding the numbers together.
+|TT |The full text to be sent to hub, including FOURCC, parameters and keywords.
+|CO |1 = Constrained, when sending this command on multiple users (for example in search results), constrain it to once per CID only
+|SP |1 = Insert separator instead of command name (name must still be present to uniquely identify the command).
+|=====
==== Keywords
Keywords are specified using "%[keyword]". Unknown keywords must be replaced by the empty string. Additionally, all %-substitutions of the C function "strftime" must be supported.
@@ -240,46 +239,41 @@
The following tables specify the keywords that must be supported.
Client parameters
-[separator="|"]
-``_
-myCID | Client CID
-mySID | ClientSID
-myXX | One for each flag on that particular hub; for example, myI4 and myNI
-___
+|=====
+|myCID |Client CID
+|mySID |ClientSID
+|myXX |One for each flag on that particular hub; for example, myI4 and myNI
+|=====
User parameters
-[separator="|"]
-``_
-userCID | User CID
-userSID | User SID
-userXX | One for each flag on the user sent; for example, userI4 and userNI
-line:info | Prompts the user for input where 'info' is the displayed text description for the user input
-___
+|=====
+|userCID |User CID
+|userSID |User SID
+|userXX |One for each flag on the user sent; for example, userI4 and userNI
+|line:info |Prompts the user for input where 'info' is the displayed text description for the user input
+|=====
File parameters
-[separator="|"]
-``_
-fileXX | One for each flag contained within a search result or file list entry (see RES)
-fileMN | Specify magnet link. Magnet links <http://en.wikipedia.org/wiki/Magnet_link> are used to reference files across networks and applications. Clients may ignore parameters it does not understand, but are free to pass on the parameters to other programs.
-___
+|=====
+|fileXX |One for each flag contained within a search result or file list entry (see RES)
+|fileMN |Specify magnet link. http://en.wikipedia.org/wiki/Magnet_link[Magnet links] are used to reference files across networks and applications. Clients may ignore parameters it does not understand, but are free to pass on the parameters to other programs.
+|=====
Hub parameters
-[separator="|"]
-``_
-hubXX | One for each flag of the hub; for example, hubNI and hubVE
-___
+|=====
+|hubXX |One for each flag of the hub; for example, hubNI and hubVE
+|=====
==== Example
-`_
-ICMD ADCH++/Hub{backslash}smanagement/Register{backslash}snick TTHMSG{backslash}s+regnick{backslash}s%[userNI]{backslash}s%[line:Password{backslash}s(leave{backslash}sempty{backslash}sto{backslash}sun-reg)]{backslash}s%[line:Level{backslash}s(facultative;{backslash}sdefaults{backslash}sto{backslash}syour{backslash}sown{backslash}slevel{backslash}sminus{backslash}sone)]{backslash}n CT2
-ICMD ADCH++/Hub{backslash}smanagement/Reload{backslash}sbans TTHMSG{backslash}s+loadbans{backslash}n CT3
-ICMD ADCH++/Hub{backslash}smanagement/Reload{backslash}sscripts TTHMSG{backslash}s+reload{backslash}n CT3
-ICMD ADCH++/Info TTHMSG{backslash}s+info{backslash}s%[userNI]{backslash}n CT2
-ICMD ADCH++/Info TTHMSG{backslash}s+info{backslash}n CT1
-___
-
+|=====
+|ICMD ADCH++/Hub\smanagement/Register\snick TTHMSG\s+regnick\s%[userNI]\s%[line:Password\s(leave\sempty\sto\sun-reg)]\s%[line:Level\s(facultative;\sdefaults\sto\syour\sown\slevel\sminus\sone)]\n CT2
+|ICMD ADCH++/Hub\smanagement/Reload\sbans TTHMSG\s+loadbans\n CT3
+|ICMD ADCH++/Hub\smanagement/Reload\sscripts TTHMSG\s+reload\n CT3
+|ICMD ADCH++/Info TTHMSG\s+info\s%[userNI]\n CT2
+|ICMD ADCH++/Info TTHMSG\s+info\n CT1
+|=====
-=== BLOM
+=== BLOM- Bloom filter
Bloom filters allow the hub to filter certain searches using bitmap that represents the hashes of the files in the users share. BLOM is an extension that allows hub software to create a map (bloom filter) of the shared files on the hub, but with minimal effort, e.g. the hub doesn't keep a list of files, but a filter that never produces false negatives but only possible false positives. This can potentially save bandwidth and effort on the client side. When the user updates the share, the client must send an INF containing the flag SF. The hub may at any time request that the client sends an updated version of its bloom filter by sending a GET command to the client. The client will then respond using SND and send the bloom filter binary data.
@@ -348,6 +342,45 @@
===== Tiger
For TTH roots, b is 192 and a reasonable value for h is 24, giving a maximum k = 8 which means that m = 8 * n / ln 2 ≈ 11.5 * n. The required bandwidth then becomes 11.5 * n / 8 bytes, so approximately 1.44 bytes per file in the users share. For 20000 files, m should then be 230016 (taking into account the modulo 64 requirement), giving a p = 0.004, in other words ~99.6% of all searches that don't match a users share would not be sent, saving valuable upload bandwidth for the hub. The client calculates i valid positions, if x is an array of bytes containing the hash of the file, on a little-endian machine, by doing pos = x[0+i*h/8] | (x[1+i*h/8] << 8) | (x[2+i*h/8] << 16) for i = [0;k). This is of course a special case where h % 8 = 0, the actual algorithm has to take into consideration values for h where the integer crosses byte boundaries.
-For test vectors, see the ADC wiki talk page; http://www.adcportal.com/wiki/index.php/Talk:BLOM
+For test vectors, see the http://www.adcportal.com/wiki/index.php/Talk:BLOM[ADC wiki talk page].
+=== NATT - NAT traversal
+NAT traversal allow two passive clients to connect to each other. For more information about NAT traversal, see https://dcpp.wordpress.com/2010/02/13/passive-mode-c-c-connections-and-nat-traversal[Passive Mode C-C Connections and NAT Traversal].
+
+If a client does not support TCP4 or TCP6, it will send an RCM to the client it is trying to connect to. If the other client also doesn't support TCP4 (or TCP6 correspondingly), NAT traversal may instead be used. The feature should be signalled in SUP as NATT.
+
+Do note that the hub must forward I4 or I6 for respective clients' INF.
+
+==== BASE RCM updates
+When receiving an RCM and the client does not support TCP4 or TCP6, and if NAT-T is supported in the remote client, a NAT command should be sent repeating the protocol and token. The port shall be the outbound port to the connected hub.
+
+==== NAT
+ NAT protocol port token
+
+Contexts: T
+
+States: NORMAL
+
+Upon receiving this, try and connect to the specified port. An RNT command should be sent repeating the protocol and token. The port shall be the outbound port to the connected hub. Upon receiving this, try and connect to the specified port.
+
+==== RNT
+ RNT protocol port token
+
+Contexts: T
+
+States: NORMAL
+
+Upon receiving this, try and connect to the specified port.
+
+==== Example
+Client A is connected to hub A with the outbound port 1000 and client B is connected to hub A with the outbound port 2000. Client A has the SID AAAA and client B has the SID BBBB.
+
+----
+Client A: DRCM AAAA BBBB ADC/1.0 foobar
+Client B: DNAT BBBB AAAA ADC/1.0 2000 foobar
+<Client A connects to client B's IP address and port 2000>
+Client A: DRNT AAAA BBBB ADC/1.0 1000 foobar
+<Client B connects to client A's IP address and port 1000>
+----
+
// vim: set syntax=asciidoc:
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
