Q2

2009-02-07T15:46:34Z

Nascentmind: /* Children */

{{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
* FS - 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.

Gnutella2 - User contributions [en]

Q2