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