<<< OVERNET_SEARCH_RESULT(MD4(paolo), MD4(file2), MetaTagList(attr(file2))) <<<
[...]
<<< OVERNET_SEARCH_RESULT(MD4(paolo), MD4(fileN), MetaTagList(attr(fileN))) <<<
<<< OVERNET_SEARCH_END(MD4(paolo), nsent, navailable) <<<

Once the user decides to download file 2, to get source location information:

>>> OVERNET_SEARCH(MD4(file2)) >>>
<<< OVERNET_SEARCH_NEXT(list of suggested peers)

and, to peers suggesting themselves:

>>> OVERNET_SEARCH_INFO(MD4(file2))
<<< OVERNET_SEARCH_RESULT(MD4(file2), RelHASH, MetaTagList(attr(fileN))) <<<
<<< OVERNET_SEARCH_RESULT(MD4(file2), RelHASH, MetaTagList(attr(fileN))) <<<
<<< OVERNET_SEARCH_RESULT(MD4(file2), RelHASH, MetaTagList(attr(fileN))) <<<
<<< OVERNET_SEARCH_END(MD4(file2), nsent, navailable) <<<

and the MetaTag list in this case is made of a single tag of type "string", name "loc" and value "bcp://....".

01 00 00 00: this list only has one tag
02: tag type 2, EDONKEY_MTAG_STRING (a pair <string name, string value>)
03 00: a three-character string follows:
6c 6f 63: 'loc'
39 00: a 0x39 (57)-character string follows
...: "bcp://24352535278...:81.190.41.198:7527"


**** EXAMPLES OF SEARCH FILTERS

Here are two exaples of the search filters that may be specified in OVERNET_SEARCH_INFO packets after setting the parameter byte to 0x01:

/* OP AND(OP AND(OP AND ("file", Type="audio"), Size>=1234), Size<=5678) */
unsigned char sf1[] = {
	EDONKEY_SEARCH_BOOL, EDONKEY_SEARCH_AND,
		EDONKEY_SEARCH_BOOL, EDONKEY_SEARCH_AND,
			EDONKEY_SEARCH_BOOL, EDONKEY_SEARCH_AND,
				EDONKEY_SEARCH_NAME,	/* = 01 */
				4, 0,					/* 4-byte value follows */
				'f', 'i', 'l', 'e',		/* keyword's value is "file" */

				EDONKEY_SEARCH_META,	/* = 02 */
				05, 00,					/* 5-byte value follows */
				'a', 'u', 'd', 'i', 'o', /* value is "audio" */
				1, 0,					/* 1-byte tagname follows */
				EDONKEY_STAG_TYPE,	/* = 03 */

			EDONKEY_SEARCH_LIMIT,		/* = 03, numeric limit follows */
			0xd2, 0x04, 0x00, 0x00,		/* limit is 0x4d2 = 1234 */
			EDONKEY_SEARCH_MIN,			/* = 01, min value */
			1, 0,						/* 1-byte tagname follows */
			EDONKEY_STAG_SIZE,			/* = 02 */


		EDONKEY_SEARCH_LIMIT,		/* = 03, numeric limit follows */
		0x2e, 0x16, 0x00, 0x00,		/* limit is 0x162e = 5678 */
		EDONKEY_SEARCH_MAX,			/* = 01, min value */
		1, 0,						/* 1-byte tagname follows */
		EDONKEY_STAG_SIZE			/* = 02 */
};

