| Andrea Tosatto | 672b9a7 | 2016-01-05 16:18:20 +0100 | [diff] [blame^] | 1 | # ndncatchunks and ndnputchunks |
| 2 | |
| 3 | **ndncatchunks** and **ndnputchunks** are a pair of programs to transfer a file as Data segments. |
| 4 | |
| 5 | * **ndnputchunks** is a producer program that reads a file from the standard input, and makes |
| 6 | it available as NDN Data segments. It appends version and segment number components |
| 7 | to the specified name, according to the |
| 8 | [NDN naming conventions](http://named-data.net/publications/techreports/ndn-tr-22-ndn-memo-naming-conventions/). |
| 9 | |
| 10 | * **ndncatchunks** is a consumer program that fetches Data segments of a file, optionally |
| 11 | discovering the latest version of the file, and writes the content of the retrieved file to |
| 12 | the standard output. |
| 13 | |
| 14 | ## Version discovery methods |
| 15 | |
| 16 | * `fixed` : ndncatchunks will send an interest attempting to find a data packet with the |
| 17 | specified prefix and version number. A version component must be present at the |
| 18 | end of the user-specified NDN name. |
| 19 | |
| 20 | * `iterative`: ndncatchunks will send a series of interests with ChildSelector set to prefer the |
| 21 | rightmost child and Exclude selectors, attempting to find a data packet with the |
| 22 | specified prefix and the latest (the largest in the NDN canonical ordering) |
| 23 | version number. The version is declared "latest" after a predefined number of |
| 24 | data retrieval timeouts (default: 1). |
| 25 | |
| 26 | The default discovery method is `fixed`. Other methods will be implemented in future versions |
| 27 | of the tool. |
| 28 | |
| 29 | |
| 30 | ## Usage examples |
| 31 | |
| 32 | ### Publishing |
| 33 | |
| 34 | The following command will publish the text of the GPL-3 license under the `/localhost/demo/gpl3` |
| 35 | prefix: |
| 36 | |
| 37 | ndnputchunks ndn:/localhost/demo/gpl3 < /usr/share/common-licenses/GPL-3 |
| 38 | |
| 39 | To find the published version you have to start ndnputchunks with the `-p` command line option, |
| 40 | for example: |
| 41 | |
| 42 | ndnputchunks -p ndn:/localhost/demo/gpl3 < /usr/share/common-licenses/GPL-3 |
| 43 | |
| 44 | This command will print the published version to the standard output. |
| 45 | |
| 46 | To publish data with a specific version, you must append a version component to the end of the |
| 47 | prefix. The version component must follow the aforementioned NDN naming conventions. |
| 48 | For example, the following command will publish the version `%FD%00%00%01Qc%CF%17v` of the |
| 49 | `/localhost/demo/gpl3` prefix: |
| 50 | |
| 51 | ndnputchunks ndn:/localhost/demo/gpl3/%FD%00%00%01Qc%CF%17v < /usr/share/common-licenses/GPL-3 |
| 52 | |
| 53 | If the version component is not valid, a new well-formed version will be generated and appended |
| 54 | to the supplied NDN name. |
| 55 | |
| 56 | |
| 57 | ### Retrieval |
| 58 | |
| 59 | To retrieve the latest version of a published file, the following command can be used: |
| 60 | |
| 61 | ndncatchunks -d iterative ndn:/localhost/demo/gpl3 |
| 62 | |
| 63 | This command will use the iterative method to discover the latest version of the file. |
| 64 | |
| 65 | To fetch a specific version of a published file, you can use the `fixed` version discovery method |
| 66 | (the default). In this case the version needs to be supplied as part of the name. For example, |
| 67 | if the version is known to be `%FD%00%00%01Qc%CF%17v`, the following command will fetch that |
| 68 | exact version of the file: |
| 69 | |
| 70 | ndncatchunks ndn:/localhost/demo/gpl3/%FD%00%00%01Qc%CF%17v |
| 71 | |
| 72 | |
| 73 | For more information, run the programs with `--help` as argument. |