QH2

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

<?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 no known children at the current time.

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