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 - review:
  21 * directory creation/inspection API
  22 * resume notifications
  23 * ProgressCallback: struct/union instead of tons of args?
  24 * download options (no temporary files -- what about no files at all?)
  25
  26 /**
  27  * @file include/gnunet_fs_service.h
  28  * @brief support for file-sharing via GNUnet
  29  * @author Christian Grothoff
  30  */
  31
  32 #ifndef GNUNET_FS_LIB_H
  33 #define GNUNET_FS_LIB_H
  34
  35 #include "gnunet_util_lib.h"
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #if 0                           /* keep Emacsens' auto-indent happy */
  41 }
  42 #endif
  43 #endif
  44
  45 /**
  46  * Version number of the implementation.
  47  * History:
  48  *
  49  * 1.x.x: initial version with triple GNUNET_hash and merkle tree
  50  * 2.x.x: root node with mime-type, filename and version number
  51  * 2.1.x: combined GNUNET_EC_ContentHashKey/3HASH encoding with 25:1 super-nodes
  52  * 2.2.x: with directories
  53  * 3.0.x: with namespaces
  54  * 3.1.x: with namespace meta-data
  55  * 3.2.x: with collections
  56  * 4.0.x: with expiration, variable meta-data, kblocks
  57  * 4.1.x: with new error and configuration handling
  58  * 5.0.x: with location URIs
  59  * 6.0.0: with support for OR in KSKs
  60  * 6.1.x: with simplified namespace support
  61  * 9.0.0: CPS-style integrated API
  62  */
  63 #define GNUNET_FS_VERSION 0x00090000
  64
  65 #define GNUNET_DIRECTORY_MIME  "application/gnunet-directory"
  66 #define GNUNET_DIRECTORY_MAGIC "\211GND\r\n\032\n"
  67 #define GNUNET_DIRECTORY_EXT   ".gnd"
  68
  69 /* URI API */
  70
  71 #define GNUNET_FS_URI_PREFIX      "gnunet://fs/"
  72 #define GNUNET_FS_SEARCH_INFIX    "ksk/"
  73 #define GNUNET_FS_SUBSPACE_INFIX  "sks/"
  74 #define GNUNET_FS_FILE_INFIX      "chk/"
  75 #define GNUNET_FS_LOCATION_INFIX  "loc/"
  76
  77 /**
  78  * Iterator over keywords
  79  *
  80  * @param cls closure
  81  * @param keyword the keyword
  82  * @param is_mandatory is the keyword mandatory (in a search)
  83  * @return GNUNET_OK to continue to iterate, GNUNET_SYSERR to abort
  84  */
  85 typedef int (*GNUNET_FS_KeywordIterator) (void *cls,
  86                                           const char *keyword,
  87                                           int is_mandatory);
  88
  89
  90 /**
  91  * Does the meta-data claim that this is a directory?
  92  * Checks if the mime-type is that of a GNUnet directory.
  93  *
  94  * @return GNUNET_YES if it is, GNUNET_NO if it is not, GNUNET_SYSERR if
  95  *  we have no mime-type information (treat as 'GNUNET_NO')
  96  */
  97 int
  98 GNUNET_FS_meta_data_test_for_directory (const struct GNUNET_CONTAINER_MetaData *md);
  99
 100
 101 /**
 102  * A URI (in internal representation).
 103  */
 104 struct GNUNET_FS_Uri;
 105
 106
 107 /**
 108  * Get a unique key from a URI.  This is for putting URIs
 109  * into HashMaps.  The key may change between FS implementations.
 110  *
 111  * @param uri uri to convert to a unique key
 112  * @param key wherer to store the unique key
 113  */
 114 void
 115 GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri,
 116                       GNUNET_HashCode * key);
 117
 118 /**
 119  * Convert a URI to a UTF-8 String.
 120  *
 121  * @param uri uri to convert to a string
 122  * @return the UTF-8 string
 123  */
 124 char *
 125 GNUNET_FS_uri_to_string (const struct GNUNET_FS_Uri *uri);
 126
 127 /**
 128  * Convert keyword URI to a human readable format
 129  * (i.e. the search query that was used in the first place)
 130  *
 131  * @param uri ksk uri to convert to a string
 132  * @return string with the keywords
 133  */
 134 char *
 135 GNUNET_FS_ksk_uri_ksk_to_string_fancy (const struct GNUNET_FS_Uri *uri);
 136
 137 /**
 138  * Convert a UTF-8 String to a URI.
 139  *
 140  * @param uri string to parse
 141  * @param emsg where to store the parser error message (if any)
 142  * @return NULL on error
 143  */
 144 struct GNUNET_FS_Uri *
 145 GNUNET_FS_uri_parse (const char *uri,
 146                      char **emsg);
 147
 148 /**
 149  * Free URI.
 150  *
 151  * @param uri uri to free
 152  */
 153 void
 154 GNUNET_FS_uri_destroy (struct GNUNET_FS_Uri *uri);
 155
 156
 157 /**
 158  * How many keywords are ANDed in this keyword URI?
 159  *
 160  * @param uri ksk uri to get the number of keywords from
 161  * @return 0 if this is not a keyword URI
 162  */
 163 unsigned int
 164 GNUNET_FS_uri_ksk_get_keyword_count (const struct GNUNET_FS_Uri *uri);
 165
 166
 167 /**
 168  * Iterate over all keywords in this keyword URI.
 169  *
 170  * @param uri ksk uri to get the keywords from
 171  * @param iterator function to call on each keyword
 172  * @param iterator_cls closure for iterator
 173  * @return -1 if this is not a keyword URI, otherwise number of
 174  *   keywords iterated over until iterator aborted
 175  */
 176 int
 177 GNUNET_FS_uri_ksk_get_keywords (const struct GNUNET_FS_Uri *uri,
 178                                 GNUNET_FS_KeywordIterator iterator,
 179                                 void *iterator_cls);
 180
 181
 182 /**
 183  * Obtain the identity of the peer offering the data
 184  *
 185  * @param uri the location URI to inspect
 186  * @param peer where to store the identify of the peer (presumably) offering the content
 187  * @return GNUNET_SYSERR if this is not a location URI, otherwise GNUNET_OK
 188  */
 189 int
 190 GNUNET_FS_uri_loc_get_peer_identity (const struct GNUNET_FS_Uri *uri,
 191                                      struct GNUNET_PeerIdentity * peer);
 192
 193
 194 /**
 195  * Obtain the URI of the content itself.
 196  *
 197  * @param uri location URI to get the content URI from
 198  * @return NULL if argument is not a location URI
 199  */
 200 struct GNUNET_FS_Uri *
 201 GNUNET_FS_uri_loc_get_uri (const struct GNUNET_FS_Uri *uri);
 202
 203
 204 /**
 205  * Construct a location URI (this peer will be used for the location).
 206  *
 207  * @param baseURI content offered by the sender
 208  * @param cfg configuration information (used to find our hostkey)
 209  * @param expiration_time how long will the content be offered?
 210  * @return the location URI, NULL on error
 211  */
 212 struct GNUNET_FS_Uri *
 213 GNUNET_FS_uri_loc_create (const struct GNUNET_FS_Uri *baseUri,
 214                           struct GNUNET_CONFIGURATION_Handle *cfg,
 215                           struct GNUNET_TIME_Absolute expiration_time);
 216
 217
 218 /**
 219  * Duplicate URI.
 220  *
 221  * @param uri the URI to duplicate
 222  * @return copy of the URI
 223  */
 224 struct GNUNET_FS_Uri *
 225 GNUNET_FS_uri_dup (const struct GNUNET_FS_Uri *uri);
 226
 227
 228 /**
 229  * Create an FS URI from a single user-supplied string of keywords.
 230  * The string is broken up at spaces into individual keywords.
 231  * Keywords that start with "+" are mandatory.  Double-quotes can
 232  * be used to prevent breaking up strings at spaces (and also
 233  * to specify non-mandatory keywords starting with "+").
 234  *
 235  * Keywords must contain a balanced number of double quotes and
 236  * double quotes can not be used in the actual keywords (for
 237  * example, the string '""foo bar""' will be turned into two
 238  * "OR"ed keywords 'foo' and 'bar', not into '"foo bar"'.
 239  *
 240  * @param keywords the keyword string
 241  * @return an FS URI for the given keywords, NULL
 242  *  if keywords is not legal (i.e. empty).
 243  */
 244 struct GNUNET_FS_Uri *
 245 GNUNET_FS_uri_ksk_create (const char *keywords);
 246
 247
 248 /**
 249  * Create an FS URI from a user-supplied command line of keywords.
 250  * Arguments should start with "+" to indicate mandatory
 251  * keywords.
 252  *
 253  * @param argc number of keywords
 254  * @param argv keywords (double quotes are not required for
 255  *             keywords containing spaces; however, double
 256  *             quotes are required for keywords starting with
 257  *             "+"); there is no mechanism for having double
 258  *             quotes in the actual keywords (if the user
 259  *             did specifically specify double quotes, the
 260  *             caller should convert each double quote
 261  *             into two single quotes).
 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_from_args (unsigned int argc,
 267                                     const char **argv);
 268
 269
 270 /**
 271  * Test if two URIs are equal.
 272  *
 273  * @param u1 one of the URIs
 274  * @param u2 the other URI
 275  * @return GNUNET_YES if the URIs are equal
 276  */
 277 int
 278 GNUNET_FS_uri_test_equal (const struct GNUNET_FS_Uri *u1,
 279                           const struct GNUNET_FS_Uri *u2);
 280
 281
 282 /**
 283  * Is this a namespace URI?
 284  *
 285  * @param uri the uri to check
 286  * @return GNUNET_YES if this is an SKS uri
 287  */
 288 int
 289 GNUNET_FS_uri_test_sks (const struct GNUNET_FS_Uri *uri);
 290
 291
 292 /**
 293  * Get the ID of a namespace from the given
 294  * namespace URI.
 295  *
 296  * @param uri the uri to get the namespace ID from
 297  * @param nsid where to store the ID of the namespace
 298  * @return GNUNET_OK on success
 299  */
 300 int
 301 GNUNET_FS_uri_sks_get_namespace (const struct GNUNET_FS_Uri *uri,
 302                                  GNUNET_HashCode * nsid);
 303
 304
 305 /**
 306  * Get the content identifier of an SKS URI.
 307  *
 308  * @param uri the sks uri
 309  * @return NULL on error (not a valid SKS URI)
 310  */
 311 char *
 312 GNUNET_FS_uri_sks_get_content_id (const struct GNUNET_FS_Uri *uri);
 313
 314
 315 /**
 316  * Convert namespace URI to a human readable format
 317  * (using the namespace description, if available).
 318  *
 319  * @param cfg configuration to use
 320  * @param uri SKS uri to convert
 321  * @return NULL on error (not an SKS URI)
 322  */
 323 char *
 324 GNUNET_FS_uri_sks_to_string_fancy (struct GNUNET_CONFIGURATION_Handle *cfg,
 325                                    const struct GNUNET_FS_Uri *uri);
 326
 327
 328 /**
 329  * Is this a keyword URI?
 330  *
 331  * @param uri the uri
 332  * @return GNUNET_YES if this is a KSK uri
 333  */
 334 int
 335 GNUNET_FS_uri_test_ksk (const struct GNUNET_FS_Uri *uri);
 336
 337
 338 /**
 339  * Is this a file (or directory) URI?
 340  *
 341  * @param uri the uri to check
 342  * @return GNUNET_YES if this is a CHK uri
 343  */
 344 int
 345 GNUNET_FS_uri_test_chk (const struct GNUNET_FS_Uri *uri);
 346
 347
 348 /**
 349  * What is the size of the file that this URI
 350  * refers to?
 351  *
 352  * @param uri the CHK URI to inspect
 353  * @return size of the file as specified in the CHK URI
 354  */
 355 uint64_t
 356 GNUNET_FS_uri_chk_get_file_size (const struct GNUNET_FS_Uri *uri);
 357
 358
 359 /**
 360  * Is this a location URI?
 361  *
 362  * @param uri the uri to check
 363  * @return GNUNET_YES if this is a LOC uri
 364  */
 365 int
 366 GNUNET_FS_uri_test_loc (const struct GNUNET_FS_Uri *uri);
 367
 368
 369 /**
 370  * Construct a keyword-URI from meta-data (take all entries
 371  * in the meta-data and construct one large keyword URI
 372  * that lists all keywords that can be found in the meta-data).
 373  * @deprecated
 374  */
 375 struct GNUNET_FS_Uri *
 376 GNUNET_FS_uri_ksk_create_from_meta_data (const struct GNUNET_MetaData *md);
 377
 378
 379 /**
 380  * Command-line option parser function that allows the user
 381  * to specify one or more '-k' options with keywords.  Each
 382  * specified keyword will be added to the URI.  A pointer to
 383  * the URI must be passed as the "scls" argument.
 384  *
 385  * @param ctx command line processor context
 386  * @param scls must be of type "struct GNUNET_FS_Uri **"
 387  * @param option name of the option (typically 'k')
 388  * @param value command line argument given
 389  * @return GNUNET_OK on success
 390  */
 391 int
 392 GNUNET_FS_getopt_configure_set_keywords (GNUNET_GETOPT_CommandLineProcessorContext* ctx,
 393                                          void *scls,
 394                                          const char *option,
 395                                          const char *value);
 396
 397
 398 /**
 399  * Command-line option parser function that allows the user to specify
 400  * one or more '-m' options with metadata.  Each specified entry of
 401  * the form "type=value" will be added to the metadata.  A pointer to
 402  * the metadata must be passed as the "scls" argument.
 403  *
 404  * @param ctx command line processor context
 405  * @param scls must be of type "struct GNUNET_MetaData **"
 406  * @param option name of the option (typically 'k')
 407  * @param value command line argument given
 408  * @return GNUNET_OK on success
 409  */
 410 int
 411 GNUNET_FS_getopt_configure_set_metadata (GNUNET_GETOPT_CommandLineProcessorContext* ctx,
 412                                          void *scls,
 413                                          const char *option,
 414                                          const char *value);
 415
 416
 417
 418 /* ************************* sharing API ***************** */
 419
 420
 421 /**
 422  * Possible status codes used in the callback for the
 423  * various file-sharing operations.  On each file (or search),
 424  * the callback is guaranteed to be called once with "START"
 425  * and once with STOPPED; calls with PROGRESS, ERROR or COMPLETED
 426  * are optional and depend on the circumstances; parent operations
 427  * will be STARTED before child-operations and STOPPED after
 428  * their respective child-operations.  START and STOP signals
 429  * are typically generated either due to explicit client requests
 430  * or because of suspend/resume operations.
 431  */
 432 enum GNUNET_FS_Status
 433 {
 434   /**
 435    * Notification that we have started to share a file structure.
 436    */
 437   GNUNET_FS_STATUS_SHARE_START,
 438
 439   /**
 440    * Notification that we have resumed sharing a file structure.
 441    */
 442   GNUNET_FS_STATUS_SHARE_RESUME,
 443
 444   /**
 445    * Notification that we have suspended sharing a file structure.
 446    */
 447   GNUNET_FS_STATUS_SHARE_SUSPEND,
 448
 449   /**
 450    * Notification that we are making progress sharing a file structure.
 451    */
 452   GNUNET_FS_STATUS_SHARE_PROGRESS,
 453
 454   /**
 455    * Notification that an error was encountered  sharing a file structure.
 456    * The application will continue to receive resume/suspend events for
 457    * this structure until "GNUNET_FS_share_stop" is called.
 458    */
 459   GNUNET_FS_STATUS_SHARE_ERROR,
 460
 461   /**
 462    * Notification that we completed sharing a file structure.
 463    * The application will continue to receive resume/suspend events for
 464    * this structure until "GNUNET_FS_share_stop" is called.
 465    */
 466   GNUNET_FS_STATUS_SHARE_COMPLETED,
 467   GNUNET_FS_STATUS_SHARE_STOPPED,
 468   GNUNET_FS_STATUS_DOWNLOAD_START,
 469   GNUNET_FS_STATUS_DOWNLOAD_RESUME,
 470   GNUNET_FS_STATUS_DOWNLOAD_SUSPEND,
 471   GNUNET_FS_STATUS_DOWNLOAD_PROGRESS,
 472   GNUNET_FS_STATUS_DOWNLOAD_ERROR,
 473   GNUNET_FS_STATUS_DOWNLOAD_COMPLETED,
 474   GNUNET_FS_STATUS_DOWNLOAD_STOPPED,
 475   GNUNET_FS_STATUS_SEARCH_START,
 476   GNUNET_FS_STATUS_SEARCH_RESUME,
 477   GNUNET_FS_STATUS_SEARCH_RESUME_RESULT,
 478   GNUNET_FS_STATUS_SEARCH_SUSPEND,
 479   GNUNET_FS_STATUS_SEARCH_RESULT,
 480   GNUNET_FS_STATUS_SEARCH_UPDATE,
 481   GNUNET_FS_STATUS_SEARCH_ERROR,
 482   GNUNET_FS_STATUS_SEARCH_STOPPED,
 483   GNUNET_FS_STATUS_UNINDEX_START,
 484   GNUNET_FS_STATUS_UNINDEX_RESUME,
 485   GNUNET_FS_STATUS_UNINDEX_SUSPEND,
 486   GNUNET_FS_STATUS_UNINDEX_PROGRESS,
 487   GNUNET_FS_STATUS_UNINDEX_ERROR,
 488   GNUNET_FS_STATUS_UNINDEX_STOPPED,
 489   GNUNET_FS_STATUS_NAMESPACE_DISCOVERED
 490 };
 491
 492
 493 /**
 494  * Notification of FS to a client about the progress of an
 495  * operation.  Callbacks of this type will be used for uploads,
 496  * downloads and searches.  Some of the arguments depend a bit
 497  * in their meaning on the context in which the callback is used.
 498  *
 499  * @param cls closure
 500  * @param cctx client-context (for the next progress call
 501  *        for this operation; should be set to NULL for
 502  *        SUSPEND and STOPPED events)
 503  * @param ctx location where the callback can store a context pointer
 504  *        to keep track of things for this specific operation
 505  * @param pctx context pointer set by the callback for the parent operation
 506  *        (NULL if there is no parent operation); for a search result,
 507  *        the actual search is the parent and the individual search results
 508  *        are the children (multiple calls for the same search result can
 509  *        be used whenever availability/certainty or metadata values change)
 510  * @param filename name of the file that this update is about, NULL for
 511  *        searches
 512  * @param availability value between 0 and 100 indicating how likely
 513  *        we think it is that this search result is actually available
 514  *        in the network (or, in the case of a download, that the download
 515  *        will complete); always 100 for uploads; percentage of blocks
 516  *        that could be unindexed so far for unindexing operations
 517  *        (indicates how many blocks in the indexed file changed in
 518  *        the meantime)
 519  * @param certainty how certain are we that the availability value is
 520  *        actually correct?  certainty is also between 0 and 100.
 521  * @param fsize number of bytes that will need to be processed (for this file)
 522  * @param completed number of bytes that have been processed (for this file)
 523  * @param offset offset of the data of buffer in the file
 524  * @param eta absolute estimated time for the completion of the operation
 525  * @param uri pointer to CHK URI for search results and downloads; pointer
 526  *        to KSK uri for uploads; client can modify KSK uri to change the
 527  *        set of keywords that will be used
 528  * @param meta metadata for search results and downloads (NULL for downloads
 529  *        if no metadata is available); can be modified for uploads to change
 530  *        metadata that will be used
 531  * @param bsize number of bytes in the buffer
 532  * @param buffer pointer to the last bytes processed; will be a plaintext
 533  *        buffer for files (with content downloaded or uploaded) and
 534  *        NULL when searching; points to an error message of bsize bytes
 535  *        if this callback is used to signal an error
 536  * @return GNUNET_SYSERR to abort the overall operation; GNUNET_NO to
 537  *        stop this specific operation (do not share this file or skip
 538  *        this download; GNUNET_NO has no meaning for search results);
 539  *        GNUNET_YES to continue processing as usual
 540  * @deprecated (use 2-arg function getting union argument instead)
 541  */
 542 typedef int (*GNUNET_FS_ProgressCallback)
 543   (void *cls,
 544    void **cctx,
 545    const struct GNUNET_FS_ProgressInfo *info);
 546
 547
 548    void **ctx,
 549    void *pctx,
 550    const char *filename,
 551    enum GNUNET_FS_Status status,
 552    float availability,
 553    float certainty,
 554    uint64_t fsize,
 555    uint64_t completed,
 556    uint64_t offset, struct GNUNET_TIME_Absolute eta,
 557    struct GNUNET_FS_Uri **uri,
 558    struct GNUNET_CONTAINER_MetaData *meta,
 559    size_t bsize, const void *buffer);
 560
 561
 562
 563 /**
 564  * Handle to one of our namespaces.
 565  */
 566 struct GNUNET_FS_Namespace;
 567
 568
 569 /**
 570  * Handle for controlling an upload.
 571  */
 572 struct GNUNET_FS_ShareContext;
 573
 574
 575 /**
 576  * Handle for controlling an unindexing operation.
 577  */
 578 struct GNUNET_FS_UnindexContext;
 579
 580
 581 /**
 582  * Handle for controlling a search.
 583  */
 584 struct GNUNET_FS_SearchContext;
 585
 586
 587 /**
 588  * Context for controlling a download.
 589  */
 590 struct GNUNET_FS_DownloadContext;
 591
 592
 593 /**
 594  * Handle for detail information about a file that is being shared.
 595  * Specifies metadata, keywords, how to get the contents of the file
 596  * (i.e. data-buffer in memory, filename on disk) and other options.
 597  */
 598 struct GNUNET_FS_FileInformation;
 599
 600
 601 /**
 602  * Argument given to the progress callback with
 603  * information about what is going on.
 604  */
 605 struct GNUNET_FS_ProgressInfo
 606 {
 607
 608   /**
 609    * Values that depend on the event type.
 610    */
 611   union {
 612
 613     /**
 614      * Values for all "GNUNET_FS_STATUS_SHARE_*" events.
 615      */
 616     struct {
 617
 618       /**
 619        * Context for controlling the upload.
 620        */
 621       struct GNUNET_FS_ShareContext *sc;
 622
 623       /**
 624        * Information about the file that is being shared.
 625        */
 626       const struct GNUNET_FS_FileInformation *fi;
 627
 628       /**
 629        * Client context pointer (set the last time
 630        * by the client for this operation; initially
 631        * NULL on START/RESUME events).
 632        */
 633       void *cctx;
 634
 635       /**
 636        * Client context pointer for the parent operation
 637        * (if this is a file in a directory or a subdirectory).
 638        */
 639       void *pctx;
 640
 641       /**
 642        * How large is the file overall?  For directories,
 643        * this is only the size of the directory itself,
 644        * not of the other files contained within the
 645        * directory.
 646        */
 647       uint64_t size;
 648
 649       /**
 650        * At what time do we expect to finish the upload?
 651        * (will be a value in the past for completed
 652        * uploads).
 653        */
 654       struct GNUNET_TIME_Absolute eta;
 655
 656       /**
 657        * How long has this upload been actively running
 658        * (excludes times where the upload was suspended).
 659        */
 660       struct GNUNET_TIME_Relative duration;
 661
 662       /**
 663        * How many bytes have we completed?
 664        */
 665       uint64_t completed;
 666
 667       /**
 668        * What anonymity level is used for this upload?
 669        */
 670       unsigned int anonymity;
 671
 672       /**
 673        * Additional values for specific events.
 674        */
 675       union {
 676
 677         /**
 678          * These values are only valid for
 679          * GNUNET_FS_STATUS_SHARE_PROGRESS events.
 680          */
 681         struct {
 682
 683           /**
 684            * Data block we just published.
 685            */
 686           const void *data;
 687
 688           /**
 689            * At what offset in the file is "data"?
 690            */
 691           uint64_t offset;
 692
 693           /**
 694            * Length of the data block.
 695            */
 696           uint64_t data_len;
 697
 698         } progress;
 699
 700         /**
 701          * These values are only valid for
 702          * GNUNET_FS_STATUS_SHARE_RESUME events.
 703          */
 704         struct {
 705
 706           /**
 707            * Error message, NULL if no error was encountered so far.
 708            */
 709           const char *message;
 710
 711         } resume;
 712
 713         /**
 714          * These values are only valid for
 715          * GNUNET_FS_STATUS_SHARE_ERROR events.
 716          */
 717         struct {
 718
 719           /**
 720            * Error message, never NULL.
 721            */
 722           const char *message;
 723
 724         } error;
 725
 726       } specifics;
 727
 728     } share;
 729
 730
 731     /**
 732      * Values for all "GNUNET_FS_STATUS_DOWNLOAD_*" events.
 733      */
 734     struct {
 735
 736       /**
 737        * Context for controlling the download.
 738        */
 739       struct GNUNET_FS_DownloadContext *dc;
 740
 741       /**
 742        * Client context pointer (set the last time
 743        * by the client for this operation; initially
 744        * NULL on START/RESUME events).
 745        */
 746       void *cctx;
 747
 748       /**
 749        * Client context pointer for the parent operation
 750        * (if this is a file in a directory or a subdirectory).
 751        */
 752       void *pctx;
 753
 754       /**
 755        * URI used for this download.
 756        */
 757       const struct GNUNET_FS_Uri *uri;
 758
 759       /**
 760        * How large is the file overall?  For directories,
 761        * this is only the size of the directory itself,
 762        * not of the other files contained within the
 763        * directory.
 764        */
 765       uint64_t size;
 766
 767       /**
 768        * At what time do we expect to finish the download?
 769        * (will be a value in the past for completed
 770        * uploads).
 771        */
 772       struct GNUNET_TIME_Absolute eta;
 773
 774       /**
 775        * How long has this download been active?
 776        */
 777       struct GNUNET_TIME_Relative duration;
 778
 779       /**
 780        * How many bytes have we completed?
 781        */
 782       uint64_t completed;
 783
 784       /**
 785        * What anonymity level is used for this download?
 786        */
 787       unsigned int anonymity;
 788
 789       /**
 790        * Additional values for specific events.
 791        */
 792       union {
 793
 794         /**
 795          * These values are only valid for
 796          * GNUNET_FS_STATUS_DOWNLOAD_PROGRESS events.
 797          */
 798         struct {
 799
 800           /**
 801            * Data block we just obtained.
 802            */
 803           const void *data;
 804
 805           /**
 806            * At what offset in the file is "data"?
 807            */
 808           uint64_t offset;
 809
 810           /**
 811            * Length of the data block.
 812            */
 813           uint64_t data_len;
 814
 815           /**
 816            * Amount of trust we offered to get the block.
 817            */
 818           unsigned int trust_offered;
 819
 820         } progress;
 821
 822         /**
 823          * These values are only valid for
 824          * GNUNET_FS_STATUS_DOWNLOAD_START events.
 825          */
 826         struct {
 827
 828           /**
 829            * Known metadata for the download.
 830            */
 831           const struct GNUNET_MetaData *meta;
 832
 833         } start;
 834
 835         /**
 836          * These values are only valid for
 837          * GNUNET_FS_STATUS_DOWNLOAD_RESUME events.
 838          */
 839         struct {
 840
 841           /**
 842            * Known metadata for the download.
 843            */
 844           const struct GNUNET_MetaData *meta;
 845
 846           /**
 847            * Error message, NULL if we have not encountered any error yet.
 848            */
 849           const char *message;
 850
 851         } resume;
 852
 853         /**
 854          * These values are only valid for
 855          * GNUNET_FS_STATUS_DOWNLOAD_ERROR events.
 856          */
 857         struct {
 858
 859           /**
 860            * Error message.
 861            */
 862           const char *message;
 863
 864         } error;
 865
 866       } specifics;
 867
 868     } download;
 869
 870     /**
 871      * Values for all "GNUNET_FS_STATUS_SEARCH_*" events.
 872      */
 873     struct {
 874
 875       /**
 876        * Context for controlling the search, NULL for
 877        * searches that were not explicitly triggered
 878        * by the client (i.e., searches for updates in
 879        * namespaces).
 880        */
 881       struct GNUNET_FS_SearchContext *sc;
 882
 883       /**
 884        * Client context pointer (set the last time by the client for
 885        * this operation; initially NULL on START/RESUME events).  Note
 886        * that this value can only be set on START/RESUME; setting
 887        * "cctx" on RESULT/RESUME_RESULT will actually update the
 888        * private context for "UPDATE" events.
 889        */
 890       void *cctx;
 891
 892       /**
 893        * Client parent-context pointer; NULL for top-level searches,
 894        * non-NULL for automatically triggered searches for updates in
 895        * namespaces.
 896        */
 897       void *pctx;
 898
 899       /**
 900        * What query is used for this search
 901        * (list of keywords or SKS identifier).
 902        */
 903       const struct GNUNET_FS_Uri *query;
 904
 905       /**
 906        * How long has this search been actively running
 907        * (excludes times where the search was paused or
 908        * suspended).
 909        */
 910       struct GNUNET_TIME_Relative duration;
 911
 912       /**
 913        * What anonymity level is used for this search?
 914        */
 915       unsigned int anonymity;
 916
 917       /**
 918        * How much trust have we been offering for this search
 919        * so far?
 920        */
 921       unsigned int trust_offered;
 922
 923       /**
 924        * Additional values for specific events.
 925        */
 926       union {
 927
 928         /**
 929          * These values are only valid for
 930          * GNUNET_FS_STATUS_SEARCH_RESULT events.
 931          */
 932         struct {
 933
 934           /**
 935            * Metadata for the search result.
 936            */
 937           const struct GNUNET_MetaData *meta;
 938
 939           /**
 940            * URI for the search result.
 941            */
 942           const struct GNUNET_FS_Uri *uri;
 943
 944         } result;
 945
 946         /**
 947          * These values are only valid for
 948          * GNUNET_FS_STATUS_SEARCH_RESUME_RESULT events.
 949          */
 950         struct {
 951
 952           /**
 953            * Metadata for the search result.
 954            */
 955           const struct GNUNET_MetaData *meta;
 956
 957           /**
 958            * URI for the search result.
 959            */
 960           const struct GNUNET_FS_Uri *uri;
 961
 962           /**
 963            * Current availability rank (negative:
 964            * unavailable, positive: available)
 965            */
 966           int availability_rank;
 967
 968           /**
 969            * On how many total queries is the given
 970            * availability_rank based?
 971            */
 972           unsigned int availabiliy_certainty;
 973
 974           /**
 975            * Updated applicability rank (the larger,
 976            * the better the result fits the search
 977            * criteria).
 978            */
 979           unsigned int applicabiliy_rank;
 980
 981         } resume_result;
 982
 983         /**
 984          * These values are only valid for
 985          * GNUNET_FS_STATUS_SEARCH_UPDATE events.
 986          */
 987         struct {
 988
 989           /**
 990            * Private context set for for this result
 991            * during the "RESULT" event.
 992            */
 993           void *cctx;
 994
 995           /**
 996            * Metadata for the search result.
 997            */
 998           const struct GNUNET_MetaData *meta;
 999
1000           /**
1001            * URI for the search result.
1002            */
1003           const struct GNUNET_FS_Uri *uri;
1004
1005           /**
1006            * Current availability rank (negative:
1007            * unavailable, positive: available)
1008            */
1009           int availability_rank;
1010
1011           /**
1012            * On how many total queries is the given
1013            * availability_rank based?
1014            */
1015           unsigned int availabiliy_certainty;
1016
1017           /**
1018            * Updated applicability rank (the larger,
1019            * the better the result fits the search
1020            * criteria).
1021            */
1022           unsigned int applicabiliy_rank;
1023
1024         } update;
1025
1026         /**
1027          * These values are only valid for
1028          * GNUNET_FS_STATUS_SEARCH_RESUME events.
1029          */
1030         struct {
1031
1032           /**
1033            * Error message, NULL if we have not encountered any error yet.
1034            */
1035           const char *message;
1036
1037           /**
1038            * Is this search currently paused?
1039            */
1040           int is_paused;
1041
1042         } resume;
1043
1044         /**
1045          * These values are only valid for
1046          * GNUNET_FS_STATUS_SEARCH_ERROR events.
1047          */
1048         struct {
1049
1050           /**
1051            * Error message.
1052            */
1053           const char *message;
1054
1055         } error;
1056
1057       } specifics;
1058
1059     } search;
1060
1061     /**
1062      * Values for all "GNUNET_FS_STATUS_UNINDEX_*" events.
1063      */
1064     struct {
1065
1066       /**
1067        * Context for controlling the unindexing.
1068        */
1069       struct GNUNET_FS_UnindexContext *uc;
1070
1071       /**
1072        * Client context pointer (set the last time
1073        * by the client for this operation; initially
1074        * NULL on START/RESUME events).
1075        */
1076       void *cctx;
1077
1078       /**
1079        * Name of the file that is being unindexed.
1080        */
1081       const char *filename;
1082
1083       /**
1084        * How large is the file overall?
1085        */
1086       uint64_t size;
1087
1088       /**
1089        * At what time do we expect to finish unindexing?
1090        * (will be a value in the past for completed
1091        * unindexing opeations).
1092        */
1093       struct GNUNET_TIME_Absolute eta;
1094
1095       /**
1096        * How long has this upload been actively running
1097        * (excludes times where the upload was suspended).
1098        */
1099       struct GNUNET_TIME_Relative duration;
1100
1101       /**
1102        * How many bytes have we completed?
1103        */
1104       uint64_t completed;
1105
1106       /**
1107        * Additional values for specific events.
1108        */
1109       union {
1110
1111         /**
1112          * These values are only valid for
1113          * GNUNET_FS_STATUS_UNINDEX_PROGRESS events.
1114          */
1115         struct {
1116
1117           /**
1118            * Data block we just unindexed.
1119            */
1120           const void *data;
1121
1122           /**
1123            * At what offset in the file is "data"?
1124            */
1125           uint64_t offset;
1126
1127           /**
1128            * Length of the data block.
1129            */
1130           uint64_t data_len;
1131
1132         } progress;
1133
1134         /**
1135          * These values are only valid for
1136          * GNUNET_FS_STATUS_UNINDEX_RESUME events.
1137          */
1138         struct {
1139
1140           /**
1141            * Error message, NULL if we have not encountered any error yet.
1142            */
1143           const char *message;
1144
1145         } resume;
1146
1147         /**
1148          * These values are only valid for
1149          * GNUNET_FS_STATUS_UNINDEX_ERROR events.
1150          */
1151         struct {
1152
1153           /**
1154            * Error message.
1155            */
1156           const char *message;
1157
1158         } error;
1159
1160       } specifics;
1161
1162     } unindex;
1163
1164
1165     /**
1166      * Values for all "GNUNET_FS_STATUS_NAMESPACE_*" events.
1167      */
1168     struct {
1169
1170       /**
1171        * Handle to the namespace (NULL if it is not a local
1172        * namespace).
1173        */
1174       struct GNUNET_FS_Namespace *ns;
1175
1176       /**
1177        * Short, human-readable name of the namespace.
1178        */
1179       const char *name;
1180
1181       /**
1182        * Root identifier for the namespace, can be NULL.
1183        */
1184       const char *root;
1185
1186       /**
1187        * Metadata for the namespace.
1188        */
1189       const struct GNUNET_CONTAINER_MetaData *meta;
1190
1191       /**
1192        * Hash-identifier for the namespace.
1193        */
1194       struct GNUNET_HashCode id;
1195
1196     } namespace;
1197
1198   } value;
1199
1200   /**
1201    * Specific status code (determines the event type).
1202    */
1203   enum GNUNET_FS_Status status;
1204
1205 };
1206
1207
1208 /**
1209  * Handle to the file-sharing service.
1210  */
1211 struct GNUNET_FS_Handle;
1212
1213
1214 /**
1215  * Setup a connection to the file-sharing service.
1216  *
1217  * @param sched scheduler to use
1218  * @param cfg configuration to use
1219  * @param client_name unique identifier for this client
1220  * @param upcb function to call to notify about FS actions
1221  * @param upcb_cls closure for upcb
1222  */
1223 struct GNUNET_FS_Handle *
1224 GNUNET_FS_start (struct GNUNET_SCHEDULER_Handle *sched,
1225                  struct GNUNET_CONFIGURATION_Handle *cfg,
1226                  const char *client_name,
1227                  GNUNET_FS_ProgressCallback upcb,
1228                  void *upcb_cls);
1229
1230
1231 /**
1232  * Close our connection with the file-sharing service.
1233  * The callback given to GNUNET_FS_start will no longer be
1234  * called after this function returns.
1235  *
1236  * @param h handle that was returned from GNUNET_FS_start
1237  */
1238 void
1239 GNUNET_FS_stop (struct GNUNET_FS_Handle *h);
1240
1241 /**
1242  * Create an entry for a file in a share-structure.
1243  *
1244  * @param filename name of the file or directory to share
1245  * @param meta metadata for the file
1246  * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
1247  *                GNUNET_SYSERR for simulation
1248  * @param anonymity what is the desired anonymity level for sharing?
1249  * @param priority what is the priority for OUR node to
1250  *   keep this file available?  Use 0 for maximum anonymity and
1251  *   minimum reliability...
1252  * @param expirationTime when should this content expire?
1253  * @return share structure entry for the file
1254  */
1255 struct GNUNET_FS_FileInformation *
1256 GNUNET_FS_file_information_create (const char *filename,
1257                                    const struct GNUNET_CONTAINER_MetaData *meta,
1258                                    int do_index,
1259                                    unsigned int anonymity,
1260                                    unsigned int priority,
1261                                    struct GNUNET_TIME_Absolute expirationTime);
1262
1263 // FIXME: broaden API to include directory creation,
1264 // introspection, modification, auto-creation, etc.
1265
1266
1267 /**
1268  * Destroy share-structure.
1269  */
1270 void
1271 GNUNET_FS_file_information_destroy (struct GNUNET_FS_FileInformation *fi);
1272
1273
1274 /**
1275  * Share a file or directory.
1276  *
1277  * @param h handle to the file sharing subsystem
1278  * @param ctx initial value to use for the '*ctx'
1279  *        in the callback (for the GNUNET_FS_STATUS_SHARE_START event).
1280  * @param fi information about the file or directory structure to share
1281  * @param namespace namespace to share the file in, NULL for no namespace
1282  * @param nid identifier to use for the shared content in the namespace
1283  *        (can be NULL, must be NULL if namespace is NULL)
1284  * @param nuid update-identifier that will be used for future updates
1285  *        (can be NULL, must be NULL if namespace or nid is NULL)
1286  * @return context that can be used to control the share operation
1287  */
1288 struct GNUNET_FS_ShareContext *
1289 GNUNET_FS_share_start (struct GNUNET_FS_Handle *h,
1290                        void *ctx,
1291                        const struct GNUNET_FS_FileInformation *fi,
1292                        struct GNUNET_FS_Namespace *namespace
1293                        const char *nid,
1294                        const char *nuid);
1295
1296
1297 /**
1298  * Stop an upload.  Will abort incomplete uploads (but
1299  * not remove blocks that have already been shared) or
1300  * simply clean up the state for completed uploads.
1301  *
1302  * @param sc context for the upload to stop
1303  */
1304 void
1305 GNUNET_FS_share_stop (struct GNUNET_FS_ShareContext *sc);
1306
1307
1308 /**
1309  * Type of a function called by "GNUNET_FS_get_indexed_files".
1310  *
1311  * @param cls closure
1312  * @param filename the name of the file
1313  * @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort
1314  */
1315 typedef int (*GNUNET_FS_FileProcessor) (void *cls,
1316                                         const char *filename);
1317
1318
1319 /**
1320  * Iterate over all indexed files.
1321  *
1322  * @param h handle to the file sharing subsystem
1323  * @param iterator function to call on each indexed file
1324  * @param iterator_cls closure for iterator
1325  */
1326 void
1327 GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h,
1328                              GNUNET_FS_FileProcessor iterator,
1329                              void *iterator_cls);
1330
1331
1332 /**
1333  * Unindex a file.
1334  *
1335  * @param h handle to the file sharing subsystem
1336  * @param filename file to unindex
1337  * @return NULL on error, otherwise handle
1338  */
1339 struct GNUNET_FS_UnindexContext *
1340 GNUNET_FS_unindex (struct GNUNET_FS_Handle *h,
1341                    const char *filename);
1342
1343
1344 /**
1345  * Clean up after completion of an unindex operation.
1346  *
1347  * @param uc handle
1348  */
1349 void
1350 GNUNET_FS_unindex_stop (struct GNUNET_FS_UnindexContext *uc);
1351
1352
1353 /**
1354  * Publish an advertismement for a namespace.
1355  *
1356  * @param h handle to the file sharing subsystem
1357  * @param namespace handle for the namespace that should be advertised
1358  * @param meta meta-data for the namespace advertisement
1359  * @param anonymity for the namespace advertismement
1360  * @param priority for the namespace advertisement
1361  * @param expiration for the namespace advertisement
1362  * @param advertisementURI the keyword (!) URI to advertise the
1363  *        namespace under (we will create a GNUNET_EC_KNBlock)
1364  * @param rootEntry name of the root entry in the namespace (for
1365  *        the namespace advertisement)
1366  *
1367  * @return uri of the advertisement
1368  */
1369 struct GNUNET_FS_Uri *
1370 GNUNET_FS_namespace_advertise (struct GNUNET_FS_Handle *h,
1371                                struct GNUNET_FS_Namespace *namespace,
1372                                const struct GNUNET_MetaData *meta,
1373                                unsigned int anonymity,
1374                                unsigned int priority,
1375                                struct GNUNET_TIME_Absolute expiration,
1376                                const struct GNUNET_FS_Uri *advertisementURI,
1377                                const char *rootEntry);
1378
1379
1380 /**
1381  * Create a namespace with the given name; if one already
1382  * exists, return a handle to the existing namespace.
1383  *
1384  * @param h handle to the file sharing subsystem
1385  * @param name name to use for the namespace
1386  * @return handle to the namespace, NULL on error
1387  */
1388 struct GNUNET_FS_Namespace *
1389 GNUNET_FS_namespace_create (struct GNUNET_FS_Handle *h,
1390                             const char *name);
1391
1392
1393 /**
1394  * Delete a namespace handle.  Can be used for a clean shutdown (free
1395  * memory) or also to freeze the namespace to prevent further
1396  * insertions by anyone.
1397  *
1398  * @param namespace handle to the namespace that should be deleted / freed
1399  * @param freeze prevents future insertions; creating a namespace
1400  *        with the same name again will create a fresh namespace instead
1401  *
1402  * @return GNUNET_OK on success, GNUNET_SYSERR on error
1403  */
1404 int
1405 GNUNET_FS_namespace_delete (struct GNUNET_FS_Namespace *namespace,
1406                             int freeze);
1407
1408
1409 /**
1410  * Callback with information about local (!) namespaces.
1411  * Contains the names of the local namespace and the global
1412  * ID.
1413  *
1414  * @param cls closure
1415  * @param name human-readable identifier of the namespace
1416  * @param id hash identifier for the namespace
1417  */
1418 typedef void (*GNUNET_FS_NamespaceInfoProcessor) (void *cls,
1419                                                   const char *name,
1420                                                   const GNUNET_HashCode *id);
1421
1422
1423 /**
1424  * Build a list of all available local (!) namespaces The returned
1425  * names are only the nicknames since we only iterate over the local
1426  * namespaces.
1427  *
1428  * @param h handle to the file sharing subsystem
1429  * @param cb function to call on each known namespace
1430  * @param cb_cls closure for cb
1431  * @return GNUNET_SYSERR on error, otherwise the number of pseudonyms in list
1432  */
1433 int
1434 GNUNET_FS_namespace_list (struct GNUNET_FS_Handle *h,
1435                           GNUNET_FS_NamespaceProcessor cb,
1436                           void *cb_cls);
1437
1438
1439 /**
1440  * Function called on updateable identifiers.
1441  *
1442  * @param cls closure
1443  * @param last_id last identifier
1444  * @param last_uri uri used for the content published under the last_id
1445  * @param last_meta metadata associated with last_uri
1446  * @param next_id identifier that should be used for updates
1447  */
1448 typedef void
1449 (*GNUNET_FS_IdentifierProcessor)(void *cls,
1450                                  const char *last_id,
1451                                  const struct GNUNET_FS_Uri *last_uri,
1452                                  const struct GNUNET_CONTAINER_MetaData *last_meta,
1453                                  const char *next_id);
1454
1455
1456 /**
1457  * List all of the identifiers in the namespace for
1458  * which we could produce an update.
1459  *
1460  * @param namespace namespace to inspect for updateable content
1461  * @param ip function to call on each updateable identifier
1462  * @param ip_cls closure for ip
1463  */
1464 void
1465 GNUNET_FS_namespace_list_updateable (struct GNUNET_FS_Namespace *namespace,
1466                                      GNUNET_FS_IdentifierProcessor ip,
1467                                      void *ip_cls);
1468
1469
1470 /**
1471  * Start search for content.
1472  *
1473  * @param h handle to the file sharing subsystem
1474  * @param uri specifies the search parameters; can be
1475  *        a KSK URI or an SKS URI.
1476  * @param anonymity desired level of anonymity
1477  * @return context that can be used to control the search
1478  */
1479 struct GNUNET_FS_SearchContext *
1480 GNUNET_FS_search_start (struct GNUNET_FS_Handle *h,
1481                         const struct GNUNET_FS_Uri *uri,
1482                         unsigned int anonymity);
1483
1484
1485 /**
1486  * Pause search.
1487  *
1488  * @param sc context for the search that should be paused
1489  */
1490 void
1491 GNUNET_FS_search_pause (struct GNUNET_FS_SearchContext *sc);
1492
1493
1494 /**
1495  * Resume paused search.
1496  *
1497  * @param sc context for the search that should be resumed
1498  */
1499 void
1500 GNUNET_FS_search_resume (struct GNUNET_FS_SearchContext *sc);
1501
1502
1503 /**
1504  * Stop search for content.
1505  *
1506  * @param sc context for the search that should be stopped
1507  */
1508 void
1509 GNUNET_FS_search_stop (struct GNUNET_FS_SearchContext *sc);
1510
1511
1512 /**
1513  * Download parts of a file.  Note that this will store
1514  * the blocks at the respective offset in the given file.  Also, the
1515  * download is still using the blocking of the underlying FS
1516  * encoding.  As a result, the download may *write* outside of the
1517  * given boundaries (if offset and length do not match the 32k FS
1518  * block boundaries). <p>
1519  *
1520  * This function should be used to focus a download towards a
1521  * particular portion of the file (optimization), not to strictly
1522  * limit the download to exactly those bytes.
1523  *
1524  * @param h handle to the file sharing subsystem
1525  * @param uri the URI of the file (determines what to download); CHK or LOC URI
1526  * @param filename where to store the file, maybe NULL (then no file is
1527  *        created on disk and data must be grabbed from the callbacks)
1528  * @param offset at what offset should we start the download (typically 0)
1529  * @param length how many bytes should be downloaded starting at offset
1530  * @param anonymity anonymity level to use for the download
1531  * @param no_temporaries set to GNUNET_YES to disallow generation of temporary files
1532  * @param recursive should this be a recursive download (useful for directories
1533  *        to automatically trigger download of files in the directories)
1534  * @param parent parent download to associate this download with (use NULL
1535  *        for top-level downloads; useful for manually-triggered recursive downloads)
1536  * @return context that can be used to control this download
1537  */
1538 struct GNUNET_FS_DownloadContext *
1539 GNUNET_FS_file_download_start (struct GNUNET_FS_Handle *h,
1540                                const struct GNUNET_FS_Uri *uri,
1541                                const char *filename,
1542                                unsigned long long offset,
1543                                unsigned long long length,
1544                                unsigned int anonymity,
1545                                int no_temporaries,
1546                                int recursive,
1547                                struct GNUNET_FS_DownloadContext *parent);
1548
1549
1550 /**
1551  * Stop a download (aborts if download is incomplete).
1552  *
1553  * @param rm handle for the download
1554  * @param do_delete delete files of incomplete downloads
1555  */
1556 void
1557 GNUNET_FS_file_download_stop (struct GNUNET_FS_DownloadContext *rm,
1558                               int do_delete);
1559
1560
1561 /**
1562  * Iterate over all entries in a directory.  Note that directories
1563  * are structured such that it is possible to iterate over the
1564  * individual blocks as well as over the entire directory.  Thus
1565  * a client can call this function on the buffer in the
1566  * GNUNET_FS_ProgressCallback.
1567  *
1568  * @param size number of bytes in data
1569  * @param data pointer to the beginning of the directory
1570  * @param offset offset of data in the directory
1571  * @param spcb function to call on each entry
1572  * @param spcb_cls closure for spcb
1573  */
1574 void
1575 GNUNET_FS_directory_list_contents (size_t size,
1576                                    const void *data,
1577                                    uint64_t offset,
1578                                    GNUNET_FS_SearchResultProcessor spcb,
1579                                    void *spcb_cls);
1580
1581
1582 /**
1583  * Create a directory.
1584  *
1585  * @param data pointer set to the beginning of the directory
1586  * @param len set to number of bytes in data
1587  * @param count number of entries in uris and metaDatas
1588
1589  * @param uris URIs of the files in the directory
1590  * @param metaDatas meta-data for the files (must match
1591  *        respective values at same offset in in uris)
1592  * @param meta meta-data for the directory.  The meta entry
1593  *        is extended with the mime-type for a GNUnet directory.
1594
1595  * @return GNUNET_OK on success, GNUNET_SYSERR on error
1596  * @deprecated (not powerful enough?)
1597  */
1598 int
1599 GNUNET_FS_directory_create (char **data,
1600                             uint64_t *len,
1601                             unsigned int count,
1602                             const GNUNET_FS_FileInfo * fis,
1603                             struct GNUNET_MetaData *meta);
1604
1605
1606 /**
1607  * Initialize collection.
1608  *
1609  * @param h handle to the file sharing subsystem
1610  * @param namespace namespace to use for the collection
1611  * @return GNUNET_OK on success, GNUNET_SYSERR if another
1612  *         namespace is already set for our collection
1613  */
1614 int
1615 GNUNET_FS_collection_start (struct GNUNET_FS_Handle *h,
1616                             struct GNUNET_FS_Namespace *namespace);
1617
1618
1619 /**
1620  * Stop collection.
1621  *
1622  * @param h handle to the file sharing subsystem
1623  * @return GNUNET_OK on success, GNUNET_SYSERR if no collection is active
1624  */
1625 int
1626 GNUNET_FS_collection_stop (struct GNUNET_FS_Handle *h);
1627
1628
1629 /**
1630  * Are we using a collection?
1631  *
1632  * @param h handle to the file sharing subsystem
1633  * @return NULL if there is no collection,
1634  */
1635 struct GNUNET_FS_Namespace *
1636 GNUNET_FS_collection_get(struct GNUNET_FS_Handle *h);
1637
1638
1639 /**
1640  * Publish an update of the current collection information to the
1641  * network now.  The function has no effect if the collection has not
1642  * changed since the last publication.  If we are currently not
1643  * collecting, this function does nothing.
1644  *
1645  * @param h handle to the file sharing subsystem
1646  */
1647 void GNUNET_FS_collection_publish (struct GNUNET_FS_Handle *h);
1648
1649
1650 /**
1651  * If we are currently building a collection, publish the given file
1652  * information in that collection.  If we are currently not
1653  * collecting, this function does nothing.
1654  *
1655  * @param h handle to the file sharing subsystem
1656  * @param uri uri to add to the collection
1657  * @param meta metadata for the uri
1658  */
1659 void GNUNET_FS_collection_add (const struct GNUNET_FS_Handle *h,
1660                                const struct GNUNET_FS_Uri *uri,
1661                                const struct GNUNET_CONTAINER_MetaData *meta);
1662
1663
1664
1665 #if 0                           /* keep Emacsens' auto-indent happy */
1666 {
1667 #endif
1668 #ifdef __cplusplus
1669 }
1670 #endif
1671
1672
1673 #endif