QH2

Root Packets
CRAWLA - CRAWLR
HAW - LNI
KHL - KHLA - KHLR
PI - PO - PUSH
QKA - QKR
Q2 - QA - QH2 - QHT
UPROC - UPROD

/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:

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

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:

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

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:

/gnutella/preview/v1?urn:xyz

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:

<?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>

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 application/x-gnutella2 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