
			aMule
	     - follow the white rabbit -


		External Connections
		     Protocol

		   version 2.0

Preface
-------

    EC is under heavy construction, however the protocol itself is considered
    stable and you can rely on. The opcodes and tagnames, tag content formats
    and values are still changing, so if you decide to implement an application
    using aMule EC, you'd better include our ECcodes.h for the values, and
    check the documentations often, or even the code itself (ExternalConn.cpp
    is a good start).



Section 1: Protocol definition
------------------------------

Short description:

    EC protocol consist of two layers: a low-level transmission layer, and
    a high level application layer.


Section 1.1: Transmission layer
-------------------------------

    The transmission layer is completely independent of the application layer,
    and holds only transport-related information.

    The transmission layer actually consists of an uint32 number, referenced
    below as flags, which describes flags for the current transmission session
    (send/receive operation).

    This four-byte value is the only one in the whole protocol, that is
    transmitted LSB first, and zero bytes omitted (therefore an empty
    transmission flags value is sent as 0x20, not 0x20 0x0 0x0 0x0).

    Bit description:

	bit 0:	Compression flag. When set, zlib compression is applied to
		the application layer's data.

	bit 1:	Compressed numbers. When set (presumably on small packets
		that doesn't worth compressing by zlib), all the numbers used
		in the protocol are encoded as a wide char converted to utf-8
		to let some zero bytes not to be sent over the network.

	bits 2-3: Reserved for later use.

	bit 4:	Accepts value present. A client sets this flag and sends
		another uint32 value (encoded as above, LSB first, zero
		bytes omitted), which is a fully constructed flags value,
		bits set meaning that the client can accept those extensions.
		No extensions can be used, until the other side sends an
		accept value for them. It is not defined when this value
		should be send, best is on first transfer, but can be sent
		any time later, even changing the previously announced
		flags.

	bit 5:	Always set to 1, to distinguish from older (pre-rc8) clients.

	bit 6:	Always set to 0, to distinguish from older (pre-rc8) clients.

	bits 7,15,23: Extension flag, means that the next byte of the flags is
		present.

	bits 8-14,16-22,24-32: Reserved for later use.


    Transmission layer example:
    	0x30 0x23 <appdata>	- Client uses no extensions on this packet,
		and indicates that it can accept zlib compression and
		compressed numbers.

    Notes:
	Note 1:	On the "accepts" value, the predefined flags must be set to
		their predefined values, because this can be used as a sort
		of a sanity check.

	Note 2:	Bits marked as "reserved" should always be set to 0.



Section 1.2: Application layer
------------------------------

    Data transmission is done in packets. A packet can be considered as a
    special tag - with no data, no tagLen field, and with the tagCount
    field always present. All numbers part of the application layer are
    transmitted in network byte order, i.e. MSB first.
	A packet contains the following:
	[ec_opcode_t] OPCODE
	[uint16] TAGCOUNT
	    <tags>

    In detail: The opcode means what to to or what the data fields contain.
    Its type is set as ec_opcode_t, which currently is an uint8.
    TagCount is the number of first level tags this packet has. Then are the
    tags themselves.

    A tag consist of:
	[ec_tagname_t] TAGNAME
	[ec_taglen_t] TAGLEN
	<[uint16] TAGCOUNT>?
	    <sub-tags>
	    <tag data>

    The ec_tagname_t is defined as an uint16, ec_taglen_t as an uint32 value
    at the moment. TagName tells what it contains (see ECcodes.h for details).
    TagLen contains the whole length of the tag, including the lengths of the
    possible sub-tags, but without the size of the tagName and tagLen fields.
    Actually the lowest bit of the tagname doesn't belong to the tagName
    itself, so it has to be cleared before checking the name.

    Tags may contain sub-tags to store the information, and a tagCount field
    is present only for these tags. The presence of the tagCount field can
    be tested by checking the lowest bit of the tagName field, when it is
    set, tagCount field present.

    When a tag contains sub-tags, the sub-tags are sent before the tag's own
    data. So, tag data length can be calculated by substracting all sub-tags'
    length from the tagLen value, and the remainder is the data length, if
    non-zero.


Section 2: Data Types
---------------------

    Integer types
    -------------

    Integer types (such as uint8, uint16, uint32) are always transmitted in
    network byte order (MSB first).


    Strings
    -------

    Strings are always UTF-8 strings, with the trailing zero byte included.
    All strings coming from the server are untranslated, but their translations
    are included in amule's translation database (amule.mo).


    Boolean
    -------

    This one is tricky. When reading, the tag's presence means true, and
    false when omitted. When writing, the should always be present -
    if not, it's considered 'unchanged' - and should hold an uint8 value.
    This value determines the boolean value in the standard way, i.e.
    zero means false and non-zero means true.

    Boolean values are mostly used in reading/writing preferences.


    MD5 Hashes
    ----------

    They are always MSB first.

