src/fs/fs_api.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your 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      Affero General Public License for more details.
  14 */
  15
  16 /**
  17  * @file fs/fs_api.h
  18  * @brief shared definitions for the FS library
  19  * @author Igor Wronsky, Christian Grothoff
  20  */
  21 #ifndef FS_API_H
  22 #define FS_API_H
  23
  24 #include "gnunet_constants.h"
  25 #include "gnunet_datastore_service.h"
  26 #include "gnunet_dht_service.h"
  27 #include "gnunet_fs_service.h"
  28 #include "gnunet_block_lib.h"
  29 #include "block_fs.h"
  30 #include "fs.h"
  31
  32 /**
  33  * Pick a multiple of 2 here to achive 8-byte alignment!  We also
  34  * probably want DBlocks to have (roughly) the same size as IBlocks.
  35  * With SHA-512, the optimal value is 32768 byte / 128 byte = 256 (128
  36  * byte = 2 * 512 bits).  DO NOT CHANGE!
  37  */
  38 #define CHK_PER_INODE 256
  39
  40 /**
  41  * Maximum size for a file to be considered for inlining in a
  42  * directory.
  43  */
  44 #define MAX_INLINE_SIZE 65536
  45
  46 /**
  47  * Name of the directory with top-level searches.
  48  */
  49 #define GNUNET_FS_SYNC_PATH_MASTER_SEARCH "search"
  50
  51 /**
  52  * Name of the directory with sub-searches (namespace-updates).
  53  */
  54 #define GNUNET_FS_SYNC_PATH_CHILD_SEARCH "search-child"
  55
  56 /**
  57  * Name of the directory with master downloads (not associated
  58  * with search or part of another download).
  59  */
  60 #define GNUNET_FS_SYNC_PATH_MASTER_DOWNLOAD "download"
  61
  62 /**
  63  * Name of the directory with downloads that are part of another
  64  * download or a search.
  65  */
  66 #define GNUNET_FS_SYNC_PATH_CHILD_DOWNLOAD "download-child"
  67
  68 /**
  69  * Name of the directory with publishing operations.
  70  */
  71 #define GNUNET_FS_SYNC_PATH_MASTER_PUBLISH "publish"
  72
  73 /**
  74  * Name of the directory with files that are being published
  75  */
  76 #define GNUNET_FS_SYNC_PATH_FILE_INFO "publish-file"
  77
  78 /**
  79  * Name of the directory with unindex operations.
  80  */
  81 #define GNUNET_FS_SYNC_PATH_MASTER_UNINDEX "unindex"
  82
  83
  84 /**
  85  * @brief complete information needed
  86  * to download a file.
  87  */
  88 struct FileIdentifier
  89 {
  90
  91   /**
  92    * Total size of the file in bytes. (network byte order (!))
  93    */
  94   uint64_t file_length;
  95
  96   /**
  97    * Query and key of the top GNUNET_EC_IBlock.
  98    */
  99   struct ContentHashKey chk;
 100
 101 };
 102
 103
 104 /**
 105  * Information about a file and its location
 106  * (peer claiming to share the file).
 107  */
 108 struct Location
 109 {
 110   /**
 111    * Information about the shared file.
 112    */
 113   struct FileIdentifier fi;
 114
 115   /**
 116    * Identity of the peer sharing the file.
 117    */
 118   struct GNUNET_PeerIdentity peer;
 119
 120   /**
 121    * Time when this location URI expires.
 122    */
 123   struct GNUNET_TIME_Absolute expirationTime;
 124
 125   /**
 126    * Signature over the GNUNET_EC_FileIdentifier,
 127    * peer identity and expiration time.
 128    */
 129   struct GNUNET_CRYPTO_EddsaSignature contentSignature;
 130
 131 };
 132
 133 /**
 134  * Types of URIs.
 135  */
 136 enum GNUNET_FS_UriType
 137 {
 138   /**
 139    * Content-hash-key (simple file).
 140    */
 141   GNUNET_FS_URI_CHK,
 142
 143   /**
 144    * Signed key space (file in namespace).
 145    */
 146   GNUNET_FS_URI_SKS,
 147
 148   /**
 149    * Keyword search key (query with keywords).
 150    */
 151   GNUNET_FS_URI_KSK,
 152
 153   /**
 154    * Location (chk with identity of hosting peer).
 155    */
 156   GNUNET_FS_URI_LOC
 157 };
 158
 159
 160 /**
 161  * A Universal Resource Identifier (URI), opaque.
 162  */
 163 struct GNUNET_FS_Uri
 164 {
 165   /**
 166    * Type of the URI.
 167    */
 168   enum GNUNET_FS_UriType type;
 169
 170   union
 171   {
 172     struct
 173     {
 174       /**
 175        * Keywords start with a '+' if they are mandatory (in which
 176        * case the '+' is NOT part of the keyword) and with a simple
 177        * space if they are optional (in which case the space is ALSO
 178        * not part of the actual keyword).
 179        *
 180        * Double-quotes to protect spaces and %-encoding are NOT used
 181        * internally (only in URI-strings).
 182        */
 183       char **keywords;
 184
 185       /**
 186        * Size of the keywords array.
 187        */
 188       unsigned int keywordCount;
 189     } ksk;
 190
 191     struct
 192     {
 193       /**
 194        * Identifier of the namespace.
 195        */
 196       struct GNUNET_CRYPTO_EcdsaPublicKey ns;
 197
 198       /**
 199        * Human-readable identifier chosen for this entry in the
 200        * namespace.
 201        */
 202       char *identifier;
 203
 204     } sks;
 205
 206     /**
 207      * Information needed to retrieve a file (content-hash-key
 208      * plus file size).
 209      */
 210     struct FileIdentifier chk;
 211
 212     /**
 213      * Information needed to retrieve a file including signed
 214      * location (identity of a peer) of the content.
 215      */
 216     struct Location loc;
 217   } data;
 218
 219 };
 220
 221
 222 /**
 223  * Information for a file or directory that is
 224  * about to be published.
 225  */
 226 struct GNUNET_FS_FileInformation
 227 {
 228
 229   /**
 230    * Files in a directory are kept as a linked list.
 231    */
 232   struct GNUNET_FS_FileInformation *next;
 233
 234   /**
 235    * If this is a file in a directory, "dir" refers to
 236    * the directory; otherwise NULL.
 237    */
 238   struct GNUNET_FS_FileInformation *dir;
 239
 240   /**
 241    * Handle to the master context.
 242    */
 243   struct GNUNET_FS_Handle *h;
 244
 245   /**
 246    * Pointer kept for the client.
 247    */
 248   void *client_info;
 249
 250   /**
 251    * Metadata to use for the file.
 252    */
 253   struct GNUNET_CONTAINER_MetaData *meta;
 254
 255   /**
 256    * Keywords to use for KBlocks.
 257    */
 258   struct GNUNET_FS_Uri *keywords;
 259
 260   /**
 261    * CHK for this file or directory. NULL if
 262    * we have not yet computed it.
 263    */
 264   struct GNUNET_FS_Uri *chk_uri;
 265
 266   /**
 267    * SKS URI for this file or directory. NULL if
 268    * we have not yet computed it.
 269    */
 270   struct GNUNET_FS_Uri *sks_uri;
 271
 272   /**
 273    * Block options for the file.
 274    */
 275   struct GNUNET_FS_BlockOptions bo;
 276
 277   /**
 278    * At what time did we start this upload?
 279    */
 280   struct GNUNET_TIME_Absolute start_time;
 281
 282   /**
 283    * Under what filename is this struct serialized
 284    * (for operational persistence).  Should be determined
 285    * using 'mktemp'.
 286    */
 287   char *serialization;
 288
 289   /**
 290    * Encoder being used to publish this file.
 291    */
 292   struct GNUNET_FS_TreeEncoder *te;
 293
 294   /**
 295    * Error message (non-NULL if this operation failed).
 296    */
 297   char *emsg;
 298
 299   /**
 300    * Name of the file or directory (must be an absolute path).
 301    */
 302   char *filename;
 303
 304   /**
 305    * Data describing either the file or the directory.
 306    */
 307   union
 308   {
 309
 310     /**
 311      * Data for a file.
 312      */
 313     struct
 314     {
 315
 316       /**
 317        * Function that can be used to read the data for the file.
 318        */
 319       GNUNET_FS_DataReader reader;
 320
 321       /**
 322        * Closure for reader.
 323        */
 324       void *reader_cls;
 325
 326       /**
 327        * If this file is being indexed, this value is set to the hash
 328        * over the entire file (when the indexing process is started).
 329        * Otherwise this field is not used.
 330        */
 331       struct GNUNET_HashCode file_id;
 332
 333       /**
 334        * Size of the file (in bytes).
 335        */
 336       uint64_t file_size;
 337
 338       /**
 339        * Should the file be indexed or inserted?
 340        */
 341       int do_index;
 342
 343       /**
 344        * Is "file_id" already valid?  Set to #GNUNET_YES once the hash
 345        * has been calculated.
 346        */
 347       int have_hash;
 348
 349       /**
 350        * Has the service confirmed our INDEX_START request?
 351        * #GNUNET_YES if this step has been completed.
 352        */
 353       int index_start_confirmed;
 354
 355     } file;
 356
 357     /**
 358      * Data for a directory.
 359      */
 360     struct
 361     {
 362
 363       /**
 364        * Linked list of entries in the directory.
 365        */
 366       struct GNUNET_FS_FileInformation *entries;
 367
 368       /**
 369        * Size of the directory itself (in bytes); 0 if the
 370        * size has not yet been calculated.
 371        */
 372       size_t dir_size;
 373
 374       /**
 375        * Pointer to the data for the directory (or NULL if not
 376        * available).
 377        */
 378       void *dir_data;
 379
 380       /**
 381        * How much of the directory have we published (relative to @e contents_size).
 382        */
 383       uint64_t contents_completed;
 384
 385       /**
 386        * Sum of all of the sizes of all of the files in the directory.
 387        */
 388       uint64_t contents_size;
 389
 390     } dir;
 391
 392   } data;
 393
 394   /**
 395    * Is this struct for a file or directory?
 396    */
 397   int is_directory;
 398
 399   /**
 400    * Are we done publishing this file?
 401    */
 402   int is_published;
 403
 404 };
 405
 406
 407 /**
 408  * Priorities for the queue.
 409  */
 410 enum GNUNET_FS_QueuePriority
 411 {
 412   /**
 413    * This is a probe (low priority).
 414    */
 415   GNUNET_FS_QUEUE_PRIORITY_PROBE,
 416
 417   /**
 418    * Default priority.
 419    */
 420   GNUNET_FS_QUEUE_PRIORITY_NORMAL
 421 };
 422
 423
 424 /**
 425  * Entry in the job queue.
 426  */
 427 struct GNUNET_FS_QueueEntry
 428 {
 429   /**
 430    * This is a linked list.
 431    */
 432   struct GNUNET_FS_QueueEntry *next;
 433
 434   /**
 435    * This is a linked list.
 436    */
 437   struct GNUNET_FS_QueueEntry *prev;
 438
 439   /**
 440    * Function to call when the job is started.
 441    */
 442   GNUNET_SCHEDULER_TaskCallback start;
 443
 444   /**
 445    * Function to call when the job needs to stop (or is done / dequeued).
 446    */
 447   GNUNET_SCHEDULER_TaskCallback stop;
 448
 449   /**
 450    * Closure for start and stop.
 451    */
 452   void *cls;
 453
 454   /**
 455    * Handle to FS primary context.
 456    */
 457   struct GNUNET_FS_Handle *h;
 458
 459   /**
 460    * Message queue handle, or NULL if job is not running.
 461    */
 462   struct GNUNET_MQ_Handle *mq;
 463
 464   /**
 465    * Time the job was originally queued.
 466    */
 467   struct GNUNET_TIME_Absolute queue_time;
 468
 469   /**
 470    * Time the job was started last.
 471    */
 472   struct GNUNET_TIME_Absolute start_time;
 473
 474   /**
 475    * Total amount of time the job has been running (except for the
 476    * current run).
 477    */
 478   struct GNUNET_TIME_Relative run_time;
 479
 480   /**
 481    * How many blocks do the active downloads have?
 482    */
 483   unsigned int blocks;
 484
 485   /**
 486    * How important is this download?
 487    */
 488   enum GNUNET_FS_QueuePriority priority;
 489
 490   /**
 491    * How often have we (re)started this download?
 492    */
 493   unsigned int start_times;
 494
 495   /**
 496    * #GNUNET_YES if the job is active now.
 497    */
 498   int active;
 499
 500 };
 501
 502
 503 /**
 504  * Information we store for each search result.
 505  */
 506 struct GNUNET_FS_SearchResult
 507 {
 508
 509   /**
 510    * File-sharing context this result belongs to.
 511    */
 512   struct GNUNET_FS_Handle *h;
 513
 514   /**
 515    * Kept in a DLL while probing.
 516    */
 517   struct GNUNET_FS_SearchResult *next;
 518
 519   /**
 520    * Kept in a DLL while probing.
 521    */
 522   struct GNUNET_FS_SearchResult *prev;
 523
 524   /**
 525    * Search context this result belongs to; can be NULL
 526    * for probes that come from a directory result.
 527    */
 528   struct GNUNET_FS_SearchContext *sc;
 529
 530   /**
 531    * URI to which this search result refers to.
 532    */
 533   struct GNUNET_FS_Uri *uri;
 534
 535   /**
 536    * Metadata for the search result.
 537    */
 538   struct GNUNET_CONTAINER_MetaData *meta;
 539
 540   /**
 541    * Client info for this search result.
 542    */
 543   void *client_info;
 544
 545   /**
 546    * ID of a job that is currently probing this results' availability
 547    * (NULL if we are not currently probing).
 548    */
 549   struct GNUNET_FS_DownloadContext *probe_ctx;
 550
 551   /**
 552    * ID of an associated download based on this search result (or
 553    * NULL for none).
 554    */
 555   struct GNUNET_FS_DownloadContext *download;
 556
 557   /**
 558    * If this search result triggered an update search, this field
 559    * links to the update search.
 560    */
 561   struct GNUNET_FS_SearchContext *update_search;
 562
 563   /**
 564    * Name under which this search result is stored on disk.
 565    */
 566   char *serialization;
 567
 568   /**
 569    * Bitmap that specifies precisely which keywords have been matched already.
 570    */
 571   uint8_t *keyword_bitmap;
 572
 573   /**
 574    * Key for the search result based on the URI.
 575    */
 576   struct GNUNET_HashCode key;
 577
 578   /**
 579    * ID of the task that will clean up the probe_ctx should it not
 580    * complete on time (and that will need to be cancelled if we clean
 581    * up the search result before then).
 582    */
 583   struct GNUNET_SCHEDULER_Task * probe_cancel_task;
 584
 585   /**
 586    * When did the current probe become active?
 587    */
 588   struct GNUNET_TIME_Absolute probe_active_time;
 589
 590   /**
 591    * How much longer should we run the current probe before giving up?
 592    */
 593   struct GNUNET_TIME_Relative remaining_probe_time;
 594
 595   /**
 596    * Anonymity level to use for probes using this search result.
 597    */
 598   uint32_t anonymity;
 599
 600   /**
 601    * Number of mandatory keywords for which we have NOT yet found the
 602    * search result; when this value hits zero, the search result is
 603    * given to the callback.
 604    */
 605   uint32_t mandatory_missing;
 606
 607   /**
 608    * Number of optional keywords under which this result was also
 609    * found.
 610    */
 611   uint32_t optional_support;
 612
 613   /**
 614    * Number of availability tests that have succeeded for this result.
 615    */
 616   uint32_t availability_success;
 617
 618   /**
 619    * Number of availability trials that we have performed for this
 620    * search result.
 621    */
 622   uint32_t availability_trials;
 623
 624 };
 625
 626
 627 /**
 628  * Add a job to the queue.
 629  *
 630  * @param h handle to the overall FS state
 631  * @param start function to call to begin the job
 632  * @param stop function to call to pause the job, or on dequeue (if the job was running)
 633  * @param cls closure for start and stop
 634  * @param blocks number of blocks this download has
 635  * @param priority how important is this download
 636  * @return queue handle
 637  */
 638 struct GNUNET_FS_QueueEntry *
 639 GNUNET_FS_queue_ (struct GNUNET_FS_Handle *h,
 640                   GNUNET_SCHEDULER_TaskCallback start,
 641                   GNUNET_SCHEDULER_TaskCallback stop,
 642                   void *cls,
 643                   unsigned int blocks,
 644                   enum GNUNET_FS_QueuePriority priority);
 645
 646
 647 /**
 648  * Dequeue a job from the queue.
 649  *
 650  * @param qe handle for the job
 651  */
 652 void
 653 GNUNET_FS_dequeue_ (struct GNUNET_FS_QueueEntry *qe);
 654
 655
 656 /**
 657  * Function that provides data by reading from a file.
 658  *
 659  * @param cls closure (points to the file information)
 660  * @param offset offset to read from; it is possible
 661  *            that the caller might need to go backwards
 662  *            a bit at times
 663  * @param max maximum number of bytes that should be
 664  *            copied to @a buf; readers are not allowed
 665  *            to provide less data unless there is an error;
 666  *            a value of "0" will be used at the end to allow
 667  *            the reader to clean up its internal state
 668  * @param buf where the reader should write the data
 669  * @param emsg location for the reader to store an error message
 670  * @return number of bytes written, usually "max", 0 on error
 671  */
 672 size_t
 673 GNUNET_FS_data_reader_file_ (void *cls,
 674                              uint64_t offset,
 675                              size_t max,
 676                              void *buf,
 677                              char **emsg);
 678
 679
 680 /**
 681  * Create the closure for the #GNUNET_FS_data_reader_file_() callback.
 682  *
 683  * @param filename file to read
 684  * @return closure to use
 685  */
 686 void *
 687 GNUNET_FS_make_file_reader_context_ (const char *filename);
 688
 689
 690
 691 /**
 692  * Function that provides data by copying from a buffer.
 693  *
 694  * @param cls closure (points to the buffer)
 695  * @param offset offset to read from; it is possible
 696  *            that the caller might need to go backwards
 697  *            a bit at times
 698  * @param max maximum number of bytes that should be
 699  *            copied to @a buf; readers are not allowed
 700  *            to provide less data unless there is an error;
 701  *            a value of "0" will be used at the end to allow
 702  *            the reader to clean up its internal state
 703  * @param buf where the reader should write the data
 704  * @param emsg location for the reader to store an error message
 705  * @return number of bytes written, usually @a max, 0 on error
 706  */
 707 size_t
 708 GNUNET_FS_data_reader_copy_ (void *cls,
 709                              uint64_t offset,
 710                              size_t max,
 711                              void *buf,
 712                              char **emsg);
 713
 714
 715 /**
 716  * Notification of FS that a search probe has made progress.
 717  * This function is used INSTEAD of the client's event handler
 718  * for downloads where the #GNUNET_FS_DOWNLOAD_IS_PROBE flag is set.
 719  *
 720  * @param cls closure, always NULL (!), actual closure
 721  *        is in the client-context of the info struct
 722  * @param info details about the event, specifying the event type
 723  *        and various bits about the event
 724  * @return client-context (for the next progress call
 725  *         for this operation; should be set to NULL for
 726  *         SUSPEND and STOPPED events).  The value returned
 727  *         will be passed to future callbacks in the respective
 728  *         field in the `struct GNUNET_FS_ProgressInfo`.
 729  */
 730 void *
 731 GNUNET_FS_search_probe_progress_ (void *cls,
 732                                   const struct GNUNET_FS_ProgressInfo *info);
 733
 734
 735 /**
 736  * Main function that performs the upload.
 737  *
 738  * @param cls `struct GNUNET_FS_PublishContext` identifies the upload
 739  */
 740 void
 741 GNUNET_FS_publish_main_ (void *cls);
 742
 743
 744 /**
 745  * Function called once the hash of the file
 746  * that is being unindexed has been computed.
 747  *
 748  * @param cls closure, unindex context
 749  * @param file_id computed hash, NULL on error
 750  */
 751 void
 752 GNUNET_FS_unindex_process_hash_ (void *cls,
 753                                  const struct GNUNET_HashCode *file_id);
 754
 755
 756 /**
 757  * Extract the keywords for KBlock removal
 758  *
 759  * @param uc context for the unindex operation.
 760  */
 761 void
 762 GNUNET_FS_unindex_do_extract_keywords_ (struct GNUNET_FS_UnindexContext *uc);
 763
 764
 765 /**
 766  * If necessary, connect to the datastore and remove the KBlocks.
 767  *
 768  * @param uc context for the unindex operation.
 769  */
 770 void
 771 GNUNET_FS_unindex_do_remove_kblocks_ (struct GNUNET_FS_UnindexContext *uc);
 772
 773
 774 /**
 775  * Fill in all of the generic fields for a publish event and call the
 776  * callback.
 777  *
 778  * @param pi structure to fill in
 779  * @param pc overall publishing context
 780  * @param p file information for the file being published
 781  * @param offset where in the file are we so far
 782  * @return value returned from callback
 783  */
 784 void *
 785 GNUNET_FS_publish_make_status_ (struct GNUNET_FS_ProgressInfo *pi,
 786                                 struct GNUNET_FS_PublishContext *pc,
 787                                 const struct GNUNET_FS_FileInformation *p,
 788                                 uint64_t offset);
 789
 790
 791 /**
 792  * Fill in all of the generic fields for a download event and call the
 793  * callback.
 794  *
 795  * @param pi structure to fill in
 796  * @param dc overall download context
 797  */
 798 void
 799 GNUNET_FS_download_make_status_ (struct GNUNET_FS_ProgressInfo *pi,
 800                                  struct GNUNET_FS_DownloadContext *dc);
 801
 802
 803 /**
 804  * Task that creates the initial (top-level) download
 805  * request for the file.
 806  *
 807  * @param cls the 'struct GNUNET_FS_DownloadContext'
 808  */
 809 void
 810 GNUNET_FS_download_start_task_ (void *cls);
 811
 812
 813
 814 /**
 815  * Fill in all of the generic fields for
 816  * an unindex event and call the callback.
 817  *
 818  * @param pi structure to fill in
 819  * @param uc overall unindex context
 820  * @param offset where we are in the file (for progress)
 821  */
 822 void
 823 GNUNET_FS_unindex_make_status_ (struct GNUNET_FS_ProgressInfo *pi,
 824                                 struct GNUNET_FS_UnindexContext *uc,
 825                                 uint64_t offset);
 826
 827 /**
 828  * Fill in all of the generic fields for a search event and
 829  * call the callback.
 830  *
 831  * @param pi structure to fill in
 832  * @param h file-sharing handle
 833  * @param sc overall search context
 834  * @return value returned by the callback
 835  */
 836 void *
 837 GNUNET_FS_search_make_status_ (struct GNUNET_FS_ProgressInfo *pi,
 838                                struct GNUNET_FS_Handle *h,
 839                                struct GNUNET_FS_SearchContext *sc);
 840
 841
 842 /**
 843  * Connect to the datastore and remove the blocks.
 844  *
 845  * @param uc context for the unindex operation.
 846  */
 847 void
 848 GNUNET_FS_unindex_do_remove_ (struct GNUNET_FS_UnindexContext *uc);
 849
 850 /**
 851  * Build the request and actually initiate the search using the
 852  * GNUnet FS service.
 853  *
 854  * @param sc search context
 855  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 856  */
 857 int
 858 GNUNET_FS_search_start_searching_ (struct GNUNET_FS_SearchContext *sc);
 859
 860 /**
 861  * Start the downloading process (by entering the queue).
 862  *
 863  * @param dc our download context
 864  */
 865 void
 866 GNUNET_FS_download_start_downloading_ (struct GNUNET_FS_DownloadContext *dc);
 867
 868
 869 /**
 870  * Start download probes for the given search result.
 871  *
 872  * @param sr the search result
 873  */
 874 void
 875 GNUNET_FS_search_start_probe_ (struct GNUNET_FS_SearchResult *sr);
 876
 877
 878 /**
 879  * Remove serialization/deserialization file from disk.
 880  *
 881  * @param h master context
 882  * @param ext component of the path
 883  * @param ent entity identifier
 884  */
 885 void
 886 GNUNET_FS_remove_sync_file_ (struct GNUNET_FS_Handle *h,
 887                              const char *ext,
 888                              const char *ent);
 889
 890
 891 /**
 892  * Remove serialization/deserialization directory from disk.
 893  *
 894  * @param h master context
 895  * @param ext component of the path
 896  * @param uni unique name of parent
 897  */
 898 void
 899 GNUNET_FS_remove_sync_dir_ (struct GNUNET_FS_Handle *h,
 900                             const char *ext,
 901                             const char *uni);
 902
 903
 904 /**
 905  * Synchronize this file-information struct with its mirror
 906  * on disk.  Note that all internal FS-operations that change
 907  * file information data should already call "sync" internally,
 908  * so this function is likely not useful for clients.
 909  *
 910  * @param fi the struct to sync
 911  */
 912 void
 913 GNUNET_FS_file_information_sync_ (struct GNUNET_FS_FileInformation *f);
 914
 915
 916 /**
 917  * Synchronize this publishing struct with its mirror
 918  * on disk.  Note that all internal FS-operations that change
 919  * publishing structs should already call "sync" internally,
 920  * so this function is likely not useful for clients.
 921  *
 922  * @param pc the struct to sync
 923  */
 924 void
 925 GNUNET_FS_publish_sync_ (struct GNUNET_FS_PublishContext *pc);
 926
 927
 928 /**
 929  * Synchronize this unindex struct with its mirror
 930  * on disk.  Note that all internal FS-operations that change
 931  * publishing structs should already call "sync" internally,
 932  * so this function is likely not useful for clients.
 933  *
 934  * @param uc the struct to sync
 935  */
 936 void
 937 GNUNET_FS_unindex_sync_ (struct GNUNET_FS_UnindexContext *uc);
 938
 939
 940 /**
 941  * Synchronize this search struct with its mirror
 942  * on disk.  Note that all internal FS-operations that change
 943  * publishing structs should already call "sync" internally,
 944  * so this function is likely not useful for clients.
 945  *
 946  * @param sc the struct to sync
 947  */
 948 void
 949 GNUNET_FS_search_sync_ (struct GNUNET_FS_SearchContext *sc);
 950
 951
 952 /**
 953  * Synchronize this search result with its mirror
 954  * on disk.  Note that all internal FS-operations that change
 955  * publishing structs should already call "sync" internally,
 956  * so this function is likely not useful for clients.
 957  *
 958  * @param sr the struct to sync
 959  */
 960 void
 961 GNUNET_FS_search_result_sync_ (struct GNUNET_FS_SearchResult *sr);
 962
 963
 964 /**
 965  * Synchronize this download struct with its mirror
 966  * on disk.  Note that all internal FS-operations that change
 967  * publishing structs should already call "sync" internally,
 968  * so this function is likely not useful for clients.
 969  *
 970  * @param dc the struct to sync
 971  */
 972 void
 973 GNUNET_FS_download_sync_ (struct GNUNET_FS_DownloadContext *dc);
 974
 975
 976 /**
 977  * Create SUSPEND event for the given publish operation
 978  * and then clean up our state (without stop signal).
 979  *
 980  * @param cls the `struct GNUNET_FS_PublishContext` to signal for
 981  */
 982 void
 983 GNUNET_FS_publish_signal_suspend_ (void *cls);
 984
 985
 986 /**
 987  * Create SUSPEND event for the given search operation
 988  * and then clean up our state (without stop signal).
 989  *
 990  * @param cls the 'struct GNUNET_FS_SearchContext' to signal for
 991  */
 992 void
 993 GNUNET_FS_search_signal_suspend_ (void *cls);
 994
 995
 996 /**
 997  * Create SUSPEND event for the given download operation
 998  * and then clean up our state (without stop signal).
 999  *
1000  * @param cls the `struct GNUNET_FS_DownloadContext` to signal for
1001  */
1002 void
1003 GNUNET_FS_download_signal_suspend_ (void *cls);
1004
1005
1006 /**
1007  * Create SUSPEND event for the given unindex operation
1008  * and then clean up our state (without stop signal).
1009  *
1010  * @param cls the `struct GNUNET_FS_UnindexContext` to signal for
1011  */
1012 void
1013 GNUNET_FS_unindex_signal_suspend_ (void *cls);
1014
1015
1016 /**
1017  * Function signature of the functions that can be called
1018  * to trigger suspend signals and clean-up for top-level
1019  * activities.
1020  *
1021  * @param cls closure
1022  */
1023 typedef void (*SuspendSignalFunction) (void *cls);
1024
1025 /**
1026  * We track all of the top-level activities of FS
1027  * so that we can signal 'suspend' on shutdown.
1028  */
1029 struct TopLevelActivity
1030 {
1031   /**
1032    * This is a doubly-linked list.
1033    */
1034   struct TopLevelActivity *next;
1035
1036   /**
1037    * This is a doubly-linked list.
1038    */
1039   struct TopLevelActivity *prev;
1040
1041   /**
1042    * Function to call for suspend-signalling and clean up.
1043    */
1044   SuspendSignalFunction ssf;
1045
1046   /**
1047    * Closure for 'ssf' (some struct GNUNET_FS_XXXHandle*)
1048    */
1049   void *ssf_cls;
1050 };
1051
1052
1053 /**
1054  * Create a top-level activity entry.
1055  *
1056  * @param h global fs handle
1057  * @param ssf suspend signal function to use
1058  * @param ssf_cls closure for @a ssf
1059  * @return fresh top-level activity handle
1060  */
1061 struct TopLevelActivity *
1062 GNUNET_FS_make_top (struct GNUNET_FS_Handle *h,
1063                     SuspendSignalFunction ssf,
1064                     void *ssf_cls);
1065
1066
1067 /**
1068  * Destroy a top-level activity entry.
1069  *
1070  * @param h global fs handle
1071  * @param top top level activity entry
1072  */
1073 void
1074 GNUNET_FS_end_top (struct GNUNET_FS_Handle *h,
1075                    struct TopLevelActivity *top);
1076
1077
1078
1079 /**
1080  * Master context for most FS operations.
1081  */
1082 struct GNUNET_FS_Handle
1083 {
1084   /**
1085    * Configuration to use.
1086    */
1087   const struct GNUNET_CONFIGURATION_Handle *cfg;
1088
1089   /**
1090    * Name of our client.
1091    */
1092   char *client_name;
1093
1094   /**
1095    * Function to call with updates on our progress.
1096    */
1097   GNUNET_FS_ProgressCallback upcb;
1098
1099   /**
1100    * Closure for upcb.
1101    */
1102   void *upcb_cls;
1103
1104   /**
1105    * Head of DLL of top-level activities.
1106    */
1107   struct TopLevelActivity *top_head;
1108
1109   /**
1110    * Tail of DLL of top-level activities.
1111    */
1112   struct TopLevelActivity *top_tail;
1113
1114   /**
1115    * Head of DLL of running jobs.
1116    */
1117   struct GNUNET_FS_QueueEntry *running_head;
1118
1119   /**
1120    * Tail of DLL of running jobs.
1121    */
1122   struct GNUNET_FS_QueueEntry *running_tail;
1123
1124   /**
1125    * Head of DLL of pending jobs.
1126    */
1127   struct GNUNET_FS_QueueEntry *pending_head;
1128
1129   /**
1130    * Tail of DLL of pending jobs.
1131    */
1132   struct GNUNET_FS_QueueEntry *pending_tail;
1133
1134   /**
1135    * Head of active probes.
1136    */
1137   struct GNUNET_FS_SearchResult *probes_head;
1138
1139   /**
1140    * Tail of active probes.
1141    */
1142   struct GNUNET_FS_SearchResult *probes_tail;
1143
1144   /**
1145    * Task that processes the jobs in the running and pending queues
1146    * (and moves jobs around as needed).
1147    */
1148   struct GNUNET_SCHEDULER_Task * queue_job;
1149
1150   /**
1151    * Task we use to report periodically to the application that
1152    * certain search probes (from @e probes_head) are still running.
1153    */
1154   struct GNUNET_SCHEDULER_Task * probe_ping_task;
1155
1156   /**
1157    * Average time we take for a single request to be satisfied.
1158    * FIXME: not yet calcualted properly...
1159    */
1160   struct GNUNET_TIME_Relative avg_block_latency;
1161
1162   /**
1163    * How many actual downloads do we have running right now?
1164    */
1165   unsigned int active_downloads;
1166
1167   /**
1168    * How many blocks do the active downloads have?
1169    */
1170   unsigned int active_blocks;
1171
1172   /**
1173    * General flags.
1174    */
1175   enum GNUNET_FS_Flags flags;
1176
1177   /**
1178    * Maximum number of parallel downloads.
1179    */
1180   unsigned int max_parallel_downloads;
1181
1182   /**
1183    * Maximum number of parallel requests.
1184    */
1185   unsigned int max_parallel_requests;
1186
1187 };
1188
1189
1190 /**
1191  * Handle for controlling a publication process.
1192  */
1193 struct GNUNET_FS_PublishContext
1194 {
1195   /**
1196    * Handle to the global fs context.
1197    */
1198   struct GNUNET_FS_Handle *h;
1199
1200   /**
1201    * Our top-level activity entry (if we are top-level, otherwise NULL).
1202    */
1203   struct TopLevelActivity *top;
1204
1205   /**
1206    * File-structure that is being shared.
1207    */
1208   struct GNUNET_FS_FileInformation *fi;
1209
1210   /**
1211    * Namespace that we are publishing in, NULL if we have no namespace.
1212    */
1213   struct GNUNET_CRYPTO_EcdsaPrivateKey *ns;
1214
1215   /**
1216    * ID of the content in the namespace, NULL if we have no namespace.
1217    */
1218   char *nid;
1219
1220   /**
1221    * ID for future updates, NULL if we have no namespace or no updates.
1222    */
1223   char *nuid;
1224
1225   /**
1226    * Filename used for serializing information about this operation
1227    * (should be determined using 'mktemp').
1228    */
1229   char *serialization;
1230
1231   /**
1232    * Our own message queue for the FS service; only briefly used when
1233    * we start to index a file, otherwise NULL.
1234    */
1235   struct GNUNET_MQ_Handle *mq;
1236
1237   /**
1238    * Current position in the file-tree for the upload.
1239    */
1240   struct GNUNET_FS_FileInformation *fi_pos;
1241
1242   /**
1243    * Non-null if we are currently hashing a file.
1244    */
1245   struct GNUNET_CRYPTO_FileHashContext *fhc;
1246
1247   /**
1248    * Connection to the datastore service.
1249    */
1250   struct GNUNET_DATASTORE_Handle *dsh;
1251
1252   /**
1253    * Queue entry for reservation/unreservation.
1254    */
1255   struct GNUNET_DATASTORE_QueueEntry *qre;
1256
1257   /**
1258    * Context for SKS publishing operation that is part of this publishing operation
1259    * (NULL if not active).
1260    */
1261   struct GNUNET_FS_PublishSksContext *sks_pc;
1262
1263   /**
1264    * Context for KSK publishing operation that is part of this publishing operation
1265    * (NULL if not active).
1266    */
1267   struct GNUNET_FS_PublishKskContext *ksk_pc;
1268
1269   /**
1270    * ID of the task performing the upload. NO_TASK if the upload has
1271    * completed.
1272    */
1273   struct GNUNET_SCHEDULER_Task * upload_task;
1274
1275   /**
1276    * Storage space to reserve for the operation.
1277    */
1278   uint64_t reserve_space;
1279
1280   /**
1281    * Overall number of entries to reserve for the
1282    * publish operation.
1283    */
1284   uint32_t reserve_entries;
1285
1286   /**
1287    * Options for publishing.
1288    */
1289   enum GNUNET_FS_PublishOptions options;
1290
1291   /**
1292    * Space reservation ID with datastore service
1293    * for this upload.
1294    */
1295   int rid;
1296
1297   /**
1298    * Set to #GNUNET_YES if we were able to publish any block.
1299    * (and thus unindexing on error might make sense).
1300    */
1301   int any_done;
1302
1303   /**
1304    * Set to #GNUNET_YES if all processing has completed.
1305    */
1306   int all_done;
1307
1308   /**
1309    * Flag set to #GNUNET_YES if the next callback from
1310    * #GNUNET_FS_file_information_inspect should be skipped because it
1311    * is for the directory which was already processed with the parent.
1312    */
1313   int skip_next_fi_callback;
1314 };
1315
1316
1317 /**
1318  * Phases of unindex processing (state machine).
1319  */
1320 enum UnindexState
1321 {
1322   /**
1323    * We're currently hashing the file.
1324    */
1325   UNINDEX_STATE_HASHING = 0,
1326
1327   /**
1328    * We're telling the datastore to delete
1329    * the respective DBlocks and IBlocks.
1330    */
1331   UNINDEX_STATE_DS_REMOVE = 1,
1332
1333   /**
1334    * Find out which keywords apply.
1335    */
1336   UNINDEX_STATE_EXTRACT_KEYWORDS = 2,
1337
1338   /**
1339    * We're telling the datastore to remove KBlocks.
1340    */
1341   UNINDEX_STATE_DS_REMOVE_KBLOCKS = 3,
1342
1343   /**
1344    * We're notifying the FS service about
1345    * the unindexing.
1346    */
1347   UNINDEX_STATE_FS_NOTIFY = 4,
1348
1349   /**
1350    * We're done.
1351    */
1352   UNINDEX_STATE_COMPLETE = 5,
1353
1354   /**
1355    * We've encountered a fatal error.
1356    */
1357   UNINDEX_STATE_ERROR = 6
1358 };
1359
1360
1361 /**
1362  * Handle for controlling an unindexing operation.
1363  */
1364 struct GNUNET_FS_UnindexContext
1365 {
1366
1367   /**
1368    * The content hash key of the last block we processed, will in the
1369    * end be set to the CHK from the URI.  Used to remove the KBlocks.
1370    */
1371   struct ContentHashKey chk;
1372
1373   /**
1374    * Global FS context.
1375    */
1376   struct GNUNET_FS_Handle *h;
1377
1378   /**
1379    * Our top-level activity entry.
1380    */
1381   struct TopLevelActivity *top;
1382
1383   /**
1384    * Directory scanner to find keywords (KBlock removal).
1385    */
1386   struct GNUNET_FS_DirScanner *dscan;
1387
1388   /**
1389    * Keywords found (telling us which KBlocks to remove).
1390    */
1391   struct GNUNET_FS_Uri *ksk_uri;
1392
1393   /**
1394    * Current offset in KSK removal.
1395    */
1396   uint32_t ksk_offset;
1397
1398   /**
1399    * Name of the file that we are unindexing.
1400    */
1401   char *filename;
1402
1403   /**
1404    * Short name under which we are serializing the state of this operation.
1405    */
1406   char *serialization;
1407
1408   /**
1409    * Connection to the FS service, only valid during the
1410    * #UNINDEX_STATE_FS_NOTIFY phase.
1411    */
1412   struct GNUNET_MQ_Handle *mq;
1413
1414   /**
1415    * Connection to the datastore service, only valid during the
1416    * UNINDEX_STATE_DS_NOTIFY phase.
1417    */
1418   struct GNUNET_DATASTORE_Handle *dsh;
1419
1420   /**
1421    * Pointer kept for the client.
1422    */
1423   void *client_info;
1424
1425   /**
1426    * Merkle-ish tree encoder context.
1427    */
1428   struct GNUNET_FS_TreeEncoder *tc;
1429
1430   /**
1431    * Handle used to read the file.
1432    */
1433   struct GNUNET_DISK_FileHandle *fh;
1434
1435   /**
1436    * Handle to datastore 'get_key' operation issued for
1437    * obtaining KBlocks.
1438    */
1439   struct GNUNET_DATASTORE_QueueEntry *dqe;
1440
1441   /**
1442    * Current key for decrypting UBLocks from 'get_key' operation.
1443    */
1444   struct GNUNET_HashCode ukey;
1445
1446   /**
1447    * Current query of 'get_key' operation.
1448    */
1449   struct GNUNET_HashCode uquery;
1450
1451   /**
1452    * Error message, NULL on success.
1453    */
1454   char *emsg;
1455
1456   /**
1457    * Context for hashing of the file.
1458    */
1459   struct GNUNET_CRYPTO_FileHashContext *fhc;
1460
1461   /**
1462    * Overall size of the file.
1463    */
1464   uint64_t file_size;
1465
1466   /**
1467    * When did we start?
1468    */
1469   struct GNUNET_TIME_Absolute start_time;
1470
1471   /**
1472    * Hash of the file's contents (once computed).
1473    */
1474   struct GNUNET_HashCode file_id;
1475
1476   /**
1477    * Current operatinonal phase.
1478    */
1479   enum UnindexState state;
1480
1481 };
1482
1483
1484 /**
1485  * Information we keep for each keyword in a keyword search.
1486  */
1487 struct SearchRequestEntry
1488 {
1489
1490   /**
1491    * Hash of the public key, also known as the query.
1492    */
1493   struct GNUNET_HashCode uquery;
1494
1495   /**
1496    * Derived public key, hashes to 'uquery'.
1497    */
1498   struct GNUNET_CRYPTO_EcdsaPublicKey dpub;
1499
1500   /**
1501    * The original keyword, used to derive the
1502    * key (for decrypting the UBlock).
1503    */
1504   char *keyword;
1505
1506   /**
1507    * Map that contains a "struct GNUNET_FS_SearchResult" for each result that
1508    * was found under this keyword.  Note that the entries will point
1509    * to the same locations as those in the master result map (in
1510    * "struct GNUNET_FS_SearchContext"), so they should not be freed.
1511    * The key for each entry is the XOR of the key and query in the CHK
1512    * URI (as a unique identifier for the search result).
1513    */
1514   struct GNUNET_CONTAINER_MultiHashMap *results;
1515
1516   /**
1517    * Is this keyword a mandatory keyword
1518    * (started with '+')?
1519    */
1520   int mandatory;
1521
1522 };
1523
1524
1525 /**
1526  * Handle for controlling a search.
1527  */
1528 struct GNUNET_FS_SearchContext
1529 {
1530   /**
1531    * Handle to the global FS context.
1532    */
1533   struct GNUNET_FS_Handle *h;
1534
1535   /**
1536    * Our top-level activity entry (if we are top-level, otherwise NULL).
1537    */
1538   struct TopLevelActivity *top;
1539
1540   /**
1541    * List of keywords that we're looking for.
1542    */
1543   struct GNUNET_FS_Uri *uri;
1544
1545   /**
1546    * For update-searches, link to the search result that triggered
1547    * the update search; otherwise NULL.
1548    */
1549   struct GNUNET_FS_SearchResult *psearch_result;
1550
1551   /**
1552    * Connection to the FS service.
1553    */
1554   struct GNUNET_MQ_Handle *mq;
1555
1556   /**
1557    * Pointer we keep for the client.
1558    */
1559   void *client_info;
1560
1561   /**
1562    * Name of the file on disk we use for persistence.
1563    */
1564   char *serialization;
1565
1566   /**
1567    * Error message (non-NULL if this operation failed).
1568    */
1569   char *emsg;
1570
1571   /**
1572    * Map that contains a `struct GNUNET_FS_SearchResult` for each result that
1573    * was found in the search.  The key for each entry is the XOR of
1574    * the key and query in the CHK URI (as a unique identifier for the
1575    * search result).
1576    */
1577   struct GNUNET_CONTAINER_MultiHashMap *master_result_map;
1578
1579   /**
1580    * Per-keyword information for a keyword search.  This array will
1581    * have exactly as many entries as there were keywords.
1582    */
1583   struct SearchRequestEntry *requests;
1584
1585   /**
1586    * When did we start?
1587    */
1588   struct GNUNET_TIME_Absolute start_time;
1589
1590   /**
1591    * How long to wait before we try to reconnect to FS service?
1592    */
1593   struct GNUNET_TIME_Relative reconnect_backoff;
1594
1595   /**
1596    * ID of a task that is using this struct and that must be cancelled
1597    * when the search is being stopped (if not
1598    * NULL).  Used for the task that adds some
1599    * artificial delay when trying to reconnect to the FS service.
1600    */
1601   struct GNUNET_SCHEDULER_Task *task;
1602
1603   /**
1604    * Anonymity level for the search.
1605    */
1606   uint32_t anonymity;
1607
1608   /**
1609    * Number of mandatory keywords in this query.
1610    */
1611   uint32_t mandatory_count;
1612
1613   /**
1614    * Options for the search.
1615    */
1616   enum GNUNET_FS_SearchOptions options;
1617 };
1618
1619
1620 /**
1621  * FSM for possible states a block can go through.  The typical
1622  * order of progression is linear through the states, alternatives
1623  * are documented in the comments.
1624  */
1625 enum BlockRequestState
1626 {
1627   /**
1628    * Initial state, block has only been allocated (since it is
1629    * relevant to the overall download request).
1630    */
1631   BRS_INIT = 0,
1632
1633   /**
1634    * We've checked the block on the path down the tree, and the
1635    * content on disk did match the desired CHK, but not all
1636    * the way down, so at the bottom some blocks will still
1637    * need to be reconstructed).
1638    */
1639   BRS_RECONSTRUCT_DOWN = 1,
1640
1641   /**
1642    * We've calculated the CHK bottom-up based on the meta data.
1643    * This may work, but if it did we have to write the meta data to
1644    * disk at the end (and we still need to check against the
1645    * CHK set on top).
1646    */
1647   BRS_RECONSTRUCT_META_UP = 2,
1648
1649   /**
1650    * We've calculated the CHK bottom-up based on what we have on
1651    * disk, which may not be what the desired CHK is.  If the
1652    * reconstructed CHKs match whatever comes from above, we're
1653    * done with the respective subtree.
1654    */
1655   BRS_RECONSTRUCT_UP = 3,
1656
1657   /**
1658    * We've determined the real, desired CHK for this block
1659    * (full tree reconstruction failed), request is now pending.
1660    * If the CHK that bubbled up through reconstruction did match
1661    * the top-level request, the state machine for the subtree
1662    * would have moved to BRS_DOWNLOAD_UP.
1663    */
1664   BRS_CHK_SET = 4,
1665
1666   /**
1667    * We've successfully downloaded this block, but the children
1668    * still need to be either downloaded or verified (download
1669    * request propagates down).  If the download fails, the
1670    * state machine for this block may move to
1671    * BRS_DOWNLOAD_ERROR instead.
1672    */
1673   BRS_DOWNLOAD_DOWN = 5,
1674
1675   /**
1676    * This block and all of its children have been downloaded
1677    * successfully (full completion propagates up).
1678    */
1679   BRS_DOWNLOAD_UP = 6,
1680
1681   /**
1682    * We got a block back that matched the query but did not hash to
1683    * the key (malicious publisher or hash collision); this block
1684    * can never be downloaded (error propagates up).
1685    */
1686   BRS_ERROR = 7
1687 };
1688
1689
1690 /**
1691  * Information about an active download request.
1692  */
1693 struct DownloadRequest
1694 {
1695
1696   /**
1697    * Parent in the CHK-tree.
1698    */
1699   struct DownloadRequest *parent;
1700
1701   /**
1702    * Array (!) of child-requests, or NULL for the bottom of the tree.
1703    */
1704   struct DownloadRequest **children;
1705
1706   /**
1707    * CHK for the request for this block (set during reconstruction
1708    * to what we have on disk, later to what we want to have).
1709    */
1710   struct ContentHashKey chk;
1711
1712   /**
1713    * Offset of the corresponding block.  Specifically, first (!) byte of
1714    * the first DBLOCK in the subtree induced by block represented by
1715    * this request.
1716    */
1717   uint64_t offset;
1718
1719   /**
1720    * Number of entries in @e children array.
1721    */
1722   unsigned int num_children;
1723
1724   /**
1725    * Depth of the corresponding block in the tree.  0==DBLOCKs.
1726    */
1727   unsigned int depth;
1728
1729   /**
1730    * Offset of the CHK for this block in the parent block
1731    */
1732   unsigned int chk_idx;
1733
1734   /**
1735    * State in the FSM.
1736    */
1737   enum BlockRequestState state;
1738
1739 };
1740
1741
1742 /**
1743  * (recursively) free download request structure
1744  *
1745  * @param dr request to free
1746  */
1747 void
1748 GNUNET_FS_free_download_request_ (struct DownloadRequest *dr);
1749
1750
1751 /**
1752  * Stop the ping task for this search result.
1753  *
1754  * @param sr result to start pinging for.
1755  */
1756 void
1757 GNUNET_FS_stop_probe_ping_task_ (struct GNUNET_FS_SearchResult *sr);
1758
1759
1760 /**
1761  * Context for controlling a download.
1762  */
1763 struct GNUNET_FS_DownloadContext
1764 {
1765
1766   /**
1767    * Global FS context.
1768    */
1769   struct GNUNET_FS_Handle *h;
1770
1771   /**
1772    * Our top-level activity entry (if we are top-level, otherwise NULL).
1773    */
1774   struct TopLevelActivity *top;
1775
1776   /**
1777    * Connection to the FS service.
1778    */
1779   struct GNUNET_MQ_Handle *mq;
1780
1781   /**
1782    * Parent download (used when downloading files
1783    * in directories).
1784    */
1785   struct GNUNET_FS_DownloadContext *parent;
1786
1787   /**
1788    * Associated search (used when downloading files
1789    * based on search results), or NULL for none.
1790    */
1791   struct GNUNET_FS_SearchResult *search;
1792
1793   /**
1794    * Head of list of child downloads.
1795    */
1796   struct GNUNET_FS_DownloadContext *child_head;
1797
1798   /**
1799    * Tail of list of child downloads.
1800    */
1801   struct GNUNET_FS_DownloadContext *child_tail;
1802
1803   /**
1804    * Previous download belonging to the same parent.
1805    */
1806   struct GNUNET_FS_DownloadContext *prev;
1807
1808   /**
1809    * Next download belonging to the same parent.
1810    */
1811   struct GNUNET_FS_DownloadContext *next;
1812
1813   /**
1814    * Context kept for the client.
1815    */
1816   void *client_info;
1817
1818   /**
1819    * URI that identifies the file that we are downloading.
1820    */
1821   struct GNUNET_FS_Uri *uri;
1822
1823   /**
1824    * Known meta-data for the file (can be NULL).
1825    */
1826   struct GNUNET_CONTAINER_MetaData *meta;
1827
1828   /**
1829    * Error message, NULL if we're doing OK.
1830    */
1831   char *emsg;
1832
1833   /**
1834    * Random portion of filename we use for syncing state of this
1835    * download.
1836    */
1837   char *serialization;
1838
1839   /**
1840    * Where are we writing the data (name of the
1841    * file, can be NULL!).
1842    */
1843   char *filename;
1844
1845   /**
1846    * Where are we writing the data temporarily (name of the
1847    * file, can be NULL!); used if we do not have a permanent
1848    * name and we are a directory and we do a recursive download.
1849    */
1850   char *temp_filename;
1851
1852   /**
1853    * Our entry in the job queue.
1854    */
1855   struct GNUNET_FS_QueueEntry *job_queue;
1856
1857   /**
1858    * Tree encoder used for the reconstruction.
1859    */
1860   struct GNUNET_FS_TreeEncoder *te;
1861
1862   /**
1863    * File handle for reading data from an existing file
1864    * (to pass to tree encoder).
1865    */
1866   struct GNUNET_DISK_FileHandle *rfh;
1867
1868   /**
1869    * Map of active requests (those waiting for a response).  The key
1870    * is the hash of the encryped block (aka query).
1871    */
1872   struct GNUNET_CONTAINER_MultiHashMap *active;
1873
1874   /**
1875    * Top-level download request.
1876    */
1877   struct DownloadRequest *top_request;
1878
1879   /**
1880    * Identity of the peer having the content, or all-zeros
1881    * if we don't know of such a peer.
1882    */
1883   struct GNUNET_PeerIdentity target;
1884
1885   /**
1886    * ID of a task that is using this struct and that must be cancelled
1887    * when the download is being stopped (if not
1888    * NULL).  Used for the task that adds some
1889    * artificial delay when trying to reconnect to the FS service or
1890    * the task processing incrementally the data on disk, or the
1891    * task requesting blocks, etc.
1892    */
1893   struct GNUNET_SCHEDULER_Task *task;
1894
1895   /**
1896    * What is the first offset that we're interested
1897    * in?
1898    */
1899   uint64_t offset;
1900
1901   /**
1902    * How many bytes starting from offset are desired?
1903    * This is NOT the overall length of the file!
1904    */
1905   uint64_t length;
1906
1907   /**
1908    * How many bytes have we already received within
1909    * the specified range (DBlocks only).
1910    */
1911   uint64_t completed;
1912
1913   /**
1914    * What was the size of the file on disk that we're downloading
1915    * before we started?  Used to detect if there is a point in
1916    * checking an existing block on disk for matching the desired
1917    * content.  0 if the file did not exist already.
1918    */
1919   uint64_t old_file_size;
1920
1921   /**
1922    * Time download was started.
1923    */
1924   struct GNUNET_TIME_Absolute start_time;
1925
1926   /**
1927    * How long to wait before we try to reconnect to FS service?
1928    */
1929   struct GNUNET_TIME_Relative reconnect_backoff;
1930
1931   /**
1932    * Desired level of anonymity.
1933    */
1934   uint32_t anonymity;
1935
1936   /**
1937    * The depth of the file-tree.
1938    */
1939   unsigned int treedepth;
1940
1941   /**
1942    * Options for the download.
1943    */
1944   enum GNUNET_FS_DownloadOptions options;
1945
1946   /**
1947    * Flag set upon transitive completion (includes child downloads).
1948    * This flag is only set to #GNUNET_YES for directories where all
1949    * child-downloads have also completed (and signalled completion).
1950    */
1951   int has_finished;
1952
1953   /**
1954    * Are we ready to issue requests (reconstructions are finished)?
1955    */
1956   int issue_requests;
1957
1958 };
1959
1960
1961 #endif
1962
1963 /* end of fs_api.h */