[ViewVC] Annotation 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 *
#	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			THE Net::FCP CLASS
37	root	1.4	$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	root	1.2	$fcp = new Net::FCP [host => $host][, port => $port]
70			Create a new virtual FCP connection to the given host and port
71	root	1.3	(default 127.0.0.1:8481, or the environment variables "FREDHOST" and
72			"FREDPORT").
73	root	1.2
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	root	1.6	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	root	1.2	$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	root	1.3	node => "Fred,0.6,1.46,7050"
110	root	1.2	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	root	1.3	datastore_free => "5ce03400",
123			datastore_max => "2540be400",
124	root	1.2	datastore_used => "1f72bb000",
125	root	1.3	estimated_load => 52,
126			free_memory => "5cc0148",
127	root	1.2	is_transient => "false",
128	root	1.3	java_name => "Java HotSpot(_T_M) Server VM",
129	root	1.2	java_vendor => "http://www.blackdown.org/",
130	root	1.3	java_version => "Blackdown-1.4.1-01",
131			least_recent_timestamp => "f41538b878",
132			max_file_size => "5f5e100",
133	root	1.2	most_recent_timestamp => "f77e2cc520"
134	root	1.3	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	root	1.2	}
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	root	1.3	$txn = $fcp->txn_client_get ($uri [, $htl = 15 [, $removelocal = 0]])
172	root	1.4	($metadata, $data) = @{ $fcp->client_get ($uri, $htl, $removelocal)
173	root	1.3	Fetches a (small, as it should fit into memory) file from freenet.
174	root	1.4	$meta is the metadata (as returned by "parse_metadata" or "undef").
175	root	1.3
176	root	1.4	Due to the overhead, a better method to download big files should be
177	root	1.3	used.
178
179	root	1.4	my ($meta, $data) = @{
180	root	1.3	$fcp->client_get (
181			"freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w"
182			)
183			};
184
185			MISSING: ClientPut
186	root	1.2
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	root	1.1
197	root	1.2	new arg => val,...
198			Creates a new "Net::FCP::Txn" object. Not normally used.
199	root	1.5
200	root	1.6	$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	root	1.1
221	root	1.2	$result = $txn->result
222			Waits until a result is available and then returns it.
223	root	1.1
224	root	1.3	This waiting is (depending on your event model) not very efficient,
225	root	1.2	as it is done outside the "mainloop".
226	root	1.1
227	root	1.2	SEE ALSO
228			<http://freenet.sf.net>.
229	root	1.1
230	root	1.2	BUGS
231	root	1.1	AUTHOR
232			Marc Lehmann <pcg@goof.com>
233			http://www.goof.com/pcg/marc/
234