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

  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.

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

    $userdata = $txn->userdata ([$userdata])
        Get and/or set user-specific data. This is useful in progress
        callbacks.

    $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.5
Committed:	Tue Sep 9 06:22:58 2003 UTC (20 years, 9 months ago) by root
Branch:	MAIN
Changes since 1.4:	+20 -2 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			$txn = $fcp->txn_client_hello
82			$nodehello = $fcp->client_hello
83			Executes a ClientHello request and returns it's results.
84
85			{
86			max_file_size => "5f5e100",
87	root	1.3	node => "Fred,0.6,1.46,7050"
88	root	1.2	protocol => "1.2",
89			}
90
91			$txn = $fcp->txn_client_info
92			$nodeinfo = $fcp->client_info
93			Executes a ClientInfo request and returns it's results.
94
95			{
96			active_jobs => "1f",
97			allocated_memory => "bde0000",
98			architecture => "i386",
99			available_threads => 17,
100	root	1.3	datastore_free => "5ce03400",
101			datastore_max => "2540be400",
102	root	1.2	datastore_used => "1f72bb000",
103	root	1.3	estimated_load => 52,
104			free_memory => "5cc0148",
105	root	1.2	is_transient => "false",
106	root	1.3	java_name => "Java HotSpot(_T_M) Server VM",
107	root	1.2	java_vendor => "http://www.blackdown.org/",
108	root	1.3	java_version => "Blackdown-1.4.1-01",
109			least_recent_timestamp => "f41538b878",
110			max_file_size => "5f5e100",
111	root	1.2	most_recent_timestamp => "f77e2cc520"
112	root	1.3	node_address => "1.2.3.4",
113			node_port => 369,
114			operating_system => "Linux",
115			operating_system_version => "2.4.20",
116			routing_time => "a5",
117	root	1.2	}
118
119			$txn = $fcp->txn_generate_chk ($metadata, $data)
120			$uri = $fcp->generate_chk ($metadata, $data)
121			Creates a new CHK, given the metadata and data. UNTESTED.
122
123			$txn = $fcp->txn_generate_svk_pair
124			($public, $private) = @{ $fcp->generate_svk_pair }
125			Creates a new SVK pair. Returns an arrayref.
126
127			[
128			"hKs0-WDQA4pVZyMPKNFsK1zapWY",
129			"ZnmvMITaTXBMFGl4~jrjuyWxOWg"
130			]
131
132			$txn = $fcp->txn_insert_private_key ($private)
133			$uri = $fcp->insert_private_key ($private)
134			Inserts a private key. $private can be either an insert URI (must
135			start with freenet:SSK@) or a raw private key (i.e. the private
136			value you get back from "generate_svk_pair").
137
138			Returns the public key.
139
140			UNTESTED.
141
142			$txn = $fcp->txn_get_size ($uri)
143			$length = $fcp->get_size ($uri)
144			Finds and returns the size (rounded up to the nearest power of two)
145			of the given document.
146
147			UNTESTED.
148
149	root	1.3	$txn = $fcp->txn_client_get ($uri [, $htl = 15 [, $removelocal = 0]])
150	root	1.4	($metadata, $data) = @{ $fcp->client_get ($uri, $htl, $removelocal)
151	root	1.3	Fetches a (small, as it should fit into memory) file from freenet.
152	root	1.4	$meta is the metadata (as returned by "parse_metadata" or "undef").
153	root	1.3
154	root	1.4	Due to the overhead, a better method to download big files should be
155	root	1.3	used.
156
157	root	1.4	my ($meta, $data) = @{
158	root	1.3	$fcp->client_get (
159			"freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w"
160			)
161			};
162
163			MISSING: ClientPut
164	root	1.2
165			THE Net::FCP::Txn CLASS
166			All requests (or transactions) are executed in a asynchroneous way (LIE:
167			uploads are blocking). For each request, a "Net::FCP::Txn" object is
168			created (worse: a tcp connection is created, too).
169
170			For each request there is actually a different subclass (and it's
171			possible to subclass these, although of course not documented).
172
173			The most interesting method is "result".
174	root	1.1
175	root	1.2	new arg => val,...
176			Creates a new "Net::FCP::Txn" object. Not normally used.
177	root	1.5
178			$userdata = $txn->userdata ([$userdata])
179			Get and/or set user-specific data. This is useful in progress
180			callbacks.
181	root	1.1
182	root	1.2	$result = $txn->result
183			Waits until a result is available and then returns it.
184	root	1.1
185	root	1.3	This waiting is (depending on your event model) not very efficient,
186	root	1.2	as it is done outside the "mainloop".
187	root	1.1
188	root	1.2	SEE ALSO
189			<http://freenet.sf.net>.
190	root	1.1
191	root	1.2	BUGS
192	root	1.1	AUTHOR
193			Marc Lehmann <pcg@goof.com>
194			http://www.goof.com/pcg/marc/
195