The cl-transmission Reference Manual

This is the cl-transmission Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sat Dec 03 20:46:27 2022 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 cl-transmission

Author

Thomas Schaper

License

MIT

Long Description

* CL-Transmission
** Usage
*** Loading
Lets start by loading ~CL-TRANSMISSION~ and defining our connection. Connections
are thread-safe in the way that you can use a one or more connection in multiple
threads.
#+begin_src lisp :exports both
(ql:quickload :cl-transmission)

(defvar *conn* (make-instance ’cl-transmission:transmission-connection
:host "your.ip" ;; the host is "localhost" by default.
:credentials ’("libreman" "super-secret-password")))
#+end_src

#+RESULTS:
: *CONN*

Please note that this package is not (yet) in Quicklisp so you will have to add
it to your local projects to be able to load it. See the [[https://www.quicklisp.org/beta/faq.html][Quicklisp FAQ]] on how to
do this.
*** Searching
So lets get some torrents. First lets get all torrents and of every torrent get
the id, name and eta. This is done by using the
~CL-TRANSMISSION:TRANSMISSION-GET~ method.

#+begin_src lisp :exports both
(cl-transmission:transmission-get *conn* #(:name :id :eta) :strict t)
#+end_src

#+RESULTS:
#+begin_example
(#<HASH-TABLE :TEST EQUAL :COUNT 3 {1014218D23}>
#<HASH-TABLE :TEST EQUAL :COUNT 3 {10142193B3}>
#<HASH-TABLE :TEST EQUAL :COUNT 3 {1014241C83}>)
NIL
#+end_example

As shown for every live torrent a hash-table is returned. So lets see how it is
structured:

#+begin_src lisp :exports both
(alexandria:hash-table-plist
(elt (cl-transmission:transmission-get *conn* #(:name :id :eta) :strict t)
0))
#+end_src

#+RESULTS:
| :NAME | debian-8.7.1-amd64-DVD-1.iso | :ID | 72 | :ETA | 1368 |

So it simply contains the fields we specified. Searching is done by or passing a
id, if you know it this is the fastest way, or mapping over the return value.

*** Adding
Adding torrents is done by the ~CL-TRANSMISSION:TRANSMISSION-ADD~
function. It accepts a =:FILENAME= argument which should be a filename
to a torrent file or a magnet link, and =:METAINFO= which should be a
base64-encoded torrent file.

So lets say we want to add a nice debian torrent to seed:

#+begin_src lisp :exports both
(cl-transmission:transmission-add *conn* :filename "http://cdimage.debian.org/debian-cd/current/amd64/bt-dvd/debian-8.7.1-amd64-DVD-2.iso.torrent") #+end_src

#+RESULTS:
: #<HASH-TABLE :TEST EQUAL :COUNT 3 {10174B6333}>
: :TORRENT-ADDED

We get a hash-table of our new torrent with an ~ID~, ~NAME~ and ~HASH-STRING~,
and the second return value is indicating this is a new torrent. So if we would
add the same torrent again this would be ~:TORRENT-DUPLICATE~.

*** Others
At the moment the entire section 3 of the RPC spec is implemented. Simply see
the exported method and their docstrings. Development is active and section 4
will be implemented.
** Author
+ Thomas Schaper (Thomas@libremail.nl)
** Copyright
Copyright (c) 2017 Thomas Schaper (Thomas@libremail.nl)

Version

0.1

Dependencies
  • rutils (system).
  • drakma (system).
  • named-readtables (system).
  • cl-ppcre (system).
  • uiop (system).
  • jonathan (system).
Source

cl-transmission.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 cl-transmission/src

Source

cl-transmission.asd.

Parent Component

cl-transmission (system).

Child Components

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


4.1 Lisp


4.1.1 cl-transmission/cl-transmission.asd

Source

cl-transmission.asd.

Parent Component

cl-transmission (system).

ASDF Systems

cl-transmission.


4.1.2 cl-transmission/src/cl-transmission.lisp

Dependencies
Source

cl-transmission.asd.

Parent Component

src (module).

Packages

cl-transmission.

Public Interface
Internals

4.1.3 cl-transmission/src/constants.lisp

Dependency

util.lisp (file).

Source

cl-transmission.asd.

Parent Component

src (module).

Packages

cl-transmission.constants.

Public Interface

4.1.4 cl-transmission/src/util.lisp

Source

cl-transmission.asd.

Parent Component

src (module).

Packages

cl-transmission.util.

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 cl-transmission.util

Source

util.lisp.

Use List
  • common-lisp.
  • rutils.readtable.
Used By List
Public Interface
Internals

5.2 cl-transmission.constants

Source

constants.lisp.

Use List
Used By List

cl-transmission.

Public Interface

5.3 cl-transmission

Source

cl-transmission.lisp.

Use List
Public Interface
Internals

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


6.1 Public Interface


6.1.1 Constants

Constant: +default-optimizations+
Package

cl-transmission.constants.

Source

constants.lisp.

Constant: +transmission-add-params+
Package

cl-transmission.constants.

Source

constants.lisp.

Constant: +transmission-get-params+
Package

cl-transmission.constants.

Source

constants.lisp.

Constant: +transmission-set-params+
Package

cl-transmission.constants.

Source

constants.lisp.


6.1.2 Macros

Macro: defclass-export (exported-name args &body body)
Package

cl-transmission.util.

Source

util.lisp.

Macro: defgeneric-export (exported-name args &body body)
Package

cl-transmission.util.

Source

util.lisp.

Macro: define-condition-export (exported-name args &body body)
Package

cl-transmission.util.

Source

util.lisp.

Macro: define-constant-export (exported-name args &body body)
Package

cl-transmission.util.

Source

util.lisp.

Macro: defmacro-export (exported-name args &body body)
Package

cl-transmission.util.

Source

util.lisp.

Macro: defun-export (exported-name args &body body)
Package

cl-transmission.util.

Source

util.lisp.


6.1.3 Ordinary functions

Function: contains-key (key hash-table)
Package

cl-transmission.util.

Source

util.lisp.

Function: make-keyword (str)
Package

cl-transmission.util.

Source

util.lisp.

Function: plist-to-hash-table (plist &rest rest &key convert-key convert-value &allow-other-keys)
Package

cl-transmission.util.

Source

util.lisp.

Function: string->keyword (string)
Package

cl-transmission.util.

Source

util.lisp.


6.1.4 Generic functions

Generic Function: transmission-add (connection &key cookies download-dir filename metainfo paused peer-limit bandwidth-priority files-wanted files-unwanted priority-high priority-low priority-normal &allow-other-keys)

Add a new torrent specified the given fields.

The torrent is given in "METAINFO" or "FILENAME". "METAINFO" should be a base64-encoded torrent file while "FILENAME" should be a filename of torrent file or a magnet link. For the other options and more detailed descriptions see the rpc specifications.

The first return value is a hash-table with fields for the id, ":ID", name, ":NAME" and hash string, ":HASH-STRING", of the added torrent. The second return value is ":TORRENT-ADDED" if a new torrent was added and ":TORRENT-DUPLICATE" if no new torrent was added.

Package

cl-transmission.

Source

cl-transmission.lisp.

Methods
Method: transmission-add ((conn transmission-connection) &rest all-keys &key &allow-other-keys)
Generic Function: transmission-get (connection fields &key ids strict)

Get the fields specified in "FIELDS" for the given "IDS".

"IDS" should be a list of torrent designators, where a torrent designator is a torrent-id or a torrent sha1 string, or it should be ":ALL" to set this value for all the torrents on the server.

The specified fields should be a sequence of keywords, if "STRICT" is non NIL we will check if it does not contain any illegal keywords. All legal keywords are specified in "CL-TRANSMISSION.CONSTANTS:+TRANSMISSION-GET-PARAMS+"

The first return value is a list of active torrents. The second return value is a list of removed torrents. Torrents are represented by a hash-table containing the specified fiels normalized as keywords.

Package

cl-transmission.

Source

cl-transmission.lisp.

Methods
Method: transmission-get ((conn transmission-connection) fields &key ids strict)
Generic Function: transmission-reannounce (connection ids)

Ask the tracker for more peers for the given torrents.

The torrents are specified by "IDS", which should be a list of torrent designators, a torrent designator is a torrent-id or a torrent sha1 string, or it should be the string "recently-active" (case sensitive).

This function will return nothing of value.

Package

cl-transmission.

Source

cl-transmission.lisp.

Methods
Method: transmission-reannounce ((conn transmission-connection) ids)
Generic Function: transmission-remove (connection &key ids delete-local-data)

Remove the torrents with the given "IDS" and maybe delete the local data.

"IDS" should be a list of torrent designators, where a torrent designator is a torrent-id or a torrent sha1 string, or it should be the string "recently-active" (case sensitive).

"DELETE-LOCAL-DATA" should parse to a json boolean. "NIL" will be converted to ":FALSE" which will parse the false boolean in json.

This function does not return anything useful.

Package

cl-transmission.

Source

cl-transmission.lisp.

Methods
Method: transmission-remove ((conn transmission-connection) &key ids delete-local-data)
Generic Function: transmission-rename-path (connection id path name)

Rename the "PATH" of given torrent by "ID" to "NAME"

The "ID" should be a torrent id, sha1 hash string or the string "recently-active" (case sensitive).

The torrents "PATH" will be renamed to "NAME", some examples (modified from transmission.h):

Consider a torrent, with id 0, which has two files with the names "frobnitz-linux/checksum" and "frobnitz-linux/frobnitz.iso".

If we would call "(TRANSMISSION-RENAME-PATH 0 "frobnitz-linux", "foo")" then the "frobnitz-linux" folder will be renamed to "foo" in both torrents. However if we would call "(TRANSMISSION-RENAME-PATH 0 "frobnitz-linux/checksum", "foo")" then only "frobnitz-linux/checksum" will be renamed to "frobnitz-linux/foo" while "frobnitz-linux/frobnitz.iso" will remain unchanged.

This value does not return anything value.

Package

cl-transmission.

Source

cl-transmission.lisp.

Methods
Method: transmission-rename-path ((conn transmission-connection) id path name)
Generic Function: transmission-set (connection ids &key bandwidth-priority download-limit download-limited files-wanted files-unwanted honors-session-limits location peer-limit priority-high priority-low priority-normal queue-position seed-idle-limit seed-idle-mode seed-ratio-limit seed-ratio-mode tracker-add tracker-remove tracker-replace upload-limit upload-limited &allow-other-keys)

Set the specified key to the given value for the given "IDS".

"IDS" should be a list of torrent designators, where a torrent designator is a torrent-id or a torrent sha1 string, or it should be ":ALL" to set this value for all the torrents on the server.

For the exact meaning of the keys see the rpc spec. Please note that leaving a key unspecified is not the same as passing an empty array. Also note that passing "NIL" will result in sending an empty array, not the boolean "false". To send the boolean "false" pass ":FALSE" as keyword.

This function will return nothing of value.

Package

cl-transmission.

Source

cl-transmission.lisp.

Methods
Method: transmission-set ((conn transmission-connection) ids &rest all-keys &key &allow-other-keys)
Generic Function: transmission-set-location (connection ids location &optional move)

Move the "IDS" to the new "LOCATION" moving the old if "MOVE" is true.

"IDS" should be a list of torrent designators, where a torrent designator is a torrent-id or a torrent sha1 string, or it should be the string "recently-active" (case sensitive).

"LOCATION" is the new location of the specified torrents. It should parse to a json string by jonathan.

"MOVE" should parse to a json boolean. "NIL" will be converted to ":FALSE" which will parse the false boolean in json.

This function does not return anything of value.

Package

cl-transmission.

Source

cl-transmission.lisp.

Methods
Method: transmission-set-location ((conn transmission-connection) ids location &optional move)
Generic Function: transmission-start (connection ids)

Start the given torrents by adding them to the appropriate queue.

The torrents are specified by "IDS", which should be a list of torrent designators, a torrent designator is a torrent-id or a torrent sha1 string, or it should be the string "recently-active" (case sensitive).

This function will return nothing of value.

Package

cl-transmission.

Source

cl-transmission.lisp.

Methods
Method: transmission-start ((conn transmission-connection) ids)
Generic Function: transmission-start-now (connection ids)

Start the given torrents directly bypassing the queues.

The torrents are specified by "IDS", which should be a list of torrent designators, a torrent designator is a torrent-id or a torrent sha1 string, or it should be the string "recently-active" (case sensitive).

This function will return nothing of value.

Package

cl-transmission.

Source

cl-transmission.lisp.

Methods
Method: transmission-start-now ((conn transmission-connection) ids)
Generic Function: transmission-stop (connection ids)

Stop (pause) the given torrents.

The torrents are specified by "IDS", which should be a list of torrent designators, a torrent designator is a torrent-id or a torrent sha1 string, or it should be the string "recently-active" (case sensitive).

This function will return nothing of value.

Package

cl-transmission.

Source

cl-transmission.lisp.

Methods
Method: transmission-stop ((conn transmission-connection) ids)
Generic Function: transmission-verify (connection ids)

Queue the given torrents for verification.

The torrents are specified by "IDS", which should be a list of torrent designators, a torrent designator is a torrent-id or a torrent sha1 string, or it should be the string "recently-active" (case sensitive).

This function will return nothing of value.

Package

cl-transmission.

Source

cl-transmission.lisp.

Methods
Method: transmission-verify ((conn transmission-connection) ids)

6.1.5 Conditions

Condition: transmission-error

The general error used when we could not complete the request to the transmission server.

Package

cl-transmission.

Source

cl-transmission.lisp.

Direct superclasses

error.

Direct methods

transmission-error-response.

Direct slots
Slot: response
Initargs

:response

Readers

transmission-error-response.

Writers

This slot is read-only.


6.1.6 Classes

Class: transmission-connection
Package

cl-transmission.

Source

cl-transmission.lisp.

Direct methods
Direct slots
Slot: protocol

The protocol to use to contact the server probably "http" or "https".

Type

string

Initform

"http"

Initargs

:protocol

Slot: host

The host of the transmission server.

Type

string

Initform

"localhost"

Initargs

:host

Slot: port

The port of the transmission server.

Type

cl-transmission::port-number

Initform

9091

Initargs

:port

Slot: url

The part of the url of the transmission server after the port.

Type

string

Initform

"transmission/rpc"

Initargs

:url

Slot: credentials

he basic authentication for the transmission server. Use NIL if no auth is needed.

Type

(or null list)

Initargs

:credentials

Slot: session-id

The current "X-Transmission-Session-Id" used by the transmission server.

Type

string

Initform

""


6.2 Internals


6.2.1 Macros

Macro: def-torrent-action-request (action &optional docstring)
Package

cl-transmission.

Source

cl-transmission.lisp.

Macro: def-torrent-request (method lambda-list (&key ignore-keys-p) &body body)
Package

cl-transmission.

Source

cl-transmission.lisp.

Macro: define-export-macro (type)
Package

cl-transmission.util.

Source

util.lisp.

Macro: the-check (type val)
Package

cl-transmission.util.

Source

util.lisp.


6.2.2 Ordinary functions

Function: %transmission-request (conn method arguments)
Package

cl-transmission.

Source

cl-transmission.lisp.

Function: get-transmission-host (conn)
Package

cl-transmission.

Source

cl-transmission.lisp.

Function: keyword-all-p (keyword)
Package

cl-transmission.

Source

cl-transmission.lisp.

Function: no-duplicates-p (item)
Package

cl-transmission.

Source

cl-transmission.lisp.

Function: transmission-request (conn method arguments)
Package

cl-transmission.

Source

cl-transmission.lisp.

Function: update-session-id (conn headers)
Package

cl-transmission.

Source

cl-transmission.lisp.

Function: valid-torrent-add-keys-p (item)
Package

cl-transmission.

Source

cl-transmission.lisp.

Function: valid-torrent-get-keys-p (item)
Package

cl-transmission.

Source

cl-transmission.lisp.


6.2.3 Generic functions

Generic Reader: transmission-error-response (condition)
Package

cl-transmission.

Methods
Reader Method: transmission-error-response ((condition transmission-error))
Source

cl-transmission.lisp.

Target Slot

response.


6.2.4 Types

Type: port-number ()
Package

cl-transmission.

Source

cl-transmission.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %  
C   D   F   G   K   M   N   P   S   T   U   V  
Index Entry  Section

%
%transmission-request: Private ordinary functions

C
contains-key: Public ordinary functions

D
def-torrent-action-request: Private macros
def-torrent-request: Private macros
defclass-export: Public macros
defgeneric-export: Public macros
define-condition-export: Public macros
define-constant-export: Public macros
define-export-macro: Private macros
defmacro-export: Public macros
defun-export: Public macros

F
Function, %transmission-request: Private ordinary functions
Function, contains-key: Public ordinary functions
Function, get-transmission-host: Private ordinary functions
Function, keyword-all-p: Private ordinary functions
Function, make-keyword: Public ordinary functions
Function, no-duplicates-p: Private ordinary functions
Function, plist-to-hash-table: Public ordinary functions
Function, string->keyword: Public ordinary functions
Function, transmission-request: Private ordinary functions
Function, update-session-id: Private ordinary functions
Function, valid-torrent-add-keys-p: Private ordinary functions
Function, valid-torrent-get-keys-p: Private ordinary functions

G
Generic Function, transmission-add: Public generic functions
Generic Function, transmission-error-response: Private generic functions
Generic Function, transmission-get: Public generic functions
Generic Function, transmission-reannounce: Public generic functions
Generic Function, transmission-remove: Public generic functions
Generic Function, transmission-rename-path: Public generic functions
Generic Function, transmission-set: Public generic functions
Generic Function, transmission-set-location: Public generic functions
Generic Function, transmission-start: Public generic functions
Generic Function, transmission-start-now: Public generic functions
Generic Function, transmission-stop: Public generic functions
Generic Function, transmission-verify: Public generic functions
get-transmission-host: Private ordinary functions

K
keyword-all-p: Private ordinary functions

M
Macro, def-torrent-action-request: Private macros
Macro, def-torrent-request: Private macros
Macro, defclass-export: Public macros
Macro, defgeneric-export: Public macros
Macro, define-condition-export: Public macros
Macro, define-constant-export: Public macros
Macro, define-export-macro: Private macros
Macro, defmacro-export: Public macros
Macro, defun-export: Public macros
Macro, the-check: Private macros
make-keyword: Public ordinary functions
Method, transmission-add: Public generic functions
Method, transmission-error-response: Private generic functions
Method, transmission-get: Public generic functions
Method, transmission-reannounce: Public generic functions
Method, transmission-remove: Public generic functions
Method, transmission-rename-path: Public generic functions
Method, transmission-set: Public generic functions
Method, transmission-set-location: Public generic functions
Method, transmission-start: Public generic functions
Method, transmission-start-now: Public generic functions
Method, transmission-stop: Public generic functions
Method, transmission-verify: Public generic functions

N
no-duplicates-p: Private ordinary functions

P
plist-to-hash-table: Public ordinary functions

S
string->keyword: Public ordinary functions

T
the-check: Private macros
transmission-add: Public generic functions
transmission-add: Public generic functions
transmission-error-response: Private generic functions
transmission-error-response: Private generic functions
transmission-get: Public generic functions
transmission-get: Public generic functions
transmission-reannounce: Public generic functions
transmission-reannounce: Public generic functions
transmission-remove: Public generic functions
transmission-remove: Public generic functions
transmission-rename-path: Public generic functions
transmission-rename-path: Public generic functions
transmission-request: Private ordinary functions
transmission-set: Public generic functions
transmission-set: Public generic functions
transmission-set-location: Public generic functions
transmission-set-location: Public generic functions
transmission-start: Public generic functions
transmission-start: Public generic functions
transmission-start-now: Public generic functions
transmission-start-now: Public generic functions
transmission-stop: Public generic functions
transmission-stop: Public generic functions
transmission-verify: Public generic functions
transmission-verify: Public generic functions

U
update-session-id: Private ordinary functions

V
valid-torrent-add-keys-p: Private ordinary functions
valid-torrent-get-keys-p: Private ordinary functions


A.4 Data types