Most recent edit on 2008-07-03 07:32:30 by NextGens [add SubscribedUSK]
Additions:
<a href="FCP2p0SubscribedUSK">SubscribedUSK</a><br/>
Edited on 2008-06-04 11:51:01 by MatthewToseland [more formatting]
Additions:
Some messages may be followed by a "payload" of binary data of a length that will be specified within the message itself, in which case they will include a DataLength with the length, and end with Data instead of EndMessage.
Deletions:
Some messages may be followed by a "payload" of binary data of a length that will be specified within the message itself, in which case they will include a DataLength with the length, and end with Data instead of EndMessage.
Edited on 2008-06-04 11:50:33 by MatthewToseland [formatting and spelling]
Additions:
Some messages may be followed by a "payload" of binary data of a length that will be specified within the message itself, in which case they will include a DataLength with the length, and end with Data instead of EndMessage.
Most messages include an Identifier, which identifies the request. This is mandatory for request messages (ClientGet, ClientPut*, SubscribeUSK), but is optional for most messages and will be echoed back to the client on replies if it is present.
Deletions:
Some messages may be followed by a "payload" of binary data of a length that will be specified within the message itself, in which case they will include a DataLength with the length, and end with Data instead of EndMessage.
Most messages include an Identifier, which identifies the request. This is mandatory for request messages (ClientGet, ClientPut*, SubscribeUSK), but is optional for most messages and will be echoes back to the client on replies if it is present.
Edited on 2008-06-04 11:50:01 by MatthewToseland [mention Data]
Additions:
Some messages may be followed by a "payload" of binary data of a length that will be specified within the message itself, in which case they will include a DataLength with the length, and end with Data instead of EndMessage.
Most messages include an Identifier, which identifies the request. This is mandatory for request messages (ClientGet, ClientPut*, SubscribeUSK), but is optional for most messages and will be echoes back to the client on replies if it is present.
Deletions:
Some messages may be followed by a "payload" of binary data of a length that will be specified within the message itself. Most messages include an Identifier, which identifies the request. This is mandatory for request messages (ClientGet, ClientPut*, SubscribeUSK), but is optional for most messages and will be echoes back to the client on replies if it is present.
Edited on 2008-04-15 22:20:12 by MatthewToseland [RemovePersistentRequest -> RemoveRequest]
Additions:
<a href="FCP2p0RemoveRequest">RemoveRequest</a><br/>
Deletions:
<a href="FCP2p0RemovePersistentRequest">RemovePersistentRequest</a><br/>
Edited on 2008-04-05 18:36:26 by MatthewToseland [formatting]
Additions:
Some messages may be followed by a "payload" of binary data of a length that will be specified within the message itself. Most messages include an Identifier, which identifies the request. This is mandatory for request messages (ClientGet, ClientPut*, SubscribeUSK), but is optional for most messages and will be echoes back to the client on replies if it is present.
Deletions:
Some messages may be followed by a "payload" of binary data of a length that will be specified within the message itself. Most messages include an Identifier, which identifies the request. This is mandatory for request messages (ClientGet, ClientPut*, SubscribeUSK), but is optional for most messages and will be echoes back to the client on replies if it is present.
Edited on 2008-04-05 18:34:20 by MatthewToseland [Identifier]
Additions:
Some messages may be followed by a "payload" of binary data of a length that will be specified within the message itself. Most messages include an Identifier, which identifies the request. This is mandatory for request messages (ClientGet, ClientPut*, SubscribeUSK), but is optional for most messages and will be echoes back to the client on replies if it is present.
Deletions:
Some messages may be followed by a "payload" of binary data of a length that will be specified within the message itself.
Edited on 2008-03-13 11:35:09 by JuergenUrner [Added a link to the todo page]
Additions:
Todo page for the documentation. Feel free to place any tasks that need to be done here.
Edited on 2008-02-25 11:19:31 by JuergenUrner [Added data types aummary]
Additions:
Data Types
summary of data types used in FCP:
Boolean
Byte amount
Floating point number
Number
String
String list
Time
Time interval
User input string
Edited on 2008-02-22 16:29:16 by EthicalAnarhist [changing repository link]
Additions:
~- FCP notes in Subversion∞
Deletions:
~- FCP notes in Subversion∞
Edited on 2007-11-19 23:28:58 by SaceS [add plugin related commands]
Additions:
<a href="FCP2p0GetPluginInfo">GetPluginInfo</a> (since 1075)<br/>
<a href="FCP2p0FCPPluginMessage">FCPPluginMessage</a> (since 1075)<br/>
<a href="FCP2p0PluginInfo">PluginInfo</a> (since 1075)<br/>
<a href="FCP2p0FCPPluginReply">FCPPluginReply</a> (since 1075)<br/>
Edited on 2007-11-19 23:10:57 by SaceS [new error code (GetPluginInfo)]
Additions:
32 - No such plugin
Edited on 2007-07-22 16:29:18 by AlexLehm [added missing message SubscribedUSKUpdate]
Additions:
<a href="FCP2p0SubscribedUSKUpdate">SubscribedUSKUpdate</a><br/>
Edited on 2007-07-22 16:27:49 by AlexLehm [added missing message SubscribeUSK]
Additions:
<a href="FCP2p0SubscribeUSK">SubscribeUSK</a><br/>
Edited on 2007-07-17 15:03:17 by ZothaR [Note that ListPeer is available since 1045]
Additions:
<a href="FCP2p0ListPeer">ListPeer</a> (since 1045)<br/>
Deletions:
<a href="FCP2p0ListPeer">ListPeer</a><br/>
Edited on 2007-07-16 01:32:08 by ZothaR [Added ListPeer]
Additions:
<a href="FCP2p0ListPeer">ListPeer</a><br/>
Edited on 2007-07-15 15:35:01 by ZothaR [Added Protocol Error Code 31]
Additions:
31 - Operation is only available on a darknet peer
Edited on 2007-07-13 21:45:46 by ZothaR [Added Protocol Error Code 30]
Additions:
30 - Opennet is currently disabled by the node's configuration
Edited on 2007-04-22 22:14:01 by ZothaR [Added/updated Protocol Error Codes]
Additions:
19 - No such node identifier (Unused since 995)
26 - Could not read file
27 - Reference signature failed to verify
28 - Node cannot peer with itself
29 - Node already has a peer with that ref
Deletions:
19 - No such node identifier
Matthew's introductory post to Tech mailing list∞
Oldest known version of this page was edited on 2007-04-15 21:23:50 by ZothaR []
Page view:
Freenet Client Protocol 2.0 Specification
Note that this specification is a work in progress, and is subject to change. Third-party application developers are encouraged to experiment with FCP 2.0, but should be prepared for backwards-incompatible changes. We suggest that these developers track changes to this page through this RSS feed∞.
Purpose
The Freenet Client Protocol is a simple, text-based protocol designed to allow third-party applications to interact with
Freenet∞. Supported functionality includes:
- Inserting of data into Freenet
- Retrieval of data from Freenet
- Querying the status of Freenet
- Managing the other Freenet nodes that are connected to your own node.
History
FCP 2.0 is was first supported in
Freenet 0.7, and is a non-backwards compatible replacement for the original Freenet Client Protocol supported by versions of Freenet prior to 0.7. The protocol is not backwards compatible because of the fundamental nature of the changes to Freenet 0.7 relative to previous versions of Freenet. Downloading large files with the old FCP API was very complex, and involved a great deal of code duplication between different client apps; the philosophy of FCP 2.0 is that it should be possible to write simple apps, but powerful options should be available when needed. The node does most of the work (e.g. reassembling splitfiles) for the client, unlike in Freenet 0.5's FCP. If you need additional functionality from FCP, please contact us, we may well be able to give you it.
Transport
FCP operates over a TCP connection, typically between Freenet and another application running on the same computer. By default, Freenet listens for FCP 2.0 connections on port 9481 (note that previous incompatible versions of FCP used port 8481). The protocol is text-based, and uses the UTF-8 character set encoding.
Basic Protocol Syntax
The basic unit of FCP is the message, which consists of a message name, and 0 or more key-value pairs called "fields". Message and field names are typically specified in
Camel Case∞ using alphanumeric characters. Messages can be sent from client to server, or from server to client. Multiple messages can be sent in either direction one after the other.
MessageName
Field1=Value1
Field2=Value2
...
EndMessage
Some messages may be followed by a "payload" of binary data of a length that will be specified within the message itself.
For ease of debugging, blank lines between messages are ignored.
Messages
Summary list of messages
Persistence and the Global Queue
ClientGet and
ClientPut messages (collectively: "requests") have a
Persistence field:
Persistence=connection : request is not persistent, will be dropped if the client connection is lost; default
Persistence=reboot : request will persist across client connection drops, but will be lost if the node is restarted
Persistence=forever : request will persist forever; the node will write it to a plaintext file on disk, and restart it if the node is restarted
If a request is persistent (i.e. if
Persistence is set to
reboot or
forever), then the Freenet node will send an acknowledgement when it is started - either a
PersistentPut or a
PersistentGet message. When the request completes, the client will be notified - if it is connected. If the client is not connected at the time when the request completes, then it will be notified when it next connects. The completed request will persist until it is explicitly removed by the client through a
RemovePersistentRequest message. When the client connects, all completed persistent requests will be sent to it - in the form of the
PersistentGet and
PersistentPut messages, followed by the
DataFound,
GetFailed,
PutSuccessful and
PutFailed messages, possibly followed by an
AllData message for a
ReturnType=direct request. If the client needs to know about all requests, including those still running, it can send a
ListPersistentRequests message. The node will then send
PersistentGet,
PersistentPut or
PersistentPutDir messages for each running and completed persistent request, and also any other pending messages for them, as above, possibly with progress messages as well (
SimpleProgress,
StartedCompression,
FinishedCompression).
Requests can be assigned to the
Global Queue, by setting
Global=true when starting them. The idea with the global queue is to have a single queue which all interested FCP apps (e.g.
FUQID) can watch, and which all FCP apps can assign downloads to (e.g.
Frost or
Fproxy queueing a download to the global queue so that the user gets the benefit of his preferred download manager interface). All apps have full control of all downloads on the global queue; they can remove them, list them, and receive notifications about them:
ClientPut
URI=CHK@
UploadFrom=disk
Filename=/home/toad/debian-sarge-dvd1.iso
Identifier=sarge-disk-1
ClientToken=This is the debian sarge dvd number 1
Global=true
EndMessage
This queues an insert on the global queue. Clients do not receive notifications about requests on the global queue, even if they started the request, unless they ask for them with a
WatchGlobal message. Once watch-the-global-queue is enabled, they will receive status updates about all requests on the global queue, and if they do
ListPersistentRequests, they will see both their own queued persistent requests and those queued to the global persistent requests queue.
Protocol Error Codes
The error codes that may be sent in a
ProtocolError message are as follows:
1 -
ClientHello must be first message
2 -
ClientHellos aren't allowed later in the protocol
3 - Message parse error
4 - URI parse error
5 - Missing field
6 - Error parsing number
7 - Invalid message
8 - Invalid field
9 - File not found
10 - Disk target exists
11 - Filename and temporary filename must be in the same directory
12 - Couldn't create file
13 - Couldn't write file
14 - Couldn't rename file
15 - No such identifier
16 - Not supported
17 - Internal error
18 - Shutting down
19 - No such node identifier
20 - URL parse error
21 - Reference parse error
22 - File parse error
23 - Not a file
24 - Access denied
25 - Direct Disk Access denied
Fetch Error Codes
The error codes that may be included in a
GetFailed message are as follows:
1 - Too many levels of archive recursion
2 - Unknown splitfile metadata
3 - Unknown metadata
4 - Invalid metadata
5 - Archive failure
6 - Block decode error
7 - Too many metadata levels
8 - Too many archive restarts
9 - Too many levels of recursion
10 - Tried to access an archive file but not in an archive (this isn't an archive, but you seem to be telling me it is)
11 - The URI has more metastrings and I can't deal with them
12 - Bucket error (ie. internal, ie. not your fault!)
13 - Data not found (I've looked, and it's really not there. Get over it)
14 - Route not found (I can't get to where it would be)
15 - Rejected overload (A downstream node was too busy to deal with us right now)
16 - Too many redirects
17 - Internal error
18 - Transfer failed (I found it, but never managed to get the data)
19 - Splitfile error
20 - Invalid URI
21 - Too big!
22 - Metadata is too big
23 - Too many blocks per segment (in a splitfile)
24 - Not enough metastrings (be more specific - put /something at the end)
25 - Cancelled
26 - Archive restart
27 - Permanent redirect (there's a newer version of the USK you asked for)
28 - All data not found (means we fetched some data but not all - perhaps a redirect to a file that hasn't been inserted)
Insert Error Codes
The error codes that may be included in a
PutFailed message are as follows:
1 - Invalid URI
2 - Bucket error (as above)
3 - Internal error
4 - Rejected Overload (a downstream node was overloaded and said no)
5 - Route not found
6 - Fatal errors in Blocks (Fatal errors in a splitfile insert)
7 - Too many retries in block (a splitfile had a certain block that just didn't want to go in)
8 - Route really not found (It couldn't even leave the node)
9 - Collision (there's already different data at that key)
10 - Cancelled (by you)
Priority classes
Several priority classes are supported:
0 - Maximum priority: anything more important than Fproxy
1 - Interactive priority class: Fproxy
2 - Semi-interactive priority class: Fproxy immediate-mode (not to disk) large file downloads
3 - Updatable site checks
4 - Bulk offline splitfile fetches (usually to disk)
5 - Prefetch priority class
6 - Minimum priority class (anything less important than prefetch)
For
ClientGet messages, the default priority depends on the ReturnType:
ReturnType=none defaults to 5,
ReturnType=disk defaults to 4, and
ReturnType=direct defaults to 2. For
ClientPut messages, the default priority class is 2. In Freenet 0.7 at present, inserts and requests do not compete directly with one another, nor do
SSKs with
CHKs; they are scheduled separately because of their different performance characteristics.
Library Implementations
Note: FCP library authors are encouraged to release their libraries under the Lesser GNU Public License.
Relevant Links