*Unofficial* eDonkey Protocol Specification v0.6.1

        Copyright (c) 2003 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/)


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
4. Basic data format
5. HighID and LowID
6. Changes


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

1.1. Client <-> Server
-------------------------
  Login
0x01         <Hello server>  ->
0x40                        <-  <ID change>
0x15          <Offer files>  ->
0x38                        <-  <Server message>
0x14      <Get server list>  ->
0x32                        <-  <Server list>
0x41                        <-  <Server info data>
0x34                        <-  <Server status>
  Search file
0x16          <Search file>  ->
0x33                        <-  <Search file results>
0x21         <More results>  ->
  Search user
0x1a          <Search user>  ->
0x43                        <-  <Search user results>
  Get sources
0x19          <Get sources>  ->
0x42                        <-  <Found sources>
  Callback
0x1c     <Client cb request> ->
0x35                        <-  <Server cb request>
0x36                        <-  <Callback fail>
  ID change
0x4d                        <-  <New client ID>

1.2. Client <-> Client
-------------------------
  Login
0x01         <Hello client>  ->
0x4c                        <-  <Hello answer>
  File request
0x58         <File request>  ->
0x59                        <-  <File request answer>
0x48                        <-  <No such file>
  File status
0x4f  <File status request>  ->
0x50                        <-  <File status>
0x51      <Hashset request>  ->
0x52                        <-  <Hashset answer>
  Slot operation
0x54         <Slot request>  ->
0x55                        <-  <Slot given>
0x57                        <-  <Slot taken>
0x56         <Slot release>  ->
  Data operation
0x47        <Request parts>  ->
0x46                        <-  <Sending part>
0x49      <End of download>  ->
  Utility
0x4a           <View files>  ->
0x4b                        <-  <View files answer>
0x4e              <Message>  ->
0x4e                        <-  <Message>


  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       <Get chat rooms>  ->
0x39                        <-  <Chat rooms>
0x1f            <Join room>  ->
0x1e         <Chat message>  ->
0x3a                        <-  <Chat broadcast>
0x3b                        <-  <Chat join>
0x3c                        <-  <Chat leave>
0x3d                        <-  <Chat users>
      -------------------------------------------
<Get chat rooms>        ::= 0x1d ?
<Chat message>          ::= 0x1e ?
<Join room>             ::= 0x1f ?
<Chat rooms>            ::= 0x39 BYTE (<String> DWORD)*
<Chat broadcast>        ::= 0x3a ?
<Chat join>             ::= 0x3b ?
<Chat leave>            ::= 0x3c ?
<Chat users>            ::= 0x3d ?


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

Every packet comes in form: Header Data

<eDonkey header>        ::= <Protocol> <Packet data length>
<Protocol>              ::= 0xe3        // eDonkey
                        ||= 0xc5        // eMule extensions
                        ||= 0xd4        // eMule compessed (data is zlib compressed)
<Packet data length>    ::= DWORD

2.1. Client <-> Server
-------------------------
<Hello server>          ::= 0x01 <Client info>
<Bad protocol>          ::= 0x05    // wrong packet, too heavy load, wrong client version
<Get server list>       ::= 0x14
<Offer files>           ::= 0x15 <File info list>
<Search file>           ::= 0x16 <Search query> 
<Disconnect>            ::= 0x18
<Get sources>           ::= 0x19 <File hash>
<Search user>           ::= 0x1a <Search query>
<?>                     ::= 0x1b ?
<Client cb request>     ::= 0x1c <Client ID>
<?>                     ::= 0x20 ?  // # Exception in Connection::doTask 25  for 16.39
<More results>          ::= 0x21
<Server list>           ::= 0x32 <Address list>
<Search file results>   ::= 0x33 <File info list> <More>
<Server status>         ::= 0x34 <Nusers> <Nfiles>
<Server cb request>     ::= 0x35 <Client address>
<Callback fail>         ::= 0x36 <Client ID>
<Server message>        ::= 0x38 <String>
<ID change>             ::= 0x40 <Client ID>
<Server info data>      ::= 0x41 <Server info>
<Found sources>         ::= 0x42 <File hash> <Address list> // ID list actually
<Search user results>   ::= 0x43 <Client info list>

2.2. Client <-> Client
-------------------------
<Hello client>          ::= 0x01 0x10 <Client info> <Server address>
<Sending part>          ::= 0x46 <File hash> <Data range> DATA
<Request parts>         ::= 0x47 <File hash> 
                                 <Start offset> <Start offset> <Start offset>
                                 <End offset>   <End offset>   <End offset>