/* OP AND(OP AND(OP AND ("filename", Format="txt"), Size>=1), Size<=5678) */
unsigned char sf2[] = {
	EDONKEY_SEARCH_BOOL, EDONKEY_SEARCH_AND,
		EDONKEY_SEARCH_BOOL, EDONKEY_SEARCH_AND,
			EDONKEY_SEARCH_BOOL, EDONKEY_SEARCH_AND,
				EDONKEY_SEARCH_NAME,	/* = 01 */
				8, 0,					/* 8-byte value follows */
				'f', 'i', 'l', 'e', 'n', 'a', 'm', 'e',	/* keyword's value is "filename" */

				EDONKEY_SEARCH_META,	/* = 02 */
				3, 0,					/* 3-byte value follows */
				't', 'x', 't', 			/* value is "txt" */
				1, 0,					/* 1-byte tagname follows */
				EDONKEY_STAG_FORMAT,	/* = 03 */

			EDONKEY_SEARCH_LIMIT,		/* = 03, numeric limit follows */
			0x01, 0x00, 0x00, 0x00,		/* limit is 1 */
			EDONKEY_SEARCH_MIN,			/* = 01, min value */
			1, 0,						/* 1-byte tagname follows */
			EDONKEY_STAG_SIZE,			/* = 02 */


		EDONKEY_SEARCH_LIMIT,		/* = 03, numeric limit follows */
		0x2e, 0x16, 0x00, 0x00,		/* limit is 0x162e = 5678 */
		EDONKEY_SEARCH_MAX,			/* = 01, min value */
		1, 0,						/* 1-byte tagname follows */
		EDONKEY_STAG_SIZE			/* = 02 */
};

****** Parameter in OVERNET_SEARCH

