NAME Net::FCP - http://freenet.sf.net client protocol SYNOPSIS use Net::FCP; my $fcp = new Net::FCP; my $ni = $fcp->txn_node_info->result; my $ni = $fcp->node_info; DESCRIPTION See for a description of what the messages do. I am too lazy to document all this here. WARNING This module is alpha. While it probably won't destroy (much :) of your data, it currently falls short of what it should provide (intelligent uri following, splitfile downloads, healing...) IMPORT TAGS Nothing much can be "imported" from this module right now. There are, however, certain "import tags" that can be used to select the event model to be used. Event models are implemented as modules under the "Net::FCP::Event::xyz" class, where "xyz" is the event model to use. The default is "Event" (or later "Auto"). The import tag to use is named "event=xyz", e.g. "event=Event", "event=Glib" etc. You should specify the event module to use only in the main program. THE Net::FCP CLASS $meta = Net::FCP::parse_metadata $string Parse a metadata string and return it. The metadata will be a hashref with key "version" (containing the mandatory version header entries). All other headers are represented by arrayrefs (they can be repeated). Since this is confusing, here is a rather verbose example of a parsed manifest: ( version => { revision => 1 }, document => [ { "info.format" => "image/jpeg", name => "background.jpg", "redirect.target" => "freenet:CHK\@ZcagI,ra726bSw" }, { "info.format" => "text/html", name => ".next", "redirect.target" => "freenet:SSK\@ilUPAgM/TFEE/3" }, { "info.format" => "text/html", "redirect.target" => "freenet:CHK\@8M8Po8ucwI,8xA" } ] ) $fcp = new Net::FCP [host => $host][, port => $port] Create a new virtual FCP connection to the given host and port (default 127.0.0.1:8481, or the environment variables "FREDHOST" and "FREDPORT"). Connections are virtual because no persistent physical connection is established. However, the existance of the node is checked by executing a "ClientHello" transaction. $txn = $fcp->txn(type => attr => val,...) The low-level interface to transactions. Don't use it. Here are some examples of using transactions: The blocking case, no (visible) transactions involved: my $nodehello = $fcp->client_hello; A transaction used in a blocking fashion: my $txn = $fcp->txn_client_hello; ... my $nodehello = $txn->result; Or shorter: my $nodehello = $fcp->txn_client_hello->result; Setting callbacks: $fcp->txn_client_hello->cb( sub { my $nodehello => $_[0]->result } ); $txn = $fcp->txn_client_hello $nodehello = $fcp->client_hello Executes a ClientHello request and returns it's results. { max_file_size => "5f5e100", node => "Fred,0.6,1.46,7050" protocol => "1.2", } $txn = $fcp->txn_client_info $nodeinfo = $fcp->client_info Executes a ClientInfo request and returns it's results. { active_jobs => "1f", allocated_memory => "bde0000", architecture => "i386", available_threads => 17, datastore_free => "5ce03400", datastore_max => "2540be400", datastore_used => "1f72bb000", estimated_load => 52, free_memory => "5cc0148", is_transient => "false", java_name => "Java HotSpot(_T_M) Server VM", java_vendor => "http://www.blackdown.org/", java_version => "Blackdown-1.4.1-01", least_recent_timestamp => "f41538b878", max_file_size => "5f5e100", most_recent_timestamp => "f77e2cc520" node_address => "1.2.3.4", node_port => 369, operating_system => "Linux", operating_system_version => "2.4.20", routing_time => "a5", } $txn = $fcp->txn_generate_chk ($metadata, $data) $uri = $fcp->generate_chk ($metadata, $data) Creates a new CHK, given the metadata and data. UNTESTED. $txn = $fcp->txn_generate_svk_pair ($public, $private) = @{ $fcp->generate_svk_pair } Creates a new SVK pair. Returns an arrayref. [ "hKs0-WDQA4pVZyMPKNFsK1zapWY", "ZnmvMITaTXBMFGl4~jrjuyWxOWg" ] $txn = $fcp->txn_insert_private_key ($private) $uri = $fcp->insert_private_key ($private) Inserts a private key. $private can be either an insert URI (must start with freenet:SSK@) or a raw private key (i.e. the private value you get back from "generate_svk_pair"). Returns the public key. UNTESTED. $txn = $fcp->txn_get_size ($uri) $length = $fcp->get_size ($uri) Finds and returns the size (rounded up to the nearest power of two) of the given document. UNTESTED. $txn = $fcp->txn_client_get ($uri [, $htl = 15 [, $removelocal = 0]]) ($metadata, $data) = @{ $fcp->client_get ($uri, $htl, $removelocal) Fetches a (small, as it should fit into memory) file from freenet. $meta is the metadata (as returned by "parse_metadata" or "undef"). Due to the overhead, a better method to download big files should be used. my ($meta, $data) = @{ $fcp->client_get ( "freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w" ) }; MISSING: ClientPut THE Net::FCP::Txn CLASS All requests (or transactions) are executed in a asynchroneous way (LIE: uploads are blocking). For each request, a "Net::FCP::Txn" object is created (worse: a tcp connection is created, too). For each request there is actually a different subclass (and it's possible to subclass these, although of course not documented). The most interesting method is "result". new arg => val,... Creates a new "Net::FCP::Txn" object. Not normally used. $txn = $txn->cb ($coderef) Sets a callback to be called when the request is finished. The coderef will be called with the txn as it's sole argument, so it has to call "result" itself. Returns the txn object, useful for chaining. Example: $fcp->txn_client_get ("freenet:CHK....") ->userdata ("ehrm") ->cb(sub { my $data = shift->result; }); $txn = $txn->userdata ([$userdata]) Set user-specific data. This is useful in progress callbacks. The data can be accessed using "$txn->{userdata}". Returns the txn object, useful for chaining. $result = $txn->result Waits until a result is available and then returns it. This waiting is (depending on your event model) not very efficient, as it is done outside the "mainloop". SEE ALSO . BUGS AUTHOR Marc Lehmann http://www.goof.com/pcg/marc/