Skip to content

FCPv2 ClientPutComplexDir

Jump to bottom Edit New page
DC* edited this page Aug 29, 2020 · 3 revisions

ClientPutComplexDir inserts one or more items under one single key.

ClientPutComplexDir works like an item container, in which you can place any number of items that can be retrieved under the same URI. On insert, items are added to the container as Files.0.* up to Files.N.*. On retrieval items can be retrieved as URI/MyItemName1, URI/Subfolder/MyItemName2.

Table of Contents

Example 

 ClientPutComplexDir
   Identifier=any
   URI=any
   Files.0.Name=any
   Files.1.Name=any
 EndMessage
 [Data]

Notes:

  • If you insert only one file, consider using ClientPut instead (with no filename after the /) -- this saves one manifest fetch
  • Item Numbers must start at zero and advance sequentially
  • Data associated to data items will be read in item order from the end of the message
  • An item can not be a folder and an item at the same time. That is, as for the example given above, you can not pass an item named Subfolder

Details

The message accepts the following fields:

Field Possible values Mandatory Default Description
URI
  • CHK@
  • KSK@name
  • SSK@privateKey/docname-1
  • USK@privateKey/docname/0/
yes The type of key to insert. When inserting an SSK, you explicitly specify the version number. For a USK, use a zero and it should automatically use the correct version number.
Identifier Arbitrary text string yes This is just for client to be able to identify files that have been inserted.
Verbosity Bitmask no 0 Enabling the following bits allows the node to provide status updates:
MaxRetries [-1..0..Integer.MAX_VALUE] no 0 Number of times to retry if the first time doesn't work. -1 means retry forever.
PriorityClass [0..2..6] no 2 (Semi-interactive priority class) How to prioritize the insert.
GetCHKOnly [true|false] no false If set to true, it won't actually insert the data, just return the key it would generate. If the key is USK, you may want to transform it into a SSK, to prevent the node spending time searching for an unused index.
Global [true|false] no false Whether the insert is visible on the global queue or not.
DontCompress [true|false] no false Hint to node: don't try to compress the data, it's already compressed
Codecs Comma separated list of either names or ids no The node try to compress the data with the given codec, if more then one codec is given the node try to find the best in given order. The node reports the supported codecs in the NodeHello message.
ClientToken Arbitrary string no Sent back to client in the PersistentPut message if this is a persistent request
Persistence [connection|reboot|forever] no connection Whether the insert stays on the queue across new client connections, Freenet restarts, or forever
TargetFilename A filename (no slashes) no Extracted from URI or Filename Filename to be appended to a CHK insert. Technically it creates a one-file manifest with this filename pointing to the file being uploaded. Ignored for all types other than CHK, since other types have human-readable filenames anyway. Empty means no filename.
EarlyEncode [true|false] no False See EarlyEncode
DefaultName String no The item to display when someone requests the URI only (without the item name part)
ForkOnCacheable [true|false] no true Override insert behavior: If true, fork an insert after its HTL becomes low enough for it to be cacheable. If false, don't fork the insert at this point. Inserts are not cached while their HTL is above 15, after that they can be cached, but this can be many hops because of probabilistic decrement, hence they may go over the "ideal" nodes or "sinks" where they should have been cached while they are still not allowed to, and the insert will not go back to those nodes because it's already been there. Forking deals with this by creating a new insert, which can go back over nodes we've already been to if necessary.
ExtraInsertsSingleBlock [0..Integer.MAX_VALUE] no 2 Insert single blocks (not blocks above splitfiles, and not blocks in splitfiles) additional times. Testing has shown that a value of 2 (3 inserts total) can dramatically improve data persistence. We are still trying to figure out why.
ExtraInsertsSplitfileHeaderBlock [0..2..Integer.MAX_VALUE] no 2 Insert blocks above splitfiles additional times. E.g. the CHK at the top of a splitfile, the CHK you actually fetch, is a single block. The splitfile itself has redundancy but the top block doesn't. So we insert it multiple times (3 by default) to improve the number of nodes it gets stored on. Tests show this dramatically improves data persistence, we are still trying to figure out why.
RealTimeFlag no false Whether to fetch the data with the real-time flag set to realtime (true) or bulk (false). (since 1311)

Followed by one or more of the following items:

Direct Transfer

Field Possible values Mandatory Description
Files.N.Name yes Name under which the item can be retrieved under the key. May contain slashes to indicate subfolders
Files.N.UploadFrom direct yes
Files.N.DataLength [0..Long.MAX_VALUE] yes Number of bytes of data associated to the item
Files.N.Metadata.ContentType Any MIME type no The MIME type of the data being inserted. For text, if charset is not specified, node should auto-detect it and force the auto-detected version

Disk Transfer

Field Possible values Mandatory Description
Files.N.Name yes Name under which the item can be retrieved under the key. May contain slashes to indicate subfolders
Files.N.UploadFrom disk yes
Files.N.Filename yes The name of the file on disk
Files.N.Metadata.ContentType Any MIME type no The MIME type of the data being inserted. For text, if charset is not specified, node should auto-detect it and force the auto-detected version

Redirect Item

Field Possible values Mandatory Description
Files.N.Name yes Name under which the item can be retrieved under the key. May contain slashes to indicate subfolders
Files.N.UploadFrom redirect yes
Files.N.TargetURI yes Freenet URI to redirect to
Add a custom footer
Add a custom sidebar

Clone this wiki locally