src/include/gnunet_fs_service.h

   1 /*
   2      This file is part of GNUnet
   3      (C) 2004--2013 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  * @file include/gnunet_fs_service.h
  22  * @brief API for file-sharing via GNUnet
  23  * @author Christian Grothoff
  24  */
  25 #ifndef GNUNET_FS_LIB_H
  26 #define GNUNET_FS_LIB_H
  27
  28 #include "gnunet_util_lib.h"
  29 #include "gnunet_scheduler_lib.h"
  30
  31 #ifdef __cplusplus
  32 extern "C"
  33 {
  34 #if 0                           /* keep Emacsens' auto-indent happy */
  35 }
  36 #endif
  37 #endif
  38
  39 /**
  40  * Version number of the implementation.
  41  * History:
  42  *
  43  * 1.x.x: initial version with triple GNUNET_hash and merkle tree
  44  * 2.x.x: root node with mime-type, filename and version number
  45  * 2.1.x: combined GNUNET_EC_ContentHashKey/3HASH encoding with 25:1 super-nodes
  46  * 2.2.x: with directories
  47  * 3.0.x: with namespaces
  48  * 3.1.x: with namespace meta-data
  49  * 3.2.x: with collections
  50  * 4.0.x: with expiration, variable meta-data, kblocks
  51  * 4.1.x: with new error and configuration handling
  52  * 5.0.x: with location URIs
  53  * 6.0.0: with support for OR in KSKs
  54  * 6.1.x: with simplified namespace support
  55  * 9.0.0: CPS-style integrated API
  56  * 9.1.1: asynchronous directory scanning
  57  * 9.2.0: unified K-Block and S-block format (#2564)
  58  */
  59 #define GNUNET_FS_VERSION 0x00090200
  60
  61
  62 /* ******************** URI API *********************** */
  63
  64 #define GNUNET_FS_URI_PREFIX "gnunet://fs/"
  65 #define GNUNET_FS_URI_KSK_INFIX "ksk/"
  66 #define GNUNET_FS_URI_SKS_INFIX "sks/"
  67 #define GNUNET_FS_URI_CHK_INFIX "chk/"
  68 #define GNUNET_FS_URI_LOC_INFIX "loc/"
  69
  70
  71 /**
  72  * How often do we signal applications that a probe for a particular
  73  * search result is running? (used to visualize probes).
  74  */
  75 #define GNUNET_FS_PROBE_UPDATE_FREQUENCY GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_MILLISECONDS, 250)
  76
  77 /**
  78  * A Universal Resource Identifier (URI), opaque.
  79  */
  80 struct GNUNET_FS_Uri;
  81
  82
  83 /**
  84  * Identifier for a GNUnet pseudonym (the public key).  Q-point, Q=dP.
  85  * Note that we (ab)use an identifier of 'Q=G=1P' to mean the
  86  * 'anonymous' pseudonym.
  87  */
  88 struct GNUNET_FS_PseudonymIdentifier
  89 {
  90   /**
  91    * Q consists of an x- and a y-value, each mod p (256 bits),
  92    * given here in affine coordinates.
  93    */
  94   unsigned char q_x[256 / 8];
  95
  96   /**
  97    * Q consists of an x- and a y-value, each mod p (256 bits),
  98    * given here in affine coordinates.
  99    */
 100   unsigned char q_y[256 / 8];
 101
 102 };
 103
 104
 105 /**
 106  * Handle for a pseudonym (private key).
 107  */
 108 struct GNUNET_FS_PseudonymHandle;
 109
 110
 111 /**
 112  * Signature made with a pseudonym (includes the full public key).
 113  * The ECDSA signature is a pair (r,s) with r = x1 mod n where
 114  * (x1,y1) = kG for "random" k and s = k^{-1}(z + rd) mod n,
 115  * where z is derived from the hash of the message that is being
 116  * signed.
 117  */
 118 struct GNUNET_FS_PseudonymSignature
 119 {
 120
 121   /**
 122    * Who created the signature? (public key of the signer), 'd' value in NIST P-256.
 123    */
 124   struct GNUNET_FS_PseudonymIdentifier signer;
 125
 126   /**
 127    * Binary ECDSA signature data, r-value.  Value is mod n, and n is 256 bits.
 128    */
 129   unsigned char sig_r[256 / 8];
 130
 131   /**
 132    * Binary ECDSA signature data, s-value.  Value is mod n, and n is 256 bits.
 133    */
 134   unsigned char sig_s[256 / 8];
 135 };
 136
 137
 138 /**
 139  * Purpose for signature made with a pseudonym.
 140  */
 141 struct GNUNET_FS_PseudonymSignaturePurpose
 142 {
 143   /**
 144    * How many bytes are being signed (including this header)?
 145    */
 146   uint32_t size;
 147
 148   /**
 149    * What is the context/purpose of the signature?
 150    */
 151   uint32_t purpose;
 152 };
 153
 154
 155 /**
 156  * Iterator over keywords
 157  *
 158  * @param cls closure
 159  * @param keyword the keyword
 160  * @param is_mandatory is the keyword mandatory (in a search)
 161  * @return GNUNET_OK to continue to iterate, GNUNET_SYSERR to abort
 162  */
 163 typedef int (*GNUNET_FS_KeywordIterator) (void *cls, const char *keyword,
 164                                           int is_mandatory);
 165
 166
 167
 168
 169 /**
 170  * Create a pseudonym.
 171  *
 172  * @param filename name of the file to use for storage, NULL for in-memory only
 173  * @return handle to the private key of the pseudonym
 174  */
 175 struct GNUNET_FS_PseudonymHandle *
 176 GNUNET_FS_pseudonym_create (const char *filename);
 177
 178
 179 /**
 180  * Create a pseudonym, from a file that must already exist.
 181  *
 182  * @param filename name of the file to use for storage, NULL for in-memory only
 183  * @return handle to the private key of the pseudonym
 184  */
 185 struct GNUNET_FS_PseudonymHandle *
 186 GNUNET_FS_pseudonym_create_from_existing_file (const char *filename);
 187
 188
 189 /**
 190  * Get the handle for the 'anonymous' pseudonym shared by all users.
 191  * That pseudonym uses a fixed 'secret' for the private key; this
 192  * construction is useful to make anonymous and pseudonymous APIs
 193  * (and packets) indistinguishable on the network.  See #2564.
 194  *
 195  * @return handle to the (non-secret) private key of the 'anonymous' pseudonym
 196  */
 197 struct GNUNET_FS_PseudonymHandle *
 198 GNUNET_FS_pseudonym_get_anonymous_pseudonym_handle (void);
 199
 200
 201 /**
 202  * Destroy a pseudonym handle.  Does NOT remove the private key from
 203  * the disk.
 204  *
 205  * @param ph pseudonym handle to destroy
 206  */
 207 void
 208 GNUNET_FS_pseudonym_destroy (struct GNUNET_FS_PseudonymHandle *ph);
 209
 210
 211 /**
 212  * Cryptographically sign some data with the pseudonym.
 213  *
 214  * @param ph private key used for signing (corresponds to 'x' in #2564)
 215  * @param purpose data to sign
 216  * @param seed hash of the plaintext of the data that we are signing,
 217  *             used for deterministic PRNG for anonymous signing;
 218  *             corresponds to 'k' in section 2.7 of #2564
 219  * @param signing_key modifier to apply to the private key for signing;
 220  *                    corresponds to 'h' in section 2.3 of #2564.
 221  * @param signature where to store the signature
 222  * @return GNUNET_SYSERR on failure
 223  */
 224 int
 225 GNUNET_FS_pseudonym_sign (struct GNUNET_FS_PseudonymHandle *ph,
 226                           const struct GNUNET_FS_PseudonymSignaturePurpose *purpose,
 227                           const struct GNUNET_HashCode *seed,
 228                           const struct GNUNET_HashCode *signing_key,
 229                           struct GNUNET_FS_PseudonymSignature *signature);
 230
 231
 232 /**
 233  * Given a pseudonym and a signing key, derive the corresponding public
 234  * key that would be used to verify the resulting signature.
 235  *
 236  * @param pseudonym the public key (g^x in DSA, dQ in ECDSA)
 237  * @param signing_key input to derive 'h' (see section 2.4 of #2564)
 238  * @param verification_key resulting public key to verify the signature
 239  *        created from the 'ph' of 'pseudonym' and the 'signing_key';
 240  *        the value stored here can then be given to GNUNET_FS_pseudonym_verify.
 241  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 242  */
 243 int
 244 GNUNET_FS_pseudonym_derive_verification_key (struct GNUNET_FS_PseudonymIdentifier *pseudonym,
 245                                              const struct GNUNET_HashCode *signing_key,
 246                                              struct GNUNET_FS_PseudonymIdentifier *verification_key);
 247
 248
 249 /**
 250  * Verify a signature made with a pseudonym.
 251  *
 252  * @param purpose data that was signed
 253  * @param signature signature to verify
 254  * @param verification_key public key to use for checking the signature;
 255  *                    corresponds to 'g^(x+h)' in section 2.4 of #2564.
 256  * @return GNUNET_OK on success (signature valid, 'pseudonym' set),
 257  *         GNUNET_SYSERR if the signature is invalid
 258  */
 259 int
 260 GNUNET_FS_pseudonym_verify (const struct GNUNET_FS_PseudonymSignaturePurpose *purpose,
 261                          const struct GNUNET_FS_PseudonymSignature *signature,
 262                          const struct GNUNET_FS_PseudonymIdentifier *verification_key);
 263
 264
 265 /**
 266  * Get the identifier (public key) of a pseudonym.
 267  *
 268  * @param ph pseudonym handle with the private key
 269  * @param pseudonym pseudonym identifier (set based on 'ph')
 270  */
 271 void
 272 GNUNET_FS_pseudonym_get_identifier (struct GNUNET_FS_PseudonymHandle *ph,
 273                                     struct GNUNET_FS_PseudonymIdentifier *pseudonym);
 274
 275
 276
 277 /**
 278  * Iterator over all known pseudonyms.
 279  *
 280  * @param cls closure
 281  * @param pseudonym hash code of public key of pseudonym
 282  * @param name name of the pseudonym (might be NULL)
 283  * @param unique_name unique name of the pseudonym (might be NULL)
 284  * @param md meta data known about the pseudonym
 285  * @param rating the local rating of the pseudonym
 286  * @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort
 287  */
 288 typedef int (*GNUNET_FS_PseudonymIterator) (void *cls,
 289                                             const struct GNUNET_FS_PseudonymIdentifier *pseudonym,
 290                                             const char *name,
 291                                             const char *unique_name,
 292                                             const struct GNUNET_CONTAINER_MetaData *md,
 293                                              int32_t rating);
 294
 295
 296 /**
 297  * Change the rank of a pseudonym.
 298  *
 299  * @param cfg overall configuration
 300  * @param pseudonym identity of the pseudonym
 301  * @param delta by how much should the rating be changed?
 302  * @return new rating of the pseudonym
 303  */
 304 int
 305 GNUNET_FS_pseudonym_rank (const struct GNUNET_CONFIGURATION_Handle *cfg,
 306                           const struct GNUNET_FS_PseudonymIdentifier *pseudonym,
 307                           int32_t delta);
 308
 309
 310 /**
 311  * Add a pseudonym to the set of known pseudonyms.
 312  * For all pseudonym advertisements that we discover
 313  * FS should automatically call this function.
 314  *
 315  * @param cfg overall configuration
 316  * @param pseudonym the pseudonym identifier
 317  * @param meta metadata for the pseudonym
 318  * @return GNUNET_OK on success, GNUNET_SYSERR on failure
 319  */
 320 int
 321 GNUNET_FS_pseudonym_add (const struct GNUNET_CONFIGURATION_Handle *cfg,
 322                          const struct GNUNET_FS_PseudonymIdentifier *pseudonym,
 323                          const struct GNUNET_CONTAINER_MetaData *meta);
 324
 325
 326 /**
 327  * List all known pseudonyms.
 328  *
 329  * @param cfg overall configuration
 330  * @param iterator function to call for each pseudonym
 331  * @param iterator_cls closure for iterator
 332  * @return number of pseudonyms found
 333  */
 334 int
 335 GNUNET_FS_pseudonym_list_all (const struct GNUNET_CONFIGURATION_Handle *cfg,
 336                               GNUNET_FS_PseudonymIterator iterator,
 337                               void *iterator_cls);
 338
 339
 340 /**
 341  * Handle for a discovery callback registration.
 342  */
 343 struct GNUNET_FS_pseudonym_DiscoveryHandle;
 344
 345
 346 /**
 347  * Register callback to be invoked whenever we discover
 348  * a new pseudonym.
 349  *
 350  * @param cfg our configuration
 351  * @param iterator function to invoke on discovery
 352  * @param iterator_cls closure for iterator
 353  * @return registration handle
 354  */
 355 struct GNUNET_FS_pseudonym_DiscoveryHandle *
 356 GNUNET_FS_pseudonym_discovery_callback_register (const struct GNUNET_CONFIGURATION_Handle *cfg,
 357                                                  GNUNET_FS_PseudonymIterator iterator,
 358                                                  void *iterator_cls);
 359
 360
 361 /**
 362  * Unregister pseudonym discovery callback.
 363  *
 364  * @param dh registration to unregister
 365  */
 366 void
 367 GNUNET_FS_pseudonym_discovery_callback_unregister (struct GNUNET_FS_pseudonym_DiscoveryHandle *dh);
 368
 369
 370 /**
 371  * Return unique variant of the pseudonym name.  Use after
 372  * GNUNET_FS_pseudonym_id_to_name() to make sure that name is unique.
 373  *
 374  * @param cfg configuration
 375  * @param pseudonym cryptographic ID of the pseudonym
 376  * @param name name to uniquify
 377  * @param suffix if not NULL, filled with the suffix value
 378  * @return NULL on failure (should never happen), name on success.
 379  *         Free the name with GNUNET_free().
 380  */
 381 char *
 382 GNUNET_FS_pseudonym_name_uniquify (const struct GNUNET_CONFIGURATION_Handle *cfg,
 383                                    const struct GNUNET_FS_PseudonymIdentifier *pseudonym,
 384                                    const char *name,
 385                                    unsigned int *suffix);
 386
 387
 388 /**
 389  * Get pseudonym name, metadata and rank. This is a wrapper around
 390  * internal read_info() call, and ensures that returned data is not
 391  * invalid (not NULL).  Writing back information returned by this
 392  * function will give a name "no-name" to pseudonyms that have no
 393  * name. This side-effect is unavoidable, but hardly harmful.
 394  *
 395  * @param cfg configuration
 396  * @param pseudonym cryptographic ID of the pseudonym
 397  * @param ret_meta a location to store metadata pointer. NULL, if metadata
 398  *        is not needed. Destroy with GNUNET_CONTAINER_meta_data_destroy().
 399  * @param ret_rank a location to store rank. NULL, if rank not needed.
 400  * @param ret_name a location to store human-readable name. Name is not unique.
 401  *        NULL, if name is not needed. Free with GNUNET_free().
 402  * @param name_is_a_dup is set to GNUNET_YES, if ret_name was filled with
 403  *        a duplicate of a "no-name" placeholder
 404  * @return GNUNET_OK on success. GNUENT_SYSERR if the data was
 405  *         unobtainable (in that case ret_* are filled with placeholders -
 406  *         empty metadata container, rank -1 and a "no-name" name).
 407  */
 408 int
 409 GNUNET_FS_pseudonym_get_info (const struct GNUNET_CONFIGURATION_Handle *cfg,
 410                               const struct GNUNET_FS_PseudonymIdentifier *pseudonym,
 411                               struct GNUNET_CONTAINER_MetaData **ret_meta,
 412                               int32_t *ret_rank,
 413                               char **ret_name,
 414                               int *name_is_a_dup);
 415
 416
 417 /**
 418  * Get the pseudonym ID belonging to the given pseudonym name.
 419  *
 420  * @param cfg configuration to use
 421  * @param ns_uname unique (!) human-readable name for the pseudonym
 422  * @param pseudonym set to pseudonym ID based on 'ns_uname'
 423  * @return GNUNET_OK on success, GNUNET_SYSERR on failure
 424  */
 425 int
 426 GNUNET_FS_pseudonym_name_to_id (const struct GNUNET_CONFIGURATION_Handle *cfg,
 427                                 const char *ns_uname,
 428                                 struct GNUNET_FS_PseudonymIdentifier *pseudonym);
 429
 430
 431 /**
 432  * Set the pseudonym metadata, rank and name.
 433  *
 434  * @param cfg overall configuration
 435  * @param pseudonym id of the pseudonym
 436  * @param name name to set. Must be the non-unique version of it.
 437  *        May be NULL, in which case it erases pseudonym's name!
 438  * @param md metadata to set
 439  *        May be NULL, in which case it erases pseudonym's metadata!
 440  * @param rank rank to assign
 441  * @return GNUNET_OK on success, GNUNET_SYSERR on failure
 442  */
 443 int
 444 GNUNET_FS_pseudonym_set_info (const struct GNUNET_CONFIGURATION_Handle *cfg,
 445                               const struct GNUNET_FS_PseudonymIdentifier *pseudonym,
 446                               const char *name,
 447                               const struct GNUNET_CONTAINER_MetaData *md,
 448                               int32_t rank);
 449
 450
 451 /**
 452  * Remove pseudonym from the set of known pseudonyms.
 453  *
 454  * @param cfg overall configuration
 455  * @param id the pseudonym identifier
 456  * @return GNUNET_OK on success, GNUNET_SYSERR on failure
 457  */
 458 int
 459 GNUNET_FS_pseudonym_remove (const struct GNUNET_CONFIGURATION_Handle *cfg,
 460                             const struct GNUNET_FS_PseudonymIdentifier *id);
 461
 462
 463 /**
 464  * Get a unique key from a URI.  This is for putting URIs
 465  * into HashMaps.  The key may change between FS implementations.
 466  *
 467  * @param uri uri to convert to a unique key
 468  * @param key wherer to store the unique key
 469  */
 470 void
 471 GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri, struct GNUNET_HashCode * key);
 472
 473
 474 /**
 475  * Convert a URI to a UTF-8 String.
 476  *
 477  * @param uri uri to convert to a string
 478  * @return the UTF-8 string
 479  */
 480 char *
 481 GNUNET_FS_uri_to_string (const struct GNUNET_FS_Uri *uri);
 482
 483
 484 /**
 485  * Convert keyword URI to a human readable format
 486  * (i.e. the search query that was used in the first place)
 487  *
 488  * @param uri ksk uri to convert to a string
 489  * @return string with the keywords
 490  */
 491 char *
 492 GNUNET_FS_uri_ksk_to_string_fancy (const struct GNUNET_FS_Uri *uri);
 493
 494
 495 /**
 496  * Add the given keyword to the set of keywords represented by the URI.
 497  * Does nothing if the keyword is already present.
 498  *
 499  * @param uri ksk uri to modify
 500  * @param keyword keyword to add
 501  * @param is_mandatory is this keyword mandatory?
 502  */
 503 void
 504 GNUNET_FS_uri_ksk_add_keyword (struct GNUNET_FS_Uri *uri, const char *keyword,
 505                                int is_mandatory);
 506
 507
 508 /**
 509  * Remove the given keyword from the set of keywords represented by the URI.
 510  * Does nothing if the keyword is not present.
 511  *
 512  * @param uri ksk uri to modify
 513  * @param keyword keyword to add
 514  */
 515 void
 516 GNUNET_FS_uri_ksk_remove_keyword (struct GNUNET_FS_Uri *uri,
 517                                   const char *keyword);
 518
 519
 520 /**
 521  * Convert a UTF-8 String to a URI.
 522  *
 523  * @param uri string to parse
 524  * @param emsg where to store the parser error message (if any)
 525  * @return NULL on error
 526  */
 527 struct GNUNET_FS_Uri *
 528 GNUNET_FS_uri_parse (const char *uri, char **emsg);
 529
 530
 531 /**
 532  * Free URI.
 533  *
 534  * @param uri uri to free
 535  */
 536 void
 537 GNUNET_FS_uri_destroy (struct GNUNET_FS_Uri *uri);
 538
 539
 540 /**
 541  * How many keywords are ANDed in this keyword URI?
 542  *
 543  * @param uri ksk uri to get the number of keywords from
 544  * @return 0 if this is not a keyword URI
 545  */
 546 unsigned int
 547 GNUNET_FS_uri_ksk_get_keyword_count (const struct GNUNET_FS_Uri *uri);
 548
 549
 550 /**
 551  * Iterate over all keywords in this keyword URI.
 552  *
 553  * @param uri ksk uri to get the keywords from
 554  * @param iterator function to call on each keyword
 555  * @param iterator_cls closure for iterator
 556  * @return -1 if this is not a keyword URI, otherwise number of
 557  *   keywords iterated over until iterator aborted
 558  */
 559 int
 560 GNUNET_FS_uri_ksk_get_keywords (const struct GNUNET_FS_Uri *uri,
 561                                 GNUNET_FS_KeywordIterator iterator,
 562                                 void *iterator_cls);
 563
 564
 565 /**
 566  * Obtain the identity of the peer offering the data
 567  *
 568  * @param uri the location URI to inspect
 569  * @param peer where to store the identify of the peer (presumably) offering the content
 570  * @return GNUNET_SYSERR if this is not a location URI, otherwise GNUNET_OK
 571  */
 572 int
 573 GNUNET_FS_uri_loc_get_peer_identity (const struct GNUNET_FS_Uri *uri,
 574                                      struct GNUNET_PeerIdentity *peer);
 575
 576
 577 /**
 578  * Obtain the URI of the content itself.
 579  *
 580  * @param uri location URI to get the content URI from
 581  * @return NULL if argument is not a location URI
 582  */
 583 struct GNUNET_FS_Uri *
 584 GNUNET_FS_uri_loc_get_uri (const struct GNUNET_FS_Uri *uri);
 585
 586
 587 /**
 588  * Obtain the expiration of the LOC URI.
 589  *
 590  * @param uri location URI to get the expiration from
 591  * @return expiration time of the URI
 592  */
 593 struct GNUNET_TIME_Absolute
 594 GNUNET_FS_uri_loc_get_expiration (const struct GNUNET_FS_Uri *uri);
 595
 596
 597 /**
 598  * Construct a location URI (this peer will be used for the location).
 599  *
 600  * @param baseUri content offered by the sender
 601  * @param cfg configuration information (used to find our hostkey)
 602  * @param expiration_time how long will the content be offered?
 603  * @return the location URI, NULL on error
 604  */
 605 struct GNUNET_FS_Uri *
 606 GNUNET_FS_uri_loc_create (const struct GNUNET_FS_Uri *baseUri,
 607                           const struct GNUNET_CONFIGURATION_Handle *cfg,
 608                           struct GNUNET_TIME_Absolute expiration_time);
 609
 610
 611 /**
 612  * Merge the sets of keywords from two KSK URIs.
 613  *
 614  * @param u1 first uri
 615  * @param u2 second uri
 616  * @return merged URI, NULL on error
 617  */
 618 struct GNUNET_FS_Uri *
 619 GNUNET_FS_uri_ksk_merge (const struct GNUNET_FS_Uri *u1,
 620                          const struct GNUNET_FS_Uri *u2);
 621
 622
 623 /**
 624  * Duplicate URI.
 625  *
 626  * @param uri the URI to duplicate
 627  * @return copy of the URI
 628  */
 629 struct GNUNET_FS_Uri *
 630 GNUNET_FS_uri_dup (const struct GNUNET_FS_Uri *uri);
 631
 632
 633 /**
 634  * Create an FS URI from a single user-supplied string of keywords.
 635  * The string is broken up at spaces into individual keywords.
 636  * Keywords that start with "+" are mandatory.  Double-quotes can
 637  * be used to prevent breaking up strings at spaces (and also
 638  * to specify non-mandatory keywords starting with "+").
 639  *
 640  * Keywords must contain a balanced number of double quotes and
 641  * double quotes can not be used in the actual keywords (for
 642  * example, the string '""foo bar""' will be turned into two
 643  * "OR"ed keywords 'foo' and 'bar', not into '"foo bar"'.
 644  *
 645  * @param keywords the keyword string
 646  * @param emsg where to store an error message
 647  * @return an FS URI for the given keywords, NULL
 648  *  if keywords is not legal (i.e. empty).
 649  */
 650 struct GNUNET_FS_Uri *
 651 GNUNET_FS_uri_ksk_create (const char *keywords, char **emsg);
 652
 653
 654 /**
 655  * Create an FS URI from a user-supplied command line of keywords.
 656  * Arguments should start with "+" to indicate mandatory
 657  * keywords.
 658  *
 659  * @param argc number of keywords
 660  * @param argv keywords (double quotes are not required for
 661  *             keywords containing spaces; however, double
 662  *             quotes are required for keywords starting with
 663  *             "+"); there is no mechanism for having double
 664  *             quotes in the actual keywords (if the user
 665  *             did specifically specify double quotes, the
 666  *             caller should convert each double quote
 667  *             into two single quotes).
 668  * @return an FS URI for the given keywords, NULL
 669  *  if keywords is not legal (i.e. empty).
 670  */
 671 struct GNUNET_FS_Uri *
 672 GNUNET_FS_uri_ksk_create_from_args (unsigned int argc, const char **argv);
 673
 674
 675 /**
 676  * Test if two URIs are equal.
 677  *
 678  * @param u1 one of the URIs
 679  * @param u2 the other URI
 680  * @return GNUNET_YES if the URIs are equal
 681  */
 682 int
 683 GNUNET_FS_uri_test_equal (const struct GNUNET_FS_Uri *u1,
 684                           const struct GNUNET_FS_Uri *u2);
 685
 686
 687 /**
 688  * Is this a namespace URI?
 689  *
 690  * @param uri the uri to check
 691  * @return GNUNET_YES if this is an SKS uri
 692  */
 693 int
 694 GNUNET_FS_uri_test_sks (const struct GNUNET_FS_Uri *uri);
 695
 696
 697 /**
 698  * Handle to one of our namespaces.
 699  */
 700 struct GNUNET_FS_Namespace;
 701
 702
 703 /**
 704  * Create an SKS URI from a namespace and an identifier.
 705  *
 706  * @param ns namespace
 707  * @param id identifier
 708  * @param emsg where to store an error message
 709  * @return an FS URI for the given namespace and identifier
 710  */
 711 struct GNUNET_FS_Uri *
 712 GNUNET_FS_uri_sks_create (struct GNUNET_FS_Namespace *ns, const char *id,
 713                           char **emsg);
 714
 715
 716 /**
 717  * Create an SKS URI from a namespace ID and an identifier.
 718  *
 719  * @param pseudonym pseudonym to use
 720  * @param id identifier
 721  * @return an FS URI for the given namespace and identifier
 722  */
 723 struct GNUNET_FS_Uri *
 724 GNUNET_FS_uri_sks_create_from_nsid (struct GNUNET_FS_PseudonymIdentifier *pseudonym,
 725                                     const char *id);
 726
 727
 728 /**
 729  * Get the public key of a namespace from the given
 730  * namespace URI.
 731  *
 732  * @param uri the uri to get the namespace ID from
 733  * @param pseudonym where to store the public key of the namespace
 734  * @return GNUNET_OK on success
 735  */
 736 int
 737 GNUNET_FS_uri_sks_get_namespace (const struct GNUNET_FS_Uri *uri,
 738                                  struct GNUNET_FS_PseudonymIdentifier *pseudonym);
 739
 740
 741 /**
 742  * Get the content identifier of an SKS URI.
 743  *
 744  * @param uri the sks uri
 745  * @return NULL on error (not a valid SKS URI)
 746  */
 747 char *
 748 GNUNET_FS_uri_sks_get_content_id (const struct GNUNET_FS_Uri *uri);
 749
 750
 751 /**
 752  * Convert namespace URI to a human readable format
 753  * (using the namespace description, if available).
 754  *
 755  * @param cfg configuration to use
 756  * @param uri SKS uri to convert
 757  * @return NULL on error (not an SKS URI)
 758  */
 759 char *
 760 GNUNET_FS_uri_sks_to_string_fancy (struct GNUNET_CONFIGURATION_Handle *cfg,
 761                                    const struct GNUNET_FS_Uri *uri);
 762
 763
 764 /**
 765  * Is this a keyword URI?
 766  *
 767  * @param uri the uri
 768  * @return GNUNET_YES if this is a KSK uri
 769  */
 770 int
 771 GNUNET_FS_uri_test_ksk (const struct GNUNET_FS_Uri *uri);
 772
 773
 774 /**
 775  * Is this a file (or directory) URI?
 776  *
 777  * @param uri the uri to check
 778  * @return GNUNET_YES if this is a CHK uri
 779  */
 780 int
 781 GNUNET_FS_uri_test_chk (const struct GNUNET_FS_Uri *uri);
 782
 783
 784 /**
 785  * What is the size of the file that this URI
 786  * refers to?
 787  *
 788  * @param uri the CHK (or LOC) URI to inspect
 789  * @return size of the file as specified in the CHK URI
 790  */
 791 uint64_t
 792 GNUNET_FS_uri_chk_get_file_size (const struct GNUNET_FS_Uri *uri);
 793
 794
 795 /**
 796  * Is this a location URI?
 797  *
 798  * @param uri the uri to check
 799  * @return GNUNET_YES if this is a LOC uri
 800  */
 801 int
 802 GNUNET_FS_uri_test_loc (const struct GNUNET_FS_Uri *uri);
 803
 804
 805 /**
 806  * Construct a keyword-URI from meta-data (take all entries
 807  * in the meta-data and construct one large keyword URI
 808  * that lists all keywords that can be found in the meta-data).
 809  *
 810  * @param md metadata to use
 811  * @return NULL on error, otherwise a KSK URI
 812  */
 813 struct GNUNET_FS_Uri *
 814 GNUNET_FS_uri_ksk_create_from_meta_data (const struct GNUNET_CONTAINER_MetaData
 815                                          *md);
 816
 817
 818 /* ******************** command-line option parsing API *********************** */
 819
 820 /**
 821  * Command-line option parser function that allows the user
 822  * to specify one or more '-k' options with keywords.  Each
 823  * specified keyword will be added to the URI.  A pointer to
 824  * the URI must be passed as the "scls" argument.
 825  *
 826  * @param ctx command line processor context
 827  * @param scls must be of type "struct GNUNET_FS_Uri **"
 828  * @param option name of the option (typically 'k')
 829  * @param value command line argument given
 830  * @return GNUNET_OK on success
 831  */
 832 int
 833 GNUNET_FS_getopt_set_keywords (struct GNUNET_GETOPT_CommandLineProcessorContext
 834                                *ctx, void *scls, const char *option,
 835                                const char *value);
 836
 837
 838 /**
 839  * Command-line option parser function that allows the user to specify
 840  * one or more '-m' options with metadata.  Each specified entry of
 841  * the form "type=value" will be added to the metadata.  A pointer to
 842  * the metadata must be passed as the "scls" argument.
 843  *
 844  * @param ctx command line processor context
 845  * @param scls must be of type "struct GNUNET_CONTAINER_MetaData **"
 846  * @param option name of the option (typically 'k')
 847  * @param value command line argument given
 848  * @return GNUNET_OK on success
 849  */
 850 int
 851 GNUNET_FS_getopt_set_metadata (struct GNUNET_GETOPT_CommandLineProcessorContext
 852                                *ctx, void *scls, const char *option,
 853                                const char *value);
 854
 855
 856
 857 /* ************************* sharing API ***************** */
 858
 859
 860 /**
 861  * Possible status codes used in the callback for the
 862  * various file-sharing operations.  On each file (or search),
 863  * the callback is guaranteed to be called once with "START"
 864  * and once with STOPPED; calls with PROGRESS, ERROR or COMPLETED
 865  * are optional and depend on the circumstances; parent operations
 866  * will be STARTED before child-operations and STOPPED after
 867  * their respective child-operations.  START and STOP signals
 868  * are typically generated either due to explicit client requests
 869  * or because of suspend/resume operations.
 870  */
 871 enum GNUNET_FS_Status
 872 {
 873   /**
 874    * Notification that we have started to publish a file structure.
 875    */
 876   GNUNET_FS_STATUS_PUBLISH_START = 0,
 877
 878   /**
 879    * Notification that we have resumed sharing a file structure.
 880    */
 881   GNUNET_FS_STATUS_PUBLISH_RESUME = 1,
 882
 883   /**
 884    * Notification that we have suspended sharing a file structure.
 885    */
 886   GNUNET_FS_STATUS_PUBLISH_SUSPEND = 2,
 887
 888   /**
 889    * Notification that we are making progress sharing a file structure.
 890    */
 891   GNUNET_FS_STATUS_PUBLISH_PROGRESS = 3,
 892
 893   /**
 894    * Notification that an error was encountered  sharing a file structure.
 895    * The application will continue to receive resume/suspend events for
 896    * this structure until "GNUNET_FS_publish_stop" is called.
 897    */
 898   GNUNET_FS_STATUS_PUBLISH_ERROR = 4,
 899
 900   /**
 901    * Notification that we completed sharing a file structure.
 902    * The application will continue to receive resume/suspend events for
 903    * this structure until "GNUNET_FS_publish_stop" is called.
 904    */
 905   GNUNET_FS_STATUS_PUBLISH_COMPLETED = 5,
 906
 907   /**
 908    * Notification that we have stopped
 909    * the process of uploading a file structure; no
 910    * futher events will be generated for this action.
 911    */
 912   GNUNET_FS_STATUS_PUBLISH_STOPPED = 6,
 913
 914   /**
 915    * Notification that we have started this download.
 916    */
 917   GNUNET_FS_STATUS_DOWNLOAD_START = 7,
 918
 919   /**
 920    * Notification that this download is being resumed.
 921    */
 922   GNUNET_FS_STATUS_DOWNLOAD_RESUME = 8,
 923
 924   /**
 925    * Notification that this download was suspended.
 926    */
 927   GNUNET_FS_STATUS_DOWNLOAD_SUSPEND = 9,
 928
 929   /**
 930    * Notification about progress with this download.
 931    */
 932   GNUNET_FS_STATUS_DOWNLOAD_PROGRESS = 10,
 933
 934   /**
 935    * Notification that this download encountered an error.
 936    */
 937   GNUNET_FS_STATUS_DOWNLOAD_ERROR = 11,
 938
 939   /**
 940    * Notification that this download completed.  Note that for
 941    * directories, completion does not imply completion of all files in
 942    * the directory.
 943    */
 944   GNUNET_FS_STATUS_DOWNLOAD_COMPLETED = 12,
 945
 946   /**
 947    * Notification that this download was stopped
 948    * (final event with respect to this action).
 949    */
 950   GNUNET_FS_STATUS_DOWNLOAD_STOPPED = 13,
 951
 952   /**
 953    * Notification that this download is now actively being
 954    * pursued (as opposed to waiting in the queue).
 955    */
 956   GNUNET_FS_STATUS_DOWNLOAD_ACTIVE = 14,
 957
 958   /**
 959    * Notification that this download is no longer actively
 960    * being pursued (back in the queue).
 961    */
 962   GNUNET_FS_STATUS_DOWNLOAD_INACTIVE = 15,
 963
 964   /**
 965    * Notification that this download is no longer part of a
 966    * recursive download or search but now a 'stand-alone'
 967    * download (and may thus need to be moved in the GUI
 968    * into a different category).
 969    */
 970   GNUNET_FS_STATUS_DOWNLOAD_LOST_PARENT = 16,
 971
 972   /**
 973    * First event generated when a client requests
 974    * a search to begin or when a namespace result
 975    * automatically triggers the search for updates.
 976    */
 977   GNUNET_FS_STATUS_SEARCH_START = 17,
 978
 979   /**
 980    * Last event when a search is being resumed;
 981    * note that "GNUNET_FS_SEARCH_START" will not
 982    * be generated in this case.
 983    */
 984   GNUNET_FS_STATUS_SEARCH_RESUME = 18,
 985
 986   /**
 987    * Event generated for each search result
 988    * when the respective search is resumed.
 989    */
 990   GNUNET_FS_STATUS_SEARCH_RESUME_RESULT = 19,
 991
 992   /**
 993    * Last event when a search is being suspended;
 994    * note that "GNUNET_FS_SEARCH_STOPPED" will not
 995    * be generated in this case.
 996    */
 997   GNUNET_FS_STATUS_SEARCH_SUSPEND = 20,
 998
 999   /**
1000    * This search has yielded a result.
1001    */
1002   GNUNET_FS_STATUS_SEARCH_RESULT = 21,
1003
1004   /**
1005    * We have discovered a new namespace.
1006    */
1007   GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE = 22,
1008
1009   /**
1010    * We have additional data about the quality
1011    * or availability of a search result.
1012    */
1013   GNUNET_FS_STATUS_SEARCH_UPDATE = 23,
1014
1015   /**
1016    * Signals a problem with this search.
1017    */
1018   GNUNET_FS_STATUS_SEARCH_ERROR = 24,
1019
1020   /**
1021    * Signals that this search was paused.
1022    */
1023   GNUNET_FS_STATUS_SEARCH_PAUSED = 25,
1024
1025   /**
1026    * Signals that this search was continued (unpaused).
1027    */
1028   GNUNET_FS_STATUS_SEARCH_CONTINUED = 26,
1029
1030   /**
1031    * Event generated for each search result
1032    * when the respective search is stopped.
1033    */
1034   GNUNET_FS_STATUS_SEARCH_RESULT_STOPPED = 27,
1035
1036   /**
1037    * Event generated for each search result
1038    * when the respective search is suspended.
1039    */
1040   GNUNET_FS_STATUS_SEARCH_RESULT_SUSPEND = 28,
1041
1042   /**
1043    * Last message from a search; this signals
1044    * that there will be no further events associated
1045    * with this search.
1046    */
1047   GNUNET_FS_STATUS_SEARCH_STOPPED = 29,
1048
1049   /**
1050    * Notification that we started to unindex a file.
1051    */
1052   GNUNET_FS_STATUS_UNINDEX_START = 30,
1053
1054   /**
1055    * Notification that we resumed unindexing of a file.
1056    */
1057   GNUNET_FS_STATUS_UNINDEX_RESUME = 31,
1058
1059   /**
1060    * Notification that we suspended unindexing a file.
1061    */
1062   GNUNET_FS_STATUS_UNINDEX_SUSPEND = 32,
1063
1064   /**
1065    * Notification that we made progress unindexing a file.
1066    */
1067   GNUNET_FS_STATUS_UNINDEX_PROGRESS = 33,
1068
1069   /**
1070    * Notification that we encountered an error unindexing
1071    * a file.
1072    */
1073   GNUNET_FS_STATUS_UNINDEX_ERROR = 34,
1074
1075   /**
1076    * Notification that the unindexing of this file
1077    * was completed.
1078    */
1079   GNUNET_FS_STATUS_UNINDEX_COMPLETED = 35,
1080
1081   /**
1082    * Notification that the unindexing of this file
1083    * was stopped (final event for this action).
1084    */
1085   GNUNET_FS_STATUS_UNINDEX_STOPPED = 36
1086 };
1087
1088
1089 /**
1090  * Handle for controlling an upload.
1091  */
1092 struct GNUNET_FS_PublishContext;
1093
1094
1095 /**
1096  * Handle for controlling an unindexing operation.
1097  */
1098 struct GNUNET_FS_UnindexContext;
1099
1100
1101 /**
1102  * Handle for controlling a search.
1103  */
1104 struct GNUNET_FS_SearchContext;
1105
1106
1107 /**
1108  * Result from a search.  Opaque handle to refer to the search
1109  * (typically used when starting a download associated with the search
1110  * result).
1111  */
1112 struct GNUNET_FS_SearchResult;
1113
1114
1115 /**
1116  * Context for controlling a download.
1117  */
1118 struct GNUNET_FS_DownloadContext;
1119
1120
1121 /**
1122  * Handle for detail information about a file that is being publishd.
1123  * Specifies metadata, keywords, how to get the contents of the file
1124  * (i.e. data-buffer in memory, filename on disk) and other options.
1125  */
1126 struct GNUNET_FS_FileInformation;
1127
1128
1129 /**
1130  * Argument given to the progress callback with
1131  * information about what is going on.
1132  */
1133 struct GNUNET_FS_ProgressInfo
1134 {
1135
1136   /**
1137    * Values that depend on the event type.
1138    */
1139   union
1140   {
1141
1142     /**
1143      * Values for all "GNUNET_FS_STATUS_PUBLISH_*" events.
1144      */
1145     struct
1146     {
1147
1148       /**
1149        * Context for controlling the upload.
1150        */
1151       struct GNUNET_FS_PublishContext *pc;
1152
1153       /**
1154        * Information about the file that is being publishd.
1155        */
1156       const struct GNUNET_FS_FileInformation *fi;
1157
1158       /**
1159        * Client context pointer (set the last time by the client for
1160        * this operation; initially NULL on START/RESUME events).
1161        */
1162       void *cctx;
1163
1164       /**
1165        * Client context pointer for the parent operation
1166        * (if this is a file in a directory or a subdirectory).
1167        */
1168       void *pctx;
1169
1170       /**
1171        * Name of the file being published; can be NULL.
1172        */
1173       const char *filename;
1174
1175       /**
1176        * How large is the file overall?  For directories,
1177        * this is only the size of the directory itself,
1178        * not of the other files contained within the
1179        * directory.
1180        */
1181       uint64_t size;
1182
1183       /**
1184        * At what time do we expect to finish the upload?
1185        * (will be a value in the past for completed
1186        * uploads).
1187        */
1188       struct GNUNET_TIME_Relative eta;
1189
1190       /**
1191        * How long has this upload been actively running
1192        * (excludes times where the upload was suspended).
1193        */
1194       struct GNUNET_TIME_Relative duration;
1195
1196       /**
1197        * How many bytes have we completed?
1198        */
1199       uint64_t completed;
1200
1201       /**
1202        * What anonymity level is used for this upload?
1203        */
1204       uint32_t anonymity;
1205
1206       /**
1207        * Additional values for specific events.
1208        */
1209       union
1210       {
1211
1212         /**
1213          * These values are only valid for
1214          * GNUNET_FS_STATUS_PUBLISH_PROGRESS events.
1215          */
1216         struct
1217         {
1218
1219           /**
1220            * Data block we just published.
1221            */
1222           const void *data;
1223
1224           /**
1225            * At what offset in the file is "data"?
1226            */
1227           uint64_t offset;
1228
1229           /**
1230            * Length of the data block.
1231            */
1232           uint64_t data_len;
1233
1234           /**
1235            * Depth of the given block in the tree;
1236            * 0 would be the lowest level (DBLOCKs).
1237            */
1238           unsigned int depth;
1239
1240         } progress;
1241
1242         /**
1243          * These values are only valid for
1244          * GNUNET_FS_STATUS_PUBLISH_RESUME events.
1245          */
1246         struct
1247         {
1248
1249           /**
1250            * Error message, NULL if no error was encountered so far.
1251            */
1252           const char *message;
1253
1254           /**
1255            * URI of the file (if the download had been completed)
1256            */
1257           const struct GNUNET_FS_Uri *chk_uri;
1258
1259         } resume;
1260
1261         /**
1262          * These values are only valid for
1263          * GNUNET_FS_STATUS_PUBLISH_COMPLETED events.
1264          */
1265         struct
1266         {
1267
1268           /**
1269            * URI of the file.
1270            */
1271           const struct GNUNET_FS_Uri *chk_uri;
1272
1273         } completed;
1274
1275         /**
1276          * These values are only valid for
1277          * GNUNET_FS_STATUS_PUBLISH_ERROR events.
1278          */
1279         struct
1280         {
1281
1282           /**
1283            * Error message, never NULL.
1284            */
1285           const char *message;
1286
1287         } error;
1288
1289       } specifics;
1290
1291     } publish;
1292
1293
1294     /**
1295      * Values for all "GNUNET_FS_STATUS_DOWNLOAD_*" events.
1296      */
1297     struct
1298     {
1299
1300       /**
1301        * Context for controlling the download.
1302        */
1303       struct GNUNET_FS_DownloadContext *dc;
1304
1305       /**
1306        * Client context pointer (set the last time
1307        * by the client for this operation; initially
1308        * NULL on START/RESUME events).
1309        */
1310       void *cctx;
1311
1312       /**
1313        * Client context pointer for the parent operation
1314        * (if this is a file in a directory or a subdirectory).
1315        */
1316       void *pctx;
1317
1318       /**
1319        * Client context pointer for the associated search operation
1320        * (specifically, context pointer for the specific search
1321        * result, not the overall search); only set if this
1322        * download was started from a search result.
1323        */
1324       void *sctx;
1325
1326       /**
1327        * URI used for this download.
1328        */
1329       const struct GNUNET_FS_Uri *uri;
1330
1331       /**
1332        * Name of the file that we are downloading.
1333        */
1334       const char *filename;
1335
1336       /**
1337        * How large is the download overall?  This
1338        * is NOT necessarily the size from the
1339        * URI since we may be doing a partial download.
1340        */
1341       uint64_t size;
1342
1343       /**
1344        * At what time do we expect to finish the download?
1345        * (will be a value in the past for completed
1346        * uploads).
1347        */
1348       struct GNUNET_TIME_Relative eta;
1349
1350       /**
1351        * How long has this download been active?
1352        */
1353       struct GNUNET_TIME_Relative duration;
1354
1355       /**
1356        * How many bytes have we completed?
1357        */
1358       uint64_t completed;
1359
1360       /**
1361        * What anonymity level is used for this download?
1362        */
1363       uint32_t anonymity;
1364
1365       /**
1366        * Is the download currently active.
1367        */
1368       int is_active;
1369
1370       /**
1371        * Additional values for specific events.
1372        */
1373       union
1374       {
1375
1376         /**
1377          * These values are only valid for
1378          * GNUNET_FS_STATUS_DOWNLOAD_PROGRESS events.
1379          */
1380         struct
1381         {
1382
1383           /**
1384            * Data block we just obtained, can be NULL (even if
1385            * data_len > 0) if we found the entire block 'intact' on
1386            * disk.  In this case, it is also possible for 'data_len'
1387            * to be larger than an individual (32k) block.
1388            */
1389           const void *data;
1390
1391           /**
1392            * At what offset in the file is "data"?
1393            */
1394           uint64_t offset;
1395
1396           /**
1397            * Length of the data block.
1398            */
1399           uint64_t data_len;
1400
1401           /**
1402            * How much time passed between us asking for this block and
1403            * actually getting it? GNUNET_TIME_UNIT_FOREVER_REL if unknown.
1404            */
1405           struct GNUNET_TIME_Relative block_download_duration;
1406
1407           /**
1408            * Depth of the given block in the tree;
1409            * 0 would be the lowest level (DBLOCKS).
1410            */
1411           unsigned int depth;
1412
1413           /**
1414            * How much respect did we offer for downloading this block? (estimate,
1415            * because we might have the same request pending for multiple clients,
1416            * and of course because a transmission may have failed at a lower
1417            * layer).
1418            */
1419           uint32_t respect_offered;
1420
1421           /**
1422            * How often did we transmit the request? (estimate,
1423            * because we might have the same request pending for multiple clients,
1424            * and of course because a transmission may have failed at a lower
1425            * layer).
1426            */
1427           uint32_t num_transmissions;
1428
1429         } progress;
1430
1431         /**
1432          * These values are only valid for
1433          * GNUNET_FS_STATUS_DOWNLOAD_START events.
1434          */
1435         struct
1436         {
1437
1438           /**
1439            * Known metadata for the download.
1440            */
1441           const struct GNUNET_CONTAINER_MetaData *meta;
1442
1443         } start;
1444
1445         /**
1446          * These values are only valid for
1447          * GNUNET_FS_STATUS_DOWNLOAD_RESUME events.
1448          */
1449         struct
1450         {
1451
1452           /**
1453            * Known metadata for the download.
1454            */
1455           const struct GNUNET_CONTAINER_MetaData *meta;
1456
1457           /**
1458            * Error message, NULL if we have not encountered any error yet.
1459            */
1460           const char *message;
1461
1462         } resume;
1463
1464         /**
1465          * These values are only valid for
1466          * GNUNET_FS_STATUS_DOWNLOAD_ERROR events.
1467          */
1468         struct
1469         {
1470
1471           /**
1472            * Error message.
1473            */
1474           const char *message;
1475
1476         } error;
1477
1478       } specifics;
1479
1480     } download;
1481
1482     /**
1483      * Values for all "GNUNET_FS_STATUS_SEARCH_*" events.
1484      */
1485     struct
1486     {
1487
1488       /**
1489        * Context for controlling the search, NULL for
1490        * searches that were not explicitly triggered
1491        * by the client (i.e., searches for updates in
1492        * namespaces).
1493        */
1494       struct GNUNET_FS_SearchContext *sc;
1495
1496       /**
1497        * Client context pointer (set the last time by the client for
1498        * this operation; initially NULL on START/RESUME events).  Note
1499        * that this value can only be set on START/RESUME; returning
1500        * non-NULL on RESULT/RESUME_RESULT will actually update the
1501        * private context for "UPDATE" events.
1502        */
1503       void *cctx;
1504
1505       /**
1506        * Client parent-context pointer; NULL for top-level searches,
1507        * refers to the client context of the associated search result
1508        * for automatically triggered searches for updates in
1509        * namespaces.  In this case, 'presult' refers to that search
1510        * result.
1511        */
1512       void *pctx;
1513
1514       /**
1515        * What query is used for this search
1516        * (list of keywords or SKS identifier).
1517        */
1518       const struct GNUNET_FS_Uri *query;
1519
1520       /**
1521        * How long has this search been actively running
1522        * (excludes times where the search was paused or
1523        * suspended).
1524        */
1525       struct GNUNET_TIME_Relative duration;
1526
1527       /**
1528        * What anonymity level is used for this search?
1529        */
1530       uint32_t anonymity;
1531
1532       /**
1533        * Additional values for specific events.
1534        */
1535       union
1536       {
1537
1538         /**
1539          * These values are only valid for
1540          * GNUNET_FS_STATUS_SEARCH_RESULT events.
1541          */
1542         struct
1543         {
1544
1545           /**
1546            * Metadata for the search result.
1547            */
1548           const struct GNUNET_CONTAINER_MetaData *meta;
1549
1550           /**
1551            * URI for the search result.
1552            */
1553           const struct GNUNET_FS_Uri *uri;
1554
1555           /**
1556            * Handle to the result (for starting downloads).
1557            */
1558           struct GNUNET_FS_SearchResult *result;
1559
1560           /**
1561            * Applicability rank (the larger, the better the result
1562            * fits the search criteria).
1563            */
1564           uint32_t applicability_rank;
1565
1566         } result;
1567
1568         /**
1569          * These values are only valid for
1570          * GNUNET_FS_STATUS_SEARCH_RESUME_RESULT events.
1571          */
1572         struct
1573         {
1574
1575           /**
1576            * Metadata for the search result.
1577            */
1578           const struct GNUNET_CONTAINER_MetaData *meta;
1579
1580           /**
1581            * URI for the search result.
1582            */
1583           const struct GNUNET_FS_Uri *uri;
1584
1585           /**
1586            * Handle to the result (for starting downloads).
1587            */
1588           struct GNUNET_FS_SearchResult *result;
1589
1590           /**
1591            * Current availability rank (negative:
1592            * unavailable, positive: available)
1593            */
1594           int32_t availability_rank;
1595
1596           /**
1597            * On how many total queries is the given
1598            * availability_rank based?
1599            */
1600           uint32_t availability_certainty;
1601
1602           /**
1603            * Updated applicability rank (the larger,
1604            * the better the result fits the search
1605            * criteria).
1606            */
1607           uint32_t applicability_rank;
1608
1609         } resume_result;
1610
1611         /**
1612          * These values are only valid for
1613          * GNUNET_FS_STATUS_SEARCH_UPDATE events.
1614          */
1615         struct
1616         {
1617
1618           /**
1619            * Private context set for for this result
1620            * during the "RESULT" event.
1621            */
1622           void *cctx;
1623
1624           /**
1625            * Metadata for the search result.
1626            */
1627           const struct GNUNET_CONTAINER_MetaData *meta;
1628
1629           /**
1630            * URI for the search result.
1631            */
1632           const struct GNUNET_FS_Uri *uri;
1633
1634           /**
1635            * Current availability rank (negative:
1636            * unavailable, positive: available)
1637            */
1638           int32_t availability_rank;
1639
1640           /**
1641            * On how many total queries is the given
1642            * availability_rank based?
1643            */
1644           uint32_t availability_certainty;
1645
1646           /**
1647            * Updated applicability rank (the larger,
1648            * the better the result fits the search
1649            * criteria).
1650            */
1651           uint32_t applicability_rank;
1652
1653           /**
1654            * How long has the current probe been active?
1655            */
1656           struct GNUNET_TIME_Relative current_probe_time;
1657
1658         } update;
1659
1660         /**
1661          * These values are only valid for
1662          * GNUNET_FS_STATUS_SEARCH_RESULT_SUSPEND events.
1663          * These events are automatically triggered for
1664          * each search result before the
1665          * GNUNET_FS_STATUS_SEARCH_SUSPEND event.  This
1666          * happens primarily to give the client a chance
1667          * to clean up the "cctx" (if needed).
1668          */
1669         struct
1670         {
1671
1672           /**
1673            * Private context set for for this result
1674            * during the "RESULT" event.
1675            */
1676           void *cctx;
1677
1678           /**
1679            * Metadata for the search result.
1680            */
1681           const struct GNUNET_CONTAINER_MetaData *meta;
1682
1683           /**
1684            * URI for the search result.
1685            */
1686           const struct GNUNET_FS_Uri *uri;
1687
1688         } result_suspend;
1689
1690         /**
1691          * These values are only valid for
1692          * GNUNET_FS_STATUS_SEARCH_RESULT_STOPPED events.
1693          * These events are automatically triggered for
1694          * each search result before the
1695          * GNUNET_FS_STATUS_SEARCH_STOPPED event.  This
1696          * happens primarily to give the client a chance
1697          * to clean up the "cctx" (if needed).
1698          */
1699         struct
1700         {
1701
1702           /**
1703            * Private context set for for this result
1704            * during the "RESULT" event.
1705            */
1706           void *cctx;
1707
1708           /**
1709            * Metadata for the search result.
1710            */
1711           const struct GNUNET_CONTAINER_MetaData *meta;
1712
1713           /**
1714            * URI for the search result.
1715            */
1716           const struct GNUNET_FS_Uri *uri;
1717
1718         } result_stopped;
1719
1720         /**
1721          * These values are only valid for
1722          * GNUNET_FS_STATUS_SEARCH_RESUME events.
1723          */
1724         struct
1725         {
1726
1727           /**
1728            * Error message, NULL if we have not encountered any error yet.
1729            */
1730           const char *message;
1731
1732           /**
1733            * Is this search currently paused?
1734            */
1735           int is_paused;
1736
1737         } resume;
1738
1739         /**
1740          * These values are only valid for
1741          * GNUNET_FS_STATUS_SEARCH_ERROR events.
1742          */
1743         struct
1744         {
1745
1746           /**
1747            * Error message.
1748            */
1749           const char *message;
1750
1751         } error;
1752
1753         /**
1754          * Values for all "GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE" events.
1755          */
1756         struct
1757         {
1758
1759           /**
1760            * Handle to the namespace (NULL if it is not a local
1761            * namespace).
1762            */
1763           struct GNUNET_FS_Namespace *ns;
1764
1765           /**
1766            * Short, human-readable name of the namespace.
1767            */
1768           const char *name;
1769
1770           /**
1771            * Root identifier for the namespace, can be NULL.
1772            */
1773           const char *root;
1774
1775           /**
1776            * Metadata for the namespace.
1777            */
1778           const struct GNUNET_CONTAINER_MetaData *meta;
1779
1780           /**
1781            * Public key of the namespace.
1782            */
1783           struct GNUNET_FS_PseudonymIdentifier pseudonym;
1784
1785         } ns;
1786
1787       } specifics;
1788
1789     } search;
1790
1791     /**
1792      * Values for all "GNUNET_FS_STATUS_UNINDEX_*" events.
1793      */
1794     struct
1795     {
1796
1797       /**
1798        * Context for controlling the unindexing.
1799        */
1800       struct GNUNET_FS_UnindexContext *uc;
1801
1802       /**
1803        * Client context pointer (set the last time
1804        * by the client for this operation; initially
1805        * NULL on START/RESUME events).
1806        */
1807       void *cctx;
1808
1809       /**
1810        * Name of the file that is being unindexed.
1811        */
1812       const char *filename;
1813
1814       /**
1815        * How large is the file overall?
1816        */
1817       uint64_t size;
1818
1819       /**
1820        * At what time do we expect to finish unindexing?
1821        * (will be a value in the past for completed
1822        * unindexing opeations).
1823        */
1824       struct GNUNET_TIME_Relative eta;
1825
1826       /**
1827        * How long has this upload been actively running
1828        * (excludes times where the upload was suspended).
1829        */
1830       struct GNUNET_TIME_Relative duration;
1831
1832       /**
1833        * How many bytes have we completed?
1834        */
1835       uint64_t completed;
1836
1837       /**
1838        * Additional values for specific events.
1839        */
1840       union
1841       {
1842
1843         /**
1844          * These values are only valid for
1845          * GNUNET_FS_STATUS_UNINDEX_PROGRESS events.
1846          */
1847         struct
1848         {
1849
1850           /**
1851            * Data block we just unindexed.
1852            */
1853           const void *data;
1854
1855           /**
1856            * At what offset in the file is "data"?
1857            */
1858           uint64_t offset;
1859
1860           /**
1861            * Length of the data block.
1862            */
1863           uint64_t data_len;
1864
1865           /**
1866            * Depth of the given block in the tree;
1867            * 0 would be the lowest level (DBLOCKS).
1868            */
1869           unsigned int depth;
1870
1871         } progress;
1872
1873         /**
1874          * These values are only valid for
1875          * GNUNET_FS_STATUS_UNINDEX_RESUME events.
1876          */
1877         struct
1878         {
1879
1880           /**
1881            * Error message, NULL if we have not encountered any error yet.
1882            */
1883           const char *message;
1884
1885         } resume;
1886
1887         /**
1888          * These values are only valid for
1889          * GNUNET_FS_STATUS_UNINDEX_ERROR events.
1890          */
1891         struct
1892         {
1893
1894           /**
1895            * Error message.
1896            */
1897           const char *message;
1898
1899         } error;
1900
1901       } specifics;
1902
1903     } unindex;
1904
1905   } value;
1906
1907   /**
1908    * Specific status code (determines the event type).
1909    */
1910   enum GNUNET_FS_Status status;
1911
1912   /**
1913    * File-sharing handle that generated the event.
1914    */
1915   struct GNUNET_FS_Handle *fsh;
1916 };
1917
1918
1919 /**
1920  * Notification of FS to a client about the progress of an
1921  * operation.  Callbacks of this type will be used for uploads,
1922  * downloads and searches.  Some of the arguments depend a bit
1923  * in their meaning on the context in which the callback is used.
1924  *
1925  * @param cls closure
1926  * @param info details about the event, specifying the event type
1927  *        and various bits about the event
1928  * @return client-context (for the next progress call
1929  *         for this operation; should be set to NULL for
1930  *         SUSPEND and STOPPED events).  The value returned
1931  *         will be passed to future callbacks in the respective
1932  *         field in the GNUNET_FS_ProgressInfo struct.
1933  */
1934 typedef void *(*GNUNET_FS_ProgressCallback) (void *cls,
1935                                              const struct GNUNET_FS_ProgressInfo *info);
1936
1937
1938 /**
1939  * General (global) option flags for file-sharing.
1940  */
1941 enum GNUNET_FS_Flags
1942 {
1943     /**
1944      * No special flags set.
1945      */
1946   GNUNET_FS_FLAGS_NONE = 0,
1947
1948     /**
1949      * Is persistence of operations desired?
1950      * (will create SUSPEND/RESUME events).
1951      */
1952   GNUNET_FS_FLAGS_PERSISTENCE = 1,
1953
1954     /**
1955      * Should we automatically trigger probes for search results
1956      * to determine availability?
1957      * (will create GNUNET_FS_STATUS_SEARCH_UPDATE events).
1958      */
1959   GNUNET_FS_FLAGS_DO_PROBES = 2
1960 };
1961
1962
1963 /**
1964  * Options specified in the VARARGs portion of GNUNET_FS_start.
1965  */
1966 enum GNUNET_FS_OPTIONS
1967 {
1968
1969   /**
1970    * Last option in the VARARG list.
1971    */
1972   GNUNET_FS_OPTIONS_END = 0,
1973
1974   /**
1975    * Select the desired amount of parallelism (this option should be
1976    * followed by an "unsigned int" giving the desired maximum number
1977    * of parallel downloads).
1978    */
1979   GNUNET_FS_OPTIONS_DOWNLOAD_PARALLELISM = 1,
1980
1981   /**
1982    * Maximum number of requests that should be pending at a given
1983    * point in time (invidivual downloads may go above this, but
1984    * if we are above this threshold, we should not activate any
1985    * additional downloads.
1986    */
1987   GNUNET_FS_OPTIONS_REQUEST_PARALLELISM = 2
1988 };
1989
1990
1991 /**
1992  * Settings for publishing a block (which may of course also
1993  * apply to an entire directory or file).
1994  */
1995 struct GNUNET_FS_BlockOptions
1996 {
1997
1998   /**
1999    * At what time should the block expire?  Data blocks (DBLOCKS and
2000    * IBLOCKS) may still be used even if they are expired (however,
2001    * they'd be removed quickly from the datastore if we are short on
2002    * space), all other types of blocks will no longer be returned
2003    * after they expire.
2004    */
2005   struct GNUNET_TIME_Absolute expiration_time;
2006
2007   /**
2008    * At which anonymity level should the block be shared?
2009    * (0: no anonymity, 1: normal GAP, >1: with cover traffic).
2010    */
2011   uint32_t anonymity_level;
2012
2013   /**
2014    * How important is it for us to store the block?  If we run
2015    * out of space, the highest-priority, non-expired blocks will
2016    * be kept.
2017    */
2018   uint32_t content_priority;
2019
2020   /**
2021    * How often should we try to migrate the block to other peers?
2022    * Only used if "CONTENT_PUSHING" is set to YES, in which case we
2023    * first push each block to other peers according to their
2024    * replication levels.  Once each block has been pushed that many
2025    * times to other peers, blocks are chosen for migration at random.
2026    * Naturally, there is no guarantee that the other peers will keep
2027    * these blocks for any period of time (since they won't have any
2028    * priority or might be too busy to even store the block in the
2029    * first place).
2030    */
2031   uint32_t replication_level;
2032
2033 };
2034
2035
2036 /**
2037  * Return the current year (i.e. '2011').
2038  */
2039 unsigned int
2040 GNUNET_FS_get_current_year (void);
2041
2042
2043 /**
2044  * Convert a year to an expiration time of January 1st of that year.
2045  *
2046  * @param year a year (after 1970, please ;-)).
2047  * @return absolute time for January 1st of that year.
2048  */
2049 struct GNUNET_TIME_Absolute
2050 GNUNET_FS_year_to_time (unsigned int year);
2051
2052
2053 /**
2054  * Convert an expiration time to the respective year (rounds)
2055  *
2056  * @param at absolute time
2057  * @return year a year (after 1970), 0 on error
2058  */
2059 unsigned int
2060 GNUNET_FS_time_to_year (struct GNUNET_TIME_Absolute at);
2061
2062
2063 /**
2064  * Handle to the file-sharing service.
2065  */
2066 struct GNUNET_FS_Handle;
2067
2068
2069 /**
2070  * Setup a connection to the file-sharing service.
2071  *
2072  * @param cfg configuration to use
2073  * @param client_name unique identifier for this client
2074  * @param upcb function to call to notify about FS actions
2075  * @param upcb_cls closure for upcb
2076  * @param flags specific attributes for fs-operations
2077  * @param ... list of optional options, terminated with GNUNET_FS_OPTIONS_END
2078  * @return NULL on error
2079  */
2080 struct GNUNET_FS_Handle *
2081 GNUNET_FS_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
2082                  const char *client_name, GNUNET_FS_ProgressCallback upcb,
2083                  void *upcb_cls, enum GNUNET_FS_Flags flags, ...);
2084
2085
2086 /**
2087  * Close our connection with the file-sharing service.
2088  * The callback given to GNUNET_FS_start will no longer be
2089  * called after this function returns.
2090  *
2091  * @param h handle that was returned from GNUNET_FS_start
2092  */
2093 void
2094 GNUNET_FS_stop (struct GNUNET_FS_Handle *h);
2095
2096
2097 /**
2098  * Function called on entries in a GNUNET_FS_FileInformation publish-structure.
2099  *
2100  * @param cls closure
2101  * @param fi the entry in the publish-structure
2102  * @param length length of the file or directory
2103  * @param meta metadata for the file or directory (can be modified)
2104  * @param uri pointer to the keywords that will be used for this entry (can be modified)
2105  * @param bo block options (can be modified)
2106  * @param do_index should we index (can be modified)
2107  * @param client_info pointer to client context set upon creation (can be modified)
2108  * @return GNUNET_OK to continue, GNUNET_NO to remove
2109  *         this entry from the directory, GNUNET_SYSERR
2110  *         to abort the iteration
2111  */
2112 typedef int (*GNUNET_FS_FileInformationProcessor) (void *cls,
2113                                                    struct
2114                                                    GNUNET_FS_FileInformation *
2115                                                    fi, uint64_t length,
2116                                                    struct
2117                                                    GNUNET_CONTAINER_MetaData *
2118                                                    meta,
2119                                                    struct GNUNET_FS_Uri ** uri,
2120                                                    struct GNUNET_FS_BlockOptions
2121                                                    * bo, int *do_index,
2122                                                    void **client_info);
2123
2124
2125 /**
2126  * Obtain the name under which this file information
2127  * structure is stored on disk.  Only works for top-level
2128  * file information structures.
2129  *
2130  * @param s structure to get the filename for
2131  * @return NULL on error, otherwise filename that
2132  *         can be passed to "GNUNET_FS_file_information_recover"
2133  *         to read this fi-struct from disk.
2134  */
2135 const char *
2136 GNUNET_FS_file_information_get_id (struct GNUNET_FS_FileInformation *s);
2137
2138
2139 /**
2140  * Obtain the filename from the file information structure.
2141  *
2142  * @param s structure to get the filename for
2143  * @return "filename" field of the structure (can be NULL)
2144  */
2145 const char *
2146 GNUNET_FS_file_information_get_filename (struct GNUNET_FS_FileInformation *s);
2147
2148
2149 /**
2150  * Set the filename in the file information structure.
2151  * If filename was already set, frees it before setting the new one.
2152  * Makes a copy of the argument.
2153  *
2154  * @param s structure to get the filename for
2155  * @param filename filename to set
2156  */
2157 void
2158 GNUNET_FS_file_information_set_filename (struct GNUNET_FS_FileInformation *s,
2159                                          const char *filename);
2160
2161
2162 /**
2163  * Create an entry for a file in a publish-structure.
2164  *
2165  * @param h handle to the file sharing subsystem
2166  * @param client_info initial client-info value for this entry
2167  * @param filename name of the file or directory to publish
2168  * @param keywords under which keywords should this file be available
2169  *         directly; can be NULL
2170  * @param meta metadata for the file
2171  * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
2172  *                GNUNET_SYSERR for simulation
2173  * @param bo block options
2174  * @return publish structure entry for the file
2175  */
2176 struct GNUNET_FS_FileInformation *
2177 GNUNET_FS_file_information_create_from_file (struct GNUNET_FS_Handle *h,
2178                                              void *client_info,
2179                                              const char *filename,
2180                                              const struct GNUNET_FS_Uri
2181                                              *keywords,
2182                                              const struct
2183                                              GNUNET_CONTAINER_MetaData *meta,
2184                                              int do_index,
2185                                              const struct GNUNET_FS_BlockOptions
2186                                              *bo);
2187
2188
2189 /**
2190  * Create an entry for a file in a publish-structure.
2191  *
2192  * @param h handle to the file sharing subsystem
2193  * @param client_info initial client-info value for this entry
2194  * @param length length of the file
2195  * @param data data for the file (should not be used afterwards by
2196  *        the caller; callee will "free")
2197  * @param keywords under which keywords should this file be available
2198  *         directly; can be NULL
2199  * @param meta metadata for the file
2200  * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
2201  *                GNUNET_SYSERR for simulation
2202  * @param bo block options
2203  * @return publish structure entry for the file
2204  */
2205 struct GNUNET_FS_FileInformation *
2206 GNUNET_FS_file_information_create_from_data (struct GNUNET_FS_Handle *h,
2207                                              void *client_info, uint64_t length,
2208                                              void *data,
2209                                              const struct GNUNET_FS_Uri
2210                                              *keywords,
2211                                              const struct
2212                                              GNUNET_CONTAINER_MetaData *meta,
2213                                              int do_index,
2214                                              const struct GNUNET_FS_BlockOptions
2215                                              *bo);
2216
2217
2218 /**
2219  * Function that provides data.
2220  *
2221  * @param cls closure
2222  * @param offset offset to read from; it is possible
2223  *            that the caller might need to go backwards
2224  *            a bit at times; set to UINT64_MAX to tell
2225  *            the reader that we won't be reading for a while
2226  *            (used to close the file descriptor but NOT fully
2227  *             clean up the reader's state); in this case,
2228  *            a value of '0' for max should be ignored
2229  * @param max maximum number of bytes that should be
2230  *            copied to buf; readers are not allowed
2231  *            to provide less data unless there is an error;
2232  *            a value of "0" will be used at the end to allow
2233  *            the reader to clean up its internal state
2234  * @param buf where the reader should write the data
2235  * @param emsg location for the reader to store an error message
2236  * @return number of bytes written, usually "max", 0 on error
2237  */
2238 typedef size_t (*GNUNET_FS_DataReader) (void *cls, uint64_t offset, size_t max,
2239                                         void *buf, char **emsg);
2240
2241
2242 /**
2243  * Create an entry for a file in a publish-structure.
2244  *
2245  * @param h handle to the file sharing subsystem
2246  * @param client_info initial client-info value for this entry
2247  * @param length length of the file
2248  * @param reader function that can be used to obtain the data for the file
2249  * @param reader_cls closure for "reader"
2250  * @param keywords under which keywords should this file be available
2251  *         directly; can be NULL
2252  * @param meta metadata for the file
2253  * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
2254  *                GNUNET_SYSERR for simulation
2255  * @param bo block options
2256  * @return publish structure entry for the file
2257  */
2258 struct GNUNET_FS_FileInformation *
2259 GNUNET_FS_file_information_create_from_reader (struct GNUNET_FS_Handle *h,
2260                                                void *client_info,
2261                                                uint64_t length,
2262                                                GNUNET_FS_DataReader reader,
2263                                                void *reader_cls,
2264                                                const struct GNUNET_FS_Uri
2265                                                *keywords,
2266                                                const struct
2267                                                GNUNET_CONTAINER_MetaData *meta,
2268                                                int do_index,
2269                                                const struct
2270                                                GNUNET_FS_BlockOptions *bo);
2271
2272
2273 /**
2274  * Create an entry for an empty directory in a publish-structure.
2275  * This function should be used by applications for which the
2276  * use of "GNUNET_FS_file_information_create_from_directory"
2277  * is not appropriate.
2278  *
2279  * @param h handle to the file sharing subsystem
2280  * @param client_info initial client-info value for this entry
2281  * @param keywords under which keywords should this directory be available
2282  *         directly; can be NULL
2283  * @param meta metadata for the directory
2284  * @param bo block options
2285  * @param filename name of the directory; can be NULL
2286  * @return publish structure entry for the directory , NULL on error
2287  */
2288 struct GNUNET_FS_FileInformation *
2289 GNUNET_FS_file_information_create_empty_directory (struct GNUNET_FS_Handle *h,
2290                                                    void *client_info,
2291                                                    const struct GNUNET_FS_Uri
2292                                                    *keywords,
2293                                                    const struct
2294                                                    GNUNET_CONTAINER_MetaData
2295                                                    *meta,
2296                                                    const struct
2297                                                    GNUNET_FS_BlockOptions *bo,
2298                                                    const char *filename);
2299
2300
2301 /**
2302  * Test if a given entry represents a directory.
2303  *
2304  * @param ent check if this FI represents a directory
2305  * @return GNUNET_YES if so, GNUNET_NO if not
2306  */
2307 int
2308 GNUNET_FS_file_information_is_directory (const struct GNUNET_FS_FileInformation
2309                                          *ent);
2310
2311
2312 /**
2313  * Add an entry to a directory in a publish-structure.  Clients
2314  * should never modify publish structures that were passed to
2315  * "GNUNET_FS_publish_start" already.
2316  *
2317  * @param dir the directory
2318  * @param ent the entry to add; the entry must not have been
2319  *            added to any other directory at this point and
2320  *            must not include "dir" in its structure
2321  * @return GNUNET_OK on success, GNUNET_SYSERR on error
2322  */
2323 int
2324 GNUNET_FS_file_information_add (struct GNUNET_FS_FileInformation *dir,
2325                                 struct GNUNET_FS_FileInformation *ent);
2326
2327
2328 /**
2329  * Inspect a file or directory in a publish-structure.  Clients
2330  * should never modify publish structures that were passed to
2331  * "GNUNET_FS_publish_start" already.  When called on a directory,
2332  * this function will FIRST call "proc" with information about
2333  * the directory itself and then for each of the files in the
2334  * directory (but not for files in subdirectories).  When called
2335  * on a file, "proc" will be called exactly once (with information
2336  * about the specific file).
2337  *
2338  * @param dir the directory
2339  * @param proc function to call on each entry
2340  * @param proc_cls closure for proc
2341  */
2342 void
2343 GNUNET_FS_file_information_inspect (struct GNUNET_FS_FileInformation *dir,
2344                                     GNUNET_FS_FileInformationProcessor proc,
2345                                     void *proc_cls);
2346
2347
2348 /**
2349  * Destroy publish-structure.  Clients should never destroy publish
2350  * structures that were passed to "GNUNET_FS_publish_start" already.
2351  *
2352  * @param fi structure to destroy
2353  * @param cleaner function to call on each entry in the structure
2354  *        (useful to clean up client_info); can be NULL; return
2355  *        values are ignored
2356  * @param cleaner_cls closure for cleaner
2357  */
2358 void
2359 GNUNET_FS_file_information_destroy (struct GNUNET_FS_FileInformation *fi,
2360                                     GNUNET_FS_FileInformationProcessor cleaner,
2361                                     void *cleaner_cls);
2362
2363
2364 /**
2365  * Options for publishing.  Compatible options
2366  * can be OR'ed together.
2367  */
2368 enum GNUNET_FS_PublishOptions
2369 {
2370     /**
2371      * No options (use defaults for everything).
2372      */
2373   GNUNET_FS_PUBLISH_OPTION_NONE = 0,
2374
2375     /**
2376      * Simulate publishing.  With this option, no data will be stored
2377      * in the datastore.  Useful for computing URIs from files.
2378      */
2379   GNUNET_FS_PUBLISH_OPTION_SIMULATE_ONLY = 1
2380 };
2381
2382 /**
2383  * Publish a file or directory.
2384  *
2385  * @param h handle to the file sharing subsystem
2386  * @param fi information about the file or directory structure to publish
2387  * @param ns namespace to publish the file in, NULL for no namespace
2388  * @param nid identifier to use for the publishd content in the namespace
2389  *        (can be NULL, must be NULL if namespace is NULL)
2390  * @param nuid update-identifier that will be used for future updates
2391  *        (can be NULL, must be NULL if namespace or nid is NULL)
2392  * @param options options for the publication
2393  * @return context that can be used to control the publish operation
2394  */
2395 struct GNUNET_FS_PublishContext *
2396 GNUNET_FS_publish_start (struct GNUNET_FS_Handle *h,
2397                          struct GNUNET_FS_FileInformation *fi,
2398                          struct GNUNET_FS_Namespace *ns, const char *nid,
2399                          const char *nuid,
2400                          enum GNUNET_FS_PublishOptions options);
2401
2402
2403 /**
2404  * Stop a publication.  Will abort incomplete publications (but
2405  * not remove blocks that have already been published) or
2406  * simply clean up the state for completed publications.
2407  * Must NOT be called from within the event callback!
2408  *
2409  * @param pc context for the publication to stop
2410  */
2411 void
2412 GNUNET_FS_publish_stop (struct GNUNET_FS_PublishContext *pc);
2413
2414
2415 /**
2416  * Signature of a function called as the continuation of a KBlock or
2417  * SBlock publication.
2418  *
2419  * @param cls closure
2420  * @param uri URI under which the block is now available, NULL on error
2421  * @param emsg error message, NULL on success
2422  */
2423 typedef void (*GNUNET_FS_PublishContinuation) (void *cls,
2424                                                const struct GNUNET_FS_Uri * uri,
2425                                                const char *emsg);
2426
2427
2428 /**
2429  * Handle to cancel publish KSK operation.
2430  */
2431 struct GNUNET_FS_PublishKskContext;
2432
2433
2434 /**
2435  * Publish a KBlock on GNUnet.
2436  *
2437  * @param h handle to the file sharing subsystem
2438  * @param ksk_uri keywords to use
2439  * @param meta metadata to use
2440  * @param uri URI to refer to in the KBlock
2441  * @param bo block options
2442  * @param options publication options
2443  * @param cont continuation
2444  * @param cont_cls closure for cont
2445  * @return NULL on error ('cont' will still be called)
2446  */
2447 struct GNUNET_FS_PublishKskContext *
2448 GNUNET_FS_publish_ksk (struct GNUNET_FS_Handle *h,
2449                        const struct GNUNET_FS_Uri *ksk_uri,
2450                        const struct GNUNET_CONTAINER_MetaData *meta,
2451                        const struct GNUNET_FS_Uri *uri,
2452                        const struct GNUNET_FS_BlockOptions *bo,
2453                        enum GNUNET_FS_PublishOptions options,
2454                        GNUNET_FS_PublishContinuation cont, void *cont_cls);
2455
2456
2457 /**
2458  * Abort the KSK publishing operation.
2459  *
2460  * @param pkc context of the operation to abort.
2461  */
2462 void
2463 GNUNET_FS_publish_ksk_cancel (struct GNUNET_FS_PublishKskContext *pkc);
2464
2465
2466 /**
2467  * Handle to cancel publish SKS operation.
2468  */
2469 struct GNUNET_FS_PublishSksContext;
2470
2471
2472 /**
2473  * Publish an SBlock on GNUnet.
2474  *
2475  * @param h handle to the file sharing subsystem
2476  * @param ns namespace to publish in
2477  * @param identifier identifier to use
2478  * @param update update identifier to use
2479  * @param meta metadata to use
2480  * @param uri URI to refer to in the SBlock
2481  * @param bo block options
2482  * @param options publication options
2483  * @param cont continuation
2484  * @param cont_cls closure for cont
2485  * @return NULL on error ('cont' will still be called)
2486  */
2487 struct GNUNET_FS_PublishSksContext *
2488 GNUNET_FS_publish_sks (struct GNUNET_FS_Handle *h,
2489                        struct GNUNET_FS_Namespace *ns,
2490                        const char *identifier, const char *update,
2491                        const struct GNUNET_CONTAINER_MetaData *meta,
2492                        const struct GNUNET_FS_Uri *uri,
2493                        const struct GNUNET_FS_BlockOptions *bo,
2494                        enum GNUNET_FS_PublishOptions options,
2495                        GNUNET_FS_PublishContinuation cont, void *cont_cls);
2496
2497
2498 /**
2499  * Abort the SKS publishing operation.
2500  *
2501  * @param psc context of the operation to abort.
2502  */
2503 void
2504 GNUNET_FS_publish_sks_cancel (struct GNUNET_FS_PublishSksContext *psc);
2505
2506
2507 /**
2508  * Type of a function called by "GNUNET_FS_get_indexed_files".
2509  *
2510  * @param cls closure
2511  * @param filename the name of the file, NULL for end of list
2512  * @param file_id hash of the contents of the indexed file
2513  * @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort
2514  */
2515 typedef int (*GNUNET_FS_IndexedFileProcessor) (void *cls, const char *filename,
2516                                                const struct GNUNET_HashCode * file_id);
2517
2518
2519 /**
2520  * Handle to cancel 'GNUNET_FS_get_indexed_files'.
2521  */
2522 struct GNUNET_FS_GetIndexedContext;
2523
2524
2525 /**
2526  * Iterate over all indexed files.
2527  *
2528  * @param h handle to the file sharing subsystem
2529  * @param iterator function to call on each indexed file
2530  * @param iterator_cls closure for iterator
2531  * @return NULL on error ('iter' is not called)
2532  */
2533 struct GNUNET_FS_GetIndexedContext *
2534 GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h,
2535                              GNUNET_FS_IndexedFileProcessor iterator,
2536                              void *iterator_cls);
2537
2538
2539 /**
2540  * Cancel iteration over all indexed files.
2541  *
2542  * @param gic operation to cancel
2543  */
2544 void
2545 GNUNET_FS_get_indexed_files_cancel (struct GNUNET_FS_GetIndexedContext *gic);
2546
2547
2548 /**
2549  * Unindex a file.
2550  *
2551  * @param h handle to the file sharing subsystem
2552  * @param filename file to unindex
2553  * @param cctx initial value for the client context
2554  * @return NULL on error, otherwise handle
2555  */
2556 struct GNUNET_FS_UnindexContext *
2557 GNUNET_FS_unindex_start (struct GNUNET_FS_Handle *h, const char *filename,
2558                          void *cctx);
2559
2560
2561 /**
2562  * Clean up after completion of an unindex operation.
2563  *
2564  * @param uc handle
2565  */
2566 void
2567 GNUNET_FS_unindex_stop (struct GNUNET_FS_UnindexContext *uc);
2568
2569
2570 /**
2571  * Create a namespace with the given name; if one already
2572  * exists, return a handle to the existing namespace.
2573  *
2574  * @param h handle to the file sharing subsystem
2575  * @param name name to use for the namespace
2576  * @return handle to the namespace, NULL on error (i.e. invalid filename)
2577  */
2578 struct GNUNET_FS_Namespace *
2579 GNUNET_FS_namespace_create (struct GNUNET_FS_Handle *h, const char *name);
2580
2581
2582 /**
2583  * Open the namespace with the given name; if it does not exist,
2584  * or the key file is corrupted, the function fails.
2585  *
2586  * @param h handle to the file sharing subsystem
2587  * @param name name of the namespace
2588  * @return handle to the namespace,
2589  *         NULL on error (i.e. invalid filename, non-existent filename)
2590  */
2591 struct GNUNET_FS_Namespace *
2592 GNUNET_FS_namespace_open_existing (struct GNUNET_FS_Handle *h, const char *name);
2593
2594
2595 /**
2596  * Rename a local namespace.
2597  *
2598  * @param h handle to the file sharing subsystem
2599  * @param old_name old name of the namespace
2600  * @param new_name new name of the namespace
2601  * @return GNUNET_OK on success, GNUNET_SYSERR on error (see errno for details)
2602  */
2603 int
2604 GNUNET_FS_namespace_rename (struct GNUNET_FS_Handle *h,
2605                             const char *old_name,
2606                             const char *new_name);
2607
2608
2609 /**
2610  * Duplicate a namespace handle.
2611  *
2612  * @param ns namespace handle
2613  * @return duplicated handle to the namespace
2614  */
2615 struct GNUNET_FS_Namespace *
2616 GNUNET_FS_namespace_dup (struct GNUNET_FS_Namespace *ns);
2617
2618
2619 /**
2620  * Get hash of the public key of a namespace.
2621  *
2622  * @param ns namespace
2623  * @param id buffer to store the key in
2624  * @return GNUNET_OK on success
2625  *         GNUNET_SYSERR on failure (contents of id remain intact)
2626  */
2627 int
2628 GNUNET_FS_namespace_get_public_identifier (struct GNUNET_FS_Namespace *ns,
2629                                            struct GNUNET_FS_PseudonymIdentifier *id);
2630
2631
2632 /**
2633  * Delete a namespace handle.  Can be used for a clean shutdown (free
2634  * memory) or also to freeze the namespace to prevent further
2635  * insertions by anyone.
2636  *
2637  * @param ns handle to the namespace that should be deleted / freed
2638  * @param freeze prevents future insertions; creating a namespace
2639  *        with the same name again will create a fresh namespace instead
2640  *
2641  * @return GNUNET_OK on success, GNUNET_SYSERR on error
2642  */
2643 int
2644 GNUNET_FS_namespace_delete (struct GNUNET_FS_Namespace *ns, int freeze);
2645
2646
2647 /**
2648  * Callback with information about local (!) namespaces.
2649  * Contains the names of the local namespace and the global
2650  * ID.
2651  *
2652  * @param cls closure
2653  * @param name human-readable identifier of the namespace
2654  * @param id identifier for the namespace
2655  */
2656 typedef void (*GNUNET_FS_NamespaceInfoProcessor) (void *cls, const char *name,
2657                                                   const struct GNUNET_FS_PseudonymIdentifier *id);
2658
2659
2660 /**
2661  * Build a list of all available local (!) namespaces The returned
2662  * names are only the nicknames since we only iterate over the local
2663  * namespaces.
2664  *
2665  * @param h handle to the file sharing subsystem
2666  * @param cb function to call on each known namespace
2667  * @param cb_cls closure for cb
2668  */
2669 void
2670 GNUNET_FS_namespace_list (struct GNUNET_FS_Handle *h,
2671                           GNUNET_FS_NamespaceInfoProcessor cb, void *cb_cls);
2672
2673
2674 /**
2675  * Function called on updateable identifiers.
2676  *
2677  * @param cls closure
2678  * @param last_id last identifier
2679  * @param last_uri uri used for the content published under the last_id
2680  * @param last_meta metadata associated with last_uri
2681  * @param next_id identifier that should be used for updates
2682  */
2683 typedef void (*GNUNET_FS_IdentifierProcessor) (void *cls, const char *last_id,
2684                                                const struct GNUNET_FS_Uri *
2685                                                last_uri,
2686                                                const struct
2687                                                GNUNET_CONTAINER_MetaData *
2688                                                last_meta, const char *next_id);
2689
2690
2691 /**
2692  * List all of the identifiers in the namespace for which we could
2693  * produce an update.  Namespace updates form a graph where each node
2694  * has a name.  Each node can have any number of URI/meta-data entries
2695  * which can each be linked to other nodes.  Cycles are possible.
2696  *
2697  * Calling this function with "next_id" NULL will cause the library to
2698  * call "ip" with a root for each strongly connected component of the
2699  * graph (a root being a node from which all other nodes in the Scc
2700  * are reachable).
2701  *
2702  * Calling this function with "next_id" being the name of a node will
2703  * cause the library to call "ip" with all children of the node.  Note
2704  * that cycles within an SCC are possible (including self-loops).
2705  *
2706  * @param ns namespace to inspect for updateable content
2707  * @param next_id ID to look for; use NULL to look for SCC roots
2708  * @param ip function to call on each updateable identifier
2709  * @param ip_cls closure for ip
2710  */
2711 void
2712 GNUNET_FS_namespace_list_updateable (struct GNUNET_FS_Namespace *ns,
2713                                      const char *next_id,
2714                                      GNUNET_FS_IdentifierProcessor ip,
2715                                      void *ip_cls);
2716
2717
2718 /**
2719  * Options for searching.  Compatible options
2720  * can be OR'ed together.
2721  */
2722 enum GNUNET_FS_SearchOptions
2723 {
2724     /**
2725      * No options (use defaults for everything).
2726      */
2727   GNUNET_FS_SEARCH_OPTION_NONE = 0,
2728
2729     /**
2730      * Only search the local host, do not search remote systems (no P2P)
2731      */
2732   GNUNET_FS_SEARCH_OPTION_LOOPBACK_ONLY = 1
2733 };
2734
2735
2736 /**
2737  * Start search for content.
2738  *
2739  * @param h handle to the file sharing subsystem
2740  * @param uri specifies the search parameters; can be
2741  *        a KSK URI or an SKS URI.
2742  * @param anonymity desired level of anonymity
2743  * @param options options for the search
2744  * @param cctx initial value for the client context
2745  * @return context that can be used to control the search
2746  */
2747 struct GNUNET_FS_SearchContext *
2748 GNUNET_FS_search_start (struct GNUNET_FS_Handle *h,
2749                         const struct GNUNET_FS_Uri *uri, uint32_t anonymity,
2750                         enum GNUNET_FS_SearchOptions options, void *cctx);
2751
2752
2753 /**
2754  * Pause search.
2755  *
2756  * @param sc context for the search that should be paused
2757  */
2758 void
2759 GNUNET_FS_search_pause (struct GNUNET_FS_SearchContext *sc);
2760
2761
2762 /**
2763  * Continue paused search.
2764  *
2765  * @param sc context for the search that should be resumed
2766  */
2767 void
2768 GNUNET_FS_search_continue (struct GNUNET_FS_SearchContext *sc);
2769
2770
2771 /**
2772  * Stop search for content.
2773  *
2774  * @param sc context for the search that should be stopped
2775  */
2776 void
2777 GNUNET_FS_search_stop (struct GNUNET_FS_SearchContext *sc);
2778
2779
2780 /**
2781  * Start download probes for the given search result.
2782  *
2783  * @param h file-sharing handle to use for the operation
2784  * @param uri URI to probe
2785  * @param meta meta data associated with the URI
2786  * @param client_info client info pointer to use for associated events
2787  * @param anonymity anonymity level to use for the probes
2788  * @return the search result handle to access the probe activity
2789  */
2790 struct GNUNET_FS_SearchResult *
2791 GNUNET_FS_probe (struct GNUNET_FS_Handle *h,
2792                  const struct GNUNET_FS_Uri *uri,
2793                  const struct GNUNET_CONTAINER_MetaData *meta,
2794                  void *client_info,
2795                  uint32_t anonymity);
2796
2797
2798 /**
2799  * Stop probe activity.  Must ONLY be used on values
2800  * returned from 'GNUNET_FS_probe'.
2801  *
2802  * @param sr search result to stop probing for (freed)
2803  * @return the value of the 'client_info' pointer
2804  */
2805 void *
2806 GNUNET_FS_probe_stop (struct GNUNET_FS_SearchResult *sr);
2807
2808
2809 /**
2810  * Options for downloading.  Compatible options
2811  * can be OR'ed together.
2812  */
2813 enum GNUNET_FS_DownloadOptions
2814 {
2815     /**
2816      * No options (use defaults for everything).
2817      */
2818   GNUNET_FS_DOWNLOAD_OPTION_NONE = 0,
2819
2820     /**
2821      * Only download from the local host, do not access remote systems (no P2P)
2822      */
2823   GNUNET_FS_DOWNLOAD_OPTION_LOOPBACK_ONLY = 1,
2824
2825     /**
2826      * Do a recursive download (that is, automatically trigger the
2827      * download of files in directories).
2828      */
2829   GNUNET_FS_DOWNLOAD_OPTION_RECURSIVE = 2,
2830
2831     /**
2832      * Do not append temporary data to
2833      * the target file (for the IBlocks).
2834      */
2835   GNUNET_FS_DOWNLOAD_NO_TEMPORARIES = 4,
2836
2837     /**
2838      * Internal option used to flag this download as a 'probe' for a
2839      * search result.  Impacts the priority with which the download is
2840      * run and causes signalling callbacks to be done differently.
2841      * Also, probe downloads are not serialized on suspension.  Normal
2842      * clients should not use this!
2843      */
2844   GNUNET_FS_DOWNLOAD_IS_PROBE = (1 << 31)
2845 };
2846
2847
2848
2849 /**
2850  * Download parts of a file.  Note that this will store
2851  * the blocks at the respective offset in the given file.  Also, the
2852  * download is still using the blocking of the underlying FS
2853  * encoding.  As a result, the download may *write* outside of the
2854  * given boundaries (if offset and length do not match the 32k FS
2855  * block boundaries). <p>
2856  *
2857  * The given range can be used to focus a download towards a
2858  * particular portion of the file (optimization), not to strictly
2859  * limit the download to exactly those bytes.
2860  *
2861  * @param h handle to the file sharing subsystem
2862  * @param uri the URI of the file (determines what to download); CHK or LOC URI
2863  * @param meta known metadata for the file (can be NULL)
2864  * @param filename where to store the file, maybe NULL (then no file is
2865  *        created on disk and data must be grabbed from the callbacks)
2866  * @param tempname where to store temporary file data, not used if filename is non-NULL;
2867  *        can be NULL (in which case we will pick a name if needed); the temporary file
2868  *        may already exist, in which case we will try to use the data that is there and
2869  *        if it is not what is desired, will overwrite it
2870  * @param offset at what offset should we start the download (typically 0)
2871  * @param length how many bytes should be downloaded starting at offset
2872  * @param anonymity anonymity level to use for the download
2873  * @param options various download options
2874  * @param cctx initial value for the client context for this download
2875  * @param parent parent download to associate this download with (use NULL
2876  *        for top-level downloads; useful for manually-triggered recursive downloads)
2877  * @return context that can be used to control this download
2878  */
2879 struct GNUNET_FS_DownloadContext *
2880 GNUNET_FS_download_start (struct GNUNET_FS_Handle *h,
2881                           const struct GNUNET_FS_Uri *uri,
2882                           const struct GNUNET_CONTAINER_MetaData *meta,
2883                           const char *filename, const char *tempname,
2884                           uint64_t offset, uint64_t length, uint32_t anonymity,
2885                           enum GNUNET_FS_DownloadOptions options, void *cctx,
2886                           struct GNUNET_FS_DownloadContext *parent);
2887
2888
2889 /**
2890  * Download parts of a file based on a search result.  The download
2891  * will be associated with the search result (and the association
2892  * will be preserved when serializing/deserializing the state).
2893  * If the search is stopped, the download will not be aborted but
2894  * be 'promoted' to a stand-alone download.
2895  *
2896  * As with the other download function, this will store
2897  * the blocks at the respective offset in the given file.  Also, the
2898  * download is still using the blocking of the underlying FS
2899  * encoding.  As a result, the download may *write* outside of the
2900  * given boundaries (if offset and length do not match the 32k FS
2901  * block boundaries). <p>
2902  *
2903  * The given range can be used to focus a download towards a
2904  * particular portion of the file (optimization), not to strictly
2905  * limit the download to exactly those bytes.
2906  *
2907  * @param h handle to the file sharing subsystem
2908  * @param sr the search result to use for the download (determines uri and
2909  *        meta data and associations)
2910  * @param filename where to store the file, maybe NULL (then no file is
2911  *        created on disk and data must be grabbed from the callbacks)
2912  * @param tempname where to store temporary file data, not used if filename is non-NULL;
2913  *        can be NULL (in which case we will pick a name if needed); the temporary file
2914  *        may already exist, in which case we will try to use the data that is there and
2915  *        if it is not what is desired, will overwrite it
2916  * @param offset at what offset should we start the download (typically 0)
2917  * @param length how many bytes should be downloaded starting at offset
2918  * @param anonymity anonymity level to use for the download
2919  * @param options various download options
2920  * @param cctx initial value for the client context for this download
2921  * @return context that can be used to control this download
2922  */
2923 struct GNUNET_FS_DownloadContext *
2924 GNUNET_FS_download_start_from_search (struct GNUNET_FS_Handle *h,
2925                                       struct GNUNET_FS_SearchResult *sr,
2926                                       const char *filename,
2927                                       const char *tempname, uint64_t offset,
2928                                       uint64_t length, uint32_t anonymity,
2929                                       enum GNUNET_FS_DownloadOptions options,
2930                                       void *cctx);
2931
2932
2933 /**
2934  * Stop a download (aborts if download is incomplete).
2935  *
2936  * @param dc handle for the download
2937  * @param do_delete delete files of incomplete downloads
2938  */
2939 void
2940 GNUNET_FS_download_stop (struct GNUNET_FS_DownloadContext *dc, int do_delete);
2941
2942
2943
2944 /* ******************** Directory API *********************** */
2945
2946
2947 #define GNUNET_FS_DIRECTORY_MIME  "application/gnunet-directory"
2948 #define GNUNET_FS_DIRECTORY_MAGIC "\211GND\r\n\032\n"
2949 #define GNUNET_FS_DIRECTORY_EXT   ".gnd"
2950
2951 /**
2952  * Does the meta-data claim that this is a directory?
2953  * Checks if the mime-type is that of a GNUnet directory.
2954  *
2955  * @return GNUNET_YES if it is, GNUNET_NO if it is not, GNUNET_SYSERR if
2956  *  we have no mime-type information (treat as 'GNUNET_NO')
2957  */
2958 int
2959 GNUNET_FS_meta_data_test_for_directory (const struct GNUNET_CONTAINER_MetaData
2960                                         *md);
2961
2962
2963 /**
2964  * Set the MIMETYPE information for the given
2965  * metadata to "application/gnunet-directory".
2966  *
2967  * @param md metadata to add mimetype to
2968  */
2969 void
2970 GNUNET_FS_meta_data_make_directory (struct GNUNET_CONTAINER_MetaData *md);
2971
2972
2973 /**
2974  * Suggest a filename based on given metadata.
2975  *
2976  * @param md given meta data
2977  * @return NULL if meta data is useless for suggesting a filename
2978  */
2979 char *
2980 GNUNET_FS_meta_data_suggest_filename (const struct GNUNET_CONTAINER_MetaData
2981                                       *md);
2982
2983
2984 /**
2985  * Function used to process entries in a directory.
2986  *
2987  * @param cls closure
2988  * @param filename name of the file in the directory
2989  * @param uri URI of the file
2990  * @param metadata metadata for the file; metadata for
2991  *        the directory if everything else is NULL/zero
2992  * @param length length of the available data for the file
2993  *           (of type size_t since data must certainly fit
2994  *            into memory; if files are larger than size_t
2995  *            permits, then they will certainly not be
2996  *            embedded with the directory itself).
2997  * @param data data available for the file (length bytes)
2998  */
2999 typedef void (*GNUNET_FS_DirectoryEntryProcessor) (void *cls,
3000                                                    const char *filename,
3001                                                    const struct GNUNET_FS_Uri *
3002                                                    uri,
3003                                                    const struct
3004                                                    GNUNET_CONTAINER_MetaData *
3005                                                    meta, size_t length,
3006                                                    const void *data);
3007
3008
3009 /**
3010  * Iterate over all entries in a directory.  Note that directories
3011  * are structured such that it is possible to iterate over the
3012  * individual blocks as well as over the entire directory.  Thus
3013  * a client can call this function on the buffer in the
3014  * GNUNET_FS_ProgressCallback.  Also, directories can optionally
3015  * include the contents of (small) files embedded in the directory
3016  * itself; for those files, the processor may be given the
3017  * contents of the file directly by this function.
3018  *
3019  * @param size number of bytes in data
3020  * @param data pointer to the beginning of the directory
3021  * @param offset offset of data in the directory
3022  * @param dep function to call on each entry
3023  * @param dep_cls closure for dep
3024  * @return GNUNET_OK if this could be a block in a directory,
3025  *         GNUNET_NO if this could be part of a directory (but not 100% OK)
3026  *         GNUNET_SYSERR if 'data' does not represent a directory
3027  */
3028 int
3029 GNUNET_FS_directory_list_contents (size_t size, const void *data,
3030                                    uint64_t offset,
3031                                    GNUNET_FS_DirectoryEntryProcessor dep,
3032                                    void *dep_cls);
3033
3034
3035 /**
3036  * Opaque handle to a directory builder.
3037  */
3038 struct GNUNET_FS_DirectoryBuilder;
3039
3040 /**
3041  * Create a directory builder.
3042  *
3043  * @param mdir metadata for the directory
3044  */
3045 struct GNUNET_FS_DirectoryBuilder *
3046 GNUNET_FS_directory_builder_create (const struct GNUNET_CONTAINER_MetaData
3047                                     *mdir);
3048
3049
3050 /**
3051  * Add an entry to a directory.
3052  *
3053  * @param bld directory to extend
3054  * @param uri uri of the entry (must not be a KSK)
3055  * @param md metadata of the entry
3056  * @param data raw data of the entry, can be NULL, otherwise
3057  *        data must point to exactly the number of bytes specified
3058  *        by the uri
3059  */
3060 void
3061 GNUNET_FS_directory_builder_add (struct GNUNET_FS_DirectoryBuilder *bld,
3062                                  const struct GNUNET_FS_Uri *uri,
3063                                  const struct GNUNET_CONTAINER_MetaData *md,
3064                                  const void *data);
3065
3066
3067 /**
3068  * Finish building the directory.  Frees the
3069  * builder context and returns the directory
3070  * in-memory.
3071  *
3072  * @param bld directory to finish
3073  * @param rsize set to the number of bytes needed
3074  * @param rdata set to the encoded directory
3075  * @return GNUNET_OK on success
3076  */
3077 int
3078 GNUNET_FS_directory_builder_finish (struct GNUNET_FS_DirectoryBuilder *bld,
3079                                     size_t * rsize, void **rdata);
3080
3081
3082 /* ******************** DirScanner API *********************** */
3083
3084 /**
3085  * Progress reasons of the directory scanner.
3086  */
3087 enum GNUNET_FS_DirScannerProgressUpdateReason
3088 {
3089
3090   /**
3091    * We've started processing a file or directory.
3092    */
3093   GNUNET_FS_DIRSCANNER_FILE_START = 0,
3094
3095   /**
3096    * We're having trouble accessing a file (soft-error); it will
3097    * be ignored.
3098    */
3099   GNUNET_FS_DIRSCANNER_FILE_IGNORED,
3100
3101   /**
3102    * We've found all files (in the pre-pass).
3103    */
3104   GNUNET_FS_DIRSCANNER_ALL_COUNTED,
3105
3106   /**
3107    * We've finished extracting meta data from a file.
3108    */
3109   GNUNET_FS_DIRSCANNER_EXTRACT_FINISHED,
3110
3111   /**
3112    * Last call to the progress function: we have finished scanning
3113    * the directory.
3114    */
3115   GNUNET_FS_DIRSCANNER_FINISHED,
3116
3117   /**
3118    * There was an internal error.  Application should abort the scan.
3119    */
3120   GNUNET_FS_DIRSCANNER_INTERNAL_ERROR
3121
3122 };
3123
3124
3125 /**
3126  * Function called over time as the directory scanner makes
3127  * progress on the job at hand.
3128  *
3129  * @param cls closure
3130  * @param filename which file we are making progress on
3131  * @param is_directory GNUNET_YES if this is a directory,
3132  *                     GNUNET_NO if this is a file
3133  *                     GNUNET_SYSERR if it is neither (or unknown)
3134  * @param reason kind of progress we are making
3135  */
3136 typedef void (*GNUNET_FS_DirScannerProgressCallback) (void *cls,
3137                                                       const char *filename,
3138                                                       int is_directory,
3139                                                       enum GNUNET_FS_DirScannerProgressUpdateReason reason);
3140
3141
3142 /**
3143  * A node of a directory tree (produced by dirscanner)
3144  */
3145 struct GNUNET_FS_ShareTreeItem
3146 {
3147   /**
3148    * This is a doubly-linked list
3149    */
3150   struct GNUNET_FS_ShareTreeItem *prev;
3151
3152   /**
3153    * This is a doubly-linked list
3154    */
3155   struct GNUNET_FS_ShareTreeItem *next;
3156
3157   /**
3158    * This is a doubly-linked tree
3159    * NULL for top-level entries.
3160    */
3161   struct GNUNET_FS_ShareTreeItem *parent;
3162
3163   /**
3164    * This is a doubly-linked tree
3165    * NULL for files and empty directories
3166    */
3167   struct GNUNET_FS_ShareTreeItem *children_head;
3168
3169   /**
3170    * This is a doubly-linked tree
3171    * NULL for files and empty directories
3172    */
3173   struct GNUNET_FS_ShareTreeItem *children_tail;
3174
3175   /**
3176    * Metadata for this file or directory
3177    */
3178   struct GNUNET_CONTAINER_MetaData *meta;
3179
3180   /**
3181    * Keywords for this file or directory (derived from metadata).
3182    */
3183   struct GNUNET_FS_Uri *ksk_uri;
3184
3185   /**
3186    * Name of the file/directory
3187    */
3188   char *filename;
3189
3190   /**
3191    * Base name of the file/directory.
3192    */
3193   char *short_filename;
3194
3195   /**
3196    * GNUNET_YES if this is a directory
3197    */
3198   int is_directory;
3199
3200 };
3201
3202
3203 /**
3204  * Opaqe handle to an asynchronous directory scanning activity.
3205  */
3206 struct GNUNET_FS_DirScanner;
3207
3208
3209 /**
3210  * Start a directory scanner.
3211  *
3212  * @param filename name of the directory to scan
3213  * @param disable_extractor GNUNET_YES to not to run libextractor on files (only build a tree)
3214  * @param ex if not NULL, must be a list of extra plugins for extractor
3215  * @param cb the callback to call when there are scanning progress messages
3216  * @param cb_cls closure for 'cb'
3217  * @return directory scanner object to be used for controlling the scanner
3218  */
3219 struct GNUNET_FS_DirScanner *
3220 GNUNET_FS_directory_scan_start (const char *filename,
3221                                 int disable_extractor,
3222                                 const char *ex,
3223                                 GNUNET_FS_DirScannerProgressCallback cb,
3224                                 void *cb_cls);
3225
3226
3227 /**
3228  * Abort the scan.    Must not be called from within the progress_callback
3229  * function.
3230  *
3231  * @param ds directory scanner structure
3232  */
3233 void
3234 GNUNET_FS_directory_scan_abort (struct GNUNET_FS_DirScanner *ds);
3235
3236
3237 /**
3238  * Obtain the result of the scan after the scan has signalled
3239  * completion.  Must not be called prior to completion.  The 'ds' is
3240  * freed as part of this call.
3241  *
3242  * @param ds directory scanner structure
3243  * @return the results of the scan (a directory tree)
3244  */
3245 struct GNUNET_FS_ShareTreeItem *
3246 GNUNET_FS_directory_scan_get_result (struct GNUNET_FS_DirScanner *ds);
3247
3248
3249 /**
3250  * Process a share item tree, moving frequent keywords up and
3251  * copying frequent metadata up.
3252  *
3253  * @param toplevel toplevel directory in the tree, returned by the scanner
3254  */
3255 void
3256 GNUNET_FS_share_tree_trim (struct GNUNET_FS_ShareTreeItem *toplevel);
3257
3258
3259 /**
3260  * Release memory of a share item tree.
3261  *
3262  * @param toplevel toplevel of the tree to be freed
3263  */
3264 void
3265 GNUNET_FS_share_tree_free (struct GNUNET_FS_ShareTreeItem *toplevel);
3266
3267
3268 #if 0                           /* keep Emacsens' auto-indent happy */
3269 {
3270 #endif
3271 #ifdef __cplusplus
3272 }
3273 #endif
3274
3275
3276 #endif