<No such file>          ::= 0x48 <File hash>
<End of download>       ::= 0x49 <File hash>
<View files>            ::= 0x4a
<View files answer>     ::= 0x4b <File info list>
<Hello answer>          ::= 0x4c <Client info> <Server address>
<New client ID>         ::= 0x4d <Client ID> <Client ID>    // change low id to high
<Message>               ::= 0x4e <String>
<File status request>   ::= 0x4f <File hash>
<File status>           ::= 0x50 <File hash> <Part status list>
<Hashset request>       ::= 0x51 <File hash>                // select file for download by offical core
<Hashset answer>        ::= 0x52 <File hash> <Part hash list>
<?>                     ::= 0x53 ?
<Slot request>          ::= 0x54 <File hash>    // Request to start upload
<Slot given>            ::= 0x55                // Accept upload request
<Slot release>          ::= 0x56                // Cancel transfer
<Slot taken>            ::= 0x57                // Out of parts
<File request>          ::= 0x58 <File hash>                // File name Requrest (select file for download by eMule)
<File request answer>   ::= 0x59 <File hash> <File name>    // File name Answer
<?>                     ::= 0x5b <File hash>
<Get shared dirs>       ::= 0x5d                // Request shared directories
<Get shared files>      ::= 0x5e <Directory>    // Request shared files from directory
<Shared dirs>           ::= 0x5f <Directory list>
<Shared files>          ::= 0x60 <Directory> <File info list>
<Shared denied>         ::= 0x61

2.3. UDP
-------------------------
<UDP Server status request> ::= 0x96 DWORD
                            ||= 0x96 BYTE BYTE 0xaa 0x5a        // extension
<UDP Server status>         ::= 0x97 DWORD <Nusers> <Nfiles>    // DWORD is the same value as passed in request
                            ||= 0x97 BYTE BYTE 0xaa 0x5a <Nusers> <Nfiles> <Nusersmax>
<UDP Search file>           ::= 0x98 <Search query>
<UDP Search file result>    ::= 0x99 <File info>
<UDP Get sources>           ::= 0x9a <File hash>
<UDP Found sources>         ::= 0x9b <File hash> <Address list>
<UDP Callback request>      ::= 0x9c <Address> <Client ID>
<UDP Callback fail>         ::= 0x9e <Client ID>
<?>                         ::= 0xa0 ?
<UDP Server list>           ::= 0xa1 <Address list>
<UDP Get server info>       ::= 0xa2
<UDP Server info>           ::= 0xa3 <String> <String>      // name description
<UDP Get server list>       ::= 0xa4

2.4. GUI <-> CORE
-------------------------
<Adm Login>             ::= 0x64 <String> <String>          // user pass
<Adm Stop>              ::= 0x65
<Adm Command>           ::= 0x66 <String>
<Adm Server list>       ::= 0xaa <Server info list>
<Adm Friend list>       ::= 0xab <Client info list>
<Adm Shared dirs>       ::= 0xac WORD <String>*
<Adm Shared files>      ::= 0xad <File info list>
<Adm Gap details>       ::= 0xae <File hash> <Gap info list>
<Adm Core status>       ::= 0xaf <SpaceTemp> <SpaceIncoming> <SpaceNeeded> <Client ID> <Nconnections> <Nqueue>
<Adm Message>           ::= 0xb4 <String>
<Adm Error message>     ::= 0xb5 <String>
<Adm Connected>         ::= 0xb6 <Server name>
<Adm Disconnected>      ::= 0xb7
<Adm Server status>     ::= 0xb8 <Nusers> <Nfiles>
<Adm Extending search>  ::= 0xb9 <Server name>
<Adm File info>         ::= 0xba <File info>
<Adm Search file res>   ::= 0xbb <File info list> <More>
<Adm New download>      ::= 0xbc <File info> <File priority> <File name>
<Adm Remove download>   ::= 0xbd <File hash>
<Adm New upload>        ::= 0xbe <File name> <Client info>
<Adm Remove upload>     ::= 0xbf <Client hash>
<Adm New upload slot>   ::= 0xc0 DWORD? <String>
<Adm Remove upload slot>::= 0xc1 DWORD?
<Adm Friend files>      ::= 0xc2 ?
<Adm Hashing>           ::= 0xc3 <File name>
<Adm Friend list update>::= 0xc4 ?
<Adm Download status>   ::= 0xc5 <Download status list>
<Adm Upload status>     ::= 0xc6 <Upload status list>
<Adm Options>           ::= 0xc7 <Option values>
<Adm Connect>           ::= 0xc8 <Address>  // 0 for any server
<Adm Disconnect>        ::= 0xc9
<Adm Search file>       ::= 0xca <Search query> 
<Adm Extend search file>::= 0xcb
<Adm More results>      ::= 0xcc
<Adm Search user>       ::= 0xcd <Search query> 
<Adm Extend search user>::= 0xce
<Adm Download>          ::= 0xcf <File hash>
<Adm Pause download>    ::= 0xd0 <File hash>
<Adm Resume download>   ::= 0xd1 <File hash>
<Adm Cancel download>   ::= 0xd2 <File hash>
<Adm Set file pri>      ::= 0xd3 <File hash> <File priority>
<Adm View friend files> ::= 0xd4 ?
<Adm Get server list>   ::= 0xd5
<Adm Get client list>   ::= 0xd6
<Adm Get shared dirs>   ::= 0xd7
<Adm Set shared dirs>   ::= 0xd8 ?
<Adm Start dl status>   ::= 0xd9
<Adm Stop dl status>    ::= 0xda
<Adm Start ul status>   ::= 0xdb
<Adm Stop ul status>    ::= 0xdc
<Adm Delete server>     ::= 0xdd <Address>
<Adm Add server>        ::= 0xde <Address>
<Adm Set server pri>    ::= 0xdf <Address> <Server priority>
<Adm Get shared files>  ::= 0xe0
<Adm Get options>       ::= 0xe1
<Adm Download file>     ::= 0xe2 <File info>
<Adm Get gap details>   ::= 0xe3 <File hash> BYTE   // BYTE reserved for future use
<Adm Get core status>   ::= 0xe4

