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

    If no event model has been specified, FCP tries to autodetect it on
    first use (e.g. first transaction), in this order: Coro, Event, Glib,
    Tk.

  FREENET BASICS
    Ok, this section will not explain any freenet basics to you, just some
    problems I found that you might want to avoid:

    freenet URIs are _NOT_ URIs
        Whenever a "uri" is required by the protocol, freenet expects a kind
        of URI prefixed with the "freenet:" scheme, e.g. "freenet:CHK...".
        However, these are not URIs, as freeent fails to parse them
        correctly, that is, you must unescape an escaped characters ("%2c"
        => ",") yourself. Maybe in the future this library will do it for
        you, so watch out for this incompatible change.

    Numbers are in HEX
        Virtually every number in the FCP protocol is in hex. Be sure to use
        "hex()" on all such numbers, as the module (currently) does nothing
        to convert these for you.

  THE Net::FCP CLASS
    $fcp = new Net::FCP [host => $host][, port => $port][, progress => \&cb]
        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.

        You can install a progress callback that is being called with the
        Net::FCP object, a txn object, the type of the transaction and the
        attributes. Use it like this:

           sub progress_cb {
              my ($self, $txn, $type, $attr) = @_;

              warn "progress<$txn,$type," . (join ":", %$attr) . ">\n";
           }

    $txn = $fcp->txn (type => attr => val,...)
        The low-level interface to transactions. Don't use it unless you
        have "special needs". Instead, use predefiend transactions like
        this:

        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[, $cipher])
    $uri = $fcp->generate_chk ($metadata, $data[, $cipher])
        Calculates a CHK, given the metadata and data. $cipher is either
        "Rijndael" or "Twofish", with the latter being the default.

    $txn = $fcp->txn_generate_svk_pair
    ($public, $private, $crypto) = @{ $fcp->generate_svk_pair }
        Creates a new SVK pair. Returns an arrayref with the public key, the
        private key and a crypto key, which is just additional entropy.

           [
             "acLx4dux9fvvABH15Gk6~d3I-yw",
             "cPoDkDMXDGSMM32plaPZDhJDxSs",
             "BH7LXCov0w51-y9i~BoB3g",
           ]

        A private key (for inserting) can be constructed like this:

           SSK@<private_key>,<crypto_key>/<name>

        It can be used to insert data. The corresponding public key looks
        like this:

           SSK@<public_key>PAgM,<crypto_key>/<name>

        Watch out for the "PAgM"-part!

    $txn = $fcp->txn_invert_private_key ($private)
    $public = $fcp->invert_private_key ($private)
        Inverts a private key (returns the public 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.

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

    $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) key content block
        from freenet. $meta is a "Net::FCP::Metadata" object or "undef").

        The $uri should begin with "freenet:", but the scheme is currently
        added, if missing.

          my ($meta, $data) = @{
             $fcp->client_get (
                "freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w"
             )
          };

    $txn = $fcp->txn_client_put ($uri, $metadata, $data, $htl, $removelocal)
    my $uri = $fcp->client_put ($uri, $metadata, $data, $htl, $removelocal);
        Insert a new key. If the client is inserting a CHK, the URI may be
        abbreviated as just CHK@. In this case, the node will calculate the
        CHK. If the key is a private SSK key, the node will calculcate the
        public key and the resulting public URI.

        $meta can be a hash reference (same format as returned by
        "Net::FCP::parse_metadata") or a string.

        The result is an arrayref with the keys "uri", "public_key" and
        "private_key".

  THE Net::FCP::Txn CLASS
    All requests (or transactions) are executed in a asynchronous way. 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.

    $txn->cancel (%attr)
        Cancels the operation with a "cancel" exception anf the given
        attributes (consider at least giving the attribute "reason").

        UNTESTED.

    $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". The biggest problem, however,
        is that it's blocking one thread of execution. Try to use the
        callback mechanism, if possible, and call result from within the
        callback (or after is has been run), as then no waiting is
        necessary.

  The Net::FCP::Exception CLASS
    Any unexpected (non-standard) responses that make it impossible to
    return the advertised result will result in an exception being thrown
    when the "result" method is called.

    These exceptions are represented by objects of this class.

    $exc = new Net::FCP::Exception $type, \%attr
        Create a new exception object of the given type (a string like
        "route_not_found"), and a hashref containing additional attributes
        (usually the attributes of the message causing the exception).

    $exc->type([$type])
        With no arguments, returns the exception type. Otherwise a boolean
        indicating wether the exception is of the given type is returned.

    $exc->attr([$attr])
        With no arguments, returns the attributes. Otherwise the named
        attribute value is returned.

