[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 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
    $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) and key "raw" containing the
        original metadata string.

        All other headers are represented by arrayrefs (they can be
        repeated).

        Since this description is confusing, here is a rather verbose
        example of a parsed manifest:

           (
              raw => "Version...",
              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.

    $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[, $cipher])
    $uri = $fcp->generate_chk ($metadata, $data[, $cipher])
        Calculcates 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) = @{ $fcp->generate_svk_pair }
        Creates a new SVK pair. Returns an arrayref.

           [
             "hKs0-WDQA4pVZyMPKNFsK1zapWY",
             "ZnmvMITaTXBMFGl4~jrjuyWxOWg"
           ]

    $txn = $fcp->txn_insert_private_key ($private)
    $public = $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"
             )
          };

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

        $meta can be a reference or a string (ONLY THE STRING CASE IS
        IMPLEMENTED!).

        THIS INTERFACE IS UNTESTED AND SUBJECT TO CHANGE.

    MISSING: (ClientPut), InsretKey

  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.

    $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 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.8
Committed:	Wed Sep 17 05:05:33 2003 UTC (20 years, 9 months ago) by root
Branch:	MAIN
Changes since 1.7:	+13 -6 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	root	1.5	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	root	1.2
36	root	1.8	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	root	1.7	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	root	1.2	THE Net::FCP CLASS
58	root	1.4	$meta = Net::FCP::parse_metadata $string
59			Parse a metadata string and return it.
60
61			The metadata will be a hashref with key "version" (containing the
62	root	1.8	mandatory version header entries) and key "raw" containing the
63			original metadata string.
64	root	1.4
65			All other headers are represented by arrayrefs (they can be
66			repeated).
67
68	root	1.8	Since this description is confusing, here is a rather verbose
69			example of a parsed manifest:
70	root	1.4
71			(
72	root	1.8	raw => "Version...",
73	root	1.4	version => { revision => 1 },
74			document => [
75			{
76	root	1.7	info => { format" => "image/jpeg" },
77	root	1.4	name => "background.jpg",
78	root	1.7	redirect => { target => "freenet:CHK\@ZcagI,ra726bSw" },
79	root	1.4	},
80			{
81	root	1.7	info => { format" => "text/html" },
82	root	1.4	name => ".next",
83	root	1.7	redirect => { target => "freenet:SSK\@ilUPAgM/TFEE/3" },
84	root	1.4	},
85			{
86	root	1.7	info => { format" => "text/html" },
87			redirect => { target => "freenet:CHK\@8M8Po8ucwI,8xA" },
88	root	1.4	}
89			]
90			)
91
92	root	1.2	$fcp = new Net::FCP [host => $host][, port => $port]
93			Create a new virtual FCP connection to the given host and port
94	root	1.3	(default 127.0.0.1:8481, or the environment variables "FREDHOST" and
95			"FREDPORT").
96	root	1.2
97			Connections are virtual because no persistent physical connection is
98	root	1.7	established.
99	root	1.2
100			$txn = $fcp->txn(type => attr => val,...)
101			The low-level interface to transactions. Don't use it.
102
103	root	1.6	Here are some examples of using transactions:
104
105			The blocking case, no (visible) transactions involved:
106
107			my $nodehello = $fcp->client_hello;
108
109			A transaction used in a blocking fashion:
110
111			my $txn = $fcp->txn_client_hello;
112			...
113			my $nodehello = $txn->result;
114
115			Or shorter:
116
117			my $nodehello = $fcp->txn_client_hello->result;
118
119			Setting callbacks:
120
121			$fcp->txn_client_hello->cb(
122			sub { my $nodehello => $_[0]->result }
123			);
124
125	root	1.2	$txn = $fcp->txn_client_hello
126			$nodehello = $fcp->client_hello
127			Executes a ClientHello request and returns it's results.
128
129			{
130			max_file_size => "5f5e100",
131	root	1.3	node => "Fred,0.6,1.46,7050"
132	root	1.2	protocol => "1.2",
133			}
134
135			$txn = $fcp->txn_client_info
136			$nodeinfo = $fcp->client_info
137			Executes a ClientInfo request and returns it's results.
138
139			{
140			active_jobs => "1f",
141			allocated_memory => "bde0000",
142			architecture => "i386",
143			available_threads => 17,
144	root	1.3	datastore_free => "5ce03400",
145			datastore_max => "2540be400",
146	root	1.2	datastore_used => "1f72bb000",
147	root	1.3	estimated_load => 52,
148			free_memory => "5cc0148",
149	root	1.2	is_transient => "false",
150	root	1.3	java_name => "Java HotSpot(_T_M) Server VM",
151	root	1.2	java_vendor => "http://www.blackdown.org/",
152	root	1.3	java_version => "Blackdown-1.4.1-01",
153			least_recent_timestamp => "f41538b878",
154			max_file_size => "5f5e100",
155	root	1.2	most_recent_timestamp => "f77e2cc520"
156	root	1.3	node_address => "1.2.3.4",
157			node_port => 369,
158			operating_system => "Linux",
159			operating_system_version => "2.4.20",
160			routing_time => "a5",
161	root	1.2	}
162
163	root	1.8	$txn = $fcp->txn_generate_chk ($metadata, $data[, $cipher])
164			$uri = $fcp->generate_chk ($metadata, $data[, $cipher])
165			Calculcates a CHK, given the metadata and data. $cipher is either
166			"Rijndael" or "Twofish", with the latter being the default.
167	root	1.2
168			$txn = $fcp->txn_generate_svk_pair
169			($public, $private) = @{ $fcp->generate_svk_pair }
170			Creates a new SVK pair. Returns an arrayref.
171
172			[
173			"hKs0-WDQA4pVZyMPKNFsK1zapWY",
174			"ZnmvMITaTXBMFGl4~jrjuyWxOWg"
175			]
176
177			$txn = $fcp->txn_insert_private_key ($private)
178	root	1.7	$public = $fcp->insert_private_key ($private)
179	root	1.2	Inserts a private key. $private can be either an insert URI (must
180	root	1.7	start with "freenet:SSK@") or a raw private key (i.e. the private
181	root	1.2	value you get back from "generate_svk_pair").
182
183			Returns the public key.
184
185			UNTESTED.
186
187			$txn = $fcp->txn_get_size ($uri)
188			$length = $fcp->get_size ($uri)
189			Finds and returns the size (rounded up to the nearest power of two)
190			of the given document.
191
192			UNTESTED.
193
194	root	1.3	$txn = $fcp->txn_client_get ($uri [, $htl = 15 [, $removelocal = 0]])
195	root	1.4	($metadata, $data) = @{ $fcp->client_get ($uri, $htl, $removelocal)
196	root	1.3	Fetches a (small, as it should fit into memory) file from freenet.
197	root	1.4	$meta is the metadata (as returned by "parse_metadata" or "undef").
198	root	1.3
199	root	1.4	Due to the overhead, a better method to download big files should be
200	root	1.3	used.
201
202	root	1.4	my ($meta, $data) = @{
203	root	1.3	$fcp->client_get (
204			"freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w"
205			)
206			};
207
208	root	1.7	$txn = $fcp->txn_client_put ($uri, $metadata, $data, $htl, $removelocal)
209			my $uri = $fcp->client_put ($uri, $metadata, $data, $htl, $removelocal);
210			Insert a new key. If the client is inserting a CHK, the URI may be
211			abbreviated as just CHK@. In this case, the node will calculate the
212			CHK.
213
214			$meta can be a reference or a string (ONLY THE STRING CASE IS
215			IMPLEMENTED!).
216
217			THIS INTERFACE IS UNTESTED AND SUBJECT TO CHANGE.
218
219			MISSING: (ClientPut), InsretKey
220	root	1.2
221			THE Net::FCP::Txn CLASS
222			All requests (or transactions) are executed in a asynchroneous way (LIE:
223			uploads are blocking). For each request, a "Net::FCP::Txn" object is
224			created (worse: a tcp connection is created, too).
225
226			For each request there is actually a different subclass (and it's
227			possible to subclass these, although of course not documented).
228
229			The most interesting method is "result".
230	root	1.1
231	root	1.2	new arg => val,...
232			Creates a new "Net::FCP::Txn" object. Not normally used.
233	root	1.5
234	root	1.6	$txn = $txn->cb ($coderef)
235			Sets a callback to be called when the request is finished. The
236			coderef will be called with the txn as it's sole argument, so it has
237			to call "result" itself.
238
239			Returns the txn object, useful for chaining.
240
241			Example:
242
243			$fcp->txn_client_get ("freenet:CHK....")
244			->userdata ("ehrm")
245			->cb(sub {
246			my $data = shift->result;
247			});
248
249			$txn = $txn->userdata ([$userdata])
250			Set user-specific data. This is useful in progress callbacks. The
251			data can be accessed using "$txn->{userdata}".
252
253			Returns the txn object, useful for chaining.
254	root	1.1
255	root	1.7	$txn->cancel (%attr)
256			Cancels the operation with a "cancel" exception anf the given
257			attributes (consider at least giving the attribute "reason").
258
259			UNTESTED.
260
261	root	1.2	$result = $txn->result
262			Waits until a result is available and then returns it.
263	root	1.1
264	root	1.3	This waiting is (depending on your event model) not very efficient,
265	root	1.2	as it is done outside the "mainloop".
266	root	1.7
267			The Net::FCP::Exception CLASS
268			Any unexpected (non-standard) responses that make it impossible to
269			return the advertised result will result in an exception being thrown
270			when the "result" method is called.
271
272			These exceptions are represented by objects of this class.
273
274			$exc = new Net::FCP::Exception $type, \%attr
275			Create a new exception object of the given type (a string like
276			"route_not_found"), and a hashref containing additional attributes
277			(usually the attributes of the message causing the exception).
278
279			$exc->type([$type])
280			With no arguments, returns the exception type. Otherwise a boolean
281			indicating wether the exception is of the given type is returned.
282
283			$exc->attr([$attr])
284			With no arguments, returns the attributes. Otherwise the named
285			attribute value is returned.
286	root	1.1
287	root	1.2	SEE ALSO
288			<http://freenet.sf.net>.
289	root	1.1
290	root	1.2	BUGS
291	root	1.1	AUTHOR
292			Marc Lehmann <pcg@goof.com>
293			http://www.goof.com/pcg/marc/
294