Gnutella2 - User contributions [en]

QH2

2014-03-12T08:00:53Z

Ram: /* /QH2/G1 - Gnutella Relaying */ Documented this new extension that will be at least supported by gtk-gnutella

{{Packets}}

= /QH2 - Query Hit =

The /QH2 Gnutella2 query hit packet contains one or more search result descriptors,
along with information about the node generating the result set. A single node may
generate several /QH2 packets in response to a /[[Q2]] query. Like all Gnutella2
packets, the /QH2 packet is highly extensible.

== Sending ==

Send a /QH2 packet when processing a /[[Q2]] query packet reveals one or more
matching objects. Query hits can be returned directly to the /Q2/UDP return address
in the query, or routed back along the delivery chain. Firewalled leaf nodes are
advised to return /QH2 packets to their connected hub for dispatch, as the hub will
be able to make a reliable delivery.

== Receiving ==

Upon receiving a /QH2 query hit packet, check the query GUID against locally
initiated queries. If it originated elsewhere, increment the route-back hop counter
and forward it to the most appropriate link or UDP endpoint. If it matches a locally
generated query, process the search results.

== Payload ==

A single byte representing the hop count, followed by a 16 byte GUID identifying the
search that produced these results.

== Children ==

This packet has many child packet types defined at the current time:

* FW - Firewalled Servent
* H - Hit Descriptor
* HG - Hit Group Descriptor
* GU - Node GUID
* NA - Node Address
* NH - Neighbouring Hub
* V - Vendor Code
* MD - Unified Metadata Block
* UPRO - User Profile
* BUP - Browse User Profile Tag
* PCH - Peer Chat Tag
* HN - DNS Host Name of Servent (e.g. "g2.example.com")
* TLS - TLS Support
* BH - Browsable Host
* G1 - Synthetized /QH2 message from Gnutella Query Hit

== /QH2/FW - Firewalled Servent ==

Specifies that the sending node is ''firewalled'' and cannot accept incoming connections.

=== Sending ===

This child is sent only when the servent issuing the hit is firewalled.

=== Payload ===

There is no payload defined.

=== Children ===

This packet has no known children at the current time.

== /QH2/GU - Node GUID ==

Specifies the GUID of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The GUID of the sending node.

=== Children ===

This packet has no known children at the current time.

== /QH2/NA - Node Address ==

Specifies the node / network address of the sending node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

The node / network address of the sending node. See datatypes for more
information.

=== Children ===

This packet has no known children at the current time.

== /QH2/NH - Neighbouring Hub ==

Lists a hub to which the sending node (a leaf) is connected. This provides a contact
point for routing communications to a possibly firewalled leaf node.

=== Sending ===

This child is optional, and may appear more than once.

=== Payload ===

The node / network address of a hub to which the sending node is connected.

=== Children ===

This packet has no known children at the current time.

== /QH2/V - Vendor Code ==

Identifies the software operating the sending node.

=== Sending ===

This child is optional.

=== Payload ===

A four character vendor code.

=== Children ===

This packet has no known children at the current time.

== /QH2/BUP - Browse User Profile Tag ==

Indicates that the sending node supports browsing the local user profile.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/PCH - Peer Chat Tag ==

Indicates that the sending node supports person to person private message chat.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/HG - Hit Group Descriptor ==

Describes a group of search results.

=== Sending ===

This child is optional and may appear more than once.

=== Payload ===

A single byte, the group ID number.

=== Children ===

This packet has one child packet type currently defined:

* SS - Server State

=== /QH2/HG/SS - Server State ===

Provides a status snapshot of the upload server that applies to search results in the
current hit group.

==== Sending ====

Add this child to the hit group descriptor to provide server state information.

==== Receiving ====

Use this information when interpreting hits linked with this hit group.

==== Payload ====

* A 16-bit integer : the current queue length including any active transfers (number waiting plus number transferring)
* An 8-bit integer : the maximum number of concurrent transfers (capacity)
* A 32-bit integer : the speed in kilobits per second for uploads on this server module

==== Children ====

This packet has no known children at the current time.

== /QH2/H - Hit Descriptor ==

Describes a single object which matched the original query.

=== Sending ===

Send a /QH2/H child for each matching object to be included in this /QH2 packet.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has many child packet types defined at the current time, and is often
extended:

* URN - Universal Resource Name
* URL - Universal Resource Location
* DN - Descriptive Name
* MD - Metadata
* SZ - Object Size
* G - Group Identifier
* ID - Object Identifier
* CSC - Cached Source Count
* PART - Partial Availability Marker
* COM - User Comment
* PVU - Preview URL
* ALT - Alternate Locations
* CT - Creation time

=== /QH2/H/URN - Universal Resource Name ===

Specifies a universal resource name which can be used to identify the object.

==== Sending ====

At least one instance of this child is required. Multiple instances are optional.

==== Payload ====

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* '''bitprint''' or '''bp''' - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* '''sha1''' - 20 bytes of SHA1
* '''tree:tiger/''' or '''ttr''' - 24 bytes of tiger-tree root
* '''md5''' - 16 bytes of MD5
* '''ed2k''' - 16 bytes of compound MD4 (ed2k style root hash)

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/URL - Universal Resource Location ===

This child specifies a location where the object being described can be acquired.

==== Sending ====

This child should be sent if it was requested and a URL is available.

==== Receiving ====

If a /QH2/H/URL child was requested but is not present, the sending node may not
have the object. It is valid to advertise information about objects that are not
available.

==== Payload ====

Empty, or a string which represents an absolute URL.

If a URL is provided, that URL should be considered to point to an instance of the
object being described.

If the payload is empty, the sender is indicating that it has the object available
locally. It can be retrieved with an HTTP request using the "uri-res" resolver.

==== Children ====

This packet has no known children at the current time.

=== QH2/H/DN - Descriptive Name (Generic) Criteria ===

The descriptive name for the object, and the object's size.

==== Sending ====

This child should be sent if it was requested and is available.

==== Payload ====

A 32-bit integer indicating the object's size, followed by a string describing it. If a
/QH2/H/SZ child is present, the 32-bit size prefix is omitted here (allowing a larger
64 bit file size).

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/MD - Metadata ===

Provides metadata describing the object.

==== Sending ====

This chid should be sent if it was requested and is available.

==== Payload ====

A string containing XML. The xml header is optional. Standard plural/singular
Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/SZ - Object Size ===

Specifies the size of the object.

==== Sending ====

This child should be sent if DN was requested, and if the size is not to be packed into
the /QH2/H/DN child.

==== Payload ====

A 32-bit or 64-bit integer representing the object size.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/G - Group Identifier ===

Indicates which hit group (/QH2/HG) this hit belongs to. If this child is not present,
the hit belongs to group zero.

==== Sending ====

Send this child if this hit belongs to a hit group other than group zero.

==== Receiving ====

If this child is present, the hit belongs to a hit group other than group zero.

==== Payload ====

A single byte, the hit group ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ID - Object Identifier ===

Specifies a 32-bit integer which uniquely identifies the object on the sender's system.

==== Sending ====

This child is not normally sent for search results. It is used in browse-user responses
to allow objects to be referenced by virtual folder structures.

==== Receiving ====

Use this ID to link objects to virtual folder structures.

==== Payload ====

A 32-bit integer ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/CSC - Cached Source Count ===

Indicates the number of external cached sources known to the sending node.

==== Sending ====

This child is sent if cached sources are available and interest in URLs was expressed
in the query.

==== Payload ====

A 16-bit integer.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PART - Partial Content Tag ===

Indicates that the sending node has only part of the object, and how much it has.

==== Sending ====

This child is sent if a /QH2/H/URL child is present and the URL contains only part of
the object.

==== Payload ====

A 32-bit integer, the number of bytes available.

==== Children ====

This packet has one child packet type defined at the current time:

* MT - Modification Time (payload = 32-bit timestamp)

The ''MT'' child carries the last modification time (UNIX timestamp) of the partial file and can be used to determine whether there has been recent updates made (''hot'' file) or if the file is ''cold'' (not undergoing any downloading activity on the remote side).

=== /QH2/H/COM - User Comment ===

Provides a user review and/or rating for the object.

==== Sending ====

This child is sent if a user comment is available, and comments were requested.

==== Payload ====

An XML string, of the form:

<pre>
<nowiki>
<comment rating="n">
The comment goes here.
</comment>
</nowiki>
</pre>

The rating is an integer 0 <= n <= 5, indicating the number of "stars". The text
may not include HTML, but may include forum-style block codes and emoticon
notation.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PVU - Preview URL ===

Indicates that a preview URL is available for the object. A preview URL will serve a
miniature version of the content.

==== Sending ====

This child is sent if a preview is available.

==== Payload ====

Empty, or an absolute URL.

If a URL is provided, that URL should be considered to point to a preview of the
object being described.

If the payload is empty, the sender is indicating that it has a preview of the object
available locally. It can be retrieved with an HTTP request to the path:

<pre>
<nowiki>
/gnutella/preview/v1?urn:xyz
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ALT - Alternate Locations ===

Supplies alternate download sources for the hit.

==== Sending ====

This child is sent when the query indicated that it wanted alternate locations, via the "A" string in its /Q2/I child.

==== Payload ====

The payload contains a vector of alternate locations, listing IPv4 addresses followed by 16-bit ports, as usual (e.g. the same format used to serialize an "NA" payload), but all the entries are concatenated. Hence, a payload of 24 bytes will indicate that there are 4 entries of 6 bytes each.

These alternate locations are the IP:port addresses of known hosts that can serve the file. These can be G2 hosts or G1 hosts, but there are no differences since the file transfer protocol is identical for both networks.

None of the addresses listed there are for firewalled hosts, so anyone should be able to contact them at their uri-res address, supplying the urn:sha1: value suitable for the resource.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/CT - Creation Time ===

Supplies the creation time of the resource.

==== Sending ====

This child is sent to indicate the creation time of the resource being returned.

==== Payload ====

The payload contains a UNIX timestamp, supplying the time when the resource was created. It is encoded using a '''variable-length''' encoding, which will ususally use 4 bytes, until 2038 is reached...

==== Children ====

This packet has no known children at the current time.

== /QH2/MD - Unified Metadata Block ==

Provides metadata describing one or more objects in the packet. This is an
alternative method of delivering metadata, which allows metadata for similar objects
to be grouped together. It is compatible with the unified metadata block format in
Gnutella1.

=== Sending ===

This chid should be sent if it was requested and is available.

=== Payload ===

A string containing one or more XML documents, each beginning with a header.
Standard plural/singular Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application index="0" title="Shareaza"/>
</applications>
<?xml version="1.0"?>
<images xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/image.xsd">
<image index="1" description="Shareaza Logo" width="128" height="128"/>
<image index="2" description="Shareaza Screen Shot" width="1024" height="768"/>
</images>
</nowiki>
</pre>

An additional attribute, "index" is added to each singular entry. The index is a zerobased
integer identifying the Nth /QH2/H child within this /QH2 packet.

=== Children ===

This packet has no known children at the current time.

== /QH2/UPRO - User Profile ==

Delivers a user profile or user profile summary, describing the user operating the
sending node.

=== Sending ===

Send a version of this child if the operating user wishes to list their screen name in
search results.

The current version of this packet contains a summary only, consisting of the
screen/nick name. Future versions may include a more comprehensive XML text
block in the payload.

=== Payload ===

No payload is defined at the current time.

=== Children ===

One child packet type is defined at the current time:

* /QH2/UPRO/NICK - Nick/screen Name

=== /QH2/UPRO/NICK - Nick/Screen Name ===

Specifies the nick/screen name of the user.

==== Payload ====

A string.

==== Children ====

This packet has no known children at the current time.

== /QH2/HN - DNS Host Name ==

This child conveys the DNS host name of the servent. This is useful when the host has a dynamic IP address that can change over time, letting others know how they can recompute your IP address through a DNS lookup when the connection to the specified address (IP and port) is no longer working properly. The port is not present here, since that is not supposed to change.

=== Sending ===

Send this child if you have a dynamic IP address and you know your DNS host name. This cannot be automatically computed and requires user input.

=== Payload ===

The host name of the host, as a string, with no trailing NUL (since the payload only contains the name). For instance, "g2host.example.com".

=== Children ===

This packet has no known children at the current time.

== /QH2/TLS - TLS Support ==

When present, this child indicates that the servent supports TLS connections.

=== Sending ===

Send this child if you are capable of initiating and receiving TLS connections.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/BH - Browsable Host ==

When present, this child indicates that the servent supports Browsing.

=== Sending ===

Send this children if you are capable of serving browsing requests using the <code>application/x-gnutella2</code> Content-Type.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/G1 - Gnutella-Relayed Query Hit ==

When present, this child indicates that the /QH2 has been synthetized from a Gnutella Query Hit by the relaying Ultrapeer.

Some Ultrapeers on Gnutella which connect as leaves to G2 can act as a '''hub-leaf''': the Query Hash Table (QHT) that they send to their G2 hubs are actually the concatenation of all the leaves they have + their own. Each /Q2 they receive are translated as a Gnutella query, then forwarded to all the Gnutella leaves. Query Hits that come back are then translated into a /QH2 to be processed correctly by the querying node. This hit can be delivered directly by UDP or relayed back to the sending hub.

The presence of /QH2/G1 indicates to the receiving G2 node that this hit was relayed from Gnutella. Therefore, one of the /QH2/NH children will point back to the Gnutella Ultrapeer which acted as the gateway. Other /QH2/NH, if present, are the Gnutella push-proxies that were possibly present in the Gnutella hit.

The hop count is set to '''1''' by the relaying Gnutella node to further indicate the relaying activity that took place.

=== Sending ===

This child is included by the relaying Gnutella Ultrapeer to indicate that the message was synthetized from a corresponding Gnutella hit, and that some of the original information may have been lost.

=== Receiving ===

When this child is present, the processing node can determine that the node serving the resources is a Gnutella host.

All the /QH2/NH children refer to Gnutella nodes, and therefore should not be sent a /PUSH message but rather a Gnutella PUSH to be on the safe side (although the nodes may also understand /PUSH because they support G2, this is not guaranteed, whereas Gnutella support is implied by the presence of this G1 child).

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has one child defined at the current time:

* V - the vendor code of the relaying Gnutella node

QH2

2014-03-12T07:39:48Z

Ram: /* Children */ Documented /QH2/G1 for G2 & Gnutella bridging

PUSH

2014-02-28T23:06:38Z

Ram: /* Children */ Added the /PUSH/TLS child

{{Packets}}

= /PUSH =

The push packet is used to request that a node initiate a TCP connection to a
specified node address. It is useful where the receiving node is unable to accept TCP
connections naturally.

