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.6 by root, Wed Sep 10 05:07:16 2003 UTC vs.
Revision 1.7 by root, Sun Sep 14 09:48:01 2003 UTC

… …
31 The import tag to use is named "event=xyz", e.g. "event=Event", 31 The import tag to use is named "event=xyz", e.g. "event=Event",
32 "event=Glib" etc. 32 "event=Glib" etc.
33 33
34 You should specify the event module to use only in the main program. 34 You should specify the event module to use only in the main program.
35 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.
52
36 THE Net::FCP CLASS 53 THE Net::FCP CLASS
37 $meta = Net::FCP::parse_metadata $string 54 $meta = Net::FCP::parse_metadata $string
38 Parse a metadata string and return it. 55 Parse a metadata string and return it.
39 56
40 The metadata will be a hashref with key "version" (containing the 57 The metadata will be a hashref with key "version" (containing the
… …
48 65
49 ( 66 (
50 version => { revision => 1 }, 67 version => { revision => 1 },
51 document => [ 68 document => [
52 { 69 {
53 "info.format" => "image/jpeg", 70 info => { format" => "image/jpeg" },
54 name => "background.jpg", 71 name => "background.jpg",
55 "redirect.target" => "freenet:CHK\@ZcagI,ra726bSw" 72 redirect => { target => "freenet:CHK\@ZcagI,ra726bSw" },
56 }, 73 },
57 { 74 {
58 "info.format" => "text/html", 75 info => { format" => "text/html" },
59 name => ".next", 76 name => ".next",
60 "redirect.target" => "freenet:SSK\@ilUPAgM/TFEE/3" 77 redirect => { target => "freenet:SSK\@ilUPAgM/TFEE/3" },
61 }, 78 },
62 { 79 {
63 "info.format" => "text/html", 80 info => { format" => "text/html" },
64 "redirect.target" => "freenet:CHK\@8M8Po8ucwI,8xA" 81 redirect => { target => "freenet:CHK\@8M8Po8ucwI,8xA" },
65 } 82 }
66 ] 83 ]
67 ) 84 )
68 85
69 $fcp = new Net::FCP [host => $host][, port => $port] 86 $fcp = new Net::FCP [host => $host][, port => $port]
70 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
71 (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
72 "FREDPORT"). 89 "FREDPORT").
73 90
74 Connections are virtual because no persistent physical connection is 91 Connections are virtual because no persistent physical connection is
75 established. However, the existance of the node is checked by 92 established.
76 executing a "ClientHello" transaction.
77 93
78 $txn = $fcp->txn(type => attr => val,...) 94 $txn = $fcp->txn(type => attr => val,...)
79 The low-level interface to transactions. Don't use it. 95 The low-level interface to transactions. Don't use it.
80 96
81 Here are some examples of using transactions: 97 Here are some examples of using transactions:
… …
150 "hKs0-WDQA4pVZyMPKNFsK1zapWY", 166 "hKs0-WDQA4pVZyMPKNFsK1zapWY",
151 "ZnmvMITaTXBMFGl4~jrjuyWxOWg" 167 "ZnmvMITaTXBMFGl4~jrjuyWxOWg"
152 ] 168 ]
153 169
154 $txn = $fcp->txn_insert_private_key ($private) 170 $txn = $fcp->txn_insert_private_key ($private)
155 $uri = $fcp->insert_private_key ($private) 171 $public = $fcp->insert_private_key ($private)
156 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
157 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
158 value you get back from "generate_svk_pair"). 174 value you get back from "generate_svk_pair").
159 175
160 Returns the public key. 176 Returns the public key.
161 177
162 UNTESTED. 178 UNTESTED.
… …
180 $fcp->client_get ( 196 $fcp->client_get (
181 "freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w" 197 "freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w"
182 ) 198 )
183 }; 199 };
184 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
185 MISSING: ClientPut 212 MISSING: (ClientPut), InsretKey
186 213
187 THE Net::FCP::Txn CLASS 214 THE Net::FCP::Txn CLASS
188 All requests (or transactions) are executed in a asynchroneous way (LIE: 215 All requests (or transactions) are executed in a asynchroneous way (LIE:
189 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
190 created (worse: a tcp connection is created, too). 217 created (worse: a tcp connection is created, too).
… …
216 Set user-specific data. This is useful in progress callbacks. The 243 Set user-specific data. This is useful in progress callbacks. The
217 data can be accessed using "$txn->{userdata}". 244 data can be accessed using "$txn->{userdata}".
218 245
219 Returns the txn object, useful for chaining. 246 Returns the txn object, useful for chaining.
220 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
221 $result = $txn->result 254 $result = $txn->result
222 Waits until a result is available and then returns it. 255 Waits until a result is available and then returns it.
223 256
224 This waiting is (depending on your event model) not very efficient, 257 This waiting is (depending on your event model) not very efficient,
225 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.
226 279
227SEE ALSO 280SEE ALSO
228 <http://freenet.sf.net>. 281 <http://freenet.sf.net>.
229 282
230BUGS 283BUGS

Diff Legend

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