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 * unindex start/stop API
  23 * resume notifications
  24 * ProgressCallback: struct/union instead of tons of args?
  25 * download options (no temporary files -- what about no files at all?)
  26
  27 /**
  28  * @file include/gnunet_fs_service.h
  29  * @brief support for file-sharing via GNUnet
  30  * @author Christian Grothoff
  31  */
  32
  33 #ifndef GNUNET_FS_LIB_H
  34 #define GNUNET_FS_LIB_H
  35
  36 #include "gnunet_util_lib.h"
  37
  38 #ifdef __cplusplus
  39 extern "C"
  40 {
  41 #if 0                           /* keep Emacsens' auto-indent happy */
  42 }
  43 #endif
  44 #endif
  45
  46 /**
  47  * Version number of the implementation.
  48  * History:
  49  *
  50  * 1.x.x: initial version with triple GNUNET_hash and merkle tree
  51  * 2.x.x: root node with mime-type, filename and version number
  52  * 2.1.x: combined GNUNET_EC_ContentHashKey/3HASH encoding with 25:1 super-nodes
  53  * 2.2.x: with directories
  54  * 3.0.x: with namespaces
  55  * 3.1.x: with namespace meta-data
  56  * 3.2.x: with collections
  57  * 4.0.x: with expiration, variable meta-data, kblocks
  58  * 4.1.x: with new error and configuration handling
  59  * 5.0.x: with location URIs
  60  * 6.0.0: with support for OR in KSKs
  61  * 6.1.x: with simplified namespace support
  62  * 9.0.0: CPS-style integrated API
  63  */
  64 #define GNUNET_FS_VERSION 0x00090000
  65
  66 #define GNUNET_DIRECTORY_MIME  "application/gnunet-directory"
  67 #define GNUNET_DIRECTORY_MAGIC "\211GND\r\n\032\n"
  68 #define GNUNET_DIRECTORY_EXT   ".gnd"
  69
  70 /* URI API */
  71
  72 #define GNUNET_FS_URI_PREFIX      "gnunet://fs/"
  73 #define GNUNET_FS_SEARCH_INFIX    "ksk/"
  74 #define GNUNET_FS_SUBSPACE_INFIX  "sks/"
  75 #define GNUNET_FS_FILE_INFIX      "chk/"
  76 #define GNUNET_FS_LOCATION_INFIX  "loc/"
  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 /**
  92  * Does the meta-data claim that this is a directory?
  93  * Checks if the mime-type is that of a GNUnet directory.
  94  *
  95  * @return GNUNET_YES if it is, GNUNET_NO if it is not, GNUNET_SYSERR if
  96  *  we have no mime-type information (treat as 'GNUNET_NO')
  97  */
  98 int
  99 GNUNET_FS_meta_data_test_for_directory (const struct GNUNET_CONTAINER_MetaData *md);
 100
 101
 102 /**
 103  * A URI (in internal representation).
 104  */
 105 struct GNUNET_FS_Uri;
 106
 107
 108 /**
 109  * Get a unique key from a URI.  This is for putting URIs
 110  * into HashMaps.  The key may change between FS implementations.
 111  *
 112  * @param uri uri to convert to a unique key
 113  * @param key wherer to store the unique key
 114  */
 115 void
 116 GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri,
 117                       GNUNET_HashCode * key);
 118
 119 /**
 120  * Convert a URI to a UTF-8 String.
 121  *
 122  * @param uri uri to convert to a string
 123  * @return the UTF-8 string
 124  */
 125 char *
 126 GNUNET_FS_uri_to_string (const struct GNUNET_FS_Uri *uri);
 127
 128 /**
 129  * Convert keyword URI to a human readable format
 130  * (i.e. the search query that was used in the first place)
 131  *
 132  * @param uri ksk uri to convert to a string
 133  * @return string with the keywords
 134  */
 135 char *
 136 GNUNET_FS_ksk_uri_ksk_to_string_fancy (const struct GNUNET_FS_Uri *uri);
 137
 138 /**
 139  * Convert a UTF-8 String to a URI.
 140  *
 141  * @param uri string to parse
 142  * @param emsg where to store the parser error message (if any)
 143  * @return NULL on error
 144  */
 145 struct GNUNET_FS_Uri *
 146 GNUNET_FS_uri_parse (const char *uri,
 147                      char **emsg);
 148
 149 /**
 150  * Free URI.
 151  *
 152  * @param uri uri to free
 153  */
 154 void
 155 GNUNET_FS_uri_destroy (struct GNUNET_FS_Uri *uri);
 156
 157
 158 /**
 159  * How many keywords are ANDed in this keyword URI?
 160  *
 161  * @param uri ksk uri to get the number of keywords from
 162  * @return 0 if this is not a keyword URI
 163  */
 164 unsigned int
 165 GNUNET_FS_uri_ksk_get_keyword_count (const struct GNUNET_FS_Uri *uri);
 166
 167
 168 /**
 169  * Iterate over all keywords in this keyword URI.
 170  *
 171  * @param uri ksk uri to get the keywords from
 172  * @param iterator function to call on each keyword
 173  * @param iterator_cls closure for iterator
 174  * @return -1 if this is not a keyword URI, otherwise number of
 175  *   keywords iterated over until iterator aborted
 176  */
 177 int
 178 GNUNET_FS_uri_ksk_get_keywords (const struct GNUNET_FS_Uri *uri,
 179                                 GNUNET_FS_KeywordIterator iterator,
 180                                 void *iterator_cls);
 181
 182
 183 /**
 184  * Obtain the identity of the peer offering the data
 185  *
 186  * @param uri the location URI to inspect
 187  * @param peer where to store the identify of the peer (presumably) offering the content
 188  * @return GNUNET_SYSERR if this is not a location URI, otherwise GNUNET_OK
 189  */
 190 int
 191 GNUNET_FS_uri_loc_get_peer_identity (const struct GNUNET_FS_Uri *uri,
 192                                      struct GNUNET_PeerIdentity * peer);
 193
 194
 195 /**
 196  * Obtain the URI of the content itself.
 197  *
 198  * @param uri location URI to get the content URI from
 199  * @return NULL if argument is not a location URI
 200  */
 201 struct GNUNET_FS_Uri *
 202 GNUNET_FS_uri_loc_get_uri (const struct GNUNET_FS_Uri *uri);
 203
 204
 205 /**
 206  * Construct a location URI (this peer will be used for the location).
 207  *
 208  * @param baseURI content offered by the sender
 209  * @param cfg configuration information (used to find our hostkey)
 210  * @param expiration_time how long will the content be offered?
 211  * @return the location URI, NULL on error
 212  */
 213 struct GNUNET_FS_Uri *
 214 GNUNET_FS_uri_loc_create (const struct GNUNET_FS_Uri *baseUri,
 215                           struct GNUNET_CONFIGURATION_Handle *cfg,
 216                           struct GNUNET_TIME_Absolute expiration_time);
 217
 218
 219 /**
 220  * Duplicate URI.
 221  *
 222  * @param uri the URI to duplicate
 223  * @return copy of the URI
 224  */
 225 struct GNUNET_FS_Uri *
 226 GNUNET_FS_uri_dup (const struct GNUNET_FS_Uri *uri);
 227
 228
 229 /**
 230  * Create an FS URI from a single user-supplied string of keywords.
 231  * The string is broken up at spaces into individual keywords.
 232  * Keywords that start with "+" are mandatory.  Double-quotes can
 233  * be used to prevent breaking up strings at spaces (and also
 234  * to specify non-mandatory keywords starting with "+").
 235  *
 236  * Keywords must contain a balanced number of double quotes and
 237  * double quotes can not be used in the actual keywords (for
 238  * example, the string '""foo bar""' will be turned into two
 239  * "OR"ed keywords 'foo' and 'bar', not into '"foo bar"'.
 240  *
 241  * @param keywords the keyword string
 242  * @return an FS URI for the given keywords, NULL
 243  *  if keywords is not legal (i.e. empty).
 244  */
 245 struct GNUNET_FS_Uri *
 246 GNUNET_FS_uri_ksk_create (const char *keywords);
 247
 248
 249 /**
 250  * Create an FS URI from a user-supplied command line of keywords.
 251  * Arguments should start with "+" to indicate mandatory
 252  * keywords.
 253  *
 254  * @param argc number of keywords
 255  * @param argv keywords (double quotes are not required for
 256  *             keywords containing spaces; however, double
 257  *             quotes are required for keywords starting with
 258  *             "+"); there is no mechanism for having double
 259  *             quotes in the actual keywords (if the user
 260  *             did specifically specify double quotes, the
 261  *             caller should convert each double quote
 262  *             into two single quotes).
 263  * @return an FS URI for the given keywords, NULL
 264  *  if keywords is not legal (i.e. empty).
 265  */
 266 struct GNUNET_FS_Uri *
 267 GNUNET_FS_uri_ksk_create_from_args (unsigned int argc,
 268                                     const char **argv);
 269
 270
 271 /**
 272  * Test if two URIs are equal.
 273  *
 274  * @param u1 one of the URIs
 275  * @param u2 the other URI
 276  * @return GNUNET_YES if the URIs are equal
 277  */
 278 int
 279 GNUNET_FS_uri_test_equal (const struct GNUNET_FS_Uri *u1,
 280                           const struct GNUNET_FS_Uri *u2);
 281
 282
 283 /**
 284  * Is this a namespace URI?
 285  *
 286  * @param uri the uri to check
 287  * @return GNUNET_YES if this is an SKS uri
 288  */
 289 int
 290 GNUNET_FS_uri_test_sks (const struct GNUNET_FS_Uri *uri);
 291
 292
 293 /**
 294  * Get the ID of a namespace from the given
 295  * namespace URI.
 296  *
 297  * @param uri the uri to get the namespace ID from
 298  * @param nsid where to store the ID of the namespace
 299  * @return GNUNET_OK on success
 300  */
 301 int
 302 GNUNET_FS_uri_sks_get_namespace (const struct GNUNET_FS_Uri *uri,
 303                                  GNUNET_HashCode * nsid);
 304
 305
 306 /**
 307  * Get the content identifier of an SKS URI.
 308  *
 309  * @param uri the sks uri
 310  * @return NULL on error (not a valid SKS URI)
 311  */
 312 char *
 313 GNUNET_FS_uri_sks_get_content_id (const struct GNUNET_FS_Uri *uri);
 314
 315
 316 /**
 317  * Convert namespace URI to a human readable format
 318  * (using the namespace description, if available).
 319  *
 320  * @param cfg configuration to use
 321  * @param uri SKS uri to convert
 322  * @return NULL on error (not an SKS URI)
 323  */
 324 char *
 325 GNUNET_FS_uri_sks_to_string_fancy (struct GNUNET_CONFIGURATION_Handle *cfg,
 326                                    const struct GNUNET_FS_Uri *uri);
 327
 328
 329 /**
 330  * Is this a keyword URI?
 331  *
 332  * @param uri the uri
 333  * @return GNUNET_YES if this is a KSK uri
 334  */
 335 int
 336 GNUNET_FS_uri_test_ksk (const struct GNUNET_FS_Uri *uri);
 337
 338
 339 /**
 340  * Is this a file (or directory) URI?
 341  *
 342  * @param uri the uri to check
 343  * @return GNUNET_YES if this is a CHK uri
 344  */
 345 int
 346 GNUNET_FS_uri_test_chk (const struct GNUNET_FS_Uri *uri);
 347
 348
 349 /**
 350  * What is the size of the file that this URI
 351  * refers to?
 352  *
 353  * @param uri the CHK URI to inspect
 354  * @return size of the file as specified in the CHK URI
 355  */
 356 uint64_t
 357 GNUNET_FS_uri_chk_get_file_size (const struct GNUNET_FS_Uri *uri);
 358
 359
 360 /**
 361  * Is this a location URI?
 362  *
 363  * @param uri the uri to check
 364  * @return GNUNET_YES if this is a LOC uri
 365  */
 366 int
 367 GNUNET_FS_uri_test_loc (const struct GNUNET_FS_Uri *uri);
 368
 369
 370 /**
 371  * Construct a keyword-URI from meta-data (take all entries
 372  * in the meta-data and construct one large keyword URI
 373  * that lists all keywords that can be found in the meta-data).
 374  * @deprecated
 375  */
 376 struct GNUNET_FS_Uri *
 377 GNUNET_FS_uri_ksk_create_from_meta_data (const struct GNUNET_MetaData *md);
 378
 379
 380 /**
 381  * Command-line option parser function that allows the user
 382  * to specify one or more '-k' options with keywords.  Each
 383  * specified keyword will be added to the URI.  A pointer to
 384  * the URI must be passed as the "scls" argument.
 385  *
 386  * @param ctx command line processor context
 387  * @param scls must be of type "struct GNUNET_FS_Uri **"
 388  * @param option name of the option (typically 'k')
 389  * @param value command line argument given
 390  * @return GNUNET_OK on success
 391  */
 392 int
 393 GNUNET_FS_getopt_configure_set_keywords (GNUNET_GETOPT_CommandLineProcessorContext* ctx,
 394                                          void *scls,
 395                                          const char *option,
 396                                          const char *value);
 397
 398
 399 /**
 400  * Command-line option parser function that allows the user to specify
 401  * one or more '-m' options with metadata.  Each specified entry of
 402  * the form "type=value" will be added to the metadata.  A pointer to
 403  * the metadata must be passed as the "scls" argument.
 404  *
 405  * @param ctx command line processor context
 406  * @param scls must be of type "struct GNUNET_MetaData **"
 407  * @param option name of the option (typically 'k')
 408  * @param value command line argument given
 409  * @return GNUNET_OK on success
 410  */
 411 int
 412 GNUNET_FS_getopt_configure_set_metadata (GNUNET_GETOPT_CommandLineProcessorContext* ctx,
 413                                          void *scls,
 414                                          const char *option,
 415                                          const char *value);
 416
 417
 418
 419 /* ************************* sharing API ***************** */
 420
 421
 422 /**
 423  * Possible status codes used in the callback for the
 424  * various file-sharing operations.  On each file (or search),
 425  * the callback is guaranteed to be called once with "START"
 426  * and once with STOPPED; calls with PROGRESS, ERROR or COMPLETED
 427  * are optional and depend on the circumstances; parent operations
 428  * will be STARTED before child-operations and STOPPED after
 429  * their respective child-operations.  START and STOP signals
 430  * are typically generated either due to explicit client requests
 431  * or because of suspend/resume operations.
 432  */
 433 enum GNUNET_FS_Status
 434 {
 435   GNUNET_FS_STATUS_UPLOAD_START,
 436   GNUNET_FS_STATUS_UPLOAD_PROGRESS,
 437   GNUENT_FS_STATUS_UPLOAD_ERROR,
 438   GNUNET_FS_STATUS_UPLOAD_COMPLETED,
 439   GNUNET_FS_STATUS_UPLOAD_STOPPED,
 440   GNUNET_FS_STATUS_DOWNLOAD_START,
 441   GNUNET_FS_STATUS_DOWNLOAD_PROGRESS,
 442   GNUNET_FS_STATUS_DOWNLOAD_ERROR,
 443   GNUNET_FS_STATUS_DOWNLOAD_COMPLETED,
 444   GNUNET_FS_STATUS_DOWNLOAD_STOPPED,
 445   GNUNET_FS_STATUS_SEARCH_START,
 446   GNUNET_FS_STATUS_SEARCH_PROGRESS,
 447   GNUNET_FS_STATUS_SEARCH_ERROR,
 448   GNUNET_FS_STATUS_SEARCH_STOPPED,
 449   GNUNET_FS_STATUS_UNINDEX_START,
 450   GNUNET_FS_STATUS_UNINDEX_PROGRESS,
 451   GNUNET_FS_STATUS_UNINDEX_ERROR,
 452   GNUNET_FS_STATUS_UNINDEX_STOPPED
 453 };
 454
 455
 456 /**
 457  * Notification of FS to a client about the progress of an
 458  * operation.  Callbacks of this type will be used for uploads,
 459  * downloads and searches.  Some of the arguments depend a bit
 460  * in their meaning on the context in which the callback is used.
 461  *
 462  * @param cls closure
 463  * @param ctx location where the callback can store a context pointer
 464  *        to keep track of things for this specific operation
 465  * @param pctx context pointer set by the callback for the parent operation
 466  *        (NULL if there is no parent operation); for a search result,
 467  *        the actual search is the parent and the individual search results
 468  *        are the children (multiple calls for the same search result can
 469  *        be used whenever availability/certainty or metadata values change)
 470  * @param filename name of the file that this update is about, NULL for
 471  *        searches
 472  * @param status specific status code
 473  * @param availability value between 0 and 100 indicating how likely
 474  *        we think it is that this search result is actually available
 475  *        in the network (or, in the case of a download, that the download
 476  *        will complete); always 100 for uploads; percentage of blocks
 477  *        that could be unindexed so far for unindexing operations
 478  *        (indicates how many blocks in the indexed file changed in
 479  *        the meantime)
 480  * @param certainty how certain are we that the availability value is
 481  *        actually correct?  certainty is also between 0 and 100.
 482  * @param fsize number of bytes that will need to be processed (for this file)
 483  * @param completed number of bytes that have been processed (for this file)
 484  * @param offset offset of the data of buffer in the file
 485  * @param eta absolute estimated time for the completion of the operation
 486  * @param uri pointer to CHK URI for search results and downloads; pointer
 487  *        to KSK uri for uploads; client can modify KSK uri to change the
 488  *        set of keywords that will be used
 489  * @param meta metadata for search results and downloads (NULL for downloads
 490  *        if no metadata is available); can be modified for uploads to change
 491  *        metadata that will be used
 492  * @param bsize number of bytes in the buffer
 493  * @param buffer pointer to the last bytes processed; will be a plaintext
 494  *        buffer for files (with content downloaded or uploaded) and
 495  *        NULL when searching; points to an error message of bsize bytes
 496  *        if this callback is used to signal an error
 497  * @return GNUNET_SYSERR to abort the overall operation; GNUNET_NO to
 498  *        stop this specific operation (do not share this file or skip
 499  *        this download; GNUNET_NO has no meaning for search results);
 500  *        GNUNET_YES to continue processing as usual
 501  * @deprecated (use 2-arg function getting union argument instead)
 502  */
 503 typedef int (*GNUNET_FS_ProgressCallback)
 504   (void *cls,
 505    void **ctx,
 506    void *pctx,
 507    const char *filename,
 508    enum GNUNET_FS_Status status,
 509    float availability,
 510    float certainty,
 511    uint64_t fsize,
 512    uint64_t completed,
 513    uint64_t offset, struct GNUNET_TIME_Absolute eta,
 514    struct GNUNET_FS_Uri **uri,
 515    struct GNUNET_CONTAINER_MetaData *meta,
 516    size_t bsize, const void *buffer);
 517
 518
 519 /**
 520  * Handle to the file-sharing service.
 521  */
 522 struct GNUNET_FS_Handle;
 523
 524
 525 /**
 526  * Setup a connection to the file-sharing service.
 527  *
 528  * @param sched scheduler to use
 529  * @param cfg configuration to use
 530  * @param client_name unique identifier for this client
 531  * @param upcb function to call to notify about FS actions
 532  * @param upcb_cls closure for upcb
 533  */
 534 struct GNUNET_FS_Handle *
 535 GNUNET_FS_start (struct GNUNET_SCHEDULER_Handle *sched,
 536                  struct GNUNET_CONFIGURATION_Handle *cfg,
 537                  const char *client_name,
 538                  GNUNET_FS_ProgressCallback upcb,
 539                  void *upcb_cls);
 540
 541
 542 /**
 543  * Close our connection with the file-sharing service.
 544  * The callback given to GNUNET_FS_start will no longer be
 545  * called after this function returns.
 546  *
 547  * @param h handle that was returned from GNUNET_FS_start
 548  */
 549 void
 550 GNUNET_FS_stop (struct GNUNET_FS_Handle *h);
 551
 552
 553 /**
 554  * Handle to one of our namespaces.
 555  */
 556 struct GNUNET_FS_Namespace;
 557
 558
 559 /**
 560  * Handle for controlling an upload.
 561  */
 562 struct GNUNET_FS_ShareContext;
 563
 564
 565 /**
 566  * Share a file or directory.
 567  *
 568  * @param h handle to the file sharing subsystem
 569  * @param ctx initial value to use for the '*ctx' in the callback
 570  * @param filename name of the file or directory to share
 571  * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
 572  *                GNUNET_SYSERR for simulation
 573  * @param anonymity what is the desired anonymity level for sharing?
 574  * @param priority what is the priority for OUR node to
 575  *   keep this file available?  Use 0 for maximum anonymity and
 576  *   minimum reliability...
 577  * @param expirationTime when should this content expire?
 578  * @param namespace namespace to share the file in, NULL for no namespace
 579  * @param nid identifier to use for the shared content in the namespace
 580  *        (can be NULL, must be NULL if namespace is NULL)
 581  * @param nuid update-identifier that will be used for future updates
 582  *        (can be NULL, must be NULL if namespace or nid is NULL)
 583  * @deprecated API not powerful enough to share complex directory structures
 584  *         with metadata in general (need to pre-build tree)
 585  */
 586 struct GNUNET_FS_ShareContext *
 587 GNUNET_FS_share_start (struct GNUNET_FS_Handle *h,
 588                        void *ctx,
 589                        const char *filename,
 590                        int do_index,
 591                        unsigned int anonymity,
 592                        unsigned int priority,
 593                        struct GNUNET_TIME_Absolute expirationTime,
 594                        struct GNUNET_FS_Namespace *namespace
 595                        const char *nid,
 596                        const char *nuid);
 597
 598
 599 /**
 600  * Stop an upload.  Will abort incomplete uploads (but
 601  * not remove blocks that have already been shared) or
 602  * simply clean up the state for completed uploads.
 603  *
 604  * @param sc context for the upload to stop
 605  */
 606 void
 607 GNUNET_FS_share_stop (struct GNUNET_FS_ShareContext *sc);
 608
 609
 610 /**
 611  * Type of a function called by "GNUNET_FS_get_indexed_files".
 612  *
 613  * @param cls closure
 614  * @param filename the name of the file
 615  * @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort
 616  */
 617 typedef int (*GNUNET_FS_FileProcessor) (void *cls,
 618                                         const char *filename);
 619
 620
 621 /**
 622  * Iterate over all indexed files.
 623  *
 624  * @param h handle to the file sharing subsystem
 625  * @param iterator function to call on each indexed file
 626  * @param iterator_cls closure for iterator
 627  */
 628 void
 629 GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h,
 630                              GNUNET_FS_FileProcessor iterator,
 631                              void *iterator_cls);
 632
 633
 634 /**
 635  * Unindex a file.
 636  *
 637  * @param h handle to the file sharing subsystem
 638  * @param filename file to unindex
 639  */
 640 void
 641 GNUNET_FS_unindex (struct GNUNET_FS_Handle *h,
 642                    const char *filename);
 643
 644
 645 /**
 646  * Publish an advertismement for a namespace.
 647  *
 648  * @param h handle to the file sharing subsystem
 649  * @param namespace handle for the namespace that should be advertised
 650  * @param meta meta-data for the namespace advertisement
 651  * @param anonymity for the namespace advertismement
 652  * @param priority for the namespace advertisement
 653  * @param expiration for the namespace advertisement
 654  * @param advertisementURI the keyword (!) URI to advertise the
 655  *        namespace under (we will create a GNUNET_EC_KNBlock)
 656  * @param rootEntry name of the root entry in the namespace (for
 657  *        the namespace advertisement)
 658  *
 659  * @return uri of the advertisement
 660  */
 661 struct GNUNET_FS_Uri *
 662 GNUNET_FS_namespace_advertise (struct GNUNET_FS_Handle *h,
 663                                struct GNUNET_FS_Namespace *namespace,
 664                                const struct GNUNET_MetaData *meta,
 665                                unsigned int anonymity,
 666                                unsigned int priority,
 667                                struct GNUNET_TIME_Absolute expiration,
 668                                const struct GNUNET_FS_Uri *advertisementURI,
 669                                const char *rootEntry);
 670
 671
 672 /**
 673  * Create a namespace with the given name; if one already
 674  * exists, return a handle to the existing namespace.
 675  *
 676  * @param h handle to the file sharing subsystem
 677  * @param name name to use for the namespace
 678  * @return handle to the namespace, NULL on error
 679  */
 680 struct GNUNET_FS_Namespace *
 681 GNUNET_FS_namespace_create (struct GNUNET_FS_Handle *h,
 682                             const char *name);
 683
 684
 685 /**
 686  * Delete a namespace handle.  Can be used for a clean shutdown (free
 687  * memory) or also to freeze the namespace to prevent further
 688  * insertions by anyone.
 689  *
 690  * @param namespace handle to the namespace that should be deleted / freed
 691  * @param freeze prevents future insertions; creating a namespace
 692  *        with the same name again will create a fresh namespace instead
 693  *
 694  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 695  */
 696 int
 697 GNUNET_FS_namespace_delete (struct GNUNET_FS_Namespace *namespace,
 698                             int freeze);
 699
 700
 701 /**
 702  * Callback with information about local (!) namespaces.
 703  * Contains the names of the local namespace and the global
 704  * ID.
 705  *
 706  * @param cls closure
 707  * @param name human-readable identifier of the namespace
 708  * @param id hash identifier for the namespace
 709  */
 710 typedef void (*GNUNET_FS_NamespaceInfoProcessor) (void *cls,
 711                                                   const char *name,
 712                                                   const GNUNET_HashCode *id);
 713
 714
 715 /**
 716  * Build a list of all available local (!) namespaces The returned
 717  * names are only the nicknames since we only iterate over the local
 718  * namespaces.
 719  *
 720  * @param h handle to the file sharing subsystem
 721  * @param cb function to call on each known namespace
 722  * @param cb_cls closure for cb
 723  * @return GNUNET_SYSERR on error, otherwise the number of pseudonyms in list
 724  */
 725 int
 726 GNUNET_FS_namespace_list (struct GNUNET_FS_Handle *h,
 727                           GNUNET_FS_NamespaceProcessor cb,
 728                           void *cb_cls);
 729
 730
 731 /**
 732  * Function called on updateable identifiers.
 733  *
 734  * @param cls closure
 735  * @param last_id last identifier
 736  * @param last_uri uri used for the content published under the last_id
 737  * @param last_meta metadata associated with last_uri
 738  * @param next_id identifier that should be used for updates
 739  */
 740 typedef void
 741 (*GNUNET_FS_IdentifierProcessor)(void *cls,
 742                                  const char *last_id,
 743                                  const struct GNUNET_FS_Uri *last_uri,
 744                                  const struct GNUNET_CONTAINER_MetaData *last_meta,
 745                                  const char *next_id);
 746
 747
 748 /**
 749  * List all of the identifiers in the namespace for
 750  * which we could produce an update.
 751  *
 752  * @param namespace namespace to inspect for updateable content
 753  * @param ip function to call on each updateable identifier
 754  * @param ip_cls closure for ip
 755  */
 756 void
 757 GNUNET_FS_namespace_list_updateable (struct GNUNET_FS_Namespace *namespace,
 758                                      GNUNET_FS_IdentifierProcessor ip,
 759                                      void *ip_cls);
 760
 761
 762 /**
 763  * Handle for controlling a search.
 764  */
 765 struct GNUNET_FS_SearchContext;
 766
 767
 768 /**
 769  * Start search for content.
 770  *
 771  * @param h handle to the file sharing subsystem
 772  * @param uri specifies the search parameters; can be
 773  *        a KSK URI or an SKS URI.
 774  * @param anonymity desired level of anonymity
 775  * @return context that can be used to control the search
 776  */
 777 struct GNUNET_FS_SearchContext *
 778 GNUNET_FS_search_start (struct GNUNET_FS_Handle *h,
 779                         const struct GNUNET_FS_Uri *uri,
 780                         unsigned int anonymity);
 781
 782
 783 /**
 784  * Pause search.
 785  *
 786  * @param sc context for the search that should be paused
 787  */
 788 void
 789 GNUNET_FS_search_pause (struct GNUNET_FS_SearchContext *sc);
 790
 791
 792 /**
 793  * Resume paused search.
 794  *
 795  * @param sc context for the search that should be resumed
 796  */
 797 void
 798 GNUNET_FS_search_resume (struct GNUNET_FS_SearchContext *sc);
 799
 800
 801 /**
 802  * Stop search for content.
 803  *
 804  * @param sc context for the search that should be stopped
 805  */
 806 void
 807 GNUNET_FS_search_stop (struct GNUNET_FS_SearchContext *sc);
 808
 809
 810 /**
 811  * Context for controlling a download.
 812  */
 813 struct GNUNET_FS_DownloadContext;
 814
 815
 816 /**
 817  * Download parts of a file.  Note that this will store
 818  * the blocks at the respective offset in the given file.  Also, the
 819  * download is still using the blocking of the underlying FS
 820  * encoding.  As a result, the download may *write* outside of the
 821  * given boundaries (if offset and length do not match the 32k FS
 822  * block boundaries). <p>
 823  *
 824  * This function should be used to focus a download towards a
 825  * particular portion of the file (optimization), not to strictly
 826  * limit the download to exactly those bytes.
 827  *
 828  * @param h handle to the file sharing subsystem
 829  * @param uri the URI of the file (determines what to download); CHK or LOC URI
 830  * @param filename where to store the file, maybe NULL (then no file is
 831  *        created on disk and data must be grabbed from the callbacks)
 832  * @param offset at what offset should we start the download (typically 0)
 833  * @param length how many bytes should be downloaded starting at offset
 834  * @param anonymity anonymity level to use for the download
 835  * @param no_temporaries set to GNUNET_YES to disallow generation of temporary files
 836  * @param recursive should this be a recursive download (useful for directories
 837  *        to automatically trigger download of files in the directories)
 838  * @param parent parent download to associate this download with (use NULL
 839  *        for top-level downloads; useful for manually-triggered recursive downloads)
 840  * @return context that can be used to control this download
 841  */
 842 struct GNUNET_FS_DownloadContext *
 843 GNUNET_FS_file_download_start (struct GNUNET_FS_Handle *h,
 844                                const struct GNUNET_FS_Uri *uri,
 845                                const char *filename,
 846                                unsigned long long offset,
 847                                unsigned long long length,
 848                                unsigned int anonymity,
 849                                int no_temporaries,
 850                                int recursive,
 851                                struct GNUNET_FS_DownloadContext *parent);
 852
 853
 854 /**
 855  * Stop a download (aborts if download is incomplete).
 856  *
 857  * @param rm handle for the download
 858  * @param do_delete delete files of incomplete downloads
 859  */
 860 void
 861 GNUNET_FS_file_download_stop (struct GNUNET_FS_DownloadContext *rm,
 862                               int do_delete);
 863
 864
 865 /**
 866  * Iterate over all entries in a directory.  Note that directories
 867  * are structured such that it is possible to iterate over the
 868  * individual blocks as well as over the entire directory.  Thus
 869  * a client can call this function on the buffer in the
 870  * GNUNET_FS_ProgressCallback.
 871  *
 872  * @param size number of bytes in data
 873  * @param data pointer to the beginning of the directory
 874  * @param offset offset of data in the directory
 875  * @param spcb function to call on each entry
 876  * @param spcb_cls closure for spcb
 877  */
 878 void
 879 GNUNET_FS_directory_list_contents (size_t size,
 880                                    const void *data,
 881                                    uint64_t offset,
 882                                    GNUNET_FS_SearchResultProcessor spcb,
 883                                    void *spcb_cls);
 884
 885
 886 /**
 887  * Create a directory.
 888  *
 889  * @param data pointer set to the beginning of the directory
 890  * @param len set to number of bytes in data
 891  * @param count number of entries in uris and metaDatas
 892
 893  * @param uris URIs of the files in the directory
 894  * @param metaDatas meta-data for the files (must match
 895  *        respective values at same offset in in uris)
 896  * @param meta meta-data for the directory.  The meta entry
 897  *        is extended with the mime-type for a GNUnet directory.
 898
 899  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 900  * @deprecated (not powerful enough?)
 901  */
 902 int
 903 GNUNET_FS_directory_create (char **data,
 904                             uint64_t *len,
 905                             unsigned int count,
 906                             const GNUNET_FS_FileInfo * fis,
 907                             struct GNUNET_MetaData *meta);
 908
 909
 910 /**
 911  * Initialize collection.
 912  *
 913  * @param h handle to the file sharing subsystem
 914  * @param namespace namespace to use for the collection
 915  * @return GNUNET_OK on success, GNUNET_SYSERR if another
 916  *         namespace is already set for our collection
 917  */
 918 int
 919 GNUNET_FS_collection_start (struct GNUNET_FS_Handle *h,
 920                             struct GNUNET_FS_Namespace *namespace);
 921
 922
 923 /**
 924  * Stop collection.
 925  *
 926  * @param h handle to the file sharing subsystem
 927  * @return GNUNET_OK on success, GNUNET_SYSERR if no collection is active
 928  */
 929 int
 930 GNUNET_CO_collection_stop (struct GNUNET_FS_Handle *h);
 931
 932
 933 /**
 934  * Are we using a collection?
 935  *
 936  * @param h handle to the file sharing subsystem
 937  * @return NULL if there is no collection,
 938  */
 939 struct GNUNET_FS_Namespace *
 940 GNUNET_FS_collection_get(struct GNUNET_FS_Handle *h);
 941
 942
 943 /**
 944  * Publish an update of the current collection information to the
 945  * network now.  The function has no effect if the collection has not
 946  * changed since the last publication.  If we are currently not
 947  * collecting, this function does nothing.
 948  *
 949  * @param h handle to the file sharing subsystem
 950  */
 951 void GNUNET_FS_collection_publish (struct GNUNET_FS_Handle *h);
 952
 953
 954 /**
 955  * If we are currently building a collection, publish the given file
 956  * information in that collection.  If we are currently not
 957  * collecting, this function does nothing.
 958  *
 959  * @param h handle to the file sharing subsystem
 960  * @param uri uri to add to the collection
 961  * @param meta metadata for the uri
 962  */
 963 void GNUNET_FS_collection_add (const struct GNUNET_FS_Handle *h,
 964                                const struct GNUNET_FS_Uri *uri,
 965                                const struct GNUNET_CONTAINER_MetaData *meta);
 966
 967
 968
 969 #if 0                           /* keep Emacsens' auto-indent happy */
 970 {
 971 #endif
 972 #ifdef __cplusplus
 973 }
 974 #endif
 975
 976
 977 #endif