src/fs/fs.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 2, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file fs/fs.h
  23  * @brief definitions for the entire fs module
  24  * @author Igor Wronsky, Christian Grothoff
  25  */
  26 #ifndef FS_H
  27 #define FS_H
  28
  29 #include "gnunet_constants.h"
  30 #include "gnunet_datastore_service.h"
  31 #include "gnunet_fs_service.h"
  32
  33 /**
  34  * Size of the individual blocks used for file-sharing.
  35  */
  36 #define DBLOCK_SIZE (32*1024)
  37
  38
  39 /**
  40  * Pick a multiple of 2 here to achive 8-byte alignment!
  41  * We also probably want DBlocks to have (roughly) the
  42  * same size as IBlocks.  With SHA-512, the optimal
  43  * value is 32768 byte / 128 byte = 256
  44  * (128 byte = 2 * 512 bits).  DO NOT CHANGE!
  45  */
  46 #define CHK_PER_INODE 256
  47
  48
  49 /**
  50  * Maximum size for a file to be considered for
  51  * inlining in a directory.
  52  */
  53 #define MAX_INLINE_SIZE 65536
  54
  55
  56 /**
  57  * Blocksize to use when hashing files
  58  * for indexing (blocksize for IO, not for
  59  * the DBlocks).  Larger blocksizes can
  60  * be more efficient but will be more disruptive
  61  * as far as the scheduler is concerned.
  62  */
  63 #define HASHING_BLOCKSIZE (1024 * 1024)
  64
  65 /**
  66  * Number of bits we set per entry in the bloomfilter.
  67  * Do not change!
  68  */
  69 #define BLOOMFILTER_K 16
  70
  71 /**
  72  * By how much (in ms) do we decrement the TTL
  73  * at each hop?
  74  */
  75 #define TTL_DECREMENT 5000
  76
  77 /**
  78  * How long are we willing to wait for the datastore to be ready to
  79  * process a request for a query without priority?
  80  */
  81 #define BASIC_DATASTORE_REQUEST_DELAY GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_SECONDS, 5)
  82
  83
  84 /**
  85  * How long are we willing to wait for the core to be ready to
  86  * transmit a reply to the target peer (if we can not transmit
  87  * until then, we will discard the reply).
  88  */
  89 #define ACCEPTABLE_REPLY_DELAY GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_MINUTES, 5)
  90
  91
  92 /**
  93  * Bandwidth value of an (effectively) 0-priority query.
  94  */
  95 #define QUERY_BANDWIDTH_VALUE 0.001
  96
  97 /**
  98  * Bandwidth value of a 0-priority content (must be
  99  * fairly high compared to query since content is
 100  * typically significantly larger -- and more valueable
 101  * since it can take many queries to get one piece of
 102  * content).
 103  */
 104 #define CONTENT_BANDWIDTH_VALUE 0.8
 105
 106 /**
 107  * By which amount do we decrement the TTL for simple forwarding /
 108  * indirection of the query; in milli-seconds.  Set somewhat in
 109  * accordance to your network latency (above the time it'll take you
 110  * to send a packet and get a reply).
 111  */
 112 #define TTL_DECREMENT 5000
 113
 114 /**
 115  * Until which load do we consider the peer idle and do not
 116  * charge at all? (should be larger than GNUNET_IDLE_LOAD_THRESHOLD used
 117  * by the rest of the code)!
 118  */
 119 #define IDLE_LOAD_THRESHOLD ((100 + GNUNET_CONSTANTS_IDLE_LOAD_THRESHOLD) / 2)
 120
 121
 122
 123 /**
 124  * @brief content hash key
 125  */
 126 struct ContentHashKey
 127 {
 128   GNUNET_HashCode key;
 129   GNUNET_HashCode query;
 130 };
 131
 132
 133 /**
 134  * @brief complete information needed
 135  * to download a file.
 136  */
 137 struct FileIdentifier
 138 {
 139
 140   /**
 141    * Total size of the file in bytes. (network byte order (!))
 142    */
 143   uint64_t file_length;
 144
 145   /**
 146    * Query and key of the top GNUNET_EC_IBlock.
 147    */
 148   struct ContentHashKey chk;
 149
 150 };
 151
 152
 153 /**
 154  * Information about a file and its location
 155  * (peer claiming to share the file).
 156  */
 157 struct Location
 158 {
 159   /**
 160    * Information about the shared file.
 161    */
 162   struct FileIdentifier fi;
 163
 164   /**
 165    * Identity of the peer sharing the file.
 166    */
 167   struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded peer;
 168
 169   /**
 170    * Time when this location URI expires.
 171    */
 172   struct GNUNET_TIME_Absolute expirationTime;
 173
 174   /**
 175    * RSA signature over the GNUNET_EC_FileIdentifier,
 176    * GNUNET_hash of the peer and expiration time.
 177    */
 178   struct GNUNET_CRYPTO_RsaSignature contentSignature;
 179
 180 };
 181
 182 enum uri_types
 183 { chk, sks, ksk, loc };
 184
 185 /**
 186  * A Universal Resource Identifier (URI), opaque.
 187  */
 188 struct GNUNET_FS_Uri
 189 {
 190   enum uri_types type;
 191   union
 192   {
 193     struct
 194     {
 195       /**
 196        * Keywords start with a '+' if they are
 197        * mandatory (in which case the '+' is NOT
 198        * part of the keyword) and with a
 199        * simple space if they are optional
 200        * (in which case the space is ALSO not
 201        * part of the actual keyword).
 202        *
 203        * Double-quotes to protect spaces and
 204        * %-encoding are NOT used internally
 205        * (only in URI-strings).
 206        */
 207       char **keywords;
 208
 209       /**
 210        * Size of the keywords array.
 211        */
 212       unsigned int keywordCount;
 213     } ksk;
 214
 215     struct
 216     {
 217       /**
 218        * Hash of the public key for the namespace.
 219        */
 220       GNUNET_HashCode namespace;
 221
 222       /**
 223        * Human-readable identifier chosen for this
 224        * entry in the namespace.
 225        */
 226       char *identifier;
 227     } sks;
 228
 229     /**
 230      * Information needed to retrieve a file (content-hash-key
 231      * plus file size).
 232      */
 233     struct FileIdentifier chk;
 234
 235     /**
 236      * Information needed to retrieve a file including signed
 237      * location (identity of a peer) of the content.
 238      */
 239     struct Location loc;
 240   } data;
 241
 242 };
 243
 244
 245 /**
 246  * Information for a file or directory that is
 247  * about to be published.
 248  */
 249 struct GNUNET_FS_FileInformation
 250 {
 251
 252   /**
 253    * Files in a directory are kept as a linked list.
 254    */
 255   struct GNUNET_FS_FileInformation *next;
 256
 257   /**
 258    * If this is a file in a directory, "dir" refers to
 259    * the directory; otherwise NULL.
 260    */
 261   struct GNUNET_FS_FileInformation *dir;
 262
 263   /**
 264    * Pointer kept for the client.
 265    */
 266   void *client_info;
 267
 268   /**
 269    * Metadata to use for the file.
 270    */
 271   struct GNUNET_CONTAINER_MetaData *meta;
 272
 273   /**
 274    * Keywords to use for KBlocks.
 275    */
 276   struct GNUNET_FS_Uri *keywords;
 277
 278   /**
 279    * CHK for this file or directory. NULL if
 280    * we have not yet computed it.
 281    */
 282   struct GNUNET_FS_Uri *chk_uri;
 283
 284   /**
 285    * At what time should the content expire?
 286    */
 287   struct GNUNET_TIME_Absolute expirationTime;
 288
 289   /**
 290    * At what time did we start this upload?
 291    */
 292   struct GNUNET_TIME_Absolute start_time;
 293
 294   /**
 295    * Under what filename is this struct serialized
 296    * (for operational persistence).
 297    */
 298   char *serialization;
 299
 300   /**
 301    * Encoder being used to publish this file.
 302    */
 303   struct GNUNET_FS_TreeEncoder *te;
 304
 305   /**
 306    * Error message (non-NULL if this operation
 307    * failed).
 308    */
 309   char *emsg;
 310
 311   /**
 312    * Data describing either the file or the directory.
 313    */
 314   union
 315   {
 316
 317     /**
 318      * Data for a file.
 319      */
 320     struct {
 321
 322       /**
 323        * Function that can be used to read the data for the file.
 324        */
 325       GNUNET_FS_DataReader reader;
 326
 327       /**
 328        * Closure for reader.
 329        */
 330       void *reader_cls;
 331
 332       /**
 333        * Name of the file (must be an absolute path).
 334        * Only required for indexing.  FIXME: not yet
 335        * initialized!
 336        */
 337       char *filename;
 338
 339       /**
 340        * If this file is being indexed, this value
 341        * is set to the hash over the entire file
 342        * (when the indexing process is started).
 343        * Otherwise this field is not used.
 344        */
 345       GNUNET_HashCode file_id;
 346
 347       /**
 348        * Size of the file (in bytes).
 349        */
 350       uint64_t file_size;
 351
 352       /**
 353        * Should the file be indexed or inserted?
 354        */
 355       int do_index;
 356
 357     } file;
 358
 359     /**
 360      * Data for a directory.
 361      */
 362     struct {
 363
 364       /**
 365        * Name of the directory.
 366        */
 367       char *dirname;
 368
 369       /**
 370        * Linked list of entries in the directory.
 371        */
 372       struct GNUNET_FS_FileInformation *entries;
 373
 374       /**
 375        * Size of the directory itself (in bytes); 0 if the
 376        * size has not yet been calculated.
 377        */
 378       size_t dir_size;
 379
 380       /**
 381        * Pointer to the data for the directory (or NULL if not
 382        * available).
 383        */
 384       void *dir_data;
 385
 386     } dir;
 387
 388   } data;
 389
 390   /**
 391    * Is this struct for a file or directory?
 392    */
 393   int is_directory;
 394
 395   /**
 396    * Desired anonymity level.
 397    */
 398   uint32_t anonymity;
 399
 400   /**
 401    * Desired priority (for keeping the content in the DB).
 402    */
 403   uint32_t priority;
 404
 405 };
 406
 407
 408 /**
 409  * Master context for most FS operations.
 410  */
 411 struct GNUNET_FS_Handle
 412 {
 413   /**
 414    * Scheduler.
 415    */
 416   struct GNUNET_SCHEDULER_Handle *sched;
 417
 418   /**
 419    * Configuration to use.
 420    */
 421   const struct GNUNET_CONFIGURATION_Handle *cfg;
 422
 423   /**
 424    * Name of our client.
 425    */
 426   char *client_name;
 427
 428   /**
 429    * Function to call with updates on our progress.
 430    */
 431   GNUNET_FS_ProgressCallback upcb;
 432
 433   /**
 434    * Closure for upcb.
 435    */
 436   void *upcb_cls;
 437
 438   /**
 439    * Connection to the FS service.
 440    */
 441   struct GNUNET_CLIENT_Connection *client;
 442
 443   /**
 444    * How many downloads probing availability
 445    * of search results do we have running
 446    * right now?
 447    */
 448   unsigned int active_probes;
 449
 450   /**
 451    * General flags.
 452    */
 453   enum GNUNET_FS_Flags flags;
 454
 455 };
 456
 457
 458 /**
 459  * Handle for controlling an upload.
 460  */
 461 struct GNUNET_FS_PublishContext
 462 {
 463   /**
 464    * Handle to the global fs context.
 465    */
 466   struct GNUNET_FS_Handle *h;
 467
 468   /**
 469    * Argument to pass to the client in callbacks.
 470    */
 471   void *client_ctx;
 472
 473   /**
 474    * File-structure that is being shared.
 475    */
 476   struct GNUNET_FS_FileInformation *fi;
 477
 478   /**
 479    * Namespace that we are publishing in, NULL if we have no namespace.
 480    */
 481   struct GNUNET_FS_Namespace *namespace;
 482
 483   /**
 484    * ID of the content in the namespace, NULL if we have no namespace.
 485    */
 486   char *nid;
 487
 488   /**
 489    * ID for future updates, NULL if we have no namespace or no updates.
 490    */
 491   char *nuid;
 492
 493   /**
 494    * Our own client handle for the FS service;
 495    * only briefly used when we start to index a
 496    * file, otherwise NULL.
 497    */
 498   struct GNUNET_CLIENT_Connection *client;
 499
 500   /**
 501    * Current position in the file-tree for the
 502    * upload.
 503    */
 504   struct GNUNET_FS_FileInformation *fi_pos;
 505
 506   /**
 507    * Connection to the datastore service.
 508    */
 509   struct GNUNET_DATASTORE_Handle *dsh;
 510
 511   /**
 512    * ID of the task performing the upload. NO_TASK
 513    * if the upload has completed.
 514    */
 515   GNUNET_SCHEDULER_TaskIdentifier upload_task;
 516
 517   /**
 518    * Typically GNUNET_NO.  Set to GNUNET_YES if
 519    * "upload_task" is GNUNET_SCHEDULER_NO_TASK
 520    * and we're waiting for a response from the
 521    * datastore service (in which case this
 522    * struct must not be freed until we have that
 523    * response).  If someone tries to stop the
 524    * download for good during this period,
 525    * "in_network_wait" is set to GNUNET_SYSERR
 526    * which will cause the struct to be destroyed
 527    * right after we have the reply (or timeout)
 528    * from the datastore service.
 529    */
 530   int in_network_wait;
 531
 532   /**
 533    * Options for publishing.
 534    */
 535   enum GNUNET_FS_PublishOptions options;
 536
 537   /**
 538    * Space reservation ID with datastore service
 539    * for this upload.
 540    */
 541   int rid;
 542 };
 543
 544
 545 /**
 546  * Phases of unindex processing (state machine).
 547  */
 548 enum UnindexState
 549   {
 550     /**
 551      * We're currently hashing the file.
 552      */
 553     UNINDEX_STATE_HASHING = 0,
 554
 555     /**
 556      * We're notifying the FS service about
 557      * the unindexing.
 558      */
 559     UNINDEX_STATE_FS_NOTIFY = 1,
 560
 561     /**
 562      * We're telling the datastore to delete
 563      * the respective entries.
 564      */
 565     UNINDEX_STATE_DS_REMOVE = 2,
 566
 567     /**
 568      * We're done.
 569      */
 570     UNINDEX_STATE_COMPLETE = 3,
 571
 572     /**
 573      * We've encountered a fatal error.
 574      */
 575     UNINDEX_STATE_ERROR = 4,
 576
 577     /**
 578      * We've been aborted.  The next callback should clean up the
 579      * struct.
 580      */
 581     UNINDEX_STATE_ABORTED = 5
 582   };
 583
 584
 585 /**
 586  * Handle for controlling an unindexing operation.
 587  */
 588 struct GNUNET_FS_UnindexContext
 589 {
 590
 591   /**
 592    * Global FS context.
 593    */
 594   struct GNUNET_FS_Handle *h;
 595
 596   /**
 597    * Name of the file that we are unindexing.
 598    */
 599   char *filename;
 600
 601   /**
 602    * Connection to the FS service,
 603    * only valid during the UNINDEX_STATE_FS_NOTIFY
 604    * phase.
 605    */
 606   struct GNUNET_CLIENT_Connection *client;
 607
 608   /**
 609    * Connection to the datastore service,
 610    * only valid during the UNINDEX_STATE_DS_NOTIFY
 611    * phase.
 612    */
 613   struct GNUNET_DATASTORE_Handle *dsh;
 614
 615   /**
 616    * Pointer kept for the client.
 617    */
 618   void *client_info;
 619
 620   /**
 621    * Merkle-ish tree encoder context.
 622    */
 623   struct GNUNET_FS_TreeEncoder *tc;
 624
 625   /**
 626    * Handle used to read the file.
 627    */
 628   struct GNUNET_DISK_FileHandle *fh;
 629
 630   /**
 631    * Overall size of the file.
 632    */
 633   uint64_t file_size;
 634
 635   /**
 636    * When did we start?
 637    */
 638   struct GNUNET_TIME_Absolute start_time;
 639
 640   /**
 641    * Hash of the file's contents (once
 642    * computed).
 643    */
 644   GNUNET_HashCode file_id;
 645
 646   /**
 647    * Current operatinonal phase.
 648    */
 649   enum UnindexState state;
 650
 651 };
 652
 653
 654 /**
 655  * Information we store for each search result.
 656  */
 657 struct SearchResult
 658 {
 659
 660   /**
 661    * URI to which this search result
 662    * refers to.
 663    */
 664   struct GNUNET_FS_Uri *uri;
 665
 666   /**
 667    * Metadata for the search result.
 668    */
 669   struct GNUNET_CONTAINER_MetaData *meta;
 670
 671   /**
 672    * Client info for this search result.
 673    */
 674   void *client_info;
 675
 676   /**
 677    * ID of a job that is currently probing
 678    * this results' availability (NULL if we
 679    * are not currently probing).
 680    */
 681   struct GNUNET_FS_DownloadContext *probe_ctx;
 682
 683   /**
 684    * ID of the task that will clean up the probe_ctx
 685    * should it not complete on time (and that will
 686    * need to be cancelled if we clean up the search
 687    * result before then).
 688    */
 689   GNUNET_SCHEDULER_TaskIdentifier probe_cancel_task;
 690
 691   /**
 692    * Number of mandatory keywords for which
 693    * we have NOT yet found the search result;
 694    * when this value hits zero, the search
 695    * result is given to the callback.
 696    */
 697   uint32_t mandatory_missing;
 698
 699   /**
 700    * Number of optional keywords under which
 701    * this result was also found.
 702    */
 703   uint32_t optional_support;
 704
 705   /**
 706    * Number of availability tests that
 707    * have succeeded for this result.
 708    */
 709   uint32_t availability_success;
 710
 711   /**
 712    * Number of availability trials that we
 713    * have performed for this search result.
 714    */
 715   uint32_t availability_trials;
 716
 717 };
 718
 719
 720 /**
 721  * Information we keep for each keyword in
 722  * a keyword search.
 723  */
 724 struct SearchRequestEntry
 725 {
 726   /**
 727    * Hash of the original keyword, also known as the
 728    * key (for decrypting the KBlock).
 729    */
 730   GNUNET_HashCode key;
 731
 732   /**
 733    * Hash of the public key, also known as the query.
 734    */
 735   GNUNET_HashCode query;
 736
 737   /**
 738    * Map that contains a "struct SearchResult" for each result that
 739    * was found under this keyword.  Note that the entries will point
 740    * to the same locations as those in the master result map (in
 741    * "struct GNUNET_FS_SearchContext"), so they should not be freed.
 742    * The key for each entry is the XOR of the key and query in the CHK
 743    * URI (as a unique identifier for the search result).
 744    */
 745   struct GNUNET_CONTAINER_MultiHashMap *results;
 746
 747   /**
 748    * Is this keyword a mandatory keyword
 749    * (started with '+')?
 750    */
 751   int mandatory;
 752
 753 };
 754
 755
 756 /**
 757  * Handle for controlling a search.
 758  */
 759 struct GNUNET_FS_SearchContext
 760 {
 761   /**
 762    * Handle to the global FS context.
 763    */
 764   struct GNUNET_FS_Handle *h;
 765
 766   /**
 767    * List of keywords that we're looking for.
 768    */
 769   struct GNUNET_FS_Uri *uri;
 770
 771   /**
 772    * For update-searches, link to the
 773    * base-SKS search that triggered the
 774    * update search; otherwise NULL.
 775    */
 776   struct GNUNET_FS_SearchContext *parent;
 777
 778   /**
 779    * Connection to the FS service.
 780    */
 781   struct GNUNET_CLIENT_Connection *client;
 782
 783   /**
 784    * Pointer we keep for the client.
 785    */
 786   void *client_info;
 787
 788   /**
 789    * Map that contains a "struct SearchResult" for each result that
 790    * was found in the search.  The key for each entry is the XOR of
 791    * the key and query in the CHK URI (as a unique identifier for the
 792    * search result).
 793    */
 794   struct GNUNET_CONTAINER_MultiHashMap *master_result_map;
 795
 796   /**
 797    * Per-keyword information for a keyword search.
 798    * This array will have exactly as many entries
 799    * as there were keywords.
 800    */
 801   struct SearchRequestEntry *requests;
 802
 803   /**
 804    * When did we start?
 805    */
 806   struct GNUNET_TIME_Absolute start_time;
 807
 808   /**
 809    * ID of a task that is using this struct
 810    * and that must be cancelled when the search
 811    * is being stopped (if not GNUNET_SCHEDULER_NO_TASK).
 812    * Used for the task that adds some artificial
 813    * delay when trying to reconnect to the FS
 814    * service.
 815    */
 816   GNUNET_SCHEDULER_TaskIdentifier task;
 817
 818   /**
 819    * Anonymity level for the search.
 820    */
 821   uint32_t anonymity;
 822
 823   /**
 824    * Number of mandatory keywords in this query.
 825    */
 826   uint32_t mandatory_count;
 827 };
 828
 829
 830 /**
 831  * Information about an active download request.
 832  */
 833 struct DownloadRequest
 834 {
 835   /**
 836    * While pending, we keep all download requests
 837    * in a linked list.
 838    */
 839   struct DownloadRequest *next;
 840
 841   /**
 842    * CHK for the request.
 843    */
 844   struct ContentHashKey chk;
 845
 846   /**
 847    * Offset of the corresponding block.
 848    */
 849   uint64_t offset;
 850
 851   /**
 852    * Depth of the corresponding block in the tree.
 853    */
 854   unsigned int depth;
 855
 856   /**
 857    * Set if this request is currently in the linked list of pending
 858    * requests.  Needed in case we get a response for a request that we
 859    * have not yet send (due to FS bug or two blocks with identical
 860    * content); in this case, we would need to remove the block from
 861    * the pending list (and need a fast way to check if the block is on
 862    * it).
 863    */
 864   int is_pending;
 865
 866 };
 867
 868
 869 /**
 870  * Context for controlling a download.
 871  */
 872 struct GNUNET_FS_DownloadContext
 873 {
 874
 875   /**
 876    * Global FS context.
 877    */
 878   struct GNUNET_FS_Handle *h;
 879
 880   /**
 881    * Connection to the FS service.
 882    */
 883   struct GNUNET_CLIENT_Connection *client;
 884
 885   /**
 886    * Parent download (used when downloading files
 887    * in directories).
 888    */
 889   struct GNUNET_FS_DownloadContext *parent;
 890
 891   /**
 892    * Context kept for the client.
 893    */
 894   void *client_info;
 895
 896   /**
 897    * URI that identifies the file that
 898    * we are downloading.
 899    */
 900   struct GNUNET_FS_Uri *uri;
 901
 902   /**
 903    * Known meta-data for the file (can be NULL).
 904    */
 905   struct GNUNET_CONTAINER_MetaData *meta;
 906
 907   /**
 908    * Error message, NULL if we're doing OK.
 909    */
 910   char *emsg;
 911
 912   /**
 913    * Where are we writing the data (name of the
 914    * file, can be NULL!).
 915    */
 916   char *filename;
 917
 918   /**
 919    * Map of active requests (those waiting
 920    * for a response).  The key is the hash
 921    * of the encryped block (aka query).
 922    */
 923   struct GNUNET_CONTAINER_MultiHashMap *active;
 924
 925   /**
 926    * Linked list of pending requests.
 927    */
 928   struct DownloadRequest *pending;
 929
 930   /**
 931    * The file handle, NULL if we don't create
 932    * a file.
 933    */
 934   struct GNUNET_DISK_FileHandle *handle;
 935
 936   /**
 937    * Identity of the peer having the content, or all-zeros
 938    * if we don't know of such a peer.
 939    */
 940   struct GNUNET_PeerIdentity target;
 941
 942   /**
 943    * ID of a task that is using this struct
 944    * and that must be cancelled when the download
 945    * is being stopped (if not GNUNET_SCHEDULER_NO_TASK).
 946    * Used for the task that adds some artificial
 947    * delay when trying to reconnect to the FS
 948    * service.
 949    */
 950   GNUNET_SCHEDULER_TaskIdentifier task;
 951
 952   /**
 953    * What was the size of the file on disk that we're downloading
 954    * before we started?  Used to detect if there is a point in
 955    * checking an existing block on disk for matching the desired
 956    * content.  0 if the file did not exist already.
 957    */
 958   uint64_t old_file_size;
 959
 960   /**
 961    * What is the first offset that we're interested
 962    * in?
 963    */
 964   uint64_t offset;
 965
 966   /**
 967    * How many bytes starting from offset are desired?
 968    * This is NOT the overall length of the file!
 969    */
 970   uint64_t length;
 971
 972   /**
 973    * How many bytes have we already received within
 974    * the specified range (DBlocks only).
 975    */
 976   uint64_t completed;
 977
 978   /**
 979    * Time download was started.
 980    */
 981   struct GNUNET_TIME_Absolute start_time;
 982
 983   /**
 984    * Desired level of anonymity.
 985    */
 986   uint32_t anonymity;
 987
 988   /**
 989    * The depth of the file-tree.
 990    */
 991   unsigned int treedepth;
 992
 993   /**
 994    * Options for the download.
 995    */
 996   enum GNUNET_FS_DownloadOptions options;
 997
 998 };
 999
