| … | |
… | |
| 8 | |
8 | |
| 9 | my $ni = $fcp->txn_node_info->result; |
9 | my $ni = $fcp->txn_node_info->result; |
| 10 | my $ni = $fcp->node_info; |
10 | my $ni = $fcp->node_info; |
| 11 | |
11 | |
| 12 | DESCRIPTION |
12 | DESCRIPTION |
|
|
13 | This module implements the first version of the freenet client protocol, |
|
|
14 | for use with freenet versions 0.5. For freenet protocol version 2.0 |
|
|
15 | support (as used by freenet 0.7), see the AnyEvent::FCP module. |
|
|
16 | |
| 13 | See <http://freenet.sourceforge.net/index.php?page=fcp> for a |
17 | See <http://freenet.sourceforge.net/index.php?page=fcp> for a |
| 14 | description of what the messages do. I am too lazy to document all this |
18 | description of what the messages do. |
| 15 | here. |
|
|
| 16 | |
19 | |
| 17 | WARNING |
20 | The module uses AnyEvent to find a suitable Event module. |
| 18 | This module is alpha. While it probably won't destroy (much :) of your |
|
|
| 19 | data, it currently falls short of what it should provide (intelligent |
|
|
| 20 | uri following, splitfile downloads, healing...) |
|
|
| 21 | |
21 | |
| 22 | IMPORT TAGS |
22 | IMPORT TAGS |
| 23 | Nothing much can be "imported" from this module right now. There are, |
23 | Nothing much can be "imported" from this module right now. |
| 24 | however, certain "import tags" that can be used to select the event |
|
|
| 25 | model to be used. |
|
|
| 26 | |
|
|
| 27 | Event models are implemented as modules under the "Net::FCP::Event::xyz" |
|
|
| 28 | class, where "xyz" is the event model to use. The default is "Event" (or |
|
|
| 29 | later "Auto"). |
|
|
| 30 | |
|
|
| 31 | The import tag to use is named "event=xyz", e.g. "event=Event", |
|
|
| 32 | "event=Glib" etc. |
|
|
| 33 | |
|
|
| 34 | You should specify the event module to use only in the main program. |
|
|
| 35 | |
|
|
| 36 | If no event model has been specified, FCP tries to autodetect it on |
|
|
| 37 | first use (e.g. first transaction), in this order: Coro, Event, Glib, |
|
|
| 38 | Tk. |
|
|
| 39 | |
24 | |
| 40 | FREENET BASICS |
25 | FREENET BASICS |
| 41 | Ok, this section will not explain any freenet basics to you, just some |
26 | Ok, this section will not explain any freenet basics to you, just some |
| 42 | problems I found that you might want to avoid: |
27 | problems I found that you might want to avoid: |
| 43 | |
28 | |
| … | |
… | |
| 53 | Virtually every number in the FCP protocol is in hex. Be sure to use |
38 | Virtually every number in the FCP protocol is in hex. Be sure to use |
| 54 | "hex()" on all such numbers, as the module (currently) does nothing |
39 | "hex()" on all such numbers, as the module (currently) does nothing |
| 55 | to convert these for you. |
40 | to convert these for you. |
| 56 | |
41 | |
| 57 | THE Net::FCP CLASS |
42 | THE Net::FCP CLASS |
| 58 | $meta = Net::FCP::parse_metadata $string |
|
|
| 59 | Parse a metadata string and return it. |
|
|
| 60 | |
|
|
| 61 | The metadata will be a hashref with key "version" (containing the |
|
|
| 62 | mandatory version header entries) and key "raw" containing the |
|
|
| 63 | original metadata string. |
|
|
| 64 | |
|
|
| 65 | All other headers are represented by arrayrefs (they can be |
|
|
| 66 | repeated). |
|
|
| 67 | |
|
|
| 68 | Since this description is confusing, here is a rather verbose |
|
|
| 69 | example of a parsed manifest: |
|
|
| 70 | |
|
|
| 71 | ( |
|
|
| 72 | raw => "Version...", |
|
|
| 73 | version => { revision => 1 }, |
|
|
| 74 | document => [ |
|
|
| 75 | { |
|
|
| 76 | info => { format" => "image/jpeg" }, |
|
|
| 77 | name => "background.jpg", |
|
|
| 78 | redirect => { target => "freenet:CHK\@ZcagI,ra726bSw" }, |
|
|
| 79 | }, |
|
|
| 80 | { |
|
|
| 81 | info => { format" => "text/html" }, |
|
|
| 82 | name => ".next", |
|
|
| 83 | redirect => { target => "freenet:SSK\@ilUPAgM/TFEE/3" }, |
|
|
| 84 | }, |
|
|
| 85 | { |
|
|
| 86 | info => { format" => "text/html" }, |
|
|
| 87 | redirect => { target => "freenet:CHK\@8M8Po8ucwI,8xA" }, |
|
|
| 88 | } |
|
|
| 89 | ] |
|
|
| 90 | ) |
|
|
| 91 | |
|
|
| 92 | $string = Net::FCP::build_metadata $meta |
|
|
| 93 | Takes a hash reference as returned by "Net::FCP::parse_metadata" and |
|
|
| 94 | returns the corresponding string form. If a string is given, it's |
|
|
| 95 | returned as is. |
|
|
| 96 | |
|
|
| 97 | $fcp = new Net::FCP [host => $host][, port => $port][, progress => \&cb] |
43 | $fcp = new Net::FCP [host => $host][, port => $port][, progress => \&cb] |
| 98 | Create a new virtual FCP connection to the given host and port |
44 | Create a new virtual FCP connection to the given host and port |
| 99 | (default 127.0.0.1:8481, or the environment variables "FREDHOST" and |
45 | (default 127.0.0.1:8481, or the environment variables "FREDHOST" and |
| 100 | "FREDPORT"). |
46 | "FREDPORT"). |
| 101 | |
47 | |
| … | |
… | |
| 110 | my ($self, $txn, $type, $attr) = @_; |
56 | my ($self, $txn, $type, $attr) = @_; |
| 111 | |
57 | |
| 112 | warn "progress<$txn,$type," . (join ":", %$attr) . ">\n"; |
58 | warn "progress<$txn,$type," . (join ":", %$attr) . ">\n"; |
| 113 | } |
59 | } |
| 114 | |
60 | |
| 115 | $txn = $fcp->txn(type => attr => val,...) |
61 | $txn = $fcp->txn (type => attr => val,...) |
| 116 | The low-level interface to transactions. Don't use it. |
62 | The low-level interface to transactions. Don't use it unless you |
| 117 | |
63 | have "special needs". Instead, use predefiend transactions like |
| 118 | Here are some examples of using transactions: |
64 | this: |
| 119 | |
65 | |
| 120 | The blocking case, no (visible) transactions involved: |
66 | The blocking case, no (visible) transactions involved: |
| 121 | |
67 | |
| 122 | my $nodehello = $fcp->client_hello; |
68 | my $nodehello = $fcp->client_hello; |
| 123 | |
69 | |
| … | |
… | |
| 179 | $uri = $fcp->generate_chk ($metadata, $data[, $cipher]) |
125 | $uri = $fcp->generate_chk ($metadata, $data[, $cipher]) |
| 180 | Calculates a CHK, given the metadata and data. $cipher is either |
126 | Calculates a CHK, given the metadata and data. $cipher is either |
| 181 | "Rijndael" or "Twofish", with the latter being the default. |
127 | "Rijndael" or "Twofish", with the latter being the default. |
| 182 | |
128 | |
| 183 | $txn = $fcp->txn_generate_svk_pair |
129 | $txn = $fcp->txn_generate_svk_pair |
| 184 | ($public, $private) = @{ $fcp->generate_svk_pair } |
130 | ($public, $private, $crypto) = @{ $fcp->generate_svk_pair } |
| 185 | Creates a new SVK pair. Returns an arrayref with the public key, the |
131 | Creates a new SVK pair. Returns an arrayref with the public key, the |
| 186 | private key and a crypto key, which is just additional entropy. |
132 | private key and a crypto key, which is just additional entropy. |
| 187 | |
133 | |
| 188 | [ |
134 | [ |
| 189 | "acLx4dux9fvvABH15Gk6~d3I-yw", |
135 | "acLx4dux9fvvABH15Gk6~d3I-yw", |
| … | |
… | |
| 216 | Finds and returns the size (rounded up to the nearest power of two) |
162 | Finds and returns the size (rounded up to the nearest power of two) |
| 217 | of the given document. |
163 | of the given document. |
| 218 | |
164 | |
| 219 | $txn = $fcp->txn_client_get ($uri [, $htl = 15 [, $removelocal = 0]]) |
165 | $txn = $fcp->txn_client_get ($uri [, $htl = 15 [, $removelocal = 0]]) |
| 220 | ($metadata, $data) = @{ $fcp->client_get ($uri, $htl, $removelocal) |
166 | ($metadata, $data) = @{ $fcp->client_get ($uri, $htl, $removelocal) |
| 221 | Fetches a (small, as it should fit into memory) file from freenet. |
167 | Fetches a (small, as it should fit into memory) key content block |
| 222 | $meta is the metadata (as returned by "parse_metadata" or "undef"). |
168 | from freenet. $meta is a "Net::FCP::Metadata" object or "undef"). |
| 223 | |
169 | |
| 224 | The $uri should begin with "freenet:", but the scheme is currently |
170 | The $uri should begin with "freenet:", but the scheme is currently |
| 225 | added, if missing. |
171 | added, if missing. |
| 226 | |
|
|
| 227 | Due to the overhead, a better method to download big files should be |
|
|
| 228 | used. |
|
|
| 229 | |
172 | |
| 230 | my ($meta, $data) = @{ |
173 | my ($meta, $data) = @{ |
| 231 | $fcp->client_get ( |
174 | $fcp->client_get ( |
| 232 | "freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w" |
175 | "freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w" |
| 233 | ) |
176 | ) |
| … | |
… | |
| 279 | data can be accessed using "$txn->{userdata}". |
222 | data can be accessed using "$txn->{userdata}". |
| 280 | |
223 | |
| 281 | Returns the txn object, useful for chaining. |
224 | Returns the txn object, useful for chaining. |
| 282 | |
225 | |
| 283 | $txn->cancel (%attr) |
226 | $txn->cancel (%attr) |
| 284 | Cancels the operation with a "cancel" exception anf the given |
227 | Cancels the operation with a "cancel" exception and the given |
| 285 | attributes (consider at least giving the attribute "reason"). |
228 | attributes (consider at least giving the attribute "reason"). |
| 286 | |
229 | |
| 287 | UNTESTED. |
230 | UNTESTED. |
| 288 | |
231 | |
| 289 | $result = $txn->result |
232 | $result = $txn->result |
| … | |
… | |
| 319 | SEE ALSO |
262 | SEE ALSO |
| 320 | <http://freenet.sf.net>. |
263 | <http://freenet.sf.net>. |
| 321 | |
264 | |
| 322 | BUGS |
265 | BUGS |
| 323 | AUTHOR |
266 | AUTHOR |
| 324 | Marc Lehmann <pcg@goof.com> |
267 | Marc Lehmann <schmorp@schmorp.de> |
| 325 | http://www.goof.com/pcg/marc/ |
268 | http://home.schmorp.de/ |
| 326 | |
269 | |
