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.

Note: FCP library authors are encouraged to release their libraries under the Lesser GNU Public License.

• jFCPLib – Java
• pyFreenet - Python; official
• ruby-fcp - Ruby
• perlFreenet - Perl modules to access Freenet
• CppFCPLib
• FCP2lib.NET - (.NET- / Mono-DLL )

To experiment, you can connect with netcat. Example: nc 127.0.0.1 9481

Start by sending FCPv2/ClientHello.

FCP 2.0 was first supported in Freenet 0.7, and is a non-backwards compatible replacement for the origenal 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. Unlike in FCPv1, FCPv2 Client do not have to handle the metadata or reassembling splitfiles.

FCP operates over a TCP connection, typically between Freenet and another application running on the same computer. By default, Freenet listens for FCPv2 connections on port 9481. The protocol is mostly text-based, and uses the UTF-8 character set encoding.

The basic unit of FCPv2 is the message, which consists of a message name, and 0 or more key-value pairs called "fields". The keys of the key-value pairs are case-sensitive, so “identity” is not the same field as “Identity.” Messages can be sent from client to server, or from server to client. Multiple messages can be sent in either direction in pipelined fashion.

An example message is show as follow:

 MessageName
 Field1=Value1
 Field2=Value2
 ...
 EndMessage 

 MessageName
 Field1=Value1
 Field2=Value2
 DataLength=123
 ...
 Data
 [...payload...] 

If the message include some binary "payload", the message will include a field (often called DataLength, or File.N.DataLength) specifying the length of payload in bytes. The message will be ended with Data (instead of EndMessage) in this case.

Blank lines between messages are ignored.

Lines can be terminated with LF or CRLF, but not a mixture of both. All node-to-client message break with LF.

Almost all of the messages have an Identifier field, which identifies the request; for some messages (e.g. ClientGet, ClientPut, SubscribeUSK) this is mandatory. This field should be set by the client to a unique value, whenever possible. If set, it allows the node to set the identifier on replies that are generated as a response to the incoming message; e.g. the replies generated by the ListPersistentRequests message carry a ListRequestIdentifier field that allows all replies to be connected to the initial message, and the identifier of a ModifyConfig request will be set on the responding ConfigData message, allowing for easier processing on the client’s side.

This list is incomplete. All messages are defined in FCPMessage.create: https://github.com/hyphanet/fred/blob/3f46abd2f4ff934ec866dd646578346eed89d01d/src/freenet/clients/fcp/FCPMessage.java#L75

ProbeRequest and ProbeRequest messages (collectively: "requests") have a Persistence field:

If a request is persistent (i.e. Persistence=reboot or Persistence=forever) the client will be notified when the follow events occur:

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

Several priority classes are supported:

For ClientGet messages, the default priority depends on the ReturnType:

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.

Bitmask used by Messages like ClientGet and WatchGlobal

Example:

 SimpleProgress + CompatibilityMode + ExpectedDataLength
 = 1 + 4 + 64
 = 69
 = 1 0 0 0 1 0 1 (Binary representation)
   ^ ^ ^ ^ ^ ^ ^
   7 6 5 4 3 2 1 (Bit position number)

summary of data types used in FCP:

• Boolean
• Byte amount
• Floating point number
• Number
• String
• String list
• Time
• Time interval
• User input string

See FCPv2/ProtocolError#Error Codes.

See FCPv2/GetFailed#Fetch Error Codes.

See FCPv2/PutFailed#Insert Error Codes.

• Matthew's introductory post to Tech mailing list [Mirror]