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