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