From 07865407f02b1088882fe06f6c6a63465677d99e Mon Sep 17 00:00:00 2001 From: Julien Lepiller Date: Sat, 19 May 2018 11:23:40 +0200 Subject: [PATCH] doc: Add documentation. --- .gitignore | 7 ++ Makefile.am | 2 + doc/guile-torrent.texi | 168 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 177 insertions(+) create mode 100644 doc/guile-torrent.texi diff --git a/.gitignore b/.gitignore index 1cb2a72..29f6512 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,10 @@ config.status aclocal.m4 missing pre-inst-env +doc/*.html +doc/*.info +stamp-vti +doc/version.texi +.dirstamp +mdate-sh +.guix-profile* diff --git a/Makefile.am b/Makefile.am index 4cbb16a..c43fc5d 100644 --- a/Makefile.am +++ b/Makefile.am @@ -5,3 +5,5 @@ SOURCES= \ torrent/utils/sha-1.scm \ torrent/bencoding.scm \ torrent/metainfo.scm + +info_TEXINFOS= doc/guile-torrent.texi diff --git a/doc/guile-torrent.texi b/doc/guile-torrent.texi new file mode 100644 index 0000000..b7e9903 --- /dev/null +++ b/doc/guile-torrent.texi @@ -0,0 +1,168 @@ +\input texinfo +@setfilename guile-torrent.info +@documentencoding UTF-8 +@settitle guile-torrent + +@include version.texi + +@copying +Copyright @copyright{} 2018 Julien Lepiller + +@quotation +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 + +@titlepage +@end titlepage + +@contents + +@node Top +@top guile-torrent + +This document describes guile-torrent version @value{VERSION}, a guile +implementation of the bittorrent protocol. + +@menu +* 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 +read. +@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} +file. + +@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 + +@bye -- 2.18.1