<Option values>         ::= WORD        //                  core version
                            FLOAT       // userMaxDownF:    max download speed
                            FLOAT       // userMaxUpF:      max upload speed
                            WORD        //                  incoming port
                            WORD        // maxCon:          max connections
                            <String>    //                  nickname
                            <String>    // temp:            temp dir
                            <String>    // 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

<Download status list>  ::= WORD <Download status>*
<Download status>       ::= <Slot ID> <Download status byte> <Speed>
                            DWORD   // transferred
                            BYTE    // availability
                            BYTE    // sources
<Download status byte>  ::= 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
<Upload status list>    ::= WORD <Upload status>*
<Upload status>         ::= <Slot ID> <Speed>

<File priority>         ::= 0x00    // low
                        ||= 0x01    // normal
                        ||= 0x02    // high
<Server priority>       ::= 0x00    // normal
                        ||= 0x01    // high
                        ||= 0x02    // low

<Gap info list>         ::= WORD <Gap info>*
<Gap info>              ::= DWORD DWORD <Gap status>    // gap start, gap end, status
<Gap status>

<SpaceTemp>             ::= FLOAT   // MB, free space in 'temp' directory
<SpaceIncoming>         ::= FLOAT   // MB, free space in 'incoming' directory
<SpaceNeeded>           ::= FLOAT   // MB, space needed for downloads
<Nconnections>          ::= WORD    // number of currently used connections
<Nqueue>                ::= WORD    // number of peoples on queue
<Speed>                 ::= FLOAT   // KB/sec
<Slot ID>               ::= WORD

2.5. eMule extensions
-------------------------
<eMule Hello>           ::= 0x01 <eMule Version> <Meta tag list>
<eMule Hello answer>    ::= 0x02 <eMule Version> <Meta tag list>
/* zlib compressed data can come in more than one packets without changing start and len */
<eMule Data compressed> ::= 0x40 <File hash> <eMule Start offset> <eMule Data length> ZDATA
<eMule Queue ranking>   ::= 0x60 <eMule Rank>
<eMule Sources request> ::= 0x81 <File hash>
<eMule Sources answer>  ::= 0x82 <File hash> <eMule Address list>

UDP
-----------
<eMule OP_REASKFILEPING>::= 0x90 <File hash>
<eMule OP_REASKACK>     ::= 0x91 <eMule Rank>
<eMule File not found>  ::= 0x92
<eMule Queue Full>      ::= 0x93

<eMule Version>         ::= WORD
<eMule Start offset>    ::= DWORD
<eMule Data length>     ::= DWORD
<eMule Address list>    ::= WORD <Address>*
<eMule Rank>            ::= WORD


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

