[ViewVC] Contents 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 *
#	Content
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	my $ni = $fcp->txn_node_info->result;
10	my $ni = $fcp->node_info;
11
12	DESCRIPTION
13	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	$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	$fcp = new Net::FCP [host => $host][, port => $port]
56	Create a new virtual FCP connection to the given host and port
57	(default 127.0.0.1:8481, or the environment variables "FREDHOST" and
58	"FREDPORT").
59
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	node => "Fred,0.6,1.46,7050"
74	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	datastore_free => "5ce03400",
87	datastore_max => "2540be400",
88	datastore_used => "1f72bb000",
89	estimated_load => 52,
90	free_memory => "5cc0148",
91	is_transient => "false",
92	java_name => "Java HotSpot(_T_M) Server VM",
93	java_vendor => "http://www.blackdown.org/",
94	java_version => "Blackdown-1.4.1-01",
95	least_recent_timestamp => "f41538b878",
96	max_file_size => "5f5e100",
97	most_recent_timestamp => "f77e2cc520"
98	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	}
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	$txn = $fcp->txn_client_get ($uri [, $htl = 15 [, $removelocal = 0]])
136	($metadata, $data) = @{ $fcp->client_get ($uri, $htl, $removelocal)
137	Fetches a (small, as it should fit into memory) file from freenet.
138	$meta is the metadata (as returned by "parse_metadata" or "undef").
139
140	Due to the overhead, a better method to download big files should be
141	used.
142
143	my ($meta, $data) = @{
144	$fcp->client_get (
145	"freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w"
146	)
147	};
148
149	MISSING: ClientPut
150
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
161	new arg => val,...
162	Creates a new "Net::FCP::Txn" object. Not normally used.
163
164	$result = $txn->result
165	Waits until a result is available and then returns it.
166
167	This waiting is (depending on your event model) not very efficient,
168	as it is done outside the "mainloop".
169
170	SEE ALSO
171	<http://freenet.sf.net>.
172
173	BUGS
174	AUTHOR
175	Marc Lehmann <pcg@goof.com>
176	http://www.goof.com/pcg/marc/
177