OVERNET_SEARCH packets contain a one-byte field (between the OVERNET_MESSAGE (0xe3) and the hash to search for) the meaning of which is commonly assumed to be "find node/find value" as described in [Maymounkov-Mazieres]. Actually, all OVERNET_SEARCH are "find node" operations (they don't stop as soon as data is found), and the parameter seems instead to be related to the purpose of the search. In particular:

   Search for loc or metadata: uses only 0x02
   Publishing:                 uses only 0x04
   Lookup for its own hash:    uses only 0x14

The lookup for own hash is probably done to refresh the k-bucket array with low-distance neighbours (recommended as part of the boot-up procedure at the end of section 2.3 of [Maymounkov-Mazieres]). Overnet, eMuleKAD and RevConnectKAD also have a separate boot mechanism making use of OVERNET_CONNECT / OVERNET_CONNECT_REPLY sessions.

****** On NATting firewalling

There are a few possible meaning of a node "being firewalled". The most common is that its TCP port in not accessible from an external TCP client, usually depending on dynamic Network Address Translation. A node can check if this is the case by issuing an OVERNET_IP_QUERY request to a known peer. the latter will reply immediately with a OVERNET_IP_QUERY_ANSWER, and at the same time will try to open a TCP connection to the TCP port declared in the OVERNET_IP_QUERY packet. In case of success, it will also send a OVERNET_IP_QUERY_END; otherwise, it won't. The initiating peer may use this to infer whether its TCP port was accessible. As TCP access is a purely auxiliary functionality, unrelated to the DHT function, having the TCP port firewalled does not seriously impact the applicability of this library.

A second meaning of a node "being firewalled" is its inability to receive on its UDP port datagrams sent by peers that have NOT recently received UDP packets by the node. Most of NATting devices currently in use punch a temporary "hole" for incoming UDP packets in order to allow responses sent to the same sending port. This makes it possible for a node to "reach out" and transact with any peer on the Net; however, ONLY recently-queried peers will be able to send UDP packets to that node. Here, the precise meaning of "recently" depends on the implementation of the specific NATting device, but in general it means "a few minutes ago". A node firewalled in this sense will be able to publish and retrieve metadata to/from the DHT, but will NOT be able to receive and procss "publish" or "search" commands. In other words, it will not be an "ultrapeer" or "supernode", to use Gnutella or FastTrack jargon. That won't impact its useability, but will not bring any benefit to the community because the local store won't be part of the DHT. To avoid confusion, we'll call this condition "NATted" rather than firewalled (although its initial cause could be different from NAT). A node advertising in the payload an IP address OR a UDP port different from the one contained in the UDP/IP headers shall be said to be in "leaf mode". KadC allows to be put in leaf mode even when not NATted by setting the flag "leafmode" in the KadEngine structure (pKE->leafmode = 1). In that case, outgoing packets will always declare for the sender node an IP address and a UDP port number equal to zero. 

****** The OVERNET_PEER_NOTFOUND (33, 0x21) opcode 

It appears that packets with opcode 0x21 are sent to nodes that in a OVERNET_SEARCH_NEXT had recommended a peer that turned out to be dead. The packet contains hash, IP and UDP port of the peer that had been recommended, followed by a flag which is 0 if that peer had not answered to OVERNET_SEARCH, and 0xfd in some other cases (?). Probably, the intended action for the recipient is to downgrade the peer by raising its type in both kbuckets/kspace and contacts rbt's.

****** Currently unresolved issues

What is the meaning of the two unsigned short ints after the hash in OvernetSearchResult packets?

#define OVERNET_SEARCH_RESULT               0x11  /* < <SEARCH_HASH> <FILE_HASH> <CNT4> <META>[cnt]*//* OvernetSearchResult in mldonkey */
/* the two ushorts are listed by OvernetClc:
> s fat day -Audio
> Got results. (2650,2650)
  Got results. (4564,4564)
Meaning?? */

---------

Which use should a receiving peer make of the previously mentioned parameter in OVERNET_SEARCH (0x02, 0x04 or 0x14)?

---------


****** Appendix - Values of constants used by different flavours of Kademlia, and structure of various packet types 

---------

/* eMule KAD */
#define OP_KADEMLIAHEADER		0xE4
#define OP_KADEMLIAPACKEDPROT	0xE5

#define KADEMLIA_BOOTSTRAP_REQ	0x00	/* <PEER (sender) [25]>				*/
#define KADEMLIA_BOOTSTRAP_RES	0x08	/* <CNT [2]> <PEER [25]>*(CNT)		*/
#define KADEMLIA_HELLO_REQ	 	0x10	/* <PEER (sender) [25]>				*/
#define KADEMLIA_HELLO_RES     	0x18	/* <PEER (reciever) [25]>			*/
#define KADEMLIA_FIREWALLED_REQ	0x50	/* <TCPPORT (sender) [2]>			*/
#define KADEMLIA_FIREWALLED_RES	0x58	/* <IP (sender) [4]>				*/
#define KADEMLIA_FIREWALLED_ACK	0x59	/* (null) (sent if TCP connection to the declared port did actually succeed)	*/
#define KADEMLIA_REQ		   	0x20	/* <TYPE [1]> <HASH (target) [16]> <HASH (reciever) 16> */
#define KADEMLIA_RES			0x28	/* <HASH (target) [16]> <CNT> <PEER [25]>*(CNT) */
#define KADEMLIA_SEARCH_REQ		0x30	/* <HASH (key) [16]> <ext 0/1 [1]> <SEARCH_TREE>[ext] */
#define KADEMLIA_SEARCH_RES		0x38	/* <HASH (key) [16]> <CNT1 [2]> (<HASH (answer) [16]> <CNT2 [2]> <META>*(CNT2))*(CNT1) */
#define KADEMLIA_PUBLISH_REQ	0x40	/* <HASH (key) [16]> <CNT1 [2]> (<HASH (target) [16]> <CNT2 [2]> <META>*(CNT2))*(CNT1) */
#define KADEMLIA_PUBLISH_RES	0x48	/* <HASH (key) [16]>				*/
#define KADEMLIA_BUDDY_REQ		0x51	/* <TCPPORT (sender) [2]>			*/
#define KADEMLIA_BUDDY_CON		0x52	/* 									*/
#define KADEMLIA_BUDDY_ACK		0x57	/* <TCPPORT (sender) [2]>			*/

/* KADEMLIA (parameter for KADEMLIA_REQ)
   note: the three most sign. bits are reserved for future flags */
#define KADEMLIA_FIND_VALUE		0x02
#define KADEMLIA_STORE			0x04
#define KADEMLIA_FIND_NODE		0x0B

/***************************************************************************/

/* RevConnect */
#define OP_REVCONNHEADER		0xD0