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