Table of Contents
This short howto contains information which could be useful for BTG developers.
Follow the instructions on http://developer.berlios.de/svn/?group_id=3293.
Trunk is being used for development. Do not use the stable-branch.
Running the autogen.sh script located in the root of SVN trunk should be enough.
On some FreeBSD versions, one has to use the following to generate the build system, since it contains older versions of autotools and no symlinks.
autoheader259 && aclocal19 -I m4 -I /usr/local/share/aclocal && libtoolize -c -f && automake19 --add-missing --copy --gnu && autoconf259 && autoheader259 && rm -f config.cache
Remember to use glibtoolize instead of libtoolize.
One can use the following script to connect to the daemon using XML-RPC. The transport in daemon.ini needs to be set to "xml-rpc".
#!/usr/bin/python import xmlrpclib uri = "http://localhost:16000" p = xmlrpclib.ServerProxy(uri) # Command id of the sent command. command_id = 1 p.general.initconnection(command_id, "user1", "hash of user1's password")
The above script sends one command, general.initconnection. This initialises the connection from a client to the daemon.
In the following, some of the more basic commands used to communicate with the deamon are explained in some detail.
The daemon will send either general.ack or general.error back. The ack command contains the ID of the command it acknowledges. The error command contains the ID of the command it was caused by and a string describing the error.
If the daemon sent a general.ack command back, one can create a new session or attach to an existing session.
To create a new session, transmit general.setup to the daemon. It will return general.setuprsp, which contains a sesion ID used to refer to this session. Or it returns an error, if the session cannot be created.
To attach to an existing session, one has to know the session ID first. To obtain the session IDs from the daemon, one has to transmit session.list to it. The daemon will transmit a session.listrsp command back, which will contain a list of sessions.
A client uses session.attach to attach to a session with a certain ID. The daemon will send a general.ack back to inform the client that it is attached. More than one client can be attached to the same session at the same time.
If the client is not allowed to attach to a session, it will receive general.error in this situation.
Once a client created or attached to a session, it can start adding torrents to the session. This can be done using context.createwithdata, context.createfromfile or context.createfromurl.
context.createwithdata adds a context (which is a torrent identified by an ID) only using the information contained in the command.
context.createfromfile creates a context by receiving parts of a torrent file until all parts are received. context.createfromurl downloads an URL.
context.createfromurl is async. The daemon returns an identifier using context.createfromurlrsp, which can be used to query the status of the operation using general.opstatus or abort it using general.opabort.
A list of context IDs / file names can be obtained using general.list. Once the client has this list, it can query the status of a context using context.status. The daemon will send a context.statusrsp back. This status contains information about how much has been downloaded, download rate etc..
Some common oprations on a torrent are
Detaching from a session is done by sending session.detach to the deamon.
This was a quick introduction to the commands used to interact with the daemon. Not all commands were covered. The easiest way to learn more about how they interact with the deamon is to observe the verbose log produced by the daemon. It shows which commands are received/sent to a client.
The list of commands is available here (generated from sources in the trunk of SVN).
Commands which inherit from btg::core::contextCommand can be constructed with an all-context flag set. This means that the daemon, when it receives such a command, will send a reply for all contexts in the session the command belongs to.
The all-context flag is not supported for some of the commands. This will for example not work with Command::CN_CPEERS and Command::CN_CFILEINFO - the daemon will not execute such commands. The reason is that the amount of data to transfer would be enormous for sessions with a large amount of torrents.
Patches can be easily made using "svn diff > file.diff" from trunk.