|
libaria2cpp 0.2.0
Basic CPP library to connect to an ARIA2 daemon via the RPC interface.
|
Aria2CPP is a C++ library to aid in the writing of programs which will need to connect to an Aria2 daemon via RPC calls. Aria is a multipurpose downloader which handles FTP, HTTP and BitTorrent protocols, in addition to others. It can run as a daemon with a JSON-RPC over HTTP interface which offers access to the same functionality as the command line client.
This library takes care of the protocol details, and allows you to write programs that directly control any Aria2 daemon simply and easily.
This library is a single static library called aria2cpp.a to be linked with your binary.
This library uses other libraries which must also be installed and linked in with your program. The libraries that it uses are JsonCPP and JsonRPCCPP. Linux users will likely find these in their distros repositories.
To use the library, you will need to link the aria2cpp.a static library, libjson, libjsonrpccpp-common and libjsonrpccpp-client.
Include the aria2cpp.h file in your source file.
#include <libaria2cpp/aria2cpp.h>
To build the library from source, just download the source and run "make" in the source directory then "make install" with root privileges. The compile, pass the following library flags to gcc
-laria2cpp -ljsonrpccpp-client -ljsonrpccpp-common -ljsoncpp
Aria2CPP is object based, and each class is documented under the "Class List" page in the "Classes" menu. This is the best way to start learning about the functionality.
Aria2 can run as a daemon, which uses RPC calls to communicate with clients. Clients can do almost anything the command line client can do, and multiple clients can use a single instance of an Aria2 daemon concurrently.
Aria2 maintains a list of active and inactive downloads. Each download, which includes BitTorrents, are uniquely identified by an alphanumeric string called a "GID". This GID can be passed to methods to specify which download you want to operate on. You can also specify which download you want to operate on by its position number in the list. Using the GID is recommended as the position a download has in the list can change from time to time, whereas the GID remains constant throughout the download, and even after an Aria2 session is saved and resumed.
Each download has a set of data associated with it, which contains its current status, total size, bytes downloaded so far, and so forth.
Finally, many configuration options, both global and specific to a download can be set to control Aria2's behaviour. While this library allows you to configure every aspect of a running Aria2 instance, this configuration is generally done by a configuration file.
This is the main class which is responsible for communicating with Aria2. Create a new instance of this class, specifying the URL, the port to connect to and optionally, the secret token. The default URL is http://localhost and the default port is 6800. This class has methods to add downloads, retrieve information, resume and pause downloads.
This class will contain an array of Download classes, each of which relates to a download that Aria2 is managing.
It is important to note that the array of Downloaded classes is a snapshot of the state of the downloads at the time the information was requested. If you require updated information, you will need to request this information again.
Optionally, you can pass a list of 'keys' through a stringlist to the getDownloads() method to only request particular details of a download to be retrieved. This may be useful if you are only interested in a small subset of information, such as only wanting to know the GID's and status.
This class contains information about a specific download. You can request this class be returned for an existing download (both active and stopped) by GID (Aria2CPP::getDownload(std::string gid)) or by position (Aria2CPP:getDownload(size_t pos)) and query it for information.
The Download class will contain a an array (filelist) of File for each downloaded file. Usually there will just be one file for a basic HTTP or FTP download, but for Torrents there will typically be multiple Files in the array. Obtain the filelist with Download::fileList().
Note that once this information is retrieved, it stays as is, regardless of progress in the background. To get up to date information, you'll need to request the Download object from Aria2CPP and the filelist from that Download object all over again.
This class contains information about a downloaded file. This class will contain download statistics which are specific for that File, the file name and path. To display information on each file being downloaded, query this class.
Note that the statistics are from the time that the last Aria2CPP::update() method was called. As with the Download class, you'll need to retrieve the information again after calling Aria2CPP::update() for new data.
This class contains options which relate to a download. Each download in Aria2 can maintain its own set of options. You can use this class to configure option when initiating a new download and pass an instance with the settings you want to one of the methods which takes this class when adding a download. Only set options which need to differ from the globally set aria2 options or defaults.
This contains global statics for Aria2. Namely how many downloads are in progress, download speeds and upload speeds.
This class is used to set and get all global options for Aria2. Retrieve an instance of this class using Aria2CPP::getGlobalOption() and use it to configure Aria2CPP on the fly.
Unlike Aria2CPP, Download and File, this class will always returns current information.
Include the "aria2cpp.h" header file.
#include <libaria2cpp/aria2cpp.h>
Create a new instance of the class.
Aria2CPP aria("http://localhost","6800","pass123");
This will create a new instance of Aria2CPP, "aria" which connects to an aria instance running on the same machine, with the default port and the secret token "pass123". Leave off the secret token of Aria2 isn't configured to use one. If Aria2 isn't configured to use a secret token, but one specified, then it will just be ignored.
From here we can run some queries.
This will retrieve a list of all downloads and print the title of all downloads which are Torrents;
for(auto a : aria.getDownloads()) {
if (a.isTorrent()) {
std::cout << a.title() std::endl;
}
}
This will add a new download;
aria.addDownload("http://ftp.cdrom/com/pub/file.txt");
This will add the torrent "test.torrent". This method takes a path to a torrent file;
aria.addTorrent("test.torrent");
Adds a torrent, with the maximum number of peers set to 4. The options class which is passed contains the custom options. All other options that aren't changed will be the current global options;
DownloadOptions options;
options.setBtMaxPeers(4);
aria.addTorrent("test.torrent", options);
Set the following Aria2 global options Disable IPV6 Maxtries to 611;
std::shared_ptr<Options> options = aria.getOptions(); options->setDisableIpv6(true); options->setMaxTries(611);
Get the status of the download at position one and if it is Paused, print "Paused";
if (aria.getDownloads().at(1).status() == Status::Paused) {
std::cout << "Paused\n";
}
With the exception of Options, all information returned from Aria2CPP should only be considered current at the time it was taken. Retrieve the information you want, act on the information, and when updated information is required, for example, when refreshing the display, run Aria2CPP::update() and obtain your information again.
A typical workflow might look like this...
Create Aria2 class to begin with. You won't get far without.
If you shutdown aira2c, then the connection will no longer be valid and any future call to a method will fail. It is important therefore if you do shutdown Aria2 to then destroy the class.
You can change alternative stop the Aria2 daemon by Options::setDaemon(false). Again, as with the shutdown, if you do this, there will no longer be an accessible Aria2 daemon, at which point the best option is to destroy the Aria2CPP objects.
The global configuration options map exactly to the command line parameters. For example, setContentDispositionDefaultUtf8() relates to the –content-disposition-default-utf8 command line option. The documentation for these configuration methods is taken from the Aria2 man page.
There is an alternative way to set a global option, and that is to use the Aria2CPP::setGlobalOptionMethod().
Aria2CPP::setGlobalOptionMethod("file-allocation", "prealloc") has the same effect as Options::setFileAllocation(FileAllocation::prealloc);
The Aria2CPP::setGlobalOptionMethod() is a fallback option, and the options are passed as-is to Aria2. Therefore, if there are any configuration options which aren't included on the Options class (i.e., an update of Aria2 adds new options which this library has not yet recognised), you can use this method to configure.
1.9.4