.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Transmission::Client 3pm"
.TH Transmission::Client 3pm "2022-10-16" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Transmission::Client \- Interface to Transmission
.SH "VERSION"
.IX Header "VERSION"
0.0806
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Transmission::Client is the main module in a collection of modules
to communicate with Transmission. Transmission is a cross-platform
BitTorrent client that is:
.IP "\(bu" 4
Easy
.IP "\(bu" 4
Lean
.IP "\(bu" 4
Native
.IP "\(bu" 4
Powerful
.IP "\(bu" 4
Free
.PP
If you want to communicate with \*(L"transmission-daemon\*(R", this is a module
which can help you with that.
.PP
The documentation is half copy/paste from the Transmission \s-1RPC\s0 spec:
<https://trac.transmissionbt.com/browser/trunk/extras/rpc\-spec.txt>
.PP
This module differs from P2P::Transmission in (at least) two ways:
This one use Moose and it won't die. The latter is especially
annoying in the constructor.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Transmission::Client;
\&
\& my $client = Transmission::Client\->new;
\& my $torrent_id = 2;
\& my $data = base64_encoded_data();
\&
\& $client\->add(metainfo => $data) or confess $client\->error;
\& $client\->remove($torrent_id) or confess $client\->error;
\&
\& for my $torrent (@{ $client\->torrents }) {
\&    print $torrent\->name, "\en";
\&    for my $file (@{ $torrent\->files }) {
\&        print "> ", $file\->name, "\en";
\&    }
\& }
\&
\& print $client\->session\->download_dir, "\en";
.Ve
.SH "FAULT HANDLING"
.IX Header "FAULT HANDLING"
In \f(CW0.06\fR Transmission::Client can be constructed with \*(L"autodie\*(R" set
to true, to make this object confess instead of just setting \*(L"error\*(R".
Example:
.PP
.Vb 1
\&    my $client = Transmission::Client\->new(autodie => 1);
\&
\&    eval {
\&        $self\->add(filename => \*(Aqfoo.torrent\*(Aq);
\&    } or do {
\&        # add() failed...
\&    };
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Transmission::AttributeRole
Transmission::Session
Transmission::Torrent
Transmission::Utils
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "url"
.IX Subsection "url"
.Vb 1
\& $str = $self\->url;
.Ve
.PP
Returns an \s-1URL\s0 to where the Transmission rpc api is.
Default value is \*(L"http://localhost:9091/transmission/rpc\*(R";
.SS "error"
.IX Subsection "error"
.Vb 1
\& $str = $self\->error;
.Ve
.PP
Returns the last error known to the object. All methods can return
empty list in addition to what specified. Check this attribute if so happens.
.PP
Like \*(L"autodie\*(R"? Create your object with \f(CW\*(C`autodie\*(C'\fR set to true and this
module will throw exceptions in addition to setting this variable.
.SS "username"
.IX Subsection "username"
.Vb 1
\& $str = $self\->username;
.Ve
.PP
Used to authenticate against Transmission.
.SS "password"
.IX Subsection "password"
.Vb 1
\& $str = $self\->password;
.Ve
.PP
Used to authenticate against Transmission.
.SS "timeout"
.IX Subsection "timeout"
.Vb 1
\& $int = $self\->timeout;
.Ve
.PP
Number of seconds to wait for \s-1RPC\s0 response.
.SS "session"
.IX Subsection "session"
.Vb 2
\& $session_obj = $self\->session;
\& $stats_obj = $self\->stats;
.Ve
.PP
Returns an instance of Transmission::Session.
\&\f(CW\*(C`stats()\*(C'\fR is a proxy method on \*(L"session\*(R".
.SS "torrents"
.IX Subsection "torrents"
.Vb 2
\& $array_ref = $self\->torrents;
\& $self\->clear_torrents;
.Ve
.PP
Returns an array-ref of Transmission::Torrent objects. Default value
is a full list of all known torrents, with as little data as possible read
from Transmission. This means that each request on a attribute on an object
will require a new request to Transmission. See \*(L"read_torrents\*(R" for more
information.
.SS "version"
.IX Subsection "version"
.Vb 1
\& $str = $self\->version;
.Ve
.PP
Get Transmission version.
.SS "session_id"
.IX Subsection "session_id"
.Vb 2
\& $self\->session_id($str);
\& $str = $self\->session_id;
.Ve
.PP
The session \s-1ID\s0 used to communicate with Transmission.
.SH "METHODS"
.IX Header "METHODS"
.SS "add"
.IX Subsection "add"
.Vb 1
\& $bool = $self\->add(%args);
\&
\& key              | value type | description
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& download_dir     | string     | path to download the torrent to
\& filename         | string     | filename or URL of the .torrent file
\& metainfo         | string     | torrent content
\& paused           | boolean    | if true, don\*(Aqt start the torrent
\& peer_limit       | number     | maximum number of peers
.Ve
.PP
Either \*(L"filename\*(R" or \*(L"metainfo\*(R" \s-1MUST\s0 be included. All other arguments are
optional.
.PP
See \*(L"3.4 Adding a torrent\*(R" from
<https://trac.transmissionbt.com/browser/trunk/extras/rpc\-spec.txt>
.SS "remove"
.IX Subsection "remove"
.Vb 1
\& $bool = $self\->remove(%args);
\&
\& key                | value type | description
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& ids                | array      | torrent list, as described in 3.1
\& delete_local_data  | boolean    | delete local data. (default: false)
.Ve
.PP
\&\f(CW\*(C`ids\*(C'\fR can also be the string \*(L"all\*(R". \f(CW\*(C`ids\*(C'\fR is required.
.PP
See \*(L"3.4 Removing a torrent\*(R" from
<https://trac.transmissionbt.com/browser/trunk/extras/rpc\-spec.txt>
.SS "move"
.IX Subsection "move"
.Vb 1
\& $bool = $self\->move(%args);
\&
\&
\& string      | value type | description
\& \-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& ids         | array      | torrent list, as described in 3.1
\& location    | string     | the new torrent location
\& move        | boolean    | if true, move from previous location.
\&             |            | otherwise, search "location" for files
.Ve
.PP
\&\f(CW\*(C`ids\*(C'\fR can also be the string \*(L"all\*(R". \f(CW\*(C`ids\*(C'\fR and \f(CW\*(C`location\*(C'\fR is required.
.PP
See \*(L"3.5 moving a torrent\*(R" from
<https://trac.transmissionbt.com/browser/trunk/extras/rpc\-spec.txt>
.SS "start"
.IX Subsection "start"
.Vb 1
\& $bool = $self\->start($ids);
.Ve
.PP
Will start one or more torrents.
\&\f(CW$ids\fR can be a single int, an array of ints or the string \*(L"all\*(R".
.SS "stop"
.IX Subsection "stop"
.Vb 1
\& $bool = $self\->stop($ids);
.Ve
.PP
Will stop one or more torrents.
\&\f(CW$ids\fR can be a single int, an array of ints or the string \*(L"all\*(R".
.SS "verify"
.IX Subsection "verify"
.Vb 1
\& $bool = $self\->stop($ids);
.Ve
.PP
Will verify one or more torrents.
\&\f(CW$ids\fR can be a single int, an array of ints or the string \*(L"all\*(R".
.SS "read_torrents"
.IX Subsection "read_torrents"
.Vb 2
\& @list = $self\->read_torrents(%args);
\& $array_ref = $self\->read_torrents(%args);
\&
\& key         | value type | description
\& \-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& ids         | array      | optional torrent list, as described in 3.1.
\& lazy_read   |            | will create objects with as little data as possible.
.Ve
.IP "List context" 4
.IX Item "List context"
Returns a list of Transmission::Torrent objects and sets the \*(L"torrents\*(R"
attribute.
.IP "Scalar context" 4
.IX Item "Scalar context"
Returns an array-ref of Transmission::Torrent.
.SS "rpc"
.IX Subsection "rpc"
.Vb 1
\& $any = $self\->rpc($method, %args);
.Ve
.PP
Communicate with backend. This methods is meant for internal use.
.SS "read_all"
.IX Subsection "read_all"
.Vb 1
\& 1 == $self\->read_all;
.Ve
.PP
This method will try to populate \s-1ALL\s0 torrent, session and stats information,
using three requests.
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
.SH "COPYRIGHT AND AUTHORS"
.IX Header "COPYRIGHT AND AUTHORS"
Copyright 2009\-2019 by Transmission::Client contributors
.PP
See \f(CW\*(C`git log \-\-format="%aN <%aE>" | sort | uniq\*(C'\fR in the git repository
for the reference list of contributors.
.SS "\s-1CONTRIBUTORS\s0"
.IX Subsection "CONTRIBUTORS"
.IP "\(bu" 4
Jan Henning Thorsen (original author)
.IP "\(bu" 4
Olof Johansson (current maintainer)
.IP "\(bu" 4
Andrew Fresh
.IP "\(bu" 4
Yanick Champoux