opcodes.h

Go to the documentation of this file.
00001 /**
00002  *  Copyright (C) 2004-2005 Alo Sarv <madcat_@users.sourceforge.net>
00003  *
00004  *  This program is free software; you can redistribute it and/or modify
00005  *  it under the terms of the GNU General Public License as published by
00006  *  the Free Software Foundation; either version 2 of the License, or
00007  *  (at your option) any later version.
00008  *
00009  *  This program is distributed in the hope that it will be useful,
00010  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00011  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00012  *  GNU General Public License for more details.
00013  *
00014  *  You should have received a copy of the GNU General Public License
00015  *  along with this program; if not, write to the Free Software
00016  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
00017  */
00018 
00019 #ifndef __OPCODES_H__
00020 #define __OPCODES_H__
00021 
00022 /**
00023  * @file opcodes.h Interface for protocol opcodes used in ed2k network
00024  * Important: The ed2k protocol overview is generated out from this file,
00025  * so make sure it is still generated correctly after changing things here.
00026  * The code generating it is at the bottom of this file, and it is HIGHLY
00027  * sensitive about reordering of things, as well as other such stuff. So
00028  * please, don't reorder stuff here, nor make any other changes - otherwise
00029  * it'll break the doxygen-generated docs.
00030  */
00031 
00032 //! Protocols
00033 enum ED2K_Protocols {
00034         PR_ED2K  = 0xe3,  //!< Standard, historical eDonkey2000 protocol
00035         PR_EMULE = 0xc5,  //!< eMule extended protocol
00036         PR_ZLIB  = 0xd4   //!< Packet payload is compressed with gzip
00037 };
00038 
00039 //! Login request
00040 enum ED2K_ServerLogin {
00041         OP_LOGINREQUEST = 0x01, //!< <hash>hash<u32>ip<u16>port<TagList>tags
00042         CT_NICK         = 0x01, //!< <string>nick
00043         CT_VERSION      = 0x11, //!< <u8>0x3c
00044         CT_PORT         = 0x0f, //!< <u16>port
00045         CT_MULEVERSION  = 0xfb, //!< <u32>ver
00046         CT_FLAGS        = 0x20, //!< <u8>flags
00047         FL_ZLIB         = 0x01, //!< zlib compression support
00048         FL_IPINLOGIN    = 0x02, //!< Client sends its own ip during login
00049         FL_AUXPORT      = 0x04, //!< ???
00050         FL_NEWTAGS      = 0x08, //!< support for new-styled eMule tags
00051         FL_UNICODE      = 0x10  //!< support for unicode
00052 };
00053 
00054 //! Server response packets to OP_LOGINREQUEST
00055 enum ED2K_ServerMessages {
00056         OP_SERVERMESSAGE = 0x38, //!< <u16>len<len>message
00057         OP_SERVERSTATUS  = 0x34, //!< <u32>users<u32>files
00058         OP_IDCHANGE      = 0x40  //!< <u32>newid
00059 };
00060 
00061 //! Updating information from server
00062 enum ED2K_ServerInfo {
00063         OP_GETSERVERLIST = 0x14, //!< (no payload)
00064         OP_SERVERLIST    = 0x32, //!< <u8>count[{<u32>ip<u16>port}*count]
00065         OP_SERVERIDENT   = 0x41, //!< <hash>hash<u32>ip<u16>port<TagList>tags
00066         CT_SERVERNAME    = 0x01, //!< <string>name
00067         CT_SERVERDESC    = 0x0b  //!< <string>desc
00068 };
00069 
00070 //! Publishing shared files
00071 enum ED2K_Publishing {
00072         //! <u32>count[<count>*{<hash>filehash<u32>ip<u16>port<TagList>tags}]
00073         OP_OFFERFILES    = 0x15,
00074         CT_FILENAME      = 0x01,       //!< <string>name
00075         CT_FILESIZE      = 0x02,       //!< <u32>size
00076         CT_FILETYPE      = 0x03,       //!< <string>type
00077         FL_COMPLETE_ID   = 0xfcfcfcfc, //!< File is complete - send this as ID
00078         FL_COMPLETE_PORT = 0xfcfc,     //!< File is complete - send this as port
00079         FL_PARTIAL_ID    = 0xfbfbfbfb, //!< File is partial  - send this as ID
00080         FL_PARTIAL_PORT  = 0xfbfb      //!< File is partial  - send this as port
00081 };
00082 
00083 #define FT_ED2K_AUDIO    "Audio"    //!< mp3/ogg/wma      etc
00084 #define FT_ED2K_VIDEO    "Video"    //!< avi/mpg/mpeg/wmv etc
00085 #define FT_ED2K_IMAGE    "Image"    //!< png/jpg/gif/tiff etc
00086 #define FT_ED2K_DOCUMENT "Doc"      //!< txt/doc/rtf      etc
00087 #define FT_ED2K_PROGRAM  "Pro"      //!< exe/bin/cue/iso  etc
00088 
00089 //! Searching
00090 enum ED2K_Searching {
00091         OP_SEARCH        = 0x16,       //!< <searchexpr>
00092         //! <u32>count[<count>*{<Hash>hash<u32>id<u16>port<Taglist>tags}]
00093         OP_SEARCHRESULT  = 0x33,
00094         CT_SOURCES       = 0x15,       //!< <u32>numsrc
00095         CT_COMPLSRC      = 0x30,       //!< <u32>numcomplsrc
00096         CT_MEDIA_LENGTH  = 0xd3,       //!< <u32>length
00097         CT_MEDIA_BITRATE = 0xd4,       //!< <u32>bitrate
00098         CT_MEDIA_CODEC   = 0xd5,       //!< <string>codec
00099         CT_LASTSEENCOMPL = 0x05        //!< <u32>lastseencomplete
00100 };
00101 
00102 //! Donkeys getting to know each other
00103 enum ED2K_Hello {
00104         OP_HELLO        = 0x01, //!< <hash>hash<u32>ip<u16>port<TagList>tags
00105         CT_MODSTR       = 0x55, //!< <string>modstring
00106         CT_UDPPORTS     = 0xf9, //!< <u16>kadudpport<u16>ed2kudpport
00107         CT_MISCFEATURES = 0xfa, //!< <u32>features bitset
00108         OP_HELLOANSWER  = 0x4c // <u8>len<hash>hash<u32>ip<u16>port<TagList>tags
00109 };
00110 
00111 //! Mules getting to know each other
00112 enum ED2K_MuleHello {
00113         OP_MULEINFO       = 0x01, //!< <u8>clientver<u8>protver<TagList>tags
00114         CT_COMPRESSION    = 0x20, //!< u32 compression version
00115         CT_UDPPORT        = 0x21, //!< u32 udp port
00116         CT_UDPVER         = 0x22, //!< u32 udp protocol version
00117         CT_SOURCEEXCH     = 0x23, //!< u32 source exchange version
00118         CT_COMMENTS       = 0x24, //!< u32 comment version
00119         CT_EXTREQ         = 0x25, //!< u32 extended request version
00120         CT_COMPATCLIENT   = 0x26, //!< u32 compatible client ID
00121         CT_FEATURES       = 0x27, //!< u32 supported features bitset
00122         CT_MODVERSION     = 0x55, //!< <string>modversion (may also be int)
00123         CT_MODPLUS        = 0x99, //!< mh? (Source: eMule+ Forums ... )
00124         CT_L2HAC          = 0x3e, //!< mh? (Source: eMule+ Forums ... )
00125         OP_MULEINFOANSWER = 0x02  //!< <u8>clientver<u8>protver<TagList>tags
00126 };
00127 
00128 //! Requesting a file
00129 enum ED2K_FileRequest {
00130         OP_REQFILE         = 0x58, //!< <hash>hash
00131         OP_FILENAME        = 0x59, //!< <hash>hash<u32>len<len>name
00132         OP_FILEDESC        = 0x61, //!< <u8>rating<u32>len<len>comment
00133         OP_SETREQFILEID    = 0x4f, //!< <hash>hash
00134         OP_REQFILE_STATUS  = 0x50, //!< <hash>hash<u16>count<count>partmap
00135         OP_REQFILE_NOFILE  = 0x48, //!< <hash>hash
00136         OP_REQHASHSET      = 0x51, //!< <hash>hash
00137         OP_HASHSET         = 0x52, //!< <hash>hash<u16>cnt[cnt*<hash>parthash]
00138         OP_STARTUPLOADREQ  = 0x54, //!< may contain <hash>hash (emule)
00139         OP_ACCEPTUPLOADREQ = 0x55, //!< Empty
00140         OP_QUEUERANKING    = 0x5c, //!< <u32>queueranking
00141         OP_MULEQUEUERANK   = 0x60  //!< <u16>queuerank<u16><u32><u32>empty
00142 };
00143 
00144 //! Transmitting data
00145 enum ED2K_SendingData {
00146         OP_REQCHUNKS      = 0x47, //!< <hash>hash[3*<u32>begin][3*<u32>end]
00147         OP_SENDINGCHUNK   = 0x46, //!< <hash>hash<u32>begin<u32>end<data>
00148         OP_PACKEDCHUNK    = 0x40, //!< <hash>hash><u32>begin<u32>len<len>data
00149         OP_CANCELTRANSFER = 0x56  //!< empty
00150 };
00151 
00152 //! LowID callbacks
00153 enum ED2K_LowIDCallbacks {
00154         OP_REQCALLBACK  = 0x1c,   //!< <u32>id
00155         OP_CBREQUESTED  = 0x35,   //!< <u32>ip<u16>tcpport
00156         OP_CALLBACKFAIL = 0x36    //!< empty
00157 };
00158 
00159 //! Looking for sources
00160 enum ED2K_SourceQueries {
00161         //! @name Client <-> Server
00162         //!@{
00163         OP_GETSOURCES    = 0x19,   //!< <hash>hash
00164         OP_FOUNDSOURCES  = 0x42,   //!< <hash>hash<u8>cnt*[<u32>id<u16>port]
00165         //!@}
00166 
00167         //! @name Client <-> Client Source Exchange
00168         //!@{
00169         OP_REQSOURCES    = 0x81,   //!< <hash>hash
00170         //! <hash>hash<u16>cnt*[<u32>id<u16>port<u32>serverip<u16>serverport]
00171         OP_ANSWERSOURCES = 0x82
00172         //!@}
00173 };
00174 
00175 //! Miscellaneous packets
00176 enum ED2K_Misc {
00177         OP_MESSAGE       = 0x4e,   //!< <u16>len<len>message
00178         OP_PORTTEST      = 0xfe,   //!< Server: <u16>0x12, Client: <u16>1
00179         OP_CHANGEID      = 0x4d    //!< <u32>oldid<u32>newid
00180 };
00181 
00182 //! Secure Identification
00183 enum ED2K_SecIdent {
00184         OP_SECIDENTSTATE = 0x87, //!< <u8>state<u32>challenge
00185         OP_PUBLICKEY     = 0x85, //!< <u8>len<len>pubkey
00186         OP_SIGNATURE     = 0x86  //!< <u8>len<len>signature
00187 };
00188 
00189 enum ED2K_Udp {
00190         //! @name Client <-> Client
00191         //! @{
00192         OP_REASKFILEPING = 0x90,   //!< <hash>hash
00193         OP_REASKACK      = 0x91,   //!< <u16>queueranking
00194         OP_FILENOTFOUND  = 0x92,   //!< empty
00195         OP_QUEUEFULL     = 0x93,   //!< empty
00196         //! @}
00197         //! @name Client <-> Server
00198         //! @{
00199         OP_GLOBGETSOURCES   = 0x9a,  //!< cnt*[<hash>hash]
00200         OP_GLOBGETSOURCES2  = 0x94,  //!< cnt*[<hash>hash<u32>size]
00201         OP_GLOBFOUNDSOURCES = 0x9b,  //!< <hash>hash<u8>cnt*[<u32>id<u16>port]
00202 
00203         OP_GLOBSTATREQ      = 0x96,  //!< <u32>challenge
00204         //! <u32>challenge<u32>users<u32>files<u32>maxusers<u32>softlimit
00205         //! <u32>hardlimit<u32>udpflags<u32>lowusers
00206         OP_GLOBSTATRES      = 0x97
00207         //! @}
00208 };
00209 
00210 /**
00211  * Special tags used in server.met file
00212  */
00213 enum ED2K_ServerMet {
00214         ST_METHEADER   = 0x0e, //!< uint8_t  - MET header
00215         ST_METVERSION  = 0xe0, //!< uint8_t  - server.met version
00216         ST_NAME        = 0x01, //!< string   - name of server
00217         ST_DESC        = 0x0b, //!< string   - description
00218         ST_PING        = 0x0c, //!< uint32_t - ping
00219         ST_PREFERENCE  = 0x0e, //!< uint32_t - preference
00220         ST_FAIL        = 0x0d, //!< uint32_t - failed count
00221         ST_DYNIP       = 0x85, //!< string   - dynamic ip address
00222         ST_MAXUSERS    = 0x87, //!< uint32_t - maximum users
00223         ST_SOFTLIMIT   = 0x88, //!< uint32_t - soft file limit
00224         ST_HARDLIMIT   = 0x89, //!< uint32_t - hard file limit
00225         ST_LASTPING    = 0x90, //!< uint32_t - last ping
00226         ST_VERSION     = 0x91, //!< string   - version string
00227         ST_UDPFLAGS    = 0x92, //!< uint32_t - UDP flags
00228         ST_AUXPORTLIST = 0x93, //!< string   - Auxiliary ports
00229         ST_LOWIDUSRS   = 0x94  //!< uint32_t - Low-id users
00230 };
00231 
00232 /**
00233  * \page ed2kproto eDonkey2000 Protocol
00234  *
00235  * \section abstr Abstract
00236  * This document describes the eDonkey2000 (ED2K) P2P protocol and eMule
00237  * Extended Protocol (EMEP).
00238  *
00239  * \section contents Table of Contents
00240  * \par
00241  * \ref intro          <br>
00242  * - \ref Definitions
00243  * .
00244  * \ref header         <br>
00245  * \ref clieserv       <br>
00246  * \list
00247  * - \ref logsrv       <br>
00248  * - \ref updateinfo   <br>
00249  * - \ref publishshrd  <br>
00250  * - \ref search       <br>
00251  * .
00252  * \ref clicli         <br>
00253  * \list
00254  * - \ref hello        <br>
00255  * - \ref reqfile      <br>
00256  * - \ref upload       <br>
00257  * .
00258  * \ref lowid          <br>
00259  * \list
00260  * - \ref lowidcb      <br>
00261  * .
00262  * \ref srcexch        <br>
00263  * \ref secident       <br>
00264  * \ref misc           <br>
00265  * \ref udp            <br>
00266  *
00267  * \section intro 1. Introduction
00268  * ED2K protocol is used for communication between compatible clients to form
00269  * a server-based peer-to-peer file-sharing network. EMEP is only used between
00270  * eMule (and compatible) clients, but not by official eDonkey2000 clients.
00271  *
00272  * Few words on the packet format strings used here:
00273  * \code
00274  * u8      unsigned 8-bit integer
00275  * u16     unsigned 16-bit integer
00276  * u32     unsigned 32-bit integer
00277  * hash    16-bytes md4 checksum
00278  * string  16-bit integer (specifying string length) followed by the string
00279  * Taglist 32-bit integer (specifying number of tags) followed by the tags
00280  * \endcode
00281  *
00282  * \subsection Definitions
00283  * \list
00284  * - <b>part</b> is a region of a file of (up to) 9500kb in length, for which
00285  * there is a corresponding MD4 PartHash.
00286  * - <b>chunk</b> is a region of a file of (up to) 180kb in length, which can
00287  * be requested from a remote client.
00288  * - <b>block</b> is a region of a <i>chunk</i> which is sent as single packet
00289  * during data transfer between clients. Chunks are split into block packets
00290  * for transmitting.
00291  *
00292  * \sa \link ed2k-tag
00293  * eDonkey2000 Tag System Overview
00294  * \endlink
00295  *
00296  * \section header 2. Header specification
00297  * \code
00298  * +--------+--------+--------+--------+--------+--------+--------+--------+----
00299  * |protocol|            packet length          |  packet data (length bytes)
00300  * +--------+--------+--------+--------+--------+--------+--------+--------+----
00301  * \endcode
00302  * Each eDonkey2000 packet begins with protocol opcode, followed by 32-bit
00303  * unsigned integer indicating the packet length. Currently, three protocol
00304  * opcodes are in use:
00305  * \dontinclude opcodes.h
00306  * \skip PR_ED2K
00307  * \until PR_ZLIB
00308  * Packed data always begins with 8-bit opcode, which indicates the packet
00309  * content. When sending packets using PR_ZLIB protocol, the packet data
00310  * (excluding the opcode) is compressed.
00311  *
00312  * \section clieserv 3. Client-Server communication
00313  * \subsection logsrv 3.1 Logging into a server
00314  *
00315  * In order to connect to an eDonkey2000 Server, Client sends OP_LOGINREQUEST
00316  * to server.
00317  * \skipline OP_LOGINREQUEST
00318  * The packet may contain the following tags:
00319  * \until CT_FLAGS
00320  * Flags is a bitfield containing the following information:
00321  * \until FL_UNICODE
00322  *
00323  * On a well-formed OP_LOGINREQUEST packet, the server first attempts to connect
00324  * to the sending client to its reported listening port as a normal client. If
00325  * the connection attempt succeeds, and the server receives a wellformed
00326  * OP_HELLOANSWER packet from the socket, the server assigns the connecting
00327  * client High ID. If the connection fails for whatever reason, the client is
00328  * assigned Low ID.
00329  * \sa \ref lowid
00330  *
00331  * The following packets are sent by the server to inform the client that the
00332  * connection has been established, as well as to provide up2date information
00333  * about the server:
00334  * \skip OP_SERVERMESSAGE
00335  * \until OP_IDCHANGE
00336  * \note Lugdunum 16.44+ servers send additional u32 in ID_CHANGE packet
00337  *       containing bitfield of supported features. Those include:
00338  * \dontinclude opcodes.h
00339  * \skipline FL_ZLIB
00340  * \skipline FL_NEWTAGS
00341  * \skipline FL_UNICODE
00342  *
00343  * \subsection updateinfo 3.2 Updating server list and information (optional)
00344  * After establishing connection with the server, the client may request
00345  * additional information from the server, as well as known servers list.
00346  * \skipline OP_GETSERVERLIST
00347  * The server answers with the following packets:
00348  * \skipline OP_SERVERLIST
00349  * \skipline OP_SERVERIDENT
00350  * The latter contains the following tags:
00351  * \skipline CT_SERVERNAME
00352  * \skipline CT_SERVERDESC
00353  *
00354  * \subsection publishshrd 3.2 Publishing Shared Files
00355  * After establishing connection with the server, the client must publish it's
00356  * shared files using OP_OFFERFILES packet. The packet should be compressed
00357  * if the server supports it to save bandwidth.
00358  * \skip Publishing shared files
00359  * \skip enum
00360  * \skipline //!
00361  * \until OP_OFFERFILES
00362  * The packet may contain the following tags:
00363  * \until CT_FILETYPE
00364  * \note File type is sent in ed2k network as string. The following strings are
00365  *       recognized:
00366  * \skip FT_ED2K_AUDIO
00367  * \until FT_ED2K_PROGRAM
00368  *
00369  * This packet should be sent on the following occasions:
00370  * - With full shared files list when connecting to server
00371  * - With single file whenever new shared file is added
00372  * - As empty packet, as server keep-alive packet at regular intervals
00373  * Additionally, it is possible to indicate whether the file being shared is
00374  * partial or complete using two special ip/port values:
00375  * \dontinclude opcodes.h
00376  * \skip FL_COMPLETE_ID
00377  * \until FL_PARTIAL_PORT
00378  * \note Only use these ID's on newer eservers. eMule uses zlib-support to
00379  *       detect whether the server supports these id's too.
00380  *
00381  * \subsection search 3.3 Performing a search
00382  *
00383  * Searching in eDonkey2000 network is server-based. Client sends SEARCHR
00384  * packet to server, which in turn returns one (or more) SEARCHRESULT packets.
00385  * This is done over TCP, and with currently connected server only. However,
00386  * optionally, the client may also send the same search request packet over
00387  * UDP sockets to all known servers using GLOBSEARCH opcode, which in turn
00388  * reply (over UDP) with GLOBSEARCHRES packets. <searchexpr> format specifi-
00389  * cation is beyond the scope of this document. Refer to ED2KPacket::Search
00390  * implementation for more information (packets.cpp)
00391  * \skipline OP_SEARCH
00392  * \until OP_SEARCHRESULT
00393  * SearchResult may contain the following tags:
00394  * \dontinclude opcodes.h
00395  * \skip CT_FILENAME
00396  * \until CT_FILETYPE
00397  * \skipline CT_SOURCES
00398  * \skipline CT_COMPLSRC
00399  *
00400  * \section clicli 4. Client <-> Client communication
00401  * \subsection hello 4.1 get-to-know-you chit-chat
00402  * In order to initialize a connection to a remote client, first the client
00403  * sends Hello packet.
00404  * \skipline OP_HELLO
00405  * Hello packet may contain the following tags:
00406  * \dontinclude opcodes.h
00407  * \skipline CT_NICK
00408  * \skipline CT_PORT
00409  * \skipline CT_MULEVERSION
00410  * \skipline CT_MODSTR
00411  * \until CT_MISCFEATURES
00412  * The correct answer to OP_HELLO is OP_HELLOANSWER. The HelloAnswer packet
00413  * format is identical to OP_HELLO, except that HelloAnswer also includes
00414  * 8-bit hash length before hash. The value of the field must be 0x0f.
00415  *
00416  * CT_MULEVERSION contains a 32-bit value with the following bits (and meanings)
00417  * \code
00418  * 1       2       3       4       5 [bytes]
00419  * 11111111222222233333334445555555  [bits]
00420  * 00000000000000001010101100000000  eMule 42g version info
00421  *     |      |      |    |    +---- Build version        (unused by eMule)
00422  *     |      |      |    +--------- Update version 6     (a = 0, g = 6)
00423  *     |      |      +-------------- Minor version 42
00424  *     |      +--------------------- Major version        (unused by eMule)
00425  *     +---------------------------- Compatible Client ID (CS_EMULE = 0x00)
00426  * \endcode
00427  *
00428  * If both of the clients are eMule-compatible, they also exchange MuleInfo
00429  * packets.
00430  * \skipline OP_MULEINFO
00431  * \skipline OP_MULEINFOANSWER
00432  * \note Both of these packets are sent using PR_EMULE.
00433  *
00434  * Tags contained in MuleInfo packets:
00435  * \dontinclude opcodes.h
00436  * \skip CT_COMPRESSION
00437  * \until CT_L2HAC
00438  * Feature set bitfield is 32-bit value with following bits and meanings:
00439  * \code
00440  * 12345678123456781234567812345678
00441  * 00000100000100110011001000011110 eMule 43b
00442  * 00110100000100110011001000011110 eMule 44b
00443  * 11123333444455556666777788889abc
00444  *  | |  |   |  |   |    |  |  |||+-- Preview
00445  *  | |  |   |  |   |    |  |  ||+--- Multipacket
00446  *  | |  |   |  |   |    |  |  |+---- No `view shared files' supported
00447  *  | |  |   |  |   |    |  |  +----- Peercache
00448  *  | |  |   |  |   |    |  +-------- Comments
00449  *  | |  |   |  |   |    +----------- Extended requests
00450  *  | |  |   |  |   +---------------- Source exchange
00451  *  | |  |   |  +-------------------- Secure ident
00452  *  | |  |   +----------------------- Data compression version
00453  *  | |  +--------------------------- UDP version
00454  *  | +------------------------------ Unicode
00455  *  +-------------------------------- AICH version (0 - not supported)
00456  * \endcode
00457  *
00458  * \subsection reqfile 4.2 Reqesting a file
00459  *
00460  * After completing the handshaking described in section 4.1, the client may
00461  * now request a file. This is done using ReqFile packet.
00462  * \skipline OP_REQFILE
00463  * \note eMule ExtReqV1 adds <u16>count<count>bitarray partmap
00464  * \note eMule ExtReqV2 adds <u16>completesources
00465  *
00466  * ReqFile is replied by OP_FILENAME and OP_FILEDESC
00467  * \skipline OP_FILENAME
00468  * \skipline OP_FILEDESC
00469  * After receiving the above packets, the downloading client sends SETREQFILEID
00470  * to bind the reqested file to the hash. This means the client is now bound to
00471  * the requested hash, until it receives it.
00472  *
00473  * FileDesc packet is sent using PR_EMULE, and does NOT contain the file hash
00474  * the description belongs to, however, since it is always sent along with
00475  * OP_FILENAME, in response to OP_REQFILE packet, client can thus assume the
00476  * FileDesc packet belongs to the most recently requested file.
00477  *
00478  * \note Actually, eMule extended protocol allows changing the reqested file
00479  *       while waiting in the queue by resending OP_SETREQFILEID at any time.
00480  *
00481  * \skipline OP_SETREQFILEID
00482  * The expected response to this packet is OP_FILESTATUS
00483  * \skipline OP_REQFILE_STATUS
00484  * If at any point during the above packets the uploading client realizes it
00485  * doesn't share the file requested, it may send OP_REQFILE_NOFILE. File status
00486  * packet contains a part map of the available parts. This is defined as a
00487  * bitfield, one bit per each ED2K part (defined by ED2K_PARTSIZE). Extra bits
00488  * needed to fill up the byte are padded with zeros. The count prior to the
00489  * bitset indicates the number of total parts, and thus also the number of total
00490  * bits in the bitset (note: NOT the number of bytes following!). Also note that
00491  * sending partmap is completely optional, and should only be sent if the file
00492  * is indeed partial - if the sender has the entire file, the partmap shall be
00493  * omitted.
00494  * \skipline OP_REQFILE_NOFILE
00495  * If the downloading client needs a hashset of the file, it may ask the
00496  * uploader for it using OP_REQHASHSET. The expected response is OP_HASHSET.
00497  * \skipline OP_REQHASHSET
00498  * \skipline OP_HASHSET
00499  * After that, the requesting client sends OP_STARTUPLOADREQ, which must be
00500  * replied either by OP_ACCEPTUPLOADREQ (if we can start uploading right away),
00501  * or OP_QUEUERANKING, in case the client has been inserted into our upload
00502  * queue.
00503  * \skipline OP_STARTUPLOADREQ
00504  * \skipline OP_ACCEPTUPLOADREQ
00505  * \skipline OP_QUEUERANKING
00506  * There is another queue ranking packet used by eMule - denoted by opcode
00507  * OP_MULEQUEUERANK.
00508  * \skipline OP_MULEQUEUERANK
00509  * This packet contains 16-bit value as queue rank, and 10 empty bytes, such as
00510  * the full packet size must be 12 bytes. This size requirement is enforced
00511  * by eMule packet parser, and the sender will be disconnected if those extra
00512  * bytes are not sent. Why are there those 10 extra empty bytes, and why is it
00513  * enforced so strongly remains unclear. This packet is also sent using PR_EMULE
00514  * protocol opcode. Note that if you'r thinking to skip over this packet and
00515  * not use it, you'r so out of luck, since eMule considers clients who send
00516  * OP_QUEUERANKING simply QueueFull (altough it seems to parse the packet). So
00517  * if you want eMule compatibility, you need to use this half-empty packet.
00518  *
00519  * \subsection upload 4.3 Uploading file data
00520  *
00521  * After receiving OP_ACCEPTUPLOADREQ, the remote client will proceed to request
00522  * chunks from us. In eDonkey2000 network, a chunk size is 180k (notice the
00523  * difference from partsize). The chunks are requested using OP_REQCHUNKS
00524  * packet:
00525  * \skipline OP_REQCHUNKS
00526  * The packet contains three begin offsets and three end offsets of the
00527  * requested chunks. ED2K data ranges logic defines that the end offset is
00528  * exclusive, thus range (0, 0) is considered as <i>invalidrange</i>. If the
00529  * client wishes less than three chunks, it may set the remaining ranges to
00530  * (0, 0) to indicate that.
00531  * \note This is slightly different from HydraNode Range API, where end offset
00532  * is considered inclusive.
00533  *
00534  * \note Implementors should be warned about different behaviours of different
00535  * clients when it comes to chunk requests. Namely, eMule (and compatible)
00536  * clients use "rotational chunkrequest" scheme, where each REQCHUNKS packet
00537  * contains one new chunk and two older chunks; for example:
00538  * \code
00539  * Packet1:   0..101, 101..201, 201..301 // initial req
00540  * Packet2: 101..201, 201..301, 301..401 // sent after completing   0..101
00541  * Packet3: 201..301, 301..401, 401..501 // sent after completing 101..201
00542  * \endcode
00543  * MLDonkeys, and some other clients, however, only send single requests:
00544  * \code
00545  * Packet1:   0..101, 101..201, 201..301 // initial req
00546  * Packet2: 301..401,   0..0,     0..0   // after completing   0..101
00547  * Packet3: 401..501,   0..0,     0..0   // after completing 101..201
00548  * \endcode
00549  * This can lead to duplicate data being sent by mldonkeys, if a rotational
00550  * chunkrequest scheme is used when communicating with them. For that reason,
00551  * HydraNode uses non-rotational request scheme with all clients, since all
00552  * clients handle it properly.
00553  *
00554  * After receiving OP_REQCHUNKS, the uploading clients starts sending data. The
00555  * requested chunks are split into (up to) 10kb blocks, each transmitted as
00556  * a separate packet, using OP_SENDINGCHUNK opcode. Optionally, clients
00557  * supporting eMule extended protocol may use OP_PACKEDCHUNK packet (which is
00558  * sent using PR_EMULE). In compressed packet, the data part of the packet is
00559  * compressed using zlib (but not the packet header - this is different from
00560  * OfferFiles packet, where everything after the opcode is compressed). Also, in
00561  * case of a compressed packet, the end offset bytes in the packet header
00562  * indicate the length of the compressed data, not the end offset of the
00563  * uncompressed data. Note that compression is not required - if data
00564  * compression results in larger amount of data, data should be sent
00565  * uncompressed instead, using OP_SENDINGCHUNK packet.
00566  *
00567  * \skipline OP_SENDINGCHUNK
00568  * \skipline OP_PACKEDCHUNK
00569  *
00570  * When the receiver decides it does not want any more data from us, it will
00571  * send OP_CANCELTRANSFER packet (empty payload) to the uploader.
00572  * \skipline OP_CANCELTRANSFER
00573  *
00574  * In case of compressed data transfer, the entire requested chunk is first
00575  * compressed, and then transmitted in 10kb chunks over time.
00576  *
00577  * \section lowid 5 LowID Clients
00578  *
00579  * LowID client is defined in ed2k network as a client who cannot receive
00580  * external connection. The client can only make external connections itself.
00581  * The only way to connect to a client is through a server callback, since the
00582  * client is connected to a server. It is only possible to contact LowID clients
00583  * that are on same server as the connecter is. LowID client's are identifier
00584  * in the network using client ID less than 0x00ffffff. This is also the reason
00585  * why everywhere where there should be client IP we say it is ID. For clients
00586  * with ID > 0x00ffffff, the ID indicates the IP of the remote client (in
00587  * network byte order), for lower ID's, it indicates the client callback ID,
00588  * as assigned by the server.
00589  *
00590  * \subsection lowidcb 5.1 Connecting to LowID clients
00591  *
00592  * Connecting to LowID client is done by sending OP_REQCALLBACK to currently
00593  * connected server, including the ID of the remote client we wish to connect.
00594  * \skipline OP_REQCALLBACK
00595  * If the client with the specified ID is connected to the server, the server
00596  * sends OP_CBREQUESTED packet to the client, after which the client will
00597  * attempt to contact the requester.
00598  * \skipline OP_CBREQUESTED
00599  * If the client in question is not connected to this server, the server will
00600  * respond with OP_CALLBACKFAIL.
00601  * \skipline OP_CALLBACKFAIL
00602  *
00603  * \section srcexch 6 Source Exchange
00604  *
00605  * Extended protocol feature added by eMule, Source Exchange allows clients to
00606  * share their known sources for files.
00607  * \skipline OP_REQSOURCES
00608  * \skipline OP_ANSWERSOURCES
00609  * \note SrcExchv2 adds 16-byte user-hash to each source.
00610  * \note SrcExchv3 sends ID's in byteswapped format (also called "Hybrid"
00611  * format in eMule code) so HighID clients with *.*.*.0 won't be falsely given
00612  * LowId.
00613  *
00614  * Normally, this packet is sent using PR_EMULE, but if possible, it should be
00615  * compressed and sent using PR_ZLIB.
00616  *
00617  * \note ED2K netiquette specifies that you should not request mosources from
00618  * clients at intervals exceeding these:
00619  * - No more than once per 40 minutes per client in case of rare files
00620  *  (less than 10 sources)
00621  * - No more than once per 2 hours per client in case of common files
00622  * .
00623  *
00624  * \section secident 7 Secure Identification
00625  * Secure Identification provides means of determining the client's identity
00626  * in a secure manner, and avoid the former problems regarding hash/credit
00627  * stealers. In the protocol, three packets implement SecIdent:
00628  * \skipline OP_SECIDENTSTATE
00629  * Request signature and/or publickey from remote client
00630  * \skipline OP_PUBLICKEY
00631  * Includes the senders public key
00632  * \skipline OP_SIGNATURE
00633  * Includes the senders signature
00634  *
00635  * The signature message contents are as follows:
00636  * \code
00637  * <*>pubkey<u32>challenge
00638  * \endcode
00639  * \note SecIdentv2 adds u32 ip and u8 iptype
00640  * The pubkey is the signature requesters public key. The message is signed
00641  * with the senders own private key. The receiver can then verify the message
00642  * with the senders public key.
00643  *
00644  * Sample implementation of this scheme, using CryptoPP library,
00645  * CreditsDb::createCryptKey
00646  * CreditsDb::loadCryptKey
00647  * CreditsDb::createSignature
00648  * CreditsDb::verifySignature
00649  *
00650  * \section misc 8 Miscellaneous TCP packets
00651  * \dontinclude opcodes.h
00652  * \skipline OP_MESSAGE
00653  * Message packets can be used to perform simple chatting between clients.
00654  * \skipline OP_PORTTEST
00655  * Not actually part of ed2k protocol, OP_PORTTEST can be used (by a website,
00656  * for example) to verify correct firewall configuration. Note that OP_PORTTEST
00657  * may be sent both via TCP and UDP.
00658  * \skipline OP_CHANGEID
00659  * Sent when client changes it's ip address, or in case of LowID clients,
00660  * changes it's ID (sent by server). Mules seem to only handle this packet, but
00661  * not send it themselves.
00662  * \note The actual format of this packet has not yet been fully verified.
00663  *
00664  * \section udp 9 UDP packets
00665  *
00666  * The format of UDP packets header differs slightly from TCP packet headers,
00667  * namely, the size field is omitted, and opcode follows the protocol code.
00668  *
00669  * \section udpext 9.1 eMule extended protocol: UDP reasks
00670  * As an eMule extended feature, UDP packets are used to "ping" sources every
00671  * now and then to verify queue status, reask queue rankings and so on. In
00672  * current implementation, eMule (and compatible) clients seem to drop clients
00673  * from their queues if they haven't pinged at least once per hour. The
00674  * following packets are currently in use, and are sent using protocol PR_EMULE:
00675  *
00676  * \skipline OP_REASKFILEPING
00677  * By default, this packet only contains filehash the source was interested in.
00678  * \note UDPv3 adds 2-bytes complete-source-count.
00679  * \note UDPv4 adds availability partmap, as in ReqFile packet.
00680  * \note When UDPv4 is used, the partmap is placed <b>before</b> the complete
00681  *       source count.
00682  *
00683  * \skipline OP_REASKACK
00684  * Expected response to OP_REASKFILEPING, this indicates that the asking client
00685  * is indeed in queue, and contains it's current queue ranking.
00686  * \note UDPv4 adds availability partmap, as in ReqFile packet
00687  *
00688  * \note Similarly to OP_REASKFILEPING packet, when UDPv4 is used, the partmap
00689  *       is placed BEFORE the queue ranking in the packet.
00690  *
00691  * \skipline OP_FILENOTFOUND
00692  * Sent as response to OP_REASKFILEPING, indicates that the remote client is
00693  * not sharing the requested file (anymore at least).
00694  *
00695  * \skipline OP_QUEUEFULL
00696  * Sent as response to OP_REASKFILEPING, indicates that the remote queue is
00697  * full.
00698  *
00699  * \section serverudp 8.1 Global server queries
00700  * In Client <-> Global Server communication, UDP is used for global searches,
00701  * as well as global source queries. The following packets are being used, and
00702  * sent using protocol PR_ED2K:
00703  *
00704  * \skipline OP_GLOBGETSOURCES
00705  * All servers support this packet, but if the ServerUDPFlags includes
00706  * FL_GETSOURCES, the server allows requesting sources for multiple files at
00707  * same time. When sending more than one hash, care must be taken to limit the
00708  * packet size to 512 bytes, anything above that will be ignored by server.
00709  *
00710  * \skipline OP_GLOBGETSOURCES2
00711  * Modified version of the above packet, this also includes file-size in the
00712  * request. This can only be used with servers, which support FL_GETSOURCES2
00713  * flag.
00714  *
00715  * \note You shouldn't query any server twice for sources during 20-minute-
00716  * interval, or you might get banned.
00717  *
00718  * \skipline OP_GLOBFOUNDSOURCES
00719  * The expected response to OP_GLOBGETSOURCES or GLOBGETSOURCES2 packets, this
00720  * packet contains the list of sources the server knows.
00721  *
00722  * \skipline OP_GLOBSTATREQ
00723  * Used for "pinging" global servers, this packet requests the remote server to
00724  * return info about it's current state. Servers always respond to this packet
00725  * (if alive), so this can be used to determine whether the server is alive or
00726  * not. As with GlobGetSources, no server should be queried more often than
00727  * once every 20 minutes.
00728  *
00729  * The first two bytes of the challenge (in network byte order) are always set
00730  * to 0x55aa, followed by random 16bit integer.
00731  *
00732  * \skipline OP_GLOBSTATRES
00733  * The expected response to OP_GLOBSTATREQ, this packet contains bunch of
00734  * information about the server. Only the first three fields (challenge, users,
00735  * files) are always present, the remainder of fields are optional (only
00736  * implemented by newer server versions, and can possibly be omitted even by
00737  * newer servers). The challenge is equal to the challenge sent in
00738  * OP_GLOBSTATREQ packet.
00739  */
00740 
00741 #endif