[ViewVC] Contents 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 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/

Revision:	1.6
Committed:	Wed Sep 10 05:07:16 2003 UTC (23 years ago) by root
Branch:	MAIN
Changes since 1.5:	+42 -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 falls short of what it should provide (intelligent
20	uri following, splitfile downloads, healing...)
21
22	IMPORT TAGS
23	Nothing much can be "imported" from this module right now. There are,
24	however, certain "import tags" that can be used to select the event
25	model to be used.
26
27	Event models are implemented as modules under the "Net::FCP::Event::xyz"
28	class, where "xyz" is the event model to use. The default is "Event" (or
29	later "Auto").
30
31	The import tag to use is named "event=xyz", e.g. "event=Event",
32	"event=Glib" etc.
33
34	You should specify the event module to use only in the main program.
35
36	THE Net::FCP CLASS
37	$meta = Net::FCP::parse_metadata $string
38	Parse a metadata string and return it.
39
40	The metadata will be a hashref with key "version" (containing the
41	mandatory version header entries).
42
43	All other headers are represented by arrayrefs (they can be
44	repeated).
45
46	Since this is confusing, here is a rather verbose example of a
47	parsed manifest:
48
49	(
50	version => { revision => 1 },
51	document => [
52	{
53	"info.format" => "image/jpeg",
54	name => "background.jpg",
55	"redirect.target" => "freenet:CHK\@ZcagI,ra726bSw"
56	},
57	{
58	"info.format" => "text/html",
59	name => ".next",
60	"redirect.target" => "freenet:SSK\@ilUPAgM/TFEE/3"
61	},
62	{
63	"info.format" => "text/html",
64	"redirect.target" => "freenet:CHK\@8M8Po8ucwI,8xA"
65	}
66	]
67	)
68
69	$fcp = new Net::FCP [host => $host][, port => $port]
70	Create a new virtual FCP connection to the given host and port
71	(default 127.0.0.1:8481, or the environment variables "FREDHOST" and
72	"FREDPORT").
73
74	Connections are virtual because no persistent physical connection is
75	established. However, the existance of the node is checked by
76	executing a "ClientHello" transaction.
77
78	$txn = $fcp->txn(type => attr => val,...)
79	The low-level interface to transactions. Don't use it.
80
81	Here are some examples of using transactions:
82
83	The blocking case, no (visible) transactions involved:
84
85	my $nodehello = $fcp->client_hello;
86
87	A transaction used in a blocking fashion:
88
89	my $txn = $fcp->txn_client_hello;
90	...
91	my $nodehello = $txn->result;
92
93	Or shorter:
94
95	my $nodehello = $fcp->txn_client_hello->result;
96
97	Setting callbacks:
98
99	$fcp->txn_client_hello->cb(
100	sub { my $nodehello => $_[0]->result }
101	);
102
103	$txn = $fcp->txn_client_hello
104	$nodehello = $fcp->client_hello
105	Executes a ClientHello request and returns it's results.
106
107	{
108	max_file_size => "5f5e100",
109	node => "Fred,0.6,1.46,7050"
110	protocol => "1.2",
111	}
112
113	$txn = $fcp->txn_client_info
114	$nodeinfo = $fcp->client_info
115	Executes a ClientInfo request and returns it's results.
116
117	{
118	active_jobs => "1f",
119	allocated_memory => "bde0000",
120	architecture => "i386",
121	available_threads => 17,
122	datastore_free => "5ce03400",
123	datastore_max => "2540be400",
124	datastore_used => "1f72bb000",
125	estimated_load => 52,
126	free_memory => "5cc0148",
127	is_transient => "false",
128	java_name => "Java HotSpot(_T_M) Server VM",
129	java_vendor => "http://www.blackdown.org/",
130	java_version => "Blackdown-1.4.1-01",
131	least_recent_timestamp => "f41538b878",
132	max_file_size => "5f5e100",
133	most_recent_timestamp => "f77e2cc520"
134	node_address => "1.2.3.4",
135	node_port => 369,
136	operating_system => "Linux",
137	operating_system_version => "2.4.20",
138	routing_time => "a5",
139	}
140
141	$txn = $fcp->txn_generate_chk ($metadata, $data)
142	$uri = $fcp->generate_chk ($metadata, $data)
143	Creates a new CHK, given the metadata and data. UNTESTED.
144
145	$txn = $fcp->txn_generate_svk_pair
146	($public, $private) = @{ $fcp->generate_svk_pair }
147	Creates a new SVK pair. Returns an arrayref.
148
149	[
150	"hKs0-WDQA4pVZyMPKNFsK1zapWY",
151	"ZnmvMITaTXBMFGl4~jrjuyWxOWg"
152	]
153
154	$txn = $fcp->txn_insert_private_key ($private)
155	$uri = $fcp->insert_private_key ($private)
156	Inserts a private key. $private can be either an insert URI (must
157	start with freenet:SSK@) or a raw private key (i.e. the private
158	value you get back from "generate_svk_pair").
159
160	Returns the public key.
161
162	UNTESTED.
163
164	$txn = $fcp->txn_get_size ($uri)
165	$length = $fcp->get_size ($uri)
166	Finds and returns the size (rounded up to the nearest power of two)
167	of the given document.
168
169	UNTESTED.
170
171	$txn = $fcp->txn_client_get ($uri [, $htl = 15 [, $removelocal = 0]])
172	($metadata, $data) = @{ $fcp->client_get ($uri, $htl, $removelocal)
173	Fetches a (small, as it should fit into memory) file from freenet.
174	$meta is the metadata (as returned by "parse_metadata" or "undef").
175
176	Due to the overhead, a better method to download big files should be
177	used.
178
179	my ($meta, $data) = @{
180	$fcp->client_get (
181	"freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w"
182	)
183	};
184
185	MISSING: ClientPut
186
187	THE Net::FCP::Txn CLASS
188	All requests (or transactions) are executed in a asynchroneous way (LIE:
189	uploads are blocking). For each request, a "Net::FCP::Txn" object is
190	created (worse: a tcp connection is created, too).
191
192	For each request there is actually a different subclass (and it's
193	possible to subclass these, although of course not documented).
194
195	The most interesting method is "result".
196
197	new arg => val,...
198	Creates a new "Net::FCP::Txn" object. Not normally used.
199
200	$txn = $txn->cb ($coderef)
201	Sets a callback to be called when the request is finished. The
202	coderef will be called with the txn as it's sole argument, so it has
203	to call "result" itself.
204
205	Returns the txn object, useful for chaining.
206
207	Example:
208
209	$fcp->txn_client_get ("freenet:CHK....")
210	->userdata ("ehrm")
211	->cb(sub {
212	my $data = shift->result;
213	});
214
215	$txn = $txn->userdata ([$userdata])
216	Set user-specific data. This is useful in progress callbacks. The
217	data can be accessed using "$txn->{userdata}".
218
219	Returns the txn object, useful for chaining.
220
221	$result = $txn->result
222	Waits until a result is available and then returns it.
223
224	This waiting is (depending on your event model) not very efficient,
225	as it is done outside the "mainloop".
226
227	SEE ALSO
228	<http://freenet.sf.net>.
229
230	BUGS
231	AUTHOR
232	Marc Lehmann <pcg@goof.com>
233	http://www.goof.com/pcg/marc/
234