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