Commit 07865407 authored by Julien Lepiller's avatar Julien Lepiller

doc: Add documentation.

parent ac4f220e
......@@ -9,3 +9,10 @@ config.status
......@@ -5,3 +5,5 @@ SOURCES= \
torrent/utils/sha-1.scm \
torrent/bencoding.scm \
info_TEXINFOS= doc/guile-torrent.texi
\input texinfo
@documentencoding UTF-8
@settitle guile-torrent
@include version.texi
Copyright @copyright{} 2018 Julien Lepiller
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end quotation
@end copying
@end titlepage
@node Top
@top guile-torrent
This document describes guile-torrent version @value{VERSION}, a guile
implementation of the bittorrent protocol.
* Encoding and decoding data::
* Managing .torrent files::
@end menu
@node Encoding and decoding data
@chapter Encoding and decoding data
Some parts of the bittorrent protocol use the @dfn{bencoding} for data
representation. This encoding is implemented in the @code{(torrent bencoding)}
module. This module consists of a record type and two public procedures:
@deffn {Data Type} dictionnary
This data type represents a dictionnary. A dictionnary is a datastructure
that associates values to keys. This field contains only one element,
@code{alist}, a association list.
@deffn {Scheme Procedure} dictionnary-alist @var{dictionnary}
This procedure returns the actual association list contains in a dictionnary.
@end deffn
@end deffn
@deffn {Scheme Procedure} bencode @var{data}
This procedure takes @var{data} and returns a @code{bytevector} corresponding
to the bencoded @var{data}. The data can be a @code{bytevector}, a @code{string},
an @code{integer}, a @code{list} or a @code{dictionnary}.
@end deffn
@deffn {Scheme Procedure} bdecode @var{port}
This procedure takes @var{port} and reads data from it. After it reaches
@code{#eof}, this procedure returns the data corresponding to what it read in
the bencoding. The result can be a @code{dictionnary}, a @code{list},
a @code{bytevector} or an @code{integer} depending on the data that has been
@end deffn
@node Managing .torrent files
@chapter Managing .torrent files
One of the ways to get torrent informations is by loading a @file{.torrent} file.
The file contains many useful information, including announce URLs to wich
the bittorrent client can ask for more peers regularly, the hash of each piece,
their size and the list of files contained in the torrent.
@cindex infohash
From this, we can derive the @dfn{infohash} which is a @code{sha-1} hash of a
part of that file and corresponds to the identifier of the torrent.
Although there are multiple methods to get peers for a torrent, they all require
the infohash of the torrent before you can start asking for peers. The infohash
itself can come either from the @file{.torrent} file as seen in this section
or a @code{magnet://} URL. The content of this URL is actually the hexadecimal
representation of the infohash.
The @code{(torrent metainfo)} module is responsible for parsing @file{.torrent}
files. This module contains the following definitions:
@deffn {Data Type} metainfo
This data type represents the necessary information contained in the @file{.torrent}
@table @asis
@item @code{info}
The info section of the @file{.torrent} file.
@item @code{annouce}
A string containing the address of the main announce URL for this torrent.
@item @code{infohash}
A bytevector representing the infohash of this file.
@end table
@end deffn
@deffn {Data Type} torrent-info
This data type represents the necessary infomation contained in the @code{info}
section of the @file{.torrent} file.
@table @asis
@item piece-length
A number representing the number of bytes of each piece
@item pieces
A bytevector representing the concatenation of each piece's @code{sha-1} hash.
This information is useful to independently check each piece's integrity.
@item private?
A boolean indicating whether this torrent is private i.e. whether the client
must only use the trackers present in the file or if it can use other means
such as the peer exchange protocol.
@item single-file?
A boolean indicating whether this torrent contains a single file.
@item name
A string containing the name of the torrent. In single-file mode, this
corresponds to the filename. In multiple-file mode, this corresponds to the
name of the folder containing the files.
@item len
In single-file mode, a number representing the size of the file in bytes. In
multiple-files mode, @code{#f}.
@item files
In single-file mode, @code{#f}. In multiple-files mode, a list of
@code{torrent-info-file} objects representing the content of the torrent.
@end table
@end deffn
@deffn {Data Type} torrent-info-file
This data type represents the necessary information to describe a file from
a torrent.
@table @asis
@item len
A number representing the size of the file in bytes.
@item path
A list of strings representing the path to the file from the top-level directory
of the torrent.
@end table
@end deffn
This module also defines the following procedure:
@deffn {Scheme Procedure} parse-torrent-file @var{file}
This procedure parses a @file{.torrent} file whose name is contained in @var{file}
and returns a @code{metainfo} object containing the necessary information in
that file.
@end deffn
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment