[ViewVC] Annotation of: cvs/Net-FCP/README

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 works only with the Event module (alkthough the event
    mechanism is fully pluggable).

  THE Net::FCP CLASS
    $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.

    $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]])
    ($data, $metadata) = @{ $fcp->client_get ($uri, $htl, $removelocal)
        Fetches a (small, as it should fit into memory) file from freenet.

        Due to the overhead, a better method to download big fiels should be
        used.

          my ($data, $meta) = @{
             $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.

    $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/

Revision:	1.3
Committed:	Mon Sep 8 00:36:45 2003 UTC (23 years ago) by root
Branch:	MAIN
Changes since 1.2:	+31 -17 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	NAME
2			Net::FCP - http://freenet.sf.net client protocol
3
4			SYNOPSIS
5			use Net::FCP;
6
7			my $fcp = new Net::FCP;
8
9	root	1.2	my $ni = $fcp->txn_node_info->result;
10			my $ni = $fcp->node_info;
11
12	root	1.1	DESCRIPTION
13	root	1.2	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
15			here.
16
17			WARNING
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
20			mechanism is fully pluggable).
21
22			THE Net::FCP CLASS
23			$fcp = new Net::FCP [host => $host][, port => $port]
24			Create a new virtual FCP connection to the given host and port
25	root	1.3	(default 127.0.0.1:8481, or the environment variables "FREDHOST" and
26			"FREDPORT").
27	root	1.2
28			Connections are virtual because no persistent physical connection is
29			established. However, the existance of the node is checked by
30			executing a "ClientHello" transaction.
31
32			$txn = $fcp->txn(type => attr => val,...)
33			The low-level interface to transactions. Don't use it.
34
35			$txn = $fcp->txn_client_hello
36			$nodehello = $fcp->client_hello
37			Executes a ClientHello request and returns it's results.
38
39			{
40			max_file_size => "5f5e100",
41	root	1.3	node => "Fred,0.6,1.46,7050"
42	root	1.2	protocol => "1.2",
43			}
44
45			$txn = $fcp->txn_client_info
46			$nodeinfo = $fcp->client_info
47			Executes a ClientInfo request and returns it's results.
48
49			{
50			active_jobs => "1f",
51			allocated_memory => "bde0000",
52			architecture => "i386",
53			available_threads => 17,
54	root	1.3	datastore_free => "5ce03400",
55			datastore_max => "2540be400",
56	root	1.2	datastore_used => "1f72bb000",
57	root	1.3	estimated_load => 52,
58			free_memory => "5cc0148",
59	root	1.2	is_transient => "false",
60	root	1.3	java_name => "Java HotSpot(_T_M) Server VM",
61	root	1.2	java_vendor => "http://www.blackdown.org/",
62	root	1.3	java_version => "Blackdown-1.4.1-01",
63			least_recent_timestamp => "f41538b878",
64			max_file_size => "5f5e100",
65	root	1.2	most_recent_timestamp => "f77e2cc520"
66	root	1.3	node_address => "1.2.3.4",
67			node_port => 369,
68			operating_system => "Linux",
69			operating_system_version => "2.4.20",
70			routing_time => "a5",
71	root	1.2	}
72
73			$txn = $fcp->txn_generate_chk ($metadata, $data)
74			$uri = $fcp->generate_chk ($metadata, $data)
75			Creates a new CHK, given the metadata and data. UNTESTED.
76
77			$txn = $fcp->txn_generate_svk_pair
78			($public, $private) = @{ $fcp->generate_svk_pair }
79			Creates a new SVK pair. Returns an arrayref.
80
81			[
82			"hKs0-WDQA4pVZyMPKNFsK1zapWY",
83			"ZnmvMITaTXBMFGl4~jrjuyWxOWg"
84			]
85
86			$txn = $fcp->txn_insert_private_key ($private)
87			$uri = $fcp->insert_private_key ($private)
88			Inserts a private key. $private can be either an insert URI (must
89			start with freenet:SSK@) or a raw private key (i.e. the private
90			value you get back from "generate_svk_pair").
91
92			Returns the public key.
93
94			UNTESTED.
95
96			$txn = $fcp->txn_get_size ($uri)
97			$length = $fcp->get_size ($uri)
98			Finds and returns the size (rounded up to the nearest power of two)
99			of the given document.
100
101			UNTESTED.
102
103	root	1.3	$txn = $fcp->txn_client_get ($uri [, $htl = 15 [, $removelocal = 0]])
104			($data, $metadata) = @{ $fcp->client_get ($uri, $htl, $removelocal)
105			Fetches a (small, as it should fit into memory) file from freenet.
106
107			Due to the overhead, a better method to download big fiels should be
108			used.
109
110			my ($data, $meta) = @{
111			$fcp->client_get (
112			"freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w"
113			)
114			};
115
116			MISSING: ClientPut
117	root	1.2
118			THE Net::FCP::Txn CLASS
119			All requests (or transactions) are executed in a asynchroneous way (LIE:
120			uploads are blocking). For each request, a "Net::FCP::Txn" object is
121			created (worse: a tcp connection is created, too).
122
123			For each request there is actually a different subclass (and it's
124			possible to subclass these, although of course not documented).
125
126			The most interesting method is "result".
127	root	1.1
128	root	1.2	new arg => val,...
129			Creates a new "Net::FCP::Txn" object. Not normally used.
130	root	1.1
131	root	1.2	$result = $txn->result
132			Waits until a result is available and then returns it.
133	root	1.1
134	root	1.3	This waiting is (depending on your event model) not very efficient,
135	root	1.2	as it is done outside the "mainloop".
136	root	1.1
137	root	1.2	SEE ALSO
138			<http://freenet.sf.net>.
139	root	1.1
140	root	1.2	BUGS
141	root	1.1	AUTHOR
142			Marc Lehmann <pcg@goof.com>
143			http://www.goof.com/pcg/marc/
144