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