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 http://freenet.sourceforge.net/index.php?page=fcp 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

http://freenet.sf.net.

BUGS

AUTHOR

 Marc Lehmann <pcg@goof.com>
 http://www.goof.com/pcg/marc/