For more information about when to use PUSH packets: [[Node_Route_Cache_and_Addressed_Packet_Forwarding#Reverse_Connection_.28Push.29_Requests|Reverse Connection (Push) Requests]]

== Sending ==

An addressed /PUSH packet should be sent to a hub with direct or proxy access to
the destination leaf node. It can be sent directly by a hub to one of its leaves without
the need for addressing.

== Receiving ==

Upon receiving a /PUSH packet, the local node should initiate a TCP connection to
the elected node address and issue a "push handshake", documented below.

== Payload ==

The network address of the node to contact, including of course the port number.

== Children ==

This packet only one known children at the current time, however it is often used with the generic addressing child packet "/?/TO" to indicate that it should be forwarded to a destination:

* TLS - sending host supports TLS connections

== /PUSH/TLS - TLS support indication ==

If a /PUSH packet contains a /PUSH/TLS child marker, the sending host can accept TLS connections.

=== Payload ===

This packet has no payload at the current time.

=== Children ===

This packet has no known children at the current time.

Q2

2014-02-25T22:02:41Z

Ram: /* /Q2/NAT - Firewalled indication */ Documented /Q2/NAT semantics

{{Packets}}

= /Q2 - Gnutella2 Query =

The /Q2 packet is the generic Gnutella2 object query descriptor. It contains search
criteria, identification, authentication, return addressing and the type of information
the search client is interested in.

== Sending ==

A node should send a /Q2 packet to another node when it wishes to execute a query
on that node (and its searchable relations).
/Q2 packets should always be filtered against a query hash table if one is available
for the outbound link.

== Receiving ==

Upon receiving a query, a node should:

* Verify its authentication
* Send an acknowledgment if it was not received from a hub
* Forward it to connected nodes if necessary (detailed below)
* Process it locally and dispatch results

== Forwarding ==

Forwarding of /Q2 packets is achieved based on fixed rules:

* A query received from a leaf or via UDP is forwarded to all connected nodes
* A query received from a hub is forwarded to connected leaves only

== Payload ==

The payload of a /Q2 packet consists of a GUID which uniquely identifies the search
operation.

== Children ==

This packet has many defined child packet types at the current time:
* /Q2/UDP - Return Address and Authentication
* /Q2/URN - Universal Resource Name
* /Q2/DN - Descriptive Name (Generic) Criteria
* /Q2/MD - Metadata Criteria
* /Q2/SZR - Object Size Restriction Criteria
* /Q2/NAT - Network Address Translation - Indicates querying node is firewalled
* /Q2/I - Interest

== /Q2/UDP - Return Address and Authentication ==

The /Q2/UDP child packet specifies the return address to be used for all direct
replies, and the query key authentication which authorises transmissions to this
address. If the query key is invalid, the query should be discarded and a valid query
key issued to the nominated address (if desired).

The query key is only checked by hubs receiving the query via UDP. Leaf nodes '''must ignore''' any query key held here.

=== Sending ===

This child is required if the query is to be delivered via UDP. It is optional if delivered
via TCP: if not included, replies will be reverse forwarded via TCP.

=== Receiving ===

If this child is present, all replies should be directed to the nominated address. The
query key should be verified (by hubs only) before replying.

=== Payload ===

A network address (variable length) followed by a query key (fixed length of 32 bits).

=== Children ===

This packet has no known children at the current time.

== /Q2/URN - Universal Resource Name ==

The /Q2/URN child specifies an exact universal resource name which will match the
query. Rules:

* If one or more URNs are present in a query, whether or not they are understood, matching must occur on URN only and other criteria should be ignored.
* If multiple URNs are present, only one need match an object for it to be considered a match for the query.
* Following from the above, multiple URNs of the same family may be specified and match multiple objects (this allows a compound query for several known objects to be executed in one packet).

=== Sending ===

This child should be added if a specific URN is being sought.

=== Payload ===

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* bitprint or bp - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* sha1 - 20 bytes of SHA1
* tree:tiger/ or ttr - 24 bytes of tiger-tree root
* md5 - 16 bytes of MD5
* ed2k - 16 bytes of compound MD4 (ed2k style root hash)

=== Children ===

This packet has no known children at the current time.

== /Q2/DN - Descriptive Name (Generic) Criteria ==

The descriptive name child provides generic query text to be used in matching
objects.

=== Payload ===

A string in the simple query language.

=== Children ===

This packet has no known children at the current time.

== /Q2/MD - Metadata Criteria ==

The metadata child provides an XML document containing rich query information.
The schema identified in the XML must match a metadata schema of prospective
matching objects.

=== Payload ===

A string containing XML. The header is optional. Standard plural/singular Gnutella
metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

All string values are in simple query language, including XML attribute and element
values.

=== Children ===

This packet has no known children at the current time.

== /Q2/SZR - Size Restriction Criteria ==

The size restriction criteria specify a minimum and maximum size for matching
objects.

=== Payload ===

A minimum size followed by a maximum size, both quoted in bytes. These two
numbers may be expressed as two 32 bit integers or two 64 bit integers.

=== Children ===

This packet has no known children at the current time.

== /Q2/NAT - Firewalled indication ==

This child indicates that the querying node is firewalled (cannot receive incoming UDP or TCP traffic).

This means a firewalled node receiving a query with this child present '''should not''' reply to it, since there will be no way to establish a TCP connection between the querying party and the source to transmit the resource content.

=== Payload ===

This packet has no payload.

=== Children ===

This packet has no known children at the current time.

== /Q2/I - Interest ==

The Interest packet advertises an interest in certain information classes, effectively
filtering the information that will be returned about matching objects.

=== Sending ===

Send an interest packet to restrict the type of information that will be returned about
matching objects. For example if querying only to find instances of a known object,
advertise interest for "URL" only. Omitting the interest packet produces a default set
of response information.

=== Receiving ===

If an interest packet is received, only return the requested information types. If no
interest packet is present, return all available information that is feasible. Extensions
may be withheld.

=== Payload ===

An array of strings identifying information classes. The following are defined:

* URL - Locations where matching objects can be found
* DN - Descriptive names of matching objects
* MD - Full metadata of matching objects
* COM - User comments, ratings and reviews of matching objects
* PFS - Partially available objects
* A - Requests alternate download sources, returned in /QH2/H/ALT.

Note that default URNs are always supplied and need not be requested.

=== Children ===

This packet has no known children at the current time.

Q2

2014-02-25T21:57:02Z

Ram: /* Children */ Documented /Q2/NAT, which seems to be used by Shareaza

{{Packets}}

= /Q2 - Gnutella2 Query =

The /Q2 packet is the generic Gnutella2 object query descriptor. It contains search
criteria, identification, authentication, return addressing and the type of information
the search client is interested in.

== Sending ==

A node should send a /Q2 packet to another node when it wishes to execute a query
on that node (and its searchable relations).
/Q2 packets should always be filtered against a query hash table if one is available
for the outbound link.

== Receiving ==

Upon receiving a query, a node should:

* Verify its authentication
* Send an acknowledgment if it was not received from a hub
* Forward it to connected nodes if necessary (detailed below)
* Process it locally and dispatch results

== Forwarding ==

Forwarding of /Q2 packets is achieved based on fixed rules:

* A query received from a leaf or via UDP is forwarded to all connected nodes
* A query received from a hub is forwarded to connected leaves only

== Payload ==

The payload of a /Q2 packet consists of a GUID which uniquely identifies the search
operation.

== Children ==

This packet has many defined child packet types at the current time:
* /Q2/UDP - Return Address and Authentication
* /Q2/URN - Universal Resource Name
* /Q2/DN - Descriptive Name (Generic) Criteria
* /Q2/MD - Metadata Criteria
* /Q2/SZR - Object Size Restriction Criteria
* /Q2/NAT - Network Address Translation - Indicates querying node is firewalled
* /Q2/I - Interest

== /Q2/UDP - Return Address and Authentication ==

The /Q2/UDP child packet specifies the return address to be used for all direct
replies, and the query key authentication which authorises transmissions to this
address. If the query key is invalid, the query should be discarded and a valid query
key issued to the nominated address (if desired).

The query key is only checked by hubs receiving the query via UDP. Leaf nodes '''must ignore''' any query key held here.

=== Sending ===

This child is required if the query is to be delivered via UDP. It is optional if delivered
via TCP: if not included, replies will be reverse forwarded via TCP.

=== Receiving ===

If this child is present, all replies should be directed to the nominated address. The
query key should be verified (by hubs only) before replying.

=== Payload ===

A network address (variable length) followed by a query key (fixed length of 32 bits).

=== Children ===

This packet has no known children at the current time.

== /Q2/URN - Universal Resource Name ==

The /Q2/URN child specifies an exact universal resource name which will match the
query. Rules:

* If one or more URNs are present in a query, whether or not they are understood, matching must occur on URN only and other criteria should be ignored.
* If multiple URNs are present, only one need match an object for it to be considered a match for the query.
* Following from the above, multiple URNs of the same family may be specified and match multiple objects (this allows a compound query for several known objects to be executed in one packet).

=== Sending ===

This child should be added if a specific URN is being sought.

=== Payload ===

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* bitprint or bp - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* sha1 - 20 bytes of SHA1
* tree:tiger/ or ttr - 24 bytes of tiger-tree root
* md5 - 16 bytes of MD5
* ed2k - 16 bytes of compound MD4 (ed2k style root hash)

=== Children ===

This packet has no known children at the current time.

== /Q2/DN - Descriptive Name (Generic) Criteria ==

The descriptive name child provides generic query text to be used in matching
objects.

=== Payload ===

A string in the simple query language.

=== Children ===

This packet has no known children at the current time.

== /Q2/MD - Metadata Criteria ==

The metadata child provides an XML document containing rich query information.
The schema identified in the XML must match a metadata schema of prospective
matching objects.

=== Payload ===

A string containing XML. The header is optional. Standard plural/singular Gnutella
metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

All string values are in simple query language, including XML attribute and element
values.

=== Children ===

This packet has no known children at the current time.

== /Q2/SZR - Size Restriction Criteria ==

The size restriction criteria specify a minimum and maximum size for matching
objects.

=== Payload ===

A minimum size followed by a maximum size, both quoted in bytes. These two
numbers may be expressed as two 32 bit integers or two 64 bit integers.

=== Children ===

This packet has no known children at the current time.

== /Q2/I - Interest ==

The Interest packet advertises an interest in certain information classes, effectively
filtering the information that will be returned about matching objects.

=== Sending ===

Send an interest packet to restrict the type of information that will be returned about
matching objects. For example if querying only to find instances of a known object,
advertise interest for "URL" only. Omitting the interest packet produces a default set
of response information.

=== Receiving ===

If an interest packet is received, only return the requested information types. If no
interest packet is present, return all available information that is feasible. Extensions
may be withheld.

=== Payload ===

An array of strings identifying information classes. The following are defined:

* URL - Locations where matching objects can be found
* DN - Descriptive names of matching objects
* MD - Full metadata of matching objects
* COM - User comments, ratings and reviews of matching objects
* PFS - Partially available objects
* A - Requests alternate download sources, returned in /QH2/H/ALT.

Note that default URNs are always supplied and need not be requested.

=== Children ===

This packet has no known children at the current time.

Object Search Mechanism

2014-02-16T21:53:26Z

Ram: /* Performance Considerations */ Fixed typo "sending" -> "receiving"

== Introduction ==

The distributed object search mechanism is a very important component of the
Gnutella2 architecture. It allows objects distributed throughout the network to be
located by a search client in an optimal fashion, requesting and receiving a subset of
the total information known about that object.

== Model ==

The Gnutella2 object search mechanism is best described as an "iterative crawl" of
the network, with a series of important optimisations derived from the network
topology and components:

* A search client iteratively contacts known hubs with its query
* Hubs match the query against the cached hash tables of their neighbours
* Where a table hit occurs, the query is forwarded once only
* The single injected query thus effectively covers the logical hub cluster, which is the basic searchable unit
* Nodes which actually receive the filtered query process it and send results to the search client directly

This model has a number of important advantages:

* Wide network coverage is provided by iterative query injection
* Effective leaf density is increased by querying hub clusters rather than single hubs or even single nodes
* Mutual and two-level filtering and static link compression are leveraged
* The load on each hub cluster is spread equally between its member hubs, providing a larger search base with a lower cost on the aggregation points
* Hubs need a greater inbound bandwidth capacity than outbound bandwidth capacity, which ideally suits asymmetric Internet connections

== Search Process Walkthrough ==

When a search client wishes to execute a new search, the following events happen:

* The search client selects an eligible hub from its global hub cache which has a recent timestamp, has not been contacted more recently than it allows, and has not yet been queried in this search.
* If a query key is not yet available for this hub, a query key request is dispatched.
* Once a query key is available, the search client sends a keyed query to the hub.
* Upon receiving the query, the hub checks the query key for validity.
* The hub then responds with a query acknowledgement packet, containing a list of neighbouring hubs which have now been searched and a list of 2-hop hubs which have not yet been searched.
* The search client adds the list of searched hubs to its "don't try again" list, and adds the list of "try hubs" to the global hub cache for future selection.
* Meanwhile, the hub examines the query to make sure that it has not received it before. Duplicate queries are dropped.
* The hub then matches the query against the query hash table of all connected nodes, and sends it to those nodes which may be able to field a match.
* While this is occurring, the hub processes the query locally and returns any results it may have.
* Leaves directly attached to the hub which have a potential match will have received the query, and process it locally. They may elect to return results directly to the search client, or may return their results to their hub for dispatch.
* Other hubs in the hub cluster which received the query now examine it to ensure they have not processed it before. They do not send an acknowledgement.
* Assuming it is new, the hubs match the query against the query hash tables of their leaves but not their neighbouring hubs. Potential leaves receive a copy of the query, and the hub processes it locally.
* Once again, the hub returns its own results and may forward results for its leaves if they do not wish to dispatch them directly.
* Meanwhile, the search client receives any search results generated by the hub cluster.
* The search client makes a decision on whether it should continue its search. If so, the process starts again.
* The search client will not requery any of the hubs in the hub cluster, but it has a list of nearby hubs so that the crawl can continue.

== Performance Considerations ==

Hubs should acknowledge /Q2 messages as quickly as possible with a /QA and not wait 5 or 10 minutes to reply. Why? Because the querying host is probably going to timeout, assuming the remote hub is off or too busy, and will start querying other hosts... which may already have been queried by the hub. This creates a nasty ''avalanche effect'' whereby busy hubs get extra traffic to acknowledge, causing them to further delay responses and therefore cause more useless querying.

The '''more delay''' there is between receiving of a /Q2 and acknowledging it via a /QA, the '''less effective''' the hub clustering topology will be.

LNI

2014-02-09T10:36:24Z

Ram: /* /LNI/TLS - TLS Support */ Documented "TLS"

{{Packets}}

= /LNI - Local Node Information =

The local node information packet is used to convey essential information about the
node on either end of a TCP stream connection.

== Sending ==

The /LNI packet should be sent to a TCP neighbour upon connection, and at regular
intervals following that if the information within it has changed. A minimum update
time of one minute is recommended.

== Receiving ==

Upon receiving a /LNI packet, the information within should be stored for subsequent
use.

== Payload ==

This packet has no payload at the current time.

== Children ==

The /LNI packet has many child packet types defined at the current time:

* /LNI/NA - Node Address
* /LNI/GU - GUID
* /LNI/V - Vendor Code
* /LNI/LS - Library Statistics
* /LNI/HS - Hub Status
* /LNI/FW - Firewalled
* /LNI/QK - Query Key Caching
* /LNI/HA - Hub Able
* /LNI/RTR - Router
* /LNI/UP - Uptime
* /LNI/TLS - TLS Support

== /LNI/NA - Node Address ==

The /LNI/NA child packet specifies the node or network address of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The physical network address of the sending node. See [[datatypes]] for more
information.

=== Children ===

This packet has no known children at the current time.

== /LNI/GU - GUID ==

The /LNI/GU child packet specifies the globally unique identifier of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The 16 byte globally unique node identifier of the sending node.

=== Children ===

This packet has no known children at the current time.

== /LNI/V - Vendor Code ==

The /LNI/V child packet specifies the vendor code of the software operating the
sending node.

=== Sending ===

This child is optional.

=== Payload ===

A four byte vendor code.

=== Children ===

This packet has no known children at the current time.

== /LNI/LS - Library Statistics ==

The /LNI/LS packet provides information about the content library of the sending
node.

=== Sending ===

This child is optional.

=== Payload ===

Two 32-bit integers representing the number of files in the local library, and the total
KB in the local library respectively. If the sending node is a hub these statistics are
combined with the known statistics from all connected leaves. The payload may grow
beyond 8 bytes in the future.

=== Children ===

This packet has no known children at the current time.

== /LNI/HS - Hub Status ==

The /LNI/HS packet is included only if the sending node is a hub, and contains the
status of the hub.

=== Sending ===

This child packet should only be sent by hub nodes. Leaf nodes should not transmit
it, and if it is received from a leaf node, it should be ignored.

=== Payload ===

Two 16-bit integers representing the current leaf count and the maximum leaf count
respectively. This packet may grow beyond 4 bytes in the future.

=== Children ===

This packet has no known children at the current time.

== /LNI/UP - Uptime ==

The /LNI/UP packet contains the node uptime, measured in seconds.

=== Sending ===

This child packet can be sent by any node (hub or leaf)

=== Payload ===

A variable-length quantity: an uptime of less than 256 seconds will be transmitted using one single byte, less than 65536 will require only 2 bytes, etc...

=== Children ===

This packet has no known children at the current time.

== /LNI/TLS - TLS Support ==

The /LNI/TLS packet presence indicates that the node can initiate and receive TLS connections.

=== Sending ===

This child packet can be sent by any node (hub or leaf) supporting TLS.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

LNI

2014-02-09T10:34:15Z

Ram: /* /LNI Children */ Added "TLS" to indicate TLS Support

QH2

2014-02-09T10:05:37Z

Ram: /* /QH2/H/ - Hit Descriptor */ Documented "CT"

{{Packets}}

= /QH2 - Query Hit =

The /QH2 Gnutella2 query hit packet contains one or more search result descriptors,
along with information about the node generating the result set. A single node may
generate several /QH2 packets in response to a /[[Q2]] query. Like all Gnutella2
packets, the /QH2 packet is highly extensible.

== Sending ==

Send a /QH2 packet when processing a /[[Q2]] query packet reveals one or more
matching objects. Query hits can be returned directly to the /Q2/UDP return address
in the query, or routed back along the delivery chain. Firewalled leaf nodes are
advised to return /QH2 packets to their connected hub for dispatch, as the hub will
be able to make a reliable delivery.

== Receiving ==

Upon receiving a /QH2 query hit packet, check the query GUID against locally
initiated queries. If it originated elsewhere, increment the route-back hop counter
and forward it to the most appropriate link or UDP endpoint. If it matches a locally
generated query, process the search results.

== Payload ==

A single byte representing the hop count, followed by a 16 byte GUID identifying the
search that produced these results.

== Children ==

This packet has many child packet types defined at the current time:

* FW - Firewalled Servent
* H - Hit Descriptor
* HG - Hit Group Descriptor
* GU - Node GUID
* NA - Node Address
* NH - Neighbouring Hub
* V - Vendor Code
* MD - Unified Metadata Block
* UPRO - User Profile
* BUP - Browse User Profile Tag
* PCH - Peer Chat Tag
* HN - DNS Host Name of Servent (e.g. "g2.example.com")
* TLS - TLS Support
* BH - Browsable Host

== /QH2/FW - Firewalled Servent ==

Specifies that the sending node is ''firewalled'' and cannot accept incoming connections.

=== Sending ===

This child is sent only when the servent issuing the hit is firewalled.

=== Payload ===

There is no payload defined.

=== Children ===

This packet has no known children at the current time.

== /QH2/GU - Node GUID ==

Specifies the GUID of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The GUID of the sending node.

=== Children ===

This packet has no known children at the current time.

== /QH2/NA - Node Address ==

Specifies the node / network address of the sending node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

The node / network address of the sending node. See datatypes for more
information.

=== Children ===

This packet has no known children at the current time.

== /QH2/NH - Neighbouring Hub ==

Lists a hub to which the sending node (a leaf) is connected. This provides a contact
point for routing communications to a possibly firewalled leaf node.

=== Sending ===

This child is optional, and may appear more than once.

=== Payload ===

The node / network address of a hub to which the sending node is connected.

=== Children ===

This packet has no known children at the current time.

== /QH2/V - Vendor Code ==

Identifies the software operating the sending node.

=== Sending ===

This child is optional.

=== Payload ===

A four character vendor code.

=== Children ===

This packet has no known children at the current time.

== /QH2/BUP - Browse User Profile Tag ==

Indicates that the sending node supports browsing the local user profile.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/PCH - Peer Chat Tag ==

Indicates that the sending node supports person to person private message chat.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/HG - Hit Group Descriptor ==

Describes a group of search results.

=== Sending ===

This child is optional and may appear more than once.

=== Payload ===

A single byte, the group ID number.

=== Children ===

This packet has one child packet type currently defined:

* SS - Server State

=== /QH2/HG/SS - Server State ===

Provides a status snapshot of the upload server that applies to search results in the
current hit group.

==== Sending ====

Add this child to the hit group descriptor to provide server state information.

==== Receiving ====

Use this information when interpreting hits linked with this hit group.

==== Payload ====

* A 16-bit integer : the current queue length including any active transfers (number waiting plus number transferring)
* An 8-bit integer : the maximum number of concurrent transfers (capacity)
* A 32-bit integer : the speed in kilobits per second for uploads on this server module

==== Children ====

This packet has no known children at the current time.

== /QH2/H - Hit Descriptor ==

Describes a single object which matched the original query.

=== Sending ===

Send a /QH2/H child for each matching object to be included in this /QH2 packet.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has many child packet types defined at the current time, and is often
extended:

* URN - Universal Resource Name
* URL - Universal Resource Location
* DN - Descriptive Name
* MD - Metadata
* SZ - Object Size
* G - Group Identifier
* ID - Object Identifier
* CSC - Cached Source Count
* PART - Partial Availability Marker
* COM - User Comment
* PVU - Preview URL
* ALT - Alternate Locations
* CT - Creation time

=== /QH2/H/URN - Universal Resource Name ===

Specifies a universal resource name which can be used to identify the object.

==== Sending ====

At least one instance of this child is required. Multiple instances are optional.

==== Payload ====

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* '''bitprint''' or '''bp''' - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* '''sha1''' - 20 bytes of SHA1
* '''tree:tiger/''' or '''ttr''' - 24 bytes of tiger-tree root
* '''md5''' - 16 bytes of MD5
* '''ed2k''' - 16 bytes of compound MD4 (ed2k style root hash)

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/URL - Universal Resource Location ===

This child specifies a location where the object being described can be acquired.

==== Sending ====

This child should be sent if it was requested and a URL is available.

==== Receiving ====

If a /QH2/H/URL child was requested but is not present, the sending node may not
have the object. It is valid to advertise information about objects that are not
available.

==== Payload ====

Empty, or a string which represents an absolute URL.

If a URL is provided, that URL should be considered to point to an instance of the
object being described.

If the payload is empty, the sender is indicating that it has the object available
locally. It can be retrieved with an HTTP request using the "uri-res" resolver.

==== Children ====

This packet has no known children at the current time.

=== QH2/H/DN - Descriptive Name (Generic) Criteria ===

The descriptive name for the object, and the object's size.

==== Sending ====

This child should be sent if it was requested and is available.

==== Payload ====

A 32-bit integer indicating the object's size, followed by a string describing it. If a
/QH2/H/SZ child is present, the 32-bit size prefix is omitted here (allowing a larger
64 bit file size).

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/MD - Metadata ===

Provides metadata describing the object.

==== Sending ====

This chid should be sent if it was requested and is available.

==== Payload ====

A string containing XML. The xml header is optional. Standard plural/singular
Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/SZ - Object Size ===

Specifies the size of the object.

==== Sending ====

This child should be sent if DN was requested, and if the size is not to be packed into
the /QH2/H/DN child.

==== Payload ====

A 32-bit or 64-bit integer representing the object size.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/G - Group Identifier ===

Indicates which hit group (/QH2/HG) this hit belongs to. If this child is not present,
the hit belongs to group zero.

==== Sending ====

Send this child if this hit belongs to a hit group other than group zero.

==== Receiving ====

If this child is present, the hit belongs to a hit group other than group zero.

==== Payload ====

A single byte, the hit group ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ID - Object Identifier ===

Specifies a 32-bit integer which uniquely identifies the object on the sender's system.

==== Sending ====

This child is not normally sent for search results. It is used in browse-user responses
to allow objects to be referenced by virtual folder structures.

==== Receiving ====

Use this ID to link objects to virtual folder structures.

==== Payload ====

A 32-bit integer ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/CSC - Cached Source Count ===

Indicates the number of external cached sources known to the sending node.

==== Sending ====

This child is sent if cached sources are available and interest in URLs was expressed
in the query.

==== Payload ====

A 16-bit integer.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PART - Partial Content Tag ===

Indicates that the sending node has only part of the object, and how much it has.

==== Sending ====

This child is sent if a /QH2/H/URL child is present and the URL contains only part of
the object.

==== Payload ====

A 32-bit integer, the number of bytes available.

==== Children ====

This packet has one child packet type defined at the current time:

* MT - Modification Time (payload = 32-bit timestamp)

The ''MT'' child carries the last modification time (UNIX timestamp) of the partial file and can be used to determine whether there has been recent updates made (''hot'' file) or if the file is ''cold'' (not undergoing any downloading activity on the remote side).

=== /QH2/H/COM - User Comment ===

Provides a user review and/or rating for the object.

==== Sending ====

This child is sent if a user comment is available, and comments were requested.

==== Payload ====

An XML string, of the form:

<pre>
<nowiki>
<comment rating="n">
The comment goes here.
</comment>
</nowiki>
</pre>

The rating is an integer 0 <= n <= 5, indicating the number of "stars". The text
may not include HTML, but may include forum-style block codes and emoticon
notation.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PVU - Preview URL ===

Indicates that a preview URL is available for the object. A preview URL will serve a
miniature version of the content.

==== Sending ====

This child is sent if a preview is available.

==== Payload ====

Empty, or an absolute URL.

If a URL is provided, that URL should be considered to point to a preview of the
object being described.

If the payload is empty, the sender is indicating that it has a preview of the object
available locally. It can be retrieved with an HTTP request to the path:

<pre>
<nowiki>
/gnutella/preview/v1?urn:xyz
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ALT - Alternate Locations ===

Supplies alternate download sources for the hit.

==== Sending ====

This child is sent when the query indicated that it wanted alternate locations, via the "A" string in its /Q2/I child.

==== Payload ====

The payload contains a vector of alternate locations, listing IPv4 addresses followed by 16-bit ports, as usual (e.g. the same format used to serialize an "NA" payload), but all the entries are concatenated. Hence, a payload of 24 bytes will indicate that there are 4 entries of 6 bytes each.

These alternate locations are the IP:port addresses of known hosts that can serve the file. These can be G2 hosts or G1 hosts, but there are no differences since the file transfer protocol is identical for both networks.

None of the addresses listed there are for firewalled hosts, so anyone should be able to contact them at their uri-res address, supplying the urn:sha1: value suitable for the resource.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/CT - Creation Time ===

Supplies the creation time of the resource.

==== Sending ====

This child is sent to indicate the creation time of the resource being returned.

==== Payload ====

The payload contains a UNIX timestamp, supplying the time when the resource was created. It is encoded using a '''variable-length''' encoding, which will ususally use 4 bytes, until 2038 is reached...

==== Children ====

This packet has no known children at the current time.

== /QH2/MD - Unified Metadata Block ==

Provides metadata describing one or more objects in the packet. This is an
alternative method of delivering metadata, which allows metadata for similar objects
to be grouped together. It is compatible with the unified metadata block format in
Gnutella1.

=== Sending ===

This chid should be sent if it was requested and is available.

=== Payload ===

A string containing one or more XML documents, each beginning with a header.
Standard plural/singular Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application index="0" title="Shareaza"/>
</applications>
<?xml version="1.0"?>
<images xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/image.xsd">
<image index="1" description="Shareaza Logo" width="128" height="128"/>
<image index="2" description="Shareaza Screen Shot" width="1024" height="768"/>
</images>
</nowiki>
</pre>

An additional attribute, "index" is added to each singular entry. The index is a zerobased
integer identifying the Nth /QH2/H child within this /QH2 packet.

=== Children ===

This packet has no known children at the current time.

== /QH2/UPRO - User Profile ==

Delivers a user profile or user profile summary, describing the user operating the
sending node.

=== Sending ===

Send a version of this child if the operating user wishes to list their screen name in
search results.

The current version of this packet contains a summary only, consisting of the
screen/nick name. Future versions may include a more comprehensive XML text
block in the payload.

=== Payload ===

No payload is defined at the current time.

=== Children ===

One child packet type is defined at the current time:

* /QH2/UPRO/NICK - Nick/screen Name

=== /QH2/UPRO/NICK - Nick/Screen Name ===

Specifies the nick/screen name of the user.

==== Payload ====

A string.

==== Children ====

This packet has no known children at the current time.

== /QH2/HN - DNS Host Name ==

This child conveys the DNS host name of the servent. This is useful when the host has a dynamic IP address that can change over time, letting others know how they can recompute your IP address through a DNS lookup when the connection to the specified address (IP and port) is no longer working properly. The port is not present here, since that is not supposed to change.

=== Sending ===

Send this child if you have a dynamic IP address and you know your DNS host name. This cannot be automatically computed and requires user input.

=== Payload ===

The host name of the host, as a string, with no trailing NUL (since the payload only contains the name). For instance, "g2host.example.com".

=== Children ===

This packet has no known children at the current time.

== /QH2/TLS - TLS Support ==

When present, this child indicates that the servent supports TLS connections.

=== Sending ===

Send this child if you are capable of initiating and receiving TLS connections.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/BH - Browsable Host ==

When present, this child indicates that the servent supports Browsing.

=== Sending ===

Send this children if you are capable of serving browsing requests using the <code>application/x-gnutella2</code> Content-Type.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

QH2

2014-02-09T09:58:52Z

Ram: /* Children */ Added "CT", the Creation Time

{{Packets}}

= /QH2 - Query Hit =

The /QH2 Gnutella2 query hit packet contains one or more search result descriptors,
along with information about the node generating the result set. A single node may
generate several /QH2 packets in response to a /[[Q2]] query. Like all Gnutella2
packets, the /QH2 packet is highly extensible.

== Sending ==

Send a /QH2 packet when processing a /[[Q2]] query packet reveals one or more
matching objects. Query hits can be returned directly to the /Q2/UDP return address
in the query, or routed back along the delivery chain. Firewalled leaf nodes are
advised to return /QH2 packets to their connected hub for dispatch, as the hub will
be able to make a reliable delivery.

== Receiving ==

Upon receiving a /QH2 query hit packet, check the query GUID against locally
initiated queries. If it originated elsewhere, increment the route-back hop counter
and forward it to the most appropriate link or UDP endpoint. If it matches a locally
generated query, process the search results.

== Payload ==

A single byte representing the hop count, followed by a 16 byte GUID identifying the
search that produced these results.

== Children ==

This packet has many child packet types defined at the current time:

* FW - Firewalled Servent
* H - Hit Descriptor
* HG - Hit Group Descriptor
* GU - Node GUID
* NA - Node Address
* NH - Neighbouring Hub
* V - Vendor Code
* MD - Unified Metadata Block
* UPRO - User Profile
* BUP - Browse User Profile Tag
* PCH - Peer Chat Tag
* HN - DNS Host Name of Servent (e.g. "g2.example.com")
* TLS - TLS Support
* BH - Browsable Host

== /QH2/FW - Firewalled Servent ==

Specifies that the sending node is ''firewalled'' and cannot accept incoming connections.

=== Sending ===

This child is sent only when the servent issuing the hit is firewalled.

=== Payload ===

There is no payload defined.

=== Children ===

This packet has no known children at the current time.

== /QH2/GU - Node GUID ==

Specifies the GUID of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The GUID of the sending node.

=== Children ===

This packet has no known children at the current time.

== /QH2/NA - Node Address ==

Specifies the node / network address of the sending node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

The node / network address of the sending node. See datatypes for more
information.

=== Children ===

This packet has no known children at the current time.

== /QH2/NH - Neighbouring Hub ==

Lists a hub to which the sending node (a leaf) is connected. This provides a contact
point for routing communications to a possibly firewalled leaf node.

=== Sending ===

This child is optional, and may appear more than once.

=== Payload ===

The node / network address of a hub to which the sending node is connected.

=== Children ===

This packet has no known children at the current time.

== /QH2/V - Vendor Code ==

Identifies the software operating the sending node.

=== Sending ===

This child is optional.

=== Payload ===

A four character vendor code.

=== Children ===

This packet has no known children at the current time.

== /QH2/BUP - Browse User Profile Tag ==

Indicates that the sending node supports browsing the local user profile.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/PCH - Peer Chat Tag ==

Indicates that the sending node supports person to person private message chat.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/HG - Hit Group Descriptor ==

Describes a group of search results.

=== Sending ===

This child is optional and may appear more than once.

=== Payload ===

A single byte, the group ID number.

=== Children ===

This packet has one child packet type currently defined:

* SS - Server State

=== /QH2/HG/SS - Server State ===

Provides a status snapshot of the upload server that applies to search results in the
current hit group.

==== Sending ====

Add this child to the hit group descriptor to provide server state information.

==== Receiving ====

Use this information when interpreting hits linked with this hit group.

==== Payload ====

* A 16-bit integer : the current queue length including any active transfers (number waiting plus number transferring)
* An 8-bit integer : the maximum number of concurrent transfers (capacity)
* A 32-bit integer : the speed in kilobits per second for uploads on this server module

==== Children ====

This packet has no known children at the current time.

== /QH2/H - Hit Descriptor ==

Describes a single object which matched the original query.

=== Sending ===

Send a /QH2/H child for each matching object to be included in this /QH2 packet.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has many child packet types defined at the current time, and is often
extended:

* URN - Universal Resource Name
* URL - Universal Resource Location
* DN - Descriptive Name
* MD - Metadata
* SZ - Object Size
* G - Group Identifier
* ID - Object Identifier
* CSC - Cached Source Count
* PART - Partial Availability Marker
* COM - User Comment
* PVU - Preview URL
* ALT - Alternate Locations
* CT - Creation time

=== /QH2/H/URN - Universal Resource Name ===

Specifies a universal resource name which can be used to identify the object.

==== Sending ====

At least one instance of this child is required. Multiple instances are optional.

==== Payload ====

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* '''bitprint''' or '''bp''' - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* '''sha1''' - 20 bytes of SHA1
* '''tree:tiger/''' or '''ttr''' - 24 bytes of tiger-tree root
* '''md5''' - 16 bytes of MD5
* '''ed2k''' - 16 bytes of compound MD4 (ed2k style root hash)

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/URL - Universal Resource Location ===

This child specifies a location where the object being described can be acquired.

==== Sending ====

This child should be sent if it was requested and a URL is available.

==== Receiving ====

If a /QH2/H/URL child was requested but is not present, the sending node may not
have the object. It is valid to advertise information about objects that are not
available.

==== Payload ====

Empty, or a string which represents an absolute URL.

If a URL is provided, that URL should be considered to point to an instance of the
object being described.

If the payload is empty, the sender is indicating that it has the object available
locally. It can be retrieved with an HTTP request using the "uri-res" resolver.

==== Children ====

This packet has no known children at the current time.

=== QH2/H/DN - Descriptive Name (Generic) Criteria ===

The descriptive name for the object, and the object's size.

==== Sending ====

This child should be sent if it was requested and is available.

==== Payload ====

A 32-bit integer indicating the object's size, followed by a string describing it. If a
/QH2/H/SZ child is present, the 32-bit size prefix is omitted here (allowing a larger
64 bit file size).

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/MD - Metadata ===

Provides metadata describing the object.

==== Sending ====

This chid should be sent if it was requested and is available.

==== Payload ====

A string containing XML. The xml header is optional. Standard plural/singular
Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/SZ - Object Size ===

Specifies the size of the object.

==== Sending ====

This child should be sent if DN was requested, and if the size is not to be packed into
the /QH2/H/DN child.

==== Payload ====

A 32-bit or 64-bit integer representing the object size.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/G - Group Identifier ===

Indicates which hit group (/QH2/HG) this hit belongs to. If this child is not present,
the hit belongs to group zero.

==== Sending ====

Send this child if this hit belongs to a hit group other than group zero.

==== Receiving ====

If this child is present, the hit belongs to a hit group other than group zero.

==== Payload ====

A single byte, the hit group ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ID - Object Identifier ===

Specifies a 32-bit integer which uniquely identifies the object on the sender's system.

==== Sending ====

This child is not normally sent for search results. It is used in browse-user responses
to allow objects to be referenced by virtual folder structures.

==== Receiving ====

Use this ID to link objects to virtual folder structures.

==== Payload ====

A 32-bit integer ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/CSC - Cached Source Count ===

Indicates the number of external cached sources known to the sending node.

==== Sending ====

This child is sent if cached sources are available and interest in URLs was expressed
in the query.

==== Payload ====

A 16-bit integer.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PART - Partial Content Tag ===

Indicates that the sending node has only part of the object, and how much it has.

==== Sending ====

This child is sent if a /QH2/H/URL child is present and the URL contains only part of
the object.

==== Payload ====

A 32-bit integer, the number of bytes available.

==== Children ====

This packet has one child packet type defined at the current time:

* MT - Modification Time (payload = 32-bit timestamp)

The ''MT'' child carries the last modification time (UNIX timestamp) of the partial file and can be used to determine whether there has been recent updates made (''hot'' file) or if the file is ''cold'' (not undergoing any downloading activity on the remote side).

=== /QH2/H/COM - User Comment ===

Provides a user review and/or rating for the object.

==== Sending ====

This child is sent if a user comment is available, and comments were requested.

==== Payload ====

An XML string, of the form:

<pre>
<nowiki>
<comment rating="n">
The comment goes here.
</comment>
</nowiki>
</pre>

The rating is an integer 0 <= n <= 5, indicating the number of "stars". The text
may not include HTML, but may include forum-style block codes and emoticon
notation.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PVU - Preview URL ===

Indicates that a preview URL is available for the object. A preview URL will serve a
miniature version of the content.

==== Sending ====

This child is sent if a preview is available.

==== Payload ====

Empty, or an absolute URL.

If a URL is provided, that URL should be considered to point to a preview of the
object being described.

If the payload is empty, the sender is indicating that it has a preview of the object
available locally. It can be retrieved with an HTTP request to the path:

<pre>
<nowiki>
/gnutella/preview/v1?urn:xyz
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ALT - Alternate Locations ===

Supplies alternate download sources for the hit.

==== Sending ====

This child is sent when the query indicated that it wanted alternate locations, via the "A" string in its /Q2/I child.

==== Payload ====

The payload contains a vector of alternate locations, listing IPv4 addresses followed by 16-bit ports, as usual (e.g. the same format used to serialize an "NA" payload), but all the entries are concatenated. Hence, a payload of 24 bytes will indicate that there are 4 entries of 6 bytes each.

These alternate locations are the IP:port addresses of known hosts that can serve the file. These can be G2 hosts or G1 hosts, but there are no differences since the file transfer protocol is identical for both networks.

None of the addresses listed there are for firewalled hosts, so anyone should be able to contact them at their uri-res address, supplying the urn:sha1: value suitable for the resource.

==== Children ====

This packet has no known children at the current time.

== /QH2/MD - Unified Metadata Block ==

Provides metadata describing one or more objects in the packet. This is an
alternative method of delivering metadata, which allows metadata for similar objects
to be grouped together. It is compatible with the unified metadata block format in
Gnutella1.

=== Sending ===

This chid should be sent if it was requested and is available.

=== Payload ===

A string containing one or more XML documents, each beginning with a header.
Standard plural/singular Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application index="0" title="Shareaza"/>
</applications>
<?xml version="1.0"?>
<images xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/image.xsd">
<image index="1" description="Shareaza Logo" width="128" height="128"/>
<image index="2" description="Shareaza Screen Shot" width="1024" height="768"/>
</images>
</nowiki>
</pre>

An additional attribute, "index" is added to each singular entry. The index is a zerobased
integer identifying the Nth /QH2/H child within this /QH2 packet.

=== Children ===

This packet has no known children at the current time.

== /QH2/UPRO - User Profile ==

Delivers a user profile or user profile summary, describing the user operating the
sending node.

=== Sending ===

Send a version of this child if the operating user wishes to list their screen name in
search results.

The current version of this packet contains a summary only, consisting of the
screen/nick name. Future versions may include a more comprehensive XML text
block in the payload.

=== Payload ===

No payload is defined at the current time.

=== Children ===

One child packet type is defined at the current time:

* /QH2/UPRO/NICK - Nick/screen Name

=== /QH2/UPRO/NICK - Nick/Screen Name ===

Specifies the nick/screen name of the user.

==== Payload ====

A string.

==== Children ====

This packet has no known children at the current time.

== /QH2/HN - DNS Host Name ==

This child conveys the DNS host name of the servent. This is useful when the host has a dynamic IP address that can change over time, letting others know how they can recompute your IP address through a DNS lookup when the connection to the specified address (IP and port) is no longer working properly. The port is not present here, since that is not supposed to change.

=== Sending ===

Send this child if you have a dynamic IP address and you know your DNS host name. This cannot be automatically computed and requires user input.

=== Payload ===

The host name of the host, as a string, with no trailing NUL (since the payload only contains the name). For instance, "g2host.example.com".

=== Children ===

This packet has no known children at the current time.

== /QH2/TLS - TLS Support ==

When present, this child indicates that the servent supports TLS connections.

=== Sending ===

Send this child if you are capable of initiating and receiving TLS connections.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/BH - Browsable Host ==

When present, this child indicates that the servent supports Browsing.

=== Sending ===

Send this children if you are capable of serving browsing requests using the <code>application/x-gnutella2</code> Content-Type.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

QH2

2014-02-09T09:56:48Z

Ram: /* /QH2 */ Documented "HN", "TLS" and "BH" children.

{{Packets}}

= /QH2 - Query Hit =

The /QH2 Gnutella2 query hit packet contains one or more search result descriptors,
along with information about the node generating the result set. A single node may
generate several /QH2 packets in response to a /[[Q2]] query. Like all Gnutella2
packets, the /QH2 packet is highly extensible.

== Sending ==

Send a /QH2 packet when processing a /[[Q2]] query packet reveals one or more
matching objects. Query hits can be returned directly to the /Q2/UDP return address
in the query, or routed back along the delivery chain. Firewalled leaf nodes are
advised to return /QH2 packets to their connected hub for dispatch, as the hub will
be able to make a reliable delivery.

== Receiving ==

Upon receiving a /QH2 query hit packet, check the query GUID against locally
initiated queries. If it originated elsewhere, increment the route-back hop counter
and forward it to the most appropriate link or UDP endpoint. If it matches a locally
generated query, process the search results.

== Payload ==

A single byte representing the hop count, followed by a 16 byte GUID identifying the
search that produced these results.

== Children ==

This packet has many child packet types defined at the current time:

* FW - Firewalled Servent
* H - Hit Descriptor
* HG - Hit Group Descriptor
* GU - Node GUID
* NA - Node Address
* NH - Neighbouring Hub
* V - Vendor Code
* MD - Unified Metadata Block
* UPRO - User Profile
* BUP - Browse User Profile Tag
* PCH - Peer Chat Tag
* HN - DNS Host Name of Servent (e.g. "g2.example.com")
* TLS - TLS Support
* BH - Browsable Host

== /QH2/FW - Firewalled Servent ==

Specifies that the sending node is ''firewalled'' and cannot accept incoming connections.

=== Sending ===

This child is sent only when the servent issuing the hit is firewalled.

=== Payload ===

There is no payload defined.

=== Children ===

This packet has no known children at the current time.

== /QH2/GU - Node GUID ==

Specifies the GUID of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The GUID of the sending node.

=== Children ===

This packet has no known children at the current time.

== /QH2/NA - Node Address ==

Specifies the node / network address of the sending node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

The node / network address of the sending node. See datatypes for more
information.

=== Children ===

This packet has no known children at the current time.

== /QH2/NH - Neighbouring Hub ==

Lists a hub to which the sending node (a leaf) is connected. This provides a contact
point for routing communications to a possibly firewalled leaf node.

=== Sending ===

This child is optional, and may appear more than once.

=== Payload ===

The node / network address of a hub to which the sending node is connected.

=== Children ===

This packet has no known children at the current time.

== /QH2/V - Vendor Code ==

Identifies the software operating the sending node.

=== Sending ===

This child is optional.

=== Payload ===

A four character vendor code.

=== Children ===

This packet has no known children at the current time.

== /QH2/BUP - Browse User Profile Tag ==

Indicates that the sending node supports browsing the local user profile.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/PCH - Peer Chat Tag ==

Indicates that the sending node supports person to person private message chat.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/HG - Hit Group Descriptor ==

Describes a group of search results.

=== Sending ===

This child is optional and may appear more than once.

=== Payload ===

A single byte, the group ID number.

=== Children ===

This packet has one child packet type currently defined:

* SS - Server State

=== /QH2/HG/SS - Server State ===

Provides a status snapshot of the upload server that applies to search results in the
current hit group.

==== Sending ====

Add this child to the hit group descriptor to provide server state information.

==== Receiving ====

Use this information when interpreting hits linked with this hit group.

==== Payload ====

* A 16-bit integer : the current queue length including any active transfers (number waiting plus number transferring)
* An 8-bit integer : the maximum number of concurrent transfers (capacity)
* A 32-bit integer : the speed in kilobits per second for uploads on this server module

==== Children ====

This packet has no known children at the current time.

== /QH2/H - Hit Descriptor ==

Describes a single object which matched the original query.

=== Sending ===

Send a /QH2/H child for each matching object to be included in this /QH2 packet.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has many child packet types defined at the current time, and is often
extended:

* URN - Universal Resource Name
* URL - Universal Resource Location
* DN - Descriptive Name
* MD - Metadata
* SZ - Object Size
* G - Group Identifier
* ID - Object Identifier
* CSC - Cached Source Count
* PART - Partial Availability Marker
* COM - User Comment
* PVU - Preview URL
* ALT - Alternate Locations

=== /QH2/H/URN - Universal Resource Name ===

Specifies a universal resource name which can be used to identify the object.

==== Sending ====

At least one instance of this child is required. Multiple instances are optional.

==== Payload ====

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* '''bitprint''' or '''bp''' - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* '''sha1''' - 20 bytes of SHA1
* '''tree:tiger/''' or '''ttr''' - 24 bytes of tiger-tree root
* '''md5''' - 16 bytes of MD5
* '''ed2k''' - 16 bytes of compound MD4 (ed2k style root hash)

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/URL - Universal Resource Location ===

This child specifies a location where the object being described can be acquired.

==== Sending ====

This child should be sent if it was requested and a URL is available.

==== Receiving ====

If a /QH2/H/URL child was requested but is not present, the sending node may not
have the object. It is valid to advertise information about objects that are not
available.

==== Payload ====

Empty, or a string which represents an absolute URL.

If a URL is provided, that URL should be considered to point to an instance of the
object being described.

If the payload is empty, the sender is indicating that it has the object available
locally. It can be retrieved with an HTTP request using the "uri-res" resolver.

==== Children ====

This packet has no known children at the current time.

=== QH2/H/DN - Descriptive Name (Generic) Criteria ===

The descriptive name for the object, and the object's size.

==== Sending ====

This child should be sent if it was requested and is available.

==== Payload ====

A 32-bit integer indicating the object's size, followed by a string describing it. If a
/QH2/H/SZ child is present, the 32-bit size prefix is omitted here (allowing a larger
64 bit file size).

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/MD - Metadata ===

Provides metadata describing the object.

==== Sending ====

This chid should be sent if it was requested and is available.

==== Payload ====

A string containing XML. The xml header is optional. Standard plural/singular
Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/SZ - Object Size ===

Specifies the size of the object.

==== Sending ====

This child should be sent if DN was requested, and if the size is not to be packed into
the /QH2/H/DN child.

==== Payload ====

A 32-bit or 64-bit integer representing the object size.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/G - Group Identifier ===

Indicates which hit group (/QH2/HG) this hit belongs to. If this child is not present,
the hit belongs to group zero.

==== Sending ====

Send this child if this hit belongs to a hit group other than group zero.

==== Receiving ====

If this child is present, the hit belongs to a hit group other than group zero.

==== Payload ====

A single byte, the hit group ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ID - Object Identifier ===

Specifies a 32-bit integer which uniquely identifies the object on the sender's system.

==== Sending ====

This child is not normally sent for search results. It is used in browse-user responses
to allow objects to be referenced by virtual folder structures.

==== Receiving ====

Use this ID to link objects to virtual folder structures.

==== Payload ====

A 32-bit integer ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/CSC - Cached Source Count ===

Indicates the number of external cached sources known to the sending node.

==== Sending ====

This child is sent if cached sources are available and interest in URLs was expressed
in the query.

==== Payload ====

A 16-bit integer.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PART - Partial Content Tag ===

Indicates that the sending node has only part of the object, and how much it has.

==== Sending ====

This child is sent if a /QH2/H/URL child is present and the URL contains only part of
the object.

==== Payload ====

A 32-bit integer, the number of bytes available.

==== Children ====

This packet has one child packet type defined at the current time:

* MT - Modification Time (payload = 32-bit timestamp)

The ''MT'' child carries the last modification time (UNIX timestamp) of the partial file and can be used to determine whether there has been recent updates made (''hot'' file) or if the file is ''cold'' (not undergoing any downloading activity on the remote side).

=== /QH2/H/COM - User Comment ===

Provides a user review and/or rating for the object.

==== Sending ====

This child is sent if a user comment is available, and comments were requested.

==== Payload ====

An XML string, of the form:

<pre>
<nowiki>
<comment rating="n">
The comment goes here.
</comment>
</nowiki>
</pre>

The rating is an integer 0 <= n <= 5, indicating the number of "stars". The text
may not include HTML, but may include forum-style block codes and emoticon
notation.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PVU - Preview URL ===

Indicates that a preview URL is available for the object. A preview URL will serve a
miniature version of the content.

==== Sending ====

This child is sent if a preview is available.

==== Payload ====

Empty, or an absolute URL.

If a URL is provided, that URL should be considered to point to a preview of the
object being described.

If the payload is empty, the sender is indicating that it has a preview of the object
available locally. It can be retrieved with an HTTP request to the path:

<pre>
<nowiki>
/gnutella/preview/v1?urn:xyz
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ALT - Alternate Locations ===

Supplies alternate download sources for the hit.

==== Sending ====

This child is sent when the query indicated that it wanted alternate locations, via the "A" string in its /Q2/I child.

==== Payload ====

The payload contains a vector of alternate locations, listing IPv4 addresses followed by 16-bit ports, as usual (e.g. the same format used to serialize an "NA" payload), but all the entries are concatenated. Hence, a payload of 24 bytes will indicate that there are 4 entries of 6 bytes each.

These alternate locations are the IP:port addresses of known hosts that can serve the file. These can be G2 hosts or G1 hosts, but there are no differences since the file transfer protocol is identical for both networks.

None of the addresses listed there are for firewalled hosts, so anyone should be able to contact them at their uri-res address, supplying the urn:sha1: value suitable for the resource.

==== Children ====

This packet has no known children at the current time.

== /QH2/MD - Unified Metadata Block ==

Provides metadata describing one or more objects in the packet. This is an
alternative method of delivering metadata, which allows metadata for similar objects
to be grouped together. It is compatible with the unified metadata block format in
Gnutella1.

=== Sending ===

This chid should be sent if it was requested and is available.

=== Payload ===

A string containing one or more XML documents, each beginning with a header.
Standard plural/singular Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application index="0" title="Shareaza"/>
</applications>
<?xml version="1.0"?>
<images xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/image.xsd">
<image index="1" description="Shareaza Logo" width="128" height="128"/>
<image index="2" description="Shareaza Screen Shot" width="1024" height="768"/>
</images>
</nowiki>
</pre>

An additional attribute, "index" is added to each singular entry. The index is a zerobased
integer identifying the Nth /QH2/H child within this /QH2 packet.

=== Children ===

This packet has no known children at the current time.

== /QH2/UPRO - User Profile ==

Delivers a user profile or user profile summary, describing the user operating the
sending node.

=== Sending ===

Send a version of this child if the operating user wishes to list their screen name in
search results.

The current version of this packet contains a summary only, consisting of the
screen/nick name. Future versions may include a more comprehensive XML text
block in the payload.

=== Payload ===

No payload is defined at the current time.

=== Children ===

One child packet type is defined at the current time:

* /QH2/UPRO/NICK - Nick/screen Name

=== /QH2/UPRO/NICK - Nick/Screen Name ===

Specifies the nick/screen name of the user.

==== Payload ====

A string.

==== Children ====

This packet has no known children at the current time.

== /QH2/HN - DNS Host Name ==

This child conveys the DNS host name of the servent. This is useful when the host has a dynamic IP address that can change over time, letting others know how they can recompute your IP address through a DNS lookup when the connection to the specified address (IP and port) is no longer working properly. The port is not present here, since that is not supposed to change.

=== Sending ===

Send this child if you have a dynamic IP address and you know your DNS host name. This cannot be automatically computed and requires user input.

=== Payload ===

The host name of the host, as a string, with no trailing NUL (since the payload only contains the name). For instance, "g2host.example.com".

=== Children ===

This packet has no known children at the current time.

== /QH2/TLS - TLS Support ==

When present, this child indicates that the servent supports TLS connections.

=== Sending ===

Send this child if you are capable of initiating and receiving TLS connections.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/BH - Browsable Host ==

When present, this child indicates that the servent supports Browsing.

=== Sending ===

Send this children if you are capable of serving browsing requests using the <code>application/x-gnutella2</code> Content-Type.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

QH2

2014-02-09T09:42:59Z

Ram: /* Children */ Added "HN", "TLS" and "BH" children

{{Packets}}

= /QH2 - Query Hit =

The /QH2 Gnutella2 query hit packet contains one or more search result descriptors,
along with information about the node generating the result set. A single node may
generate several /QH2 packets in response to a /[[Q2]] query. Like all Gnutella2
packets, the /QH2 packet is highly extensible.

== Sending ==

Send a /QH2 packet when processing a /[[Q2]] query packet reveals one or more
matching objects. Query hits can be returned directly to the /Q2/UDP return address
in the query, or routed back along the delivery chain. Firewalled leaf nodes are
advised to return /QH2 packets to their connected hub for dispatch, as the hub will
be able to make a reliable delivery.

== Receiving ==

Upon receiving a /QH2 query hit packet, check the query GUID against locally
initiated queries. If it originated elsewhere, increment the route-back hop counter
and forward it to the most appropriate link or UDP endpoint. If it matches a locally
generated query, process the search results.

== Payload ==

A single byte representing the hop count, followed by a 16 byte GUID identifying the
search that produced these results.

== Children ==

This packet has many child packet types defined at the current time:

* FW - Firewalled Servent
* H - Hit Descriptor
* HG - Hit Group Descriptor
* GU - Node GUID
* NA - Node Address
* NH - Neighbouring Hub
* V - Vendor Code
* MD - Unified Metadata Block
* UPRO - User Profile
* BUP - Browse User Profile Tag
* PCH - Peer Chat Tag
* HN - DNS Host Name of Servent (e.g. "g2.example.com")
* TLS - TLS Support
* BH - Browsable Host

== /QH2/FW - Firewalled Servent ==

Specifies that the sending node is ''firewalled'' and cannot accept incoming connections.

=== Sending ===

This child is sent only when the servent issuing the hit is firewalled.

=== Payload ===

There is no payload defined.

=== Children ===

This packet has no known children at the current time.

== /QH2/GU - Node GUID ==

Specifies the GUID of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The GUID of the sending node.

=== Children ===

This packet has no known children at the current time.

== /QH2/NA - Node Address ==

Specifies the node / network address of the sending node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

The node / network address of the sending node. See datatypes for more
information.

=== Children ===

This packet has no known children at the current time.

== /QH2/NH - Neighbouring Hub ==

Lists a hub to which the sending node (a leaf) is connected. This provides a contact
point for routing communications to a possibly firewalled leaf node.

=== Sending ===

This child is optional, and may appear more than once.

=== Payload ===

The node / network address of a hub to which the sending node is connected.

=== Children ===

This packet has no known children at the current time.

== /QH2/V - Vendor Code ==

Identifies the software operating the sending node.

=== Sending ===

This child is optional.

=== Payload ===

A four character vendor code.

=== Children ===

This packet has no known children at the current time.

== /QH2/BUP - Browse User Profile Tag ==

Indicates that the sending node supports browsing the local user profile.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/PCH - Peer Chat Tag ==

Indicates that the sending node supports person to person private message chat.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/HG - Hit Group Descriptor ==

Describes a group of search results.

=== Sending ===

This child is optional and may appear more than once.

=== Payload ===

A single byte, the group ID number.

=== Children ===

This packet has one child packet type currently defined:

* SS - Server State

=== /QH2/HG/SS - Server State ===

Provides a status snapshot of the upload server that applies to search results in the
current hit group.

==== Sending ====

Add this child to the hit group descriptor to provide server state information.

==== Receiving ====

Use this information when interpreting hits linked with this hit group.

==== Payload ====

* A 16-bit integer : the current queue length including any active transfers (number waiting plus number transferring)
* An 8-bit integer : the maximum number of concurrent transfers (capacity)
* A 32-bit integer : the speed in kilobits per second for uploads on this server module

==== Children ====

This packet has no known children at the current time.

== /QH2/H - Hit Descriptor ==

Describes a single object which matched the original query.

=== Sending ===

Send a /QH2/H child for each matching object to be included in this /QH2 packet.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has many child packet types defined at the current time, and is often
extended:

* URN - Universal Resource Name
* URL - Universal Resource Location
* DN - Descriptive Name
* MD - Metadata
* SZ - Object Size
* G - Group Identifier
* ID - Object Identifier
* CSC - Cached Source Count
* PART - Partial Availability Marker
* COM - User Comment
* PVU - Preview URL
* ALT - Alternate Locations

=== /QH2/H/URN - Universal Resource Name ===

Specifies a universal resource name which can be used to identify the object.

==== Sending ====

At least one instance of this child is required. Multiple instances are optional.

==== Payload ====

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* '''bitprint''' or '''bp''' - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* '''sha1''' - 20 bytes of SHA1
* '''tree:tiger/''' or '''ttr''' - 24 bytes of tiger-tree root
* '''md5''' - 16 bytes of MD5
* '''ed2k''' - 16 bytes of compound MD4 (ed2k style root hash)

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/URL - Universal Resource Location ===

This child specifies a location where the object being described can be acquired.

==== Sending ====

This child should be sent if it was requested and a URL is available.

==== Receiving ====

If a /QH2/H/URL child was requested but is not present, the sending node may not
have the object. It is valid to advertise information about objects that are not
available.

==== Payload ====

Empty, or a string which represents an absolute URL.

If a URL is provided, that URL should be considered to point to an instance of the
object being described.

If the payload is empty, the sender is indicating that it has the object available
locally. It can be retrieved with an HTTP request using the "uri-res" resolver.

==== Children ====

This packet has no known children at the current time.

=== QH2/H/DN - Descriptive Name (Generic) Criteria ===

The descriptive name for the object, and the object's size.

==== Sending ====

This child should be sent if it was requested and is available.

==== Payload ====

A 32-bit integer indicating the object's size, followed by a string describing it. If a
/QH2/H/SZ child is present, the 32-bit size prefix is omitted here (allowing a larger
64 bit file size).

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/MD - Metadata ===

Provides metadata describing the object.

==== Sending ====

This chid should be sent if it was requested and is available.

==== Payload ====

A string containing XML. The xml header is optional. Standard plural/singular
Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/SZ - Object Size ===

Specifies the size of the object.

==== Sending ====

This child should be sent if DN was requested, and if the size is not to be packed into
the /QH2/H/DN child.

==== Payload ====

A 32-bit or 64-bit integer representing the object size.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/G - Group Identifier ===

Indicates which hit group (/QH2/HG) this hit belongs to. If this child is not present,
the hit belongs to group zero.

==== Sending ====

Send this child if this hit belongs to a hit group other than group zero.

==== Receiving ====

If this child is present, the hit belongs to a hit group other than group zero.

==== Payload ====

A single byte, the hit group ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ID - Object Identifier ===

Specifies a 32-bit integer which uniquely identifies the object on the sender's system.

==== Sending ====

This child is not normally sent for search results. It is used in browse-user responses
to allow objects to be referenced by virtual folder structures.

==== Receiving ====

Use this ID to link objects to virtual folder structures.

==== Payload ====

A 32-bit integer ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/CSC - Cached Source Count ===

Indicates the number of external cached sources known to the sending node.

==== Sending ====

This child is sent if cached sources are available and interest in URLs was expressed
in the query.

==== Payload ====

A 16-bit integer.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PART - Partial Content Tag ===

Indicates that the sending node has only part of the object, and how much it has.

==== Sending ====

This child is sent if a /QH2/H/URL child is present and the URL contains only part of
the object.

==== Payload ====

A 32-bit integer, the number of bytes available.

==== Children ====

This packet has one child packet type defined at the current time:

* MT - Modification Time (payload = 32-bit timestamp)

The ''MT'' child carries the last modification time (UNIX timestamp) of the partial file and can be used to determine whether there has been recent updates made (''hot'' file) or if the file is ''cold'' (not undergoing any downloading activity on the remote side).

=== /QH2/H/COM - User Comment ===

Provides a user review and/or rating for the object.

==== Sending ====

This child is sent if a user comment is available, and comments were requested.

==== Payload ====

An XML string, of the form:

<pre>
<nowiki>
<comment rating="n">
The comment goes here.
</comment>
</nowiki>
</pre>

The rating is an integer 0 <= n <= 5, indicating the number of "stars". The text
may not include HTML, but may include forum-style block codes and emoticon
notation.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PVU - Preview URL ===

Indicates that a preview URL is available for the object. A preview URL will serve a
miniature version of the content.

==== Sending ====

This child is sent if a preview is available.

==== Payload ====

Empty, or an absolute URL.

If a URL is provided, that URL should be considered to point to a preview of the
object being described.

If the payload is empty, the sender is indicating that it has a preview of the object
available locally. It can be retrieved with an HTTP request to the path:

<pre>
<nowiki>
/gnutella/preview/v1?urn:xyz
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ALT - Alternate Locations ===

Supplies alternate download sources for the hit.

==== Sending ====

This child is sent when the query indicated that it wanted alternate locations, via the "A" string in its /Q2/I child.

==== Payload ====

The payload contains a vector of alternate locations, listing IPv4 addresses followed by 16-bit ports, as usual (e.g. the same format used to serialize an "NA" payload), but all the entries are concatenated. Hence, a payload of 24 bytes will indicate that there are 4 entries of 6 bytes each.

These alternate locations are the IP:port addresses of known hosts that can serve the file. These can be G2 hosts or G1 hosts, but there are no differences since the file transfer protocol is identical for both networks.

None of the addresses listed there are for firewalled hosts, so anyone should be able to contact them at their uri-res address, supplying the urn:sha1: value suitable for the resource.

==== Children ====

This packet has no known children at the current time.

== /QH2/MD - Unified Metadata Block ==

Provides metadata describing one or more objects in the packet. This is an
alternative method of delivering metadata, which allows metadata for similar objects
to be grouped together. It is compatible with the unified metadata block format in
Gnutella1.

=== Sending ===

This chid should be sent if it was requested and is available.

=== Payload ===

A string containing one or more XML documents, each beginning with a header.
Standard plural/singular Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application index="0" title="Shareaza"/>
</applications>
<?xml version="1.0"?>
<images xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/image.xsd">
<image index="1" description="Shareaza Logo" width="128" height="128"/>
<image index="2" description="Shareaza Screen Shot" width="1024" height="768"/>
</images>
</nowiki>
</pre>

An additional attribute, "index" is added to each singular entry. The index is a zerobased
integer identifying the Nth /QH2/H child within this /QH2 packet.

=== Children ===

This packet has no known children at the current time.

== /QH2/UPRO - User Profile ==

Delivers a user profile or user profile summary, describing the user operating the
sending node.

=== Sending ===

Send a version of this child if the operating user wishes to list their screen name in
search results.

The current version of this packet contains a summary only, consisting of the
screen/nick name. Future versions may include a more comprehensive XML text
block in the payload.

=== Payload ===

No payload is defined at the current time.

=== Children ===

One child packet type is defined at the current time:

* /QH2/UPRO/NICK - Nick/screen Name

=== /QH2/UPRO/NICK - Nick/Screen Name ===

Specifies the nick/screen name of the user.

==== Payload ====

A string.

==== Children ====

This packet has no known children at the current time.

QH2

2014-02-04T23:45:59Z

Ram: Added /QH2/FW description

{{Packets}}

= /QH2 - Query Hit =

The /QH2 Gnutella2 query hit packet contains one or more search result descriptors,
along with information about the node generating the result set. A single node may
generate several /QH2 packets in response to a /[[Q2]] query. Like all Gnutella2
packets, the /QH2 packet is highly extensible.

== Sending ==

Send a /QH2 packet when processing a /[[Q2]] query packet reveals one or more
matching objects. Query hits can be returned directly to the /Q2/UDP return address
in the query, or routed back along the delivery chain. Firewalled leaf nodes are
advised to return /QH2 packets to their connected hub for dispatch, as the hub will
be able to make a reliable delivery.

== Receiving ==

Upon receiving a /QH2 query hit packet, check the query GUID against locally
initiated queries. If it originated elsewhere, increment the route-back hop counter
and forward it to the most appropriate link or UDP endpoint. If it matches a locally
generated query, process the search results.

== Payload ==

A single byte representing the hop count, followed by a 16 byte GUID identifying the
search that produced these results.

== Children ==

This packet has many child packet types defined at the current time:

* FW - Firewalled Servent
* H - Hit Descriptor
* HG - Hit Group Descriptor
* GU - Node GUID
* NA - Node Address
* NH - Neighbouring Hub
* V - Vendor Code
* MD - Unified Metadata Block
* UPRO - User Profile
* BUP - Browse User Profile Tag
* PCH - Peer Chat Tag

== /QH2/FW - Firewalled Servent ==

Specifies that the sending node is ''firewalled'' and cannot accept incoming connections.

=== Sending ===

This child is sent only when the servent issuing the hit is firewalled.

=== Payload ===

There is no payload defined.

=== Children ===

This packet has no known children at the current time.

== /QH2/GU - Node GUID ==

Specifies the GUID of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The GUID of the sending node.

=== Children ===

This packet has no known children at the current time.

== /QH2/NA - Node Address ==

Specifies the node / network address of the sending node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

The node / network address of the sending node. See datatypes for more
information.

=== Children ===

This packet has no known children at the current time.

== /QH2/NH - Neighbouring Hub ==

Lists a hub to which the sending node (a leaf) is connected. This provides a contact
point for routing communications to a possibly firewalled leaf node.

=== Sending ===

This child is optional, and may appear more than once.

=== Payload ===

The node / network address of a hub to which the sending node is connected.

=== Children ===

This packet has no known children at the current time.

== /QH2/V - Vendor Code ==

Identifies the software operating the sending node.

=== Sending ===

This child is optional.

=== Payload ===

A four character vendor code.

=== Children ===

This packet has no known children at the current time.

== /QH2/BUP - Browse User Profile Tag ==

Indicates that the sending node supports browsing the local user profile.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/PCH - Peer Chat Tag ==

Indicates that the sending node supports person to person private message chat.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/HG - Hit Group Descriptor ==

Describes a group of search results.

=== Sending ===

This child is optional and may appear more than once.

=== Payload ===

A single byte, the group ID number.

=== Children ===

This packet has one child packet type currently defined:

* SS - Server State

=== /QH2/HG/SS - Server State ===

Provides a status snapshot of the upload server that applies to search results in the
current hit group.

==== Sending ====

Add this child to the hit group descriptor to provide server state information.

==== Receiving ====

Use this information when interpreting hits linked with this hit group.

==== Payload ====

* A 16-bit integer : the current queue length including any active transfers (number waiting plus number transferring)
* An 8-bit integer : the maximum number of concurrent transfers (capacity)
* A 32-bit integer : the speed in kilobits per second for uploads on this server module

==== Children ====

This packet has no known children at the current time.

== /QH2/H - Hit Descriptor ==

Describes a single object which matched the original query.

=== Sending ===

Send a /QH2/H child for each matching object to be included in this /QH2 packet.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has many child packet types defined at the current time, and is often
extended:

* URN - Universal Resource Name
* URL - Universal Resource Location
* DN - Descriptive Name
* MD - Metadata
* SZ - Object Size
* G - Group Identifier
* ID - Object Identifier
* CSC - Cached Source Count
* PART - Partial Availability Marker
* COM - User Comment
* PVU - Preview URL
* ALT - Alternate Locations

=== /QH2/H/URN - Universal Resource Name ===

Specifies a universal resource name which can be used to identify the object.

==== Sending ====

At least one instance of this child is required. Multiple instances are optional.

==== Payload ====

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* '''bitprint''' or '''bp''' - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* '''sha1''' - 20 bytes of SHA1
* '''tree:tiger/''' or '''ttr''' - 24 bytes of tiger-tree root
* '''md5''' - 16 bytes of MD5
* '''ed2k''' - 16 bytes of compound MD4 (ed2k style root hash)

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/URL - Universal Resource Location ===

This child specifies a location where the object being described can be acquired.

==== Sending ====

This child should be sent if it was requested and a URL is available.

==== Receiving ====

If a /QH2/H/URL child was requested but is not present, the sending node may not
have the object. It is valid to advertise information about objects that are not
available.

==== Payload ====

Empty, or a string which represents an absolute URL.

If a URL is provided, that URL should be considered to point to an instance of the
object being described.

If the payload is empty, the sender is indicating that it has the object available
locally. It can be retrieved with an HTTP request using the "uri-res" resolver.

==== Children ====

This packet has no known children at the current time.

=== QH2/H/DN - Descriptive Name (Generic) Criteria ===

The descriptive name for the object, and the object's size.

==== Sending ====

This child should be sent if it was requested and is available.

==== Payload ====

A 32-bit integer indicating the object's size, followed by a string describing it. If a
/QH2/H/SZ child is present, the 32-bit size prefix is omitted here (allowing a larger
64 bit file size).

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/MD - Metadata ===

Provides metadata describing the object.

==== Sending ====

This chid should be sent if it was requested and is available.

==== Payload ====

A string containing XML. The xml header is optional. Standard plural/singular
Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/SZ - Object Size ===

Specifies the size of the object.

==== Sending ====

This child should be sent if DN was requested, and if the size is not to be packed into
the /QH2/H/DN child.

==== Payload ====

A 32-bit or 64-bit integer representing the object size.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/G - Group Identifier ===

Indicates which hit group (/QH2/HG) this hit belongs to. If this child is not present,
the hit belongs to group zero.

==== Sending ====

Send this child if this hit belongs to a hit group other than group zero.

==== Receiving ====

If this child is present, the hit belongs to a hit group other than group zero.

==== Payload ====

A single byte, the hit group ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ID - Object Identifier ===

Specifies a 32-bit integer which uniquely identifies the object on the sender's system.

==== Sending ====

This child is not normally sent for search results. It is used in browse-user responses
to allow objects to be referenced by virtual folder structures.

==== Receiving ====

Use this ID to link objects to virtual folder structures.

==== Payload ====

A 32-bit integer ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/CSC - Cached Source Count ===

Indicates the number of external cached sources known to the sending node.

==== Sending ====

This child is sent if cached sources are available and interest in URLs was expressed
in the query.

==== Payload ====

A 16-bit integer.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PART - Partial Content Tag ===

Indicates that the sending node has only part of the object, and how much it has.

==== Sending ====

This child is sent if a /QH2/H/URL child is present and the URL contains only part of
the object.

==== Payload ====

A 32-bit integer, the number of bytes available.

==== Children ====

This packet has one child packet type defined at the current time:

* MT - Modification Time (payload = 32-bit timestamp)

The ''MT'' child carries the last modification time (UNIX timestamp) of the partial file and can be used to determine whether there has been recent updates made (''hot'' file) or if the file is ''cold'' (not undergoing any downloading activity on the remote side).

=== /QH2/H/COM - User Comment ===

Provides a user review and/or rating for the object.

==== Sending ====

This child is sent if a user comment is available, and comments were requested.

==== Payload ====

An XML string, of the form:

<pre>
<nowiki>
<comment rating="n">
The comment goes here.
</comment>
</nowiki>
</pre>

The rating is an integer 0 <= n <= 5, indicating the number of "stars". The text
may not include HTML, but may include forum-style block codes and emoticon
notation.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PVU - Preview URL ===

Indicates that a preview URL is available for the object. A preview URL will serve a
miniature version of the content.

==== Sending ====

This child is sent if a preview is available.

==== Payload ====

Empty, or an absolute URL.

If a URL is provided, that URL should be considered to point to a preview of the
object being described.

If the payload is empty, the sender is indicating that it has a preview of the object
available locally. It can be retrieved with an HTTP request to the path:

<pre>
<nowiki>
/gnutella/preview/v1?urn:xyz
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ALT - Alternate Locations ===

Supplies alternate download sources for the hit.

==== Sending ====

This child is sent when the query indicated that it wanted alternate locations, via the "A" string in its /Q2/I child.

==== Payload ====

The payload contains a vector of alternate locations, listing IPv4 addresses followed by 16-bit ports, as usual (e.g. the same format used to serialize an "NA" payload), but all the entries are concatenated. Hence, a payload of 24 bytes will indicate that there are 4 entries of 6 bytes each.

These alternate locations are the IP:port addresses of known hosts that can serve the file. These can be G2 hosts or G1 hosts, but there are no differences since the file transfer protocol is identical for both networks.

None of the addresses listed there are for firewalled hosts, so anyone should be able to contact them at their uri-res address, supplying the urn:sha1: value suitable for the resource.

==== Children ====

This packet has no known children at the current time.

== /QH2/MD - Unified Metadata Block ==

Provides metadata describing one or more objects in the packet. This is an
alternative method of delivering metadata, which allows metadata for similar objects
to be grouped together. It is compatible with the unified metadata block format in
Gnutella1.

=== Sending ===

This chid should be sent if it was requested and is available.

=== Payload ===

A string containing one or more XML documents, each beginning with a header.
Standard plural/singular Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application index="0" title="Shareaza"/>
</applications>
<?xml version="1.0"?>
<images xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/image.xsd">
<image index="1" description="Shareaza Logo" width="128" height="128"/>
<image index="2" description="Shareaza Screen Shot" width="1024" height="768"/>
</images>
</nowiki>
</pre>

An additional attribute, "index" is added to each singular entry. The index is a zerobased
integer identifying the Nth /QH2/H child within this /QH2 packet.

=== Children ===

This packet has no known children at the current time.

== /QH2/UPRO - User Profile ==

Delivers a user profile or user profile summary, describing the user operating the
sending node.

=== Sending ===

Send a version of this child if the operating user wishes to list their screen name in
search results.

The current version of this packet contains a summary only, consisting of the
screen/nick name. Future versions may include a more comprehensive XML text
block in the payload.

=== Payload ===

No payload is defined at the current time.

=== Children ===

One child packet type is defined at the current time:

* /QH2/UPRO/NICK - Nick/screen Name

=== /QH2/UPRO/NICK - Nick/Screen Name ===

Specifies the nick/screen name of the user.

==== Payload ====

A string.

==== Children ====

This packet has no known children at the current time.

QH2

2014-02-04T23:43:26Z

Ram: /* Children */ Added missing "FW" child

{{Packets}}

= /QH2 - Query Hit =

The /QH2 Gnutella2 query hit packet contains one or more search result descriptors,
along with information about the node generating the result set. A single node may
generate several /QH2 packets in response to a /[[Q2]] query. Like all Gnutella2
packets, the /QH2 packet is highly extensible.

== Sending ==

Send a /QH2 packet when processing a /[[Q2]] query packet reveals one or more
matching objects. Query hits can be returned directly to the /Q2/UDP return address
in the query, or routed back along the delivery chain. Firewalled leaf nodes are
advised to return /QH2 packets to their connected hub for dispatch, as the hub will
be able to make a reliable delivery.

== Receiving ==

Upon receiving a /QH2 query hit packet, check the query GUID against locally
initiated queries. If it originated elsewhere, increment the route-back hop counter
and forward it to the most appropriate link or UDP endpoint. If it matches a locally
generated query, process the search results.

== Payload ==

A single byte representing the hop count, followed by a 16 byte GUID identifying the
search that produced these results.

== Children ==

This packet has many child packet types defined at the current time:

* FW - Firewalled Servent
* H - Hit Descriptor
* HG - Hit Group Descriptor
* GU - Node GUID
* NA - Node Address
* NH - Neighbouring Hub
* V - Vendor Code
* MD - Unified Metadata Block
* UPRO - User Profile
* BUP - Browse User Profile Tag
* PCH - Peer Chat Tag

== /QH2/GU - Node GUID ==

Specifies the GUID of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The GUID of the sending node.

=== Children ===

This packet has no known children at the current time.

== /QH2/NA - Node Address ==

Specifies the node / network address of the sending node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

The node / network address of the sending node. See datatypes for more
information.

=== Children ===

This packet has no known children at the current time.

== /QH2/NH - Neighbouring Hub ==

Lists a hub to which the sending node (a leaf) is connected. This provides a contact
point for routing communications to a possibly firewalled leaf node.

=== Sending ===

This child is optional, and may appear more than once.

=== Payload ===

The node / network address of a hub to which the sending node is connected.

=== Children ===

This packet has no known children at the current time.

== /QH2/V - Vendor Code ==

Identifies the software operating the sending node.

=== Sending ===

This child is optional.

=== Payload ===

A four character vendor code.

=== Children ===

This packet has no known children at the current time.

== /QH2/BUP - Browse User Profile Tag ==

Indicates that the sending node supports browsing the local user profile.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/PCH - Peer Chat Tag ==

Indicates that the sending node supports person to person private message chat.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/HG - Hit Group Descriptor ==

Describes a group of search results.

=== Sending ===

This child is optional and may appear more than once.

=== Payload ===

A single byte, the group ID number.

=== Children ===

This packet has one child packet type currently defined:

* SS - Server State

=== /QH2/HG/SS - Server State ===

Provides a status snapshot of the upload server that applies to search results in the
current hit group.

==== Sending ====

Add this child to the hit group descriptor to provide server state information.

==== Receiving ====

Use this information when interpreting hits linked with this hit group.

==== Payload ====

* A 16-bit integer : the current queue length including any active transfers (number waiting plus number transferring)
* An 8-bit integer : the maximum number of concurrent transfers (capacity)
* A 32-bit integer : the speed in kilobits per second for uploads on this server module

==== Children ====

This packet has no known children at the current time.

== /QH2/H - Hit Descriptor ==

Describes a single object which matched the original query.

=== Sending ===

Send a /QH2/H child for each matching object to be included in this /QH2 packet.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has many child packet types defined at the current time, and is often
extended:

* URN - Universal Resource Name
* URL - Universal Resource Location
* DN - Descriptive Name
* MD - Metadata
* SZ - Object Size
* G - Group Identifier
* ID - Object Identifier
* CSC - Cached Source Count
* PART - Partial Availability Marker
* COM - User Comment
* PVU - Preview URL
* ALT - Alternate Locations

=== /QH2/H/URN - Universal Resource Name ===

Specifies a universal resource name which can be used to identify the object.

==== Sending ====

At least one instance of this child is required. Multiple instances are optional.

==== Payload ====

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* '''bitprint''' or '''bp''' - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* '''sha1''' - 20 bytes of SHA1
* '''tree:tiger/''' or '''ttr''' - 24 bytes of tiger-tree root
* '''md5''' - 16 bytes of MD5
* '''ed2k''' - 16 bytes of compound MD4 (ed2k style root hash)

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/URL - Universal Resource Location ===

This child specifies a location where the object being described can be acquired.

==== Sending ====

This child should be sent if it was requested and a URL is available.

==== Receiving ====

If a /QH2/H/URL child was requested but is not present, the sending node may not
have the object. It is valid to advertise information about objects that are not
available.

==== Payload ====

Empty, or a string which represents an absolute URL.

If a URL is provided, that URL should be considered to point to an instance of the
object being described.

If the payload is empty, the sender is indicating that it has the object available
locally. It can be retrieved with an HTTP request using the "uri-res" resolver.

==== Children ====

This packet has no known children at the current time.

=== QH2/H/DN - Descriptive Name (Generic) Criteria ===

The descriptive name for the object, and the object's size.

==== Sending ====

This child should be sent if it was requested and is available.

==== Payload ====

A 32-bit integer indicating the object's size, followed by a string describing it. If a
/QH2/H/SZ child is present, the 32-bit size prefix is omitted here (allowing a larger
64 bit file size).

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/MD - Metadata ===

Provides metadata describing the object.

==== Sending ====

This chid should be sent if it was requested and is available.

==== Payload ====

A string containing XML. The xml header is optional. Standard plural/singular
Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/SZ - Object Size ===

Specifies the size of the object.

==== Sending ====

This child should be sent if DN was requested, and if the size is not to be packed into
the /QH2/H/DN child.

==== Payload ====

A 32-bit or 64-bit integer representing the object size.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/G - Group Identifier ===

Indicates which hit group (/QH2/HG) this hit belongs to. If this child is not present,
the hit belongs to group zero.

==== Sending ====

Send this child if this hit belongs to a hit group other than group zero.

==== Receiving ====

If this child is present, the hit belongs to a hit group other than group zero.

==== Payload ====

A single byte, the hit group ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ID - Object Identifier ===

Specifies a 32-bit integer which uniquely identifies the object on the sender's system.

==== Sending ====

This child is not normally sent for search results. It is used in browse-user responses
to allow objects to be referenced by virtual folder structures.

==== Receiving ====

Use this ID to link objects to virtual folder structures.

==== Payload ====

A 32-bit integer ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/CSC - Cached Source Count ===

Indicates the number of external cached sources known to the sending node.

==== Sending ====

This child is sent if cached sources are available and interest in URLs was expressed
in the query.

==== Payload ====

A 16-bit integer.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PART - Partial Content Tag ===

Indicates that the sending node has only part of the object, and how much it has.

==== Sending ====

This child is sent if a /QH2/H/URL child is present and the URL contains only part of
the object.

==== Payload ====

A 32-bit integer, the number of bytes available.

==== Children ====

This packet has one child packet type defined at the current time:

* MT - Modification Time (payload = 32-bit timestamp)

The ''MT'' child carries the last modification time (UNIX timestamp) of the partial file and can be used to determine whether there has been recent updates made (''hot'' file) or if the file is ''cold'' (not undergoing any downloading activity on the remote side).

=== /QH2/H/COM - User Comment ===

Provides a user review and/or rating for the object.

==== Sending ====

This child is sent if a user comment is available, and comments were requested.

==== Payload ====

An XML string, of the form:

<pre>
<nowiki>
<comment rating="n">
The comment goes here.
</comment>
</nowiki>
</pre>

The rating is an integer 0 <= n <= 5, indicating the number of "stars". The text
may not include HTML, but may include forum-style block codes and emoticon
notation.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PVU - Preview URL ===

Indicates that a preview URL is available for the object. A preview URL will serve a
miniature version of the content.

==== Sending ====

This child is sent if a preview is available.

==== Payload ====

Empty, or an absolute URL.

If a URL is provided, that URL should be considered to point to a preview of the
object being described.

If the payload is empty, the sender is indicating that it has a preview of the object
available locally. It can be retrieved with an HTTP request to the path:

<pre>
<nowiki>
/gnutella/preview/v1?urn:xyz
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ALT - Alternate Locations ===

Supplies alternate download sources for the hit.

==== Sending ====

This child is sent when the query indicated that it wanted alternate locations, via the "A" string in its /Q2/I child.

==== Payload ====

The payload contains a vector of alternate locations, listing IPv4 addresses followed by 16-bit ports, as usual (e.g. the same format used to serialize an "NA" payload), but all the entries are concatenated. Hence, a payload of 24 bytes will indicate that there are 4 entries of 6 bytes each.

These alternate locations are the IP:port addresses of known hosts that can serve the file. These can be G2 hosts or G1 hosts, but there are no differences since the file transfer protocol is identical for both networks.

None of the addresses listed there are for firewalled hosts, so anyone should be able to contact them at their uri-res address, supplying the urn:sha1: value suitable for the resource.

==== Children ====

This packet has no known children at the current time.

== /QH2/MD - Unified Metadata Block ==

Provides metadata describing one or more objects in the packet. This is an
alternative method of delivering metadata, which allows metadata for similar objects
to be grouped together. It is compatible with the unified metadata block format in
Gnutella1.

=== Sending ===

This chid should be sent if it was requested and is available.

=== Payload ===

A string containing one or more XML documents, each beginning with a header.
Standard plural/singular Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application index="0" title="Shareaza"/>
</applications>
<?xml version="1.0"?>
<images xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/image.xsd">
<image index="1" description="Shareaza Logo" width="128" height="128"/>
<image index="2" description="Shareaza Screen Shot" width="1024" height="768"/>
</images>
</nowiki>
</pre>

An additional attribute, "index" is added to each singular entry. The index is a zerobased
integer identifying the Nth /QH2/H child within this /QH2 packet.

=== Children ===

This packet has no known children at the current time.

== /QH2/UPRO - User Profile ==

Delivers a user profile or user profile summary, describing the user operating the
sending node.

=== Sending ===

Send a version of this child if the operating user wishes to list their screen name in
search results.

The current version of this packet contains a summary only, consisting of the
screen/nick name. Future versions may include a more comprehensive XML text
block in the payload.

=== Payload ===

No payload is defined at the current time.

=== Children ===

One child packet type is defined at the current time:

* /QH2/UPRO/NICK - Nick/screen Name

=== /QH2/UPRO/NICK - Nick/Screen Name ===

Specifies the nick/screen name of the user.

==== Payload ====

A string.

==== Children ====

This packet has no known children at the current time.

Object Search Mechanism

2014-01-31T22:23:12Z

Ram: /* Search Process Walkthrough */ Adding section on performance of searches

== Introduction ==

The distributed object search mechanism is a very important component of the
Gnutella2 architecture. It allows objects distributed throughout the network to be
located by a search client in an optimal fashion, requesting and receiving a subset of
the total information known about that object.

== Model ==

The Gnutella2 object search mechanism is best described as an "iterative crawl" of
the network, with a series of important optimisations derived from the network
topology and components:

* A search client iteratively contacts known hubs with its query
* Hubs match the query against the cached hash tables of their neighbours
* Where a table hit occurs, the query is forwarded once only
* The single injected query thus effectively covers the logical hub cluster, which is the basic searchable unit
* Nodes which actually receive the filtered query process it and send results to the search client directly

This model has a number of important advantages:

* Wide network coverage is provided by iterative query injection
* Effective leaf density is increased by querying hub clusters rather than single hubs or even single nodes
* Mutual and two-level filtering and static link compression are leveraged
* The load on each hub cluster is spread equally between its member hubs, providing a larger search base with a lower cost on the aggregation points
* Hubs need a greater inbound bandwidth capacity than outbound bandwidth capacity, which ideally suits asymmetric Internet connections

== Search Process Walkthrough ==

When a search client wishes to execute a new search, the following events happen:

* The search client selects an eligible hub from its global hub cache which has a recent timestamp, has not been contacted more recently than it allows, and has not yet been queried in this search.
* If a query key is not yet available for this hub, a query key request is dispatched.
* Once a query key is available, the search client sends a keyed query to the hub.
* Upon receiving the query, the hub checks the query key for validity.
* The hub then responds with a query acknowledgement packet, containing a list of neighbouring hubs which have now been searched and a list of 2-hop hubs which have not yet been searched.
* The search client adds the list of searched hubs to its "don't try again" list, and adds the list of "try hubs" to the global hub cache for future selection.
* Meanwhile, the hub examines the query to make sure that it has not received it before. Duplicate queries are dropped.
* The hub then matches the query against the query hash table of all connected nodes, and sends it to those nodes which may be able to field a match.
* While this is occurring, the hub processes the query locally and returns any results it may have.
* Leaves directly attached to the hub which have a potential match will have received the query, and process it locally. They may elect to return results directly to the search client, or may return their results to their hub for dispatch.
* Other hubs in the hub cluster which received the query now examine it to ensure they have not processed it before. They do not send an acknowledgement.
* Assuming it is new, the hubs match the query against the query hash tables of their leaves but not their neighbouring hubs. Potential leaves receive a copy of the query, and the hub processes it locally.
* Once again, the hub returns its own results and may forward results for its leaves if they do not wish to dispatch them directly.
* Meanwhile, the search client receives any search results generated by the hub cluster.
* The search client makes a decision on whether it should continue its search. If so, the process starts again.
* The search client will not requery any of the hubs in the hub cluster, but it has a list of nearby hubs so that the crawl can continue.

== Performance Considerations ==

Hubs should acknowledge /Q2 messages as quickly as possible with a /QA and not wait 5 or 10 minutes to reply. Why? Because the querying host is probably going to timeout, assuming the remote hub is off or too busy, and will start querying other hosts... which may already have been queried by the hub. This creates a nasty ''avalanche effect'' whereby busy hubs get extra traffic to acknowledge, causing them to further delay responses and therefore cause more useless querying.

The '''more delay''' there is between sending of a /Q2 and acknowledging it via a /QA, the '''less effective''' the hub clustering topology will be.

QKA

2014-01-27T22:12:42Z

Ram: /* Payload */ Pinpoint a G2 protocol design mistake

{{Packets}}

= /QKA - Query Key Answer =

The query key answer packet is sent in response to a [[QKR|query key request]] or in the
event that a query with an incorrect or omitted query key is received. It advises the
receiver of the correct query key to be used when contacting the sending hub to
execute a remote cluster query.

== Sending ==

The query key answer packet should be sent by a hub when a query key has been
requested. It should contain a key unique to the local hub and the requesting node
address supplied in the request, and should be sent to that address only.
The query key answer packet may also be sent upon receiving a query with a
missing or invalid query key. In this case no query should be performed.

== Receiving ==

Upon receiving a query key answer packet, the supplied query key should be stored
for later use. If the answer packet contains a sending node address (/QKA/SNA) child
which does not match the local node address, it may be forwarded to a connected
leaf node via TCP with a matching address. In the forwarding case, a query node
address (/QKA/QNA) child is added prior to forwarding to retain the remote (queried)
hub's address.

== Payload ==

This packet has no payload at the current time.

'''Note''' from ''Raphael Manfredi'': there is a protocol design ''mistake'' here: when the /QKA message is sent back by a hub because the /Q2 did not contain a valid query key, the MUID of the faulty /Q2 should be inserted here as payload, in order to let the querying party know which /Q2 was rejected.

It is OK however to have an empty payload when replying to a /QKR.

== Children ==

The QKA packet has these child packets defined at the current time:

* /QKA/QK
* /QKA/SNA
* /QKA/QNA
* /QKA/CACHED

== /QKA/QK - Query Key ==

The /QKA/QK child contains the query key that was requested.

=== Sending ===

This child is required if a key is being issued. Sending a /QKA without a /QKA/QK
indicates that the hub does not wish to authorise the requesting node to query it or
its cluster.

=== Payload ===

A 32-bit query key which is unique to the hub and the sending node address.

=== Children ===

This packet has no known children at the current time.

== /QKA/SNA - Sending Node Address ==

This child specifies the node address for which the key has been issued. This is not
necessarily the node that physically transmitted the key request or the query.

=== Sending ===

This child is required.

=== Payload ===

The node address (with port number optional) of the node which requested the
query key.

=== Children ===

This packet has no known children at the current time.

== /QKA/QNA - Queried Node Address ==

If this query key answer packet has been forwarded to a firewalled leaf from a
connected hub, a /QKA/QNA child will have been added to indicate the address of
the remote hub from which the query key has been issued.

=== Sending ===

This child should be added by a hub when relaying a received query key answer on
to a leaf via TCP.

=== Receiving ===

If this child is present, the query key answer should be treated as if it originated
from the stored address rather than the TCP neighbour.

=== Payload ===

The node address (with port number optional) of the remote hub.

=== Children ===

This packet has no known children at the current time.

== /QKA/CACHED - Query Key Cached ==

Indicates that the query key returned was retrieved from cache.

=== Sending ===

This packet should be added by a hub in response to a /QKR/QNA over TCP from a leaf.

=== Receiving ===

Indicates to the leaf that the query key in the response was retrieved from cache.

=== Payload ===

This packet has no payload at the current time.

=== Children ===

This packet has no known children at the current time.

Q2

2014-01-27T15:45:24Z

Ram: /* /Q2/UDP - Return Address and Authentication */ Make it clear that leaf nodes must ignore query keys in /Q2/UDP.

{{Packets}}

= /Q2 - Gnutella2 Query =

The /Q2 packet is the generic Gnutella2 object query descriptor. It contains search
criteria, identification, authentication, return addressing and the type of information
the search client is interested in.

== Sending ==

A node should send a /Q2 packet to another node when it wishes to execute a query
on that node (and its searchable relations).
/Q2 packets should always be filtered against a query hash table if one is available
for the outbound link.

== Receiving ==

Upon receiving a query, a node should:

* Verify its authentication
* Send an acknowledgment if it was not received from a hub
* Forward it to connected nodes if necessary (detailed below)
* Process it locally and dispatch results

== Forwarding ==

Forwarding of /Q2 packets is achieved based on fixed rules:

* A query received from a leaf or via UDP is forwarded to all connected nodes
* A query received from a hub is forwarded to connected leaves only

== Payload ==

The payload of a /Q2 packet consists of a GUID which uniquely identifies the search
operation.

== Children ==

This packet has many defined child packet types at the current time:
* /Q2/UDP - Return Address and Authentication
* /Q2/URN - Universal Resource Name
* /Q2/DN - Descriptive Name (Generic) Criteria
* /Q2/MD - Metadata Criteria
* /Q2/SZR - Object Size Restriction Criteria
* /Q2/I - Interest

== /Q2/UDP - Return Address and Authentication ==

The /Q2/UDP child packet specifies the return address to be used for all direct
replies, and the query key authentication which authorises transmissions to this
address. If the query key is invalid, the query should be discarded and a valid query
key issued to the nominated address (if desired).

The query key is only checked by hubs receiving the query via UDP. Leaf nodes '''must ignore''' any query key held here.

=== Sending ===

This child is required if the query is to be delivered via UDP. It is optional if delivered
via TCP: if not included, replies will be reverse forwarded via TCP.

=== Receiving ===

If this child is present, all replies should be directed to the nominated address. The
query key should be verified (by hubs only) before replying.

=== Payload ===

A network address (variable length) followed by a query key (fixed length of 32 bits).

=== Children ===

This packet has no known children at the current time.

== /Q2/URN - Universal Resource Name ==

The /Q2/URN child specifies an exact universal resource name which will match the
query. Rules:

* If one or more URNs are present in a query, whether or not they are understood, matching must occur on URN only and other criteria should be ignored.
* If multiple URNs are present, only one need match an object for it to be considered a match for the query.
* Following from the above, multiple URNs of the same family may be specified and match multiple objects (this allows a compound query for several known objects to be executed in one packet).

=== Sending ===

This child should be added if a specific URN is being sought.

=== Payload ===

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* bitprint or bp - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* sha1 - 20 bytes of SHA1
* tree:tiger/ or ttr - 24 bytes of tiger-tree root
* md5 - 16 bytes of MD5
* ed2k - 16 bytes of compound MD4 (ed2k style root hash)

=== Children ===

This packet has no known children at the current time.

== /Q2/DN - Descriptive Name (Generic) Criteria ==

The descriptive name child provides generic query text to be used in matching
objects.

=== Payload ===

A string in the simple query language.

=== Children ===

This packet has no known children at the current time.

== /Q2/MD - Metadata Criteria ==

The metadata child provides an XML document containing rich query information.
The schema identified in the XML must match a metadata schema of prospective
matching objects.

=== Payload ===

A string containing XML. The header is optional. Standard plural/singular Gnutella
metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

All string values are in simple query language, including XML attribute and element
values.

=== Children ===

This packet has no known children at the current time.

== /Q2/SZR - Size Restriction Criteria ==

The size restriction criteria specify a minimum and maximum size for matching
objects.

=== Payload ===

A minimum size followed by a maximum size, both quoted in bytes. These two
numbers may be expressed as two 32 bit integers or two 64 bit integers.

=== Children ===

This packet has no known children at the current time.

== /Q2/I - Interest ==

The Interest packet advertises an interest in certain information classes, effectively
filtering the information that will be returned about matching objects.

=== Sending ===

Send an interest packet to restrict the type of information that will be returned about
matching objects. For example if querying only to find instances of a known object,
advertise interest for "URL" only. Omitting the interest packet produces a default set
of response information.

=== Receiving ===

If an interest packet is received, only return the requested information types. If no
interest packet is present, return all available information that is feasible. Extensions
may be withheld.

=== Payload ===

An array of strings identifying information classes. The following are defined:

* URL - Locations where matching objects can be found
* DN - Descriptive names of matching objects
* MD - Full metadata of matching objects
* COM - User comments, ratings and reviews of matching objects
* PFS - Partially available objects
* A - Requests alternate download sources, returned in /QH2/H/ALT.

Note that default URNs are always supplied and need not be requested.

=== Children ===

This packet has no known children at the current time.

QA

2014-01-26T11:20:03Z

Ram: /* Sending */ Typo fix

{{Packets}}

= /QA - Query Acknowledgement =

The query acknowledgement packet is used to inform a search client that a target
hub has received its [[Q2|query]] and is processing it. It also provides information for the
search client's hub cache, expanding knowledge of the network and ensuring hubs
are not searched more than once in a given query.

== Sending ==

Send a query acknowledgement packet only when operating in hub mode, and only
when the query was not received from a hub via a TCP link. Acknowledgements
should only be sent after verifying the query key authentication.

== Receiving ==

When a query acknowledgement is received, update the local hub cache as
necessary:

* Hubs which have been searched should not be sent this query again
* New suggested hubs should be added and refreshed
* Any "back-off" time should be recorded and honoured.

== Payload ==

A GUID identifying the query being acknowledged.

== Children ==

This packet has several child packet types defined at the current time:

* /QA/TS - Timestamp
* /QA/D - "Done" or Completed Hub
* /QA/S - "Search" or New Hub
* /QA/RA - Retry After
* /QA/FR - From Address

== /QA/TS - Timestamp ==

The /QA/TS child provides a timestamp representing the current universal time at the
sending node. This can be used as a reference when considering other timestamps in
the packet, allowing them to be adjusted to eliminate differences between the time
setting on the local and remote node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

A 32-bit integer representing the current UNIX time, or time(NULL).

=== Children ===

This packet has no known children at the current time.

== /QA/D - Done Hub ==

References a hub which has now been queried, and should not be queried again.

=== Sending ===

Send a /QA/D child for the local hub and each neighbouring hub, whether or not the
hub has actually forwarded the query. If a hub has not forwarded the query, it was
still effectively searched as the QHT indicated it could not find a matching object.

=== Receiving ===

Upon receiving a /QA/D child, add the hub to the cache, freshen its timestamp and
mark it as queried in this search. Do not query this node again for several minutes.

=== Payload ===

A network/node address followed by a 16-bit leaf count.

=== Children ===

This packet has no known children at the current time.

== /QA/S - Search Hub ==

References a hub which was not searched in this operation, but could be searched
later if it has not already been touched.

=== Sending ===

Send a /QA/S child for every unique hub in the local hub cluster which is not a direct
neighbour. Optionally select some recent cached hubs and send /QA/S children for
them also, to make up at least 10 in total.

=== Receiving ===

Upon receiving a /QA/S child, add the hub to the cache and/or freshen its
timestamp.

=== Payload ===

A network/node address, optionally followed by a 32-bit last-seen timestamp. This
makes detecting the address family slightly harder, but the compactness is
worthwhile. Timestamps are omitted for hubs in the local hub cluster, which should
make up the majority.

=== Children ===

This packet has no known children at the current time.

== /QA/RA - Retry After ==

Advises the search client that the hub does not wish to be contacted again for a
specified period of time. Queries earlier than this time may result in a longer-term
ban.

=== Sending ===

Send this child, with or without executing the search if the hub's resources are
becoming saturated. It provides an indirect means of flow control.

=== Receiving ===

Upon receiving a /QA/RA child, record the retry after interval and do not send any
requests to the hub until the period has expired.

=== Payload ===

A 16 bit or 32 bit integer specifying the delay in seconds until the hub may be
contacted again.

=== Children ===

This packet has no known children at the current time.

== /QA/FR - From Address ==

This child is used when a query acknowledgement is forwarded from a proxy hub to
a firewalled leaf node. It advises the leaf of the original sender.

=== Sending ===

When a hub receives a /QA packet for a search originated by one of its leaves, it
should forward the /QA to the appropriate leaf after adding a /QA/FR child with the
remote hub's network address.

=== Receiving ===

If this child is present and the /QA packet was received via TCP from a local hub, the
node address within should be used as the remote hub's node address. This
information is often reflected in the first /QA/D child, however this is not always
present.

=== Payload ===

A network address which may omit the port number.

=== Children ===

This packet has no known children at the current time.

Q2

2014-01-18T16:49:22Z

Ram: /* Payload */ Documented "A" in the /Q2/I child

{{Packets}}

= /Q2 - Gnutella2 Query =

The /Q2 packet is the generic Gnutella2 object query descriptor. It contains search
criteria, identification, authentication, return addressing and the type of information
the search client is interested in.

== Sending ==

A node should send a /Q2 packet to another node when it wishes to execute a query
on that node (and its searchable relations).
/Q2 packets should always be filtered against a query hash table if one is available
for the outbound link.

== Receiving ==

Upon receiving a query, a node should:

* Verify its authentication
* Send an acknowledgment if it was not received from a hub
* Forward it to connected nodes if necessary (detailed below)
* Process it locally and dispatch results

== Forwarding ==

Forwarding of /Q2 packets is achieved based on fixed rules:

* A query received from a leaf or via UDP is forwarded to all connected nodes
* A query received from a hub is forwarded to connected leaves only

== Payload ==

The payload of a /Q2 packet consists of a GUID which uniquely identifies the search
operation.

== Children ==

This packet has many defined child packet types at the current time:
* /Q2/UDP - Return Address and Authentication
* /Q2/URN - Universal Resource Name
* /Q2/DN - Descriptive Name (Generic) Criteria
* /Q2/MD - Metadata Criteria
* /Q2/SZR - Object Size Restriction Criteria
* /Q2/I - Interest

== /Q2/UDP - Return Address and Authentication ==

The /Q2/UDP child packet specifies the return address to be used for all direct
replies, and the query key authentication which authorises transmissions to this
address. If the query key is invalid, the query should be discarded and a valid query
key issued to the nominated address (if desired).

=== Sending ===

This child is required if the query is to be delivered via UDP. It is optional if delivered
via TCP: if not included, replies will be reverse forwarded via TCP.

=== Receiving ===

If this child is present, all replies should be directed to the nominated address. The
query key should be verified before replying.

=== Payload ===

A network address (variable length) followed by a query key (fixed length of 32 bits).

=== Children ===

This packet has no known children at the current time.

== /Q2/URN - Universal Resource Name ==

The /Q2/URN child specifies an exact universal resource name which will match the
query. Rules:

* If one or more URNs are present in a query, whether or not they are understood, matching must occur on URN only and other criteria should be ignored.
* If multiple URNs are present, only one need match an object for it to be considered a match for the query.
* Following from the above, multiple URNs of the same family may be specified and match multiple objects (this allows a compound query for several known objects to be executed in one packet).

=== Sending ===

This child should be added if a specific URN is being sought.

=== Payload ===

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* bitprint or bp - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* sha1 - 20 bytes of SHA1
* tree:tiger/ or ttr - 24 bytes of tiger-tree root
* md5 - 16 bytes of MD5
* ed2k - 16 bytes of compound MD4 (ed2k style root hash)

=== Children ===

This packet has no known children at the current time.

== /Q2/DN - Descriptive Name (Generic) Criteria ==

The descriptive name child provides generic query text to be used in matching
objects.

=== Payload ===

A string in the simple query language.

=== Children ===

This packet has no known children at the current time.

== /Q2/MD - Metadata Criteria ==

The metadata child provides an XML document containing rich query information.
The schema identified in the XML must match a metadata schema of prospective
matching objects.

=== Payload ===

A string containing XML. The header is optional. Standard plural/singular Gnutella
metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

All string values are in simple query language, including XML attribute and element
values.

=== Children ===

This packet has no known children at the current time.

== /Q2/SZR - Size Restriction Criteria ==

The size restriction criteria specify a minimum and maximum size for matching
objects.

=== Payload ===

A minimum size followed by a maximum size, both quoted in bytes. These two
numbers may be expressed as two 32 bit integers or two 64 bit integers.

=== Children ===

This packet has no known children at the current time.

== /Q2/I - Interest ==

The Interest packet advertises an interest in certain information classes, effectively
filtering the information that will be returned about matching objects.

=== Sending ===

Send an interest packet to restrict the type of information that will be returned about
matching objects. For example if querying only to find instances of a known object,
advertise interest for "URL" only. Omitting the interest packet produces a default set
of response information.

=== Receiving ===

If an interest packet is received, only return the requested information types. If no
interest packet is present, return all available information that is feasible. Extensions
may be withheld.

=== Payload ===

An array of strings identifying information classes. The following are defined:

* URL - Locations where matching objects can be found
* DN - Descriptive names of matching objects
* MD - Full metadata of matching objects
* COM - User comments, ratings and reviews of matching objects
* PFS - Partially available objects
* A - Requests alternate download sources, returned in /QH2/H/ALT.

Note that default URNs are always supplied and need not be requested.

=== Children ===

This packet has no known children at the current time.

QH2

2014-01-18T16:47:29Z

Ram: /* /QH2/H - Hit Descriptor */ Documented /QH2/H/ALT

{{Packets}}

= /QH2 - Query Hit =

The /QH2 Gnutella2 query hit packet contains one or more search result descriptors,
along with information about the node generating the result set. A single node may
generate several /QH2 packets in response to a /[[Q2]] query. Like all Gnutella2
packets, the /QH2 packet is highly extensible.

== Sending ==

Send a /QH2 packet when processing a /[[Q2]] query packet reveals one or more
matching objects. Query hits can be returned directly to the /Q2/UDP return address
in the query, or routed back along the delivery chain. Firewalled leaf nodes are
advised to return /QH2 packets to their connected hub for dispatch, as the hub will
be able to make a reliable delivery.

== Receiving ==

Upon receiving a /QH2 query hit packet, check the query GUID against locally
initiated queries. If it originated elsewhere, increment the route-back hop counter
and forward it to the most appropriate link or UDP endpoint. If it matches a locally
generated query, process the search results.

== Payload ==

A single byte representing the hop count, followed by a 16 byte GUID identifying the
search that produced these results.

== Children ==

This packet has many child packet types defined at the current time:

* H - Hit Descriptor
* HG - Hit Group Descriptor
* GU - Node GUID
* NA - Node Address
* NH - Neighbouring Hub
* V - Vendor Code
* MD - Unified Metadata Block
* UPRO - User Profile
* BUP - Browse User Profile Tag
* PCH - Peer Chat Tag

== /QH2/GU - Node GUID ==

Specifies the GUID of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The GUID of the sending node.

=== Children ===

This packet has no known children at the current time.

== /QH2/NA - Node Address ==

Specifies the node / network address of the sending node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

The node / network address of the sending node. See datatypes for more
information.

=== Children ===

This packet has no known children at the current time.

== /QH2/NH - Neighbouring Hub ==

Lists a hub to which the sending node (a leaf) is connected. This provides a contact
point for routing communications to a possibly firewalled leaf node.

=== Sending ===

This child is optional, and may appear more than once.

=== Payload ===

The node / network address of a hub to which the sending node is connected.

=== Children ===

This packet has no known children at the current time.

== /QH2/V - Vendor Code ==

Identifies the software operating the sending node.

=== Sending ===

This child is optional.

=== Payload ===

A four character vendor code.

=== Children ===

This packet has no known children at the current time.

== /QH2/BUP - Browse User Profile Tag ==

Indicates that the sending node supports browsing the local user profile.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/PCH - Peer Chat Tag ==

Indicates that the sending node supports person to person private message chat.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/HG - Hit Group Descriptor ==

Describes a group of search results.

=== Sending ===

This child is optional and may appear more than once.

=== Payload ===

A single byte, the group ID number.

=== Children ===

This packet has one child packet type currently defined:

* SS - Server State

=== /QH2/HG/SS - Server State ===

Provides a status snapshot of the upload server that applies to search results in the
current hit group.

==== Sending ====

Add this child to the hit group descriptor to provide server state information.

==== Receiving ====

Use this information when interpreting hits linked with this hit group.

==== Payload ====

* A 16-bit integer : the current queue length including any active transfers (number waiting plus number transferring)
* An 8-bit integer : the maximum number of concurrent transfers (capacity)
* A 32-bit integer : the speed in kilobits per second for uploads on this server module

==== Children ====

This packet has no known children at the current time.

== /QH2/H - Hit Descriptor ==

Describes a single object which matched the original query.

=== Sending ===

Send a /QH2/H child for each matching object to be included in this /QH2 packet.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has many child packet types defined at the current time, and is often
extended:

* URN - Universal Resource Name
* URL - Universal Resource Location
* DN - Descriptive Name
* MD - Metadata
* SZ - Object Size
* G - Group Identifier
* ID - Object Identifier
* CSC - Cached Source Count
* PART - Partial Availability Marker
* COM - User Comment
* PVU - Preview URL
* ALT - Alternate Locations

=== /QH2/H/URN - Universal Resource Name ===

Specifies a universal resource name which can be used to identify the object.

==== Sending ====

At least one instance of this child is required. Multiple instances are optional.

==== Payload ====

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* '''bitprint''' or '''bp''' - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* '''sha1''' - 20 bytes of SHA1
* '''tree:tiger/''' or '''ttr''' - 24 bytes of tiger-tree root
* '''md5''' - 16 bytes of MD5
* '''ed2k''' - 16 bytes of compound MD4 (ed2k style root hash)

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/URL - Universal Resource Location ===

This child specifies a location where the object being described can be acquired.

==== Sending ====

This child should be sent if it was requested and a URL is available.

==== Receiving ====

If a /QH2/H/URL child was requested but is not present, the sending node may not
have the object. It is valid to advertise information about objects that are not
available.

==== Payload ====

Empty, or a string which represents an absolute URL.

If a URL is provided, that URL should be considered to point to an instance of the
object being described.

If the payload is empty, the sender is indicating that it has the object available
locally. It can be retrieved with an HTTP request using the "uri-res" resolver.

==== Children ====

This packet has no known children at the current time.

=== QH2/H/DN - Descriptive Name (Generic) Criteria ===

The descriptive name for the object, and the object's size.

==== Sending ====

This child should be sent if it was requested and is available.

==== Payload ====

A 32-bit integer indicating the object's size, followed by a string describing it. If a
/QH2/H/SZ child is present, the 32-bit size prefix is omitted here (allowing a larger
64 bit file size).

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/MD - Metadata ===

Provides metadata describing the object.

==== Sending ====

This chid should be sent if it was requested and is available.

==== Payload ====

A string containing XML. The xml header is optional. Standard plural/singular
Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/SZ - Object Size ===

Specifies the size of the object.

==== Sending ====

This child should be sent if DN was requested, and if the size is not to be packed into
the /QH2/H/DN child.

==== Payload ====

A 32-bit or 64-bit integer representing the object size.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/G - Group Identifier ===

Indicates which hit group (/QH2/HG) this hit belongs to. If this child is not present,
the hit belongs to group zero.

==== Sending ====

Send this child if this hit belongs to a hit group other than group zero.

==== Receiving ====

If this child is present, the hit belongs to a hit group other than group zero.

==== Payload ====

A single byte, the hit group ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ID - Object Identifier ===

Specifies a 32-bit integer which uniquely identifies the object on the sender's system.

==== Sending ====

This child is not normally sent for search results. It is used in browse-user responses
to allow objects to be referenced by virtual folder structures.

==== Receiving ====

Use this ID to link objects to virtual folder structures.

==== Payload ====

A 32-bit integer ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/CSC - Cached Source Count ===

Indicates the number of external cached sources known to the sending node.

==== Sending ====

This child is sent if cached sources are available and interest in URLs was expressed
in the query.

==== Payload ====

A 16-bit integer.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PART - Partial Content Tag ===

Indicates that the sending node has only part of the object, and how much it has.

==== Sending ====

This child is sent if a /QH2/H/URL child is present and the URL contains only part of
the object.

==== Payload ====

A 32-bit integer, the number of bytes available.

==== Children ====

This packet has one child packet type defined at the current time:

* MT - Modification Time (payload = 32-bit timestamp)

The ''MT'' child carries the last modification time (UNIX timestamp) of the partial file and can be used to determine whether there has been recent updates made (''hot'' file) or if the file is ''cold'' (not undergoing any downloading activity on the remote side).

=== /QH2/H/COM - User Comment ===

Provides a user review and/or rating for the object.

==== Sending ====

This child is sent if a user comment is available, and comments were requested.

==== Payload ====

An XML string, of the form:

<pre>
<nowiki>
<comment rating="n">
The comment goes here.
</comment>
</nowiki>
</pre>

The rating is an integer 0 <= n <= 5, indicating the number of "stars". The text
may not include HTML, but may include forum-style block codes and emoticon
notation.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PVU - Preview URL ===

Indicates that a preview URL is available for the object. A preview URL will serve a
miniature version of the content.

==== Sending ====

This child is sent if a preview is available.

==== Payload ====

Empty, or an absolute URL.

If a URL is provided, that URL should be considered to point to a preview of the
object being described.

If the payload is empty, the sender is indicating that it has a preview of the object
available locally. It can be retrieved with an HTTP request to the path:

<pre>
<nowiki>
/gnutella/preview/v1?urn:xyz
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ALT - Alternate Locations ===

Supplies alternate download sources for the hit.

==== Sending ====

This child is sent when the query indicated that it wanted alternate locations, via the "A" string in its /Q2/I child.

==== Payload ====

The payload contains a vector of alternate locations, listing IPv4 addresses followed by 16-bit ports, as usual (e.g. the same format used to serialize an "NA" payload), but all the entries are concatenated. Hence, a payload of 24 bytes will indicate that there are 4 entries of 6 bytes each.

These alternate locations are the IP:port addresses of known hosts that can serve the file. These can be G2 hosts or G1 hosts, but there are no differences since the file transfer protocol is identical for both networks.

None of the addresses listed there are for firewalled hosts, so anyone should be able to contact them at their uri-res address, supplying the urn:sha1: value suitable for the resource.

==== Children ====

This packet has no known children at the current time.

== /QH2/MD - Unified Metadata Block ==

Provides metadata describing one or more objects in the packet. This is an
alternative method of delivering metadata, which allows metadata for similar objects
to be grouped together. It is compatible with the unified metadata block format in
Gnutella1.

=== Sending ===

This chid should be sent if it was requested and is available.

=== Payload ===

A string containing one or more XML documents, each beginning with a header.
Standard plural/singular Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application index="0" title="Shareaza"/>
</applications>
<?xml version="1.0"?>
<images xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/image.xsd">
<image index="1" description="Shareaza Logo" width="128" height="128"/>
<image index="2" description="Shareaza Screen Shot" width="1024" height="768"/>
</images>
</nowiki>
</pre>

An additional attribute, "index" is added to each singular entry. The index is a zerobased
integer identifying the Nth /QH2/H child within this /QH2 packet.

=== Children ===

This packet has no known children at the current time.

== /QH2/UPRO - User Profile ==

Delivers a user profile or user profile summary, describing the user operating the
sending node.

=== Sending ===

Send a version of this child if the operating user wishes to list their screen name in
search results.

The current version of this packet contains a summary only, consisting of the
screen/nick name. Future versions may include a more comprehensive XML text
block in the payload.

=== Payload ===

No payload is defined at the current time.

=== Children ===

One child packet type is defined at the current time:

* /QH2/UPRO/NICK - Nick/screen Name

=== /QH2/UPRO/NICK - Nick/Screen Name ===

Specifies the nick/screen name of the user.

==== Payload ====

A string.

==== Children ====

This packet has no known children at the current time.

QH2

2014-01-18T16:36:44Z

Ram: /* Children */

{{Packets}}

= /QH2 - Query Hit =

The /QH2 Gnutella2 query hit packet contains one or more search result descriptors,
along with information about the node generating the result set. A single node may
generate several /QH2 packets in response to a /[[Q2]] query. Like all Gnutella2
packets, the /QH2 packet is highly extensible.

== Sending ==

Send a /QH2 packet when processing a /[[Q2]] query packet reveals one or more
matching objects. Query hits can be returned directly to the /Q2/UDP return address
in the query, or routed back along the delivery chain. Firewalled leaf nodes are
advised to return /QH2 packets to their connected hub for dispatch, as the hub will
be able to make a reliable delivery.

== Receiving ==

Upon receiving a /QH2 query hit packet, check the query GUID against locally
initiated queries. If it originated elsewhere, increment the route-back hop counter
and forward it to the most appropriate link or UDP endpoint. If it matches a locally
generated query, process the search results.

== Payload ==

A single byte representing the hop count, followed by a 16 byte GUID identifying the
search that produced these results.

== Children ==

This packet has many child packet types defined at the current time:

* H - Hit Descriptor
* HG - Hit Group Descriptor
* GU - Node GUID
* NA - Node Address
* NH - Neighbouring Hub
* V - Vendor Code
* MD - Unified Metadata Block
* UPRO - User Profile
* BUP - Browse User Profile Tag
* PCH - Peer Chat Tag

== /QH2/GU - Node GUID ==

Specifies the GUID of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The GUID of the sending node.

=== Children ===

This packet has no known children at the current time.

== /QH2/NA - Node Address ==

Specifies the node / network address of the sending node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

The node / network address of the sending node. See datatypes for more
information.

=== Children ===

This packet has no known children at the current time.

== /QH2/NH - Neighbouring Hub ==

Lists a hub to which the sending node (a leaf) is connected. This provides a contact
point for routing communications to a possibly firewalled leaf node.

=== Sending ===

This child is optional, and may appear more than once.

=== Payload ===

The node / network address of a hub to which the sending node is connected.

=== Children ===

This packet has no known children at the current time.

== /QH2/V - Vendor Code ==

Identifies the software operating the sending node.

=== Sending ===

This child is optional.

=== Payload ===

A four character vendor code.

=== Children ===

This packet has no known children at the current time.

== /QH2/BUP - Browse User Profile Tag ==

Indicates that the sending node supports browsing the local user profile.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/PCH - Peer Chat Tag ==

Indicates that the sending node supports person to person private message chat.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/HG - Hit Group Descriptor ==

Describes a group of search results.

=== Sending ===

This child is optional and may appear more than once.

=== Payload ===

A single byte, the group ID number.

=== Children ===

This packet has one child packet type currently defined:

* SS - Server State

=== /QH2/HG/SS - Server State ===

Provides a status snapshot of the upload server that applies to search results in the
current hit group.

==== Sending ====

Add this child to the hit group descriptor to provide server state information.

==== Receiving ====

Use this information when interpreting hits linked with this hit group.

==== Payload ====

* A 16-bit integer : the current queue length including any active transfers (number waiting plus number transferring)
* An 8-bit integer : the maximum number of concurrent transfers (capacity)
* A 32-bit integer : the speed in kilobits per second for uploads on this server module

==== Children ====

This packet has no known children at the current time.

== /QH2/H - Hit Descriptor ==

Describes a single object which matched the original query.

=== Sending ===

Send a /QH2/H child for each matching object to be included in this /QH2 packet.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has many child packet types defined at the current time, and is often
extended:

* URN - Universal Resource Name
* URL - Universal Resource Location
* DN - Descriptive Name
* MD - Metadata
* SZ - Object Size
* G - Group Identifier
* ID - Object Identifier
* CSC - Cached Source Count
* PART - Partial Availability Marker
* COM - User Comment
* PVU - Preview URL
* ALT - Alternate Locations

=== /QH2/H/URN - Universal Resource Name ===

Specifies a universal resource name which can be used to identify the object.

==== Sending ====

At least one instance of this child is required. Multiple instances are optional.

==== Payload ====

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* '''bitprint''' or '''bp''' - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* '''sha1''' - 20 bytes of SHA1
* '''tree:tiger/''' or '''ttr''' - 24 bytes of tiger-tree root
* '''md5''' - 16 bytes of MD5
* '''ed2k''' - 16 bytes of compound MD4 (ed2k style root hash)

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/URL - Universal Resource Location ===

This child specifies a location where the object being described can be acquired.

==== Sending ====

This child should be sent if it was requested and a URL is available.

==== Receiving ====

If a /QH2/H/URL child was requested but is not present, the sending node may not
have the object. It is valid to advertise information about objects that are not
available.

==== Payload ====

Empty, or a string which represents an absolute URL.

If a URL is provided, that URL should be considered to point to an instance of the
object being described.

If the payload is empty, the sender is indicating that it has the object available
locally. It can be retrieved with an HTTP request using the "uri-res" resolver.

==== Children ====

This packet has no known children at the current time.

=== QH2/H/DN - Descriptive Name (Generic) Criteria ===

The descriptive name for the object, and the object's size.

==== Sending ====

This child should be sent if it was requested and is available.

==== Payload ====

A 32-bit integer indicating the object's size, followed by a string describing it. If a
/QH2/H/SZ child is present, the 32-bit size prefix is omitted here (allowing a larger
64 bit file size).

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/MD - Metadata ===

Provides metadata describing the object.

==== Sending ====

This chid should be sent if it was requested and is available.

==== Payload ====

A string containing XML. The xml header is optional. Standard plural/singular
Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/SZ - Object Size ===

Specifies the size of the object.

==== Sending ====

This child should be sent if DN was requested, and if the size is not to be packed into
the /QH2/H/DN child.

==== Payload ====

A 32-bit or 64-bit integer representing the object size.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/G - Group Identifier ===

Indicates which hit group (/QH2/HG) this hit belongs to. If this child is not present,
the hit belongs to group zero.

==== Sending ====

Send this child if this hit belongs to a hit group other than group zero.

==== Receiving ====

If this child is present, the hit belongs to a hit group other than group zero.

==== Payload ====

A single byte, the hit group ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ID - Object Identifier ===

Specifies a 32-bit integer which uniquely identifies the object on the sender's system.

==== Sending ====

This child is not normally sent for search results. It is used in browse-user responses
to allow objects to be referenced by virtual folder structures.

==== Receiving ====

Use this ID to link objects to virtual folder structures.

==== Payload ====

A 32-bit integer ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/CSC - Cached Source Count ===

Indicates the number of external cached sources known to the sending node.

==== Sending ====

This child is sent if cached sources are available and interest in URLs was expressed
in the query.

==== Payload ====

A 16-bit integer.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PART - Partial Content Tag ===

Indicates that the sending node has only part of the object, and how much it has.

==== Sending ====

This child is sent if a /QH2/H/URL child is present and the URL contains only part of
the object.

==== Payload ====

A 32-bit integer, the number of bytes available.

==== Children ====

This packet has one child packet type defined at the current time:

* MT - Modification Time (payload = 32-bit timestamp)

The ''MT'' child carries the last modification time (UNIX timestamp) of the partial file and can be used to determine whether there has been recent updates made (''hot'' file) or if the file is ''cold'' (not undergoing any downloading activity on the remote side).

=== /QH2/H/COM - User Comment ===

Provides a user review and/or rating for the object.

==== Sending ====

This child is sent if a user comment is available, and comments were requested.

==== Payload ====

An XML string, of the form:

<pre>
<nowiki>
<comment rating="n">
The comment goes here.
</comment>
</nowiki>
</pre>

The rating is an integer 0 <= n <= 5, indicating the number of "stars". The text
may not include HTML, but may include forum-style block codes and emoticon
notation.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PVU - Preview URL ===

Indicates that a preview URL is available for the object. A preview URL will serve a
miniature version of the content.

==== Sending ====

This child is sent if a preview is available.

==== Payload ====

Empty, or an absolute URL.

If a URL is provided, that URL should be considered to point to a preview of the
object being described.

If the payload is empty, the sender is indicating that it has a preview of the object
available locally. It can be retrieved with an HTTP request to the path:

<pre>
<nowiki>
/gnutella/preview/v1?urn:xyz
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

== /QH2/MD - Unified Metadata Block ==

Provides metadata describing one or more objects in the packet. This is an
alternative method of delivering metadata, which allows metadata for similar objects
to be grouped together. It is compatible with the unified metadata block format in
Gnutella1.

=== Sending ===

This chid should be sent if it was requested and is available.

=== Payload ===

A string containing one or more XML documents, each beginning with a header.
Standard plural/singular Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application index="0" title="Shareaza"/>
</applications>
<?xml version="1.0"?>
<images xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/image.xsd">
<image index="1" description="Shareaza Logo" width="128" height="128"/>
<image index="2" description="Shareaza Screen Shot" width="1024" height="768"/>
</images>
</nowiki>
</pre>

An additional attribute, "index" is added to each singular entry. The index is a zerobased
integer identifying the Nth /QH2/H child within this /QH2 packet.

=== Children ===

This packet has no known children at the current time.

== /QH2/UPRO - User Profile ==

Delivers a user profile or user profile summary, describing the user operating the
sending node.

=== Sending ===

Send a version of this child if the operating user wishes to list their screen name in
search results.

The current version of this packet contains a summary only, consisting of the
screen/nick name. Future versions may include a more comprehensive XML text
block in the payload.

=== Payload ===

No payload is defined at the current time.

=== Children ===

One child packet type is defined at the current time:

* /QH2/UPRO/NICK - Nick/screen Name

=== /QH2/UPRO/NICK - Nick/Screen Name ===

Specifies the nick/screen name of the user.

==== Payload ====

A string.

==== Children ====

This packet has no known children at the current time.

QH2

2014-01-18T16:36:15Z

Ram: /* Children */

{{Packets}}

= /QH2 - Query Hit =

The /QH2 Gnutella2 query hit packet contains one or more search result descriptors,
along with information about the node generating the result set. A single node may
generate several /QH2 packets in response to a /[[Q2]] query. Like all Gnutella2
packets, the /QH2 packet is highly extensible.

== Sending ==

Send a /QH2 packet when processing a /[[Q2]] query packet reveals one or more
matching objects. Query hits can be returned directly to the /Q2/UDP return address
in the query, or routed back along the delivery chain. Firewalled leaf nodes are
advised to return /QH2 packets to their connected hub for dispatch, as the hub will
be able to make a reliable delivery.

== Receiving ==

Upon receiving a /QH2 query hit packet, check the query GUID against locally
initiated queries. If it originated elsewhere, increment the route-back hop counter
and forward it to the most appropriate link or UDP endpoint. If it matches a locally
generated query, process the search results.

== Payload ==

A single byte representing the hop count, followed by a 16 byte GUID identifying the
search that produced these results.

== Children ==

This packet has many child packet types defined at the current time:

* H - Hit Descriptor
* HG - Hit Group Descriptor
* GU - Node GUID
* NA - Node Address
* NH - Neighbouring Hub
* V - Vendor Code
* MD - Unified Metadata Block
* UPRO - User Profile
* BUP - Browse User Profile Tag
* PCH - Peer Chat Tag

== /QH2/GU - Node GUID ==

Specifies the GUID of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The GUID of the sending node.

=== Children ===

This packet has no known children at the current time.

== /QH2/NA - Node Address ==

Specifies the node / network address of the sending node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

The node / network address of the sending node. See datatypes for more
information.

=== Children ===

This packet has no known children at the current time.

== /QH2/NH - Neighbouring Hub ==

Lists a hub to which the sending node (a leaf) is connected. This provides a contact
point for routing communications to a possibly firewalled leaf node.

=== Sending ===

This child is optional, and may appear more than once.

=== Payload ===

The node / network address of a hub to which the sending node is connected.

=== Children ===

This packet has no known children at the current time.

== /QH2/V - Vendor Code ==

Identifies the software operating the sending node.

=== Sending ===

This child is optional.

=== Payload ===

A four character vendor code.

=== Children ===

This packet has no known children at the current time.

== /QH2/BUP - Browse User Profile Tag ==

Indicates that the sending node supports browsing the local user profile.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/PCH - Peer Chat Tag ==

Indicates that the sending node supports person to person private message chat.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/HG - Hit Group Descriptor ==

Describes a group of search results.

=== Sending ===

This child is optional and may appear more than once.

=== Payload ===

A single byte, the group ID number.

=== Children ===

This packet has one child packet type currently defined:

* SS - Server State

=== /QH2/HG/SS - Server State ===

Provides a status snapshot of the upload server that applies to search results in the
current hit group.

==== Sending ====

Add this child to the hit group descriptor to provide server state information.

==== Receiving ====

Use this information when interpreting hits linked with this hit group.

==== Payload ====

* A 16-bit integer : the current queue length including any active transfers (number waiting plus number transferring)
* An 8-bit integer : the maximum number of concurrent transfers (capacity)
* A 32-bit integer : the speed in kilobits per second for uploads on this server module

==== Children ====

This packet has no known children at the current time.

== /QH2/H - Hit Descriptor ==

Describes a single object which matched the original query.

=== Sending ===

Send a /QH2/H child for each matching object to be included in this /QH2 packet.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has many child packet types defined at the current time, and is often
extended:

* URN - Universal Resource Name
* URL - Universal Resource Location
* DN - Descriptive Name
* MD - Metadata
* SZ - Object Size
* G - Group Identifier
* ID - Object Identifier
* CSC - Cached Source Count
* PART - Partial Availability Marker
* COM - User Comment
* PVU - Preview URL

=== /QH2/H/URN - Universal Resource Name ===

Specifies a universal resource name which can be used to identify the object.

==== Sending ====

At least one instance of this child is required. Multiple instances are optional.

==== Payload ====

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* '''bitprint''' or '''bp''' - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* '''sha1''' - 20 bytes of SHA1
* '''tree:tiger/''' or '''ttr''' - 24 bytes of tiger-tree root
* '''md5''' - 16 bytes of MD5
* '''ed2k''' - 16 bytes of compound MD4 (ed2k style root hash)

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/URL - Universal Resource Location ===

This child specifies a location where the object being described can be acquired.

==== Sending ====

This child should be sent if it was requested and a URL is available.

==== Receiving ====

If a /QH2/H/URL child was requested but is not present, the sending node may not
have the object. It is valid to advertise information about objects that are not
available.

==== Payload ====

Empty, or a string which represents an absolute URL.

If a URL is provided, that URL should be considered to point to an instance of the
object being described.

If the payload is empty, the sender is indicating that it has the object available
locally. It can be retrieved with an HTTP request using the "uri-res" resolver.

==== Children ====

This packet has no known children at the current time.

=== QH2/H/DN - Descriptive Name (Generic) Criteria ===

The descriptive name for the object, and the object's size.

==== Sending ====

This child should be sent if it was requested and is available.

==== Payload ====

A 32-bit integer indicating the object's size, followed by a string describing it. If a
/QH2/H/SZ child is present, the 32-bit size prefix is omitted here (allowing a larger
64 bit file size).

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/MD - Metadata ===

Provides metadata describing the object.

==== Sending ====

This chid should be sent if it was requested and is available.

==== Payload ====

A string containing XML. The xml header is optional. Standard plural/singular
Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/SZ - Object Size ===

Specifies the size of the object.

==== Sending ====

This child should be sent if DN was requested, and if the size is not to be packed into
the /QH2/H/DN child.

==== Payload ====

A 32-bit or 64-bit integer representing the object size.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/G - Group Identifier ===

Indicates which hit group (/QH2/HG) this hit belongs to. If this child is not present,
the hit belongs to group zero.

==== Sending ====

Send this child if this hit belongs to a hit group other than group zero.

==== Receiving ====

If this child is present, the hit belongs to a hit group other than group zero.

==== Payload ====

A single byte, the hit group ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ID - Object Identifier ===

Specifies a 32-bit integer which uniquely identifies the object on the sender's system.

==== Sending ====

This child is not normally sent for search results. It is used in browse-user responses
to allow objects to be referenced by virtual folder structures.

==== Receiving ====

Use this ID to link objects to virtual folder structures.

==== Payload ====

A 32-bit integer ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/CSC - Cached Source Count ===

Indicates the number of external cached sources known to the sending node.

==== Sending ====

This child is sent if cached sources are available and interest in URLs was expressed
in the query.

==== Payload ====

A 16-bit integer.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PART - Partial Content Tag ===

Indicates that the sending node has only part of the object, and how much it has.

==== Sending ====

This child is sent if a /QH2/H/URL child is present and the URL contains only part of
the object.

==== Payload ====

A 32-bit integer, the number of bytes available.

==== Children ====

This packet has one child packet type defined at the current time:

* MT - Modification Time (payload = 32-bit timestamp)

The ''MT'' child carries the last modification time (UNIX timestamp) of the partial file and can be used to determine whether there has been recent updates made (''hot'' file) or if the file is ''cold'' (not undergoing any downloading activity on the remote side).

=== /QH2/H/COM - User Comment ===

Provides a user review and/or rating for the object.

==== Sending ====

This child is sent if a user comment is available, and comments were requested.

==== Payload ====

An XML string, of the form:

<pre>
<nowiki>
<comment rating="n">
The comment goes here.
</comment>
</nowiki>
</pre>

The rating is an integer 0 <= n <= 5, indicating the number of "stars". The text
may not include HTML, but may include forum-style block codes and emoticon
notation.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PVU - Preview URL ===

Indicates that a preview URL is available for the object. A preview URL will serve a
miniature version of the content.

==== Sending ====

This child is sent if a preview is available.

==== Payload ====

Empty, or an absolute URL.

If a URL is provided, that URL should be considered to point to a preview of the
object being described.

If the payload is empty, the sender is indicating that it has a preview of the object
available locally. It can be retrieved with an HTTP request to the path:

<pre>
<nowiki>
/gnutella/preview/v1?urn:xyz
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

== /QH2/MD - Unified Metadata Block ==

Provides metadata describing one or more objects in the packet. This is an
alternative method of delivering metadata, which allows metadata for similar objects
to be grouped together. It is compatible with the unified metadata block format in
Gnutella1.

=== Sending ===

This chid should be sent if it was requested and is available.

=== Payload ===

A string containing one or more XML documents, each beginning with a header.
Standard plural/singular Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application index="0" title="Shareaza"/>
</applications>
<?xml version="1.0"?>
<images xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/image.xsd">
<image index="1" description="Shareaza Logo" width="128" height="128"/>
<image index="2" description="Shareaza Screen Shot" width="1024" height="768"/>
</images>
</nowiki>
</pre>

An additional attribute, "index" is added to each singular entry. The index is a zerobased
integer identifying the Nth /QH2/H child within this /QH2 packet.

=== Children ===

This packet has no known children at the current time.

== /QH2/UPRO - User Profile ==

Delivers a user profile or user profile summary, describing the user operating the
sending node.

=== Sending ===

Send a version of this child if the operating user wishes to list their screen name in
search results.

The current version of this packet contains a summary only, consisting of the
screen/nick name. Future versions may include a more comprehensive XML text
block in the payload.

=== Payload ===

No payload is defined at the current time.

=== Children ===

One child packet type is defined at the current time:

* /QH2/UPRO/NICK - Nick/screen Name

=== /QH2/UPRO/NICK - Nick/Screen Name ===

Specifies the nick/screen name of the user.

==== Payload ====

A string.

==== Children ====

This packet has no known children at the current time.

QH2

2014-01-18T16:35:18Z

Ram: /* Children */

{{Packets}}

= /QH2 - Query Hit =

The /QH2 Gnutella2 query hit packet contains one or more search result descriptors,
along with information about the node generating the result set. A single node may
generate several /QH2 packets in response to a /[[Q2]] query. Like all Gnutella2
packets, the /QH2 packet is highly extensible.

== Sending ==

Send a /QH2 packet when processing a /[[Q2]] query packet reveals one or more
matching objects. Query hits can be returned directly to the /Q2/UDP return address
in the query, or routed back along the delivery chain. Firewalled leaf nodes are
advised to return /QH2 packets to their connected hub for dispatch, as the hub will
be able to make a reliable delivery.

== Receiving ==

Upon receiving a /QH2 query hit packet, check the query GUID against locally
initiated queries. If it originated elsewhere, increment the route-back hop counter
and forward it to the most appropriate link or UDP endpoint. If it matches a locally
generated query, process the search results.

== Payload ==

A single byte representing the hop count, followed by a 16 byte GUID identifying the
search that produced these results.

== Children ==

This packet has many child packet types defined at the current time:

* H - Hit Descriptor
* HG - Hit Group Descriptor
* GU - Node GUID
* NA - Node Address
* NH - Neighbouring Hub
* V - Vendor Code
* MD - Unified Metadata Block
* UPRO - User Profile
* BUP - Browse User Profile Tag
* PCH - Peer Chat Tag
* ALT - Alternate Locations

== /QH2/GU - Node GUID ==

Specifies the GUID of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The GUID of the sending node.

=== Children ===

This packet has no known children at the current time.

== /QH2/NA - Node Address ==

Specifies the node / network address of the sending node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

The node / network address of the sending node. See datatypes for more
information.

=== Children ===

This packet has no known children at the current time.

== /QH2/NH - Neighbouring Hub ==

Lists a hub to which the sending node (a leaf) is connected. This provides a contact
point for routing communications to a possibly firewalled leaf node.

=== Sending ===

This child is optional, and may appear more than once.

=== Payload ===

The node / network address of a hub to which the sending node is connected.

=== Children ===

This packet has no known children at the current time.

== /QH2/V - Vendor Code ==

Identifies the software operating the sending node.

=== Sending ===

This child is optional.

=== Payload ===

A four character vendor code.

=== Children ===

This packet has no known children at the current time.

== /QH2/BUP - Browse User Profile Tag ==

Indicates that the sending node supports browsing the local user profile.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/PCH - Peer Chat Tag ==

Indicates that the sending node supports person to person private message chat.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/HG - Hit Group Descriptor ==

Describes a group of search results.

=== Sending ===

This child is optional and may appear more than once.

=== Payload ===

A single byte, the group ID number.

=== Children ===

This packet has one child packet type currently defined:

* SS - Server State

=== /QH2/HG/SS - Server State ===

Provides a status snapshot of the upload server that applies to search results in the
current hit group.

==== Sending ====

Add this child to the hit group descriptor to provide server state information.

==== Receiving ====

Use this information when interpreting hits linked with this hit group.

==== Payload ====

* A 16-bit integer : the current queue length including any active transfers (number waiting plus number transferring)
* An 8-bit integer : the maximum number of concurrent transfers (capacity)
* A 32-bit integer : the speed in kilobits per second for uploads on this server module

==== Children ====

This packet has no known children at the current time.

== /QH2/H - Hit Descriptor ==

Describes a single object which matched the original query.

=== Sending ===

Send a /QH2/H child for each matching object to be included in this /QH2 packet.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has many child packet types defined at the current time, and is often
extended:

* URN - Universal Resource Name
* URL - Universal Resource Location
* DN - Descriptive Name
* MD - Metadata
* SZ - Object Size
* G - Group Identifier
* ID - Object Identifier
* CSC - Cached Source Count
* PART - Partial Availability Marker
* COM - User Comment
* PVU - Preview URL

=== /QH2/H/URN - Universal Resource Name ===

Specifies a universal resource name which can be used to identify the object.

==== Sending ====

At least one instance of this child is required. Multiple instances are optional.

==== Payload ====

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* '''bitprint''' or '''bp''' - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* '''sha1''' - 20 bytes of SHA1
* '''tree:tiger/''' or '''ttr''' - 24 bytes of tiger-tree root
* '''md5''' - 16 bytes of MD5
* '''ed2k''' - 16 bytes of compound MD4 (ed2k style root hash)

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/URL - Universal Resource Location ===

This child specifies a location where the object being described can be acquired.

==== Sending ====

This child should be sent if it was requested and a URL is available.

==== Receiving ====

If a /QH2/H/URL child was requested but is not present, the sending node may not
have the object. It is valid to advertise information about objects that are not
available.

==== Payload ====

Empty, or a string which represents an absolute URL.

If a URL is provided, that URL should be considered to point to an instance of the
object being described.

If the payload is empty, the sender is indicating that it has the object available
locally. It can be retrieved with an HTTP request using the "uri-res" resolver.

==== Children ====

This packet has no known children at the current time.

=== QH2/H/DN - Descriptive Name (Generic) Criteria ===

The descriptive name for the object, and the object's size.

==== Sending ====

This child should be sent if it was requested and is available.

==== Payload ====

A 32-bit integer indicating the object's size, followed by a string describing it. If a
/QH2/H/SZ child is present, the 32-bit size prefix is omitted here (allowing a larger
64 bit file size).

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/MD - Metadata ===

Provides metadata describing the object.

==== Sending ====

This chid should be sent if it was requested and is available.

==== Payload ====

A string containing XML. The xml header is optional. Standard plural/singular
Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/SZ - Object Size ===

Specifies the size of the object.

==== Sending ====

This child should be sent if DN was requested, and if the size is not to be packed into
the /QH2/H/DN child.

==== Payload ====

A 32-bit or 64-bit integer representing the object size.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/G - Group Identifier ===

Indicates which hit group (/QH2/HG) this hit belongs to. If this child is not present,
the hit belongs to group zero.

==== Sending ====

Send this child if this hit belongs to a hit group other than group zero.

==== Receiving ====

If this child is present, the hit belongs to a hit group other than group zero.

==== Payload ====

A single byte, the hit group ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ID - Object Identifier ===

Specifies a 32-bit integer which uniquely identifies the object on the sender's system.

==== Sending ====

This child is not normally sent for search results. It is used in browse-user responses
to allow objects to be referenced by virtual folder structures.

==== Receiving ====

Use this ID to link objects to virtual folder structures.

==== Payload ====

A 32-bit integer ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/CSC - Cached Source Count ===

Indicates the number of external cached sources known to the sending node.

==== Sending ====

This child is sent if cached sources are available and interest in URLs was expressed
in the query.

==== Payload ====

A 16-bit integer.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PART - Partial Content Tag ===

Indicates that the sending node has only part of the object, and how much it has.

==== Sending ====

This child is sent if a /QH2/H/URL child is present and the URL contains only part of
the object.

==== Payload ====

A 32-bit integer, the number of bytes available.

==== Children ====

This packet has one child packet type defined at the current time:

* MT - Modification Time (payload = 32-bit timestamp)

The ''MT'' child carries the last modification time (UNIX timestamp) of the partial file and can be used to determine whether there has been recent updates made (''hot'' file) or if the file is ''cold'' (not undergoing any downloading activity on the remote side).

=== /QH2/H/COM - User Comment ===

Provides a user review and/or rating for the object.

==== Sending ====

This child is sent if a user comment is available, and comments were requested.

==== Payload ====

An XML string, of the form:

<pre>
<nowiki>
<comment rating="n">
The comment goes here.
</comment>
</nowiki>
</pre>

The rating is an integer 0 <= n <= 5, indicating the number of "stars". The text
may not include HTML, but may include forum-style block codes and emoticon
notation.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PVU - Preview URL ===

Indicates that a preview URL is available for the object. A preview URL will serve a
miniature version of the content.

==== Sending ====

This child is sent if a preview is available.

==== Payload ====

Empty, or an absolute URL.

If a URL is provided, that URL should be considered to point to a preview of the
object being described.

If the payload is empty, the sender is indicating that it has a preview of the object
available locally. It can be retrieved with an HTTP request to the path:

<pre>
<nowiki>
/gnutella/preview/v1?urn:xyz
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

== /QH2/MD - Unified Metadata Block ==

Provides metadata describing one or more objects in the packet. This is an
alternative method of delivering metadata, which allows metadata for similar objects
to be grouped together. It is compatible with the unified metadata block format in
Gnutella1.

=== Sending ===

This chid should be sent if it was requested and is available.

=== Payload ===

A string containing one or more XML documents, each beginning with a header.
Standard plural/singular Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application index="0" title="Shareaza"/>
</applications>
<?xml version="1.0"?>
<images xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/image.xsd">
<image index="1" description="Shareaza Logo" width="128" height="128"/>
<image index="2" description="Shareaza Screen Shot" width="1024" height="768"/>
</images>
</nowiki>
</pre>

An additional attribute, "index" is added to each singular entry. The index is a zerobased
integer identifying the Nth /QH2/H child within this /QH2 packet.

=== Children ===

This packet has no known children at the current time.

== /QH2/UPRO - User Profile ==

Delivers a user profile or user profile summary, describing the user operating the
sending node.

=== Sending ===

Send a version of this child if the operating user wishes to list their screen name in
search results.

The current version of this packet contains a summary only, consisting of the
screen/nick name. Future versions may include a more comprehensive XML text
block in the payload.

=== Payload ===

No payload is defined at the current time.

=== Children ===

One child packet type is defined at the current time:

* /QH2/UPRO/NICK - Nick/screen Name

=== /QH2/UPRO/NICK - Nick/Screen Name ===

Specifies the nick/screen name of the user.

==== Payload ====

A string.

==== Children ====

This packet has no known children at the current time.

QH2

2014-01-18T16:33:07Z

Ram: /* Children */ Documented the /QH2/H/PART/MT child

{{Packets}}

= /QH2 - Query Hit =

The /QH2 Gnutella2 query hit packet contains one or more search result descriptors,
along with information about the node generating the result set. A single node may
generate several /QH2 packets in response to a /[[Q2]] query. Like all Gnutella2
packets, the /QH2 packet is highly extensible.

== Sending ==

Send a /QH2 packet when processing a /[[Q2]] query packet reveals one or more
matching objects. Query hits can be returned directly to the /Q2/UDP return address
in the query, or routed back along the delivery chain. Firewalled leaf nodes are
advised to return /QH2 packets to their connected hub for dispatch, as the hub will
be able to make a reliable delivery.

== Receiving ==

Upon receiving a /QH2 query hit packet, check the query GUID against locally
initiated queries. If it originated elsewhere, increment the route-back hop counter
and forward it to the most appropriate link or UDP endpoint. If it matches a locally
generated query, process the search results.

== Payload ==

A single byte representing the hop count, followed by a 16 byte GUID identifying the
search that produced these results.

== Children ==

This packet has many child packet types defined at the current time:

* H - Hit Descriptor
* HG - Hit Group Descriptor
* GU - Node GUID
* NA - Node Address
* NH - Neighbouring Hub
* V - Vendor Code
* MD - Unified Metadata Block
* UPRO - User Profile
* BUP - Browse User Profile Tag
* PCH - Peer Chat Tag

== /QH2/GU - Node GUID ==

Specifies the GUID of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The GUID of the sending node.

=== Children ===

This packet has no known children at the current time.

== /QH2/NA - Node Address ==

Specifies the node / network address of the sending node.

=== Sending ===

This child is optional but recommended.

=== Payload ===

The node / network address of the sending node. See datatypes for more
information.

=== Children ===

This packet has no known children at the current time.

== /QH2/NH - Neighbouring Hub ==

Lists a hub to which the sending node (a leaf) is connected. This provides a contact
point for routing communications to a possibly firewalled leaf node.

=== Sending ===

This child is optional, and may appear more than once.

=== Payload ===

The node / network address of a hub to which the sending node is connected.

=== Children ===

This packet has no known children at the current time.

== /QH2/V - Vendor Code ==

Identifies the software operating the sending node.

=== Sending ===

This child is optional.

=== Payload ===

A four character vendor code.

=== Children ===

This packet has no known children at the current time.

== /QH2/BUP - Browse User Profile Tag ==

Indicates that the sending node supports browsing the local user profile.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/PCH - Peer Chat Tag ==

Indicates that the sending node supports person to person private message chat.

=== Sending ===

This child is optional.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has no known children at the current time.

== /QH2/HG - Hit Group Descriptor ==

Describes a group of search results.

=== Sending ===

This child is optional and may appear more than once.

=== Payload ===

A single byte, the group ID number.

=== Children ===

This packet has one child packet type currently defined:

* SS - Server State

=== /QH2/HG/SS - Server State ===

Provides a status snapshot of the upload server that applies to search results in the
current hit group.

==== Sending ====

Add this child to the hit group descriptor to provide server state information.

==== Receiving ====

Use this information when interpreting hits linked with this hit group.

==== Payload ====

* A 16-bit integer : the current queue length including any active transfers (number waiting plus number transferring)
* An 8-bit integer : the maximum number of concurrent transfers (capacity)
* A 32-bit integer : the speed in kilobits per second for uploads on this server module

==== Children ====

This packet has no known children at the current time.

== /QH2/H - Hit Descriptor ==

Describes a single object which matched the original query.

=== Sending ===

Send a /QH2/H child for each matching object to be included in this /QH2 packet.

=== Payload ===

No payload is defined at the current time.

=== Children ===

This packet has many child packet types defined at the current time, and is often
extended:

* URN - Universal Resource Name
* URL - Universal Resource Location
* DN - Descriptive Name
* MD - Metadata
* SZ - Object Size
* G - Group Identifier
* ID - Object Identifier
* CSC - Cached Source Count
* PART - Partial Availability Marker
* COM - User Comment
* PVU - Preview URL

=== /QH2/H/URN - Universal Resource Name ===

Specifies a universal resource name which can be used to identify the object.

==== Sending ====

At least one instance of this child is required. Multiple instances are optional.

==== Payload ====

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* '''bitprint''' or '''bp''' - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* '''sha1''' - 20 bytes of SHA1
* '''tree:tiger/''' or '''ttr''' - 24 bytes of tiger-tree root
* '''md5''' - 16 bytes of MD5
* '''ed2k''' - 16 bytes of compound MD4 (ed2k style root hash)

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/URL - Universal Resource Location ===

This child specifies a location where the object being described can be acquired.

==== Sending ====

This child should be sent if it was requested and a URL is available.

==== Receiving ====

If a /QH2/H/URL child was requested but is not present, the sending node may not
have the object. It is valid to advertise information about objects that are not
available.

==== Payload ====

Empty, or a string which represents an absolute URL.

If a URL is provided, that URL should be considered to point to an instance of the
object being described.

If the payload is empty, the sender is indicating that it has the object available
locally. It can be retrieved with an HTTP request using the "uri-res" resolver.

==== Children ====

This packet has no known children at the current time.

=== QH2/H/DN - Descriptive Name (Generic) Criteria ===

The descriptive name for the object, and the object's size.

==== Sending ====

This child should be sent if it was requested and is available.

==== Payload ====

A 32-bit integer indicating the object's size, followed by a string describing it. If a
/QH2/H/SZ child is present, the 32-bit size prefix is omitted here (allowing a larger
64 bit file size).

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/MD - Metadata ===

Provides metadata describing the object.

==== Sending ====

This chid should be sent if it was requested and is available.

==== Payload ====

A string containing XML. The xml header is optional. Standard plural/singular
Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/SZ - Object Size ===

Specifies the size of the object.

==== Sending ====

This child should be sent if DN was requested, and if the size is not to be packed into
the /QH2/H/DN child.

==== Payload ====

A 32-bit or 64-bit integer representing the object size.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/G - Group Identifier ===

Indicates which hit group (/QH2/HG) this hit belongs to. If this child is not present,
the hit belongs to group zero.

==== Sending ====

Send this child if this hit belongs to a hit group other than group zero.

==== Receiving ====

If this child is present, the hit belongs to a hit group other than group zero.

==== Payload ====

A single byte, the hit group ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/ID - Object Identifier ===

Specifies a 32-bit integer which uniquely identifies the object on the sender's system.

==== Sending ====

This child is not normally sent for search results. It is used in browse-user responses
to allow objects to be referenced by virtual folder structures.

==== Receiving ====

Use this ID to link objects to virtual folder structures.

==== Payload ====

A 32-bit integer ID.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/CSC - Cached Source Count ===

Indicates the number of external cached sources known to the sending node.

==== Sending ====

This child is sent if cached sources are available and interest in URLs was expressed
in the query.

==== Payload ====

A 16-bit integer.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PART - Partial Content Tag ===

Indicates that the sending node has only part of the object, and how much it has.

==== Sending ====

This child is sent if a /QH2/H/URL child is present and the URL contains only part of
the object.

==== Payload ====

A 32-bit integer, the number of bytes available.

==== Children ====

This packet has one child packet type defined at the current time:

* MT - Modification Time (payload = 32-bit timestamp)

The ''MT'' child carries the last modification time (UNIX timestamp) of the partial file and can be used to determine whether there has been recent updates made (''hot'' file) or if the file is ''cold'' (not undergoing any downloading activity on the remote side).

=== /QH2/H/COM - User Comment ===

Provides a user review and/or rating for the object.

==== Sending ====

This child is sent if a user comment is available, and comments were requested.

==== Payload ====

An XML string, of the form:

<pre>
<nowiki>
<comment rating="n">
The comment goes here.
</comment>
</nowiki>
</pre>

The rating is an integer 0 <= n <= 5, indicating the number of "stars". The text
may not include HTML, but may include forum-style block codes and emoticon
notation.

==== Children ====

This packet has no known children at the current time.

=== /QH2/H/PVU - Preview URL ===

Indicates that a preview URL is available for the object. A preview URL will serve a
miniature version of the content.

==== Sending ====

This child is sent if a preview is available.

==== Payload ====

Empty, or an absolute URL.

If a URL is provided, that URL should be considered to point to a preview of the
object being described.

If the payload is empty, the sender is indicating that it has a preview of the object
available locally. It can be retrieved with an HTTP request to the path:

<pre>
<nowiki>
/gnutella/preview/v1?urn:xyz
</nowiki>
</pre>

==== Children ====

This packet has no known children at the current time.

== /QH2/MD - Unified Metadata Block ==

Provides metadata describing one or more objects in the packet. This is an
alternative method of delivering metadata, which allows metadata for similar objects
to be grouped together. It is compatible with the unified metadata block format in
Gnutella1.

=== Sending ===

This chid should be sent if it was requested and is available.

=== Payload ===

A string containing one or more XML documents, each beginning with a header.
Standard plural/singular Gnutella metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application index="0" title="Shareaza"/>
</applications>
<?xml version="1.0"?>
<images xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/image.xsd">
<image index="1" description="Shareaza Logo" width="128" height="128"/>
<image index="2" description="Shareaza Screen Shot" width="1024" height="768"/>
</images>
</nowiki>
</pre>

An additional attribute, "index" is added to each singular entry. The index is a zerobased
integer identifying the Nth /QH2/H child within this /QH2 packet.

=== Children ===

This packet has no known children at the current time.

== /QH2/UPRO - User Profile ==

Delivers a user profile or user profile summary, describing the user operating the
sending node.

=== Sending ===

Send a version of this child if the operating user wishes to list their screen name in
search results.

The current version of this packet contains a summary only, consisting of the
screen/nick name. Future versions may include a more comprehensive XML text
block in the payload.

=== Payload ===

No payload is defined at the current time.

=== Children ===

One child packet type is defined at the current time:

* /QH2/UPRO/NICK - Nick/screen Name

=== /QH2/UPRO/NICK - Nick/Screen Name ===

Specifies the nick/screen name of the user.

==== Payload ====

A string.

==== Children ====

This packet has no known children at the current time.

Datatypes

2014-01-18T16:19:37Z

Ram: /* Multi-Byte Integers */ Added blurb about variable-length encoding

[[Packet_Structure|<< Packet Structure]] | [[Basic_Network_Maintenance|Basic Network Maintenance >>]] | [[Main_Page|Main Page]]

== Introduction ==

The format of a packet payload is defined by the packet type and can consist of any
binary data; however, there are a number of conventions in place for serializing
common datatypes.

== Multi-Byte Integers ==

Multi-byte integers are serialized in the byte-order of the topmost packet. Little endian
is the default byte-order; however, big-endian byte order can be selected for
those who want it.

Some values can also be serialized with spurious zeroes stripped-off, which is called '''variable-length''' encoding. This is suitable for values that are usually small, because it avoids transmitting extra zero bytes over the network.

A ''variable-length'' encoding of values less than 256 requires 1 single byte, values up to 65536 will require 2 bytes, and so on and so forth. This is the type of encoding used for serializing the length of each G2 packet, for instance.

== Network/Node Addresses ==

A network or node address consists of a physical address and a port number, and are
of variable length, depending on the address family.
In IPv4, a network/node address is six bytes long: 4 bytes for an IP address and 2
bytes for a port number as follows:

<pre>
<nowiki>
typedef struct
{
BYTE ip[4];
SHORT port;
} IPV4_ENDPOINT;
</nowiki>
</pre>

Note that this is considered an array of 4 8-bit integers (bytes), followed by a 16-bit
integer (short). Byte order does not affect bytes, but it will affect the 16-bit port
number.

IPv6 addresses are longer and are not yet defined within the scope of Gnutella2,
however, applications should be aware that if the node address is not 6 bytes, it is of
a different address family.

== GUIDs ==

Globally unique identifiers (GUIDs) are used to identify nodes on the network. GUIDs
are serialized as an array of 16 bytes.

== Strings ==

Strings are encoded with UTF-8 encoding and serialized as a zero-terminated
sequence of 8 bit integers.

A zero character (0x00) marks the end of the string, however, if the string data meets
the end of the packet (or child packet) payload, the terminator is not required. This
means that packets whose payload consists of a string, do not need to include a zero
string terminator and their payload length will be the byte length of the encoded
string exactly.

UTF-8 encoding is required for all strings present in the packet payload. This means
that 7-bit characters may be passed as-is, while extended characters are encoded
with multi-byte sequences.

All applications must be able to parse UTF-8 encoded strings, however, it is up to the
individual application whether to store the string in Unicode, or convert it to the
local code page for processing. In situations where a packet must be processed ''and''
forwarded, the original packet must be forwarded rather than a regenerated version.
This ensures that both locally unsupported encodings and packet extensions are
preserved.

Applications should never send ANSI strings directly if they contain extended
characters with the MSB set. These should be encoded with UTF-8. If this is not
done, the decoding process may fail and the packet will be discarded or contain
bogus information.

LNI

2014-01-18T13:00:13Z

Ram: /* /LNI - Local Node Information */ Added documentation for /LNI/UP

{{Packets}}

= /LNI - Local Node Information =

The local node information packet is used to convey essential information about the
node on either end of a TCP stream connection.

== Sending ==

The /LNI packet should be sent to a TCP neighbour upon connection, and at regular
intervals following that if the information within it has changed. A minimum update
time of one minute is recommended.

== Receiving ==

Upon receiving a /LNI packet, the information within should be stored for subsequent
use.

== Payload ==

This packet has no payload at the current time.

== Children ==

The /LNI packet has many child packet types defined at the current time:

* /LNI/NA - Node Address
* /LNI/GU - GUID
* /LNI/V - Vendor Code
* /LNI/LS - Library Statistics
* /LNI/HS - Hub Status
* /LNI/FW - Firewalled
* /LNI/QK - Query Key Caching
* /LNI/HA - Hub Able
* /LNI/RTR - Router
* /LNI/UP - Uptime

== /LNI/NA - Node Address ==

The /LNI/NA child packet specifies the node or network address of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The physical network address of the sending node. See [[datatypes]] for more
information.

=== Children ===

This packet has no known children at the current time.

== /LNI/GU - GUID ==

The /LNI/GU child packet specifies the globally unique identifier of the sending node.

=== Sending ===

This child is required.

=== Payload ===

The 16 byte globally unique node identifier of the sending node.

=== Children ===

This packet has no known children at the current time.

== /LNI/V - Vendor Code ==

The /LNI/V child packet specifies the vendor code of the software operating the
sending node.

=== Sending ===

This child is optional.

=== Payload ===

A four byte vendor code.

=== Children ===

This packet has no known children at the current time.

== /LNI/LS - Library Statistics ==

The /LNI/LS packet provides information about the content library of the sending
node.

=== Sending ===

This child is optional.

=== Payload ===

Two 32-bit integers representing the number of files in the local library, and the total
KB in the local library respectively. If the sending node is a hub these statistics are
combined with the known statistics from all connected leaves. The payload may grow
beyond 8 bytes in the future.

=== Children ===

This packet has no known children at the current time.

== /LNI/HS - Hub Status ==

The /LNI/HS packet is included only if the sending node is a hub, and contains the
status of the hub.

=== Sending ===

This child packet should only be sent by hub nodes. Leaf nodes should not transmit
it, and if it is received from a leaf node, it should be ignored.

=== Payload ===

Two 16-bit integers representing the current leaf count and the maximum leaf count
respectively. This packet may grow beyond 4 bytes in the future.

=== Children ===

This packet has no known children at the current time.

== /LNI/UP - Uptime ==

The /LNI/UP packet contains the node uptime, measured in seconds.

=== Sending ===

This child packet can be sent by any node (hub or leaf)

=== Payload ===

A variable-length quantity: an uptime of less than 256 seconds will be transmitted using one single byte, less than 65536 will require only 2 bytes, etc...

=== Children ===

This packet has no known children at the current time.

PI

2014-01-15T22:41:31Z

Ram: /* Receiving */ Clarified that leaves should never be forwarded /PI/UDP messages

{{Packets}}

= /PI - Ping =

The ping packet is used to verify the presence of the addressed node, testing that:

* The destination node is online
* The destination node can receive the transmission
* The local node can receive the reply

Aside from performing a "keep-alive" function on TCP links, pings can be used to
solicit inbound UDP datagrams to test the local node's ability to receive UDP. Many
NAT systems will route UDP traffic from nodes with whom a persistent TCP stream
has been established, so it is necessary to test inbound traffic from nodes with which
there is no TCP connection. This is achieved by sending a ping with a /PI/UDP packet
to a connected hub via TCP, which will forward the request to its neighbours who
then reply to the originator via UDP.

== Sending ==

On a TCP stream connection, if one end has not received a valid packet from the
other after an internally determined period of time, it has the option of sending a
keep-alive ping to verify the other end's presence. If a pong is not received in a
timeout period it may close the connection.

If a node needs to verify that it is able to receive UDP datagrams from nodes with
which it does not have a TCP stream connection, it may send a ping packet with a
/PI/UDP child packet. If it then receives a /PO (pong) packet with a /PO/RELAY child
tag and there is no TCP connection to the sender, it can assume it is able to receive
UDP.

== Receiving ==

Upon receiving a keep-alive ping, a node should respond with a keep-alive pong
immediately.

If the ping was received by a hub from a TCP neighbour and contains a /PI/UDP child packet,
but no /PI/RELAY tag, a /PI/RELAY tag should be added and the packet forwarded to
all neighbouring hubs. If a /PI/RELAY tag was present, the node should send a /PO
packet with a /PO/RELAY tag to the UDP address identified in the /PI/UDP child
packet.

Note that leaf nodes should '''never''' be forwarded /PI packets with a /PI/UDP child: these need to be handled by hubs only.

== Payload ==

This packet has no payload at the current time.

== Children ==

The ping packet has two child packets defined at the current time:

* /PI/RELAY
* /PI/UDP

== /PI/RELAY - Relayed Ping Marker ==

If a /PI packet contains a /PI/RELAY child marker, the ping has been relayed for a
third party. The receiving node should reply to the original party rather than the
sender. The original party should be contacted via UDP with the address contained in
the /PI/UDP child. If the /PI/UDP child is absent, the packet is invalid.

=== Sending ===

The /PI/RELAY child should be added to a /PI packet when relaying a ping to hub
neighbours at the request of a leaf.

=== Receiving ===

Upon receiving a /PI packet with a /PI/RELAY tag, a /PO (pong) packet should be
sent via UDP to the node identified in the /PI/UDP child.

=== Payload ===

This packet has no payload at the current time.

=== Children ===

This packet has no known children at the current time.

== /PI/UDP - Ping Response Address ==

The /PI/UDP child packet specifies the return address for a relay able or relayed
ping.

=== Sending ===

Add a /PI/UDP child packet to a /PI packet to request a relayed "two hop" ping.

=== Receiving ===

The /PI/UDP child packet indicates that a /PI packet needs to be relayed.

=== Payload ===

The /PI/UDP packet contains an endpoint address.

=== Children ===

This packet has no known children at the current time.

Q2

2014-01-15T22:32:39Z

Ram: /* Payload */ Fixed typo: it stated "FS", it's actually "PFS" that is used out there

{{Packets}}

= /Q2 - Gnutella2 Query =

The /Q2 packet is the generic Gnutella2 object query descriptor. It contains search
criteria, identification, authentication, return addressing and the type of information
the search client is interested in.

== Sending ==

A node should send a /Q2 packet to another node when it wishes to execute a query
on that node (and its searchable relations).
/Q2 packets should always be filtered against a query hash table if one is available
for the outbound link.

== Receiving ==

Upon receiving a query, a node should:

* Verify its authentication
* Send an acknowledgment if it was not received from a hub
* Forward it to connected nodes if necessary (detailed below)
* Process it locally and dispatch results

== Forwarding ==

Forwarding of /Q2 packets is achieved based on fixed rules:

* A query received from a leaf or via UDP is forwarded to all connected nodes
* A query received from a hub is forwarded to connected leaves only

== Payload ==

The payload of a /Q2 packet consists of a GUID which uniquely identifies the search
operation.

== Children ==

This packet has many defined child packet types at the current time:
* /Q2/UDP - Return Address and Authentication
* /Q2/URN - Universal Resource Name
* /Q2/DN - Descriptive Name (Generic) Criteria
* /Q2/MD - Metadata Criteria
* /Q2/SZR - Object Size Restriction Criteria
* /Q2/I - Interest

== /Q2/UDP - Return Address and Authentication ==

The /Q2/UDP child packet specifies the return address to be used for all direct
replies, and the query key authentication which authorises transmissions to this
address. If the query key is invalid, the query should be discarded and a valid query
key issued to the nominated address (if desired).

=== Sending ===

This child is required if the query is to be delivered via UDP. It is optional if delivered
via TCP: if not included, replies will be reverse forwarded via TCP.

=== Receiving ===

If this child is present, all replies should be directed to the nominated address. The
query key should be verified before replying.

=== Payload ===

A network address (variable length) followed by a query key (fixed length of 32 bits).

=== Children ===

This packet has no known children at the current time.

== /Q2/URN - Universal Resource Name ==

The /Q2/URN child specifies an exact universal resource name which will match the
query. Rules:

* If one or more URNs are present in a query, whether or not they are understood, matching must occur on URN only and other criteria should be ignored.
* If multiple URNs are present, only one need match an object for it to be considered a match for the query.
* Following from the above, multiple URNs of the same family may be specified and match multiple objects (this allows a compound query for several known objects to be executed in one packet).

=== Sending ===

This child should be added if a specific URN is being sought.

=== Payload ===

A string identifying the URN families followed by the URN in either text or binary
representation. Text representations should always be 8-bit so that they can be
considered binary.

The following compact URN families are recognised:

* bitprint or bp - 20 bytes of SHA1 followed by 24 bytes of tiger-tree root
* sha1 - 20 bytes of SHA1
* tree:tiger/ or ttr - 24 bytes of tiger-tree root
* md5 - 16 bytes of MD5
* ed2k - 16 bytes of compound MD4 (ed2k style root hash)

=== Children ===

This packet has no known children at the current time.

== /Q2/DN - Descriptive Name (Generic) Criteria ==

The descriptive name child provides generic query text to be used in matching
objects.

=== Payload ===

A string in the simple query language.

=== Children ===

This packet has no known children at the current time.

== /Q2/MD - Metadata Criteria ==

The metadata child provides an XML document containing rich query information.
The schema identified in the XML must match a metadata schema of prospective
matching objects.

=== Payload ===

A string containing XML. The header is optional. Standard plural/singular Gnutella
metadata schemas are used, for example:

<pre>
<nowiki>
<?xml version="1.0"?>
<applications xsi:noNamespaceSchemaLocation="http://www.shareaza.com/schemas/application.xsd">
<application title="Shareaza"/>
</applications>
</nowiki>
</pre>

All string values are in simple query language, including XML attribute and element
values.

=== Children ===

This packet has no known children at the current time.

== /Q2/SZR - Size Restriction Criteria ==

The size restriction criteria specify a minimum and maximum size for matching
objects.

=== Payload ===

A minimum size followed by a maximum size, both quoted in bytes. These two
numbers may be expressed as two 32 bit integers or two 64 bit integers.

=== Children ===

This packet has no known children at the current time.

== /Q2/I - Interest ==

The Interest packet advertises an interest in certain information classes, effectively
filtering the information that will be returned about matching objects.

=== Sending ===

Send an interest packet to restrict the type of information that will be returned about
matching objects. For example if querying only to find instances of a known object,
advertise interest for "URL" only. Omitting the interest packet produces a default set
of response information.

=== Receiving ===

If an interest packet is received, only return the requested information types. If no
interest packet is present, return all available information that is feasible. Extensions
may be withheld.

=== Payload ===

An array of strings identifying information classes. The following are defined:

* URL - Locations where matching objects can be found
* DN - Descriptive names of matching objects
* MD - Full metadata of matching objects
* COM - User comments, ratings and reviews of matching objects
* PFS - Partially available objects

Note that default URNs are always supplied and need not be requested.

=== Children ===

This packet has no known children at the current time.

UDP Transceiver

2012-09-29T15:58:22Z

Ram: /* Negotiation */ Clarified processing contract for improved acknowledgments

[[TCP_Stream_Connection_and_Handshaking|<< TCP Stream Connection and Handshaking]] | [[Packet_Structure|Packet Structure >>]] | [[Main_Page|Main Page]]

== Introduction ==

The User Datagram Protocol (UDP) is invaluable in peer to peer systems because it
provides a relatively low-cost (low-overhead) method of sending short, irregular
messages to a very large number of peers on demand. Establishing a TCP stream
connection to a peer simply to deliver a single packet of information is wasteful in
data volume and time for the peers involved and state-aware network devices along
the route, for example, network address translation facilities. When dealing with a
large number of peers quickly, these costs become unbearable. UDP provides a
solution and makes this kind of interaction possible.

However, the delivery of UDP packets is not reliable: packets may be lost en-route for
a number of reasons. Often this behaviour is desirable, for example when the
destination node's connection is highly congested, UDP packets are likely to be
discarded. If the content was not critical, this loss is appropriate as the host's
resources are effectively unavailable. In other scenarios involving critical payloads,
UDP's lack of reliability is a problem: either the sender needs to make sure the
receiver gets the payload, or it needs to know definitively that the receiver was
unavailable.

The Gnutella2 network solves this problem by implementing a selectively engaged
reliability layer on top of the basic UDP protocol. This reliability layer shares some
common functionality with TCP, but importantly does not provide any connection
state and thus retains the efficiency originally sought in UDP.

This allows Gnutella2 to select the most optimal communication medium for each
and every transmission it needs to perform:

* If a significant volume of data is to be exchanged, or subsequent data will be exchanged with the same destination, a TCP connection is established
* If a small volume of important data is to be exchanged in a once-off operation or irregularly, reliable UDP is used
* If a small volume of unimportant data is to be exchanged in a once-off operation or irregularly, unreliable UDP is used

== UDP ==

Gnutella2 semi-reliable communication is transported using the UDP protocol. The
port number for receiving UDP is the same as the port number listening for TCP
connections.

== Encoding ==

Implementing an additional reliable protocol within UDP requires a small control
header before the payload itself. This header is put to good use:

A small signature identifies the packet as a Gnutella2 semi-reliable UDP datagram.
This allows the same port to be used for receiving UDP traffic for other protocols if
desired, and offers some simple protection against random, unexpected traffic.
A content code identifies the payload as a Gnutella2 packet stream, allowing future
protocols to be added within the same reliability layer if desired.
Flags allow additional attributes to be specified, such as inline stateless compression
of the payload (which is a required feature).
The header has a fixed size of 8 bytes, and is represented by the following C
structure:

<pre>
<nowiki>
#pragma pack(1)
typedef struct
{
CHAR szTag[3];
BYTE nFlags;
WORD nSequence;
BYTE nPart;
BYTE nCount;
} GND_HEADER;
</nowiki>
</pre>

Byte format:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| szTag | nFlags | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nSequence | nPart | nCount | 4-7
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

The members of the structure are detailed below:

* '''szTag''' - contains a three byte encoding protocol identifier, in this case "GND" for "GNutella Datagram". If this signature is not present the packet should not be decoded as a Gnutella2 reliability layer transmission.
* '''nFlags''' - contains flags which modify the content of the packet. The low-order nibble is reserved for critical flags: if one of these bits is set but the decoding software does not understand the meaning, the packet must be discarded. The high-order nibble is reserved for non-critical flags: when set these bits may be interpreted, but an inability to interpret a bit does not cause the packet to be discarded. Currently defined flags are:
:* '''0x01''' - Deflate
:: When the deflate bit is set, the entire payload is compressed with the deflate algorithm. The compression method used is the Deflate Compression Data Format (RFC 1951). On top of this compression a ZLIB ‘wrapper’ is applied (RFC 1950, ZLIB Compressed Data Format). The ZLIB wrapper ensures packet integrity, among other things. Note that the entire payload must be reassembled in the correct order before it can be deflated if the packet was fragmented. Fragments are not compressed separately!
:* '''0x02''' - Acknowledge Me
:: When the acknowledge me bit is set, the sender is expecting an acknowledgement for this packet.

* '''nSequence''' - contains the sequence number of the packet. This sequence number is unique to the sending host only. It is not unique to the pair of the sending host and receiving host as in TCP, as there is no concept of connection state. Sequence numbers on consecutive packets need not be increasing (although that is convenient) â€“ they must only be different. If a packet is fragmented, all of its fragments will have the same sequence number. Byte order is unimportant here.
* '''nPart''' - contains the fragment part number (1 <= nPart <= nCount)
* '''nCount''' - contains the number of fragment parts in this packet. On a transmission, this value will be non-zero (all packets must have at least one fragment). If nCount is zero, this is an acknowledgement (see below).

== Fragmentation ==

Large packets must be fragmented before they can be sent through most network
interfaces. Different network media have different MTUs, and it is difficult to predict
what the lowest common size will be. Fragmentation and reassembly is performed by
the existing Internet protocols, however, there are two important reasons why the
reliability layer performs its own fragmentation:

* Sockets implementations specify a maximum datagram size. This is adequate for the vast majority of transmissions, but it is desirable to have the transparent ability to send larger packets without worrying about the host implementation.
* When the Internet protocols fragment, a packet and one or more fragments are lost, it may decide to discard the whole packet in an unreliable datagram protocol. The Gnutella2 reliability layer can compensate by retransmitting the whole packet, which would then be re-fragmented and each fragment resent - however, this wastes the fragments that were successfully received before. Managing fragmentation natively allows this optimisation.

Each node determines its own MTU, often based on a best guess combined with
information from the host's sockets implementation. Packets exceeding this size are
fragmented into multiple datagrams of the appropriate size. Each datagram has the
same sequence number and the same fragment count (nCount), but a different
fragment number (nPart).

== Transmission Process ==

When a packet is to be transmitted, the network layer must:

* Cache the payload
* Allocate a new locally and temporally unique sequence number
* Derive the appropriate number of fragments
* Queue the fragments for dispatch
* If the fragments do not need to be acknowledged, the packet can be flushed now

The payload will generally be cached for an appropriate timeout period, or until the
data cache becomes full, at which time older payloads can be discarded. Fragments
are dispatched according to the dispatch algorithm of choice, and the sender listens
for acknowledgements. When an acknowledgement is received:

* Lookup the sent packet by sequence number
* Mark the nPart fragment as received and cancel any retransmissions of this part
* If all fragments have been acknowledged, flush this packet from the cache

If a fragment has been transmitted but has not been acknowledged within the
timeout, it should be retransmitted. A finite number of retransmissions are allowed
before the packet as a whole expires, at which time it is assumed that the packet
was not received.

== Receive Process ==

When a new datagram is received, the network layer must:

* If the acknowledge bit was set, send an acknowledge packet for this sequence number and part number, with nCount set to zero (ack)
* Lookup any existing packet by the sending IP and sequence number
* If there is no existing packet, create a new packet entry with the IP, sequence number, fragment count and flags
* If there was an existing packet, make sure it is not marked as done - if so, abort
* Add the transmitted fragment to the (new or old) packet entry
* If the packet now has all fragments, mark it as done and decode it and pass it up to the application layer
* Leave the packet on the cache even if it was finished, in case any parts are retransmitted
* Expire old packets from the receive buffer after a timeout, or if the buffer is full

== Dispatch Algorithm ==

Fragment datagrams need to be dispatched intelligently, to spread the load on
network resources and maximise the chance that the receiver will get the message.
To do this, the dispatch algorithm should take into account several points:

* Prioritize acknowledgements.
* If fragments are waiting to be sent to a number of hosts, do not send to the same host twice in a row. Alternating, or looping through the target hosts achieves the same data rate locally, but spreads out the load over downstream links.
* Do not exceed or approach the capacity of the local network connection. If a host has a 128 kb/s outbound bandwidth, dispatching 32 KB of data in one second will likely cause massive packet loss, leading to a retransmission.
* After considering the above points, prefer fragments that were queued recently to older packets. A LIFO or stack type approach means that even if a transmitter is becoming backed up, some fragments will get there on time, while others will be delayed. A FIFO approach would mean that a backed up host delivers every fragment late.

== Parameters ==
The recommended parameters for the reliability layer are as follows:

<pre>
<nowiki>
MTU = 500 bytes
Transmit Retransmit Interval = 10 seconds
Transmit Packet Timeout / Expire = 26 seconds (allows for two retransmissions before expiry)
Receive Packet Expiry = 30 seconds (allows 10 seconds beyond final retransmission)
</nowiki>
</pre>

The UDP/IP header being typically 28 bytes, it is best to limit the payload of the messages to '''476 bytes'''. That way, with the 8-byte header we're topping plus the UDP/IP header, the whole message will not be greater than 512 bytes. The recommended MTU should therefore be 476 rather than the legacy 500. --RAM, 05:19, 23 September 2012 (PDT)

== Performance Considerations ==

Relatively low-level network implementations such as this are reasonably
complicated, but must operate fast. It is desirable to avoid runtime memory
allocations in network code as much as possible, and particularly at this level.

It should be noted that in almost all cases, transmissions to "untested" nodes are
single fragment. Replies on the other hand are often larger, and may be deflated in
many fragments. This is optimal, because attempting to contact a node which may be
unavailable, involves a retransmission of only a single fragment.

Flow control is an important topic, however, it is handled at a higher layer. The UDP
reliability layer is only responsible for guaranteeing delivery of selected datagrams.

Only critical transmissions whose reception cannot otherwise be inferred, should have
the acknowledge request bit set.

== Extension Proposal ==

The following is still a proposoal, but since there is no G2 Development Forum where this can be discussed, I thought I would document it here. 05:07, 23 September 2012 (PDT)

This extension ''should'' be '''totally backward compatible''' with existing implementations provided the above page specifications were strictly adhered to. Here it goes:

=== Improved Acknowledgments ===

Because acknowledgment messages can be lost in the way or arrive out of order, it is best to include as much of the reception state as possible so that the sending party can optimize retransmissions.

In order to do that, the following extensions to the original specifications has been added by gtk-gnutella:

* '''Cumulative Acknowledgements''': when the flag '''0x10''' is set, it tells the other party that '''all''' the fragments up to '''nPart''' have been received.

* '''Extended Acknowledgments''': when the flag '''0x20''' is set, it tells the other party that an acknowledgment payload is present. It immediately follows the header and is architected thusly:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nReceived | missingBits | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

'''nReceived''' is the total amount of parts successfully received so far.

'''missingBits''' is a bitfield that is read as a '''big-endian number''' and which contains set bits for the parts still missing. The ''base'' part number is normally 0, unless flag '''0x10''' was set, in which case the '''nPart''' value indicates the base. The rule is then that if bit ''b'' is set, then the fragment number ''b'' + ''base'' + 1 is still missing.

In the unlikely case where missingBits is too small to hold all the missing parts, only the ones that can be represented are included, the '''nReceived''' field being there to provide additional information.

Proper generation and parsing of the '''missingBits''' field is crucial, so to remove any ambiguity, it is best to interpret missingBits as a number. Then bit 0 is the bit corresponding to 2^0, bit ''n'' is the bit corresponding to 2^n. In the above framing pictogram, bit 0 is the 7th bit of the 3rd byte (because the number in '''missingBits''' is encoded in ''big-endian'').

Bit 0 corresponds to fragment #1, unless the '''0x10''' flag was set. In that case, if for instance '''nPart''' is 3, then it means fragments #1, #2 and #3 were already received. The base is therefore 3, and if bit 0 is set in '''missingBits''', it means fragment #4 (0 + 3 + 1) is still missing.

This extended acknowledgment lets the sending party optimize its retransmissions even when some acknowledgments are lost.

''Extended Acknowledgments'' are only useful when the total amount of fragments
is 3 or above. Indeed, with only 2 fragments, the ''Cumulative Acknowledgment''
lets the receiving party know about the whole reception state.

When the amount of fragments is 3 or more and only a ''Cumulative Acknowledgment'' is sent out, it '''implicitly denies reception''' of any other fragments. This optimizes bandwidth since the 4 extra bytes sent out will only be required for large messages (more than 2 fragments) in case fragments are received out-of-order.

=== Negotiation ===

Before the recipient can use this extension, it must be certain that the sender will understand its semantics. Indeed, imagine the case where a 3-fragment message is sent and completely received, and therefore the recipient only sends a ''Cumulative Acknowledge'' for fragment #3. A legacy sender would think fragments #1 and #2 are still missing.

To signify to the recipient that the sender will understand the new acknowledgments, it '''must set the flag 0x10''' in all the fragments it sends. This new flag is therefore defined as:

* '''Improved Acknowledgements''': when the flag '''0x10''' is set in emitted fragments, it tells the other party that it can reply with the ''Cumulative Acknowledgments'' or the ''Extended Acknowledgment'' bits in its acknowledgment messages.

When the ''Improved Acknowledgments'' flag is '''missing''', the receiver '''must fall back''' to the ''legacy'' acknowledgment protocol. Since '''0x10''' is in the high-nibble part of the flag field, no legacy implementation will choke upon seeing it, and they can safely ignore it. This guarantees the sender that the message will be processed correctly by legacy implementations.

When the ''Improved Acknowledgment'' bit is seen, the receiver is naturally free to ignore it altogether (as legacy servents will do) or chose to reply only with ''Cumulative Acknowledgements'' and never send ''Extended Acknowledgments'', for instance.

However, when the sender sets the ''Improved Acknowledgment'' bit, it '''must''' be prepared to receive both ''Cumulative Acknowledgments'' '''and''' ''Extended Acknowledgments''. It is safe to ignore the extension part of the latter though, but the former must be fully handled.

=== Delayed Acknowledgments ===

To maximize the usefulness of ''Cumulative Acknowledgments'', the receiver can delay its acknowledgments for a small period of time (100 ms, say) in the hope that more fragments of the message will arrive meanwhile, provided the message has more than 1 fragment naturally. When the 100 ms delay is expired, it can then acknowledge everything it got so far. Performance will not be impacted by this small delaying, but it can save a few acknowledgments for larger messages.

This means a sender must use a transmission policy whereby it first sends '''all the fragments''' of each message at once, then waits for acknowledgments or timeouts before retransmitting the um-acknowledged fragments. In other words, the sender should not send a fragment, wait for its acknowledgement before sending the next one: this would delay the reception of the entire message and it would prevent using the optimizations that this extension proposal wants to promote!

=== Author ===

This proposal was created by Raphael Manfredi, last modified on 01:03, 26 September 2012 (PDT).

UDP Transceiver

2012-09-28T10:28:46Z

Ram: /* Negotiation */

[[TCP_Stream_Connection_and_Handshaking|<< TCP Stream Connection and Handshaking]] | [[Packet_Structure|Packet Structure >>]] | [[Main_Page|Main Page]]

== Introduction ==

The User Datagram Protocol (UDP) is invaluable in peer to peer systems because it
provides a relatively low-cost (low-overhead) method of sending short, irregular
messages to a very large number of peers on demand. Establishing a TCP stream
connection to a peer simply to deliver a single packet of information is wasteful in
data volume and time for the peers involved and state-aware network devices along
the route, for example, network address translation facilities. When dealing with a
large number of peers quickly, these costs become unbearable. UDP provides a
solution and makes this kind of interaction possible.

However, the delivery of UDP packets is not reliable: packets may be lost en-route for
a number of reasons. Often this behaviour is desirable, for example when the
destination node's connection is highly congested, UDP packets are likely to be
discarded. If the content was not critical, this loss is appropriate as the host's
resources are effectively unavailable. In other scenarios involving critical payloads,
UDP's lack of reliability is a problem: either the sender needs to make sure the
receiver gets the payload, or it needs to know definitively that the receiver was
unavailable.

The Gnutella2 network solves this problem by implementing a selectively engaged
reliability layer on top of the basic UDP protocol. This reliability layer shares some
common functionality with TCP, but importantly does not provide any connection
state and thus retains the efficiency originally sought in UDP.

This allows Gnutella2 to select the most optimal communication medium for each
and every transmission it needs to perform:

* If a significant volume of data is to be exchanged, or subsequent data will be exchanged with the same destination, a TCP connection is established
* If a small volume of important data is to be exchanged in a once-off operation or irregularly, reliable UDP is used
* If a small volume of unimportant data is to be exchanged in a once-off operation or irregularly, unreliable UDP is used

== UDP ==

Gnutella2 semi-reliable communication is transported using the UDP protocol. The
port number for receiving UDP is the same as the port number listening for TCP
connections.

== Encoding ==

Implementing an additional reliable protocol within UDP requires a small control
header before the payload itself. This header is put to good use:

A small signature identifies the packet as a Gnutella2 semi-reliable UDP datagram.
This allows the same port to be used for receiving UDP traffic for other protocols if
desired, and offers some simple protection against random, unexpected traffic.
A content code identifies the payload as a Gnutella2 packet stream, allowing future
protocols to be added within the same reliability layer if desired.
Flags allow additional attributes to be specified, such as inline stateless compression
of the payload (which is a required feature).
The header has a fixed size of 8 bytes, and is represented by the following C
structure:

<pre>
<nowiki>
#pragma pack(1)
typedef struct
{
CHAR szTag[3];
BYTE nFlags;
WORD nSequence;
BYTE nPart;
BYTE nCount;
} GND_HEADER;
</nowiki>
</pre>

Byte format:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| szTag | nFlags | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nSequence | nPart | nCount | 4-7
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

The members of the structure are detailed below:

* '''szTag''' - contains a three byte encoding protocol identifier, in this case "GND" for "GNutella Datagram". If this signature is not present the packet should not be decoded as a Gnutella2 reliability layer transmission.
* '''nFlags''' - contains flags which modify the content of the packet. The low-order nibble is reserved for critical flags: if one of these bits is set but the decoding software does not understand the meaning, the packet must be discarded. The high-order nibble is reserved for non-critical flags: when set these bits may be interpreted, but an inability to interpret a bit does not cause the packet to be discarded. Currently defined flags are:
:* '''0x01''' - Deflate
:: When the deflate bit is set, the entire payload is compressed with the deflate algorithm. The compression method used is the Deflate Compression Data Format (RFC 1951). On top of this compression a ZLIB ‘wrapper’ is applied (RFC 1950, ZLIB Compressed Data Format). The ZLIB wrapper ensures packet integrity, among other things. Note that the entire payload must be reassembled in the correct order before it can be deflated if the packet was fragmented. Fragments are not compressed separately!
:* '''0x02''' - Acknowledge Me
:: When the acknowledge me bit is set, the sender is expecting an acknowledgement for this packet.

* '''nSequence''' - contains the sequence number of the packet. This sequence number is unique to the sending host only. It is not unique to the pair of the sending host and receiving host as in TCP, as there is no concept of connection state. Sequence numbers on consecutive packets need not be increasing (although that is convenient) â€“ they must only be different. If a packet is fragmented, all of its fragments will have the same sequence number. Byte order is unimportant here.
* '''nPart''' - contains the fragment part number (1 <= nPart <= nCount)
* '''nCount''' - contains the number of fragment parts in this packet. On a transmission, this value will be non-zero (all packets must have at least one fragment). If nCount is zero, this is an acknowledgement (see below).

== Fragmentation ==

Large packets must be fragmented before they can be sent through most network
interfaces. Different network media have different MTUs, and it is difficult to predict
what the lowest common size will be. Fragmentation and reassembly is performed by
the existing Internet protocols, however, there are two important reasons why the
reliability layer performs its own fragmentation:

* Sockets implementations specify a maximum datagram size. This is adequate for the vast majority of transmissions, but it is desirable to have the transparent ability to send larger packets without worrying about the host implementation.
* When the Internet protocols fragment, a packet and one or more fragments are lost, it may decide to discard the whole packet in an unreliable datagram protocol. The Gnutella2 reliability layer can compensate by retransmitting the whole packet, which would then be re-fragmented and each fragment resent - however, this wastes the fragments that were successfully received before. Managing fragmentation natively allows this optimisation.

Each node determines its own MTU, often based on a best guess combined with
information from the host's sockets implementation. Packets exceeding this size are
fragmented into multiple datagrams of the appropriate size. Each datagram has the
same sequence number and the same fragment count (nCount), but a different
fragment number (nPart).

== Transmission Process ==

When a packet is to be transmitted, the network layer must:

* Cache the payload
* Allocate a new locally and temporally unique sequence number
* Derive the appropriate number of fragments
* Queue the fragments for dispatch
* If the fragments do not need to be acknowledged, the packet can be flushed now

The payload will generally be cached for an appropriate timeout period, or until the
data cache becomes full, at which time older payloads can be discarded. Fragments
are dispatched according to the dispatch algorithm of choice, and the sender listens
for acknowledgements. When an acknowledgement is received:

* Lookup the sent packet by sequence number
* Mark the nPart fragment as received and cancel any retransmissions of this part
* If all fragments have been acknowledged, flush this packet from the cache

If a fragment has been transmitted but has not been acknowledged within the
timeout, it should be retransmitted. A finite number of retransmissions are allowed
before the packet as a whole expires, at which time it is assumed that the packet
was not received.

== Receive Process ==

When a new datagram is received, the network layer must:

* If the acknowledge bit was set, send an acknowledge packet for this sequence number and part number, with nCount set to zero (ack)
* Lookup any existing packet by the sending IP and sequence number
* If there is no existing packet, create a new packet entry with the IP, sequence number, fragment count and flags
* If there was an existing packet, make sure it is not marked as done - if so, abort
* Add the transmitted fragment to the (new or old) packet entry
* If the packet now has all fragments, mark it as done and decode it and pass it up to the application layer
* Leave the packet on the cache even if it was finished, in case any parts are retransmitted
* Expire old packets from the receive buffer after a timeout, or if the buffer is full

== Dispatch Algorithm ==

Fragment datagrams need to be dispatched intelligently, to spread the load on
network resources and maximise the chance that the receiver will get the message.
To do this, the dispatch algorithm should take into account several points:

* Prioritize acknowledgements.
* If fragments are waiting to be sent to a number of hosts, do not send to the same host twice in a row. Alternating, or looping through the target hosts achieves the same data rate locally, but spreads out the load over downstream links.
* Do not exceed or approach the capacity of the local network connection. If a host has a 128 kb/s outbound bandwidth, dispatching 32 KB of data in one second will likely cause massive packet loss, leading to a retransmission.
* After considering the above points, prefer fragments that were queued recently to older packets. A LIFO or stack type approach means that even if a transmitter is becoming backed up, some fragments will get there on time, while others will be delayed. A FIFO approach would mean that a backed up host delivers every fragment late.

== Parameters ==
The recommended parameters for the reliability layer are as follows:

<pre>
<nowiki>
MTU = 500 bytes
Transmit Retransmit Interval = 10 seconds
Transmit Packet Timeout / Expire = 26 seconds (allows for two retransmissions before expiry)
Receive Packet Expiry = 30 seconds (allows 10 seconds beyond final retransmission)
</nowiki>
</pre>

The UDP/IP header being typically 28 bytes, it is best to limit the payload of the messages to '''476 bytes'''. That way, with the 8-byte header we're topping plus the UDP/IP header, the whole message will not be greater than 512 bytes. The recommended MTU should therefore be 476 rather than the legacy 500. --RAM, 05:19, 23 September 2012 (PDT)

== Performance Considerations ==

Relatively low-level network implementations such as this are reasonably
complicated, but must operate fast. It is desirable to avoid runtime memory
allocations in network code as much as possible, and particularly at this level.

It should be noted that in almost all cases, transmissions to "untested" nodes are
single fragment. Replies on the other hand are often larger, and may be deflated in
many fragments. This is optimal, because attempting to contact a node which may be
unavailable, involves a retransmission of only a single fragment.

Flow control is an important topic, however, it is handled at a higher layer. The UDP
reliability layer is only responsible for guaranteeing delivery of selected datagrams.

Only critical transmissions whose reception cannot otherwise be inferred, should have
the acknowledge request bit set.

== Extension Proposal ==

The following is still a proposoal, but since there is no G2 Development Forum where this can be discussed, I thought I would document it here. 05:07, 23 September 2012 (PDT)

This extension ''should'' be '''totally backward compatible''' with existing implementations provided the above page specifications were strictly adhered to. Here it goes:

=== Improved Acknowledgments ===

Because acknowledgment messages can be lost in the way or arrive out of order, it is best to include as much of the reception state as possible so that the sending party can optimize retransmissions.

In order to do that, the following extensions to the original specifications has been added by gtk-gnutella:

* '''Cumulative Acknowledgements''': when the flag '''0x10''' is set, it tells the other party that '''all''' the fragments up to '''nPart''' have been received.

* '''Extended Acknowledgments''': when the flag '''0x20''' is set, it tells the other party that an acknowledgment payload is present. It immediately follows the header and is architected thusly:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nReceived | missingBits | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

'''nReceived''' is the total amount of parts successfully received so far.

'''missingBits''' is a bitfield that is read as a '''big-endian number''' and which contains set bits for the parts still missing. The ''base'' part number is normally 0, unless flag '''0x10''' was set, in which case the '''nPart''' value indicates the base. The rule is then that if bit ''b'' is set, then the fragment number ''b'' + ''base'' + 1 is still missing.

In the unlikely case where missingBits is too small to hold all the missing parts, only the ones that can be represented are included, the '''nReceived''' field being there to provide additional information.

Proper generation and parsing of the '''missingBits''' field is crucial, so to remove any ambiguity, it is best to interpret missingBits as a number. Then bit 0 is the bit corresponding to 2^0, bit ''n'' is the bit corresponding to 2^n. In the above framing pictogram, bit 0 is the 7th bit of the 3rd byte (because the number in '''missingBits''' is encoded in ''big-endian'').

Bit 0 corresponds to fragment #1, unless the '''0x10''' flag was set. In that case, if for instance '''nPart''' is 3, then it means fragments #1, #2 and #3 were already received. The base is therefore 3, and if bit 0 is set in '''missingBits''', it means fragment #4 (0 + 3 + 1) is still missing.

This extended acknowledgment lets the sending party optimize its retransmissions even when some acknowledgments are lost.

''Extended Acknowledgments'' are only useful when the total amount of fragments
is 3 or above. Indeed, with only 2 fragments, the ''Cumulative Acknowledgment''
lets the receiving party know about the whole reception state.

When the amount of fragments is 3 or more and only a ''Cumulative Acknowledgment'' is sent out, it '''implicitly denies reception''' of any other fragments. This optimizes bandwidth since the 4 extra bytes sent out will only be required for large messages (more than 2 fragments) in case fragments are received out-of-order.

=== Negotiation ===

Before the recipient can use this extension, it must be certain that the sender will understand its semantics. Indeed, imagine the case where a 3-fragment message is sent and completely received, and therefore the recipient only sends a ''Cumulative Acknowledge'' for fragment #3. A legacy sender would think fragments #1 and #2 are still missing.

To signify to the recipient that the sender will understand the new acknowledgments, it '''must set the flag 0x10''' in all the fragments it sends. This new flag is therefore defined as:

* '''Improved Acknowledgements''': when the flag '''0x10''' is set in emitted fragments, it tells the other party that it can reply with the ''Cumulative Acknowledgments'' or the ''Extended Acknowledgment'' bits in its acknowledgment messages.

When the ''Improved Acknowledgments'' flag is '''missing''', the receiver '''must fall back''' to the ''legacy'' acknowledgment protocol. Since '''0x10''' is in the high-nibble part of the flag field, no legacy implementation will choke upon seeing it, and they can safely ignore it. This guarantees the sender that the message will be processed correctly by legacy implementations.

=== Delayed Acknowledgments ===

To maximize the usefulness of ''Cumulative Acknowledgments'', the receiver can delay its acknowledgments for a small period of time (100 ms, say) in the hope that more fragments of the message will arrive meanwhile, provided the message has more than 1 fragment naturally. When the 100 ms delay is expired, it can then acknowledge everything it got so far. Performance will not be impacted by this small delaying, but it can save a few acknowledgments for larger messages.

This means a sender must use a transmission policy whereby it first sends '''all the fragments''' of each message at once, then waits for acknowledgments or timeouts before retransmitting the um-acknowledged fragments. In other words, the sender should not send a fragment, wait for its acknowledgement before sending the next one: this would delay the reception of the entire message and it would prevent using the optimizations that this extension proposal wants to promote!

=== Author ===

This proposal was created by Raphael Manfredi, last modified on 01:03, 26 September 2012 (PDT).

UDP Transceiver

2012-09-27T07:11:05Z

Ram: /* Delayed Acknowledgments */

[[TCP_Stream_Connection_and_Handshaking|<< TCP Stream Connection and Handshaking]] | [[Packet_Structure|Packet Structure >>]] | [[Main_Page|Main Page]]

== Introduction ==

The User Datagram Protocol (UDP) is invaluable in peer to peer systems because it
provides a relatively low-cost (low-overhead) method of sending short, irregular
messages to a very large number of peers on demand. Establishing a TCP stream
connection to a peer simply to deliver a single packet of information is wasteful in
data volume and time for the peers involved and state-aware network devices along
the route, for example, network address translation facilities. When dealing with a
large number of peers quickly, these costs become unbearable. UDP provides a
solution and makes this kind of interaction possible.

However, the delivery of UDP packets is not reliable: packets may be lost en-route for
a number of reasons. Often this behaviour is desirable, for example when the
destination node's connection is highly congested, UDP packets are likely to be
discarded. If the content was not critical, this loss is appropriate as the host's
resources are effectively unavailable. In other scenarios involving critical payloads,
UDP's lack of reliability is a problem: either the sender needs to make sure the
receiver gets the payload, or it needs to know definitively that the receiver was
unavailable.

The Gnutella2 network solves this problem by implementing a selectively engaged
reliability layer on top of the basic UDP protocol. This reliability layer shares some
common functionality with TCP, but importantly does not provide any connection
state and thus retains the efficiency originally sought in UDP.

This allows Gnutella2 to select the most optimal communication medium for each
and every transmission it needs to perform:

* If a significant volume of data is to be exchanged, or subsequent data will be exchanged with the same destination, a TCP connection is established
* If a small volume of important data is to be exchanged in a once-off operation or irregularly, reliable UDP is used
* If a small volume of unimportant data is to be exchanged in a once-off operation or irregularly, unreliable UDP is used

== UDP ==

Gnutella2 semi-reliable communication is transported using the UDP protocol. The
port number for receiving UDP is the same as the port number listening for TCP
connections.

== Encoding ==

Implementing an additional reliable protocol within UDP requires a small control
header before the payload itself. This header is put to good use:

A small signature identifies the packet as a Gnutella2 semi-reliable UDP datagram.
This allows the same port to be used for receiving UDP traffic for other protocols if
desired, and offers some simple protection against random, unexpected traffic.
A content code identifies the payload as a Gnutella2 packet stream, allowing future
protocols to be added within the same reliability layer if desired.
Flags allow additional attributes to be specified, such as inline stateless compression
of the payload (which is a required feature).
The header has a fixed size of 8 bytes, and is represented by the following C
structure:

<pre>
<nowiki>
#pragma pack(1)
typedef struct
{
CHAR szTag[3];
BYTE nFlags;
WORD nSequence;
BYTE nPart;
BYTE nCount;
} GND_HEADER;
</nowiki>
</pre>

Byte format:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| szTag | nFlags | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nSequence | nPart | nCount | 4-7
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

The members of the structure are detailed below:

* '''szTag''' - contains a three byte encoding protocol identifier, in this case "GND" for "GNutella Datagram". If this signature is not present the packet should not be decoded as a Gnutella2 reliability layer transmission.
* '''nFlags''' - contains flags which modify the content of the packet. The low-order nibble is reserved for critical flags: if one of these bits is set but the decoding software does not understand the meaning, the packet must be discarded. The high-order nibble is reserved for non-critical flags: when set these bits may be interpreted, but an inability to interpret a bit does not cause the packet to be discarded. Currently defined flags are:
:* '''0x01''' - Deflate
:: When the deflate bit is set, the entire payload is compressed with the deflate algorithm. The compression method used is the Deflate Compression Data Format (RFC 1951). On top of this compression a ZLIB ‘wrapper’ is applied (RFC 1950, ZLIB Compressed Data Format). The ZLIB wrapper ensures packet integrity, among other things. Note that the entire payload must be reassembled in the correct order before it can be deflated if the packet was fragmented. Fragments are not compressed separately!
:* '''0x02''' - Acknowledge Me
:: When the acknowledge me bit is set, the sender is expecting an acknowledgement for this packet.

* '''nSequence''' - contains the sequence number of the packet. This sequence number is unique to the sending host only. It is not unique to the pair of the sending host and receiving host as in TCP, as there is no concept of connection state. Sequence numbers on consecutive packets need not be increasing (although that is convenient) â€“ they must only be different. If a packet is fragmented, all of its fragments will have the same sequence number. Byte order is unimportant here.
* '''nPart''' - contains the fragment part number (1 <= nPart <= nCount)
* '''nCount''' - contains the number of fragment parts in this packet. On a transmission, this value will be non-zero (all packets must have at least one fragment). If nCount is zero, this is an acknowledgement (see below).

== Fragmentation ==

Large packets must be fragmented before they can be sent through most network
interfaces. Different network media have different MTUs, and it is difficult to predict
what the lowest common size will be. Fragmentation and reassembly is performed by
the existing Internet protocols, however, there are two important reasons why the
reliability layer performs its own fragmentation:

* Sockets implementations specify a maximum datagram size. This is adequate for the vast majority of transmissions, but it is desirable to have the transparent ability to send larger packets without worrying about the host implementation.
* When the Internet protocols fragment, a packet and one or more fragments are lost, it may decide to discard the whole packet in an unreliable datagram protocol. The Gnutella2 reliability layer can compensate by retransmitting the whole packet, which would then be re-fragmented and each fragment resent - however, this wastes the fragments that were successfully received before. Managing fragmentation natively allows this optimisation.

Each node determines its own MTU, often based on a best guess combined with
information from the host's sockets implementation. Packets exceeding this size are
fragmented into multiple datagrams of the appropriate size. Each datagram has the
same sequence number and the same fragment count (nCount), but a different
fragment number (nPart).

== Transmission Process ==

When a packet is to be transmitted, the network layer must:

* Cache the payload
* Allocate a new locally and temporally unique sequence number
* Derive the appropriate number of fragments
* Queue the fragments for dispatch
* If the fragments do not need to be acknowledged, the packet can be flushed now

The payload will generally be cached for an appropriate timeout period, or until the
data cache becomes full, at which time older payloads can be discarded. Fragments
are dispatched according to the dispatch algorithm of choice, and the sender listens
for acknowledgements. When an acknowledgement is received:

* Lookup the sent packet by sequence number
* Mark the nPart fragment as received and cancel any retransmissions of this part
* If all fragments have been acknowledged, flush this packet from the cache

If a fragment has been transmitted but has not been acknowledged within the
timeout, it should be retransmitted. A finite number of retransmissions are allowed
before the packet as a whole expires, at which time it is assumed that the packet
was not received.

== Receive Process ==

When a new datagram is received, the network layer must:

* If the acknowledge bit was set, send an acknowledge packet for this sequence number and part number, with nCount set to zero (ack)
* Lookup any existing packet by the sending IP and sequence number
* If there is no existing packet, create a new packet entry with the IP, sequence number, fragment count and flags
* If there was an existing packet, make sure it is not marked as done - if so, abort
* Add the transmitted fragment to the (new or old) packet entry
* If the packet now has all fragments, mark it as done and decode it and pass it up to the application layer
* Leave the packet on the cache even if it was finished, in case any parts are retransmitted
* Expire old packets from the receive buffer after a timeout, or if the buffer is full

== Dispatch Algorithm ==

Fragment datagrams need to be dispatched intelligently, to spread the load on
network resources and maximise the chance that the receiver will get the message.
To do this, the dispatch algorithm should take into account several points:

* Prioritize acknowledgements.
* If fragments are waiting to be sent to a number of hosts, do not send to the same host twice in a row. Alternating, or looping through the target hosts achieves the same data rate locally, but spreads out the load over downstream links.
* Do not exceed or approach the capacity of the local network connection. If a host has a 128 kb/s outbound bandwidth, dispatching 32 KB of data in one second will likely cause massive packet loss, leading to a retransmission.
* After considering the above points, prefer fragments that were queued recently to older packets. A LIFO or stack type approach means that even if a transmitter is becoming backed up, some fragments will get there on time, while others will be delayed. A FIFO approach would mean that a backed up host delivers every fragment late.

== Parameters ==
The recommended parameters for the reliability layer are as follows:

<pre>
<nowiki>
MTU = 500 bytes
Transmit Retransmit Interval = 10 seconds
Transmit Packet Timeout / Expire = 26 seconds (allows for two retransmissions before expiry)
Receive Packet Expiry = 30 seconds (allows 10 seconds beyond final retransmission)
</nowiki>
</pre>

The UDP/IP header being typically 28 bytes, it is best to limit the payload of the messages to '''476 bytes'''. That way, with the 8-byte header we're topping plus the UDP/IP header, the whole message will not be greater than 512 bytes. The recommended MTU should therefore be 476 rather than the legacy 500. --RAM, 05:19, 23 September 2012 (PDT)

== Performance Considerations ==

Relatively low-level network implementations such as this are reasonably
complicated, but must operate fast. It is desirable to avoid runtime memory
allocations in network code as much as possible, and particularly at this level.

It should be noted that in almost all cases, transmissions to "untested" nodes are
single fragment. Replies on the other hand are often larger, and may be deflated in
many fragments. This is optimal, because attempting to contact a node which may be
unavailable, involves a retransmission of only a single fragment.

Flow control is an important topic, however, it is handled at a higher layer. The UDP
reliability layer is only responsible for guaranteeing delivery of selected datagrams.

Only critical transmissions whose reception cannot otherwise be inferred, should have
the acknowledge request bit set.

== Extension Proposal ==

The following is still a proposoal, but since there is no G2 Development Forum where this can be discussed, I thought I would document it here. 05:07, 23 September 2012 (PDT)

This extension ''should'' be '''totally backward compatible''' with existing implementations provided the above page specifications were strictly adhered to. Here it goes:

=== Improved Acknowledgments ===

Because acknowledgment messages can be lost in the way or arrive out of order, it is best to include as much of the reception state as possible so that the sending party can optimize retransmissions.

In order to do that, the following extensions to the original specifications has been added by gtk-gnutella:

* '''Cumulative Acknowledgements''': when the flag '''0x10''' is set, it tells the other party that '''all''' the fragments up to '''nPart''' have been received.

* '''Extended Acknowledgments''': when the flag '''0x20''' is set, it tells the other party that an acknowledgment payload is present. It immediately follows the header and is architected thusly:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nReceived | missingBits | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

'''nReceived''' is the total amount of parts successfully received so far.

'''missingBits''' is a bitfield that is read as a '''big-endian number''' and which contains set bits for the parts still missing. The ''base'' part number is normally 0, unless flag '''0x10''' was set, in which case the '''nPart''' value indicates the base. The rule is then that if bit ''b'' is set, then the fragment number ''b'' + ''base'' + 1 is still missing.

In the unlikely case where missingBits is too small to hold all the missing parts, only the ones that can be represented are included, the '''nReceived''' field being there to provide additional information.

Proper generation and parsing of the '''missingBits''' field is crucial, so to remove any ambiguity, it is best to interpret missingBits as a number. Then bit 0 is the bit corresponding to 2^0, bit ''n'' is the bit corresponding to 2^n. In the above framing pictogram, bit 0 is the 7th bit of the 3rd byte (because the number in '''missingBits''' is encoded in ''big-endian'').

Bit 0 corresponds to fragment #1, unless the '''0x10''' flag was set. In that case, if for instance '''nPart''' is 3, then it means fragments #1, #2 and #3 were already received. The base is therefore 3, and if bit 0 is set in '''missingBits''', it means fragment #4 (0 + 3 + 1) is still missing.

This extended acknowledgment lets the sending party optimize its retransmissions even when some acknowledgments are lost.

''Extended Acknowledgments'' are only useful when the total amount of fragments
is 3 or above. Indeed, with only 2 fragments, the ''Cumulative Acknowledgment''
lets the receiving party know about the whole reception state.

When the amount of fragments is 3 or more and only a ''Cumulative Acknowledgment'' is sent out, it '''implicitly denies reception''' of any other fragments. This optimizes bandwidth since the 4 extra bytes sent out will only be required for large messages (more than 2 fragments) in case fragments are received out-of-order.

=== Negotiation ===

Before the recipient can use this extension, it must be certain that the sender will understand its semantics. Indeed, imagine the case where a 3-fragment message is sent and completely received, and therefore the recipient only sends a ''Cumulative Acknowledge'' for fragment #3. A legacy sender would think fragments #1 and #2 are still missing.

To signify to the recipient that the sender will understand the new acknowledgments, it '''must set the flag 0x10''' in all the fragments it sends. This new flag is therefore defined as:

* '''Improved Acknowledgements''': when the flag '''0x10''' is set in emitted fragments, it tells the other party that it can reply with the ''Cumulative Acknowledgments'' or the ''Extended Acknowledgment'' bits in its acknowledgment messages.

When the ''Improved Acknowledgments'' flag is '''missing''', the receiver '''must fall back''' to the ''legacy'' acknowledgment protocol. Since '''0x10''' is in the high-nibble part of the flag field, no legacy implementation will choke upon seeing it, and can safely ignore it. This guarantees the sender that the message will be processed correctly by legacy implementations.

=== Delayed Acknowledgments ===

To maximize the usefulness of ''Cumulative Acknowledgments'', the receiver can delay its acknowledgments for a small period of time (100 ms, say) in the hope that more fragments of the message will arrive meanwhile, provided the message has more than 1 fragment naturally. When the 100 ms delay is expired, it can then acknowledge everything it got so far. Performance will not be impacted by this small delaying, but it can save a few acknowledgments for larger messages.

This means a sender must use a transmission policy whereby it first sends '''all the fragments''' of each message at once, then waits for acknowledgments or timeouts before retransmitting the um-acknowledged fragments. In other words, the sender should not send a fragment, wait for its acknowledgement before sending the next one: this would delay the reception of the entire message and it would prevent using the optimizations that this extension proposal wants to promote!

=== Author ===

This proposal was created by Raphael Manfredi, last modified on 01:03, 26 September 2012 (PDT).

UDP Transceiver

2012-09-26T21:45:21Z

Ram: /* Improved Acknowledgments */ Really emphasize that missingBits is big-endian

[[TCP_Stream_Connection_and_Handshaking|<< TCP Stream Connection and Handshaking]] | [[Packet_Structure|Packet Structure >>]] | [[Main_Page|Main Page]]

== Introduction ==

The User Datagram Protocol (UDP) is invaluable in peer to peer systems because it
provides a relatively low-cost (low-overhead) method of sending short, irregular
messages to a very large number of peers on demand. Establishing a TCP stream
connection to a peer simply to deliver a single packet of information is wasteful in
data volume and time for the peers involved and state-aware network devices along
the route, for example, network address translation facilities. When dealing with a
large number of peers quickly, these costs become unbearable. UDP provides a
solution and makes this kind of interaction possible.

However, the delivery of UDP packets is not reliable: packets may be lost en-route for
a number of reasons. Often this behaviour is desirable, for example when the
destination node's connection is highly congested, UDP packets are likely to be
discarded. If the content was not critical, this loss is appropriate as the host's
resources are effectively unavailable. In other scenarios involving critical payloads,
UDP's lack of reliability is a problem: either the sender needs to make sure the
receiver gets the payload, or it needs to know definitively that the receiver was
unavailable.

The Gnutella2 network solves this problem by implementing a selectively engaged
reliability layer on top of the basic UDP protocol. This reliability layer shares some
common functionality with TCP, but importantly does not provide any connection
state and thus retains the efficiency originally sought in UDP.

This allows Gnutella2 to select the most optimal communication medium for each
and every transmission it needs to perform:

* If a significant volume of data is to be exchanged, or subsequent data will be exchanged with the same destination, a TCP connection is established
* If a small volume of important data is to be exchanged in a once-off operation or irregularly, reliable UDP is used
* If a small volume of unimportant data is to be exchanged in a once-off operation or irregularly, unreliable UDP is used

== UDP ==

Gnutella2 semi-reliable communication is transported using the UDP protocol. The
port number for receiving UDP is the same as the port number listening for TCP
connections.

== Encoding ==

Implementing an additional reliable protocol within UDP requires a small control
header before the payload itself. This header is put to good use:

A small signature identifies the packet as a Gnutella2 semi-reliable UDP datagram.
This allows the same port to be used for receiving UDP traffic for other protocols if
desired, and offers some simple protection against random, unexpected traffic.
A content code identifies the payload as a Gnutella2 packet stream, allowing future
protocols to be added within the same reliability layer if desired.
Flags allow additional attributes to be specified, such as inline stateless compression
of the payload (which is a required feature).
The header has a fixed size of 8 bytes, and is represented by the following C
structure:

<pre>
<nowiki>
#pragma pack(1)
typedef struct
{
CHAR szTag[3];
BYTE nFlags;
WORD nSequence;
BYTE nPart;
BYTE nCount;
} GND_HEADER;
</nowiki>
</pre>

Byte format:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| szTag | nFlags | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nSequence | nPart | nCount | 4-7
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

The members of the structure are detailed below:

* '''szTag''' - contains a three byte encoding protocol identifier, in this case "GND" for "GNutella Datagram". If this signature is not present the packet should not be decoded as a Gnutella2 reliability layer transmission.
* '''nFlags''' - contains flags which modify the content of the packet. The low-order nibble is reserved for critical flags: if one of these bits is set but the decoding software does not understand the meaning, the packet must be discarded. The high-order nibble is reserved for non-critical flags: when set these bits may be interpreted, but an inability to interpret a bit does not cause the packet to be discarded. Currently defined flags are:
:* '''0x01''' - Deflate
:: When the deflate bit is set, the entire payload is compressed with the deflate algorithm. The compression method used is the Deflate Compression Data Format (RFC 1951). On top of this compression a ZLIB ‘wrapper’ is applied (RFC 1950, ZLIB Compressed Data Format). The ZLIB wrapper ensures packet integrity, among other things. Note that the entire payload must be reassembled in the correct order before it can be deflated if the packet was fragmented. Fragments are not compressed separately!
:* '''0x02''' - Acknowledge Me
:: When the acknowledge me bit is set, the sender is expecting an acknowledgement for this packet.

* '''nSequence''' - contains the sequence number of the packet. This sequence number is unique to the sending host only. It is not unique to the pair of the sending host and receiving host as in TCP, as there is no concept of connection state. Sequence numbers on consecutive packets need not be increasing (although that is convenient) â€“ they must only be different. If a packet is fragmented, all of its fragments will have the same sequence number. Byte order is unimportant here.
* '''nPart''' - contains the fragment part number (1 <= nPart <= nCount)
* '''nCount''' - contains the number of fragment parts in this packet. On a transmission, this value will be non-zero (all packets must have at least one fragment). If nCount is zero, this is an acknowledgement (see below).

== Fragmentation ==

Large packets must be fragmented before they can be sent through most network
interfaces. Different network media have different MTUs, and it is difficult to predict
what the lowest common size will be. Fragmentation and reassembly is performed by
the existing Internet protocols, however, there are two important reasons why the
reliability layer performs its own fragmentation:

* Sockets implementations specify a maximum datagram size. This is adequate for the vast majority of transmissions, but it is desirable to have the transparent ability to send larger packets without worrying about the host implementation.
* When the Internet protocols fragment, a packet and one or more fragments are lost, it may decide to discard the whole packet in an unreliable datagram protocol. The Gnutella2 reliability layer can compensate by retransmitting the whole packet, which would then be re-fragmented and each fragment resent - however, this wastes the fragments that were successfully received before. Managing fragmentation natively allows this optimisation.

Each node determines its own MTU, often based on a best guess combined with
information from the host's sockets implementation. Packets exceeding this size are
fragmented into multiple datagrams of the appropriate size. Each datagram has the
same sequence number and the same fragment count (nCount), but a different
fragment number (nPart).

== Transmission Process ==

When a packet is to be transmitted, the network layer must:

* Cache the payload
* Allocate a new locally and temporally unique sequence number
* Derive the appropriate number of fragments
* Queue the fragments for dispatch
* If the fragments do not need to be acknowledged, the packet can be flushed now

The payload will generally be cached for an appropriate timeout period, or until the
data cache becomes full, at which time older payloads can be discarded. Fragments
are dispatched according to the dispatch algorithm of choice, and the sender listens
for acknowledgements. When an acknowledgement is received:

* Lookup the sent packet by sequence number
* Mark the nPart fragment as received and cancel any retransmissions of this part
* If all fragments have been acknowledged, flush this packet from the cache

If a fragment has been transmitted but has not been acknowledged within the
timeout, it should be retransmitted. A finite number of retransmissions are allowed
before the packet as a whole expires, at which time it is assumed that the packet
was not received.

== Receive Process ==

When a new datagram is received, the network layer must:

* If the acknowledge bit was set, send an acknowledge packet for this sequence number and part number, with nCount set to zero (ack)
* Lookup any existing packet by the sending IP and sequence number
* If there is no existing packet, create a new packet entry with the IP, sequence number, fragment count and flags
* If there was an existing packet, make sure it is not marked as done - if so, abort
* Add the transmitted fragment to the (new or old) packet entry
* If the packet now has all fragments, mark it as done and decode it and pass it up to the application layer
* Leave the packet on the cache even if it was finished, in case any parts are retransmitted
* Expire old packets from the receive buffer after a timeout, or if the buffer is full

== Dispatch Algorithm ==

Fragment datagrams need to be dispatched intelligently, to spread the load on
network resources and maximise the chance that the receiver will get the message.
To do this, the dispatch algorithm should take into account several points:

* Prioritize acknowledgements.
* If fragments are waiting to be sent to a number of hosts, do not send to the same host twice in a row. Alternating, or looping through the target hosts achieves the same data rate locally, but spreads out the load over downstream links.
* Do not exceed or approach the capacity of the local network connection. If a host has a 128 kb/s outbound bandwidth, dispatching 32 KB of data in one second will likely cause massive packet loss, leading to a retransmission.
* After considering the above points, prefer fragments that were queued recently to older packets. A LIFO or stack type approach means that even if a transmitter is becoming backed up, some fragments will get there on time, while others will be delayed. A FIFO approach would mean that a backed up host delivers every fragment late.

== Parameters ==
The recommended parameters for the reliability layer are as follows:

<pre>
<nowiki>
MTU = 500 bytes
Transmit Retransmit Interval = 10 seconds
Transmit Packet Timeout / Expire = 26 seconds (allows for two retransmissions before expiry)
Receive Packet Expiry = 30 seconds (allows 10 seconds beyond final retransmission)
</nowiki>
</pre>

The UDP/IP header being typically 28 bytes, it is best to limit the payload of the messages to '''476 bytes'''. That way, with the 8-byte header we're topping plus the UDP/IP header, the whole message will not be greater than 512 bytes. The recommended MTU should therefore be 476 rather than the legacy 500. --RAM, 05:19, 23 September 2012 (PDT)

== Performance Considerations ==

Relatively low-level network implementations such as this are reasonably
complicated, but must operate fast. It is desirable to avoid runtime memory
allocations in network code as much as possible, and particularly at this level.

It should be noted that in almost all cases, transmissions to "untested" nodes are
single fragment. Replies on the other hand are often larger, and may be deflated in
many fragments. This is optimal, because attempting to contact a node which may be
unavailable, involves a retransmission of only a single fragment.

Flow control is an important topic, however, it is handled at a higher layer. The UDP
reliability layer is only responsible for guaranteeing delivery of selected datagrams.

Only critical transmissions whose reception cannot otherwise be inferred, should have
the acknowledge request bit set.

== Extension Proposal ==

The following is still a proposoal, but since there is no G2 Development Forum where this can be discussed, I thought I would document it here. 05:07, 23 September 2012 (PDT)

This extension ''should'' be '''totally backward compatible''' with existing implementations provided the above page specifications were strictly adhered to. Here it goes:

=== Improved Acknowledgments ===

Because acknowledgment messages can be lost in the way or arrive out of order, it is best to include as much of the reception state as possible so that the sending party can optimize retransmissions.

In order to do that, the following extensions to the original specifications has been added by gtk-gnutella:

* '''Cumulative Acknowledgements''': when the flag '''0x10''' is set, it tells the other party that '''all''' the fragments up to '''nPart''' have been received.

* '''Extended Acknowledgments''': when the flag '''0x20''' is set, it tells the other party that an acknowledgment payload is present. It immediately follows the header and is architected thusly:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nReceived | missingBits | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

'''nReceived''' is the total amount of parts successfully received so far.

'''missingBits''' is a bitfield that is read as a '''big-endian number''' and which contains set bits for the parts still missing. The ''base'' part number is normally 0, unless flag '''0x10''' was set, in which case the '''nPart''' value indicates the base. The rule is then that if bit ''b'' is set, then the fragment number ''b'' + ''base'' + 1 is still missing.

In the unlikely case where missingBits is too small to hold all the missing parts, only the ones that can be represented are included, the '''nReceived''' field being there to provide additional information.

Proper generation and parsing of the '''missingBits''' field is crucial, so to remove any ambiguity, it is best to interpret missingBits as a number. Then bit 0 is the bit corresponding to 2^0, bit ''n'' is the bit corresponding to 2^n. In the above framing pictogram, bit 0 is the 7th bit of the 3rd byte (because the number in '''missingBits''' is encoded in ''big-endian'').

Bit 0 corresponds to fragment #1, unless the '''0x10''' flag was set. In that case, if for instance '''nPart''' is 3, then it means fragments #1, #2 and #3 were already received. The base is therefore 3, and if bit 0 is set in '''missingBits''', it means fragment #4 (0 + 3 + 1) is still missing.

This extended acknowledgment lets the sending party optimize its retransmissions even when some acknowledgments are lost.

''Extended Acknowledgments'' are only useful when the total amount of fragments
is 3 or above. Indeed, with only 2 fragments, the ''Cumulative Acknowledgment''
lets the receiving party know about the whole reception state.

When the amount of fragments is 3 or more and only a ''Cumulative Acknowledgment'' is sent out, it '''implicitly denies reception''' of any other fragments. This optimizes bandwidth since the 4 extra bytes sent out will only be required for large messages (more than 2 fragments) in case fragments are received out-of-order.

=== Negotiation ===

Before the recipient can use this extension, it must be certain that the sender will understand its semantics. Indeed, imagine the case where a 3-fragment message is sent and completely received, and therefore the recipient only sends a ''Cumulative Acknowledge'' for fragment #3. A legacy sender would think fragments #1 and #2 are still missing.

To signify to the recipient that the sender will understand the new acknowledgments, it '''must set the flag 0x10''' in all the fragments it sends. This new flag is therefore defined as:

* '''Improved Acknowledgements''': when the flag '''0x10''' is set in emitted fragments, it tells the other party that it can reply with the ''Cumulative Acknowledgments'' or the ''Extended Acknowledgment'' bits in its acknowledgment messages.

When the ''Improved Acknowledgments'' flag is '''missing''', the receiver '''must fall back''' to the ''legacy'' acknowledgment protocol. Since '''0x10''' is in the high-nibble part of the flag field, no legacy implementation will choke upon seeing it, and can safely ignore it. This guarantees the sender that the message will be processed correctly by legacy implementations.

=== Delayed Acknowledgments ===

To maximize the usefulness of ''Cumulative Acknowledgments'', the receiver can delay its acknowledgments for a small period of time (100 ms, say) in the hope that more fragments of the message will arrive meanwhile, provided the message has more than 1 fragment naturally. When the 100 ms delay is expired, it can then acknowledge everything it got so far. Performance will not be impacted by this small delaying, but it can save a few acknowledgments for larger messages.

This means a sender must use a transmission policy whereby it first sends '''all the fragments''' of each message at once the first time, then wait for acknowledgments or timeouts before retransmitting the missing fragments. In other words, the sender should not send a fragment, wait for its acknowledge before sending the next one: this delays the reception of the entire message and it prevents using the optimizations that this extension proposal wants to promote!

=== Author ===

This proposal was created by Raphael Manfredi, last modified on 01:03, 26 September 2012 (PDT).

UDP Transceiver

2012-09-26T21:42:04Z

Ram: /* Improved Acknowledgments */

[[TCP_Stream_Connection_and_Handshaking|<< TCP Stream Connection and Handshaking]] | [[Packet_Structure|Packet Structure >>]] | [[Main_Page|Main Page]]

== Introduction ==

The User Datagram Protocol (UDP) is invaluable in peer to peer systems because it
provides a relatively low-cost (low-overhead) method of sending short, irregular
messages to a very large number of peers on demand. Establishing a TCP stream
connection to a peer simply to deliver a single packet of information is wasteful in
data volume and time for the peers involved and state-aware network devices along
the route, for example, network address translation facilities. When dealing with a
large number of peers quickly, these costs become unbearable. UDP provides a
solution and makes this kind of interaction possible.

However, the delivery of UDP packets is not reliable: packets may be lost en-route for
a number of reasons. Often this behaviour is desirable, for example when the
destination node's connection is highly congested, UDP packets are likely to be
discarded. If the content was not critical, this loss is appropriate as the host's
resources are effectively unavailable. In other scenarios involving critical payloads,
UDP's lack of reliability is a problem: either the sender needs to make sure the
receiver gets the payload, or it needs to know definitively that the receiver was
unavailable.

The Gnutella2 network solves this problem by implementing a selectively engaged
reliability layer on top of the basic UDP protocol. This reliability layer shares some
common functionality with TCP, but importantly does not provide any connection
state and thus retains the efficiency originally sought in UDP.

This allows Gnutella2 to select the most optimal communication medium for each
and every transmission it needs to perform:

* If a significant volume of data is to be exchanged, or subsequent data will be exchanged with the same destination, a TCP connection is established
* If a small volume of important data is to be exchanged in a once-off operation or irregularly, reliable UDP is used
* If a small volume of unimportant data is to be exchanged in a once-off operation or irregularly, unreliable UDP is used

== UDP ==

Gnutella2 semi-reliable communication is transported using the UDP protocol. The
port number for receiving UDP is the same as the port number listening for TCP
connections.

== Encoding ==

Implementing an additional reliable protocol within UDP requires a small control
header before the payload itself. This header is put to good use:

A small signature identifies the packet as a Gnutella2 semi-reliable UDP datagram.
This allows the same port to be used for receiving UDP traffic for other protocols if
desired, and offers some simple protection against random, unexpected traffic.
A content code identifies the payload as a Gnutella2 packet stream, allowing future
protocols to be added within the same reliability layer if desired.
Flags allow additional attributes to be specified, such as inline stateless compression
of the payload (which is a required feature).
The header has a fixed size of 8 bytes, and is represented by the following C
structure:

<pre>
<nowiki>
#pragma pack(1)
typedef struct
{
CHAR szTag[3];
BYTE nFlags;
WORD nSequence;
BYTE nPart;
BYTE nCount;
} GND_HEADER;
</nowiki>
</pre>

Byte format:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| szTag | nFlags | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nSequence | nPart | nCount | 4-7
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

The members of the structure are detailed below:

* '''szTag''' - contains a three byte encoding protocol identifier, in this case "GND" for "GNutella Datagram". If this signature is not present the packet should not be decoded as a Gnutella2 reliability layer transmission.
* '''nFlags''' - contains flags which modify the content of the packet. The low-order nibble is reserved for critical flags: if one of these bits is set but the decoding software does not understand the meaning, the packet must be discarded. The high-order nibble is reserved for non-critical flags: when set these bits may be interpreted, but an inability to interpret a bit does not cause the packet to be discarded. Currently defined flags are:
:* '''0x01''' - Deflate
:: When the deflate bit is set, the entire payload is compressed with the deflate algorithm. The compression method used is the Deflate Compression Data Format (RFC 1951). On top of this compression a ZLIB ‘wrapper’ is applied (RFC 1950, ZLIB Compressed Data Format). The ZLIB wrapper ensures packet integrity, among other things. Note that the entire payload must be reassembled in the correct order before it can be deflated if the packet was fragmented. Fragments are not compressed separately!
:* '''0x02''' - Acknowledge Me
:: When the acknowledge me bit is set, the sender is expecting an acknowledgement for this packet.

* '''nSequence''' - contains the sequence number of the packet. This sequence number is unique to the sending host only. It is not unique to the pair of the sending host and receiving host as in TCP, as there is no concept of connection state. Sequence numbers on consecutive packets need not be increasing (although that is convenient) â€“ they must only be different. If a packet is fragmented, all of its fragments will have the same sequence number. Byte order is unimportant here.
* '''nPart''' - contains the fragment part number (1 <= nPart <= nCount)
* '''nCount''' - contains the number of fragment parts in this packet. On a transmission, this value will be non-zero (all packets must have at least one fragment). If nCount is zero, this is an acknowledgement (see below).

== Fragmentation ==

Large packets must be fragmented before they can be sent through most network
interfaces. Different network media have different MTUs, and it is difficult to predict
what the lowest common size will be. Fragmentation and reassembly is performed by
the existing Internet protocols, however, there are two important reasons why the
reliability layer performs its own fragmentation:

* Sockets implementations specify a maximum datagram size. This is adequate for the vast majority of transmissions, but it is desirable to have the transparent ability to send larger packets without worrying about the host implementation.
* When the Internet protocols fragment, a packet and one or more fragments are lost, it may decide to discard the whole packet in an unreliable datagram protocol. The Gnutella2 reliability layer can compensate by retransmitting the whole packet, which would then be re-fragmented and each fragment resent - however, this wastes the fragments that were successfully received before. Managing fragmentation natively allows this optimisation.

Each node determines its own MTU, often based on a best guess combined with
information from the host's sockets implementation. Packets exceeding this size are
fragmented into multiple datagrams of the appropriate size. Each datagram has the
same sequence number and the same fragment count (nCount), but a different
fragment number (nPart).

== Transmission Process ==

When a packet is to be transmitted, the network layer must:

* Cache the payload
* Allocate a new locally and temporally unique sequence number
* Derive the appropriate number of fragments
* Queue the fragments for dispatch
* If the fragments do not need to be acknowledged, the packet can be flushed now

The payload will generally be cached for an appropriate timeout period, or until the
data cache becomes full, at which time older payloads can be discarded. Fragments
are dispatched according to the dispatch algorithm of choice, and the sender listens
for acknowledgements. When an acknowledgement is received:

* Lookup the sent packet by sequence number
* Mark the nPart fragment as received and cancel any retransmissions of this part
* If all fragments have been acknowledged, flush this packet from the cache

If a fragment has been transmitted but has not been acknowledged within the
timeout, it should be retransmitted. A finite number of retransmissions are allowed
before the packet as a whole expires, at which time it is assumed that the packet
was not received.

== Receive Process ==

When a new datagram is received, the network layer must:

* If the acknowledge bit was set, send an acknowledge packet for this sequence number and part number, with nCount set to zero (ack)
* Lookup any existing packet by the sending IP and sequence number
* If there is no existing packet, create a new packet entry with the IP, sequence number, fragment count and flags
* If there was an existing packet, make sure it is not marked as done - if so, abort
* Add the transmitted fragment to the (new or old) packet entry
* If the packet now has all fragments, mark it as done and decode it and pass it up to the application layer
* Leave the packet on the cache even if it was finished, in case any parts are retransmitted
* Expire old packets from the receive buffer after a timeout, or if the buffer is full

== Dispatch Algorithm ==

Fragment datagrams need to be dispatched intelligently, to spread the load on
network resources and maximise the chance that the receiver will get the message.
To do this, the dispatch algorithm should take into account several points:

* Prioritize acknowledgements.
* If fragments are waiting to be sent to a number of hosts, do not send to the same host twice in a row. Alternating, or looping through the target hosts achieves the same data rate locally, but spreads out the load over downstream links.
* Do not exceed or approach the capacity of the local network connection. If a host has a 128 kb/s outbound bandwidth, dispatching 32 KB of data in one second will likely cause massive packet loss, leading to a retransmission.
* After considering the above points, prefer fragments that were queued recently to older packets. A LIFO or stack type approach means that even if a transmitter is becoming backed up, some fragments will get there on time, while others will be delayed. A FIFO approach would mean that a backed up host delivers every fragment late.

== Parameters ==
The recommended parameters for the reliability layer are as follows:

<pre>
<nowiki>
MTU = 500 bytes
Transmit Retransmit Interval = 10 seconds
Transmit Packet Timeout / Expire = 26 seconds (allows for two retransmissions before expiry)
Receive Packet Expiry = 30 seconds (allows 10 seconds beyond final retransmission)
</nowiki>
</pre>

The UDP/IP header being typically 28 bytes, it is best to limit the payload of the messages to '''476 bytes'''. That way, with the 8-byte header we're topping plus the UDP/IP header, the whole message will not be greater than 512 bytes. The recommended MTU should therefore be 476 rather than the legacy 500. --RAM, 05:19, 23 September 2012 (PDT)

== Performance Considerations ==

Relatively low-level network implementations such as this are reasonably
complicated, but must operate fast. It is desirable to avoid runtime memory
allocations in network code as much as possible, and particularly at this level.

It should be noted that in almost all cases, transmissions to "untested" nodes are
single fragment. Replies on the other hand are often larger, and may be deflated in
many fragments. This is optimal, because attempting to contact a node which may be
unavailable, involves a retransmission of only a single fragment.

Flow control is an important topic, however, it is handled at a higher layer. The UDP
reliability layer is only responsible for guaranteeing delivery of selected datagrams.

Only critical transmissions whose reception cannot otherwise be inferred, should have
the acknowledge request bit set.

== Extension Proposal ==

The following is still a proposoal, but since there is no G2 Development Forum where this can be discussed, I thought I would document it here. 05:07, 23 September 2012 (PDT)

This extension ''should'' be '''totally backward compatible''' with existing implementations provided the above page specifications were strictly adhered to. Here it goes:

=== Improved Acknowledgments ===

Because acknowledgment messages can be lost in the way or arrive out of order, it is best to include as much of the reception state as possible so that the sending party can optimize retransmissions.

In order to do that, the following extensions to the original specifications has been added by gtk-gnutella:

* '''Cumulative Acknowledgements''': when the flag '''0x10''' is set, it tells the other party that '''all''' the fragments up to '''nPart''' have been received.

* '''Extended Acknowledgments''': when the flag '''0x20''' is set, it tells the other party that an acknowledgment payload is present. It immediately follows the header and is architected thusly:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nReceived | missingBits | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

'''nReceived''' is the total amount of parts successfully received so far.

'''missingBits''' is a bitfield that is read as a '''big-endian number''' and which contains set bits for the parts still missing. The ''base'' part number is normally 0, unless flag '''0x10''' was set, in which case the '''nPart''' value indicates the base. The rule is then that if bit ''b'' is set, then the fragment number ''b'' + ''base'' + 1 is still missing.

In the unlikely case where missingBits is too small to hold all the missing parts, only the ones that can be represented are included, the '''nReceived''' field being there to provide additional information.

Proper generation and parsing of the missingBits field is crucial, so to remove any ambiguity, it is best to interpret missingBits as a number. Then bit 0 is the bit corresponding to 2^0, bit ''n'' is the bit corresponding to 2^n.

Bit 0 corresponds to fragment #1, unless the '''0x10''' flag was set. In that case, if for instance '''nPart''' is 3, then it means fragments #1, #2 and #3 were already received. The base is therefore 3, and if bit 0 is set in '''missingBits''', it means fragment #4 (0 + 3 + 1) is still missing.

This extended acknowledgment lets the sending party optimize its retransmissions even when some acknowledgments are lost.

''Extended Acknowledgments'' are only useful when the total amount of fragments
is 3 or above. Indeed, with only 2 fragments, the ''Cumulative Acknowledgment''
lets the receiving party know about the whole reception state.

When the amount of fragments is 3 or more and only a ''Cumulative Acknowledgment'' is sent out, it '''implicitly denies reception''' of any other fragments. This optimizes bandwidth since the 4 extra bytes sent out will only be required for large messages (more than 2 fragments) in case fragments are received out-of-order.

=== Negotiation ===

Before the recipient can use this extension, it must be certain that the sender will understand its semantics. Indeed, imagine the case where a 3-fragment message is sent and completely received, and therefore the recipient only sends a ''Cumulative Acknowledge'' for fragment #3. A legacy sender would think fragments #1 and #2 are still missing.

To signify to the recipient that the sender will understand the new acknowledgments, it '''must set the flag 0x10''' in all the fragments it sends. This new flag is therefore defined as:

* '''Improved Acknowledgements''': when the flag '''0x10''' is set in emitted fragments, it tells the other party that it can reply with the ''Cumulative Acknowledgments'' or the ''Extended Acknowledgment'' bits in its acknowledgment messages.

When the ''Improved Acknowledgments'' flag is '''missing''', the receiver '''must fall back''' to the ''legacy'' acknowledgment protocol. Since '''0x10''' is in the high-nibble part of the flag field, no legacy implementation will choke upon seeing it, and can safely ignore it. This guarantees the sender that the message will be processed correctly by legacy implementations.

=== Delayed Acknowledgments ===

To maximize the usefulness of ''Cumulative Acknowledgments'', the receiver can delay its acknowledgments for a small period of time (100 ms, say) in the hope that more fragments of the message will arrive meanwhile, provided the message has more than 1 fragment naturally. When the 100 ms delay is expired, it can then acknowledge everything it got so far. Performance will not be impacted by this small delaying, but it can save a few acknowledgments for larger messages.

This means a sender must use a transmission policy whereby it first sends '''all the fragments''' of each message at once the first time, then wait for acknowledgments or timeouts before retransmitting the missing fragments. In other words, the sender should not send a fragment, wait for its acknowledge before sending the next one: this delays the reception of the entire message and it prevents using the optimizations that this extension proposal wants to promote!

=== Author ===

This proposal was created by Raphael Manfredi, last modified on 01:03, 26 September 2012 (PDT).

UDP Transceiver

2012-09-26T08:03:22Z

Ram: /* Extension Proposal */ Added delayed acknowledgments + negotiation sub-sections

[[TCP_Stream_Connection_and_Handshaking|<< TCP Stream Connection and Handshaking]] | [[Packet_Structure|Packet Structure >>]] | [[Main_Page|Main Page]]

== Introduction ==

The User Datagram Protocol (UDP) is invaluable in peer to peer systems because it
provides a relatively low-cost (low-overhead) method of sending short, irregular
messages to a very large number of peers on demand. Establishing a TCP stream
connection to a peer simply to deliver a single packet of information is wasteful in
data volume and time for the peers involved and state-aware network devices along
the route, for example, network address translation facilities. When dealing with a
large number of peers quickly, these costs become unbearable. UDP provides a
solution and makes this kind of interaction possible.

However, the delivery of UDP packets is not reliable: packets may be lost en-route for
a number of reasons. Often this behaviour is desirable, for example when the
destination node's connection is highly congested, UDP packets are likely to be
discarded. If the content was not critical, this loss is appropriate as the host's
resources are effectively unavailable. In other scenarios involving critical payloads,
UDP's lack of reliability is a problem: either the sender needs to make sure the
receiver gets the payload, or it needs to know definitively that the receiver was
unavailable.

The Gnutella2 network solves this problem by implementing a selectively engaged
reliability layer on top of the basic UDP protocol. This reliability layer shares some
common functionality with TCP, but importantly does not provide any connection
state and thus retains the efficiency originally sought in UDP.

This allows Gnutella2 to select the most optimal communication medium for each
and every transmission it needs to perform:

* If a significant volume of data is to be exchanged, or subsequent data will be exchanged with the same destination, a TCP connection is established
* If a small volume of important data is to be exchanged in a once-off operation or irregularly, reliable UDP is used
* If a small volume of unimportant data is to be exchanged in a once-off operation or irregularly, unreliable UDP is used

== UDP ==

Gnutella2 semi-reliable communication is transported using the UDP protocol. The
port number for receiving UDP is the same as the port number listening for TCP
connections.

== Encoding ==

Implementing an additional reliable protocol within UDP requires a small control
header before the payload itself. This header is put to good use:

A small signature identifies the packet as a Gnutella2 semi-reliable UDP datagram.
This allows the same port to be used for receiving UDP traffic for other protocols if
desired, and offers some simple protection against random, unexpected traffic.
A content code identifies the payload as a Gnutella2 packet stream, allowing future
protocols to be added within the same reliability layer if desired.
Flags allow additional attributes to be specified, such as inline stateless compression
of the payload (which is a required feature).
The header has a fixed size of 8 bytes, and is represented by the following C
structure:

<pre>
<nowiki>
#pragma pack(1)
typedef struct
{
CHAR szTag[3];
BYTE nFlags;
WORD nSequence;
BYTE nPart;
BYTE nCount;
} GND_HEADER;
</nowiki>
</pre>

Byte format:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| szTag | nFlags | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nSequence | nPart | nCount | 4-7
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

The members of the structure are detailed below:

* '''szTag''' - contains a three byte encoding protocol identifier, in this case "GND" for "GNutella Datagram". If this signature is not present the packet should not be decoded as a Gnutella2 reliability layer transmission.
* '''nFlags''' - contains flags which modify the content of the packet. The low-order nibble is reserved for critical flags: if one of these bits is set but the decoding software does not understand the meaning, the packet must be discarded. The high-order nibble is reserved for non-critical flags: when set these bits may be interpreted, but an inability to interpret a bit does not cause the packet to be discarded. Currently defined flags are:
:* '''0x01''' - Deflate
:: When the deflate bit is set, the entire payload is compressed with the deflate algorithm. The compression method used is the Deflate Compression Data Format (RFC 1951). On top of this compression a ZLIB ‘wrapper’ is applied (RFC 1950, ZLIB Compressed Data Format). The ZLIB wrapper ensures packet integrity, among other things. Note that the entire payload must be reassembled in the correct order before it can be deflated if the packet was fragmented. Fragments are not compressed separately!
:* '''0x02''' - Acknowledge Me
:: When the acknowledge me bit is set, the sender is expecting an acknowledgement for this packet.

* '''nSequence''' - contains the sequence number of the packet. This sequence number is unique to the sending host only. It is not unique to the pair of the sending host and receiving host as in TCP, as there is no concept of connection state. Sequence numbers on consecutive packets need not be increasing (although that is convenient) â€“ they must only be different. If a packet is fragmented, all of its fragments will have the same sequence number. Byte order is unimportant here.
* '''nPart''' - contains the fragment part number (1 <= nPart <= nCount)
* '''nCount''' - contains the number of fragment parts in this packet. On a transmission, this value will be non-zero (all packets must have at least one fragment). If nCount is zero, this is an acknowledgement (see below).

== Fragmentation ==

Large packets must be fragmented before they can be sent through most network
interfaces. Different network media have different MTUs, and it is difficult to predict
what the lowest common size will be. Fragmentation and reassembly is performed by
the existing Internet protocols, however, there are two important reasons why the
reliability layer performs its own fragmentation:

* Sockets implementations specify a maximum datagram size. This is adequate for the vast majority of transmissions, but it is desirable to have the transparent ability to send larger packets without worrying about the host implementation.
* When the Internet protocols fragment, a packet and one or more fragments are lost, it may decide to discard the whole packet in an unreliable datagram protocol. The Gnutella2 reliability layer can compensate by retransmitting the whole packet, which would then be re-fragmented and each fragment resent - however, this wastes the fragments that were successfully received before. Managing fragmentation natively allows this optimisation.

Each node determines its own MTU, often based on a best guess combined with
information from the host's sockets implementation. Packets exceeding this size are
fragmented into multiple datagrams of the appropriate size. Each datagram has the
same sequence number and the same fragment count (nCount), but a different
fragment number (nPart).

== Transmission Process ==

When a packet is to be transmitted, the network layer must:

* Cache the payload
* Allocate a new locally and temporally unique sequence number
* Derive the appropriate number of fragments
* Queue the fragments for dispatch
* If the fragments do not need to be acknowledged, the packet can be flushed now

The payload will generally be cached for an appropriate timeout period, or until the
data cache becomes full, at which time older payloads can be discarded. Fragments
are dispatched according to the dispatch algorithm of choice, and the sender listens
for acknowledgements. When an acknowledgement is received:

* Lookup the sent packet by sequence number
* Mark the nPart fragment as received and cancel any retransmissions of this part
* If all fragments have been acknowledged, flush this packet from the cache

If a fragment has been transmitted but has not been acknowledged within the
timeout, it should be retransmitted. A finite number of retransmissions are allowed
before the packet as a whole expires, at which time it is assumed that the packet
was not received.

== Receive Process ==

When a new datagram is received, the network layer must:

* If the acknowledge bit was set, send an acknowledge packet for this sequence number and part number, with nCount set to zero (ack)
* Lookup any existing packet by the sending IP and sequence number
* If there is no existing packet, create a new packet entry with the IP, sequence number, fragment count and flags
* If there was an existing packet, make sure it is not marked as done - if so, abort
* Add the transmitted fragment to the (new or old) packet entry
* If the packet now has all fragments, mark it as done and decode it and pass it up to the application layer
* Leave the packet on the cache even if it was finished, in case any parts are retransmitted
* Expire old packets from the receive buffer after a timeout, or if the buffer is full

== Dispatch Algorithm ==

Fragment datagrams need to be dispatched intelligently, to spread the load on
network resources and maximise the chance that the receiver will get the message.
To do this, the dispatch algorithm should take into account several points:

* Prioritize acknowledgements.
* If fragments are waiting to be sent to a number of hosts, do not send to the same host twice in a row. Alternating, or looping through the target hosts achieves the same data rate locally, but spreads out the load over downstream links.
* Do not exceed or approach the capacity of the local network connection. If a host has a 128 kb/s outbound bandwidth, dispatching 32 KB of data in one second will likely cause massive packet loss, leading to a retransmission.
* After considering the above points, prefer fragments that were queued recently to older packets. A LIFO or stack type approach means that even if a transmitter is becoming backed up, some fragments will get there on time, while others will be delayed. A FIFO approach would mean that a backed up host delivers every fragment late.

== Parameters ==
The recommended parameters for the reliability layer are as follows:

<pre>
<nowiki>
MTU = 500 bytes
Transmit Retransmit Interval = 10 seconds
Transmit Packet Timeout / Expire = 26 seconds (allows for two retransmissions before expiry)
Receive Packet Expiry = 30 seconds (allows 10 seconds beyond final retransmission)
</nowiki>
</pre>

The UDP/IP header being typically 28 bytes, it is best to limit the payload of the messages to '''476 bytes'''. That way, with the 8-byte header we're topping plus the UDP/IP header, the whole message will not be greater than 512 bytes. The recommended MTU should therefore be 476 rather than the legacy 500. --RAM, 05:19, 23 September 2012 (PDT)

== Performance Considerations ==

Relatively low-level network implementations such as this are reasonably
complicated, but must operate fast. It is desirable to avoid runtime memory
allocations in network code as much as possible, and particularly at this level.

It should be noted that in almost all cases, transmissions to "untested" nodes are
single fragment. Replies on the other hand are often larger, and may be deflated in
many fragments. This is optimal, because attempting to contact a node which may be
unavailable, involves a retransmission of only a single fragment.

Flow control is an important topic, however, it is handled at a higher layer. The UDP
reliability layer is only responsible for guaranteeing delivery of selected datagrams.

Only critical transmissions whose reception cannot otherwise be inferred, should have
the acknowledge request bit set.

== Extension Proposal ==

The following is still a proposoal, but since there is no G2 Development Forum where this can be discussed, I thought I would document it here. 05:07, 23 September 2012 (PDT)

This extension ''should'' be '''totally backward compatible''' with existing implementations provided the above page specifications were strictly adhered to. Here it goes:

=== Improved Acknowledgments ===

Because acknowledgment messages can be lost in the way or arrive out of order, it is best to include as much of the reception state as possible so that the sending party can optimize retransmissions.

In order to do that, the following extensions to the original specifications has been added by gtk-gnutella:

* '''Cumulative Acknowledgements''': when the flag '''0x10''' is set, it tells the other party that '''all''' the fragments up to '''nPart''' have been received.

* '''Extended Acknowledgments''': when the flag '''0x20''' is set, it tells the other party that an acknowledgment payload is present. It immediately follows the header and is architected thusly:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nReceived | missingBits | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

'''nReceived''' is the total amount of parts successfully received so far.

'''missingBits''' is a bitfield that is read as a big-endian number and which contains set bits for the parts still missing. The ''base'' part number is normally 0, unless flag '''0x10''' was set, in which case the '''nPart''' value indicates the base. The rule is then that if bit ''b'' is set, then the fragment number ''b'' + ''base'' + 1 is still missing.

In the unlikely case where missingBits is too small to hold all the missing parts, only the ones that can be represented are included, the '''nReceived''' field being there to provide additional information.

Proper generation and parsing of the missingBits field is crucial, so to remove any ambiguity, it is best to interpret missingBits as a number. Then bit 0 is the bit corresponding to 2^0, bit ''n'' is the bit corresponding to 2^n.

Bit 0 corresponds to fragment #1, unless the '''0x10''' flag was set. In that case, if for instance '''nPart''' is 3, then it means fragments #1, #2 and #3 were already received. The base is therefore 3, and if bit 0 is set in '''missingBits''', it means fragment #4 (0 + 3 + 1) is still missing.

This extended acknowledgment lets the sending party optimize its retransmissions even when some acknowledgments are lost.

''Extended Acknowledgments'' are only useful when the total amount of fragments
is 3 or above. Indeed, with only 2 fragments, the ''Cumulative Acknowledgment''
lets the receiving party know about the whole reception state.

When the amount of fragments is 3 or more and only a ''Cumulative Acknowledgment'' is sent out, it '''implicitly denies reception''' of any other fragments. This optimizes bandwidth since the 4 extra bytes sent out will only be required for large messages (more than 2 fragments) in case fragments are received out-of-order.

=== Negotiation ===

Before the recipient can use this extension, it must be certain that the sender will understand its semantics. Indeed, imagine the case where a 3-fragment message is sent and completely received, and therefore the recipient only sends a ''Cumulative Acknowledge'' for fragment #3. A legacy sender would think fragments #1 and #2 are still missing.

To signify to the recipient that the sender will understand the new acknowledgments, it '''must set the flag 0x10''' in all the fragments it sends. This new flag is therefore defined as:

* '''Improved Acknowledgements''': when the flag '''0x10''' is set in emitted fragments, it tells the other party that it can reply with the ''Cumulative Acknowledgments'' or the ''Extended Acknowledgment'' bits in its acknowledgment messages.

When the ''Improved Acknowledgments'' flag is '''missing''', the receiver '''must fall back''' to the ''legacy'' acknowledgment protocol. Since '''0x10''' is in the high-nibble part of the flag field, no legacy implementation will choke upon seeing it, and can safely ignore it. This guarantees the sender that the message will be processed correctly by legacy implementations.

=== Delayed Acknowledgments ===

To maximize the usefulness of ''Cumulative Acknowledgments'', the receiver can delay its acknowledgments for a small period of time (100 ms, say) in the hope that more fragments of the message will arrive meanwhile, provided the message has more than 1 fragment naturally. When the 100 ms delay is expired, it can then acknowledge everything it got so far. Performance will not be impacted by this small delaying, but it can save a few acknowledgments for larger messages.

This means a sender must use a transmission policy whereby it first sends '''all the fragments''' of each message at once the first time, then wait for acknowledgments or timeouts before retransmitting the missing fragments. In other words, the sender should not send a fragment, wait for its acknowledge before sending the next one: this delays the reception of the entire message and it prevents using the optimizations that this extension proposal wants to promote!

=== Author ===

This proposal was created by Raphael Manfredi, last modified on 01:03, 26 September 2012 (PDT).

UDP Transceiver

2012-09-23T12:55:35Z

Ram: /* Encoding */ Fixed szTag item in structure (was missing [])

[[TCP_Stream_Connection_and_Handshaking|<< TCP Stream Connection and Handshaking]] | [[Packet_Structure|Packet Structure >>]] | [[Main_Page|Main Page]]

== Introduction ==

The User Datagram Protocol (UDP) is invaluable in peer to peer systems because it
provides a relatively low-cost (low-overhead) method of sending short, irregular
messages to a very large number of peers on demand. Establishing a TCP stream
connection to a peer simply to deliver a single packet of information is wasteful in
data volume and time for the peers involved and state-aware network devices along
the route, for example, network address translation facilities. When dealing with a
large number of peers quickly, these costs become unbearable. UDP provides a
solution and makes this kind of interaction possible.

However, the delivery of UDP packets is not reliable: packets may be lost en-route for
a number of reasons. Often this behaviour is desirable, for example when the
destination node's connection is highly congested, UDP packets are likely to be
discarded. If the content was not critical, this loss is appropriate as the host's
resources are effectively unavailable. In other scenarios involving critical payloads,
UDP's lack of reliability is a problem: either the sender needs to make sure the
receiver gets the payload, or it needs to know definitively that the receiver was
unavailable.

The Gnutella2 network solves this problem by implementing a selectively engaged
reliability layer on top of the basic UDP protocol. This reliability layer shares some
common functionality with TCP, but importantly does not provide any connection
state and thus retains the efficiency originally sought in UDP.

This allows Gnutella2 to select the most optimal communication medium for each
and every transmission it needs to perform:

* If a significant volume of data is to be exchanged, or subsequent data will be exchanged with the same destination, a TCP connection is established
* If a small volume of important data is to be exchanged in a once-off operation or irregularly, reliable UDP is used
* If a small volume of unimportant data is to be exchanged in a once-off operation or irregularly, unreliable UDP is used

== UDP ==

Gnutella2 semi-reliable communication is transported using the UDP protocol. The
port number for receiving UDP is the same as the port number listening for TCP
connections.

== Encoding ==

Implementing an additional reliable protocol within UDP requires a small control
header before the payload itself. This header is put to good use:

A small signature identifies the packet as a Gnutella2 semi-reliable UDP datagram.
This allows the same port to be used for receiving UDP traffic for other protocols if
desired, and offers some simple protection against random, unexpected traffic.
A content code identifies the payload as a Gnutella2 packet stream, allowing future
protocols to be added within the same reliability layer if desired.
Flags allow additional attributes to be specified, such as inline stateless compression
of the payload (which is a required feature).
The header has a fixed size of 8 bytes, and is represented by the following C
structure:

<pre>
<nowiki>
#pragma pack(1)
typedef struct
{
CHAR szTag[3];
BYTE nFlags;
WORD nSequence;
BYTE nPart;
BYTE nCount;
} GND_HEADER;
</nowiki>
</pre>

Byte format:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| szTag | nFlags | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nSequence | nPart | nCount | 4-7
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

The members of the structure are detailed below:

* '''szTag''' - contains a three byte encoding protocol identifier, in this case "GND" for "GNutella Datagram". If this signature is not present the packet should not be decoded as a Gnutella2 reliability layer transmission.
* '''nFlags''' - contains flags which modify the content of the packet. The low-order nibble is reserved for critical flags: if one of these bits is set but the decoding software does not understand the meaning, the packet must be discarded. The high-order nibble is reserved for non-critical flags: when set these bits may be interpreted, but an inability to interpret a bit does not cause the packet to be discarded. Currently defined flags are:
:* '''0x01''' - Deflate
:: When the deflate bit is set, the entire payload is compressed with the deflate algorithm. The compression method used is the Deflate Compression Data Format (RFC 1951). On top of this compression a ZLIB ‘wrapper’ is applied (RFC 1950, ZLIB Compressed Data Format). The ZLIB wrapper ensures packet integrity, among other things. Note that the entire payload must be reassembled in the correct order before it can be deflated if the packet was fragmented. Fragments are not compressed separately!
:* '''0x02''' - Acknowledge Me
:: When the acknowledge me bit is set, the sender is expecting an acknowledgement for this packet.

* '''nSequence''' - contains the sequence number of the packet. This sequence number is unique to the sending host only. It is not unique to the pair of the sending host and receiving host as in TCP, as there is no concept of connection state. Sequence numbers on consecutive packets need not be increasing (although that is convenient) â€“ they must only be different. If a packet is fragmented, all of its fragments will have the same sequence number. Byte order is unimportant here.
* '''nPart''' - contains the fragment part number (1 <= nPart <= nCount)
* '''nCount''' - contains the number of fragment parts in this packet. On a transmission, this value will be non-zero (all packets must have at least one fragment). If nCount is zero, this is an acknowledgement (see below).

== Fragmentation ==

Large packets must be fragmented before they can be sent through most network
interfaces. Different network media have different MTUs, and it is difficult to predict
what the lowest common size will be. Fragmentation and reassembly is performed by
the existing Internet protocols, however, there are two important reasons why the
reliability layer performs its own fragmentation:

* Sockets implementations specify a maximum datagram size. This is adequate for the vast majority of transmissions, but it is desirable to have the transparent ability to send larger packets without worrying about the host implementation.
* When the Internet protocols fragment, a packet and one or more fragments are lost, it may decide to discard the whole packet in an unreliable datagram protocol. The Gnutella2 reliability layer can compensate by retransmitting the whole packet, which would then be re-fragmented and each fragment resent - however, this wastes the fragments that were successfully received before. Managing fragmentation natively allows this optimisation.

Each node determines its own MTU, often based on a best guess combined with
information from the host's sockets implementation. Packets exceeding this size are
fragmented into multiple datagrams of the appropriate size. Each datagram has the
same sequence number and the same fragment count (nCount), but a different
fragment number (nPart).

== Transmission Process ==

When a packet is to be transmitted, the network layer must:

* Cache the payload
* Allocate a new locally and temporally unique sequence number
* Derive the appropriate number of fragments
* Queue the fragments for dispatch
* If the fragments do not need to be acknowledged, the packet can be flushed now

The payload will generally be cached for an appropriate timeout period, or until the
data cache becomes full, at which time older payloads can be discarded. Fragments
are dispatched according to the dispatch algorithm of choice, and the sender listens
for acknowledgements. When an acknowledgement is received:

* Lookup the sent packet by sequence number
* Mark the nPart fragment as received and cancel any retransmissions of this part
* If all fragments have been acknowledged, flush this packet from the cache

If a fragment has been transmitted but has not been acknowledged within the
timeout, it should be retransmitted. A finite number of retransmissions are allowed
before the packet as a whole expires, at which time it is assumed that the packet
was not received.

== Receive Process ==

When a new datagram is received, the network layer must:

* If the acknowledge bit was set, send an acknowledge packet for this sequence number and part number, with nCount set to zero (ack)
* Lookup any existing packet by the sending IP and sequence number
* If there is no existing packet, create a new packet entry with the IP, sequence number, fragment count and flags
* If there was an existing packet, make sure it is not marked as done - if so, abort
* Add the transmitted fragment to the (new or old) packet entry
* If the packet now has all fragments, mark it as done and decode it and pass it up to the application layer
* Leave the packet on the cache even if it was finished, in case any parts are retransmitted
* Expire old packets from the receive buffer after a timeout, or if the buffer is full

== Dispatch Algorithm ==

Fragment datagrams need to be dispatched intelligently, to spread the load on
network resources and maximise the chance that the receiver will get the message.
To do this, the dispatch algorithm should take into account several points:

* Prioritize acknowledgements.
* If fragments are waiting to be sent to a number of hosts, do not send to the same host twice in a row. Alternating, or looping through the target hosts achieves the same data rate locally, but spreads out the load over downstream links.
* Do not exceed or approach the capacity of the local network connection. If a host has a 128 kb/s outbound bandwidth, dispatching 32 KB of data in one second will likely cause massive packet loss, leading to a retransmission.
* After considering the above points, prefer fragments that were queued recently to older packets. A LIFO or stack type approach means that even if a transmitter is becoming backed up, some fragments will get there on time, while others will be delayed. A FIFO approach would mean that a backed up host delivers every fragment late.

== Parameters ==
The recommended parameters for the reliability layer are as follows:

<pre>
<nowiki>
MTU = 500 bytes
Transmit Retransmit Interval = 10 seconds
Transmit Packet Timeout / Expire = 26 seconds (allows for two retransmissions before expiry)
Receive Packet Expiry = 30 seconds (allows 10 seconds beyond final retransmission)
</nowiki>
</pre>

The UDP/IP header being typically 28 bytes, it is best to limit the payload of the messages to '''476 bytes'''. That way, with the 8-byte header we're topping plus the UDP/IP header, the whole message will not be greater than 512 bytes. The recommended MTU should therefore be 476 rather than the legacy 500. --RAM, 05:19, 23 September 2012 (PDT)

== Performance Considerations ==

Relatively low-level network implementations such as this are reasonably
complicated, but must operate fast. It is desirable to avoid runtime memory
allocations in network code as much as possible, and particularly at this level.

It should be noted that in almost all cases, transmissions to "untested" nodes are
single fragment. Replies on the other hand are often larger, and may be deflated in
many fragments. This is optimal, because attempting to contact a node which may be
unavailable, involves a retransmission of only a single fragment.

Flow control is an important topic, however, it is handled at a higher layer. The UDP
reliability layer is only responsible for guaranteeing delivery of selected datagrams.

Only critical transmissions whose reception cannot otherwise be inferred, should have
the acknowledge request bit set.

== Extension Proposal ==

The following is still a proposoal, but since there is no G2 Development Forum where this can be discussed, I thought I would document it here. 05:07, 23 September 2012 (PDT)

This extension ''should'' be '''totally backward compatible''' with existing implementations provided the above page specifications were strictly adhered to. Here it goes:

Because acknowledgment messages can be lost in the way or arrive out of
order, it is best to include as much of the reception state as possible
so that the sending party can optimize retransmissions.

In order to do that, the following extensions to the original specifications
has been added by gtk-gnutella:

* '''Cumulative Acknowledgements''': when the flag '''0x10''' is set, it tells the other party that '''all''' the fragments up to '''nPart''' have been received.

* '''Extended Acknowledgments''': when the flag '''0x20''' is set, it tells the other party that an acknowledgment payload is present. It immediately follows the header and is architected thusly:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nReceived | missingBits | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

'''nReceived''' is the total amount of parts successfully received so far.

'''missingBits''' is a bitfield that is read as a big-endian number and
which contains set bits for the parts still missing. The ''base'' part number
is normally 0, unless flag '''0x10''' was set, in which case the '''nPart'''
value indicates the base. The rule is then that if bit ''b'' is set,
then the fragment number ''b'' + ''base'' + 1 is still missing.

In the unlikely case where missingBits is too small to hold all the
missing parts, only the ones that can be represented are included, the
'''nReceived''' field being there to provide additional information.

Proper generation and parsing of the missingBits field is crucial, so to
remove any ambiguity, it is best to interpret missingBits as a number.
Then bit 0 is the bit corresponding to 2^0, bit ''n'' is the bit
corresponding to 2^n.

Bit 0 corresponds to fragment #1, unless the '''0x10''' flag was set. In that
case, if for instance '''nPart''' is 3, then it means fragments #1, #2 and #3
were already received. The base is therefore 3, and if bit 0 is set
in '''missingBits''', it means fragment #4 (0 + 3 + 1) is still missing.

This extended acknowledgment lets the sending party optimize its
retransmissions even when some acknowledgments are lost.

''Extended Acknowlegments'' are only useful when the total amount of fragments
is 3 or above. Indeed, with only 2 fragments, the ''Cumulative Acknowledgment''
lets the receiving party know about the whole reception state.

When the amount of fragments is 3 or more and only a
''Cumulative Acknowledgment''
is sent out, it '''implicitly denies reception''' of any other
fragments. This optimizes bandwidth since the 4 extra bytes sent out will
only be required for large messages (more than 2 fragments) in case fragments
are received out-of-order.

UDP Transceiver

2012-09-23T12:19:25Z

Ram: /* Parameters */ MTU should really be 476 bytes, not 500

[[TCP_Stream_Connection_and_Handshaking|<< TCP Stream Connection and Handshaking]] | [[Packet_Structure|Packet Structure >>]] | [[Main_Page|Main Page]]

== Introduction ==

The User Datagram Protocol (UDP) is invaluable in peer to peer systems because it
provides a relatively low-cost (low-overhead) method of sending short, irregular
messages to a very large number of peers on demand. Establishing a TCP stream
connection to a peer simply to deliver a single packet of information is wasteful in
data volume and time for the peers involved and state-aware network devices along
the route, for example, network address translation facilities. When dealing with a
large number of peers quickly, these costs become unbearable. UDP provides a
solution and makes this kind of interaction possible.

However, the delivery of UDP packets is not reliable: packets may be lost en-route for
a number of reasons. Often this behaviour is desirable, for example when the
destination node's connection is highly congested, UDP packets are likely to be
discarded. If the content was not critical, this loss is appropriate as the host's
resources are effectively unavailable. In other scenarios involving critical payloads,
UDP's lack of reliability is a problem: either the sender needs to make sure the
receiver gets the payload, or it needs to know definitively that the receiver was
unavailable.

The Gnutella2 network solves this problem by implementing a selectively engaged
reliability layer on top of the basic UDP protocol. This reliability layer shares some
common functionality with TCP, but importantly does not provide any connection
state and thus retains the efficiency originally sought in UDP.

This allows Gnutella2 to select the most optimal communication medium for each
and every transmission it needs to perform:

* If a significant volume of data is to be exchanged, or subsequent data will be exchanged with the same destination, a TCP connection is established
* If a small volume of important data is to be exchanged in a once-off operation or irregularly, reliable UDP is used
* If a small volume of unimportant data is to be exchanged in a once-off operation or irregularly, unreliable UDP is used

== UDP ==

Gnutella2 semi-reliable communication is transported using the UDP protocol. The
port number for receiving UDP is the same as the port number listening for TCP
connections.

== Encoding ==

Implementing an additional reliable protocol within UDP requires a small control
header before the payload itself. This header is put to good use:

A small signature identifies the packet as a Gnutella2 semi-reliable UDP datagram.
This allows the same port to be used for receiving UDP traffic for other protocols if
desired, and offers some simple protection against random, unexpected traffic.
A content code identifies the payload as a Gnutella2 packet stream, allowing future
protocols to be added within the same reliability layer if desired.
Flags allow additional attributes to be specified, such as inline stateless compression
of the payload (which is a required feature).
The header has a fixed size of 8 bytes, and is represented by the following C
structure:

<pre>
<nowiki>
#pragma pack(1)
typedef struct
{
CHAR szTag3;
BYTE nFlags;
WORD nSequence;
BYTE nPart;
BYTE nCount;
} GND_HEADER;
</nowiki>
</pre>

Byte format:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| szTag | nFlags | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nSequence | nPart | nCount | 4-7
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

The members of the structure are detailed below:

* '''szTag''' - contains a three byte encoding protocol identifier, in this case "GND" for "GNutella Datagram". If this signature is not present the packet should not be decoded as a Gnutella2 reliability layer transmission.
* '''nFlags''' - contains flags which modify the content of the packet. The low-order nibble is reserved for critical flags: if one of these bits is set but the decoding software does not understand the meaning, the packet must be discarded. The high-order nibble is reserved for non-critical flags: when set these bits may be interpreted, but an inability to interpret a bit does not cause the packet to be discarded. Currently defined flags are:
:* '''0x01''' - Deflate
:: When the deflate bit is set, the entire payload is compressed with the deflate algorithm. The compression method used is the Deflate Compression Data Format (RFC 1951). On top of this compression a ZLIB ‘wrapper’ is applied (RFC 1950, ZLIB Compressed Data Format). The ZLIB wrapper ensures packet integrity, among other things. Note that the entire payload must be reassembled in the correct order before it can be deflated if the packet was fragmented. Fragments are not compressed separately!
:* '''0x02''' - Acknowledge Me
:: When the acknowledge me bit is set, the sender is expecting an acknowledgement for this packet.

* '''nSequence''' - contains the sequence number of the packet. This sequence number is unique to the sending host only. It is not unique to the pair of the sending host and receiving host as in TCP, as there is no concept of connection state. Sequence numbers on consecutive packets need not be increasing (although that is convenient) â€“ they must only be different. If a packet is fragmented, all of its fragments will have the same sequence number. Byte order is unimportant here.
* '''nPart''' - contains the fragment part number (1 <= nPart <= nCount)
* '''nCount''' - contains the number of fragment parts in this packet. On a transmission, this value will be non-zero (all packets must have at least one fragment). If nCount is zero, this is an acknowledgement (see below).

== Fragmentation ==

Large packets must be fragmented before they can be sent through most network
interfaces. Different network media have different MTUs, and it is difficult to predict
what the lowest common size will be. Fragmentation and reassembly is performed by
the existing Internet protocols, however, there are two important reasons why the
reliability layer performs its own fragmentation:

* Sockets implementations specify a maximum datagram size. This is adequate for the vast majority of transmissions, but it is desirable to have the transparent ability to send larger packets without worrying about the host implementation.
* When the Internet protocols fragment, a packet and one or more fragments are lost, it may decide to discard the whole packet in an unreliable datagram protocol. The Gnutella2 reliability layer can compensate by retransmitting the whole packet, which would then be re-fragmented and each fragment resent - however, this wastes the fragments that were successfully received before. Managing fragmentation natively allows this optimisation.

Each node determines its own MTU, often based on a best guess combined with
information from the host's sockets implementation. Packets exceeding this size are
fragmented into multiple datagrams of the appropriate size. Each datagram has the
same sequence number and the same fragment count (nCount), but a different
fragment number (nPart).

== Transmission Process ==

When a packet is to be transmitted, the network layer must:

* Cache the payload
* Allocate a new locally and temporally unique sequence number
* Derive the appropriate number of fragments
* Queue the fragments for dispatch
* If the fragments do not need to be acknowledged, the packet can be flushed now

The payload will generally be cached for an appropriate timeout period, or until the
data cache becomes full, at which time older payloads can be discarded. Fragments
are dispatched according to the dispatch algorithm of choice, and the sender listens
for acknowledgements. When an acknowledgement is received:

* Lookup the sent packet by sequence number
* Mark the nPart fragment as received and cancel any retransmissions of this part
* If all fragments have been acknowledged, flush this packet from the cache

If a fragment has been transmitted but has not been acknowledged within the
timeout, it should be retransmitted. A finite number of retransmissions are allowed
before the packet as a whole expires, at which time it is assumed that the packet
was not received.

== Receive Process ==

When a new datagram is received, the network layer must:

* If the acknowledge bit was set, send an acknowledge packet for this sequence number and part number, with nCount set to zero (ack)
* Lookup any existing packet by the sending IP and sequence number
* If there is no existing packet, create a new packet entry with the IP, sequence number, fragment count and flags
* If there was an existing packet, make sure it is not marked as done - if so, abort
* Add the transmitted fragment to the (new or old) packet entry
* If the packet now has all fragments, mark it as done and decode it and pass it up to the application layer
* Leave the packet on the cache even if it was finished, in case any parts are retransmitted
* Expire old packets from the receive buffer after a timeout, or if the buffer is full

== Dispatch Algorithm ==

Fragment datagrams need to be dispatched intelligently, to spread the load on
network resources and maximise the chance that the receiver will get the message.
To do this, the dispatch algorithm should take into account several points:

* Prioritize acknowledgements.
* If fragments are waiting to be sent to a number of hosts, do not send to the same host twice in a row. Alternating, or looping through the target hosts achieves the same data rate locally, but spreads out the load over downstream links.
* Do not exceed or approach the capacity of the local network connection. If a host has a 128 kb/s outbound bandwidth, dispatching 32 KB of data in one second will likely cause massive packet loss, leading to a retransmission.
* After considering the above points, prefer fragments that were queued recently to older packets. A LIFO or stack type approach means that even if a transmitter is becoming backed up, some fragments will get there on time, while others will be delayed. A FIFO approach would mean that a backed up host delivers every fragment late.

== Parameters ==
The recommended parameters for the reliability layer are as follows:

<pre>
<nowiki>
MTU = 500 bytes
Transmit Retransmit Interval = 10 seconds
Transmit Packet Timeout / Expire = 26 seconds (allows for two retransmissions before expiry)
Receive Packet Expiry = 30 seconds (allows 10 seconds beyond final retransmission)
</nowiki>
</pre>

The UDP/IP header being typically 28 bytes, it is best to limit the payload of the messages to '''476 bytes'''. That way, with the 8-byte header we're topping plus the UDP/IP header, the whole message will not be greater than 512 bytes. The recommended MTU should therefore be 476 rather than the legacy 500. --RAM, 05:19, 23 September 2012 (PDT)

== Performance Considerations ==

Relatively low-level network implementations such as this are reasonably
complicated, but must operate fast. It is desirable to avoid runtime memory
allocations in network code as much as possible, and particularly at this level.

It should be noted that in almost all cases, transmissions to "untested" nodes are
single fragment. Replies on the other hand are often larger, and may be deflated in
many fragments. This is optimal, because attempting to contact a node which may be
unavailable, involves a retransmission of only a single fragment.

Flow control is an important topic, however, it is handled at a higher layer. The UDP
reliability layer is only responsible for guaranteeing delivery of selected datagrams.

Only critical transmissions whose reception cannot otherwise be inferred, should have
the acknowledge request bit set.

== Extension Proposal ==

The following is still a proposoal, but since there is no G2 Development Forum where this can be discussed, I thought I would document it here. 05:07, 23 September 2012 (PDT)

This extension ''should'' be '''totally backward compatible''' with existing implementations provided the above page specifications were strictly adhered to. Here it goes:

Because acknowledgment messages can be lost in the way or arrive out of
order, it is best to include as much of the reception state as possible
so that the sending party can optimize retransmissions.

In order to do that, the following extensions to the original specifications
has been added by gtk-gnutella:

* '''Cumulative Acknowledgements''': when the flag '''0x10''' is set, it tells the other party that '''all''' the fragments up to '''nPart''' have been received.

* '''Extended Acknowledgments''': when the flag '''0x20''' is set, it tells the other party that an acknowledgment payload is present. It immediately follows the header and is architected thusly:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nReceived | missingBits | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

'''nReceived''' is the total amount of parts successfully received so far.

'''missingBits''' is a bitfield that is read as a big-endian number and
which contains set bits for the parts still missing. The ''base'' part number
is normally 0, unless flag '''0x10''' was set, in which case the '''nPart'''
value indicates the base. The rule is then that if bit ''b'' is set,
then the fragment number ''b'' + ''base'' + 1 is still missing.

In the unlikely case where missingBits is too small to hold all the
missing parts, only the ones that can be represented are included, the
'''nReceived''' field being there to provide additional information.

Proper generation and parsing of the missingBits field is crucial, so to
remove any ambiguity, it is best to interpret missingBits as a number.
Then bit 0 is the bit corresponding to 2^0, bit ''n'' is the bit
corresponding to 2^n.

Bit 0 corresponds to fragment #1, unless the '''0x10''' flag was set. In that
case, if for instance '''nPart''' is 3, then it means fragments #1, #2 and #3
were already received. The base is therefore 3, and if bit 0 is set
in '''missingBits''', it means fragment #4 (0 + 3 + 1) is still missing.

This extended acknowledgment lets the sending party optimize its
retransmissions even when some acknowledgments are lost.

''Extended Acknowlegments'' are only useful when the total amount of fragments
is 3 or above. Indeed, with only 2 fragments, the ''Cumulative Acknowledgment''
lets the receiving party know about the whole reception state.

When the amount of fragments is 3 or more and only a
''Cumulative Acknowledgment''
is sent out, it '''implicitly denies reception''' of any other
fragments. This optimizes bandwidth since the 4 extra bytes sent out will
only be required for large messages (more than 2 fragments) in case fragments
are received out-of-order.

UDP Transceiver

2012-09-23T12:07:27Z

Ram: Added proposed acknowledgment extension

[[TCP_Stream_Connection_and_Handshaking|<< TCP Stream Connection and Handshaking]] | [[Packet_Structure|Packet Structure >>]] | [[Main_Page|Main Page]]

== Introduction ==

The User Datagram Protocol (UDP) is invaluable in peer to peer systems because it
provides a relatively low-cost (low-overhead) method of sending short, irregular
messages to a very large number of peers on demand. Establishing a TCP stream
connection to a peer simply to deliver a single packet of information is wasteful in
data volume and time for the peers involved and state-aware network devices along
the route, for example, network address translation facilities. When dealing with a
large number of peers quickly, these costs become unbearable. UDP provides a
solution and makes this kind of interaction possible.

However, the delivery of UDP packets is not reliable: packets may be lost en-route for
a number of reasons. Often this behaviour is desirable, for example when the
destination node's connection is highly congested, UDP packets are likely to be
discarded. If the content was not critical, this loss is appropriate as the host's
resources are effectively unavailable. In other scenarios involving critical payloads,
UDP's lack of reliability is a problem: either the sender needs to make sure the
receiver gets the payload, or it needs to know definitively that the receiver was
unavailable.

The Gnutella2 network solves this problem by implementing a selectively engaged
reliability layer on top of the basic UDP protocol. This reliability layer shares some
common functionality with TCP, but importantly does not provide any connection
state and thus retains the efficiency originally sought in UDP.

This allows Gnutella2 to select the most optimal communication medium for each
and every transmission it needs to perform:

* If a significant volume of data is to be exchanged, or subsequent data will be exchanged with the same destination, a TCP connection is established
* If a small volume of important data is to be exchanged in a once-off operation or irregularly, reliable UDP is used
* If a small volume of unimportant data is to be exchanged in a once-off operation or irregularly, unreliable UDP is used

== UDP ==

Gnutella2 semi-reliable communication is transported using the UDP protocol. The
port number for receiving UDP is the same as the port number listening for TCP
connections.

== Encoding ==

Implementing an additional reliable protocol within UDP requires a small control
header before the payload itself. This header is put to good use:

A small signature identifies the packet as a Gnutella2 semi-reliable UDP datagram.
This allows the same port to be used for receiving UDP traffic for other protocols if
desired, and offers some simple protection against random, unexpected traffic.
A content code identifies the payload as a Gnutella2 packet stream, allowing future
protocols to be added within the same reliability layer if desired.
Flags allow additional attributes to be specified, such as inline stateless compression
of the payload (which is a required feature).
The header has a fixed size of 8 bytes, and is represented by the following C
structure:

<pre>
<nowiki>
#pragma pack(1)
typedef struct
{
CHAR szTag3;
BYTE nFlags;
WORD nSequence;
BYTE nPart;
BYTE nCount;
} GND_HEADER;
</nowiki>
</pre>

Byte format:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| szTag | nFlags | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nSequence | nPart | nCount | 4-7
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

The members of the structure are detailed below:

* '''szTag''' - contains a three byte encoding protocol identifier, in this case "GND" for "GNutella Datagram". If this signature is not present the packet should not be decoded as a Gnutella2 reliability layer transmission.
* '''nFlags''' - contains flags which modify the content of the packet. The low-order nibble is reserved for critical flags: if one of these bits is set but the decoding software does not understand the meaning, the packet must be discarded. The high-order nibble is reserved for non-critical flags: when set these bits may be interpreted, but an inability to interpret a bit does not cause the packet to be discarded. Currently defined flags are:
:* '''0x01''' - Deflate
:: When the deflate bit is set, the entire payload is compressed with the deflate algorithm. The compression method used is the Deflate Compression Data Format (RFC 1951). On top of this compression a ZLIB ‘wrapper’ is applied (RFC 1950, ZLIB Compressed Data Format). The ZLIB wrapper ensures packet integrity, among other things. Note that the entire payload must be reassembled in the correct order before it can be deflated if the packet was fragmented. Fragments are not compressed separately!
:* '''0x02''' - Acknowledge Me
:: When the acknowledge me bit is set, the sender is expecting an acknowledgement for this packet.

* '''nSequence''' - contains the sequence number of the packet. This sequence number is unique to the sending host only. It is not unique to the pair of the sending host and receiving host as in TCP, as there is no concept of connection state. Sequence numbers on consecutive packets need not be increasing (although that is convenient) â€“ they must only be different. If a packet is fragmented, all of its fragments will have the same sequence number. Byte order is unimportant here.
* '''nPart''' - contains the fragment part number (1 <= nPart <= nCount)
* '''nCount''' - contains the number of fragment parts in this packet. On a transmission, this value will be non-zero (all packets must have at least one fragment). If nCount is zero, this is an acknowledgement (see below).

== Fragmentation ==

Large packets must be fragmented before they can be sent through most network
interfaces. Different network media have different MTUs, and it is difficult to predict
what the lowest common size will be. Fragmentation and reassembly is performed by
the existing Internet protocols, however, there are two important reasons why the
reliability layer performs its own fragmentation:

* Sockets implementations specify a maximum datagram size. This is adequate for the vast majority of transmissions, but it is desirable to have the transparent ability to send larger packets without worrying about the host implementation.
* When the Internet protocols fragment, a packet and one or more fragments are lost, it may decide to discard the whole packet in an unreliable datagram protocol. The Gnutella2 reliability layer can compensate by retransmitting the whole packet, which would then be re-fragmented and each fragment resent - however, this wastes the fragments that were successfully received before. Managing fragmentation natively allows this optimisation.

Each node determines its own MTU, often based on a best guess combined with
information from the host's sockets implementation. Packets exceeding this size are
fragmented into multiple datagrams of the appropriate size. Each datagram has the
same sequence number and the same fragment count (nCount), but a different
fragment number (nPart).

== Transmission Process ==

When a packet is to be transmitted, the network layer must:

* Cache the payload
* Allocate a new locally and temporally unique sequence number
* Derive the appropriate number of fragments
* Queue the fragments for dispatch
* If the fragments do not need to be acknowledged, the packet can be flushed now

The payload will generally be cached for an appropriate timeout period, or until the
data cache becomes full, at which time older payloads can be discarded. Fragments
are dispatched according to the dispatch algorithm of choice, and the sender listens
for acknowledgements. When an acknowledgement is received:

* Lookup the sent packet by sequence number
* Mark the nPart fragment as received and cancel any retransmissions of this part
* If all fragments have been acknowledged, flush this packet from the cache

If a fragment has been transmitted but has not been acknowledged within the
timeout, it should be retransmitted. A finite number of retransmissions are allowed
before the packet as a whole expires, at which time it is assumed that the packet
was not received.

== Receive Process ==

When a new datagram is received, the network layer must:

* If the acknowledge bit was set, send an acknowledge packet for this sequence number and part number, with nCount set to zero (ack)
* Lookup any existing packet by the sending IP and sequence number
* If there is no existing packet, create a new packet entry with the IP, sequence number, fragment count and flags
* If there was an existing packet, make sure it is not marked as done - if so, abort
* Add the transmitted fragment to the (new or old) packet entry
* If the packet now has all fragments, mark it as done and decode it and pass it up to the application layer
* Leave the packet on the cache even if it was finished, in case any parts are retransmitted
* Expire old packets from the receive buffer after a timeout, or if the buffer is full

== Dispatch Algorithm ==

Fragment datagrams need to be dispatched intelligently, to spread the load on
network resources and maximise the chance that the receiver will get the message.
To do this, the dispatch algorithm should take into account several points:

* Prioritize acknowledgements.
* If fragments are waiting to be sent to a number of hosts, do not send to the same host twice in a row. Alternating, or looping through the target hosts achieves the same data rate locally, but spreads out the load over downstream links.
* Do not exceed or approach the capacity of the local network connection. If a host has a 128 kb/s outbound bandwidth, dispatching 32 KB of data in one second will likely cause massive packet loss, leading to a retransmission.
* After considering the above points, prefer fragments that were queued recently to older packets. A LIFO or stack type approach means that even if a transmitter is becoming backed up, some fragments will get there on time, while others will be delayed. A FIFO approach would mean that a backed up host delivers every fragment late.

== Parameters ==
The recommended parameters for the reliability layer are as follows:

<pre>
<nowiki>
MTU = 500 bytes
Transmit Retransmit Interval = 10 seconds
Transmit Packet Timeout / Expire = 26 seconds (allows for two retransmissions before expiry)
Receive Packet Expiry = 30 seconds (allows 10 seconds beyond final retransmission)
</nowiki>
</pre>

== Performance Considerations ==

Relatively low-level network implementations such as this are reasonably
complicated, but must operate fast. It is desirable to avoid runtime memory
allocations in network code as much as possible, and particularly at this level.

It should be noted that in almost all cases, transmissions to "untested" nodes are
single fragment. Replies on the other hand are often larger, and may be deflated in
many fragments. This is optimal, because attempting to contact a node which may be
unavailable, involves a retransmission of only a single fragment.

Flow control is an important topic, however, it is handled at a higher layer. The UDP
reliability layer is only responsible for guaranteeing delivery of selected datagrams.

Only critical transmissions whose reception cannot otherwise be inferred, should have
the acknowledge request bit set.

== Extension Proposal ==

The following is still a proposoal, but since there is no G2 Development Forum where this can be discussed, I thought I would document it here. 05:07, 23 September 2012 (PDT)

This extension ''should'' be '''totally backward compatible''' with existing implementations provided the above page specifications were strictly adhered to. Here it goes:

Because acknowledgment messages can be lost in the way or arrive out of
order, it is best to include as much of the reception state as possible
so that the sending party can optimize retransmissions.

In order to do that, the following extensions to the original specifications
has been added by gtk-gnutella:

* '''Cumulative Acknowledgements''': when the flag '''0x10''' is set, it tells the other party that '''all''' the fragments up to '''nPart''' have been received.

* '''Extended Acknowledgments''': when the flag '''0x20''' is set, it tells the other party that an acknowledgment payload is present. It immediately follows the header and is architected thusly:

<pre>
<nowiki>
0 1 2 3
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7| Byte
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| nReceived | missingBits | 0-3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</nowiki>
</pre>

'''nReceived''' is the total amount of parts successfully received so far.

'''missingBits''' is a bitfield that is read as a big-endian number and
which contains set bits for the parts still missing. The ''base'' part number
is normally 0, unless flag '''0x10''' was set, in which case the '''nPart'''
value indicates the base. The rule is then that if bit ''b'' is set,
then the fragment number ''b'' + ''base'' + 1 is still missing.

In the unlikely case where missingBits is too small to hold all the
missing parts, only the ones that can be represented are included, the
'''nReceived''' field being there to provide additional information.

Proper generation and parsing of the missingBits field is crucial, so to
remove any ambiguity, it is best to interpret missingBits as a number.
Then bit 0 is the bit corresponding to 2^0, bit ''n'' is the bit
corresponding to 2^n.

Bit 0 corresponds to fragment #1, unless the '''0x10''' flag was set. In that
case, if for instance '''nPart''' is 3, then it means fragments #1, #2 and #3
were already received. The base is therefore 3, and if bit 0 is set
in '''missingBits''', it means fragment #4 (0 + 3 + 1) is still missing.

This extended acknowledgment lets the sending party optimize its
retransmissions even when some acknowledgments are lost.

''Extended Acknowlegments'' are only useful when the total amount of fragments
is 3 or above. Indeed, with only 2 fragments, the ''Cumulative Acknowledgment''
lets the receiving party know about the whole reception state.

When the amount of fragments is 3 or more and only a
''Cumulative Acknowledgment''
is sent out, it '''implicitly denies reception''' of any other
fragments. This optimizes bandwidth since the 4 extra bytes sent out will
only be required for large messages (more than 2 fragments) in case fragments
are received out-of-order.