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