[ViewVC] Annotation of: cvs/cvsroot/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
    $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.

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

    $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.4
Committed:	Mon Sep 8 01:47:31 2003 UTC (20 years, 9 months ago) by root
Branch:	MAIN
Changes since 1.3:	+36 -3 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	root	1.4	$meta = Net::FCP::parse_metadata $string
24			Parse a metadata string and return it.
25
26			The metadata will be a hashref with key "version" (containing the
27			mandatory version header entries).
28
29			All other headers are represented by arrayrefs (they can be
30			repeated).
31
32			Since this is confusing, here is a rather verbose example of a
33			parsed manifest:
34
35			(
36			version => { revision => 1 },
37			document => [
38			{
39			"info.format" => "image/jpeg",
40			name => "background.jpg",
41			"redirect.target" => "freenet:CHK\@ZcagI,ra726bSw"
42			},
43			{
44			"info.format" => "text/html",
45			name => ".next",
46			"redirect.target" => "freenet:SSK\@ilUPAgM/TFEE/3"
47			},
48			{
49			"info.format" => "text/html",
50			"redirect.target" => "freenet:CHK\@8M8Po8ucwI,8xA"
51			}
52			]
53			)
54
55	root	1.2	$fcp = new Net::FCP [host => $host][, port => $port]
56			Create a new virtual FCP connection to the given host and port
57	root	1.3	(default 127.0.0.1:8481, or the environment variables "FREDHOST" and
58			"FREDPORT").
59	root	1.2
60			Connections are virtual because no persistent physical connection is
61			established. However, the existance of the node is checked by
62			executing a "ClientHello" transaction.
63
64			$txn = $fcp->txn(type => attr => val,...)
65			The low-level interface to transactions. Don't use it.
66
67			$txn = $fcp->txn_client_hello
68			$nodehello = $fcp->client_hello
69			Executes a ClientHello request and returns it's results.
70
71			{
72			max_file_size => "5f5e100",
73	root	1.3	node => "Fred,0.6,1.46,7050"
74	root	1.2	protocol => "1.2",
75			}
76
77			$txn = $fcp->txn_client_info
78			$nodeinfo = $fcp->client_info
79			Executes a ClientInfo request and returns it's results.
80
81			{
82			active_jobs => "1f",
83			allocated_memory => "bde0000",
84			architecture => "i386",
85			available_threads => 17,
86	root	1.3	datastore_free => "5ce03400",
87			datastore_max => "2540be400",
88	root	1.2	datastore_used => "1f72bb000",
89	root	1.3	estimated_load => 52,
90			free_memory => "5cc0148",
91	root	1.2	is_transient => "false",
92	root	1.3	java_name => "Java HotSpot(_T_M) Server VM",
93	root	1.2	java_vendor => "http://www.blackdown.org/",
94	root	1.3	java_version => "Blackdown-1.4.1-01",
95			least_recent_timestamp => "f41538b878",
96			max_file_size => "5f5e100",
97	root	1.2	most_recent_timestamp => "f77e2cc520"
98	root	1.3	node_address => "1.2.3.4",
99			node_port => 369,
100			operating_system => "Linux",
101			operating_system_version => "2.4.20",
102			routing_time => "a5",
103	root	1.2	}
104
105			$txn = $fcp->txn_generate_chk ($metadata, $data)
106			$uri = $fcp->generate_chk ($metadata, $data)
107			Creates a new CHK, given the metadata and data. UNTESTED.
108
109			$txn = $fcp->txn_generate_svk_pair
110			($public, $private) = @{ $fcp->generate_svk_pair }
111			Creates a new SVK pair. Returns an arrayref.
112
113			[
114			"hKs0-WDQA4pVZyMPKNFsK1zapWY",
115			"ZnmvMITaTXBMFGl4~jrjuyWxOWg"
116			]
117
118			$txn = $fcp->txn_insert_private_key ($private)
119			$uri = $fcp->insert_private_key ($private)
120			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
122			value you get back from "generate_svk_pair").
123
124			Returns the public key.
125
126			UNTESTED.
127
128			$txn = $fcp->txn_get_size ($uri)
129			$length = $fcp->get_size ($uri)
130			Finds and returns the size (rounded up to the nearest power of two)
131			of the given document.
132
133			UNTESTED.
134
135	root	1.3	$txn = $fcp->txn_client_get ($uri [, $htl = 15 [, $removelocal = 0]])
136	root	1.4	($metadata, $data) = @{ $fcp->client_get ($uri, $htl, $removelocal)
137	root	1.3	Fetches a (small, as it should fit into memory) file from freenet.
138	root	1.4	$meta is the metadata (as returned by "parse_metadata" or "undef").
139	root	1.3
140	root	1.4	Due to the overhead, a better method to download big files should be
141	root	1.3	used.
142
143	root	1.4	my ($meta, $data) = @{
144	root	1.3	$fcp->client_get (
145			"freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w"
146			)
147			};
148
149			MISSING: ClientPut
150	root	1.2
151			THE Net::FCP::Txn CLASS
152			All requests (or transactions) are executed in a asynchroneous way (LIE:
153			uploads are blocking). For each request, a "Net::FCP::Txn" object is
154			created (worse: a tcp connection is created, too).
155
156			For each request there is actually a different subclass (and it's
157			possible to subclass these, although of course not documented).
158
159			The most interesting method is "result".
160	root	1.1
161	root	1.2	new arg => val,...
162			Creates a new "Net::FCP::Txn" object. Not normally used.
163	root	1.1
164	root	1.2	$result = $txn->result
165			Waits until a result is available and then returns it.
166	root	1.1
167	root	1.3	This waiting is (depending on your event model) not very efficient,
168	root	1.2	as it is done outside the "mainloop".
169	root	1.1
170	root	1.2	SEE ALSO
171			<http://freenet.sf.net>.
172	root	1.1
173	root	1.2	BUGS
174	root	1.1	AUTHOR
175			Marc Lehmann <pcg@goof.com>
176			http://www.goof.com/pcg/marc/
177