blib/lib/AnyEvent/FCP.pm

filter: Statementstmt 11.8% 37 / 313 Branchbran 0.0% 0 / 120 Conditioncond 0.0% 0 / 29 MC/DCmcdc 0.0% 0 / 18 Subroutinesub 9.2% 7 / 76 Podpod 9.0% 1 / 11 totaltotal 7.9% 45 / 567 CC 76 SCAR 34.1
CC
76
Cov
8%
__ANON__
132.0
__ANON__
132.0
recv
72.0
CRAP 30.4
↑ Summary
1 =head1 NAME
2  
3 AnyEvent::FCP - freenet client protocol 2.0
4  
5 =head1 SYNOPSIS
6  
7 use AnyEvent::FCP;
8  
9 my $fcp = new AnyEvent::FCP;
10  
11 # transactions return condvars
12 my $lp_cv = $fcp->list_peers;
13 my $pr_cv = $fcp->list_persistent_requests;
14  
15 my $peers = $lp_cv->recv;
16 my $reqs = $pr_cv->recv;
17  
18 =head1 DESCRIPTION
19  
20 This module implements the freenet client protocol version 2.0, as used by
21 freenet 0.7. See L<Net::FCP> for the earlier freenet 0.5 version.
22  
23 See L<http://wiki.freenetproject.org/FreenetFCPSpec2Point0> for a
24 description of what the messages do.
25  
26 The module uses L<AnyEvent> to find a suitable event module.
27  
28 Only very little is implemented, ask if you need more, and look at the
29 example program later in this section.
30  
31 =head2 EXAMPLE
32  
33 This example fetches the download list and sets the priority of all files
34 with "a" in their name to "emergency":
35  
36 use AnyEvent::FCP;
37  
38 my $fcp = new AnyEvent::FCP;
39  
40 $fcp->watch_global (1, 0);
41 my $req = $fcp->list_persistent_requests;
42  
43 TODO
44 for my $req (values %$req) {
45 if ($req->{filename} =~ /a/) {
46 $fcp->modify_persistent_request (1, $req->{identifier}, undef, 0);
47 }
48 }
49  
50 =head2 IMPORT TAGS
51  
52 Nothing much can be "imported" from this module right now.
53  
54 =head1 THE AnyEvent::FCP CLASS
55  
56 =over 4
57  
58 =cut
59  
60 package AnyEvent::FCP;
61  
62 1 ▶use common::sense;
Subroutine BEGIN: called CC=1 SCAR=0.0
63  
64 1 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
65  
66 1 our $VERSION = 0.5;
67  
68 1 ▶use Scalar::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
69  
70 1 ▶use AnyEvent;
Subroutine BEGIN: called CC=1 SCAR=0.0
71 1 ▶use AnyEvent::Handle;
Subroutine BEGIN: called CC=1 SCAR=0.0
72 1 ▶use AnyEvent::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
73  
74 1 our %TOLC; # tolc cache
75  
76 0 ▶sub touc($) {
Subroutine touc: not called CC=2 SCAR=17.9
Pod undocumented
77 0 local $_ = shift;
78 0 ▶ 1 while s/((?:^|_)(?:svk|chk|uri|fcp|ds|mime|dda)(?:_|$))/\U$1/;
Branch: 1 branch
BranchTrueFalseTotal
s/((?:^|_)(?:svk|chk|uri|fcp|ds|mime|dda)(?:_|$))/\U$1\E/u and do { '???' } 0 0 0
79 0 s/(?:^|_)(.)/\U$1/g;
80 0 $_
81 }
82  
83 0 ▶sub tolc($) {
Subroutine tolc: not called CC=3 SCAR=24.8
Pod undocumented
84 0 local $_ = shift;
85 0 ▶ 1 while s/(SVK|CHK|URI|FCP|DS|MIME|DDA)([^_])/$1\_$2/;
Branch: 1 branch
BranchTrueFalseTotal
s/(SVK|CHK|URI|FCP|DS|MIME|DDA)([^_])/$1_$2/u and do { '???' } 0 0 0
86 0 ▶ 1 while s/([^_])(SVK|CHK|URI|FCP|DS|MIME|DDA)/$1\_$2/;
Branch: 1 branch
BranchTrueFalseTotal
s/([^_])(SVK|CHK|URI|FCP|DS|MIME|DDA)/$1_$2/u and do { '???' } 0 0 0
87 0 s/(?<=[a-z])(?=[A-Z])/_/g;
88 lc
89 0 }
90  
91 =item $fcp = new AnyEvent::FCP key => value...;
92  
93 Create a new FCP connection to the given host and port (default
94 127.0.0.1:9481, or the environment variables C<FREDHOST> and C<FREDPORT>).
95  
96 If no C<name> was specified, then AnyEvent::FCP will generate a
97 (hopefully) unique client name for you.
98  
99 The following keys can be specified (they are all optional):
100  
101 =over 4
102  
103 =item name => $string
104  
105 A unique name to identify this client. If none is specified, a randomly
106 generated name will be used.
107  
108 =item host => $hostname
109  
110 The hostname or IP address of the freenet node. Default is C<$ENV{FREDHOST}>
111 or C<127.0.0.1>.
112  
113 =item port => $portnumber
114  
115 The port number of the FCP port. Default is C<$ENV{FREDPORT}> or C<9481>.
116  
117 =item timeout => $seconds
118  
119 The timeout, in seconds, after which a connection error is assumed when
120 there is no activity. Default is C<7200>, i.e. two hours.
121  
122 =item keepalive => $seconds
123  
124 The interval, in seconds, at which keepalive messages will be
125 sent. Default is C<540>, i.e. nine minutes.
126  
127 These keepalive messages are useful both to detect that a connection is
128 no longer working and to keep any (home) routers from expiring their
129 masquerading entry.
130  
131 =item on_eof => $callback->($fcp)
132  
133 Invoked when the underlying L<AnyEvent::Handle> signals EOF, currently
134 regardless of whether the EOF was expected or not.
135  
136 =item on_error => $callback->($fcp, $message)
137  
138 Invoked on any (fatal) errors, such as unexpected connection close. The
139 callback receives the FCP object and a textual error message.
140  
141 =item on_failure => $callback->($fcp, $type, $backtrace, $args, $error)
142  
143 Invoked when an FCP request fails that didn't have a failure callback. See
144 L<FCP REQUESTS> for details.
145  
146 =back
147  
148 =cut
149  
150 0 ▶sub new {
Subroutine new: not called CC=3 SCAR=24.8
Pod documented
151 0 my $class = shift;
152  
153 0 my $rand = join "", map chr 0x21 + rand 94, 1..40; # ~ 262 bits entropy
154  
155 my $self = bless {
156 host => $ENV{FREDHOST} || "127.0.0.1",
157 0 ▶ port => $ENV{FREDPORT} || 9481,
Condition0%0/4
$ENV{'FREDHOST'} || '127.0.0.1'
l!l
00
$ENV{'FREDPORT'} || 9481
l!l
00
MC/DC0%0/1
$ENV{'FREDHOST'} || '127.0.0.1'
$ENV{'FREDHOST'}
MC/DC0%0/1
$ENV{'FREDPORT'} || 9481
$ENV{'FREDPORT'}
Truth table0%0/2
A
A= $ENV{'FREDHOST'}
Aresult
11
00
Truth table0%0/2
A
A= $ENV{'FREDPORT'}
Aresult
11
00
158 timeout => 3600 * 2,
159 keepalive => 9 * 60,
160 name => time.rand.rand.rand, # lame
161 @_,
162 queue => [],
163 req => {},
164 prefix => "..:aefcpid:$rand:",
165 idseq => "a0",
166 }, $class;
167  
168 {
169 0 Scalar::Util::weaken (my $self = $self);
170  
171 0 ▶ $self->{kw} = AE::timer $self->{keepalive}, $self->{keepalive}, sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
172 0 $self->{hdl}->push_write ("\n");
173 0 };
174  
175 0 our $ENDMESSAGE = qr<\012(EndMessage|Data)\012>;
176  
177 # these are declared here for performance reasons
178 0 my ($k, $v, $type);
179 0 my $rdata;
180
181 0 ▶ my $on_read = sub {
Subroutine __ANON__: not called CC=11 SCAR=48.8
182 0 my ($hdl) = @_;
183  
184 # we only carve out whole messages here
185 0 ▶ while ($hdl->{rbuf} =~ /\012(EndMessage|Data)\012/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($hdl->{"rbuf"} =~ /\012(EndMessage|Data)\012/u) 0 0 0
186 # remember end marker
187 0 ▶ $rdata = $1 eq "Data"
Branch: 1 branch
BranchTrueFalseTotal
$rdata = $1 eq "Data" or $1 eq "EndMessage" or return $self->fatal("protocol error, expected message end, got $1\n") 0 0 0
Condition0%0/3
$rdata = $1 eq "Data" or $1 eq "EndMessage"
l!l&&r!l&&!r
000
MC/DC0%0/2
$rdata = $1 eq "Data" or $1 eq "EndMessage"
$rdata = $1 eq "Data" $1 eq "EndMessage"
Truth table0%0/3
A or B
A= $rdata = $1 eq "Data"B= $1 eq "EndMessage"
ABresult
1X1
011
000
188 or $1 eq "EndMessage"
189 or return $self->fatal ("protocol error, expected message end, got $1\n");
190  
191 0 my @lines = split /\012/, substr $hdl->{rbuf}, 0, $-[0];
192  
193 0 substr $hdl->{rbuf}, 0, $+[0], ""; # remove pkg
194  
195 0 $type = shift @lines;
196 0 ▶ $type = ($TOLC{$type} ||= tolc $type);
Condition0%0/3
$AnyEvent::FCP::TOLC{$type} ||= &tolc($type)
l!l&&r!l&&!r
000
MC/DC0%0/2
$AnyEvent::FCP::TOLC{$type} ||= &tolc($type)
$AnyEvent::FCP::TOLC{$type} &tolc($type)
Truth table0%0/3
A ||= B
A= $AnyEvent::FCP::TOLC{$type}B= &tolc($type)
ABresult
1X1
011
000
197  
198 0 my %kv;
199  
200 0 for (@lines) {
201 0 ($k, $v) = split /=/, $_, 2;
202 0 ▶ $k = ($TOLC{$k} ||= tolc $k);
Condition0%0/3
$AnyEvent::FCP::TOLC{$k} ||= &tolc($k)
l!l&&r!l&&!r
000
MC/DC0%0/2
$AnyEvent::FCP::TOLC{$k} ||= &tolc($k)
$AnyEvent::FCP::TOLC{$k} &tolc($k)
Truth table0%0/3
A ||= B
A= $AnyEvent::FCP::TOLC{$k}B= &tolc($k)
ABresult
1X1
011
000
203
204 0 ▶ if ($k =~ /\./) {
Branch: 1 branch
BranchTrueFalseTotal
if ($k =~ /\./u) 0 0 0
205 # generic, slow case
206 0 my @k = split /\./, $k;
207 0 my $ro = \\%kv;
208  
209 0 ▶ while (@k) {
Branch: 1 branch
BranchTrueFalseTotal
if (@k) 0 0 0
210 0 $k = shift @k;
211 0 ▶ if ($k =~ /^\d+$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($k =~ /^\d+$/u) { } 0 0 0
212 0 $ro = \$$ro->[$k];
213 } else {
214 0 $ro = \$$ro->{$k};
215 }
216 }
217  
218 0 $$ro = $v;
219  
220 0 next;
221 }
222  
223 # special comon case, for performance only
224 0 $kv{$k} = $v;
225 }
226
227 0 ▶ if ($rdata) {
Branch: 1 branch
BranchTrueFalseTotal
if ($rdata) { } 0 0 0
228 0 ▶ $_[0]->push_read (chunk => delete $kv{data_length}, sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
229 0 $rdata = \$_[1];
230 0 $self->recv ($type, \%kv, $rdata);
231 0 });
232  
233 0 last; # do not tgry to parse more messages
234 } else {
235 0 $self->recv ($type, \%kv);
236 }
237 }
238 0 };
239  
240 $self->{hdl} = new AnyEvent::Handle
241 connect => [$self->{host} => $self->{port}],
242 timeout => $self->{timeout},
243 on_read => $on_read,
244 0 ▶ on_eof => sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
245 0 ▶ if ($self->{on_eof}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{'on_eof'}) { } 0 0 0
246 0 $self->{on_eof}($self);
247 } else {
248 0 $self->fatal ("EOF");
249 }
250 },
251 0 ▶ on_error => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
252 0 $self->fatal ($_[2]);
253 },
254 0 ;
255  
256 0 Scalar::Util::weaken ($self->{hdl}{fcp} = $self);
257 }
258  
259 $self->send_msg (client_hello =>
260 name => $self->{name},
261 0 expected_version => "2.0",
262 );
263  
264 0 $self
265 }
266  
267 0 ▶sub fatal {
Subroutine fatal: not called CC=2 SCAR=17.9
Pod undocumented
268 0 my ($self, $msg) = @_;
269  
270 0 $self->{hdl}->shutdown;
271 0 delete $self->{kw};
272
273 0 ▶ if ($self->{on_error}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{'on_error'}) { } 0 0 0
274 0 $self->{on_error}->($self, $msg);
275 } else {
276 0 die $msg;
277 }
278 }
279  
280 0 ▶sub identifier {
Subroutine identifier: not called CC=1 SCAR=6.9
Pod undocumented
281 $_[0]{prefix} . ++$_[0]{idseq}
282 0 }
283  
284 0 ▶sub send_msg {
Subroutine send_msg: not called CC=4 SCAR=30.0
Pod undocumented
285 0 my ($self, $type, %kv) = @_;
286  
287 0 my $data = delete $kv{data};
288  
289 0 ▶ if (exists $kv{id_cb}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $kv{"id_cb"}) 0 0 0
290 0 ▶ my $id = $kv{identifier} ||= $self->identifier;
Condition0%0/3
$kv{"identifier"} ||= $self->identifier
l!l&&r!l&&!r
000
MC/DC0%0/2
$kv{"identifier"} ||= $self->identifier
$kv{"identifier"} $self->identifier
Truth table0%0/3
A ||= B
A= $kv{"identifier"}B= $self->identifier
ABresult
1X1
011
000
291 0 $self->{id}{$id} = delete $kv{id_cb};
292 }
293  
294 0 my $msg = (touc $type) . "\012"
295 . join "", map +(touc $_) . "=$kv{$_}\012", keys %kv;
296  
297 0 ▶ sub id {
Subroutine id: not called CC=1 SCAR=6.9
Pod undocumented
298 0 my ($self) = @_;
299  
300  
301 }
302  
303 0 ▶ if (defined $data) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $data) { } 0 0 0
304 0 $msg .= "DataLength=" . (length $data) . "\012"
305 . "Data\012$data";
306 } else {
307 0 $msg .= "EndMessage\012";
308 }
309  
310 0 $self->{hdl}->push_write ($msg);
311 }
312  
313 0 ▶sub on {
Subroutine on: not called CC=1 SCAR=6.9
Pod undocumented
314 0 my ($self, $cb) = @_;
315  
316 # cb return undef - message eaten, remove cb
317 # cb return 0 - message eaten
318 # cb return 1 - pass to next
319  
320 0 push @{ $self->{on} }, $cb;
321 }
322  
323 0 ▶sub _push_queue {
Subroutine _push_queue: not called CC=2 SCAR=17.9
324 0 my ($self, $queue) = @_;
325  
326 0 shift @$queue;
327 0 ▶ $queue->[0]($self, AnyEvent::Util::guard { $self->_push_queue ($queue) })
Subroutine __ANON__: not called CC=1 SCAR=6.9
328 0 ▶ if @$queue;
Branch: 1 branch
BranchTrueFalseTotal
if @$queue 0 0 0
329 }
330  
331 # lock so only one $type (arbitrary string) is in flight,
332 # to work around horribly misdesigned protocol.
333 0 ▶sub serialise {
Subroutine serialise: not called CC=3 SCAR=24.8
Pod undocumented
334 0 my ($self, $type, $cb) = @_;
335  
336 0 ▶ my $queue = $self->{serialise}{$type} ||= [];
Condition0%0/2
$self->{"serialise"}{$type} ||= []
l!l
00
MC/DC0%0/1
$self->{"serialise"}{$type} ||= []
$self->{"serialise"}{$type}
Truth table0%0/2
A
A= $self->{"serialise"}{$type}
Aresult
11
00
337 0 push @$queue, $cb;
338 0 ▶ $cb->($self, AnyEvent::Util::guard { $self->_push_queue ($queue) })
Subroutine __ANON__: not called CC=1 SCAR=6.9
339 0 ▶ unless $#$queue;
Branch: 1 branch
BranchTrueFalseTotal
unless $queue->$#* 0 0 0
340 }
341  
342 # how to merge these types into $self->{persistent}
343 our %PERSISTENT_TYPE = (
344 0 ▶ persistent_get => sub { %{ $_[1] } = (type => "persistent_get" , %{ $_[2] }) },
Subroutine __ANON__: not called CC=1 SCAR=6.9
345 0 ▶ persistent_put => sub { %{ $_[1] } = (type => "persistent_put" , %{ $_[2] }) },
Subroutine __ANON__: not called CC=1 SCAR=6.9
346 0 ▶ persistent_put_dir => sub { %{ $_[1] } = (type => "persistent_put_dir", %{ $_[2] }) },
Subroutine __ANON__: not called CC=1 SCAR=6.9
347 0 ▶ persistent_request_modified => sub { %{ $_[1] } = (%{ $_[1] }, %{ $_[2] }) },
Subroutine __ANON__: not called CC=1 SCAR=6.9
348 0 ▶ persistent_request_removed => sub { delete $_[0]{req}{$_[2]{identifier}} },
Subroutine __ANON__: not called CC=1 SCAR=6.9
349  
350 0 ▶ simple_progress => sub { $_[1]{simple_progress} = $_[2] }, # get/put
Subroutine __ANON__: not called CC=1 SCAR=6.9
351  
352 0 ▶ uri_generated => sub { $_[1]{uri_generated} = $_[2] }, # put
Subroutine __ANON__: not called CC=1 SCAR=6.9
353 0 ▶ generated_metadata => sub { $_[1]{generated_metadata} = $_[2] }, # put
Subroutine __ANON__: not called CC=1 SCAR=6.9
354 0 ▶ started_compression => sub { $_[1]{started_compression} = $_[2] }, # put
Subroutine __ANON__: not called CC=1 SCAR=6.9
355 0 ▶ finished_compression => sub { $_[1]{finished_compression} = $_[2] }, # put
Subroutine __ANON__: not called CC=1 SCAR=6.9
356 0 ▶ put_fetchable => sub { $_[1]{put_fetchable} = $_[2] }, # put
Subroutine __ANON__: not called CC=1 SCAR=6.9
357 0 ▶ put_failed => sub { $_[1]{put_failed} = $_[2] }, # put
Subroutine __ANON__: not called CC=1 SCAR=6.9
358 0 ▶ put_successful => sub { $_[1]{put_successful} = $_[2] }, # put
Subroutine __ANON__: not called CC=1 SCAR=6.9
359  
360 0 ▶ sending_to_network => sub { $_[1]{sending_to_network} = $_[2] }, # get
Subroutine __ANON__: not called CC=1 SCAR=6.9
361 0 ▶ compatibility_mode => sub { $_[1]{compatibility_mode} = $_[2] }, # get
Subroutine __ANON__: not called CC=1 SCAR=6.9
362 0 ▶ expected_hashes => sub { $_[1]{expected_hashes} = $_[2] }, # get
Subroutine __ANON__: not called CC=1 SCAR=6.9
363 0 ▶ expected_mime => sub { $_[1]{expected_mime} = $_[2] }, # get
Subroutine __ANON__: not called CC=1 SCAR=6.9
364 0 ▶ expected_data_length => sub { $_[1]{expected_data_length} = $_[2] }, # get
Subroutine __ANON__: not called CC=1 SCAR=6.9
365 0 ▶ get_failed => sub { $_[1]{get_failed} = $_[2] }, # get
Subroutine __ANON__: not called CC=1 SCAR=6.9
366 0 ▶ data_found => sub { $_[1]{data_found} = $_[2] }, # get
Subroutine __ANON__: not called CC=1 SCAR=6.9
367 0 ▶ enter_finite_cooldown => sub { $_[1]{enter_finite_cooldown} = $_[2] }, # get
Subroutine __ANON__: not called CC=1 SCAR=6.9
368 1 );
369  
370 0 ▶sub recv {
Subroutine recv: not called CC=8 SCAR=42.8
Pod undocumented
371 0 my ($self, $type, $kv, @extra) = @_;
372  
373 0 ▶ if (my $cb = $PERSISTENT_TYPE{$type}) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $cb = $AnyEvent::FCP::PERSISTENT_TYPE{$type}) 0 0 0
374 0 my $id = $kv->{identifier};
375 0 ▶ my $req = $_[0]{req}{$id} ||= {};
Condition0%0/2
$_[0]{"req"}{$id} ||= {}
l!l
00
MC/DC0%0/1
$_[0]{"req"}{$id} ||= {}
$_[0]{"req"}{$id}
Truth table0%0/2
A
A= $_[0]{"req"}{$id}
Aresult
11
00
376 0 $cb->($self, $req, $kv);
377 0 $self->recv (request_changed => $kv, $type, @extra);
378 }
379  
380 0 my $on = $self->{on};
381 0 for (0 .. $#$on) {
382 0 ▶ unless (my $res = $on->[$_]($self, $type, $kv, @extra)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (my $res = $on->[$_]->($self, $type, $kv, @extra)) 0 0 0
383 0 ▶ splice @$on, $_, 1 unless defined $res;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $res 0 0 0
384 0 return;
385 }
386 }
387  
388 0 ▶ if (my $cb = $self->{queue}[0]) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $cb = $self->{'queue'}[0]) { } 0 0 0
389 $cb->($self, $type, $kv, @extra)
390 0 ▶ and shift @{ $self->{queue} };
Branch: 1 branch
BranchTrueFalseTotal
&$cb($self, $type, $kv, @extra) and shift @{$$self{"queue"};} 0 0 0
391 } else {
392 0 $self->default_recv ($type, $kv, @extra);
393 }
394 }
395  
396 0 ▶sub default_recv {
Subroutine default_recv: not called CC=4 SCAR=30.0
Pod undocumented
397 0 my ($self, $type, $kv, $rdata) = @_;
398  
399 0 ▶ if ($type eq "node_hello") {
Branch: 2 branches
BranchTrueFalseTotal
if ($type eq 'node_hello') { } 0 0 0
elsif (exists $self->{'id'}{$kv->{'identifier'}}) { } 0 0 0
400 0 $self->{node_hello} = $kv;
401 } elsif (exists $self->{id}{$kv->{identifier}}) {
402 $self->{id}{$kv->{identifier}}($self, $type, $kv, $rdata)
403 0 ▶ and delete $self->{id}{$kv->{identifier}};
Branch: 1 branch
BranchTrueFalseTotal
$self->{"id"}{$kv->{"identifier"}}($self, $type, $kv, $rdata) and delete $self->{"id"}{$kv->{"identifier"}} 0 0 0
404 }
405 }
406  
407 =back
408  
409 =head2 FCP REQUESTS
410  
411 The following methods implement various requests. Most of them map
412 directory to the FCP message of the same name. The added benefit of
413 these over sending requests yourself is that they handle the necessary
414 serialisation, protocol quirks, and replies.
415  
416 All of them exist in two versions, the variant shown in this manpage, and
417 a variant with an extra C<_> at the end, and an extra C<$cb> argument. The
418 version as shown is I<synchronous> - it will wait for any replies, and
419 either return the reply, or croak with an error. The underscore variant
420 returns immediately and invokes one or more callbacks or condvars later.
421  
422 For example, the call
423  
424 $info = $fcp->get_plugin_info ($name, $detailed);
425  
426 Also comes in this underscore variant:
427  
428 $fcp->get_plugin_info_ ($name, $detailed, $cb);
429  
430 You can thinbk of the underscore as a kind of continuation indicator - the
431 normal function waits and returns with the data, the C<_> indicates that
432 you pass the continuation yourself, and the continuation will be invoked
433 with the results.
434  
435 This callback/continuation argument (C<$cb>) can come in three forms itself:
436  
437 =over 4
438  
439 =item A code reference (or rather anything not matching some other alternative)
440  
441 This code reference will be invoked with the result on success. On an
442 error, it will invoke the C<on_failure> callback of the FCP object, or,
443 if none was defined, will die (in the event loop) with a backtrace of the
444 call site.
445  
446 This is a popular choice, but it makes handling errors hard - make sure
447 you never generate protocol errors!
448  
449 If an C<on_failure> hook exists, it will be invoked with the FCP object,
450 the request type (the name of the method), a (textual) backtrace as
451 generated by C<Carp::longmess>, and arrayref containing the arguments from
452 the original request invocation and the error object from the server, in
453 this order, e.g.:
454  
455 on_failure => sub {
456 my ($fcp, $request_type, $backtrace, $orig_args, $error_object) = @_;
457  
458 warn "FCP failure ($type), $error_object->{code_description} ($error_object->{extra_description})$backtrace";
459 exit 1;
460 },
461  
462 =item A condvar (as returned by e.g. C<< AnyEvent->condvar >>)
463  
464 When a condvar is passed, it is sent (C<< $cv->send ($results) >>) the
465 results when the request has finished. Should an error occur, the error
466 will instead result in C<< $cv->croak ($error) >>.
467  
468 This is also a popular choice.
469  
470 =item An array with two callbacks C<[$success, $failure]>
471  
472 The C<$success> callback will be invoked with the results, while the
473 C<$failure> callback will be invoked on any errors.
474  
475 The C<$failure> callback will be invoked with the error object from the
476 server.
477  
478 =item C<undef>
479  
480 This is the same thing as specifying C<sub { }> as callback, i.e. on
481 success, the results are ignored, while on failure, the C<on_failure> hook
482 is invoked or the module dies with a backtrace.
483  
484 This is good for quick scripts, or when you really aren't interested in
485 the results.
486  
487 =back
488  
489 =cut
490  
491 1 ▶our $NOP_CB = sub { };
Subroutine __ANON__: not called CC=1 SCAR=0.0
492  
493 9 ▶sub _txn {
Subroutine _txn: called CC=1 SCAR=4.9
494 9 my ($name, $sub) = @_;
495  
496 9 ▶ *{$name} = sub {
Subroutine __ANON__: not called CC=1 SCAR=4.6
497 0 my $cv = AE::cv;
498  
499 0 ▶ splice @_, 1, 0, $cv, sub { $cv->croak ($_[0]{extra_description}) };
Subroutine __ANON__: not called CC=1 SCAR=6.9
500 0 &$sub;
501 0 $cv->recv
502 9 };
503  
504 9 ▶ *{"$name\_"} = sub {
Subroutine __ANON__: not called CC=4 SCAR=29.0
505 0 my ($ok, $err) = pop;
506  
507 0 ▶ if (ARRAY:: eq ref $ok) {
Branch: 2 branches
BranchTrueFalseTotal
if ('ARRAY' eq ref $ok) { } 0 0 0
elsif (UNIVERSAL::isa($ok, 'AnyEvent::CondVar')) { } 0 0 0
508 0 ($ok, $err) = @$ok;
509 } elsif (UNIVERSAL::isa $ok, AnyEvent::CondVar::) {
510 0 ▶ $err = sub { $ok->croak ($_[0]{extra_description}) };
Subroutine __ANON__: not called CC=1 SCAR=6.9
511 } else {
512 0 my $bt = Carp::longmess "AnyEvent::FCP request $name";
513 0 Scalar::Util::weaken (my $self = $_[0]);
514 0 my $args = [@_]; shift @$args;
515 0 ▶ $err = sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
516 0 ▶ if ($self->{on_failure}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{'on_failure'}) { } 0 0 0
517 0 $self->{on_failure}($self, $name, $args, $bt, $_[0]);
518 } else {
519 0 die "$_[0]{code_description} ($_[0]{extra_description})$bt";
520 }
521 0 };
522 }
523  
524 0 ▶ $ok ||= $NOP_CB;
Condition0%0/3
$ok ||= $AnyEvent::FCP::NOP_CB
l!l&&r!l&&!r
000
MC/DC0%0/2
$ok ||= $AnyEvent::FCP::NOP_CB
$ok $AnyEvent::FCP::NOP_CB
Truth table0%0/3
A ||= B
A= $okB= $AnyEvent::FCP::NOP_CB
ABresult
1X1
011
000
525  
526 0 splice @_, 1, 0, $ok, $err;
527 0 &$sub;
528 9 };
529 }
530  
531 =over 4
532  
533 =item $peers = $fcp->list_peers ([$with_metdata[, $with_volatile]])
534  
535 =cut
536  
537 0 ▶_txn list_peers => sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
538 0 my ($self, $ok, undef, $with_metadata, $with_volatile) = @_;
539  
540 0 my @res;
541  
542 $self->send_msg (list_peers =>
543 with_metadata => $with_metadata ? "true" : "false",
544 with_volatile => $with_volatile ? "true" : "false",
545 0 ▶ id_cb => sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
546 0 my ($self, $type, $kv, $rdata) = @_;
547  
548 0 ▶ if ($type eq "end_list_peers") {
Branch: 1 branch
BranchTrueFalseTotal
if ($type eq 'end_list_peers') { } 0 0 0
549 0 $ok->(\@res);
550 0 1
551 } else {
552 0 push @res, $kv;
553 0 0
554 }
555 },
556 0 ▶ );
Branch: 2 branches
BranchTrueFalseTotal
$with_metadata ? : 0 0 0
$with_volatile ? : 0 0 0
557 1 };
558  
559 =item $notes = $fcp->list_peer_notes ($node_identifier)
560  
561 =cut
562  
563 0 ▶_txn list_peer_notes => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
564 0 my ($self, $ok, undef, $node_identifier) = @_;
565  
566 $self->send_msg (list_peer_notes =>
567 node_identifier => $node_identifier,
568 0 ▶ id_cb => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
569 0 my ($self, $type, $kv, $rdata) = @_;
570  
571 0 $ok->($kv);
572 0 1
573 },
574 0 );
575 1 };
576  
577 =item $fcp->watch_global ($enabled[, $verbosity_mask])
578  
579 =cut
580  
581 0 ▶_txn watch_global => sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
582 0 my ($self, $ok, $err, $enabled, $verbosity_mask) = @_;
583  
584 0 ▶ $self->send_msg (watch_global =>
Branch: 2 branches
BranchTrueFalseTotal
$enabled ? : 0 0 0
defined $verbosity_mask ? : 0 0 0
585 enabled => $enabled ? "true" : "false",
586 defined $verbosity_mask ? (verbosity_mask => $verbosity_mask+0) : (),
587 );
588  
589 0 $ok->();
590 1 };
591  
592 =item $reqs = $fcp->list_persistent_requests
593  
594 =cut
595  
596 0 ▶_txn list_persistent_requests => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
597 0 my ($self, $ok, $err) = @_;
598  
599 0 ▶ $self->serialise (list_persistent_requests => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
600 0 my ($self, $guard) = @_;
601  
602 0 my @res;
603  
604 0 $self->send_msg ("list_persistent_requests");
605  
606 0 ▶ $self->on (sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
607 0 my ($self, $type, $kv, $rdata) = @_;
608  
609 0 $guard if 0;
610  
611 0 ▶ if ($type eq "end_list_persistent_requests") {
Branch: 1 branch
BranchTrueFalseTotal
if ($type eq 'end_list_persistent_requests') { } 0 0 0
612 0 $ok->(\@res);
613 0 return;
614 } else {
615 0 my $id = $kv->{identifier};
616  
617 0 ▶ if ($type =~ /^persistent_(get|put|put_dir)$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($type =~ /^persistent_(get|put|put_dir)$/u) 0 0 0
618 0 push @res, [$type, $kv];
619 }
620 }
621  
622 0 1
623 0 });
624 0 });
625 1 };
626  
627 =item $sync = $fcp->modify_persistent_request ($global, $identifier[, $client_token[, $priority_class]])
628  
629 Update either the C<client_token> or C<priority_class> of a request
630 identified by C<$global> and C<$identifier>, depending on which of
631 C<$client_token> and C<$priority_class> are not C<undef>.
632  
633 =cut
634  
635 0 ▶_txn modify_persistent_request => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
636 0 my ($self, $ok, $err, $global, $identifier, $client_token, $priority_class) = @_;
637  
638 0 ▶ $self->serialise ($identifier => sub {
Subroutine __ANON__: not called CC=4 SCAR=30.0
639 0 my ($self, $guard) = @_;
640  
641 0 ▶ $self->send_msg (modify_persistent_request =>
Branch: 3 branches
BranchTrueFalseTotal
$global ? : 0 0 0
defined $client_token ? : 0 0 0
defined $priority_class ? : 0 0 0
642 global => $global ? "true" : "false",
643 identifier => $identifier,
644 defined $client_token ? (client_token => $client_token ) : (),
645 defined $priority_class ? (priority_class => $priority_class) : (),
646 );
647  
648 0 ▶ $self->on (sub {
Subroutine __ANON__: not called CC=4 SCAR=30.0
649 0 my ($self, $type, $kv, @extra) = @_;
650  
651 0 $guard if 0;
652  
653 0 ▶ if ($kv->{identifier} eq $identifier) {
Branch: 1 branch
BranchTrueFalseTotal
if ($kv->{"identifier"} eq $identifier) 0 0 0
654 0 ▶ if ($type eq "persistent_request_modified") {
Branch: 2 branches
BranchTrueFalseTotal
if ($type eq 'persistent_request_modified') { } 0 0 0
elsif ($type eq 'protocol_error') { } 0 0 0
655 0 $ok->($kv);
656 0 return;
657 } elsif ($type eq "protocol_error") {
658 0 $err->($kv);
659 0 return;
660 }
661 }
662  
663 1
664 0 });
665 0 });
666 1 };
667  
668 =item $info = $fcp->get_plugin_info ($name, $detailed)
669  
670 =cut
671  
672 0 ▶_txn get_plugin_info => sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
673 0 my ($self, $ok, $err, $name, $detailed) = @_;
674  
675 0 my $id = $self->identifier;
676  
677 0 ▶ $self->send_msg (get_plugin_info =>
Branch: 1 branch
BranchTrueFalseTotal
$detailed ? : 0 0 0
678 identifier => $id,
679 plugin_name => $name,
680 detailed => $detailed ? "true" : "false",
681 );
682 0 ▶ $self->on (sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
683 0 my ($self, $type, $kv) = @_;
684  
685 0 ▶ if ($kv->{identifier} eq $id) {
Branch: 1 branch
BranchTrueFalseTotal
if ($kv->{"identifier"} eq $id) 0 0 0
686 0 ▶ if ($type eq "get_plugin_info") {
Branch: 1 branch
BranchTrueFalseTotal
if ($type eq 'get_plugin_info') { } 0 0 0
687 0 $ok->($kv);
688 } else {
689 0 $err->($kv, $type);
690 }
691 0 return;
692 }
693  
694 1
695 0 });
696 1 };
697  
698 =item $status = $fcp->client_get ($uri, $identifier, %kv)
699  
700 %kv can contain (L<http://wiki.freenetproject.org/FCP2p0ClientGet>).
701  
702 ignore_ds, ds_only, verbosity, max_size, max_temp_size, max_retries,
703 priority_class, persistence, client_token, global, return_type,
704 binary_blob, allowed_mime_types, filename, temp_filename
705  
706 =cut
707  
708 0 ▶_txn client_get => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
709 0 my ($self, $ok, $err, $uri, $identifier, %kv) = @_;
710  
711 0 ▶ $self->serialise ($identifier => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
712 0 my ($self, $guard) = @_;
713  
714 0 $self->send_msg (client_get =>
715 %kv,
716 uri => $uri,
717 identifier => $identifier,
718 );
719  
720 0 ▶ $self->on (sub {
Subroutine __ANON__: not called CC=4 SCAR=30.0
721 0 my ($self, $type, $kv, @extra) = @_;
722  
723 0 $guard if 0;
724  
725 0 ▶ if ($kv->{identifier} eq $identifier) {
Branch: 1 branch
BranchTrueFalseTotal
if ($kv->{"identifier"} eq $identifier) 0 0 0
726 0 ▶ if ($type eq "persistent_get") {
Branch: 2 branches
BranchTrueFalseTotal
if ($type eq 'persistent_get') { } 0 0 0
elsif ($type eq 'protocol_error') { } 0 0 0
727 0 $ok->($kv);
728 0 return;
729 } elsif ($type eq "protocol_error") {
730 0 $err->($kv);
731 0 return;
732 }
733 }
734  
735 1
736 0 });
737 0 });
738 1 };
739  
740 =item $status = $fcp->remove_request ($identifier[, $global])
741  
742 Remove the request with the given isdentifier. Returns true if successful,
743 false on error.
744  
745 =cut
746  
747 0 ▶_txn remove_request => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
748 0 my ($self, $ok, $err, $identifier, $global) = @_;
749  
750 0 ▶ $self->serialise ($identifier => sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
751 0 my ($self, $guard) = @_;
752  
753 0 ▶ $self->send_msg (remove_request =>
Branch: 1 branch
BranchTrueFalseTotal
$global ? : 0 0 0
754 identifier => $identifier,
755 global => $global ? "true" : "false",
756 );
757 0 ▶ $self->on (sub {
Subroutine __ANON__: not called CC=4 SCAR=30.0
758 0 my ($self, $type, $kv, @extra) = @_;
759  
760 0 $guard if 0;
761  
762 0 ▶ if ($kv->{identifier} eq $identifier) {
Branch: 1 branch
BranchTrueFalseTotal
if ($kv->{"identifier"} eq $identifier) 0 0 0
763 0 ▶ if ($type eq "persistent_request_removed") {
Branch: 2 branches
BranchTrueFalseTotal
if ($type eq 'persistent_request_removed') { } 0 0 0
elsif ($type eq 'protocol_error') { } 0 0 0
764 0 $ok->(1);
765 0 return;
766 } elsif ($type eq "protocol_error") {
767 0 $err->($kv);
768 0 return;
769 }
770 }
771  
772 1
773 0 });
774 0 });
775 1 };
776  
777 =item ($can_read, $can_write) = $fcp->test_dda ($local_directory, $remote_directory, $want_read, $want_write))
778  
779 The DDA test in FCP is probably the single most broken protocol - only
780 one directory test can be outstanding at any time, and some guessing and
781 heuristics are involved in mangling the paths.
782  
783 This function combines C<TestDDARequest> and C<TestDDAResponse> in one
784 request, handling file reading and writing as well, and tries very hard to
785 do the right thing.
786  
787 Both C<$local_directory> and C<$remote_directory> must specify the same
788 directory - C<$local_directory> is the directory path on the client (where
789 L<AnyEvent::FCP> runs) and C<$remote_directory> is the directory path on
790 the server (where the freenet node runs). When both are running on the
791 same node, the paths are generally identical.
792  
793 C<$want_read> and C<$want_write> should be set to a true value when you
794 want to read (get) files or write (put) files, respectively.
795  
796 On error, an exception is thrown. Otherwise, C<$can_read> and
797 C<$can_write> indicate whether you can reaqd or write to freenet via the
798 directory.
799  
800 =cut
801  
802 0 ▶_txn test_dda => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
803 0 my ($self, $ok, $err, $local, $remote, $want_read, $want_write) = @_;
804  
805 0 ▶ $self->serialise (test_dda => sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
806 0 my ($self, $guard) = @_;
807  
808 0 ▶ $self->send_msg (test_dda_request =>
Branch: 2 branches
BranchTrueFalseTotal
$want_read ? : 0 0 0
$want_write ? : 0 0 0
809 directory => $remote,
810 want_read_directory => $want_read ? "true" : "false",
811 want_write_directory => $want_write ? "true" : "false",
812 );
813 0 ▶ $self->on (sub {
Subroutine __ANON__: not called CC=11 SCAR=48.8
814 0 my ($self, $type, $kv) = @_;
815  
816 0 ▶ if ($type eq "test_dda_reply") {
Branch: 2 branches
BranchTrueFalseTotal
if ($type eq 'test_dda_reply') { } 0 0 0
elsif ($type eq 'protocol_error' and $kv->{'identifier'} eq $remote) { } 0 0 0
817 # the filenames are all relative to the server-side directory,
818 # which might or might not match $remote anymore, so we
819 # need to rewrite the paths to be relative to $local
820 0 for my $k (qw(read_filename write_filename)) {
821 0 my $f = $kv->{$k};
822 0 for my $dir ($kv->{directory}, $remote) {
823 0 ▶ if ($dir eq substr $f, 0, length $dir) {
Branch: 1 branch
BranchTrueFalseTotal
if ($dir eq substr($f, 0, length $dir)) 0 0 0
824 0 substr $f, 0, 1 + length $dir, "";
825 0 $kv->{$k} = $f;
826 0 last;
827 }
828 }
829 }
830  
831 0 my %response = (directory => $remote);
832  
833 0 ▶ if (length $kv->{read_filename}) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $kv->{"read_filename"}) 0 0 0
834 0 ▶ if (open my $fh, "<:raw", "$local/$kv->{read_filename}") {
Branch: 1 branch
BranchTrueFalseTotal
if (open my $fh, "<:raw", qq[$local/$kv->{"read_filename"}]) 0 0 0
835 0 sysread $fh, my $buf, -s $fh;
836 0 $response{read_content} = $buf;
837 }
838 }
839  
840 0 ▶ if (length $kv->{write_filename}) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $kv->{"write_filename"}) 0 0 0
841 0 ▶ if (open my $fh, ">:raw", "$local/$kv->{write_filename}") {
Branch: 1 branch
BranchTrueFalseTotal
if (open my $fh, ">:raw", qq[$local/$kv->{"write_filename"}]) 0 0 0
842 0 syswrite $fh, $kv->{content_to_write};
843 }
844 }
845  
846 0 $self->send_msg (test_dda_response => %response);
847  
848 0 ▶ $self->on (sub {
Subroutine __ANON__: not called CC=4 SCAR=30.0
849 0 my ($self, $type, $kv) = @_;
850  
851 0 $guard if 0; # reference
852  
853 0 ▶ if ($type eq "test_dda_complete") {
Branch: 2 branches
BranchTrueFalseTotal
if ($type eq 'test_dda_complete') { } 0 0 0
elsif ($type eq 'protocol_error' and $kv->{'identifier'} eq $remote) { } 0 0 0
854 $ok->(
855 $kv->{read_directory_allowed} eq "true",
856 0 $kv->{write_directory_allowed} eq "true",
857 );
858 ▶ } elsif ($type eq "protocol_error" && $kv->{identifier} eq $remote) {
Condition0%0/3
$type eq "protocol_error" and $kv->{"identifier"} eq $remote
!ll&&!rl&&r
000
MC/DC0%0/2
$type eq "protocol_error" and $kv->{"identifier"} eq $remote
$type eq "protocol_error" $kv->{"identifier"} eq $remote
Truth table0%0/3
A and B
A= $type eq "protocol_error"B= $kv->{"identifier"} eq $remote
ABresult
0X0
100
111
859 0 $err->($kv->{extra_description});
860 0 return;
861 }
862  
863 1
864 0 });
865  
866 0 return;
867 ▶ } elsif ($type eq "protocol_error" && $kv->{identifier} eq $remote) {
Condition0%0/3
$type eq "protocol_error" and $kv->{"identifier"} eq $remote
!ll&&!rl&&r
000
MC/DC0%0/2
$type eq "protocol_error" and $kv->{"identifier"} eq $remote
$type eq "protocol_error" $kv->{"identifier"} eq $remote
Truth table0%0/3
A and B
A= $type eq "protocol_error"B= $kv->{"identifier"} eq $remote
ABresult
0X0
100
111
868 0 $err->($kv);
869 0 return;
870 }
871  
872 1
873 0 });
874 0 });
875 1 };
876  
877 =back
878  
879 =head2 REQUEST CACHE
880  
881 The C<AnyEvent::FCP> class keeps a request cache, where it caches all
882 information from requests.
883  
884 For these messages, it will store a copy of the key-value pairs, together with a C<type> slot,
885 in C<< $fcp->{req}{$identifier} >>:
886  
887 persistent_get
888 persistent_put
889 persistent_put_dir
890  
891 This message updates the stored data:
892  
893 persistent_request_modified
894  
895 This message will remove this entry:
896  
897 persistent_request_removed
898  
899 These messages get merged into the cache entry, under their
900 type, i.e. a C<simple_progress> message will be stored in C<<
901 $fcp->{req}{$identifier}{simple_progress} >>:
902  
903 simple_progress # get/put
904  
905 uri_generated # put
906 generated_metadata # put
907 started_compression # put
908 finished_compression # put
909 put_failed # put
910 put_fetchable # put
911 put_successful # put
912  
913 sending_to_network # get
914 compatibility_mode # get
915 expected_hashes # get
916 expected_mime # get
917 expected_data_length # get
918 get_failed # get
919 data_found # get
920 enter_finite_cooldown # get
921  
922 In addition, an event (basically a fake message) of type C<request_changed> is generated
923 on every change, which will be called as C<< $cb->($fcp, $kv, $type) >>, where C<$type>
924 is the type of the original message triggering the change,
925  
926 To fill this cache with the global queue and keep it updated,
927 call C<watch_global> to subscribe to updates, followed by
928 C<list_persistent_requests_sync>.
929  
930 $fcp->watch_global_sync_; # do not wait
931 $fcp->list_persistent_requests; # wait
932  
933 To get a better idea of what is stored in the cache, here is an example of
934 what might be stored in C<< $fcp->{req}{"Frost-gpl.txt"} >>:
935  
936 {
937 identifier => "Frost-gpl.txt",
938 uri => 'CHK@Fnx5kzdrfE,EImdzaVyEWl,AAIC--8/gpl.txt',
939 binary_blob => "false",
940 global => "true",
941 max_retries => -1,
942 max_size => 9223372036854775807,
943 persistence => "forever",
944 priority_class => 3,
945 real_time => "false",
946 return_type => "direct",
947 started => "true",
948 type => "persistent_get",
949 verbosity => 2147483647,
950 sending_to_network => {
951 identifier => "Frost-gpl.txt",
952 global => "true",
953 },
954 compatibility_mode => {
955 identifier => "Frost-gpl.txt",
956 definitive => "true",
957 dont_compress => "false",
958 global => "true",
959 max => "COMPAT_1255",
960 min => "COMPAT_1255",
961 },
962 expected_hashes => {
963 identifier => "Frost-gpl.txt",
964 global => "true",
965 hashes => {
966 ed2k => "d83596f5ee3b7...",
967 md5 => "e0894e4a2a6...",
968 sha1 => "...",
969 sha256 => "...",
970 sha512 => "...",
971 tth => "...",
972 },
973 },
974 expected_mime => {
975 identifier => "Frost-gpl.txt",
976 global => "true",
977 metadata => { content_type => "application/rar" },
978 },
979 expected_data_length => {
980 identifier => "Frost-gpl.txt",
981 data_length => 37576,
982 global => "true",
983 },
984 simple_progress => {
985 identifier => "Frost-gpl.txt",
986 failed => 0,
987 fatally_failed => 0,
988 finalized_total => "true",
989 global => "true",
990 last_progress => 1438639282628,
991 required => 372,
992 succeeded => 102,
993 total => 747,
994 },
995 data_found => {
996 identifier => "Frost-gpl.txt",
997 completion_time => 1438663354026,
998 data_length => 37576,
999 global => "true",
1000 metadata => { content_type => "image/jpeg" },
1001 startup_time => 1438657196167,
1002 },
1003 }
1004  
1005 =head1 EXAMPLE PROGRAM
1006  
1007 use AnyEvent::FCP;
1008  
1009 my $fcp = new AnyEvent::FCP;
1010  
1011 # let us look at the global request list
1012 $fcp->watch_global_ (1);
1013  
1014 # list them, synchronously
1015 my $req = $fcp->list_persistent_requests;
1016  
1017 # go through all requests
1018 TODO
1019 for my $req (values %$req) {
1020 # skip jobs not directly-to-disk
1021 next unless $req->{return_type} eq "disk";
1022 # skip jobs not issued by FProxy
1023 next unless $req->{identifier} =~ /^FProxy:/;
1024  
1025 if ($req->{data_found}) {
1026 # file has been successfully downloaded
1027
1028 ... move the file away
1029 (left as exercise)
1030  
1031 # remove the request
1032  
1033 $fcp->remove_request (1, $req->{identifier});
1034 } elsif ($req->{get_failed}) {
1035 # request has failed
1036 if ($req->{get_failed}{code} == 11) {
1037 # too many path components, should restart
1038 } else {
1039 # other failure
1040 }
1041 } else {
1042 # modify priorities randomly, to improve download rates
1043 $fcp->modify_persistent_request (1, $req->{identifier}, undef, int 6 - 5 * (rand) ** 1.7)
1044 if 0.1 > rand;
1045 }
1046 }
1047  
1048 # see if the dummy plugin is loaded, to ensure all previous requests have finished.
1049 $fcp->get_plugin_info_sync ("dummy");
1050  
1051 =head1 SEE ALSO
1052  
1053 L<http://wiki.freenetproject.org/FreenetFCPSpec2Point0>, L<Net::FCP>.
1054  
1055 =head1 BUGS
1056  
1057 =head1 AUTHOR
1058  
1059 Marc Lehmann <schmorp@schmorp.de>
1060 http://home.schmorp.de/
1061  
1062 =cut
1063  
1064 1 1
1065  
↑ Summary