1000 struct GNUNET_FS_Namespace
1001 {
1002
1003   /**
1004    * Private key for the namespace.
1005    */
1006   struct GNUNET_CRYPTO_RsaPrivateKey *key;
1007
1008   /**
1009    * Reference counter.
1010    */
1011   unsigned int rc;
1012 };
1013
1014
1015 /**
1016  * @brief index block (indexing a DBlock that
1017  *        can be obtained directly from reading
1018  *        the plaintext file)
1019  */
1020 struct OnDemandBlock
1021 {
1022   /**
1023    * Hash code of the entire content of the
1024    * file that was indexed (used to uniquely
1025    * identify the plaintext file).
1026    */
1027   GNUNET_HashCode file_id;
1028
1029   /**
1030    * At which offset should we be able to find
1031    * this on-demand encoded block?
1032    */
1033   uint64_t offset GNUNET_PACKED;
1034
1035 };
1036
1037
1038 /**
1039  * @brief keyword block (advertising data under a keyword)
1040  */
1041 struct KBlock
1042 {
1043
1044   /**
1045    * GNUNET_RSA_Signature using RSA-key generated from search keyword.
1046    */
1047   struct GNUNET_CRYPTO_RsaSignature signature;
1048
1049   /**
1050    * What is being signed and why?
1051    */
1052   struct GNUNET_CRYPTO_RsaSignaturePurpose purpose;
1053
1054   /**
1055    * Key generated (!) from the H(keyword) as the seed!
1056    */
1057   struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded keyspace;
1058
1059   /* 0-terminated URI here */
1060
1061   /* variable-size Meta-Data follows here */
1062
1063 };
1064
1065 /**
1066  * @brief namespace content block (advertising data under an identifier in a namespace)
1067  */
1068 struct SBlock
1069 {
1070
1071   /**
1072    * GNUNET_RSA_Signature using RSA-key of the namespace
1073    */
1074   struct GNUNET_CRYPTO_RsaSignature signature;
1075
1076   /**
1077    * What is being signed and why?
1078    */
1079   struct GNUNET_CRYPTO_RsaSignaturePurpose purpose;
1080
1081   /**
1082    * Hash of the hash of the human-readable identifier used for
1083    * this entry (the hash of the human-readable identifier is
1084    * used as the key for decryption; the xor of this identifier
1085    * and the hash of the "keyspace" is the datastore-query hash).
1086    */
1087   GNUNET_HashCode identifier;
1088
1089   /**
1090    * Public key of the namespace.
1091    */
1092   struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded subspace;
1093
1094   /* 0-terminated update-identifier here */
1095
1096   /* 0-terminated URI here */
1097
1098   /* variable-size Meta-Data follows here */
1099
1100 };
1101
1102
1103 /**
1104  * Message sent from a GNUnet (fs) publishing
1105  * activity to the gnunet-fs-service to
1106  * initiate indexing of a file.  The service
1107  * is supposed to check if the specified file
1108  * is available and has the same cryptographic
1109  * hash.  It should then respond with either
1110  * a confirmation or a denial.
1111  *
1112  * On OSes where this works, it is considered
1113  * acceptable if the service only checks that
1114  * the path, device and inode match (it can
1115  * then be assumed that the hash will also match
1116  * without actually computing it; this is an
1117  * optimization that should be safe given that
1118  * the client is not our adversary).
1119  */
1120 struct IndexStartMessage
1121 {
1122
1123   /**
1124    * Message type will be
1125    * GNUNET_MESSAGE_TYPE_FS_INDEX_START.
1126    */
1127   struct GNUNET_MessageHeader header;
1128
1129   /**
1130    * ID of device containing the file, as seen by the client.  This
1131    * device ID is obtained using a call like "statvfs" (and converting
1132    * the "f_fsid" field to a 32-bit big-endian number).  Use 0 if the
1133    * OS does not support this, in which case the service must do a
1134    * full hash recomputation.
1135    */
1136   uint32_t device GNUNET_PACKED;
1137
1138   /**
1139    * Inode of the file on the given device, as seen by the client
1140    * ("st_ino" field from "struct stat").  Use 0 if the OS does not
1141    * support this, in which case the service must do a full hash
1142    * recomputation.
1143    */
1144   uint64_t inode GNUNET_PACKED;
1145
1146   /**
1147    * Hash of the file that we would like to index.
1148    */
1149   GNUNET_HashCode file_id;
1150
1151   /* this is followed by a 0-terminated
1152      filename of a file with the hash
1153      "file_id" as seen by the client */
1154
1155 };
1156
1157
1158 /**
1159  * Message send by FS service in response to a request
1160  * asking for a list of all indexed files.
1161  */
1162 struct IndexInfoMessage
1163 {
1164   /**
1165    * Message type will be
1166    * GNUNET_MESSAGE_TYPE_FS_INDEX_LIST_ENTRY.
1167    */
1168   struct GNUNET_MessageHeader header;
1169
1170   /**
1171    * Always zero.
1172    */
1173   uint32_t reserved GNUNET_PACKED;
1174
1175   /**
1176    * Hash of the indexed file.
1177    */
1178   GNUNET_HashCode file_id;
1179
1180   /* this is followed by a 0-terminated
1181      filename of a file with the hash
1182      "file_id" as seen by the client */
1183
1184 };
1185
1186
1187 /**
1188  * Message sent from a GNUnet (fs) unindexing
1189  * activity to the gnunet-fs-service to
1190  * indicate that a file will be unindexed.  The service
1191  * is supposed to remove the file from the
1192  * list of indexed files and response with
1193  * a confirmation message (even if the file
1194  * was already not on the list).
1195  */
1196 struct UnindexMessage
1197 {
1198
1199   /**
1200    * Message type will be
1201    * GNUNET_MESSAGE_TYPE_FS_UNINDEX.
1202    */
1203   struct GNUNET_MessageHeader header;
1204
1205   /**
1206    * Always zero.
1207    */
1208   uint32_t reserved GNUNET_PACKED;
1209
1210   /**
1211    * Hash of the file that we will unindex.
1212    */
1213   GNUNET_HashCode file_id;
1214
1215 };
1216
1217
1218 /**
1219  * Message sent from a GNUnet (fs) search
1220  * activity to the gnunet-fs-service to
1221  * start a search.
1222  */
1223 struct SearchMessage
1224 {
1225
1226   /**
1227    * Message type will be
1228    * GNUNET_MESSAGE_TYPE_FS_START_SEARCH.
1229    */
1230   struct GNUNET_MessageHeader header;
1231
1232   /**
1233    * Should be zero.
1234    */
1235   int32_t reserved GNUNET_PACKED;
1236
1237   /**
1238    * Type of the content that we're looking for.
1239    * 0 for any.
1240    */
1241   uint32_t type GNUNET_PACKED;
1242
1243   /**
1244    * Desired anonymity level, big-endian.
1245    */
1246   uint32_t anonymity_level GNUNET_PACKED;
1247
1248   /**
1249    * If the request is for a DBLOCK or IBLOCK, this is the identity of
1250    * the peer that is known to have a response.  Set to all-zeros if
1251    * such a target is not known (note that even if OUR anonymity
1252    * level is >0 we may happen to know the responder's identity;
1253    * nevertheless, we should probably not use it for a DHT-lookup
1254    * or similar blunt actions in order to avoid exposing ourselves).
1255    * <p>
1256    * If the request is for an SBLOCK, this is the identity of the
1257    * pseudonym to which the SBLOCK belongs.
1258    * <p>
1259    * If the request is for a KBLOCK, "target" must be all zeros.
1260    */
1261   GNUNET_HashCode target;
1262
1263   /**
1264    * Hash of the keyword (aka query) for KBLOCKs; Hash of
1265    * the CHK-encoded block for DBLOCKS and IBLOCKS (aka query)
1266    * and hash of the identifier XORed with the target for
1267    * SBLOCKS (aka query).
1268    */
1269   GNUNET_HashCode query;
1270
1271   /* this is followed by the hash codes of already-known
1272      results (which should hence be excluded from what
1273      the service returns); naturally, this only applies
1274      to queries that can have multiple results, such as
1275      those for KBLOCKS (KSK) and SBLOCKS (SKS) */
1276 };
1277
1278
1279 /**
1280  * Response from FS service with a result for
1281  * a previous FS search.  Note that queries
1282  * for DBLOCKS and IBLOCKS that have received
1283  * a single response are considered done.
1284  */
1285 struct ContentMessage
1286 {
1287
1288   /**
1289    * Message type will be
1290    * GNUNET_MESSAGE_TYPE_FS_CONTENT.
1291    */
1292   struct GNUNET_MessageHeader header;
1293
1294   /**
1295    * Type of the content that was found,
1296    * should never be 0.
1297    */
1298   uint32_t type GNUNET_PACKED;
1299
1300   /**
1301    * When will this result expire?
1302    */
1303   struct GNUNET_TIME_AbsoluteNBO expiration;
1304
1305   /* followed by the actual block of data */
1306
1307 };
1308
1309 /**
1310  * Only the (mandatory) query is included.
1311  */
1312 #define GET_MESSAGE_BIT_QUERY_ONLY 0
1313
1314 /**
1315  * The peer identity of a peer waiting for the
1316  * reply is included (used if the response
1317  * should be transmitted to someone other than
1318  * the sender of the GET).
1319  */
1320 #define GET_MESSAGE_BIT_RETURN_TO 1
1321
1322 /**
1323  * The hash of the public key of the target
1324  * namespace is included (for SKS queries).
1325  */
1326 #define GET_MESSAGE_BIT_SKS_NAMESPACE 2
1327
1328 /**
1329  * The peer identity of a peer that had claimed to have the content
1330  * previously is included (can be used if responder-anonymity is not
1331  * desired; note that the precursor presumably lacked a direct
1332  * connection to the specified peer; still, the receiver is in no way
1333  * required to limit forwarding only to the specified peer, it should
1334  * only prefer it somewhat if possible).
1335  */
1336 #define GET_MESSAGE_BIT_TRANSMIT_TO 4
1337
1338
1339 /**
1340  * Message sent between peers asking for FS-content.
1341  */
1342 struct GetMessage
1343 {
1344
1345   /**
1346    * Message type will be GNUNET_MESSAGE_TYPE_FS_GET.
1347    */
1348   struct GNUNET_MessageHeader header;
1349
1350   /**
1351    * Type of the query (block type).
1352    */
1353   uint32_t type GNUNET_PACKED;
1354
1355   /**
1356    * How important is this request (network byte order)
1357    */
1358   uint32_t priority GNUNET_PACKED;
1359
1360   /**
1361    * Relative time to live in GNUNET_CRON_MILLISECONDS (network byte order)
1362    */
1363   int32_t ttl GNUNET_PACKED;
1364
1365   /**
1366    * The content hash should be mutated using this value
1367    * before checking against the bloomfilter (used to
1368    * get many different filters for the same hash codes).
1369    * The number should be in big-endian format when used
1370    * for mingling.
1371    */
1372   int32_t filter_mutator GNUNET_PACKED;
1373
1374   /**
1375    * Which of the optional hash codes are present at the end of the
1376    * message?  See GET_MESSAGE_BIT_xx constants.  For each bit that is
1377    * set, an additional GNUNET_HashCode with the respective content
1378    * (in order of the bits) will be appended to the end of the GET
1379    * message.
1380    */
1381   uint32_t hash_bitmap GNUNET_PACKED;
1382
1383   /**
1384    * Hashcodes of the file(s) we're looking for.
1385    * Details depend on the query type.
1386    */
1387   GNUNET_HashCode query GNUNET_PACKED;
1388
1389   /* this is followed by hash codes
1390      as specified in the  "hash_bitmap";
1391      after that, an optional bloomfilter
1392      (with bits set for replies that should
1393      be suppressed) can be present */
1394 };
1395
1396
1397 /**
1398  * Message sent between peers providing FS-content.
1399  */
1400 struct PutMessage
1401 {
1402
1403   /**
1404    * Message type will be GNUNET_MESSAGE_TYPE_FS_PUT.
1405    */
1406   struct GNUNET_MessageHeader header;
1407
1408   /**
1409    * Type of the block (in big endian).
1410    */
1411   uint32_t type GNUNET_PACKED;
1412
1413   /**
1414    * When does this result expire?
1415    */
1416   struct GNUNET_TIME_RelativeNBO expiration;
1417
1418   /* this is followed by the actual encrypted content */
1419
1420 };
1421
1422
1423 #endif
1424
1425 /* end of fs.h */