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