Editing Recomendations

THIS IS NOT FINAL...
If you have any suggestions please post them on the discussion page

= Introduction =

The recommendation system is thought to enhance the filesharing experience.
While most ppl do not offer their list of shared files or do not want to show all files on it or even want to promote files they aren't sharing any longer recommendations will provide a useful addition.

= Features =

The current recommendation system includes:

* manual adding of currently shared/downloading files, search results and ed2k-links to the recommendation list
* possibility to manually (de-)select if a recommendation gets shared
* AICH hash support
* comment support
* rating support

= How it works =

Recommendations are kept in a separate editable list (preferably with a listctrl in sharedfileswnd).
The recommendation support has to be announced via ModProt and uses 2 bits.
Bit number 1 shows if recommendations are supported. This is evaluated in case someone wants to request our list of recommendations and in case we want to request the list from someone.
Bit number 2 shows if some recommendations (at least one) are available. This is evaluated in case we want to request the list from someone. (this is rather cosmetic but should save some overhead).

The request and answer are done via one opcode, if the received packet has "zero" size then it's a request, otherwise it's an answer.
I'd prefere to use
<pre>
#define OP_RECOMMENDATIONS		0x52	//'R'
</pre>
for that packet.

= Packet Format =

The recommendation request is an empty packet with the OP_RECOMMENDATIONS opcode.
The recommendation answer will be sent in any case, even if there are no recommendations available. That way only ONE opcode is used.
The packet will look like that (adapted from official code):
<pre>
[uint32 4]     //filecount
[hash128 16]   //filehash
[uint32 4]     //our ID - only if useful*
[uint16 2]     //our Port - only if useful*
[uint32 4]     //taglist size **
<taglist>      //variable size depending on which tags are to be sent
 includes:
 * filename    //FT_FILENAME
 * filesize    //FT_FILESIZE
 * filerating  //FT_FILERATING
 * filecomment //FT_FILECOMMENT
 can include:
 * filetype    //FT_FILETYPE
 * metadata    //FT_MEDIA_ARTIST,FT_MEDIA_ALBUM,FT_MEDIA_TITLE,FT_MEDIA_LENGTH,FT_MEDIA_BITRATE,FT_MEDIA_CODEC
</pre>

<nowiki>*</nowiki> we are useful if we are connected, not firewalled and do currently share the recommended file
<nowiki>**</nowiki> it would be possible to cut that down to a uint8 (1 byte) to save overhead because it's extremely unlikely that we will ever need more than 255 tags

This format is kept for now so we can easily process the resulting packet using the ProcessSearchAnswer function which is already available in the official client.

[[category:Mod_protocol_extensions]]