src/fs/fs_api.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 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., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, 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  * The job is now ready to run and should use the given client
 414  * handle to communicate with the FS service.
 415  *
 416  * @param cls closure
 417  * @param client handle to use for FS communication
 418  */
 419 typedef void (*GNUNET_FS_QueueStart) (void *cls,
 420                                       struct GNUNET_CLIENT_Connection * client);
 421
 422
 423 /**
 424  * The job must now stop to run and should destry the client handle as
 425  * soon as possible (ideally prior to returning).
 426  */
 427 typedef void (*GNUNET_FS_QueueStop) (void *cls);
 428
 429
 430
 431 /**
 432  * Priorities for the queue.
 433  */
 434 enum GNUNET_FS_QueuePriority
 435 {
 436   /**
 437    * This is a probe (low priority).
 438    */
 439   GNUNET_FS_QUEUE_PRIORITY_PROBE,
 440
 441   /**
 442    * Default priority.
 443    */
 444   GNUNET_FS_QUEUE_PRIORITY_NORMAL
 445 };
 446
 447
 448 /**
 449  * Entry in the job queue.
 450  */
 451 struct GNUNET_FS_QueueEntry
 452 {
 453   /**
 454    * This is a linked list.
 455    */
 456   struct GNUNET_FS_QueueEntry *next;
 457
 458   /**
 459    * This is a linked list.
 460    */
 461   struct GNUNET_FS_QueueEntry *prev;
 462
 463   /**
 464    * Function to call when the job is started.
 465    */
 466   GNUNET_FS_QueueStart start;
 467
 468   /**
 469    * Function to call when the job needs to stop (or is done / dequeued).
 470    */
 471   GNUNET_FS_QueueStop stop;
 472
 473   /**
 474    * Closure for start and stop.
 475    */
 476   void *cls;
 477
 478   /**
 479    * Handle to FS primary context.
 480    */
 481   struct GNUNET_FS_Handle *h;
 482
 483   /**
 484    * Client handle, or NULL if job is not running.
 485    */
 486   struct GNUNET_CLIENT_Connection *client;
 487
 488   /**
 489    * Time the job was originally queued.
 490    */
 491   struct GNUNET_TIME_Absolute queue_time;
 492
 493   /**
 494    * Time the job was started last.
 495    */
 496   struct GNUNET_TIME_Absolute start_time;
 497
 498   /**
 499    * Total amount of time the job has been running (except for the
 500    * current run).
 501    */
 502   struct GNUNET_TIME_Relative run_time;
 503
 504   /**
 505    * How many blocks do the active downloads have?
 506    */
 507   unsigned int blocks;
 508
 509   /**
 510    * How important is this download?
 511    */
 512   enum GNUNET_FS_QueuePriority priority;
 513
 514   /**
 515    * How often have we (re)started this download?
 516    */
 517   unsigned int start_times;
 518
 519 };
 520
 521
 522 /**
 523  * Information we store for each search result.
 524  */
 525 struct GNUNET_FS_SearchResult
 526 {
 527
 528   /**
 529    * File-sharing context this result belongs to.
 530    */
 531   struct GNUNET_FS_Handle *h;
 532
 533   /**
 534    * Search context this result belongs to; can be NULL
 535    * for probes that come from a directory result.
 536    */
 537   struct GNUNET_FS_SearchContext *sc;
 538
 539   /**
 540    * URI to which this search result refers to.
 541    */
 542   struct GNUNET_FS_Uri *uri;
 543
 544   /**
 545    * Metadata for the search result.
 546    */
 547   struct GNUNET_CONTAINER_MetaData *meta;
 548
 549   /**
 550    * Client info for this search result.
 551    */
 552   void *client_info;
 553
 554   /**
 555    * ID of a job that is currently probing this results' availability
 556    * (NULL if we are not currently probing).
 557    */
 558   struct GNUNET_FS_DownloadContext *probe_ctx;
 559
 560   /**
 561    * ID of an associated download based on this search result (or
 562    * NULL for none).
 563    */
 564   struct GNUNET_FS_DownloadContext *download;
 565
 566   /**
 567    * If this search result triggered an update search, this field
 568    * links to the update search.
 569    */
 570   struct GNUNET_FS_SearchContext *update_search;
 571
 572   /**
 573    * Name under which this search result is stored on disk.
 574    */
 575   char *serialization;
 576
 577   /**
 578    * Bitmap that specifies precisely which keywords have been matched already.
 579    */
 580   uint8_t *keyword_bitmap;
 581
 582   /**
 583    * Key for the search result based on the URI.
 584    */
 585   struct GNUNET_HashCode key;
 586
 587   /**
 588    * ID of the task that will clean up the probe_ctx should it not
 589    * complete on time (and that will need to be cancelled if we clean
 590    * up the search result before then).
 591    */
 592   GNUNET_SCHEDULER_TaskIdentifier probe_cancel_task;
 593
 594   /**
 595    * Task we use to report periodically to the application that the
 596    * probe is still running.
 597    */
 598   GNUNET_SCHEDULER_TaskIdentifier probe_ping_task;
 599
 600   /**
 601    * When did the current probe become active?
 602    */
 603   struct GNUNET_TIME_Absolute probe_active_time;
 604
 605   /**
 606    * How much longer should we run the current probe before giving up?
 607    */
 608   struct GNUNET_TIME_Relative remaining_probe_time;
 609
 610   /**
 611    * Anonymity level to use for probes using this search result.
 612    */
 613   uint32_t anonymity;
 614
 615   /**
 616    * Number of mandatory keywords for which we have NOT yet found the
 617    * search result; when this value hits zero, the search result is
 618    * given to the callback.
 619    */
 620   uint32_t mandatory_missing;
 621
 622   /**
 623    * Number of optional keywords under which this result was also
 624    * found.
 625    */
 626   uint32_t optional_support;
 627
 628   /**
 629    * Number of availability tests that have succeeded for this result.
 630    */
 631   uint32_t availability_success;
 632
 633   /**
 634    * Number of availability trials that we have performed for this
 635    * search result.
 636    */
 637   uint32_t availability_trials;
 638
 639 };
 640
 641
 642 /**
 643  * Add a job to the queue.
 644  *
 645  * @param h handle to the overall FS state
 646  * @param start function to call to begin the job
 647  * @param stop function to call to pause the job, or on dequeue (if the job was running)
 648  * @param cls closure for start and stop
 649  * @param blocks number of blocks this download has
 650  * @param priority how important is this download
 651  * @return queue handle
 652  */
 653 struct GNUNET_FS_QueueEntry *
 654 GNUNET_FS_queue_ (struct GNUNET_FS_Handle *h, GNUNET_FS_QueueStart start,
 655                   GNUNET_FS_QueueStop stop, void *cls, unsigned int blocks,
 656                   enum GNUNET_FS_QueuePriority priority);
 657
 658
 659 /**
 660  * Dequeue a job from the queue.
 661  *
 662  * @param qe handle for the job
 663  */
 664 void
 665 GNUNET_FS_dequeue_ (struct GNUNET_FS_QueueEntry *qe);
 666
 667
 668 /**
 669  * Function that provides data by reading from a file.
 670  *
 671  * @param cls closure (points to the file information)
 672  * @param offset offset to read from; it is possible
 673  *            that the caller might need to go backwards
 674  *            a bit at times
 675  * @param max maximum number of bytes that should be
 676  *            copied to buf; readers are not allowed
 677  *            to provide less data unless there is an error;
 678  *            a value of "0" will be used at the end to allow
 679  *            the reader to clean up its internal state
 680  * @param buf where the reader should write the data
 681  * @param emsg location for the reader to store an error message
 682  * @return number of bytes written, usually "max", 0 on error
 683  */
 684 size_t
 685 GNUNET_FS_data_reader_file_ (void *cls, uint64_t offset, size_t max, void *buf,
 686                              char **emsg);
 687
 688
 689 /**
 690  * Create the closure for the 'GNUNET_FS_data_reader_file_' callback.
 691  *
 692  * @param filename file to read
 693  * @return closure to use
 694  */
 695 void *
 696 GNUNET_FS_make_file_reader_context_ (const char *filename);
 697
 698
 699
 700 /**
 701  * Function that provides data by copying from a buffer.
 702  *
 703  * @param cls closure (points to the buffer)
 704  * @param offset offset to read from; it is possible
 705  *            that the caller might need to go backwards
 706  *            a bit at times
 707  * @param max maximum number of bytes that should be
 708  *            copied to buf; readers are not allowed
 709  *            to provide less data unless there is an error;
 710  *            a value of "0" will be used at the end to allow
 711  *            the reader to clean up its internal state
 712  * @param buf where the reader should write the data
 713  * @param emsg location for the reader to store an error message
 714  * @return number of bytes written, usually "max", 0 on error
 715  */
 716 size_t
 717 GNUNET_FS_data_reader_copy_ (void *cls, uint64_t offset, size_t max, void *buf,
 718                              char **emsg);
 719
 720
 721 /**
 722  * Notification of FS that a search probe has made progress.
 723  * This function is used INSTEAD of the client's event handler
 724  * for downloads where the GNUNET_FS_DOWNLOAD_IS_PROBE flag is set.
 725  *
 726  * @param cls closure, always NULL (!), actual closure
 727  *        is in the client-context of the info struct
 728  * @param info details about the event, specifying the event type
 729  *        and various bits about the event
 730  * @return client-context (for the next progress call
 731  *         for this operation; should be set to NULL for
 732  *         SUSPEND and STOPPED events).  The value returned
 733  *         will be passed to future callbacks in the respective
 734  *         field in the GNUNET_FS_ProgressInfo struct.
 735  */
 736 void *
 737 GNUNET_FS_search_probe_progress_ (void *cls,
 738                                   const struct GNUNET_FS_ProgressInfo *info);
 739
 740
 741 /**
 742  * Main function that performs the upload.
 743  *
 744  * @param cls `struct GNUNET_FS_PublishContext` identifies the upload
 745  * @param tc task context
 746  */
 747 void
 748 GNUNET_FS_publish_main_ (void *cls,
 749                          const struct GNUNET_SCHEDULER_TaskContext *tc);
 750
 751
 752 /**
 753  * Function called once the hash of the file
 754  * that is being unindexed has been computed.
 755  *
 756  * @param cls closure, unindex context
 757  * @param file_id computed hash, NULL on error
 758  */
 759 void
 760 GNUNET_FS_unindex_process_hash_ (void *cls, const struct GNUNET_HashCode * file_id);
 761
 762
 763 /**
 764  * Extract the keywords for KBlock removal
 765  *
 766  * @param uc context for the unindex operation.
 767  */
 768 void
 769 GNUNET_FS_unindex_do_extract_keywords_ (struct GNUNET_FS_UnindexContext *uc);
 770
 771
 772 /**
 773  * If necessary, connect to the datastore and remove the KBlocks.
 774  *
 775  * @param uc context for the unindex operation.
 776  */
 777 void
 778 GNUNET_FS_unindex_do_remove_kblocks_ (struct GNUNET_FS_UnindexContext *uc);
 779
 780
 781 /**
 782  * Fill in all of the generic fields for a publish event and call the
 783  * callback.
 784  *
 785  * @param pi structure to fill in
 786  * @param pc overall publishing context
 787  * @param p file information for the file being published
 788  * @param offset where in the file are we so far
 789  * @return value returned from callback
 790  */
 791 void *
 792 GNUNET_FS_publish_make_status_ (struct GNUNET_FS_ProgressInfo *pi,
 793                                 struct GNUNET_FS_PublishContext *pc,
 794                                 const struct GNUNET_FS_FileInformation *p,
 795                                 uint64_t offset);
 796
 797
 798 /**
 799  * Fill in all of the generic fields for a download event and call the
 800  * callback.
 801  *
 802  * @param pi structure to fill in
 803  * @param dc overall download context
 804  */
 805 void
 806 GNUNET_FS_download_make_status_ (struct GNUNET_FS_ProgressInfo *pi,
 807                                  struct GNUNET_FS_DownloadContext *dc);
 808
 809
 810 /**
 811  * Task that creates the initial (top-level) download
 812  * request for the file.
 813  *
 814  * @param cls the 'struct GNUNET_FS_DownloadContext'
 815  * @param tc scheduler context
 816  */
 817 void
 818 GNUNET_FS_download_start_task_ (void *cls,
 819                                 const struct GNUNET_SCHEDULER_TaskContext *tc);
 820
 821
 822
 823 /**
 824  * Fill in all of the generic fields for
 825  * an unindex event and call the callback.
 826  *
 827  * @param pi structure to fill in
 828  * @param uc overall unindex context
 829  * @param offset where we are in the file (for progress)
 830  */
 831 void
 832 GNUNET_FS_unindex_make_status_ (struct GNUNET_FS_ProgressInfo *pi,
 833                                 struct GNUNET_FS_UnindexContext *uc,
 834                                 uint64_t offset);
 835
 836 /**
 837  * Fill in all of the generic fields for a search event and
 838  * call the callback.
 839  *
 840  * @param pi structure to fill in
 841  * @param h file-sharing handle
 842  * @param sc overall search context
 843  * @return value returned by the callback
 844  */
 845 void *
 846 GNUNET_FS_search_make_status_ (struct GNUNET_FS_ProgressInfo *pi,
 847                                struct GNUNET_FS_Handle *h,
 848                                struct GNUNET_FS_SearchContext *sc);
 849
 850
 851 /**
 852  * Connect to the datastore and remove the blocks.
 853  *
 854  * @param uc context for the unindex operation.
 855  */
 856 void
 857 GNUNET_FS_unindex_do_remove_ (struct GNUNET_FS_UnindexContext *uc);
 858
 859 /**
 860  * Build the request and actually initiate the search using the
 861  * GNUnet FS service.
 862  *
 863  * @param sc search context
 864  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 865  */
 866 int
 867 GNUNET_FS_search_start_searching_ (struct GNUNET_FS_SearchContext *sc);
 868
 869 /**
 870  * Start the downloading process (by entering the queue).
 871  *
 872  * @param dc our download context
 873  */
 874 void
 875 GNUNET_FS_download_start_downloading_ (struct GNUNET_FS_DownloadContext *dc);
 876
 877
 878 /**
 879  * Start download probes for the given search result.
 880  *
 881  * @param sr the search result
 882  */
 883 void
 884 GNUNET_FS_search_start_probe_ (struct GNUNET_FS_SearchResult *sr);
 885
 886 /**
 887  * Remove serialization/deserialization file from disk.
 888  *
 889  * @param h master context
 890  * @param ext component of the path
 891  * @param ent entity identifier
 892  */
 893 void
 894 GNUNET_FS_remove_sync_file_ (struct GNUNET_FS_Handle *h, const char *ext,
 895                              const char *ent);
 896
 897
 898 /**
 899  * Remove serialization/deserialization directory from disk.
 900  *
 901  * @param h master context
 902  * @param ext component of the path
 903  * @param uni unique name of parent
 904  */
 905 void
 906 GNUNET_FS_remove_sync_dir_ (struct GNUNET_FS_Handle *h, const char *ext,
 907                             const char *uni);
 908
 909
 910 /**
 911  * Synchronize this file-information struct with its mirror
 912  * on disk.  Note that all internal FS-operations that change
 913  * file information data should already call "sync" internally,
 914  * so this function is likely not useful for clients.
 915  *
 916  * @param fi the struct to sync
 917  */
 918 void
 919 GNUNET_FS_file_information_sync_ (struct GNUNET_FS_FileInformation *f);
 920
 921
 922 /**
 923  * Synchronize this publishing struct with its mirror
 924  * on disk.  Note that all internal FS-operations that change
 925  * publishing structs should already call "sync" internally,
 926  * so this function is likely not useful for clients.
 927  *
 928  * @param pc the struct to sync
 929  */
 930 void
 931 GNUNET_FS_publish_sync_ (struct GNUNET_FS_PublishContext *pc);
 932
 933
 934 /**
 935  * Synchronize this unindex struct with its mirror
 936  * on disk.  Note that all internal FS-operations that change
 937  * publishing structs should already call "sync" internally,
 938  * so this function is likely not useful for clients.
 939  *
 940  * @param uc the struct to sync
 941  */
 942 void
 943 GNUNET_FS_unindex_sync_ (struct GNUNET_FS_UnindexContext *uc);
 944
 945
 946 /**
 947  * Synchronize this search struct with its mirror
 948  * on disk.  Note that all internal FS-operations that change
 949  * publishing structs should already call "sync" internally,
 950  * so this function is likely not useful for clients.
 951  *
 952  * @param sc the struct to sync
 953  */
 954 void
 955 GNUNET_FS_search_sync_ (struct GNUNET_FS_SearchContext *sc);
 956
 957
 958 /**
 959  * Synchronize this search result with its mirror
 960  * on disk.  Note that all internal FS-operations that change
 961  * publishing structs should already call "sync" internally,
 962  * so this function is likely not useful for clients.
 963  *
 964  * @param sr the struct to sync
 965  */
 966 void
 967 GNUNET_FS_search_result_sync_ (struct GNUNET_FS_SearchResult *sr);
 968
 969
 970 /**
 971  * Synchronize this download struct with its mirror
 972  * on disk.  Note that all internal FS-operations that change
 973  * publishing structs should already call "sync" internally,
 974  * so this function is likely not useful for clients.
 975  *
 976  * @param dc the struct to sync
 977  */
 978 void
 979 GNUNET_FS_download_sync_ (struct GNUNET_FS_DownloadContext *dc);
 980
 981
 982 /**
 983  * Create SUSPEND event for the given publish operation
 984  * and then clean up our state (without stop signal).
 985  *
 986  * @param cls the 'struct GNUNET_FS_PublishContext' to signal for
 987  */
 988 void
 989 GNUNET_FS_publish_signal_suspend_ (void *cls);
 990
 991
 992 /**
 993  * Create SUSPEND event for the given search operation
 994  * and then clean up our state (without stop signal).
 995  *
 996  * @param cls the 'struct GNUNET_FS_SearchContext' to signal for
 997  */
 998 void
 999 GNUNET_FS_search_signal_suspend_ (void *cls);
