Q2

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

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

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

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.