3.1. server.met
-------------------------
<server.met>        ::= 0x0e <Server desc list> <Tail>
<Server desc list>  ::= DWORD <Server desc>*
<Server desc>       ::= <IP> <Port> <Meta tag list>
<Tail>              ::= DATA

NOTE: <Tail> 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
-------------------------
<part.met>          ::= 0xe1 <File details>     // 0xe0 in older versions
<File details>      ::= <Date> <File hash> <Part hash list> <Meta tag list>
<Date>              ::= DWORD

3.3. known.met
-------------------------
<known.met>         ::= 0x0e <File details list>
<File details list> ::= DWORD <File details>*

3.4. pref.met
-------------------------
<pref.met>          ::= <Address> HASH <Meta tag list> <Preferencies>
<Preferencies>      ::= <Meta tag list>


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

<Search query>      ::= 0x00 <Operator> <Search query> <Search query>
                    ||= 0x01 <String>                       // search by name
                    ||= 0x02 <String> <Meta tag name>       // search by meta
                    ||= 0x03 DWORD <Minmax> <Meta tag name> // search by limit
<Operator>          ::= 0x00     // and
                    ||= 0x01     // or
                    ||= 0x02     // and not
<Minmax>            ::= 0x01     // min
                    ||= 0x02     // max

<File info list>    ::= DWORD <File info>*
<File info>         ::= <File hash> <Client ID> <Port> <Meta tag list>
<Server info list>  ::= DWORD <Server info>*
<Server info>       ::= <Server hash> <Server address> <Meta tag list>
<Client info list>  ::= DWORD <Client info>*
<Client info>       ::= <Client hash> <Client ID> <Port> <Meta tag list>

<Meta tag list>     ::= DWORD <Meta tag>*
<Meta tag>          ::= 0x00 Undefined
                    ||= 0x01 <Meta tag name> HASH
                    ||= 0x02 <Meta tag name> <String>
                    ||= 0x03 <Meta tag name> DWORD
                    ||= 0x04 <Meta tag name> FLOAT
                    ||= 0x05 <Meta tag name> BOOL       // ??
                    ||= 0x06 <Meta tag name> BOOL Array // ??
                    ||= 0x07 <Meta tag name> BLOB       // ??
<Meta tag name>     ::= WORD <Special tag>  // WORD is the number of bytes in <Special tag>
                    ||= <String>
<Special tag>       ::= 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                    // ??
                    ||= <eMule special tag>

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

<Address list>      ::= BYTE <Address>*
<Server address>    ::= <Address>
<Client address>    ::= <Address>
<Address>           ::= <IP> <Port>

/* Warning there are broken clients that send the list 2 Times where WORD has the doubled len */
/* Part status are stored as follow:
  [ 7 6 5 4 3 2 1 0 ] [ 1 1 1 1 1 1 9 8 ] [ 2 2 2 2 1 1 1 1 ] ... 
                        5 4 3 2 1 0         3 2 1 0 9 8 7 6
*/
<Part status list>  ::= 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 */
<Part hash list>    ::= WORD HASH*

<Data range>        ::= <Start offset> <End offset>     // Len = End - Start (mean End is not included)
<Start offset>      ::= DWORD
<End offset>        ::= DWORD

<Directory list>    ::= <String list>
<Directory>         ::= <String>
<File name>         ::= <String>
<Server name>       ::= <String>
<Client ID>         ::= DWORD   // client IP for high id, or number
<Nusers>            ::= DWORD
<Nusersmax>         ::= DWORD
<Nfiles>            ::= DWORD
<File hash>         ::= HASH    // MD4 of file for files of unknown type
<Client hash>       ::= HASH    ??
<Server hash>       ::= HASH    ??
<IP>                ::= DWORD
<Port>              ::= WORD

<More>              ::= 0x00
                    ||= 0x01

<String list>       ::= DWORD <String>*
<String>            ::= <String length> DATA
<String length>     ::= WORD

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


5. HighID and LowID
======================================================================

The <Client ID> 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 <Client ID> 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.


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

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 <Slot request> (eKwak Team)
    - fixed <Meta tag> for 0x2 and 0x3 (eKwak Team)
    - added extension for <UDP Server status request> (Stéphane Loeuillet)
    - added part.met byte 0xe1  (??)
    - added eMule packets: 0x90, 0x91, 0x92, 0x93 (??)
    - fixed <Search query> 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 <known.met>.
    - changed to <File details> in 3.2 to avoid names clash with packet 
      <File status>.
    - fixed "Meta list" entries to <Meta tag list>.
    - added format for <Date>.

      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.