AMule Project FAQ - User contributions [en]

HowTo Compile In Debian-de

2007-11-30T11:32:08Z

87.139.115.64: /* Vorbereitung: wxwidgets compilieren und installieren */

<center>'''Deutsch''' | [[HowTo_Compile_In_Debian|English]] | [[HowTo_Compile_In_Debian-es|Español]]</center>

'''ANMERKUNG:''' Diese Anleitung funktioniert auch für [http://www.ubuntulinux.com Ubuntu Linux].

Siehe auch allgemein [[Compilation Installation-de|Kompilieren/Installieren]]

== Bis du sicher das du kompilieren willst?? ==

Wenn nicht, (was normal ist) eintscheide dich ob du das stabile [[aMule-de|aMule]] oder die Entwicklerversion [[aMule CVS-de|aMule CVS]] willst.

=== [[aMule-de|aMule]] stabile Veröffentlichung ===

'''Diese Pakete sind ausschließlich für Debian 3.1 Sarge!'''

Du kannst du aktuell stable [[aMule-de|aMule]] Version als [http://packages.debian.org deb]s beziehen. Dazu musst du nur folgendes deiner ''/etc/apt/sources.list'' Datei hinzufügen:

deb http://amule-debian.dyndns.org/ debian/

Und anschließend <code>apt-get update && apt-get install amule</code> ausfüren.

Pakete in diesem Repository:
*amule
*amule-daemon
*amule-remote-gui
*amule-gui-utils (alc, wxcas)
*amule-console-utils (amuleweb, alcc, cas)
*amule-utils (metapackage für amule-gui-utils und amule-console-utils)

'''ANMERKUNGEN:'''
* Wenn [[aMule-de|aMule]] mit einer Fehlermeldung über libbfd-2.15.so abbricht bedeutet das, das du NICHT Debian Sarge benutzt. Fange lieber nicht mit irgendwelchen Symlinks oder anderen Tricks an, das kann dir das ganze System versauen.

* http://dude.gemil.de ist veraltet. http://amule-debian.dyndns.org is (zumindest vorerst) leitet zur Zeit nur um, aber das könnte sich in Zukunft ädern (Wenn das Repository wegen Bandbreitenbeschränkungen verschoben werden muss).

=== [[aMule CVS-de|aMule CVS]] Veröffentlichung ===

Du kannst auch die aktuelle [[aMule CVS-de|aMule CVS]] als Paket beziehen. Dazu muss du folgende Zeile deiner ''/etc/apt/sources.list'' Datei hinzufügen:

Für Debian Testing (aka Lenny). Meistes auch fü sid/unstable geeignet:

deb http://www.vollstreckernet.de/debian/ testing amule

Für Debian Stable (aka Etch)

deb http://www.vollstreckernet.de/debian/ stable amule

Wenn du auch eine aktuelle Version von wx (2.8 zur Zeit) benötigst, hänge einfach '''" wx"''' and die oben genannten Zeilen an..
Beachte das ein Leerzeichen zwischen amule und wx stehen muss.
Wenn du nur die wx-Pakete installieren willst, ersetze amule durch wx.

Die Pakete sind mit gpg signiert. Diesen bekommst du durch ausfüren von:
''gpg --keyserver wwwkeys.eu.pgp.net --recv 50D0AE60''
''gpg -a --export 50D0AE60 > /tmp/key''
''apt-key add /tmp/key'' (requires superuser privileges)

Jetzt starte ''apt-get update && apt-get install amule''

Sieh dir auch die anderen [[aMule-de|aMule]] Zubehörprogramme an:

'''[[aMule CVS-de|aMule CVS]]'''

* amule
* amule-alc
* amule-alcc
* amule-alcc-dbg
* amule-alc-dbg
* amule-cas
* amule-cas-dbg
* amule-cmd
* amule-cmd-dbg
* amule-common
* amule-daemon
* amule-daemon-dbg
* amule-dbg
* amule-ed2k
* amule-ed2k-dbg
* amule-i18n-ar
* amule-i18n-bg
* amule-i18n-ca
* amule-i18n-da
* amule-i18n-de
* amule-i18n-en-gb
* amule-i18n-en-us
* amule-i18n-es
* amule-i18n-es-mx
* amule-i18n-et-ee
* amule-i18n-eu
* amule-i18n-fi
* amule-i18n-fr
* amule-i18n-gl
* amule-i18n-hr
* amule-i18n-hu
* amule-i18n-it
* amule-i18n-it-ch
* amule-i18n-ko-kr
* amule-i18n-nl
* amule-i18n-pl
* amule-i18n-pt-br
* amule-i18n-pt-pt
* amule-i18n-ru
* amule-i18n-sl
* amule-i18n-sv
* amule-i18n-tr
* amule-i18n-zh-cn
* amule-i18n-zh-tw
* amule-remote-gui
* amule-remote-gui-dbg
* amule-skin-gnome
* amule-skin-kde4
* amule-skin-tango
* amule-skin-xfce
* amule-theme-chicane
* amule-theme-default
* amule-theme-php-default
* amule-utils
* amule-utils-gui
* amuleweb
* amuleweb-dbg
* amule-wxcas
* amule-wxcas-dbg
* amule-xas

Zum Beispiel, wenn dir [[aMule-de|aMules]] [[AMuleWeb-de|Web interface]] gefällt und du das auch haben willst, starte nach den obigen Befehlen:

Für [[aMule CVS-de|aMule CVS]]: ''apt-get install amuleweb''

Für [[aMule-de|aMule]] stabile Veröffentlichung: ''apt-get install amule-console-utils''

Wenn du [[aMule-de|aMule]] immernoch kompilieren willst anstatt ein Paket zu verwenden: Lies weiter...

==Info: Welche aMule Version braucht welches wx?==
* Debian Etch liefert aMule 2.1.3 und wxwidgets 2.6.3

* aMule 2.1 braucht wxwidgets 2.6. Neuere Versionen von wxwidgets werden nicht unterstützt.
* aMule 2.2 braucht wxwidgets 2.8. Ältere Versionen von wxwidgets werden nicht unterstützt.

==Welche Entwicklerpakete benötige ich zum kompilieren?==

Zum kompilieren von [[aMule CVS-de|aMule CVS]] und [[aMule-de|aMule 2.2.0]] müssen folgende Pakete installiert sein:

* libglib2.0-dev
* libgtk2.0-dev
* zlib1g-dev
* libwxgtk2.8-dev (Wenn du wx von Hand kompilieren willst, brauchst du das nicht. Dieses Paket gibt es für Debian nur aus Vollstrecker`s Repository)
* libgd2-xpm-dev
* bison
* flex
* libreadline5-dev
* libgeoip-dev
* libupnp-dev

Wenn du die externe Kryptobibliothek verwenden willst brauchst du zusätzlich:

* libcrypto++-dev

==Vorbereitung: wxwidgets compilieren und installieren==
Dieses vorgehen ist für alle Debian Veröffentlichungen gleich.

Um aMule kompilieren zu künnen muss eine aktuelle Version von [[wxWidgets-de|wxWidgets]] installiert sein. Um das zu erreichen:
Deinstalliere alle früher erstellten Versionen von wx (vergleiche [[How to uninstall wxWidgets-de|Wie deinstalliere ich wxWidgets]]
und [[Check if wx is installed twice-de|Prüfen ob wx doppelt installiert ist]])
Folgende Pakete müssen installiert sein:

* flex
* bison
* gettext
* libgtk2.0-dev
* python-dev (>= 2.4.3)
* python-dbg
* lib1g-dev
* libjpeg62-dev
* libpng12-dev
* libtiff4-dev
* libgl1-mesa-dev '''oder''' libgl-dev
* libglu1-mesa-dev '''oder''' libglu-dev
* libesd0-dev
* libgnomeprintui2.2-dev
* libgconf2-dev
* libgstreamer0.10-dev
* libgstreamer-plugins-base0.10-dev
* python-central
* bc

Um ein aktuelles wxwidges zu installieren, können folgende Zeilen zur /etc/apt/sources.list hinzugefügt werden:

deb http://apt.wxwidgets.org/ etch-wx main

deb-src http://apt.wxwidgets.org/ etch-wx main

Dann sollten noch folgende Zeilen ausgeführt werden:
# $curl http://apt.wxwidgets.org/key.asc | sudo apt-key add -
# $sudo apt-get update
# $sudo apt-get install libwxbase2.8-dev

(Quelle: http://wiki.wxpython.org/InstallingOnUbuntuOrDebian)

Alternativ kann auch aus den Quellen kompiliert werden:

# Lade dazu das aktuelle wxwidgets wxGTK Quelltextarchiv von <tt>http://www.wxwidgets.org/downloads/</tt> herunter
# <tt>$ tar xvzf wxgtk-''Version''.tar.gz</tt>
# <tt>$ cd wxGTK-''Version''</tt>
# <tt>$ ./configure --prefix=/usr --with-gtk --enable-unicode --disable-compat24 --enable-optimise</tt>
# <tt>$ make</tt>
# <tt># make install</tt>
# <tt># ldconfig</tt>

$ = als normaler Nutzer ausgeführt 
<nowiki>#</nowiki> = als root ausgeführt

==aMule kompilieren und installieren==
Jetzt da du ein aktuelles wxGTK hast, mach weiter mit aMule:
# Installiere alle benötigten Paket die unter '''"Welche Entwicklerpakete benötige ich zum kompilieren?"'''
# Lade das aMule Quelltextarchiv von <tt>http://www.amule.org</tt> herunter (Beachte: Zum kompilieren von aMule 2.1.3 benötigst du noch [http://cvs.pld-linux.org/cgi-bin/cvsweb/SOURCES/aMule-wx.patch?rev=1.2 DIESEN] Patch.
# <tt>$ tar xvjf aMule-''Version''.tar.bz2</tt>
# <tt>$ cd aMule-''Version''</tt>
# Fü eine Übersicht welche Funktionen die (de)aktivieren kannst: <tt>$ ./configure --help</tt>
# Im einfachsten Fall führe <tt>$ ./configure --disable-debug --enable-optimize</tt> aus
# <tt>$ make</tt>
# <tt># make install</tt>

$ = als normaler Nutzer ausgeführt 
<nowiki>#</nowiki> = als root ausgeführt

Das wars! Jetzt starte aMule mit dem Befehl "amule".

== Eigene Debianpakete bauen ==

Zuerst brauchst du das Quelltextarchiv. Beachte; Nur aMule-CVS und Veröffentlichen von aMule 2.2.0 oder neuer können direkt zum bauen von Paketen verwendet werden.

Zuerst musst du alle nötigen Werkzeuge installieren:

* build-essential
* debhelper
* libglib2.0-dev
* libgtk2.0-dev
* zlib1g-dev
* libwxgtk2.8-dev
* libgd2-xpm-dev
* bison
* flex
* libcrypto++-dev
* libreadline5-dev
* libgeoip-dev
* libupnp-dev

'''Alle Befehle müssen im obersten Verzeichnis des entpackten Quelltextarchives ausgeführt werden (normalerweise .../amule-cvs oder .../aMule-<Version>)'''

Erstelle einen neuen Changelogeintrag (die Version im Changelog gibt die Version deiner Pakete vor) mit:
dch -v `date +%Y%m%d` New Upstream CVS Release
Nun starte den Paketbau mit:
dpkg-buildpackage -uc -b -rfakeroot
Nun wurden alle Pakete im übergeordneten Verzeichnis erstellt.
Zum installieren verwende:
dpkg -i <Paket>
oder erstelle dein eigenes Repository.

Du kannst auch nur einzelne Pakete bauen. Informationen hierzu gibt:
debian/rules help

== Geschafft... ==

Das wars! Dein selbstkompiliertes [[aMule-de|aMule]] ist auf deinem System installiert und wartet darauf benutzt zu werden.

Um [[aMule-de|aMule]] zu starten, tippe einfach <code>"amule"</code>. Um zu sehen ob alles funktioniert hat tippe <code>"amule -v"</code> und vergleiche die Ausgabe mit der Version die du installiert/kompiliert hast.

Wenn diese Anleitung dir nicht geholfen hat, hast du ein seltenes Problem auf deinem System ;-) Suche auf http://www.amule.org ([http://www.amule.org/amule aMule Forum] auf http://forum.amule.org ) oder besuche und in #amule auf irc.freenode.net und (nicht verzweifeln) wir werden unser besten tun dir zu helfen.

== Abschlußbemerkung ==

Wenn du einer der seltenen Fälle bist die [[aMule-de|aMule]] statisch kompilieren wollen, musst du zusätzlich ''libtiff4-dev'' (mit ''apt-get install libtiff4-dev'') installieren. Allerdings, dies wird '''NICHT''' empfohlen und, im Ernst, wird nicht wirklich besser funktionieren oder überhaupt funktionieren.

EC Protocol HOWTO

2007-08-24T11:59:44Z

87.139.115.64:

Work in progress, this site is under heavy construction.

== Basic Protocol Structure ==

'''Protocol definition'''

Short description:

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

The transmission layer consist of an two int32 values. 
A uint32 flag specify the format of the message e.g. if the packet uses utf8 encoded numbers or is compressed by zlib. 
The next uint32 determines the size of the application layer data. 

The application layer consists of an op-code and a tag counter,followed by a tag structure.

== 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

:bit 2: Has ID. When this flag is set, an uint32 number follows the flags, which is the ID of this packet. The response to this
::packet also has to have this ID. The only requirement for the ID value is that they should be unique in one session (or at
::least do not repeat for a reasonably long time.)

:bit 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.

== 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_tagtype_t] TAGTYPE
::[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. ec_tagtype_t is an uint8. 
TagName tells what it contains (see ECcodes.h for details). 
TagType sends the type of this tag (see ECPacket.h for types) 
TagLen contains the whole length of the tag, including the lengths of the 
possible sub-tags, but without the size of the tagName, tagType 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.

== Future Changes ==

Future changes of the EC protocol (probably after 2.2.0) may be:
*no more \0 for string termination
*last bit of flag byte indicates a following flag byte, and so on

== Resources ==

You get definitions of OP- and Tag-Codes at this locations in the source:
*./src/lib/ec/[c#|cpp|java]/ECCodes.[cs|h|java]
* ./docs/EC_Protocol.txt (outdated, but much useful information)

== Examples ==

'''Notes:'''
*aMule sends EC packets in two flavours (albeit it would understand other flag options as well), depending on the packet size.
**zlib compressed application data that doesn't use utf8 compressed numbers when decompressed.
**utf8 compressed numbers in the application data
*The tag size doesn't take into account the size of utf8 compressed numbers in subtags. When parsing, you may want to drop the length completely and get it by the size of the subtags + size of the value field (determined by the value type flag).

----

This is a packet in hex values that is send to aMule
for authorization:
<pre>
00 00 00 22 //flag
00 00 00 36 //packet body length 54
02 //EC_OP_AUTH_REQ
04 //tag count

c8 80 //EC_TAG_CLIENT_NAME
06 //EC_TAGTYPE_STRING
0d //value length 13
61 6d 75 6c 65 2d 72 65 6d 6f 74 65 00 //"amule-remote\0"

c8 82 //EC_TAG_CLIENT_VERSION
06 //EC_TAGTYPE_STRING
07 //value length 7
30 78 30 30 30 31 00 // "0x0001\0"

04 //EC_TAG_PROTOCOL_VERSION
03 //EC_TAGTYPE_UINT16
02 //value length 2
02 00 //value is defined by EC_CURRENT_PROTOCOL_VERSION

02 //EC_TAG_PASSWD_HASH
09 //EC_TAGTYPE_HASH16
10 //value length 16
47 bc e5 c7 4f 58 9f 48 //md5 hashed password string
67 db d5 7e 9c a9 f8 08 //password "aaa" was used
</pre>

c8 80 is in fact an utf8 encoded number. It decodes to 02 00 (or 512 in decimal). 
As every tag code, it is shifted one bit to left to
fit in a bit that indicates the presence of subtags. 
The lowest bit of 02 00 is 0; so this tag doesn't have subtags. 
When we shift the value to the right one bit (or divide by 2),
we get 01 00. 
That's the value that can be found in ECCodes.h.

----

This is a simple search request that is send without utf8 compressed numbers. 
<pre>
00 00 00 20 //plain format, no compression
00 00 00 21 //message length: 33

26 00 //EC_OP_SEARCH_START
01 //tag count
0e 03 //EC_TAG_SEARCH_TYPE
02 //EC_TAGTYPE_UINT8
00 00 00 17 //tag length: 23
00 02 //subtag count

0e 04 //EC_TAG_SEARCH_NAME
06 //EC_TAGTYPE_STRING
00 00 00 05 //tag length
74 65 73 74 00 //"test\0"

0e 0a //EC_TAG_SEARCH_FILE_TYPE
06 //EC_TAGTYPE_STRING
00 00 00 01 //tag length
00 //"\0"

00 //uint8 search type (local)
</pre>

EC Protocol HOWTO

2007-08-21T17:18:24Z

87.139.115.64:

Work in progress, this site is under heavy construction.

== Basic Protocol Structure ==

'''Protocol definition'''

Short description:

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

The transmission layer consist of an two int32 values. 
A uint32 flag specify the format of the message e.g. if the packet uses utf8 encoded numbers or is compressed by zlib. 
The next uint32 determines the size of the application layer data. 

The application layer consists of an op-code and a tag counter,followed by a tag structure.

== 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

:bit 2: Has ID. When this flag is set, an uint32 number follows the flags, which is the ID of this packet. The response to this
::packet also has to have this ID. The only requirement for the ID value is that they should be unique in one session (or at
::least do not repeat for a reasonably long time.)

:bit 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.

== 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_tagtype_t] TAGTYPE
::[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. ec_tagtype_t is an uint8. 
TagName tells what it contains (see ECcodes.h for details). 
TagType sends the type of this tag (see ECPacket.h for types) 
TagLen contains the whole length of the tag, including the lengths of the 
possible sub-tags, but without the size of the tagName, tagType 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.

== Future Changes ==

Future changes of the EC protocol (probably after 2.2.0) may be:
*no more \0 for string termination
*last bit of flag byte indicates a following flag byte, and so on

== Examples ==

'''Notes:'''
*aMule sends EC packets in two flavours (albeit it would understand other flag options as well), depending on the packet size.
**zlib compressed application data that doesn't use utf8 compressed numbers when decompressed.
**utf8 compressed numbers in the application data
*The tag size doesn't take into account the size of utf8 compressed numbers in subtags. When parsing, you may want to drop the length completely and get it by the size of the subtags + size of the value field (determined by the value type flag).

----

This is a packet in hex values that is send to aMule
for authorization:
<pre>
00 00 00 22 //flag
00 00 00 36 //packet body length 54
02 //EC_OP_AUTH_REQ
04 //tag count

c8 80 //EC_TAG_CLIENT_NAME
06 //EC_TAGTYPE_STRING
0d //value length 13
61 6d 75 6c 65 2d 72 65 6d 6f 74 65 00 //"amule-remote\0"

c8 82 //EC_TAG_CLIENT_VERSION
06 //EC_TAGTYPE_STRING
07 //value length 7
30 78 30 30 30 31 00 // "0x0001\0"

04 //EC_TAG_PROTOCOL_VERSION
03 //EC_TAGTYPE_UINT16
02 //value length 2
02 00 //value is defined by EC_CURRENT_PROTOCOL_VERSION

02 //EC_TAG_PASSWD_HASH
09 //EC_TAGTYPE_HASH16
10 //value length 16
47 bc e5 c7 4f 58 9f 48 //md5 hashed password string
67 db d5 7e 9c a9 f8 08 //password "aaa" was used
</pre>

c8 80 is in fact an utf8 encoded number. It decodes to 02 00 (or 512 in decimal). 
As every tag code, it is shifted one bit to left to
fit in a bit that indicates the presence of subtags. 
The lowest bit of 02 00 is 0; so this tag doesn't have subtags. 
When we shift the value to the right one bit (or divide by 2),
we get 01 00. 
That's the value that can be found in ECCodes.h.

----

This is a simple search request that is send without utf8 compressed numbers. 
<pre>
00 00 00 20 //plain format, no compression
00 00 00 21 //message length: 33

26 00 //EC_OP_SEARCH_START
01 //tag count
0e 03 //EC_TAG_SEARCH_TYPE
02 //EC_TAGTYPE_UINT8
00 00 00 17 //tag length: 23
00 02 //subtag count

0e 04 //EC_TAG_SEARCH_NAME
06 //EC_TAGTYPE_STRING
00 00 00 05 //tag length
74 65 73 74 00 //"test\0"

0e 0a //EC_TAG_SEARCH_FILE_TYPE
06 //EC_TAGTYPE_STRING
00 00 00 01 //tag length
00 //"\0"

00 //uint8 search type (local)
</pre>

EC Protocol HOWTO

2007-08-21T16:51:00Z

87.139.115.64: extend short description

Work in progress, this site is under heavy construction.

== Basic Protocol Structure ==

'''Protocol definition'''

Short description:

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

The transmission layer consist of an two int32 values. 
A uint32 flag specify the format of the message e.g. if the packet uses utf8 encoded numbers or is compressed by zlib. 
The next uint32 determines the size of the application layer data. 

The application layer consists of an op-code and a tag counter,followed by a tag structure.

== 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

:bit 2: Has ID. When this flag is set, an uint32 number follows the flags, which is the ID of this packet. The response to this
::packet also has to have this ID. The only requirement for the ID value is that they should be unique in one session (or at
::least do not repeat for a reasonably long time.)

:bit 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.

== 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_tagtype_t] TAGTYPE
::[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. ec_tagtype_t is an uint8. 
TagName tells what it contains (see ECcodes.h for details). 
TagType sends the type of this tag (see ECPacket.h for types) 
TagLen contains the whole length of the tag, including the lengths of the 
possible sub-tags, but without the size of the tagName, tagType 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.

'''Future Changes'''
Future changes of the EC protocol (probably after 2.2.0) may be:
*no more \0 for string termination
*last bit of flag byte indicates a following flag byte, and so on

'''Examples'''

This is a packet in hex values that is send to aMule
for authorization:
<pre>
00 00 00 22 //flag
00 00 00 36 //packet body length 54
02 //EC_OP_AUTH_REQ
04 //tag count

c8 80 //EC_TAG_CLIENT_NAME
06 //EC_TAGTYPE_STRING
0d //value length 13
61 6d 75 6c 65 2d 72 65 6d 6f 74 65 00 //"amule-remote\0"

c8 82 //EC_TAG_CLIENT_VERSION
06 //EC_TAGTYPE_STRING
07 //value length 7
30 78 30 30 30 31 00 // "0x0001\0"

04 //EC_TAG_PROTOCOL_VERSION
03 //EC_TAGTYPE_UINT16
02 //value length 2
02 00 //value is defined by EC_CURRENT_PROTOCOL_VERSION

02 //EC_TAG_PASSWD_HASH
09 //EC_TAGTYPE_HASH16
10 //value length 16
47 bc e5 c7 4f 58 9f 48 //md5 hashed password string
67 db d5 7e 9c a9 f8 08 //password "aaa" was used
</pre>

c8 80 is in fact an utf8 encoded number. It decodes to 02 00 (or 512 in decimal). 
As every tag code, it is shifted one bit to left to
fit in a bit that indicates the presence of subtags. 
The lowest bit of 02 00 is 0; so this tag doesn't have subtags. 
When we shift the value to the right one bit (or divide by 2),
we get 01 00. 
That's the value that can be found in ECCodes.h.

This is a search request that

EC Protocol HOWTO

2007-08-21T16:41:45Z

87.139.115.64: filled in some text from the docs/EC_Protocol.txt

Work in progress, this site is under heavy construction.

== Basic Protocol Structure ==

'''Protocol definition'''

Short description:

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

== 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

:bit 2: Has ID. When this flag is set, an uint32 number follows the flags, which is the ID of this packet. The response to this
::packet also has to have this ID. The only requirement for the ID value is that they should be unique in one session (or at
::least do not repeat for a reasonably long time.)

:bit 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.

== 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_tagtype_t] TAGTYPE
::[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. ec_tagtype_t is an uint8. 
TagName tells what it contains (see ECcodes.h for details). 
TagType sends the type of this tag (see ECPacket.h for types) 
TagLen contains the whole length of the tag, including the lengths of the 
possible sub-tags, but without the size of the tagName, tagType 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.

'''Future Changes'''
Future changes of the EC protocol (probably after 2.2.0) may be:
*no more \0 for string termination
*last bit of flag byte indicates a following flag byte, and so on

'''Examples'''

This is a packet in hex values that is send to aMule
for authorization:
<pre>
00 00 00 22 //flag
00 00 00 36 //packet body length 54
02 //EC_OP_AUTH_REQ
04 //tag count

c8 80 //EC_TAG_CLIENT_NAME
06 //EC_TAGTYPE_STRING
0d //value length 13
61 6d 75 6c 65 2d 72 65 6d 6f 74 65 00 //"amule-remote\0"

c8 82 //EC_TAG_CLIENT_VERSION
06 //EC_TAGTYPE_STRING
07 //value length 7
30 78 30 30 30 31 00 // "0x0001\0"

04 //EC_TAG_PROTOCOL_VERSION
03 //EC_TAGTYPE_UINT16
02 //value length 2
02 00 //value is defined by EC_CURRENT_PROTOCOL_VERSION

02 //EC_TAG_PASSWD_HASH
09 //EC_TAGTYPE_HASH16
10 //value length 16
47 bc e5 c7 4f 58 9f 48 //md5 hashed password string
67 db d5 7e 9c a9 f8 08 //password "aaa" was used
</pre>

c8 80 is in fact an utf8 encoded number. It decodes to 02 00 (or 512 in decimal). 
As every tag code, it is shifted one bit to left to
fit in a bit that indicates the presence of subtags. 
The lowest bit of 02 00 is 0; so this tag doesn't have subtags. 
When we shift the value to the right one bit (or divide by 2),
we get 01 00. 
That's the value that can be found in ECCodes.h.

This is a search request that

EC Protocol HOWTO

2007-08-21T16:14:55Z

87.139.115.64:

'''Basic Protocol Structure'''

'''Future Changes'''
Future changes of the EC protocol (probably after 2.2.0) may be:
*no more \0 for string termination
*last bit of flag byte indicates a following flag byte, and so on

'''Examples'''

This is a packet in hex values that is send to aMule
for authorization:
<pre>
00 00 00 22 //flag
00 00 00 36 //packet body length 54
02 //EC_OP_AUTH_REQ
04 //tag count

c8 80 //EC_TAG_CLIENT_NAME
06 //EC_TAGTYPE_STRING
0d //value length 13
61 6d 75 6c 65 2d 72 65 6d 6f 74 65 00 //"amule-remote\0"

c8 82 //EC_TAG_CLIENT_VERSION
06 //EC_TAGTYPE_STRING
07 //value length 7
30 78 30 30 30 31 00 // "0x0001\0"

04 //EC_TAG_PROTOCOL_VERSION
03 //EC_TAGTYPE_UINT16
02 //value length 2
02 00 //value is defined by EC_CURRENT_PROTOCOL_VERSION

02 //EC_TAG_PASSWD_HASH
09 //EC_TAGTYPE_HASH16
10 //value length 16
47 bc e5 c7 4f 58 9f 48 //md5 hashed password string
67 db d5 7e 9c a9 f8 08 //password "aaa" was used
</pre>

c8 80 is in fact an utf8 encoded number. It decodes to 02 00 (or 512 in decimal). 
As every tag code, it is shifted one bit to left to
fit in a bit that indicates the presence of subtags. 
The lowest bit of 02 00 is 0; so this tag doesn't have subtags. 
When we shift the value to the right one bit (or divide by 2),
we get 01 00. 
That's the value that can be found in ECCodes.h.

EC Protocol HOWTO

2007-08-17T19:36:02Z

87.139.115.64:

'''Basic Protocol Structure'''

'''Future Changes'''

'''Examples'''

This is a packet in hex values that is send to aMule
for authorization:
<pre>
00 00 00 22 //flag
00 00 00 36 //packet body length 54
02 //EC_OP_AUTH_REQ
04 //tag count

c8 80 //EC_TAG_CLIENT_NAME
06 //EC_TAGTYPE_STRING
0d //value length 13
61 6d 75 6c 65 2d 72 65 6d 6f 74 65 00 //"amule-remote\0"

c8 82 //EC_TAG_CLIENT_VERSION
06 //EC_TAGTYPE_STRING
07 //value length 7
30 78 30 30 30 31 00 // "0x0001\0"

04 //EC_TAG_PROTOCOL_VERSION
03 //EC_TAGTYPE_UINT16
02 //value length 2
02 00 //value is defined by EC_CURRENT_PROTOCOL_VERSION

02 //EC_TAG_PASSWD_HASH
09 //EC_TAGTYPE_HASH16
10 //value length 16
47 bc e5 c7 4f 58 9f 48 //md5 hashed password string
67 db d5 7e 9c a9 f8 08 //password "aaa" was used
</pre>

c8 80 is in fact an utf8 encoded number, which decodes to 02 00 (or 512 in decimal). 
As every tag code, it is shifted one bit to left to
fit in a bit that indicates the presence of subtags. 
The lowest bit of 02 00 is 0; so this tag doesn't have subtags. 
When we shift the value to the right one bit (or divide by 2),
we get 01 00. 
That's the value that can be found in ECCodes.h.