ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/Net-FCP/README
(Generate patch)

Comparing cvsroot/Net-FCP/README (file contents):
Revision 1.4 by root, Mon Sep 8 01:47:31 2003 UTC vs.
Revision 1.7 by root, Sun Sep 14 09:48:01 2003 UTC

… …
14 description of what the messages do. I am too lazy to document all this 14 description of what the messages do. I am too lazy to document all this
15 here. 15 here.
16 16
17WARNING 17WARNING
18 This module is alpha. While it probably won't destroy (much :) of your 18 This module is alpha. While it probably won't destroy (much :) of your
19 data, it currently works only with the Event module (alkthough the event 19 data, it currently falls short of what it should provide (intelligent
20 mechanism is fully pluggable). 20 uri following, splitfile downloads, healing...)
21
22 IMPORT TAGS
23 Nothing much can be "imported" from this module right now. There are,
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 FREENET BASICS
37 Ok, this section will not explain any freenet basics to you, just some
38 problems I found that you might want to avoid:
39
40 freenet URIs are _NOT_ URIs
41 Whenever a "uri" is required by the protocol, freenet expects a kind
42 of URI prefixed with the "freenet:" scheme, e.g. "freenet:CHK...".
43 However, these are not URIs, as freeent fails to parse them
44 correctly, that is, you must unescape an escaped characters ("%2c"
45 => ",") yourself. Maybe in the future this library will do it for
46 you, so watch out for this incompatible change.
47
48 Numbers are in HEX
49 Virtually every number in the FCP protocol is in hex. Be sure to use
50 "hex()" on all such numbers, as the module (currently) does nothing
51 to convert these for you.
21 52
22 THE Net::FCP CLASS 53 THE Net::FCP CLASS
23 $meta = Net::FCP::parse_metadata $string 54 $meta = Net::FCP::parse_metadata $string
24 Parse a metadata string and return it. 55 Parse a metadata string and return it.
25 56
… …
34 65
35 ( 66 (
36 version => { revision => 1 }, 67 version => { revision => 1 },
37 document => [ 68 document => [
38 { 69 {
39 "info.format" => "image/jpeg", 70 info => { format" => "image/jpeg" },
40 name => "background.jpg", 71 name => "background.jpg",
41 "redirect.target" => "freenet:CHK\@ZcagI,ra726bSw" 72 redirect => { target => "freenet:CHK\@ZcagI,ra726bSw" },
42 }, 73 },
43 { 74 {
44 "info.format" => "text/html", 75 info => { format" => "text/html" },
45 name => ".next", 76 name => ".next",
46 "redirect.target" => "freenet:SSK\@ilUPAgM/TFEE/3" 77 redirect => { target => "freenet:SSK\@ilUPAgM/TFEE/3" },
47 }, 78 },
48 { 79 {
49 "info.format" => "text/html", 80 info => { format" => "text/html" },
50 "redirect.target" => "freenet:CHK\@8M8Po8ucwI,8xA" 81 redirect => { target => "freenet:CHK\@8M8Po8ucwI,8xA" },
51 } 82 }
52 ] 83 ]
53 ) 84 )
54 85
55 $fcp = new Net::FCP [host => $host][, port => $port] 86 $fcp = new Net::FCP [host => $host][, port => $port]
56 Create a new virtual FCP connection to the given host and port 87 Create a new virtual FCP connection to the given host and port
57 (default 127.0.0.1:8481, or the environment variables "FREDHOST" and 88 (default 127.0.0.1:8481, or the environment variables "FREDHOST" and
58 "FREDPORT"). 89 "FREDPORT").
59 90
60 Connections are virtual because no persistent physical connection is 91 Connections are virtual because no persistent physical connection is
61 established. However, the existance of the node is checked by 92 established.
62 executing a "ClientHello" transaction.
63 93
64 $txn = $fcp->txn(type => attr => val,...) 94 $txn = $fcp->txn(type => attr => val,...)
65 The low-level interface to transactions. Don't use it. 95 The low-level interface to transactions. Don't use it.
96
97 Here are some examples of using transactions:
98
99 The blocking case, no (visible) transactions involved:
100
101 my $nodehello = $fcp->client_hello;
102
103 A transaction used in a blocking fashion:
104
105 my $txn = $fcp->txn_client_hello;
106 ...
107 my $nodehello = $txn->result;
108
109 Or shorter:
110
111 my $nodehello = $fcp->txn_client_hello->result;
112
113 Setting callbacks:
114
115 $fcp->txn_client_hello->cb(
116 sub { my $nodehello => $_[0]->result }
117 );
66 118
67 $txn = $fcp->txn_client_hello 119 $txn = $fcp->txn_client_hello
68 $nodehello = $fcp->client_hello 120 $nodehello = $fcp->client_hello
69 Executes a ClientHello request and returns it's results. 121 Executes a ClientHello request and returns it's results.
70 122
… …
114 "hKs0-WDQA4pVZyMPKNFsK1zapWY", 166 "hKs0-WDQA4pVZyMPKNFsK1zapWY",
115 "ZnmvMITaTXBMFGl4~jrjuyWxOWg" 167 "ZnmvMITaTXBMFGl4~jrjuyWxOWg"
116 ] 168 ]
117 169
118 $txn = $fcp->txn_insert_private_key ($private) 170 $txn = $fcp->txn_insert_private_key ($private)
119 $uri = $fcp->insert_private_key ($private) 171 $public = $fcp->insert_private_key ($private)
120 Inserts a private key. $private can be either an insert URI (must 172 Inserts a private key. $private can be either an insert URI (must
121 start with freenet:SSK@) or a raw private key (i.e. the private 173 start with "freenet:SSK@") or a raw private key (i.e. the private
122 value you get back from "generate_svk_pair"). 174 value you get back from "generate_svk_pair").
123 175
124 Returns the public key. 176 Returns the public key.
125 177
126 UNTESTED. 178 UNTESTED.
… …
144 $fcp->client_get ( 196 $fcp->client_get (
145 "freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w" 197 "freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w"
146 ) 198 )
147 }; 199 };
148 200
201 $txn = $fcp->txn_client_put ($uri, $metadata, $data, $htl, $removelocal)
202 my $uri = $fcp->client_put ($uri, $metadata, $data, $htl, $removelocal);
203 Insert a new key. If the client is inserting a CHK, the URI may be
204 abbreviated as just CHK@. In this case, the node will calculate the
205 CHK.
206
207 $meta can be a reference or a string (ONLY THE STRING CASE IS
208 IMPLEMENTED!).
209
210 THIS INTERFACE IS UNTESTED AND SUBJECT TO CHANGE.
211
149 MISSING: ClientPut 212 MISSING: (ClientPut), InsretKey
150 213
151 THE Net::FCP::Txn CLASS 214 THE Net::FCP::Txn CLASS
152 All requests (or transactions) are executed in a asynchroneous way (LIE: 215 All requests (or transactions) are executed in a asynchroneous way (LIE:
153 uploads are blocking). For each request, a "Net::FCP::Txn" object is 216 uploads are blocking). For each request, a "Net::FCP::Txn" object is
154 created (worse: a tcp connection is created, too). 217 created (worse: a tcp connection is created, too).
… …
159 The most interesting method is "result". 222 The most interesting method is "result".
160 223
161 new arg => val,... 224 new arg => val,...
162 Creates a new "Net::FCP::Txn" object. Not normally used. 225 Creates a new "Net::FCP::Txn" object. Not normally used.
163 226
227 $txn = $txn->cb ($coderef)
228 Sets a callback to be called when the request is finished. The
229 coderef will be called with the txn as it's sole argument, so it has
230 to call "result" itself.
231
232 Returns the txn object, useful for chaining.
233
234 Example:
235
236 $fcp->txn_client_get ("freenet:CHK....")
237 ->userdata ("ehrm")
238 ->cb(sub {
239 my $data = shift->result;
240 });
241
242 $txn = $txn->userdata ([$userdata])
243 Set user-specific data. This is useful in progress callbacks. The
244 data can be accessed using "$txn->{userdata}".
245
246 Returns the txn object, useful for chaining.
247
248 $txn->cancel (%attr)
249 Cancels the operation with a "cancel" exception anf the given
250 attributes (consider at least giving the attribute "reason").
251
252 UNTESTED.
253
164 $result = $txn->result 254 $result = $txn->result
165 Waits until a result is available and then returns it. 255 Waits until a result is available and then returns it.
166 256
167 This waiting is (depending on your event model) not very efficient, 257 This waiting is (depending on your event model) not very efficient,
168 as it is done outside the "mainloop". 258 as it is done outside the "mainloop".
259
260 The Net::FCP::Exception CLASS
261 Any unexpected (non-standard) responses that make it impossible to
262 return the advertised result will result in an exception being thrown
263 when the "result" method is called.
264
265 These exceptions are represented by objects of this class.
266
267 $exc = new Net::FCP::Exception $type, \%attr
268 Create a new exception object of the given type (a string like
269 "route_not_found"), and a hashref containing additional attributes
270 (usually the attributes of the message causing the exception).
271
272 $exc->type([$type])
273 With no arguments, returns the exception type. Otherwise a boolean
274 indicating wether the exception is of the given type is returned.
275
276 $exc->attr([$attr])
277 With no arguments, returns the attributes. Otherwise the named
278 attribute value is returned.
169 279
170SEE ALSO 280SEE ALSO
171 <http://freenet.sf.net>. 281 <http://freenet.sf.net>.
172 282
173BUGS 283BUGS

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines