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

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

        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.

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