1000
1001
1002 /**
1003  * Create SUSPEND event for the given download operation
1004  * and then clean up our state (without stop signal).
1005  *
1006  * @param cls the 'struct GNUNET_FS_DownloadContext' to signal for
1007  */
1008 void
1009 GNUNET_FS_download_signal_suspend_ (void *cls);
1010
1011
1012 /**
1013  * Create SUSPEND event for the given unindex operation
1014  * and then clean up our state (without stop signal).
1015  *
1016  * @param cls the 'struct GNUNET_FS_UnindexContext' to signal for
1017  */
1018 void
1019 GNUNET_FS_unindex_signal_suspend_ (void *cls);
1020
1021
1022 /**
1023  * Function signature of the functions that can be called
1024  * to trigger suspend signals and clean-up for top-level
1025  * activities.
1026  *
1027  * @param cls closure
1028  */
1029 typedef void (*SuspendSignalFunction) (void *cls);
1030
1031 /**
1032  * We track all of the top-level activities of FS
1033  * so that we can signal 'suspend' on shutdown.
1034  */
1035 struct TopLevelActivity
1036 {
1037   /**
1038    * This is a doubly-linked list.
1039    */
1040   struct TopLevelActivity *next;
1041
1042   /**
1043    * This is a doubly-linked list.
1044    */
1045   struct TopLevelActivity *prev;
1046
1047   /**
1048    * Function to call for suspend-signalling and clean up.
1049    */
1050   SuspendSignalFunction ssf;
1051
1052   /**
1053    * Closure for 'ssf' (some struct GNUNET_FS_XXXHandle*)
1054    */
1055   void *ssf_cls;
1056 };
1057
1058
1059 /**
1060  * Create a top-level activity entry.
1061  *
1062  * @param h global fs handle
1063  * @param ssf suspend signal function to use
1064  * @param ssf_cls closure for @a ssf
1065  * @return fresh top-level activity handle
1066  */
1067 struct TopLevelActivity *
1068 GNUNET_FS_make_top (struct GNUNET_FS_Handle *h,
1069                     SuspendSignalFunction ssf,
1070                     void *ssf_cls);
1071
1072
1073 /**
1074  * Destroy a top-level activity entry.
1075  *
1076  * @param h global fs handle
1077  * @param top top level activity entry
1078  */
1079 void
1080 GNUNET_FS_end_top (struct GNUNET_FS_Handle *h,
1081                    struct TopLevelActivity *top);
1082
1083
1084
1085 /**
1086  * Master context for most FS operations.
1087  */
1088 struct GNUNET_FS_Handle
1089 {
1090   /**
1091    * Configuration to use.
1092    */
1093   const struct GNUNET_CONFIGURATION_Handle *cfg;
1094
1095   /**
1096    * Name of our client.
1097    */
1098   char *client_name;
1099
1100   /**
1101    * Function to call with updates on our progress.
1102    */
1103   GNUNET_FS_ProgressCallback upcb;
1104
1105   /**
1106    * Closure for upcb.
1107    */
1108   void *upcb_cls;
1109
1110   /**
1111    * Head of DLL of top-level activities.
1112    */
1113   struct TopLevelActivity *top_head;
1114
1115   /**
1116    * Tail of DLL of top-level activities.
1117    */
1118   struct TopLevelActivity *top_tail;
1119
1120   /**
1121    * Head of DLL of running jobs.
1122    */
1123   struct GNUNET_FS_QueueEntry *running_head;
1124
1125   /**
1126    * Tail of DLL of running jobs.
1127    */
1128   struct GNUNET_FS_QueueEntry *running_tail;
1129
1130   /**
1131    * Head of DLL of pending jobs.
1132    */
1133   struct GNUNET_FS_QueueEntry *pending_head;
1134
1135   /**
1136    * Tail of DLL of pending jobs.
1137    */
1138   struct GNUNET_FS_QueueEntry *pending_tail;
1139
1140   /**
1141    * Task that processes the jobs in the running and pending queues
1142    * (and moves jobs around as needed).
1143    */
1144   GNUNET_SCHEDULER_TaskIdentifier queue_job;
1145
1146   /**
1147    * Average time we take for a single request to be satisfied.
1148    * FIXME: not yet calcualted properly...
1149    */
1150   struct GNUNET_TIME_Relative avg_block_latency;
1151
1152   /**
1153    * How many actual downloads do we have running right now?
1154    */
1155   unsigned int active_downloads;
1156
1157   /**
1158    * How many blocks do the active downloads have?
1159    */
1160   unsigned int active_blocks;
1161
1162   /**
1163    * General flags.
1164    */
1165   enum GNUNET_FS_Flags flags;
1166
1167   /**
1168    * Maximum number of parallel downloads.
1169    */
1170   unsigned int max_parallel_downloads;
1171
1172   /**
1173    * Maximum number of parallel requests.
1174    */
1175   unsigned int max_parallel_requests;
1176
1177 };
1178
1179
1180 /**
1181  * Handle for controlling a publication process.
1182  */
1183 struct GNUNET_FS_PublishContext
1184 {
1185   /**
1186    * Handle to the global fs context.
1187    */
1188   struct GNUNET_FS_Handle *h;
1189
1190   /**
1191    * Our top-level activity entry (if we are top-level, otherwise NULL).
1192    */
1193   struct TopLevelActivity *top;
1194
1195   /**
1196    * File-structure that is being shared.
1197    */
1198   struct GNUNET_FS_FileInformation *fi;
1199
1200   /**
1201    * Namespace that we are publishing in, NULL if we have no namespace.
1202    */
1203   struct GNUNET_CRYPTO_EcdsaPrivateKey *ns;
1204
1205   /**
1206    * ID of the content in the namespace, NULL if we have no namespace.
1207    */
1208   char *nid;
1209
1210   /**
1211    * ID for future updates, NULL if we have no namespace or no updates.
1212    */
1213   char *nuid;
1214
1215   /**
1216    * Filename used for serializing information about this operation
1217    * (should be determined using 'mktemp').
1218    */
1219   char *serialization;
1220
1221   /**
1222    * Our own client handle for the FS service; only briefly used when
1223    * we start to index a file, otherwise NULL.
1224    */
1225   struct GNUNET_CLIENT_Connection *client;
1226
1227   /**
1228    * Current position in the file-tree for the upload.
1229    */
1230   struct GNUNET_FS_FileInformation *fi_pos;
1231
1232   /**
1233    * Non-null if we are currently hashing a file.
1234    */
1235   struct GNUNET_CRYPTO_FileHashContext *fhc;
1236
1237   /**
1238    * Connection to the datastore service.
1239    */
1240   struct GNUNET_DATASTORE_Handle *dsh;
1241
1242   /**
1243    * Queue entry for reservation/unreservation.
1244    */
1245   struct GNUNET_DATASTORE_QueueEntry *qre;
1246
1247   /**
1248    * Context for SKS publishing operation that is part of this publishing operation
1249    * (NULL if not active).
1250    */
1251   struct GNUNET_FS_PublishSksContext *sks_pc;
1252
1253   /**
1254    * Context for KSK publishing operation that is part of this publishing operation
1255    * (NULL if not active).
1256    */
1257   struct GNUNET_FS_PublishKskContext *ksk_pc;
1258
1259   /**
1260    * ID of the task performing the upload. NO_TASK if the upload has
1261    * completed.
1262    */
1263   GNUNET_SCHEDULER_TaskIdentifier upload_task;
1264
1265   /**
1266    * Storage space to reserve for the operation.
1267    */
1268   uint64_t reserve_space;
1269
1270   /**
1271    * Overall number of entries to reserve for the
1272    * publish operation.
1273    */
1274   uint32_t reserve_entries;
1275
1276   /**
1277    * Options for publishing.
1278    */
1279   enum GNUNET_FS_PublishOptions options;
1280
1281   /**
1282    * Space reservation ID with datastore service
1283    * for this upload.
1284    */
1285   int rid;
1286
1287   /**
1288    * Set to #GNUNET_YES if all processing has completed.
1289    */
1290   int all_done;
1291
1292   /**
1293    * Flag set to #GNUNET_YES if the next callback from
1294    * #GNUNET_FS_file_information_inspect should be skipped because it
1295    * is for the directory which was already processed with the parent.
1296    */
1297   int skip_next_fi_callback;
1298 };
1299
1300
1301 /**
1302  * Phases of unindex processing (state machine).
1303  */
1304 enum UnindexState
1305 {
1306   /**
1307    * We're currently hashing the file.
1308    */
1309   UNINDEX_STATE_HASHING = 0,
1310
1311   /**
1312    * We're telling the datastore to delete
1313    * the respective DBlocks and IBlocks.
1314    */
1315   UNINDEX_STATE_DS_REMOVE = 1,
1316
1317   /**
1318    * Find out which keywords apply.
1319    */
1320   UNINDEX_STATE_EXTRACT_KEYWORDS = 2,
1321
1322   /**
1323    * We're telling the datastore to remove KBlocks.
1324    */
1325   UNINDEX_STATE_DS_REMOVE_KBLOCKS = 3,
1326
1327   /**
1328    * We're notifying the FS service about
1329    * the unindexing.
1330    */
1331   UNINDEX_STATE_FS_NOTIFY = 4,
1332
1333   /**
1334    * We're done.
1335    */
1336   UNINDEX_STATE_COMPLETE = 5,
1337
1338   /**
1339    * We've encountered a fatal error.
1340    */
1341   UNINDEX_STATE_ERROR = 6
1342 };
1343
1344
1345 /**
1346  * Handle for controlling an unindexing operation.
1347  */
1348 struct GNUNET_FS_UnindexContext
1349 {
1350
1351   /**
1352    * The content hash key of the last block we processed, will in the
1353    * end be set to the CHK from the URI.  Used to remove the KBlocks.
1354    */
1355   struct ContentHashKey chk;
1356
1357   /**
1358    * Global FS context.
1359    */
1360   struct GNUNET_FS_Handle *h;
1361
1362   /**
1363    * Our top-level activity entry.
1364    */
1365   struct TopLevelActivity *top;
1366
1367   /**
1368    * Directory scanner to find keywords (KBlock removal).
1369    */
1370   struct GNUNET_FS_DirScanner *dscan;
1371
1372   /**
1373    * Keywords found (telling us which KBlocks to remove).
1374    */
1375   struct GNUNET_FS_Uri *ksk_uri;
1376
1377   /**
1378    * Current offset in KSK removal.
1379    */
1380   uint32_t ksk_offset;
1381
1382   /**
1383    * Name of the file that we are unindexing.
1384    */
1385   char *filename;
1386
1387   /**
1388    * Short name under which we are serializing the state of this operation.
1389    */
1390   char *serialization;
1391
1392   /**
1393    * Connection to the FS service, only valid during the
1394    * #UNINDEX_STATE_FS_NOTIFY phase.
1395    */
1396   struct GNUNET_CLIENT_Connection *client;
1397
1398   /**
1399    * Connection to the datastore service, only valid during the
1400    * UNINDEX_STATE_DS_NOTIFY phase.
1401    */
1402   struct GNUNET_DATASTORE_Handle *dsh;
1403
1404   /**
1405    * Pointer kept for the client.
1406    */
1407   void *client_info;
1408
1409   /**
1410    * Merkle-ish tree encoder context.
1411    */
1412   struct GNUNET_FS_TreeEncoder *tc;
1413
1414   /**
1415    * Handle used to read the file.
1416    */
1417   struct GNUNET_DISK_FileHandle *fh;
1418
1419   /**
1420    * Handle to datastore 'get_key' operation issued for
1421    * obtaining KBlocks.
1422    */
1423   struct GNUNET_DATASTORE_QueueEntry *dqe;
1424
1425   /**
1426    * Current key for decrypting UBLocks from 'get_key' operation.
1427    */
1428   struct GNUNET_HashCode ukey;
1429
1430   /**
1431    * Current query of 'get_key' operation.
1432    */
1433   struct GNUNET_HashCode uquery;
1434
1435   /**
1436    * First content UID, 0 for none.
1437    */
1438   uint64_t first_uid;
1439
1440   /**
1441    * Error message, NULL on success.
1442    */
1443   char *emsg;
1444
1445   /**
1446    * Context for hashing of the file.
1447    */
1448   struct GNUNET_CRYPTO_FileHashContext *fhc;
1449
1450   /**
1451    * Overall size of the file.
1452    */
1453   uint64_t file_size;
1454
1455   /**
1456    * Random offset given to #GNUNET_DATASTORE_get_key.
1457    */
1458   uint64_t roff;
1459
1460   /**
1461    * When did we start?
1462    */
1463   struct GNUNET_TIME_Absolute start_time;
1464
1465   /**
1466    * Hash of the file's contents (once computed).
1467    */
1468   struct GNUNET_HashCode file_id;
1469
1470   /**
1471    * Current operatinonal phase.
1472    */
1473   enum UnindexState state;
1474
1475 };
1476
1477
1478 /**
1479  * Information we keep for each keyword in a keyword search.
1480  */
1481 struct SearchRequestEntry
1482 {
1483
1484   /**
1485    * Hash of the public key, also known as the query.
1486    */
1487   struct GNUNET_HashCode uquery;
1488
1489   /**
1490    * Derived public key, hashes to 'uquery'.
1491    */
1492   struct GNUNET_CRYPTO_EcdsaPublicKey dpub;
1493
1494   /**
1495    * The original keyword, used to derive the
1496    * key (for decrypting the UBlock).
1497    */
1498   char *keyword;
1499
1500   /**
1501    * Map that contains a "struct GNUNET_FS_SearchResult" for each result that
1502    * was found under this keyword.  Note that the entries will point
1503    * to the same locations as those in the master result map (in
1504    * "struct GNUNET_FS_SearchContext"), so they should not be freed.
1505    * The key for each entry is the XOR of the key and query in the CHK
1506    * URI (as a unique identifier for the search result).
1507    */
1508   struct GNUNET_CONTAINER_MultiHashMap *results;
1509
1510   /**
1511    * Is this keyword a mandatory keyword
1512    * (started with '+')?
1513    */
1514   int mandatory;
1515
1516 };
1517
1518
1519 /**
1520  * Handle for controlling a search.
1521  */
1522 struct GNUNET_FS_SearchContext
1523 {
1524   /**
1525    * Handle to the global FS context.
1526    */
1527   struct GNUNET_FS_Handle *h;
1528
1529   /**
1530    * Our top-level activity entry (if we are top-level, otherwise NULL).
1531    */
1532   struct TopLevelActivity *top;
1533
1534   /**
1535    * List of keywords that we're looking for.
1536    */
1537   struct GNUNET_FS_Uri *uri;
1538
1539   /**
1540    * For update-searches, link to the search result that triggered
1541    * the update search; otherwise NULL.
1542    */
1543   struct GNUNET_FS_SearchResult *psearch_result;
1544
1545   /**
1546    * Connection to the FS service.
1547    */
1548   struct GNUNET_CLIENT_Connection *client;
1549
1550   /**
1551    * Pointer we keep for the client.
1552    */
1553   void *client_info;
1554
1555   /**
1556    * Name of the file on disk we use for persistence.
1557    */
1558   char *serialization;
1559
1560   /**
1561    * Error message (non-NULL if this operation failed).
1562    */
1563   char *emsg;
1564
1565   /**
1566    * Map that contains a "struct GNUNET_FS_SearchResult" for each result that
1567    * was found in the search.  The key for each entry is the XOR of
1568    * the key and query in the CHK URI (as a unique identifier for the
1569    * search result).
1570    */
1571   struct GNUNET_CONTAINER_MultiHashMap *master_result_map;
1572
1573   /**
1574    * Per-keyword information for a keyword search.  This array will
1575    * have exactly as many entries as there were keywords.
1576    */
1577   struct SearchRequestEntry *requests;
1578
1579   /**
1580    * When did we start?
1581    */
1582   struct GNUNET_TIME_Absolute start_time;
1583
1584   /**
1585    * How long to wait before we try to reconnect to FS service?
1586    */
1587   struct GNUNET_TIME_Relative reconnect_backoff;
1588
1589   /**
1590    * ID of a task that is using this struct and that must be cancelled
1591    * when the search is being stopped (if not
1592    * #GNUNET_SCHEDULER_NO_TASK).  Used for the task that adds some
1593    * artificial delay when trying to reconnect to the FS service.
1594    */
1595   GNUNET_SCHEDULER_TaskIdentifier task;
1596
1597   /**
1598    * How many of the entries in the search request
1599    * map have been passed to the service so far?
1600    */
1601   unsigned int search_request_map_offset;
1602
1603   /**
1604    * How many of the keywords in the KSK
1605    * map have been passed to the service so far?
1606    */
1607   unsigned int keyword_offset;
1608
1609   /**
1610    * Anonymity level for the search.
1611    */
1612   uint32_t anonymity;
1613
1614   /**
1615    * Number of mandatory keywords in this query.
1616    */
1617   uint32_t mandatory_count;
1618
1619   /**
1620    * Options for the search.
1621    */
1622   enum GNUNET_FS_SearchOptions options;
1623 };
1624
1625
1626 /**
1627  * FSM for possible states a block can go through.  The typical
1628  * order of progression is linear through the states, alternatives
1629  * are documented in the comments.
1630  */
1631 enum BlockRequestState
1632 {
1633   /**
1634    * Initial state, block has only been allocated (since it is
1635    * relevant to the overall download request).
1636    */
1637   BRS_INIT = 0,
1638
1639   /**
1640    * We've checked the block on the path down the tree, and the
1641    * content on disk did match the desired CHK, but not all
1642    * the way down, so at the bottom some blocks will still
1643    * need to be reconstructed).
1644    */
1645   BRS_RECONSTRUCT_DOWN = 1,
1646
1647   /**
1648    * We've calculated the CHK bottom-up based on the meta data.
1649    * This may work, but if it did we have to write the meta data to
1650    * disk at the end (and we still need to check against the
1651    * CHK set on top).
1652    */
1653   BRS_RECONSTRUCT_META_UP = 2,
1654
1655   /**
1656    * We've calculated the CHK bottom-up based on what we have on
1657    * disk, which may not be what the desired CHK is.  If the
1658    * reconstructed CHKs match whatever comes from above, we're
1659    * done with the respective subtree.
1660    */
1661   BRS_RECONSTRUCT_UP = 3,
1662
1663   /**
1664    * We've determined the real, desired CHK for this block
1665    * (full tree reconstruction failed), request is now pending.
1666    * If the CHK that bubbled up through reconstruction did match
1667    * the top-level request, the state machine for the subtree
1668    * would have moved to BRS_DOWNLOAD_UP.
1669    */
1670   BRS_CHK_SET = 4,
1671
1672   /**
1673    * We've successfully downloaded this block, but the children
1674    * still need to be either downloaded or verified (download
1675    * request propagates down).  If the download fails, the
1676    * state machine for this block may move to
1677    * BRS_DOWNLOAD_ERROR instead.
1678    */
1679   BRS_DOWNLOAD_DOWN = 5,
1680
1681   /**
1682    * This block and all of its children have been downloaded
1683    * successfully (full completion propagates up).
1684    */
1685   BRS_DOWNLOAD_UP = 6,
1686
1687   /**
1688    * We got a block back that matched the query but did not hash to
1689    * the key (malicious publisher or hash collision); this block
1690    * can never be downloaded (error propagates up).
1691    */
1692   BRS_ERROR = 7
1693 };
1694
1695
1696 /**
1697  * Information about an active download request.
1698  */
1699 struct DownloadRequest
1700 {
1701   /**
1702    * While pending, we keep all download requests in a doubly-linked list.
1703    */
1704   struct DownloadRequest *next;
1705
1706   /**
1707    * While pending, we keep all download requests in a doubly-linked list.
1708    */
1709   struct DownloadRequest *prev;
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 '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    * #GNUNET_YES if this entry is in the pending list.
1756    */
1757   int is_pending;
1758
1759 };
1760
1761
1762 /**
1763  * (recursively) free download request structure
1764  *
1765  * @param dr request to free
1766  */
1767 void
1768 GNUNET_FS_free_download_request_ (struct DownloadRequest *dr);
1769
1770
1771 /**
1772  * Context for controlling a download.
1773  */
1774 struct GNUNET_FS_DownloadContext
1775 {
1776
1777   /**
1778    * Global FS context.
1779    */
1780   struct GNUNET_FS_Handle *h;
1781
1782   /**
1783    * Our top-level activity entry (if we are top-level, otherwise NULL).
1784    */
1785   struct TopLevelActivity *top;
1786
1787   /**
1788    * Connection to the FS service.
1789    */
1790   struct GNUNET_CLIENT_Connection *client;
1791
1792   /**
1793    * Parent download (used when downloading files
1794    * in directories).
1795    */
1796   struct GNUNET_FS_DownloadContext *parent;
1797
1798   /**
1799    * Associated search (used when downloading files
1800    * based on search results), or NULL for none.
1801    */
1802   struct GNUNET_FS_SearchResult *search;
1803
1804   /**
1805    * Head of list of child downloads.
1806    */
1807   struct GNUNET_FS_DownloadContext *child_head;
1808
1809   /**
1810    * Tail of list of child downloads.
1811    */
1812   struct GNUNET_FS_DownloadContext *child_tail;
1813
1814   /**
1815    * Previous download belonging to the same parent.
1816    */
1817   struct GNUNET_FS_DownloadContext *prev;
1818
1819   /**
1820    * Next download belonging to the same parent.
1821    */
1822   struct GNUNET_FS_DownloadContext *next;
1823
1824   /**
1825    * Context kept for the client.
1826    */
1827   void *client_info;
1828
1829   /**
1830    * URI that identifies the file that we are downloading.
1831    */
1832   struct GNUNET_FS_Uri *uri;
1833
1834   /**
1835    * Known meta-data for the file (can be NULL).
1836    */
1837   struct GNUNET_CONTAINER_MetaData *meta;
1838
1839   /**
1840    * Error message, NULL if we're doing OK.
1841    */
1842   char *emsg;
1843
1844   /**
1845    * Random portion of filename we use for syncing state of this
1846    * download.
1847    */
1848   char *serialization;
1849
1850   /**
1851    * Where are we writing the data (name of the
1852    * file, can be NULL!).
1853    */
1854   char *filename;
1855
1856   /**
1857    * Where are we writing the data temporarily (name of the
1858    * file, can be NULL!); used if we do not have a permanent
1859    * name and we are a directory and we do a recursive download.
1860    */
1861   char *temp_filename;
1862
1863   /**
1864    * Our entry in the job queue.
1865    */
1866   struct GNUNET_FS_QueueEntry *job_queue;
1867
1868   /**
1869    * Non-NULL if we are currently having a request for
1870    * transmission pending with the client handle.
1871    */
1872   struct GNUNET_CLIENT_TransmitHandle *th;
1873
1874   /**
1875    * Tree encoder used for the reconstruction.
1876    */
1877   struct GNUNET_FS_TreeEncoder *te;
1878
1879   /**
1880    * File handle for reading data from an existing file
1881    * (to pass to tree encoder).
1882    */
1883   struct GNUNET_DISK_FileHandle *rfh;
1884
1885   /**
1886    * Map of active requests (those waiting for a response).  The key
1887    * is the hash of the encryped block (aka query).
1888    */
1889   struct GNUNET_CONTAINER_MultiHashMap *active;
1890
1891   /**
1892    * Head of linked list of pending requests.
1893    */
1894   struct DownloadRequest *pending_head;
1895
1896   /**
1897    * Head of linked list of pending requests.
1898    */
1899   struct DownloadRequest *pending_tail;
1900
1901   /**
1902    * Top-level download request.
1903    */
1904   struct DownloadRequest *top_request;
1905
1906   /**
1907    * Identity of the peer having the content, or all-zeros
1908    * if we don't know of such a peer.
1909    */
1910   struct GNUNET_PeerIdentity target;
1911
1912   /**
1913    * ID of a task that is using this struct and that must be cancelled
1914    * when the download is being stopped (if not
1915    * GNUNET_SCHEDULER_NO_TASK).  Used for the task that adds some
1916    * artificial delay when trying to reconnect to the FS service or
1917    * the task processing incrementally the data on disk, or the
1918    * task requesting blocks, etc.
1919    */
1920   GNUNET_SCHEDULER_TaskIdentifier task;
1921
1922   /**
1923    * What is the first offset that we're interested
1924    * in?
1925    */
1926   uint64_t offset;
1927
1928   /**
1929    * How many bytes starting from offset are desired?
1930    * This is NOT the overall length of the file!
1931    */
1932   uint64_t length;
1933
1934   /**
1935    * How many bytes have we already received within
1936    * the specified range (DBlocks only).
1937    */
1938   uint64_t completed;
1939
1940   /**
1941    * What was the size of the file on disk that we're downloading
1942    * before we started?  Used to detect if there is a point in
1943    * checking an existing block on disk for matching the desired
1944    * content.  0 if the file did not exist already.
1945    */
1946   uint64_t old_file_size;
1947
1948   /**
1949    * Time download was started.
1950    */
1951   struct GNUNET_TIME_Absolute start_time;
1952
1953   /**
1954    * How long to wait before we try to reconnect to FS service?
1955    */
1956   struct GNUNET_TIME_Relative reconnect_backoff;
1957
1958   /**
1959    * Desired level of anonymity.
1960    */
1961   uint32_t anonymity;
1962
1963   /**
1964    * The depth of the file-tree.
1965    */
1966   unsigned int treedepth;
1967
1968   /**
1969    * Options for the download.
1970    */
1971   enum GNUNET_FS_DownloadOptions options;
1972
1973   /**
1974    * Flag set upon transitive completion (includes child downloads).
1975    * This flag is only set to #GNUNET_YES for directories where all
1976    * child-downloads have also completed (and signalled completion).
1977    */
1978   int has_finished;
1979
1980   /**
1981    * Have we started the receive continuation yet?
1982    */
1983   int in_receive;
1984
1985   /**
1986    * Are we ready to issue requests (reconstructions are finished)?
1987    */
1988   int issue_requests;
1989
1990 };
1991
1992
1993 #endif
1994
1995 /* end of fs_api.h */