API Reference
This page contains all functions and signals which can be used in your scripts.
Contents |
The KTorrent module
Functions
| Function name | Description |
|---|---|
| KTorrent.torrents() | Returns a list of strings containing the info hashes of all torrents. |
| KTorrent.start(info_hash) | Start a torrent, the info hash of the torrent needs to be given as parameter. |
| KTorrent.stop(info_hash) | Stop a torrent, the info hash of the torrent needs to be given as parameter. |
| KTorrent.startAll() | Start all torrents. |
| KTorrent.stopAll() | Stop all running torrents. |
| KTorrent.load(url,group) | Load a torrent, the url can be a local file as well as a remote file (e.g. http://foo.com/bar.torrent). The group parameter is used to add the torrent to a group, if the string is empty, the torrent will not be added to a group. |
| KTorrent.loadSilently(url,group) | Same as load, except don't ask the user any questions and just use the default settings. |
| KTorrent.remove(info_hash,data_to) | Remove a torrent, the info hash of the torrent needs to be given as parameter. The data_to parameter is a boolean indicating whether you want to also remove the data of the torrent. |
| KTorrent.removeDelayed(info_hash,data_to) | Removes a torrent later (half a second after the call), not immediately. Use this function when responding to a signal of a torrent and you want to remove that torrent. |
| KTorrent.setPaused(pause) | Pause or resume the queue. Pausing will cause all running torrents to be stopped, resuming will continue those stopped by the last pause. |
| KTorrent.paused() | Whether or not the queue is paused. |
| KTorrent.orderQueue() | Tell the queue manager to order the queue. |
| KTorrent.reindexQueue() | Tell the queue manager to reindex the queue priorities. If you have 5 torrents, the priorities will be 5 for the first in the queue, 4 for the next, ... and 1 for the last. |
| KTorrent.groups() | Get a list of all custom groups. |
| KTorrent.addGroup(group_name) | Add a new custom group, the name of the group needs to be given as parameter. Returns True upon succes, False otherwise. |
| KTorrent.removeGroup(group_name) | Remove a group. |
| KTorrent.group(group_name) | Get a group given it's name. |
| KTorrent.torrent(info_hash) | Returns an object representing a torrent, the info hash of the torrents needs to be given as parameter. The functions and signals of a torrent can be found here |
| KTorrent.log(line) | Write something to the log. |
| KTorrent.numTorrentsRunning() | Get the number of running torrents. |
| KTorrent.numTorrentsNotRunning() | Get the number of torrents not running. |
| KTorrent.dataDir() | Get the directory where ktorrent stores it's data. |
Signals
The signals, shown here are the C++ signatures, which you need to use when connecting to them in your script.
| Signal | Meaning |
|---|---|
| torrentAdded(const QString & info_hash) | Emitted when a torrent is added. As parameter the info hash of the torrent is provided. |
| torrentRemoved(const QString & info_hash) | Emitted when a torrent is removed. As parameter the info hash of the torrent is provided. |
| finished(const QString & info_hash) | Emitted when a torrent finishes downloading. As parameter the info hash of the torrent is provided. |
| torrentStoppedByError(const QString & info_hash,const QString & msg) | Emitted when a torrent is stopped by an error, the msg parameter is a human readable string giving some information about the error. |
| settingsChanged() | Emitted when the user has modified the settings. |
| pauseStateChanged(bool paused) | Emitted when the pause state changes. |
Torrents
For the rest of this section, we assume that tor is a variable which is returned by KTorrent.torrent() :
tor = KTorrent.torrent(some_info_hash)
Functions
| Function name | Description |
|---|---|
| tor.infoHash() | Returns the info hash of a torrent in a string. |
| tor.name() | Returns the name of the torrent. |
| tor.isPrivate() | Returns True if the torrent is private, False otherwise. |
| tor.downloadSpeed() | Returns the current download speed (in bytes/second) |
| tor.uploadSpeed() | Returns the current upload speed (in bytes/second) |
| tor.bytesDownloaded() | Returns the total number of bytes downloaded |
| tor.bytesUploaded() | Returns the total number of bytes uploaded |
| tor.totalSize() | Returns the total size in bytes of a torrent |
| tor.bytesLeftToDownload() | Returns how many bytes there are left to download (deselected files not included) |
| tor.bytesLeft() | Returns how many bytes there are left to download (deselected files included) |
| tor.bytesToDownload() | Returns how many bytes there need to be downloaded (totalSize() - deselected files) |
| tor.priority() | Returns the torrents priority in the queue, the higher the number the higher the priority |
| tor.setPriority(p) | Sets the priority, an integer should be used as parameter. |
| tor.isAllowedToStart() | Returns true if the torrent is allowed to be started by the queue manager |
| tor.setAllowedToStart(allowed) | Set whether the queue manager can start this torrent |
| tor.setMaxShareRatio(ratio) | Set the max share ratio |
| tor.maxShareRatio() | Get the max share ratio |
| tor.shareRatio() | Get the current share ratio |
| tor.setMaxSeedTime(hours) | Set the max seed time in hours |
| tor.maxSeedTime() | Get the max seed time in hours |
| tor.seedTime() | Get the current seed time in hours |
tor.chunks() tor.chunkSize() tor.chunkDownloaded(chunk_index)
Functions to ask information about chunks, how many there are, how big they are (in bytes), and whether or not a chunk is donwloaded.
tor.seedersConnected() tor.seedersTotal() tor.leechersConnected() tor.leechersTotal()
These functions give information about the number of seeders and leechers.
tor.currentTracker()
tor.trackers()
tor.setTrackerEnabled(tracker_url,enabled) | 1 = enabled, 0 = disabled
ex: tor.setTrackerEnabled("http://tracker.thepiratebay.org/announce",0)
tor.changeTracker(tracker_url)
tor.announce()
tor.scrape()
tor.addTracker(tracker_url)
tor.removeTracker(tracker_url)
tor.restoreDefaultTrackers()
With these functions you can control the trackers of the torrent, currentTracker will return a string and the tracker_url parameters are also strings. The trackers function returns a list of strings.
tor.webSeeds() tor.addWebSeed(webseed_url) tor.removeWebSeed(webseed_url)
These allow you to add and remove webseeds.
tor.numFiles() tor.dataDir() tor.torDir() tor.pathOnDisk() (will be added in 4.0) tor.filePath(file_index) tor.filePathOnDisk(file_index) tor.fileSize(file_index) tor.filePriority(file_index) tor.setFilePriority(file_index,prio) tor.firstChunkOfFile(file_index) tor.lastChunkOfFile(file_index) tor.filePercentage(file_index) tor.isMultiMediaFile(file_index) tor.setDoNotDownload(file_index,do_not_download)
Finally with these functions you can do stuff with the files of a torrent. Note that calling tor.setDoNotDownload(0,True), will delete the first file of a torrent, so be careful when calling this function.
Signals
finished(QObject* tor) stoppedByError(QObject* tor,const QString & msg) seedingAutoStopped(QObject* tor,const QString & reason) corruptedDataFound(QObject* tor) torrentStopped(QObject* tor)
These signals are supported by a torrent. It should be pretty obvious what happened when these signals are emitted. The seedingAutoStopped signals is emitted when the torrent reaches it's maximum share ratio or it's maximum seed time. These are the C++ signatures of the signals, which need to be used when you connect to them like this :
tor.connect("finished(QObject* )",torrentFinished)
tor.connect("stoppedByError(QObject* ,const QString & )",torrentStoppedByError)
tor.connect("seedingAutoStopped(QObject* ,const QString & )",seedingAutoStopped)
tor.connect("corruptedDataFound(QObject* )",corruptedDataFound)
George can you verify this is the correct syntax for torrentStopped?
tor.connect("torrentStopped(QObject* ,const QString & )",torrentStopped)
The QObject parameter, is actually the torrent object (so in the above snippet it would be equal to tor).
Example: See E-Mail Notifications in Writing_Scripts#Included_Scripts.
Groups
For the rest of this section, we assume that group is a variable which is returned by KTorrent.group() :
Note: For current versions this only work on user-created groups (i.e not created by KTScriptingPlugin)
group = KTorrent.group("my cool group")
Functions
| Function name | Description |
|---|---|
| group.name() | Returns the name of the group. |
| group.icon() | Returns the icon of the group. This function returns the icon name. |
The following functions apply to the group policy :
group.defaultSaveLocation() group.setDefaultSaveLocation(dir)
Get and set the default save location of the group.
group.maxShareRatio() group.setMaxShareRatio(ratio) group.maxSeedTime() group.setMaxSeedTime(hours)
Set and get the max share ratio and max seed time of torrents which are part of the group.
group.maxUploadSpeed() group.setMaxUploadSpeed(speed) group.maxDownloadSpeed() group.setMaxDownloadSpeed(speed)
Set and get the max upload and download speed (in bytes/s) for torrents of the group.
group.onlyApplyOnNewTorrents() group.setOnlyApplyOnNewTorrents(on)
Set whether or not the group policy will be applied on every torrent which is added to the group, or only on the newly loaded or created torrents.
The KTScriptingPlugin module
KTScriptingPlugin.scriptsDir() KTScriptingPlugin.scriptDir(script) // added in 3.2.1
Get the scripts directory or the data directory of a script. Use these to find ui files and data files you might need for your script.
KTScriptingPlugin.readConfigEntry(group,name,default_value) KTScriptingPlugin.readConfigEntryInt(group,name,default_value) KTScriptingPlugin.readConfigEntryFloat(group,name,default_value) KTScriptingPlugin.readConfigEntryBool(group,name,default_value)
Read entries from the configuration.
KTScriptingPlugin.writeConfigEntry(group,name,value) KTScriptingPlugin.writeConfigEntryInt(group,name,value) KTScriptingPlugin.writeConfigEntryFloat(group,name,value) KTScriptingPlugin.writeConfigEntryBool(group,name,value)
Write entries to the configuration. Make sure that group is unique, so that you do not get conflicts with other parts of KTorrent.
KTScriptingPlugin.syncConfig(group)
Make sure that a group in the configuration is saved.
KTScriptingPlugin.createTimer(single_shot)
This creates a Qt QTimer object, which you can use in your scripts, to schedule timeouts.
KTScriptingPlugin.addGroup(name,icon,path,obj) KTScriptingPlugin.removeGroup(name)
Add and remove your own group, see above for more details.
Random Code Snippets
Random Code Snippets are kept in the Writing_Scripts#Random_Code_Snippets document.