SEE ALSO
    <http://freenet.sf.net>.

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

Revision:	1.11
Committed:	Tue May 18 13:45:05 2004 UTC (22 years, 4 months ago) by root
Branch:	MAIN
Changes since 1.10:	+7 -49 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	If no event model has been specified, FCP tries to autodetect it on
37	first use (e.g. first transaction), in this order: Coro, Event, Glib,
38	Tk.
39
40	FREENET BASICS
41	Ok, this section will not explain any freenet basics to you, just some
42	problems I found that you might want to avoid:
43
44	freenet URIs are _NOT_ URIs
45	Whenever a "uri" is required by the protocol, freenet expects a kind
46	of URI prefixed with the "freenet:" scheme, e.g. "freenet:CHK...".
47	However, these are not URIs, as freeent fails to parse them
48	correctly, that is, you must unescape an escaped characters ("%2c"
49	=> ",") yourself. Maybe in the future this library will do it for
50	you, so watch out for this incompatible change.
51
52	Numbers are in HEX
53	Virtually every number in the FCP protocol is in hex. Be sure to use
54	"hex()" on all such numbers, as the module (currently) does nothing
55	to convert these for you.
56
57	THE Net::FCP CLASS
58	$fcp = new Net::FCP [host => $host][, port => $port][, progress => \&cb]
59	Create a new virtual FCP connection to the given host and port
60	(default 127.0.0.1:8481, or the environment variables "FREDHOST" and
61	"FREDPORT").
62
63	Connections are virtual because no persistent physical connection is
64	established.
65
66	You can install a progress callback that is being called with the
67	Net::FCP object, a txn object, the type of the transaction and the
68	attributes. Use it like this:
69
70	sub progress_cb {
71	my ($self, $txn, $type, $attr) = @_;
72
73	warn "progress<$txn,$type," . (join ":", %$attr) . ">\n";
74	}
75
76	$txn = $fcp->txn (type => attr => val,...)
77	The low-level interface to transactions. Don't use it unless you
78	have "special needs". Instead, use predefiend transactions like
79	this:
80
81	The blocking case, no (visible) transactions involved:
82
83	my $nodehello = $fcp->client_hello;
84
85	A transaction used in a blocking fashion:
86
87	my $txn = $fcp->txn_client_hello;
88	...
89	my $nodehello = $txn->result;
90
91	Or shorter:
92
93	my $nodehello = $fcp->txn_client_hello->result;
94
95	Setting callbacks:
96
97	$fcp->txn_client_hello->cb(
98	sub { my $nodehello => $_[0]->result }
99	);
100
101	$txn = $fcp->txn_client_hello
102	$nodehello = $fcp->client_hello
103	Executes a ClientHello request and returns it's results.
104
105	{
106	max_file_size => "5f5e100",
107	node => "Fred,0.6,1.46,7050"
108	protocol => "1.2",
109	}
110
111	$txn = $fcp->txn_client_info
112	$nodeinfo = $fcp->client_info
113	Executes a ClientInfo request and returns it's results.
114
115	{
116	active_jobs => "1f",
117	allocated_memory => "bde0000",
118	architecture => "i386",
119	available_threads => 17,
120	datastore_free => "5ce03400",
121	datastore_max => "2540be400",
122	datastore_used => "1f72bb000",
123	estimated_load => 52,
124	free_memory => "5cc0148",
125	is_transient => "false",
126	java_name => "Java HotSpot(_T_M) Server VM",
127	java_vendor => "http://www.blackdown.org/",
128	java_version => "Blackdown-1.4.1-01",
129	least_recent_timestamp => "f41538b878",
130	max_file_size => "5f5e100",
131	most_recent_timestamp => "f77e2cc520"
132	node_address => "1.2.3.4",
133	node_port => 369,
134	operating_system => "Linux",
135	operating_system_version => "2.4.20",
136	routing_time => "a5",
137	}
138
139	$txn = $fcp->txn_generate_chk ($metadata, $data[, $cipher])
140	$uri = $fcp->generate_chk ($metadata, $data[, $cipher])
141	Calculates a CHK, given the metadata and data. $cipher is either
142	"Rijndael" or "Twofish", with the latter being the default.
143
144	$txn = $fcp->txn_generate_svk_pair
145	($public, $private, $crypto) = @{ $fcp->generate_svk_pair }
146	Creates a new SVK pair. Returns an arrayref with the public key, the
147	private key and a crypto key, which is just additional entropy.
148
149	[
150	"acLx4dux9fvvABH15Gk6~d3I-yw",
151	"cPoDkDMXDGSMM32plaPZDhJDxSs",
152	"BH7LXCov0w51-y9i~BoB3g",
153	]
154
155	A private key (for inserting) can be constructed like this:
156
157	SSK@<private_key>,<crypto_key>/<name>
158
159	It can be used to insert data. The corresponding public key looks
160	like this:
161
162	SSK@<public_key>PAgM,<crypto_key>/<name>
163
164	Watch out for the "PAgM"-part!
165
166	$txn = $fcp->txn_invert_private_key ($private)
167	$public = $fcp->invert_private_key ($private)
168	Inverts a private key (returns the public key). $private can be
169	either an insert URI (must start with "freenet:SSK@") or a raw
170	private key (i.e. the private value you get back from
171	"generate_svk_pair").
172
173	Returns the public key.
174
175	$txn = $fcp->txn_get_size ($uri)
176	$length = $fcp->get_size ($uri)
177	Finds and returns the size (rounded up to the nearest power of two)
178	of the given document.
179
180	$txn = $fcp->txn_client_get ($uri [, $htl = 15 [, $removelocal = 0]])
181	($metadata, $data) = @{ $fcp->client_get ($uri, $htl, $removelocal)
182	Fetches a (small, as it should fit into memory) key content block
183	from freenet. $meta is a "Net::FCP::Metadata" object or "undef").
184
185	The $uri should begin with "freenet:", but the scheme is currently
186	added, if missing.
187
188	my ($meta, $data) = @{
189	$fcp->client_get (
190	"freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w"
191	)
192	};
193
194	$txn = $fcp->txn_client_put ($uri, $metadata, $data, $htl, $removelocal)
195	my $uri = $fcp->client_put ($uri, $metadata, $data, $htl, $removelocal);
196	Insert a new key. If the client is inserting a CHK, the URI may be
197	abbreviated as just CHK@. In this case, the node will calculate the
198	CHK. If the key is a private SSK key, the node will calculcate the
199	public key and the resulting public URI.
200
201	$meta can be a hash reference (same format as returned by
202	"Net::FCP::parse_metadata") or a string.
203
204	The result is an arrayref with the keys "uri", "public_key" and
205	"private_key".
206
207	THE Net::FCP::Txn CLASS
208	All requests (or transactions) are executed in a asynchronous way. For
209	each request, a "Net::FCP::Txn" object is created (worse: a tcp
210	connection is created, too).
211
212	For each request there is actually a different subclass (and it's
213	possible to subclass these, although of course not documented).
214
215	The most interesting method is "result".
216
217	new arg => val,...
218	Creates a new "Net::FCP::Txn" object. Not normally used.
219
220	$txn = $txn->cb ($coderef)
221	Sets a callback to be called when the request is finished. The
222	coderef will be called with the txn as it's sole argument, so it has
223	to call "result" itself.
224
225	Returns the txn object, useful for chaining.
226
227	Example:
228
229	$fcp->txn_client_get ("freenet:CHK....")
230	->userdata ("ehrm")
231	->cb(sub {
232	my $data = shift->result;
233	});
234
235	$txn = $txn->userdata ([$userdata])
236	Set user-specific data. This is useful in progress callbacks. The
237	data can be accessed using "$txn->{userdata}".
238
239	Returns the txn object, useful for chaining.
240
241	$txn->cancel (%attr)
242	Cancels the operation with a "cancel" exception anf the given
243	attributes (consider at least giving the attribute "reason").
244
245	UNTESTED.
246
247	$result = $txn->result
248	Waits until a result is available and then returns it.
249
250	This waiting is (depending on your event model) not very efficient,
251	as it is done outside the "mainloop". The biggest problem, however,
252	is that it's blocking one thread of execution. Try to use the
253	callback mechanism, if possible, and call result from within the
254	callback (or after is has been run), as then no waiting is
255	necessary.
256
257	The Net::FCP::Exception CLASS
258	Any unexpected (non-standard) responses that make it impossible to
259	return the advertised result will result in an exception being thrown
260	when the "result" method is called.
261
262	These exceptions are represented by objects of this class.
263
264	$exc = new Net::FCP::Exception $type, \%attr
265	Create a new exception object of the given type (a string like
266	"route_not_found"), and a hashref containing additional attributes
267	(usually the attributes of the message causing the exception).
268
269	$exc->type([$type])
270	With no arguments, returns the exception type. Otherwise a boolean
271	indicating wether the exception is of the given type is returned.
272
273	$exc->attr([$attr])
274	With no arguments, returns the attributes. Otherwise the named
275	attribute value is returned.
276
277	SEE ALSO
278	<http://freenet.sf.net>.
279
280	BUGS
281	AUTHOR
282	Marc Lehmann <pcg@goof.com>
283	http://www.goof.com/pcg/marc/
284