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