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_datastore_service.h"
  30 #include "gnunet_fs_service.h"
  31
  32 /**
  33  * Size of the individual blocks used for file-sharing.
  34  */
  35 #define GNUNET_FS_DBLOCK_SIZE (32*1024)
  36
  37
  38 /**
  39  * Pick a multiple of 2 here to achive 8-byte alignment!
  40  * We also probably want DBlocks to have (roughly) the
  41  * same size as IBlocks.  With SHA-512, the optimal
  42  * value is 32768 byte / 128 byte = 256
  43  * (128 byte = 2 * 512 bits).  DO NOT CHANGE!
  44  */
  45 #define GNUNET_FS_CHK_PER_INODE 256
  46
  47
  48 /**
  49  * Maximum size for a file to be considered for
  50  * inlining in a directory.
  51  */
  52 #define GNUNET_FS_MAX_INLINE_SIZE 65536
  53
  54
  55
  56 /**
  57  * @brief content hash key
  58  */
  59 struct ContentHashKey
  60 {
  61   GNUNET_HashCode key;
  62   GNUNET_HashCode query;
  63 };
  64
  65
  66 /**
  67  * @brief complete information needed
  68  * to download a file.
  69  */
  70 struct FileIdentifier
  71 {
  72
  73   /**
  74    * Total size of the file in bytes. (network byte order (!))
  75    */
  76   uint64_t file_length;
  77
  78   /**
  79    * Query and key of the top GNUNET_EC_IBlock.
  80    */
  81   struct ContentHashKey chk;
  82
  83 };
  84
  85
  86 /**
  87  * Information about a file and its location
  88  * (peer claiming to share the file).
  89  */
  90 struct Location
  91 {
  92   /**
  93    * Information about the shared file.
  94    */
  95   struct FileIdentifier fi;
  96
  97   /**
  98    * Identity of the peer sharing the file.
  99    */
 100   struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded peer;
 101
 102   /**
 103    * Time when this location URI expires.
 104    */
 105   struct GNUNET_TIME_Absolute expirationTime;
 106
 107   /**
 108    * RSA signature over the GNUNET_EC_FileIdentifier,
 109    * GNUNET_hash of the peer and expiration time.
 110    */
 111   struct GNUNET_CRYPTO_RsaSignature contentSignature;
 112
 113 };
 114
 115 enum uri_types
 116 { chk, sks, ksk, loc };
 117
 118 /**
 119  * A Universal Resource Identifier (URI), opaque.
 120  */
 121 struct GNUNET_FS_Uri
 122 {
 123   enum uri_types type;
 124   union
 125   {
 126     struct
 127     {
 128       /**
 129        * Keywords start with a '+' if they are
 130        * mandatory (in which case the '+' is NOT
 131        * part of the keyword) and with a
 132        * simple space if they are optional
 133        * (in which case the space is ALSO not
 134        * part of the actual keyword).
 135        *
 136        * Double-quotes to protect spaces and
 137        * %-encoding are NOT used internally
 138        * (only in URI-strings).
 139        */
 140       char **keywords;
 141
 142       /**
 143        * Size of the keywords array.
 144        */
 145       unsigned int keywordCount;
 146     } ksk;
 147
 148     struct
 149     {
 150       /**
 151        * Hash of the public key for the namespace.
 152        */
 153       GNUNET_HashCode namespace;
 154
 155       /**
 156        * Human-readable identifier chosen for this
 157        * entry in the namespace.
 158        */
 159       char *identifier;
 160     } sks;
 161
 162     /**
 163      * Information needed to retrieve a file (content-hash-key
 164      * plus file size).
 165      */
 166     struct FileIdentifier chk;
 167
 168     /**
 169      * Information needed to retrieve a file including signed
 170      * location (identity of a peer) of the content.
 171      */
 172     struct Location loc;
 173   } data;
 174
 175 };
 176
 177
 178 /**
 179  * Information for a file or directory that is
 180  * about to be published.
 181  */
 182 struct GNUNET_FS_FileInformation
 183 {
 184
 185   /**
 186    * Files in a directory are kept as a linked list.
 187    */
 188   struct GNUNET_FS_FileInformation *next;
 189
 190   /**
 191    * If this is a file in a directory, "dir" refers to
 192    * the directory; otherwise NULL.
 193    */
 194   struct GNUNET_FS_FileInformation *dir;
 195
 196   /**
 197    * Pointer kept for the client.
 198    */
 199   void *client_info;
 200
 201   /**
 202    * Metadata to use for the file.
 203    */
 204   struct GNUNET_CONTAINER_MetaData *meta;
 205
 206   /**
 207    * Keywords to use for KBlocks.
 208    */
 209   struct GNUNET_FS_Uri *keywords;
 210
 211   /**
 212    * CHK for this file or directory. NULL if
 213    * we have not yet computed it.
 214    */
 215   struct GNUNET_FS_Uri *chk_uri;
 216
 217   /**
 218    * At what time should the content expire?
 219    */
 220   struct GNUNET_TIME_Absolute expirationTime;
 221
 222   /**
 223    * At what time did we start this upload?
 224    */
 225   struct GNUNET_TIME_Absolute start_time;
 226
 227   /**
 228    * Under what filename is this struct serialized
 229    * (for operational persistence).
 230    */
 231   char *serialization;
 232
 233   /**
 234    * In-memory cache of the current CHK tree.
 235    * This struct will contain the CHK values
 236    * from the root to the currently processed
 237    * node in the tree as identified by
 238    * "current_depth" and "publish_offset".
 239    * The "chktree" will be initially NULL,
 240    * then allocated to a sufficient number of
 241    * entries for the size of the file and
 242    * finally freed once the upload is complete.
 243    */
 244   struct ContentHashKey *chk_tree;
 245
 246   /**
 247    * Error message (non-NULL if this operation
 248    * failed).
 249    */
 250   char *emsg;
 251
 252   /**
 253    * Number of entries in "chk_tree".
 254    */
 255   unsigned int chk_tree_depth;
 256
 257   /**
 258    * Depth in the CHK-tree at which we are
 259    * currently publishing.  0 is the root
 260    * of the tree.
 261    */
 262   unsigned int current_depth;
 263
 264   /**
 265    * How many bytes of this file or directory have been
 266    * published so far?
 267    */
 268   uint64_t publish_offset;
 269
 270   /**
 271    * Data describing either the file or the directory.
 272    */
 273   union
 274   {
 275
 276     /**
 277      * Data for a file.
 278      */
 279     struct {
 280
 281       /**
 282        * Function that can be used to read the data for the file.
 283        */
 284       GNUNET_FS_DataReader reader;
 285
 286       /**
 287        * Closure for reader.
 288        */
 289       void *reader_cls;
 290
 291       /**
 292        * Size of the file (in bytes).
 293        */
 294       uint64_t file_size;
 295
 296       /**
 297        * Should the file be indexed or inserted?
 298        */
 299       int do_index;
 300
 301     } file;
 302
 303     /**
 304      * Data for a directory.
 305      */
 306     struct {
 307
 308       /**
 309        * Name of the directory.
 310        */
 311       char *dirname;
 312
 313       /**
 314        * Linked list of entries in the directory.
 315        */
 316       struct GNUNET_FS_FileInformation *entries;
 317
 318       /**
 319        * Size of the directory itself (in bytes); 0 if the
 320        * size has not yet been calculated.
 321        */
 322       size_t dir_size;
 323
 324       /**
 325        * Pointer to the data for the directory (or NULL if not
 326        * available).
 327        */
 328       void *dir_data;
 329
 330     } dir;
 331
 332   } data;
 333
 334   /**
 335    * Is this struct for a file or directory?
 336    */
 337   int is_directory;
 338
 339   /**
 340    * Desired anonymity level.
 341    */
 342   unsigned int anonymity;
 343
 344   /**
 345    * Desired priority (for keeping the content in the DB).
 346    */
 347   unsigned int priority;
 348
 349 };
 350
 351
 352 /**
 353  * Master context for most FS operations.
 354  */
 355 struct GNUNET_FS_Handle
 356 {
 357   /**
 358    * Scheduler.
 359    */
 360   struct GNUNET_SCHEDULER_Handle *sched;
 361
 362   /**
 363    * Configuration to use.
 364    */
 365   const struct GNUNET_CONFIGURATION_Handle *cfg;
 366
 367   /**
 368    * Name of our client.
 369    */
 370   char *client_name;
 371
 372   /**
 373    * Function to call with updates on our progress.
 374    */
 375   GNUNET_FS_ProgressCallback upcb;
 376
 377   /**
 378    * Closure for upcb.
 379    */
 380   void *upcb_cls;
 381
 382   /**
 383    * Connection to the FS service.
 384    */
 385   struct GNUNET_CLIENT_Connection *client;
 386
 387
 388 };
 389
 390
 391 /**
 392  * Handle for controlling an upload.
 393  */
 394 struct GNUNET_FS_PublishContext
 395 {
 396   /**
 397    * Handle to the global fs context.
 398    */
 399   struct GNUNET_FS_Handle *h;
 400
 401   /**
 402    * Argument to pass to the client in callbacks.
 403    */
 404   void *client_ctx;
 405
 406   /**
 407    * File-structure that is being shared.
 408    */
 409   struct GNUNET_FS_FileInformation *fi;
 410
 411   /**
 412    * Namespace that we are publishing in, NULL if we have no namespace.
 413    */
 414   struct GNUNET_FS_Namespace *namespace;
 415
 416   /**
 417    * ID of the content in the namespace, NULL if we have no namespace.
 418    */
 419   char *nid;
 420
 421   /**
 422    * ID for future updates, NULL if we have no namespace or no updates.
 423    */
 424   char *nuid;
 425
 426   /**
 427    * ID of the task performing the upload. NO_TASK
 428    * if the upload has completed.
 429    */
 430   GNUNET_SCHEDULER_TaskIdentifier upload_task;
 431
 432   /**
 433    * Typically GNUNET_NO.  Set to GNUNET_YES if
 434    * "upload_task" is GNUNET_SCHEDULER_NO_TASK
 435    * and we're waiting for a response from the
 436    * datastore service (in which case this
 437    * struct must not be freed until we have that
 438    * response).  If someone tries to stop the
 439    * download for good during this period,
 440    * "in_network_wait" is set to GNUNET_SYSERR
 441    * which will cause the struct to be destroyed
 442    * right after we have the reply (or timeout)
 443    * from the datastore service.
 444    */
 445   int in_network_wait;
 446
 447   /**
 448    * Options for publishing.
 449    */
 450   enum GNUNET_FS_PublishOptions options;
 451
 452   /**
 453    * Current position in the file-tree for the
 454    * upload.
 455    */
 456   struct GNUNET_FS_FileInformation *fi_pos;
 457
 458   /**
 459    * Connection to the datastore service.
 460    */
 461   struct GNUNET_DATASTORE_Handle *dsh;
 462
 463   /**
 464    * Space reservation ID with datastore service
 465    * for this upload.
 466    */
 467   int rid;
 468 };
 469
 470
 471 /**
 472  * Handle for controlling an unindexing operation.
 473  */
 474 struct GNUNET_FS_UnindexContext
 475 {
 476 };
 477
 478
 479 /**
 480  * Handle for controlling a search.
 481  */
 482 struct GNUNET_FS_SearchContext
 483 {
 484 };
 485
 486
 487 /**
 488  * Context for controlling a download.
 489  */
 490 struct GNUNET_FS_DownloadContext
 491 {
 492 };
 493
 494 struct GNUNET_FS_Namespace
 495 {
 496
 497   /**
 498    * Private key for the namespace.
 499    */
 500   struct GNUNET_CRYPTO_RsaPrivateKey *key;
 501
 502   /**
 503    * Reference counter.
 504    */
 505   unsigned int rc;
 506 };
 507
 508
 509 /**
 510  * @brief keyword block (advertising data under a keyword)
 511  */
 512 struct GNUNET_FS_KBlock
 513 {
 514
 515   /**
 516    * GNUNET_RSA_Signature using RSA-key generated from search keyword.
 517    */
 518   struct GNUNET_CRYPTO_RsaSignature signature;
 519
 520   /**
 521    * What is being signed and why?
 522    */
 523   struct GNUNET_CRYPTO_RsaSignaturePurpose purpose;
 524
 525   /**
 526    * Key generated (!) from the H(keyword) as the seed!
 527    */
 528   struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded keyspace;
 529
 530   /* 0-terminated URI here */
 531
 532   /* variable-size Meta-Data follows here */
 533
 534 };
 535
 536 /**
 537  * @brief namespace content block (advertising data under an identifier in a namespace)
 538  */
 539 struct GNUNET_FS_SBlock
 540 {
 541
 542   /**
 543    * GNUNET_RSA_Signature using RSA-key of the namespace
 544    */
 545   struct GNUNET_CRYPTO_RsaSignature signature;
 546
 547   /**
 548    * What is being signed and why?
 549    */
 550   struct GNUNET_CRYPTO_RsaSignaturePurpose purpose;
 551
 552   /**
 553    * Hash of the hash of the human-readable identifier used for
 554    * this entry (the hash of the human-readable identifier is
 555    * used as the key for decryption; the xor of this identifier
 556    * and the hash of the "keyspace" is the datastore-query hash).
 557    */
 558   GNUNET_HashCode identifier;
 559
 560   /**
 561    * Public key of the namespace.
 562    */
 563   struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded subspace;
 564
 565   /* 0-terminated update-identifier here */
 566
 567   /* 0-terminated URI here */
 568
 569   /* variable-size Meta-Data follows here */
 570
 571 };
 572
 573
 574
 575
 576 #endif
 577
 578 /* end of fs.h */