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