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