Technical Notes
===============
This document describes additional technical information of aria2. The
expected audience is developers.
Control File (\*.aria2) Format
------------------------------
The control file uses a binary format to store progress information of
a download. Here is the diagram for each field::
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+---+-------+-------+-------------------------------------------+
|VER| EXT |INFO |INFO HASH ... |
|(2)| (4) |HASH | (INFO HASH LENGTH) |
| | |LENGTH | |
| | | (4) | |
+---+---+---+-------+---+---------------+-------+---------------+
|PIECE |TOTAL LENGTH |UPLOAD LENGTH |BIT- |BITFIELD ... |
|LENGTH | (8) | (8) |FIELD | (BITFIELD |
| (4) | | |LENGTH | LENGTH) |
| | | | (4) | |
+-------+-------+-------+-------+-------+-------+---------------+
|NUM |INDEX |LENGTH |PIECE |PIECE BITFIELD ... |
|IN- | (4) | (4) |BIT- | (PIECE BITFIELD LENGTH) |
|FLIGHT | | |FIELD | |
|PIECE | | |LENGTH | |
| (4) | | | (4) | |
+-------+-------+-------+-------+-------------------------------+
^ ^
| |
+-------------------------------------------------------+
Repeated in (NUM IN-FLIGHT) PIECE times
``VER`` (VERSION): 2 bytes
Should be either version 0(0x0000) or version 1(0x0001). In
version 1, all multi-byte integers are saved in network byte
order(big endian). In version 0, all multi-byte integers are saved
in host byte order. aria2 1.4.1 can read both versions and only
writes a control file in version 1 format. version 0 support will
be disappear in the future version.
``EXT`` (EXTENSION): 4 bytes
If LSB is 1(i.e. ``EXT[3]&1 == 1``), aria2 checks whether the saved
!InfoHash and current downloading one are the same. If they are not
the same, an exception is thrown. This is called "infoHashCheck"
extension.
``INFO HASH LENGTH``: 4 bytes
The length of InfoHash that is located after this field. If
"infoHashCheck" extension is enabled, if this value is 0, then an
exception is thrown. For http/ftp downloads, this value should be
0.
``INFO HASH``: ``(INFO HASH LENGTH)`` bytes
BitTorrent InfoHash.
``PIECE LENGTH``: 4 bytes
The length of the piece.
``TOTAL LENGTH``: 8 bytes
The total length of the download.
``UPLOAD LENGTH``: 8 bytes
The uploaded length in this download.
``BITFIELD LENGTH``: 4 bytes
The length of bitfield.
``BITFIELD``: ``(BITFIELD LENGTH)`` bytes
This is the bitfield which represents current download progress.
``NUM IN-FLIGHT PIECE``: 4 bytes
The number of in-flight pieces. These piece is not marked
'downloaded' in the bitfield, but it has at least one downloaded
chunk.
The following 4 fields are repeated in ``(NUM IN-FLIGHT PIECE)``
times.
``INDEX``: 4 bytes
The index of the piece.
``LENGTH``: 4 bytes
The length of the piece.
``PIECE BITFIELD LENGTH``: 4 bytes
The length of bitfield of this piece.
``PIECE BITFIELD``: ``(PIECE BITFIELD LENGTH)`` bytes
The bitfield of this piece. The each bit represents 16KiB chunk.
DHT routing table file format
-----------------------------
aria2 saves IPv4 DHT routing table in ``${HOME}/.aria2/dht.dat`` and
IPv6 DHT routing table in ``${HOME}/.aria2/dht6.dat`` by default.
``dht.dat`` and ``dht6.dat`` files use same binary encoding and have
following fields. All multi byte integers are in network byte
order. ``RSV`` (RESERVED) fields are reserved for future use. For now
they should be all zeros::
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+---+-+---+-----+---------------+---------------+---------------+
|MGC|F|VER| RSV | MTIME | RSV |LOCAL NODE ID :
|(2)|M|(2)| (3) | (8) | (8) | (20) :
| |T| | | | | :
+---+-+---+-----+-------+-------+-------+-------+---------------+
:LOCAL NODE ID | RSV | NUM | RSV |
: (continued) | (4) | NODE | (4) |
: | | (4) | |
+-+-------------+-------+-------+-+-----+-------+---------------+
|P| RSV |COMPACT PEER INFO| RSV | <-+
|L| (7) | (PLEN) | (24 - PLEN) | |
|E| | | | |
|N| | | | |
+-+-------------+-----------------+-----+-------+---------------+ |
| NODE ID | RSV | |
| (20) | (4) | <-----------------+
+---------------------------------------+-------+ Repeated in
(NUM NODE) times.
``MGC`` (MAGIC): 2 bytes
It must be ``0xa1 0xa2``.
``FMT`` (FORMAT ID): 1 byte
The format ID should be ``0x02``.
``VER`` (VERSION): 2 bytes
The version number should be ``0x00 0x03``.
``MTIME``: 8 bytes
This is the time when aria2 saved the file. The value is the time
since the Epoch(1970/1/1 00:00:00) in 64 bits integer.
``LOCALNODE ID``: 20 bytes
Node ID of the client.
``NUM NODE``: 4 bytes
The number of nodes the routing table has. ``NUM NODE`` node
information follows.
The data of ``NUM NODE`` node will follow. The node information are
stored in the following fields. They are repeated in ``NUM NODE``
times.
``PLEN`` (COMPACT PEER INFO LENGTH): 1 byte
The length of compact peer info. For IPv4 DHT, it must be 6. For
IPv6 DHT, it must be 18.
``COMPACT PEER INFO``: ``(PLEN)`` bytes
The address and port of peer in compact peer format.
``NODE ID``: 20 bytes
The node ID of this node.