src/include/gnunet_fs_service.h

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