*Unofficial* eDonkey Protocol Specification v0.6.2

      Copyright (c) 2003-2004 Alexey Klimkin "klimkin at cpan.org"
              http://sourceforge.net/projects/pdonkey/

======================================================================
            

Used the following sources in time order:

    http://hitech.dk/donkeyprotocol.html
    http://www.schrevel.com/edonkey/ (dead since 21.04.2003)
    eMule: http://www.emule-project.net/
    MLDonkey: http://www.nongnu.org/mldonkey/
    http://sourceforge.net/projects/ed2k-gtk-gui/

Thanks for updates to:

    1. Thomas Lussnig (http://cDonkey.suche.org/)
    2. Qi-Hong Chen
    3. St�phane Loeuillet
    3. eKwak Team "unmap at hotmail.com"
       (http://savannah.nongnu.org/projects/ekwak/)
    4. Kornilov Matvei aka ArgentumBrom


Table of Content
======================================================================

1. Network protocol
  1.1. Client <-> Server
  1.2. Client <-> Client
2. Packet format
  2.1. Client <-> Server
  2.2. Client <-> Client
  2.3. UDP
  2.4. GUI <-> CORE
  2.5. eMule extensions
3. Met files format
  3.1. server.met
  3.2. part.met
  3.3. known.met
  3.4. pref.met
  3.5. formats for old versions
4. Basic data format
5. Semantics
  5.1. HighID and LowID
  5.2. UDP port
6. Changes


1. Network protocol
======================================================================

1.1. Client <-> Server
-------------------------
  Login
0x01           ->
0x40                        <-  
0x15            ->
0x38                        <-  
0x14        ->
0x32                        <-  
0x41                        <-  
0x34                        <-  
  Search file
0x16            ->
0x33                        <-  
0x21           ->
  Search user
0x1a            ->
0x43                        <-  
  Get sources
0x19            ->
0x42                        <-  
  Callback
0x1c      ->
0x35                        <-  
0x36                        <-  
  ID change
0x4d                        <-  

1.2. Client <-> Client
-------------------------
  Login
0x01           ->
0x4c                        <-  
  File request
0x58           ->
0x59                        <-  
0x48                        <-  
  File status
0x4f    ->
0x50                        <-  
0x51        ->
0x52                        <-  
  Slot operation
0x54           ->
0x55                        <-  
0x57                        <-  
0x56           ->
  Data operation
0x47          ->
0x46                        <-  
0x49        ->
  Utility
0x4a             ->
0x4b                        <-  
0x4e                ->
0x4e                        <-  


  This is how chat could be (mldonkey)
  
The chat was part of the eDonkey protocol, but not longer 
supported by the official server or client, also eMule do
not support it. The chat currently used is IRC based.

      -------------------------------------------
0x1d         ->
0x39                        <-  
0x1f              ->
0x1e           ->
0x3a                        <-  
0x3b                        <-  
0x3c                        <-  
0x3d                        <-  
      -------------------------------------------
        ::= 0x1d ?
          ::= 0x1e ?
             ::= 0x1f ?
            ::= 0x39 BYTE ( DWORD)*
        ::= 0x3a ?
             ::= 0x3b ?
            ::= 0x3c ?
            ::= 0x3d ?


2. Packet format
======================================================================

Every packet comes in form: Header Data

        ::=  
              ::= 0xe3        // eDonkey
                        ||= 0xc5        // eMule extensions
                        ||= 0xd4        // eMule compessed (data is zlib compressed)
    ::= DWORD

2.1. Client <-> Server
-------------------------
          ::= 0x01 
          ::= 0x05    // wrong packet, too heavy load, wrong client version
       ::= 0x14
           ::= 0x15 
           ::= 0x16  
            ::= 0x18
           ::= 0x19 
           ::= 0x1a 
                     ::= 0x1b ?
     ::= 0x1c 
                     ::= 0x20 ?  // # Exception in Connection::doTask 25  for 16.39
          ::= 0x21
           ::= 0x32 

   ::= 0x33  
         ::= 0x34  
     ::= 0x35 
         ::= 0x36 
        ::= 0x38 
             ::= 0x40 
      ::= 0x41 
         ::= 0x42  
 // ID list actually
   ::= 0x43 

2.2. Client <-> Client
-------------------------
          ::= 0x01 0x10  
          ::= 0x46   DATA
         ::= 0x47  
                                   
                                       
          ::= 0x48 
       ::= 0x49 
            ::= 0x4a
     ::= 0x4b 
          ::= 0x4c  
         ::= 0x4d      // change low id to high
               ::= 0x4e 
   ::= 0x4f 
           ::= 0x50  
       ::= 0x51                 // select file for download by offical core
        ::= 0x52  
                     ::= 0x53 ?
          ::= 0x54     // Request to start upload
            ::= 0x55                // Accept upload request
          ::= 0x56                // Cancel transfer
            ::= 0x57                // Out of parts
          ::= 0x58                 // File name Requrest (select file for download by eMule)
   ::= 0x59      // File name Answer
                     ::= 0x5b 
            ::= 0x5c DWORD          // ??
       ::= 0x5d                // Request shared directories
      ::= 0x5e     // Request shared files from directory
           ::= 0x5f 
          ::= 0x60  
         ::= 0x61

2.3. UDP
-------------------------
 ::= 0x96 DWORD
                            ||= 0x96 BYTE BYTE 0xaa 0x5a        // extension
         ::= 0x97 DWORD      // DWORD is the same value as passed in request
                            ||= 0x97 BYTE BYTE 0xaa 0x5a   
           ::= 0x98 
    ::= 0x99 
           ::= 0x9a 
         ::= 0x9b  

      ::= 0x9c 
 
         ::= 0x9e 
                         ::= 0xa0 ?
           ::= 0xa1 

       ::= 0xa2
           ::= 0xa3        // name description
       ::= 0xa4

2.4. GUI <-> CORE
-------------------------
             ::= 0x64            // user pass
              ::= 0x65
           ::= 0x66 
       ::= 0xaa 
       ::= 0xab 
       ::= 0xac WORD *
      ::= 0xad 
       ::= 0xae  
       ::= 0xaf      
           ::= 0xb4 
     ::= 0xb5 
         ::= 0xb6 
      ::= 0xb7
     ::= 0xb8  
  ::= 0xb9 
         ::= 0xba 
   ::= 0xbb  
      ::= 0xbc   
   ::= 0xbd 
        ::= 0xbe  
     ::= 0xbf 
   ::= 0xc0 DWORD? 
::= 0xc1 DWORD?
      ::= 0xc2 ?
           ::= 0xc3 
::= 0xc4 ?
   ::= 0xc5 
     ::= 0xc6 
           ::= 0xc7 
           ::= 0xc8 
  // 0 for any server
        ::= 0xc9
       ::= 0xca  
::= 0xcb
      ::= 0xcc
       ::= 0xcd  
::= 0xce
          ::= 0xcf 
    ::= 0xd0 
   ::= 0xd1 
   ::= 0xd2 
      ::= 0xd3  
 ::= 0xd4 ?
   ::= 0xd5
   ::= 0xd6
   ::= 0xd7
   ::= 0xd8 ?
   ::= 0xd9
    ::= 0xda
   ::= 0xdb
    ::= 0xdc
     ::= 0xdd 

        ::= 0xde 

    ::= 0xdf 
 
  ::= 0xe0
       ::= 0xe1
     ::= 0xe2 
   ::= 0xe3  BYTE   // BYTE reserved for future use
   ::= 0xe4

         ::= WORD        //                  core version
                            FLOAT       // userMaxDownF:    max download speed
                            FLOAT       // userMaxUpF:      max upload speed
                            WORD        //                  incoming port
                            WORD        // maxCon:          max connections
                                //                  nickname
                                // temp:            temp dir
                                // incoming:        incoming dir
                            BYTE        // auto:            auto reconnect
                            BYTE        // servRemove:      remove dead servers
                            BYTE        // pmAllow:         allow private messages
                            BYTE        // saveCor:         save corrupted files
                            BYTE        // verifyCancel:    verify cancels
                            WORD        // adminDoorPort:   admin port
                            DWORD       // maxCon:          max connections
                            DWORD       //                  core build date
                            FLOAT       // lineDown?:        line speed
                            DWORD       //                  core PID

  ::= WORD *
       ::=   
                            DWORD   // transferred
                            BYTE    // availability
                            BYTE    // sources
  ::= 0x00    // hashing
                        ||= 0x01    // queued
                        ||= 0x02    // looking
                        ||= 0x03    // downloading
                        ||= 0x04    // paused
                        ||= 0x05    // ids
                        ||= 0x06    // nosrcs
                        ||= 0x07    // done
                        ||= 0x08    // hashing2
                        ||= 0x09    // errloading
                        ||= 0x0a    // completing
                        ||= 0x0b    // complete
                        ||= 0x0c    // corrupted
                        ||= 0x0d    // errhashing
                        ||= 0x0e    // transferring
    ::= WORD *
         ::=  

         ::= 0x00    // low
                        ||= 0x01    // normal
                        ||= 0x02    // high
       ::= 0x00    // normal
                        ||= 0x01    // high
                        ||= 0x02    // low

         ::= WORD *
              ::= DWORD DWORD     // gap start, gap end, status


             ::= FLOAT   // MB, free space in 'temp' directory
         ::= FLOAT   // MB, free space in 'incoming' directory
           ::= FLOAT   // MB, space needed for downloads
          ::= WORD    // number of currently used connections
                ::= WORD    // number of peoples on queue
                 ::= FLOAT   // KB/sec
               ::= WORD

2.5. eMule extensions
-------------------------
           ::= 0x01  
    ::= 0x02  
/* zlib compressed data can come in more than one packets without changing start and len */
 ::= 0x40    ZDATA
   ::= 0x60 
       ::= 0x61    // File comment (128 bytes max)
 ::= 0x81 
  ::= 0x82  

UDP
-----------
::= 0x90 
     ::= 0x91 
  ::= 0x92
      ::= 0x93

         ::= WORD
    ::= DWORD
     ::= DWORD
    ::= WORD 
*
            ::= WORD


3. Met files format
======================================================================

3.1. server.met
-------------------------
        ::= 0x0e  
  ::= DWORD *
       ::=   
              ::= DATA

NOTE:  may keep some data as
28 unhandled bytes at the end:
  0x11A0 : 6D 61 64 65 20 62 79 20 6F 20 63 20 62 20 20 4D : made.by.o.c.b..M
  0x11B0 : 20 61 20 75 20 72 20 69 20 63 20 65             : .a.u.r.i.c.e

3.2. part.met
-------------------------
          ::= 0xe1  0x00
      ::= 0x02   
                        [ 0x01  ] [ 0x01  ]
     ::= HASH*   // number of hashes == ceil(size/9728000)
     ::= HASH8*  // number of hashes == ceil(size/486400)

              ::= DWORD

3.3. known.met
-------------------------
         ::= 0x0e 
 ::= DWORD *

3.4. pref.met
-------------------------
          ::= 
 HASH  
      ::= 

3.5. formats for old versions
-------------------------
          ::= 0xe0 
      ::=    

         ::= 0x0e DWORD *


4. Basic data format
======================================================================

      ::= 0x00   
                    ||= 0x01                        // search by name
                    ||= 0x02         // search by meta
                    ||= 0x03 DWORD   // search by limit
          ::= 0x00     // and
                    ||= 0x01     // or
                    ||= 0x02     // and not
            ::= 0x01     // min
                    ||= 0x02     // max

    ::= DWORD *
         ::=    
  ::= DWORD *
       ::=   
  ::= DWORD *
       ::=    

     ::= DWORD *
          ::= 0x00 Undefined
                    ||= 0x01  HASH
                    ||= 0x02  
                    ||= 0x03  DWORD
                    ||= 0x04  FLOAT
                    ||= 0x05  BOOL       // ??
                    ||= 0x06  BOOL Array // ??
                    ||= 0x07  BLOB       // ??
     ::= WORD   // WORD is the number of bytes in 
                    ||= 
       ::= 0x01        // name
                    ||= 0x02        // size: size of file
                    ||= 0x03        // type: Audio, Video, Image, Pro, Doc, Col
                    ||= 0x04        // format: file extension
                    ||= 0x05        // Collection (depricated)  // ??
                    ||= 0x06        // Part Path                // ??
                    ||= 0x07        // Part Hash                // ??
                    ||= 0x08        // copied
                    ||= 0x09 DATA   // gap start: DATA keeps number of gap as string
                    ||= 0x0a DATA   // gap end: DATA keeps number of gap as string
                    ||= 0x0b        // description
                    ||= 0x0c        // ping
                    ||= 0x0d        // fail
                    ||= 0x0e        // preference
                    ||= 0x0f        // port
                    ||= 0x10        // ip
                    ||= 0x11        // version
                    ||= 0x12        // tempfile
                    ||= 0x13        // priority
                    ||= 0x14        // status
                    ||= 0x15        // availability
                    ||= 0x16        // QTime                    // ??
                    ||= 0x17        // Parts                    // ??
                    ||= 

 ::= 0x20        // Compression
                    ||= 0x21        // UDP client port
                    ||= 0x22        // UDP version
                    ||= 0x23        // Source exchange
                    ||= 0x24        // Comments
                    ||= 0x25        // Extended request
                    ||= 0x26        // Compatible client

      ::= BYTE 
*
    ::= 

    ::= 

           ::=  

/* Warning there are broken clients that send the list 2 Times where WORD has the doubled len */
/* Part status are stored as follow:
bytes [            0            ] [            1            ] [            2            ] ...
bits  [ 7  6  5  4  3  2  1  0  ] [ 7  6  5  4  3  2  1  0  ] [ 7  6  5  4  3  2  1  0  ] ...
parts [ 7  6  5  4  3  2  1  0  ] [ 15 14 13 12 11 10 9  8  ] [ 23 22 21 20 19 18 17 16 ] ... 
*/
  ::= WORD BYTE*  // number of bytes is WORD/8, 1 bit for each part

/* Warning there are broken clients that send the list 2 Times where WORD has the doubled len */
    ::= WORD HASH*

        ::=       // Len = End - Start (mean End is not included)
      ::= DWORD
        ::= DWORD

    ::= 
         ::= 
         ::= 
       ::= 
         ::= DWORD   // client IP for high id, or number
            ::= DWORD
         ::= DWORD
            ::= DWORD
         ::= HASH    // MD4 of file for files of unknown type
       ::= HASH    ??
       ::= HASH    ??
                ::= DWORD
              ::= WORD

              ::= 0x00
                    ||= 0x01

       ::= DWORD *
            ::=  DATA
     ::= WORD

BYTE    1 byte integer
WORD    2 bytes integer
DWORD   4 bytes integer
FLOAT   4 bytes single float
HASH    16 bytes MD4 digest
HASH8   8 first bytes of HASH
DATA    Data of custom length
ZDATA   zlib-compressed DATA
BOOL    ??
BLOB    ??


5. Semantics
======================================================================

5.1. HighID and LowID
-------------------------
The  match the client IP address in case of high ID, so if the ID
value is stored in hexadecimal as 0xAABBCCDD, the IP is DD.CC.BB.AA.
The  is a low ID when it is below 16777216, so the last low ID is 
0x00FFFFFF, every IP that end with a 0 is considered as a low ID.

5.2. UDP port
-------------------------
Number of UDP port on server is equal to number of TCP listen port + 4.


6. Changes
======================================================================

0.6.2 Mon Apr 19 17:39:12 MSD 2004
    - file details updated (Kornilov Matvei)
    - added section for old protocol versions
    - added packets 0x60, 0x5c (eMule)
    - added section Semantics for all info about protocol semantic
    - updated comment for part status

0.6.1 Wed Apr 23 17:25:43 MSD 2003
    - updated html "makeup"
    - removed value type comments from special tag name, because
      value type is stored in meta tag
    - added HighID and LowID section (eKwak Team)
    - added list of contributors
    - added shared dirs/files requests (0x5d-0x61) (eMule)
    - fixed  (eKwak Team)
    - fixed  for 0x2 and 0x3 (eKwak Team)
    - added extension for  (St�phane Loeuillet)
    - added part.met byte 0xe1  (??)
    - added eMule packets: 0x90, 0x91, 0x92, 0x93 (??)
    - fixed  for 0x1 and 0x2

0.6   Mon Jan 20 14:03:12 MSK 2003
    - added format of whole packet (header, protocol, etc.).
    - fixed some mistypos.

      Mon Jan 20 12:42:51 MSK 2003 (Qi-Hong Chen)
    - fixed mistypos for .
    - changed to  in 3.2 to avoid names clash with packet 
      .
    - fixed "Meta list" entries to .
    - added format for .

      Sun Dez 15 11:44:00 GMT+1 2002 (Thomas Lussnig)
    - eMule Packets.
    - Metta tag and Meta Special tag.
    - some anotations.

0.5   Fri Oct 18 12:28:37 MSD 2002
    - packet names for 0x54-0x57 changed to "Slot ...".
    - added core<->gui protocol.
    - the document reorganized.

0.4   Fri Oct 11 11:53:32 MSD 2002
    - is chat actually function in eDonkey network? at least not for
      server v16.39 under linux.
    - rewritten udp section.
    - added packet 0x9e - UDP Callback fail.
    - added packet 0x18 - server know the packet and drops connection.
    - added packet 0x05 - this packet server sends to client, if server
      receive bad packet from client. Server sends 0x05 and closes connection.

0.3   Tue Oct  8 17:50:28 MSD 2002
    - added format for *.met files.
0.2
    - merged information from mldonkey.
0.1
    - started document from some public info and dumped packets.