jMoule : protocol

In order to write jMoule, I add to understand the mlDonkey Core/Gui protocol.
The file "interface_protocol.txt" in mlDonkey's sources gives some information about this protocol but his still incomplete so I wrote this page... I hope you will find it useful :)
Anyway this document is not a reference and many options are not used or not explained... if you want to know everything you should read the "guiEncoding.ml" file in the source distribution.

First you need to connect to the mlDonkey Core (using TCP socket on port 4001).
Then you can start reading and sending binary messages from and to the Core with the following structure :

Size of content	Content
	Function	Parameters
Long (4 bytes)	Int (2 bytes)	(Size of content - 2) bytes

List of types used in this protocol :

• Byte : range 0-255 (1 byte).
• Int : range 0-65535 (2 bytes).
• Long : range 0-2^32-1 (4 bytes).
• String : length of the string (Int) followed by the characters.
• List of <type> : number of elements (Int) followed by the elements.
• IP : Standart IPv4 (4 bytes).
• Boolean : 0 if false or 1 if true (1 byte).

Messages you receive from the Core (this currently only lists the messages I use in jMoule...) :

• CoreProtocol :
  • Function : 0
  • Description : This gives you the version of the protocol used by this Core. You should send the version of the protocol you use (see below). Then both the Core and the Gui should use the lower protocol.
    
  • Parameters : Version (Long)
  
  
• Options_info :
  • Function : 1
  • Description : This gives you the list of options the Core knowns.
  • Parameters : List of options (Int elements) with the following structure :
    • Option name (String)
    • Option value (String)
  
  
• Result_info :
  • Function : 4
  • Description : This gives the informations about one result of a search.
  • Parameters :
    • ID (Long) : ID of the file (you should use this later).
    • Network (Long) : ID of the network where the file has been found.
    • File Names (List of Strings) : The names for this file.
    • Hash Code (16 bytes)
    • File size (Long)
    • File format (String)
    • File type (String)
    • List of tags (Int elements) with the following structure :
      • Tag name (String)
      • Tag type (Byte)
      • Tag value (Long if type is 0 or 1, String if type is 2, Ip if type is 3)
    • Comment (String)
    • Done (Boolean)
  
  
• File_info :
  • Function : 7, 40 or 43 (depending of protocol)
  • Description : This gives the informations about one file being downloaded.
  • Parameters :
    • ID (Long) : ID of the file.
    • Network (Long) : ID of the network where this file is being downloaded.
    • File Names (List of Strings) : The names for this file, first name is the hash code.
    • Hash Code (16 bytes)
    • File size (Long)
    • Downloaded bytes (Long)
    • Number of locations (Long)
    • Number of clients (Long)
    • File state (Byte) where value can be :
      • 0 = Downloading
      • 1 = Paused
      • 2 = Downloaded
      • 3 = Shared
      • 4 = Cancelled
      • 5 = New
      • 6 = Aborted s
      • 7 = Queued
    • Chunks (String)
    • Availability (String)
    • Rate (String) : Float downloading rate in bytes per second.
    • Chunks age (List of Strings)
    • Age (String)
    • Format (Byte) for this file where value can be :
      • 0 = "Unknown Format".
      • 1 = "Format Type" + String + String
      • 2 = "AVI" + Codec (String) + Xsize (Long) + Ysize (Long) + Frames per second (Long) + Rate (Long)
      • 3 = "MP3" + Title (String) + Artist (String) + Album (String) + Year (String) + Comment (String) + Track (Long) + Genre (Long)
  
  
• Server_state :
  • Function : 13
  • Description : Updates the state for a server.
  • Parameters :
    • ID (Long) : ID of the server
    • Server state (Byte) where value can be :
      • 0 = NotConnected -1
      • 1 = Connecting
      • 2 = Connected_initiating
      • 3 = Connected_downloading
      • 4 = Connected -1
      • 5 = Connected n
      • 6 = NewHost
      • 7 = RemovedHost
      • 8 = BlackListedHost
      • 9 = NotConnected n
  
  
• Console :
  • Function : 19
  • Description : A message from the Core or from a server.
  • Parameters : Message (String)
  
  
• Server_info :
  • Function : 26
  • Description : Informations about a server.
  • Parameters :
    • ID (Long) : ID of the server.
    • Network (Long) : ID of the network this server belongs to.
    • Host type (Byte)
    • Host (IP if type is 0, String if type is 1)
    • Port (Int)
    • Score (Long)
    • List of tags (Int elements) with the following structure :
      • Tag name (String)
      • Tag type (Byte)
      • Tag value (Long if type is 0 or 1, String if type is 2, Ip if type is 3)
    • Number of users (String)
    • Number of files (String)
    • Server state (Byte) where values are the same as "Server_state" function.

Messages you can send to the Core (this currently only lists the messages I use in jMoule...) :

• CoreProtocol :
  • Function : 0
  • Description : The version of the protocol used by the Gui.
  • Parameters : Version (Long)
  
  
• ConnectMore :
  • Function : 1
  • Description : Asks the Core to try connecting more servers.
  • No parameters.
  
  
• CleanOldServers :
  • Function : 2
  • Descriptions : Asks the Core to remove old servers.
  • No parameters.
  
  
• KillServer :
  • Function : 3
  • Descriptions : Asks the Core to kill himself (shutdown).
  • No parameters.
  
  
• ExtendedSearch :
  • Function : 4
  • Descriptions : Asks the Core to extends the last search.
  • No parameters.
  
  
• Password :
  • Function : 5
  • Description : Password if needed to connect to the Core. This should be send just after the CoreProtocol message.
  • Parameters : Password (Long)
  
  
• ConnectServer :
  • Function : 21
  • Description : Try to connect to the given server.
  • Parameters : ID (Long) of the server.
  
  
• DisconnectServer :
  • Function : 22
  • Description : Disconnects from the given server.
  • Parameters : ID (Long) of the server.
  
  
• SwitchDownload :
  • Function : 23
  • Description : Pause or Resume the given download.
  • Parameters :
    • ID (Long) : ID of the file.
    • State (Byte) : 0 to pause, 1 to resume.
  
  
• Search :
  • Function : 42
  • Description : Asks the Core to search for new files.
  • Parameters :
    • Number (Long) : number of the search, you must increment it for every new search.
    • Type (Byte) : set it to "4" for a standart search...
    • ? (String) : setting it to empty String works...
    • Query (String) : search criteria.
    • Max hits (Long) : maximum number of resultats you want.
    • Type (Byte) : set it to "1"...
  
  
• Download :
  • Function : 50
  • Description : Download the given file.
  • Parameters : ID (Long) of the file found in a result.