2 This file is part of GNUnet
3 (C) 2004, 2005, 2006, 2007, 2008, 2009 Christian Grothoff (and other contributing authors)
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version.
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.
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.
21 * @file include/gnunet_fs_service.h
22 * @brief API for file-sharing via GNUnet
23 * @author Christian Grothoff
25 #ifndef GNUNET_FS_LIB_H
26 #define GNUNET_FS_LIB_H
28 #include "gnunet_util_lib.h"
33 #if 0 /* keep Emacsens' auto-indent happy */
39 * Version number of the implementation.
42 * 1.x.x: initial version with triple GNUNET_hash and merkle tree
43 * 2.x.x: root node with mime-type, filename and version number
44 * 2.1.x: combined GNUNET_EC_ContentHashKey/3HASH encoding with 25:1 super-nodes
45 * 2.2.x: with directories
46 * 3.0.x: with namespaces
47 * 3.1.x: with namespace meta-data
48 * 3.2.x: with collections
49 * 4.0.x: with expiration, variable meta-data, kblocks
50 * 4.1.x: with new error and configuration handling
51 * 5.0.x: with location URIs
52 * 6.0.0: with support for OR in KSKs
53 * 6.1.x: with simplified namespace support
54 * 9.0.0: CPS-style integrated API
56 #define GNUNET_FS_VERSION 0x00090000
59 /* ******************** URI API *********************** */
61 #define GNUNET_FS_URI_PREFIX "gnunet://fs/"
62 #define GNUNET_FS_URI_KSK_INFIX "ksk/"
63 #define GNUNET_FS_URI_SKS_INFIX "sks/"
64 #define GNUNET_FS_URI_CHK_INFIX "chk/"
65 #define GNUNET_FS_URI_LOC_INFIX "loc/"
69 * A Universal Resource Identifier (URI), opaque.
75 * Iterator over keywords
78 * @param keyword the keyword
79 * @param is_mandatory is the keyword mandatory (in a search)
80 * @return GNUNET_OK to continue to iterate, GNUNET_SYSERR to abort
82 typedef int (*GNUNET_FS_KeywordIterator) (void *cls,
87 * Get a unique key from a URI. This is for putting URIs
88 * into HashMaps. The key may change between FS implementations.
90 * @param uri uri to convert to a unique key
91 * @param key wherer to store the unique key
94 GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri,
95 GNUNET_HashCode * key);
98 * Convert a URI to a UTF-8 String.
100 * @param uri uri to convert to a string
101 * @return the UTF-8 string
104 GNUNET_FS_uri_to_string (const struct GNUNET_FS_Uri *uri);
107 * Convert keyword URI to a human readable format
108 * (i.e. the search query that was used in the first place)
110 * @param uri ksk uri to convert to a string
111 * @return string with the keywords
114 GNUNET_FS_uri_ksk_to_string_fancy (const struct GNUNET_FS_Uri *uri);
118 * Add the given keyword to the set of keywords represented by the URI.
119 * Does nothing if the keyword is already present.
121 * @param uri ksk uri to modify
122 * @param keyword keyword to add
123 * @param is_mandatory is this keyword mandatory?
126 GNUNET_FS_uri_ksk_add_keyword (struct GNUNET_FS_Uri *uri,
132 * Convert a UTF-8 String to a URI.
134 * @param uri string to parse
135 * @param emsg where to store the parser error message (if any)
136 * @return NULL on error
138 struct GNUNET_FS_Uri *
139 GNUNET_FS_uri_parse (const char *uri,
145 * @param uri uri to free
148 GNUNET_FS_uri_destroy (struct GNUNET_FS_Uri *uri);
152 * How many keywords are ANDed in this keyword URI?
154 * @param uri ksk uri to get the number of keywords from
155 * @return 0 if this is not a keyword URI
158 GNUNET_FS_uri_ksk_get_keyword_count (const struct GNUNET_FS_Uri *uri);
162 * Iterate over all keywords in this keyword URI.
164 * @param uri ksk uri to get the keywords from
165 * @param iterator function to call on each keyword
166 * @param iterator_cls closure for iterator
167 * @return -1 if this is not a keyword URI, otherwise number of
168 * keywords iterated over until iterator aborted
171 GNUNET_FS_uri_ksk_get_keywords (const struct GNUNET_FS_Uri *uri,
172 GNUNET_FS_KeywordIterator iterator,
177 * Obtain the identity of the peer offering the data
179 * @param uri the location URI to inspect
180 * @param peer where to store the identify of the peer (presumably) offering the content
181 * @return GNUNET_SYSERR if this is not a location URI, otherwise GNUNET_OK
184 GNUNET_FS_uri_loc_get_peer_identity (const struct GNUNET_FS_Uri *uri,
185 struct GNUNET_PeerIdentity * peer);
189 * Obtain the URI of the content itself.
191 * @param uri location URI to get the content URI from
192 * @return NULL if argument is not a location URI
194 struct GNUNET_FS_Uri *
195 GNUNET_FS_uri_loc_get_uri (const struct GNUNET_FS_Uri *uri);
199 * Obtain the expiration of the LOC URI.
201 * @param uri location URI to get the expiration from
202 * @return expiration time of the URI
204 struct GNUNET_TIME_Absolute
205 GNUNET_FS_uri_loc_get_expiration (const struct GNUNET_FS_Uri *uri);
209 * Construct a location URI (this peer will be used for the location).
211 * @param baseUri content offered by the sender
212 * @param cfg configuration information (used to find our hostkey)
213 * @param expiration_time how long will the content be offered?
214 * @return the location URI, NULL on error
216 struct GNUNET_FS_Uri *
217 GNUNET_FS_uri_loc_create (const struct GNUNET_FS_Uri *baseUri,
218 const struct GNUNET_CONFIGURATION_Handle *cfg,
219 struct GNUNET_TIME_Absolute expiration_time);
223 * Canonicalize keyword URI. Performs operations such
224 * as decapitalization and removal of certain characters.
225 * (useful for search).
227 * @param uri the URI to canonicalize
228 * @return canonicalized version of the URI, NULL on error
230 struct GNUNET_FS_Uri *
231 GNUNET_FS_uri_ksk_canonicalize (const struct GNUNET_FS_Uri *uri);
235 * Merge the sets of keywords from two KSK URIs.
236 * (useful for merging the canonicalized keywords with
237 * the original keywords for sharing).
239 * @param u1 first uri
240 * @param u2 second uri
241 * @return merged URI, NULL on error
243 struct GNUNET_FS_Uri *
244 GNUNET_FS_uri_ksk_merge (const struct GNUNET_FS_Uri *u1,
245 const struct GNUNET_FS_Uri *u2);
251 * @param uri the URI to duplicate
252 * @return copy of the URI
254 struct GNUNET_FS_Uri *
255 GNUNET_FS_uri_dup (const struct GNUNET_FS_Uri *uri);
259 * Create an FS URI from a single user-supplied string of keywords.
260 * The string is broken up at spaces into individual keywords.
261 * Keywords that start with "+" are mandatory. Double-quotes can
262 * be used to prevent breaking up strings at spaces (and also
263 * to specify non-mandatory keywords starting with "+").
265 * Keywords must contain a balanced number of double quotes and
266 * double quotes can not be used in the actual keywords (for
267 * example, the string '""foo bar""' will be turned into two
268 * "OR"ed keywords 'foo' and 'bar', not into '"foo bar"'.
270 * @param keywords the keyword string
271 * @param emsg where to store an error message
272 * @return an FS URI for the given keywords, NULL
273 * if keywords is not legal (i.e. empty).
275 struct GNUNET_FS_Uri *
276 GNUNET_FS_uri_ksk_create (const char *keywords,
281 * Create an FS URI from a user-supplied command line of keywords.
282 * Arguments should start with "+" to indicate mandatory
285 * @param argc number of keywords
286 * @param argv keywords (double quotes are not required for
287 * keywords containing spaces; however, double
288 * quotes are required for keywords starting with
289 * "+"); there is no mechanism for having double
290 * quotes in the actual keywords (if the user
291 * did specifically specify double quotes, the
292 * caller should convert each double quote
293 * into two single quotes).
294 * @return an FS URI for the given keywords, NULL
295 * if keywords is not legal (i.e. empty).
297 struct GNUNET_FS_Uri *
298 GNUNET_FS_uri_ksk_create_from_args (unsigned int argc,
303 * Test if two URIs are equal.
305 * @param u1 one of the URIs
306 * @param u2 the other URI
307 * @return GNUNET_YES if the URIs are equal
310 GNUNET_FS_uri_test_equal (const struct GNUNET_FS_Uri *u1,
311 const struct GNUNET_FS_Uri *u2);
315 * Is this a namespace URI?
317 * @param uri the uri to check
318 * @return GNUNET_YES if this is an SKS uri
321 GNUNET_FS_uri_test_sks (const struct GNUNET_FS_Uri *uri);
325 * Handle to one of our namespaces.
327 struct GNUNET_FS_Namespace;
331 * Create an SKS URI from a namespace and an identifier.
333 * @param ns namespace
334 * @param id identifier
335 * @param emsg where to store an error message
336 * @return an FS URI for the given namespace and identifier
338 struct GNUNET_FS_Uri *
339 GNUNET_FS_uri_sks_create (struct GNUNET_FS_Namespace *ns,
345 * Create an SKS URI from a namespace ID and an identifier.
347 * @param nsid namespace ID
348 * @param id identifier
349 * @return an FS URI for the given namespace and identifier
351 struct GNUNET_FS_Uri *
352 GNUNET_FS_uri_sks_create_from_nsid (GNUNET_HashCode *nsid,
357 * Get the ID of a namespace from the given
360 * @param uri the uri to get the namespace ID from
361 * @param nsid where to store the ID of the namespace
362 * @return GNUNET_OK on success
365 GNUNET_FS_uri_sks_get_namespace (const struct GNUNET_FS_Uri *uri,
366 GNUNET_HashCode * nsid);
370 * Get the content identifier of an SKS URI.
372 * @param uri the sks uri
373 * @return NULL on error (not a valid SKS URI)
376 GNUNET_FS_uri_sks_get_content_id (const struct GNUNET_FS_Uri *uri);
380 * Convert namespace URI to a human readable format
381 * (using the namespace description, if available).
383 * @param cfg configuration to use
384 * @param uri SKS uri to convert
385 * @return NULL on error (not an SKS URI)
388 GNUNET_FS_uri_sks_to_string_fancy (struct GNUNET_CONFIGURATION_Handle *cfg,
389 const struct GNUNET_FS_Uri *uri);
393 * Is this a keyword URI?
396 * @return GNUNET_YES if this is a KSK uri
399 GNUNET_FS_uri_test_ksk (const struct GNUNET_FS_Uri *uri);
403 * Is this a file (or directory) URI?
405 * @param uri the uri to check
406 * @return GNUNET_YES if this is a CHK uri
409 GNUNET_FS_uri_test_chk (const struct GNUNET_FS_Uri *uri);
413 * What is the size of the file that this URI
416 * @param uri the CHK (or LOC) URI to inspect
417 * @return size of the file as specified in the CHK URI
420 GNUNET_FS_uri_chk_get_file_size (const struct GNUNET_FS_Uri *uri);
424 * Is this a location URI?
426 * @param uri the uri to check
427 * @return GNUNET_YES if this is a LOC uri
430 GNUNET_FS_uri_test_loc (const struct GNUNET_FS_Uri *uri);
434 * Construct a keyword-URI from meta-data (take all entries
435 * in the meta-data and construct one large keyword URI
436 * that lists all keywords that can be found in the meta-data).
438 * @param md metadata to use
439 * @return NULL on error, otherwise a KSK URI
441 struct GNUNET_FS_Uri *
442 GNUNET_FS_uri_ksk_create_from_meta_data (const struct GNUNET_CONTAINER_MetaData *md);
445 /* ******************** command-line option parsing API *********************** */
448 * Command-line option parser function that allows the user
449 * to specify one or more '-k' options with keywords. Each
450 * specified keyword will be added to the URI. A pointer to
451 * the URI must be passed as the "scls" argument.
453 * @param ctx command line processor context
454 * @param scls must be of type "struct GNUNET_FS_Uri **"
455 * @param option name of the option (typically 'k')
456 * @param value command line argument given
457 * @return GNUNET_OK on success
460 GNUNET_FS_getopt_set_keywords (struct GNUNET_GETOPT_CommandLineProcessorContext* ctx,
467 * Command-line option parser function that allows the user to specify
468 * one or more '-m' options with metadata. Each specified entry of
469 * the form "type=value" will be added to the metadata. A pointer to
470 * the metadata must be passed as the "scls" argument.
472 * @param ctx command line processor context
473 * @param scls must be of type "struct GNUNET_CONTAINER_MetaData **"
474 * @param option name of the option (typically 'k')
475 * @param value command line argument given
476 * @return GNUNET_OK on success
479 GNUNET_FS_getopt_set_metadata (struct GNUNET_GETOPT_CommandLineProcessorContext* ctx,
486 /* ************************* sharing API ***************** */
490 * Possible status codes used in the callback for the
491 * various file-sharing operations. On each file (or search),
492 * the callback is guaranteed to be called once with "START"
493 * and once with STOPPED; calls with PROGRESS, ERROR or COMPLETED
494 * are optional and depend on the circumstances; parent operations
495 * will be STARTED before child-operations and STOPPED after
496 * their respective child-operations. START and STOP signals
497 * are typically generated either due to explicit client requests
498 * or because of suspend/resume operations.
500 enum GNUNET_FS_Status
503 * Notification that we have started to publish a file structure.
505 GNUNET_FS_STATUS_PUBLISH_START,
508 * Notification that we have resumed sharing a file structure.
510 GNUNET_FS_STATUS_PUBLISH_RESUME,
513 * Notification that we have suspended sharing a file structure.
515 GNUNET_FS_STATUS_PUBLISH_SUSPEND,
518 * Notification that we are making progress sharing a file structure.
520 GNUNET_FS_STATUS_PUBLISH_PROGRESS,
523 * Notification that an error was encountered sharing a file structure.
524 * The application will continue to receive resume/suspend events for
525 * this structure until "GNUNET_FS_publish_stop" is called.
527 GNUNET_FS_STATUS_PUBLISH_ERROR,
530 * Notification that we completed sharing a file structure.
531 * The application will continue to receive resume/suspend events for
532 * this structure until "GNUNET_FS_publish_stop" is called.
534 GNUNET_FS_STATUS_PUBLISH_COMPLETED,
537 * Notification that we have stopped
538 * the process of uploading a file structure; no
539 * futher events will be generated for this action.
541 GNUNET_FS_STATUS_PUBLISH_STOPPED,
544 * Notification that we have started this download.
546 GNUNET_FS_STATUS_DOWNLOAD_START,
549 * Notification that this download is being resumed.
551 GNUNET_FS_STATUS_DOWNLOAD_RESUME,
554 * Notification that this download was suspended.
556 GNUNET_FS_STATUS_DOWNLOAD_SUSPEND,
559 * Notification about progress with this download.
561 GNUNET_FS_STATUS_DOWNLOAD_PROGRESS,
564 * Notification that this download encountered an error.
566 GNUNET_FS_STATUS_DOWNLOAD_ERROR,
569 * Notification that this download completed. Note that for
570 * directories, completion does not imply completion of all files in
573 GNUNET_FS_STATUS_DOWNLOAD_COMPLETED,
576 * Notification that this download was stopped
577 * (final event with respect to this action).
579 GNUNET_FS_STATUS_DOWNLOAD_STOPPED,
582 * Notification that this download is now actively being
583 * pursued (as opposed to waiting in the queue).
585 GNUNET_FS_STATUS_DOWNLOAD_ACTIVE,
588 * Notification that this download is no longer actively
589 * being pursued (back in the queue).
591 GNUNET_FS_STATUS_DOWNLOAD_INACTIVE,
594 * Notification that this download is no longer part of a
595 * recursive download or search but now a 'stand-alone'
596 * download (and may thus need to be moved in the GUI
597 * into a different category).
599 GNUNET_FS_STATUS_DOWNLOAD_LOST_PARENT,
602 * First event generated when a client requests
603 * a search to begin or when a namespace result
604 * automatically triggers the search for updates.
606 GNUNET_FS_STATUS_SEARCH_START,
609 * Last event when a search is being resumed;
610 * note that "GNUNET_FS_SEARCH_START" will not
611 * be generated in this case.
613 GNUNET_FS_STATUS_SEARCH_RESUME,
616 * Event generated for each search result
617 * when the respective search is resumed.
619 GNUNET_FS_STATUS_SEARCH_RESUME_RESULT,
622 * Last event when a search is being suspended;
623 * note that "GNUNET_FS_SEARCH_STOPPED" will not
624 * be generated in this case.
626 GNUNET_FS_STATUS_SEARCH_SUSPEND,
629 * This search has yielded a result.
631 GNUNET_FS_STATUS_SEARCH_RESULT,
634 * We have discovered a new namespace.
636 GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE,
639 * We have additional data about the quality
640 * or availability of a search result.
642 GNUNET_FS_STATUS_SEARCH_UPDATE,
645 * Signals a problem with this search.
647 GNUNET_FS_STATUS_SEARCH_ERROR,
650 * Signals that this search was paused.
652 GNUNET_FS_STATUS_SEARCH_PAUSED,
655 * Signals that this search was continued (unpaused).
657 GNUNET_FS_STATUS_SEARCH_CONTINUED,
660 * Event generated for each search result
661 * when the respective search is stopped.
663 GNUNET_FS_STATUS_SEARCH_RESULT_STOPPED,
666 * Event generated for each search result
667 * when the respective search is suspended.
669 GNUNET_FS_STATUS_SEARCH_RESULT_SUSPEND,
672 * Last message from a search; this signals
673 * that there will be no further events associated
676 GNUNET_FS_STATUS_SEARCH_STOPPED,
679 * Notification that we started to unindex a file.
681 GNUNET_FS_STATUS_UNINDEX_START,
684 * Notification that we resumed unindexing of a file.
686 GNUNET_FS_STATUS_UNINDEX_RESUME,
689 * Notification that we suspended unindexing a file.
691 GNUNET_FS_STATUS_UNINDEX_SUSPEND,
694 * Notification that we made progress unindexing a file.
696 GNUNET_FS_STATUS_UNINDEX_PROGRESS,
699 * Notification that we encountered an error unindexing
702 GNUNET_FS_STATUS_UNINDEX_ERROR,
705 * Notification that the unindexing of this file
708 GNUNET_FS_STATUS_UNINDEX_COMPLETED,
711 * Notification that the unindexing of this file
712 * was stopped (final event for this action).
714 GNUNET_FS_STATUS_UNINDEX_STOPPED
720 * Handle for controlling an upload.
722 struct GNUNET_FS_PublishContext;
726 * Handle for controlling an unindexing operation.
728 struct GNUNET_FS_UnindexContext;
732 * Handle for controlling a search.
734 struct GNUNET_FS_SearchContext;
738 * Result from a search. Opaque handle to refer to the search
739 * (typically used when starting a download associated with the search
742 struct GNUNET_FS_SearchResult;
746 * Context for controlling a download.
748 struct GNUNET_FS_DownloadContext;
752 * Handle for detail information about a file that is being publishd.
753 * Specifies metadata, keywords, how to get the contents of the file
754 * (i.e. data-buffer in memory, filename on disk) and other options.
756 struct GNUNET_FS_FileInformation;
760 * Argument given to the progress callback with
761 * information about what is going on.
763 struct GNUNET_FS_ProgressInfo
767 * Values that depend on the event type.
772 * Values for all "GNUNET_FS_STATUS_PUBLISH_*" events.
777 * Context for controlling the upload.
779 struct GNUNET_FS_PublishContext *pc;
782 * Information about the file that is being publishd.
784 const struct GNUNET_FS_FileInformation *fi;
787 * Client context pointer (set the last time by the client for
788 * this operation; initially NULL on START/RESUME events).
793 * Client context pointer for the parent operation
794 * (if this is a file in a directory or a subdirectory).
799 * Name of the file being published; can be NULL.
801 const char *filename;
804 * How large is the file overall? For directories,
805 * this is only the size of the directory itself,
806 * not of the other files contained within the
812 * At what time do we expect to finish the upload?
813 * (will be a value in the past for completed
816 struct GNUNET_TIME_Relative eta;
819 * How long has this upload been actively running
820 * (excludes times where the upload was suspended).
822 struct GNUNET_TIME_Relative duration;
825 * How many bytes have we completed?
830 * What anonymity level is used for this upload?
835 * Additional values for specific events.
840 * These values are only valid for
841 * GNUNET_FS_STATUS_PUBLISH_PROGRESS events.
846 * Data block we just published.
851 * At what offset in the file is "data"?
856 * Length of the data block.
861 * Depth of the given block in the tree;
862 * 0 would be the highest level (the first
863 * call is guaranteed to be for the lowest
871 * These values are only valid for
872 * GNUNET_FS_STATUS_PUBLISH_RESUME events.
877 * Error message, NULL if no error was encountered so far.
882 * URI of the file (if the download had been completed)
884 const struct GNUNET_FS_Uri *chk_uri;
889 * These values are only valid for
890 * GNUNET_FS_STATUS_PUBLISH_COMPLETED events.
897 const struct GNUNET_FS_Uri *chk_uri;
902 * These values are only valid for
903 * GNUNET_FS_STATUS_PUBLISH_ERROR events.
908 * Error message, never NULL.
920 * Values for all "GNUNET_FS_STATUS_DOWNLOAD_*" events.
925 * Context for controlling the download.
927 struct GNUNET_FS_DownloadContext *dc;
930 * Client context pointer (set the last time
931 * by the client for this operation; initially
932 * NULL on START/RESUME events).
937 * Client context pointer for the parent operation
938 * (if this is a file in a directory or a subdirectory).
943 * Client context pointer for the associated search operation
944 * (specifically, context pointer for the specific search
945 * result, not the overall search); only set if this
946 * download was started from a search result.
951 * URI used for this download.
953 const struct GNUNET_FS_Uri *uri;
956 * Name of the file that we are downloading.
958 const char *filename;
961 * How large is the download overall? This
962 * is NOT necessarily the size from the
963 * URI since we may be doing a partial download.
968 * At what time do we expect to finish the download?
969 * (will be a value in the past for completed
972 struct GNUNET_TIME_Relative eta;
975 * How long has this download been active?
977 struct GNUNET_TIME_Relative duration;
980 * How many bytes have we completed?
985 * What anonymity level is used for this download?
990 * Is the download currently active.
995 * Additional values for specific events.
1000 * These values are only valid for
1001 * GNUNET_FS_STATUS_DOWNLOAD_PROGRESS events.
1006 * Data block we just obtained.
1011 * At what offset in the file is "data"?
1016 * Length of the data block.
1021 * Depth of the given block in the tree;
1022 * 0 would be the highest level (the first
1023 * call is guaranteed to be for the lowest
1031 * These values are only valid for
1032 * GNUNET_FS_STATUS_DOWNLOAD_START events.
1037 * Known metadata for the download.
1039 const struct GNUNET_CONTAINER_MetaData *meta;
1044 * These values are only valid for
1045 * GNUNET_FS_STATUS_DOWNLOAD_RESUME events.
1050 * Known metadata for the download.
1052 const struct GNUNET_CONTAINER_MetaData *meta;
1055 * Error message, NULL if we have not encountered any error yet.
1057 const char *message;
1062 * These values are only valid for
1063 * GNUNET_FS_STATUS_DOWNLOAD_ERROR events.
1070 const char *message;
1079 * Values for all "GNUNET_FS_STATUS_SEARCH_*" events.
1084 * Context for controlling the search, NULL for
1085 * searches that were not explicitly triggered
1086 * by the client (i.e., searches for updates in
1089 struct GNUNET_FS_SearchContext *sc;
1092 * Client context pointer (set the last time by the client for
1093 * this operation; initially NULL on START/RESUME events). Note
1094 * that this value can only be set on START/RESUME; returning
1095 * non-NULL on RESULT/RESUME_RESULT will actually update the
1096 * private context for "UPDATE" events.
1101 * Client parent-context pointer; NULL for top-level searches,
1102 * refers to the client context of the associated search result
1103 * for automatically triggered searches for updates in
1104 * namespaces. In this case, 'presult' refers to that search
1110 * What query is used for this search
1111 * (list of keywords or SKS identifier).
1113 const struct GNUNET_FS_Uri *query;
1116 * How long has this search been actively running
1117 * (excludes times where the search was paused or
1120 struct GNUNET_TIME_Relative duration;
1123 * What anonymity level is used for this search?
1128 * Additional values for specific events.
1133 * These values are only valid for
1134 * GNUNET_FS_STATUS_SEARCH_RESULT events.
1139 * Metadata for the search result.
1141 const struct GNUNET_CONTAINER_MetaData *meta;
1144 * URI for the search result.
1146 const struct GNUNET_FS_Uri *uri;
1149 * Handle to the result (for starting downloads).
1151 struct GNUNET_FS_SearchResult *result;
1154 * Applicability rank (the larger, the better the result
1155 * fits the search criteria).
1157 uint32_t applicability_rank;
1162 * These values are only valid for
1163 * GNUNET_FS_STATUS_SEARCH_RESUME_RESULT events.
1168 * Metadata for the search result.
1170 const struct GNUNET_CONTAINER_MetaData *meta;
1173 * URI for the search result.
1175 const struct GNUNET_FS_Uri *uri;
1178 * Handle to the result (for starting downloads).
1180 struct GNUNET_FS_SearchResult *result;
1183 * Current availability rank (negative:
1184 * unavailable, positive: available)
1186 int32_t availability_rank;
1189 * On how many total queries is the given
1190 * availability_rank based?
1192 uint32_t availability_certainty;
1195 * Updated applicability rank (the larger,
1196 * the better the result fits the search
1199 uint32_t applicability_rank;
1204 * These values are only valid for
1205 * GNUNET_FS_STATUS_SEARCH_UPDATE events.
1210 * Private context set for for this result
1211 * during the "RESULT" event.
1216 * Metadata for the search result.
1218 const struct GNUNET_CONTAINER_MetaData *meta;
1221 * URI for the search result.
1223 const struct GNUNET_FS_Uri *uri;
1226 * Current availability rank (negative:
1227 * unavailable, positive: available)
1229 int32_t availability_rank;
1232 * On how many total queries is the given
1233 * availability_rank based?
1235 uint32_t availability_certainty;
1238 * Updated applicability rank (the larger,
1239 * the better the result fits the search
1242 uint32_t applicability_rank;
1247 * These values are only valid for
1248 * GNUNET_FS_STATUS_SEARCH_RESULT_SUSPEND events.
1249 * These events are automatically triggered for
1250 * each search result before the
1251 * GNUNET_FS_STATUS_SEARCH_SUSPEND event. This
1252 * happens primarily to give the client a chance
1253 * to clean up the "cctx" (if needed).
1258 * Private context set for for this result
1259 * during the "RESULT" event.
1264 * Metadata for the search result.
1266 const struct GNUNET_CONTAINER_MetaData *meta;
1269 * URI for the search result.
1271 const struct GNUNET_FS_Uri *uri;
1276 * These values are only valid for
1277 * GNUNET_FS_STATUS_SEARCH_RESULT_STOPPED events.
1278 * These events are automatically triggered for
1279 * each search result before the
1280 * GNUNET_FS_STATUS_SEARCH_STOPPED event. This
1281 * happens primarily to give the client a chance
1282 * to clean up the "cctx" (if needed).
1287 * Private context set for for this result
1288 * during the "RESULT" event.
1293 * Metadata for the search result.
1295 const struct GNUNET_CONTAINER_MetaData *meta;
1298 * URI for the search result.
1300 const struct GNUNET_FS_Uri *uri;
1305 * These values are only valid for
1306 * GNUNET_FS_STATUS_SEARCH_RESUME events.
1311 * Error message, NULL if we have not encountered any error yet.
1313 const char *message;
1316 * Is this search currently paused?
1323 * These values are only valid for
1324 * GNUNET_FS_STATUS_SEARCH_ERROR events.
1331 const char *message;
1336 * Values for all "GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE" events.
1341 * Handle to the namespace (NULL if it is not a local
1344 struct GNUNET_FS_Namespace *ns;
1347 * Short, human-readable name of the namespace.
1352 * Root identifier for the namespace, can be NULL.
1357 * Metadata for the namespace.
1359 const struct GNUNET_CONTAINER_MetaData *meta;
1362 * Hash-identifier for the namespace.
1373 * Values for all "GNUNET_FS_STATUS_UNINDEX_*" events.
1378 * Context for controlling the unindexing.
1380 struct GNUNET_FS_UnindexContext *uc;
1383 * Client context pointer (set the last time
1384 * by the client for this operation; initially
1385 * NULL on START/RESUME events).
1390 * Name of the file that is being unindexed.
1392 const char *filename;
1395 * How large is the file overall?
1400 * At what time do we expect to finish unindexing?
1401 * (will be a value in the past for completed
1402 * unindexing opeations).
1404 struct GNUNET_TIME_Relative eta;
1407 * How long has this upload been actively running
1408 * (excludes times where the upload was suspended).
1410 struct GNUNET_TIME_Relative duration;
1413 * How many bytes have we completed?
1418 * Additional values for specific events.
1423 * These values are only valid for
1424 * GNUNET_FS_STATUS_UNINDEX_PROGRESS events.
1429 * Data block we just unindexed.
1434 * At what offset in the file is "data"?
1439 * Length of the data block.
1444 * Depth of the given block in the tree;
1445 * 0 would be the highest level (the first
1446 * call is guaranteed to be for the lowest
1454 * These values are only valid for
1455 * GNUNET_FS_STATUS_UNINDEX_RESUME events.
1460 * Error message, NULL if we have not encountered any error yet.
1462 const char *message;
1467 * These values are only valid for
1468 * GNUNET_FS_STATUS_UNINDEX_ERROR events.
1475 const char *message;
1486 * Specific status code (determines the event type).
1488 enum GNUNET_FS_Status status;
1494 * Notification of FS to a client about the progress of an
1495 * operation. Callbacks of this type will be used for uploads,
1496 * downloads and searches. Some of the arguments depend a bit
1497 * in their meaning on the context in which the callback is used.
1499 * @param cls closure
1500 * @param info details about the event, specifying the event type
1501 * and various bits about the event
1502 * @return client-context (for the next progress call
1503 * for this operation; should be set to NULL for
1504 * SUSPEND and STOPPED events). The value returned
1505 * will be passed to future callbacks in the respective
1506 * field in the GNUNET_FS_ProgressInfo struct.
1508 typedef void* (*GNUNET_FS_ProgressCallback)
1510 const struct GNUNET_FS_ProgressInfo *info);
1514 * General (global) option flags for file-sharing.
1516 enum GNUNET_FS_Flags
1519 * No special flags set.
1521 GNUNET_FS_FLAGS_NONE = 0,
1524 * Is persistence of operations desired?
1525 * (will create SUSPEND/RESUME events).
1527 GNUNET_FS_FLAGS_PERSISTENCE = 1,
1530 * Should we automatically trigger probes for search results
1531 * to determine availability?
1532 * (will create GNUNET_FS_STATUS_SEARCH_UPDATE events).
1534 GNUNET_FS_FLAGS_DO_PROBES = 2
1539 * Options specified in the VARARGs portion of GNUNET_FS_start.
1541 enum GNUNET_FS_OPTIONS
1545 * Last option in the VARARG list.
1547 GNUNET_FS_OPTIONS_END = 0,
1550 * Select the desired amount of parallelism (this option should be
1551 * followed by an "unsigned int" giving the desired maximum number
1552 * of parallel downloads).
1554 GNUNET_FS_OPTIONS_DOWNLOAD_PARALLELISM = 1,
1557 * Maximum number of requests that should be pending at a given
1558 * point in time (invidivual downloads may go above this, but
1559 * if we are above this threshold, we should not activate any
1560 * additional downloads.
1562 GNUNET_FS_OPTIONS_REQUEST_PARALLELISM = 2
1568 * Handle to the file-sharing service.
1570 struct GNUNET_FS_Handle;
1574 * Setup a connection to the file-sharing service.
1576 * @param sched scheduler to use
1577 * @param cfg configuration to use
1578 * @param client_name unique identifier for this client
1579 * @param upcb function to call to notify about FS actions
1580 * @param upcb_cls closure for upcb
1581 * @param flags specific attributes for fs-operations
1582 * @param ... list of optional options, terminated with GNUNET_FS_OPTIONS_END
1583 * @return NULL on error
1585 struct GNUNET_FS_Handle *
1586 GNUNET_FS_start (struct GNUNET_SCHEDULER_Handle *sched,
1587 const struct GNUNET_CONFIGURATION_Handle *cfg,
1588 const char *client_name,
1589 GNUNET_FS_ProgressCallback upcb,
1591 enum GNUNET_FS_Flags flags,
1596 * Close our connection with the file-sharing service.
1597 * The callback given to GNUNET_FS_start will no longer be
1598 * called after this function returns.
1600 * @param h handle that was returned from GNUNET_FS_start
1603 GNUNET_FS_stop (struct GNUNET_FS_Handle *h);
1607 * Extract meta-data from a file.
1609 * @param md metadata to set
1610 * @param filename name of file to inspect
1611 * @param extractors plugins to use
1612 * @return GNUNET_SYSERR on error, otherwise the number
1613 * of meta-data items obtained
1616 GNUNET_FS_meta_data_extract_from_file (struct
1617 GNUNET_CONTAINER_MetaData
1618 *md, const char *filename,
1619 struct EXTRACTOR_PluginList *
1624 * Function called on entries in a GNUNET_FS_FileInformation publish-structure.
1626 * @param cls closure
1627 * @param fi the entry in the publish-structure
1628 * @param length length of the file or directory
1629 * @param meta metadata for the file or directory (can be modified)
1630 * @param uri pointer to the keywords that will be used for this entry (can be modified)
1631 * @param anonymity pointer to selected anonymity level (can be modified)
1632 * @param priority pointer to selected priority (can be modified)
1633 * @param do_index should we index (can be modified)
1634 * @param expirationTime pointer to selected expiration time (can be modified)
1635 * @param client_info pointer to client context set upon creation (can be modified)
1636 * @return GNUNET_OK to continue, GNUNET_NO to remove
1637 * this entry from the directory, GNUNET_SYSERR
1638 * to abort the iteration
1640 typedef int (*GNUNET_FS_FileInformationProcessor)(void *cls,
1641 struct GNUNET_FS_FileInformation *fi,
1643 struct GNUNET_CONTAINER_MetaData *meta,
1644 struct GNUNET_FS_Uri **uri,
1645 uint32_t *anonymity,
1648 struct GNUNET_TIME_Absolute *expirationTime,
1649 void **client_info);
1653 * Obtain the name under which this file information
1654 * structure is stored on disk. Only works for top-level
1655 * file information structures.
1657 * @param s structure to get the filename for
1658 * @return NULL on error, otherwise filename that
1659 * can be passed to "GNUNET_FS_file_information_recover"
1660 * to read this fi-struct from disk.
1663 GNUNET_FS_file_information_get_id (struct GNUNET_FS_FileInformation *s);
1668 * Create an entry for a file in a publish-structure.
1670 * @param h handle to the file sharing subsystem
1671 * @param client_info initial client-info value for this entry
1672 * @param filename name of the file or directory to publish
1673 * @param keywords under which keywords should this file be available
1674 * directly; can be NULL
1675 * @param meta metadata for the file
1676 * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
1677 * GNUNET_SYSERR for simulation
1678 * @param anonymity what is the desired anonymity level for sharing?
1679 * @param priority what is the priority for OUR node to
1680 * keep this file available? Use 0 for maximum anonymity and
1681 * minimum reliability...
1682 * @param expirationTime when should this content expire?
1683 * @return publish structure entry for the file
1685 struct GNUNET_FS_FileInformation *
1686 GNUNET_FS_file_information_create_from_file (struct GNUNET_FS_Handle *h,
1688 const char *filename,
1689 const struct GNUNET_FS_Uri *keywords,
1690 const struct GNUNET_CONTAINER_MetaData *meta,
1694 struct GNUNET_TIME_Absolute expirationTime);
1698 * Create an entry for a file in a publish-structure.
1700 * @param h handle to the file sharing subsystem
1701 * @param client_info initial client-info value for this entry
1702 * @param length length of the file
1703 * @param data data for the file (should not be used afterwards by
1704 * the caller; callee will "free")
1705 * @param keywords under which keywords should this file be available
1706 * directly; can be NULL
1707 * @param meta metadata for the file
1708 * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
1709 * GNUNET_SYSERR for simulation
1710 * @param anonymity what is the desired anonymity level for sharing?
1711 * @param priority what is the priority for OUR node to
1712 * keep this file available? Use 0 for maximum anonymity and
1713 * minimum reliability...
1714 * @param expirationTime when should this content expire?
1715 * @return publish structure entry for the file
1717 struct GNUNET_FS_FileInformation *
1718 GNUNET_FS_file_information_create_from_data (struct GNUNET_FS_Handle *h,
1722 const struct GNUNET_FS_Uri *keywords,
1723 const struct GNUNET_CONTAINER_MetaData *meta,
1727 struct GNUNET_TIME_Absolute expirationTime);
1731 * Function that provides data.
1733 * @param cls closure
1734 * @param offset offset to read from; it is possible
1735 * that the caller might need to go backwards
1737 * @param max maximum number of bytes that should be
1738 * copied to buf; readers are not allowed
1739 * to provide less data unless there is an error;
1740 * a value of "0" will be used at the end to allow
1741 * the reader to clean up its internal state
1742 * @param buf where the reader should write the data
1743 * @param emsg location for the reader to store an error message
1744 * @return number of bytes written, usually "max", 0 on error
1746 typedef size_t (*GNUNET_FS_DataReader)(void *cls,
1754 * Create an entry for a file in a publish-structure.
1756 * @param h handle to the file sharing subsystem
1757 * @param client_info initial client-info value for this entry
1758 * @param length length of the file
1759 * @param reader function that can be used to obtain the data for the file
1760 * @param reader_cls closure for "reader"
1761 * @param keywords under which keywords should this file be available
1762 * directly; can be NULL
1763 * @param meta metadata for the file
1764 * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
1765 * GNUNET_SYSERR for simulation
1766 * @param anonymity what is the desired anonymity level for sharing?
1767 * @param priority what is the priority for OUR node to
1768 * keep this file available? Use 0 for maximum anonymity and
1769 * minimum reliability...
1770 * @param expirationTime when should this content expire?
1771 * @return publish structure entry for the file
1773 struct GNUNET_FS_FileInformation *
1774 GNUNET_FS_file_information_create_from_reader (struct GNUNET_FS_Handle *h,
1777 GNUNET_FS_DataReader reader,
1779 const struct GNUNET_FS_Uri *keywords,
1780 const struct GNUNET_CONTAINER_MetaData *meta,
1784 struct GNUNET_TIME_Absolute expirationTime);
1788 * Function that a "GNUNET_FS_DirectoryScanner" should call
1789 * for each entry in the directory.
1791 * @param cls closure
1792 * @param filename name of the file (including path); must end
1793 * in a "/" (even on W32) if this is a directory
1794 * @param fi information about the file (should not be
1795 * used henceforth by the caller)
1797 typedef void (*GNUNET_FS_FileProcessor)(void *cls,
1798 const char *filename,
1799 struct GNUNET_FS_FileInformation *fi);
1803 * Type of a function that will be used to scan a directory.
1805 * @param cls closure
1806 * @param h handle to the file sharing subsystem
1807 * @param dirname name of the directory to scan
1808 * @param do_index should files be indexed or inserted
1809 * @param anonymity desired anonymity level
1810 * @param priority priority for publishing
1811 * @param expirationTime expiration for publication
1812 * @param proc function to call on each entry
1813 * @param proc_cls closure for proc
1814 * @param emsg where to store an error message (on errors)
1815 * @return GNUNET_OK on success
1817 typedef int (*GNUNET_FS_DirectoryScanner)(void *cls,
1818 struct GNUNET_FS_Handle *h,
1819 const char *dirname,
1823 struct GNUNET_TIME_Absolute expirationTime,
1824 GNUNET_FS_FileProcessor proc,
1831 * Simple, useful default implementation of a directory scanner
1832 * (GNUNET_FS_DirectoryScanner). This implementation expects to get a
1833 * UNIX filename, will publish all files in the directory except hidden
1834 * files (those starting with a "."). Metadata will be extracted
1835 * using GNU libextractor; the specific list of plugins should be
1836 * specified in "cls", passing NULL will disable (!) metadata
1837 * extraction. Keywords will be derived from the metadata and be
1838 * subject to default canonicalization. This is strictly a
1839 * convenience function.
1841 * @param cls must be of type "struct EXTRACTOR_Extractor*"
1842 * @param h handle to the file sharing subsystem
1843 * @param dirname name of the directory to scan
1844 * @param do_index should files be indexed or inserted
1845 * @param anonymity desired anonymity level
1846 * @param priority priority for publishing
1847 * @param expirationTime expiration for publication
1848 * @param proc function called on each entry
1849 * @param proc_cls closure for proc
1850 * @param emsg where to store an error message (on errors)
1851 * @return GNUNET_OK on success
1854 GNUNET_FS_directory_scanner_default (void *cls,
1855 struct GNUNET_FS_Handle *h,
1856 const char *dirname,
1860 struct GNUNET_TIME_Absolute expirationTime,
1861 GNUNET_FS_FileProcessor proc,
1867 * Create a publish-structure from an existing file hierarchy, inferring
1868 * and organizing keywords and metadata as much as possible. This
1869 * function primarily performs the recursive build and re-organizes
1870 * keywords and metadata; for automatically getting metadata
1871 * extraction, scanning of directories and creation of the respective
1872 * GNUNET_FS_FileInformation entries the default scanner should be
1873 * passed (GNUNET_FS_directory_scanner_default). This is strictly a
1874 * convenience function.
1876 * @param h handle to the file sharing subsystem
1877 * @param client_info initial client-info value for this entry
1878 * @param filename name of the top-level file or directory
1879 * @param scanner function used to get a list of files in a directory
1880 * @param scanner_cls closure for scanner
1881 * @param do_index should files in the hierarchy be indexed?
1882 * @param anonymity what is the desired anonymity level for sharing?
1883 * @param priority what is the priority for OUR node to
1884 * keep this file available? Use 0 for maximum anonymity and
1885 * minimum reliability...
1886 * @param expirationTime when should this content expire?
1887 * @param emsg where to store an error message
1888 * @return publish structure entry for the directory, NULL on error
1890 struct GNUNET_FS_FileInformation *
1891 GNUNET_FS_file_information_create_from_directory (struct GNUNET_FS_Handle *h,
1893 const char *filename,
1894 GNUNET_FS_DirectoryScanner scanner,
1899 struct GNUNET_TIME_Absolute expirationTime,
1904 * Create an entry for an empty directory in a publish-structure.
1905 * This function should be used by applications for which the
1906 * use of "GNUNET_FS_file_information_create_from_directory"
1907 * is not appropriate.
1909 * @param h handle to the file sharing subsystem
1910 * @param client_info initial client-info value for this entry
1911 * @param keywords under which keywords should this directory be available
1912 * directly; can be NULL
1913 * @param meta metadata for the directory
1914 * @param anonymity what is the desired anonymity level for sharing?
1915 * @param priority what is the priority for OUR node to
1916 * keep this file available? Use 0 for maximum anonymity and
1917 * minimum reliability...
1918 * @param expirationTime when should this content expire?
1919 * @return publish structure entry for the directory , NULL on error
1921 struct GNUNET_FS_FileInformation *
1922 GNUNET_FS_file_information_create_empty_directory (struct GNUNET_FS_Handle *h,
1924 const struct GNUNET_FS_Uri *keywords,
1925 const struct GNUNET_CONTAINER_MetaData *meta,
1928 struct GNUNET_TIME_Absolute expirationTime);
1932 * Test if a given entry represents a directory.
1934 * @param ent check if this FI represents a directory
1935 * @return GNUNET_YES if so, GNUNET_NO if not
1938 GNUNET_FS_file_information_is_directory (struct GNUNET_FS_FileInformation *ent);
1942 * Add an entry to a directory in a publish-structure. Clients
1943 * should never modify publish structures that were passed to
1944 * "GNUNET_FS_publish_start" already.
1946 * @param dir the directory
1947 * @param ent the entry to add; the entry must not have been
1948 * added to any other directory at this point and
1949 * must not include "dir" in its structure
1950 * @return GNUNET_OK on success, GNUNET_SYSERR on error
1953 GNUNET_FS_file_information_add (struct GNUNET_FS_FileInformation *dir,
1954 struct GNUNET_FS_FileInformation *ent);
1958 * Inspect a file or directory in a publish-structure. Clients
1959 * should never modify publish structures that were passed to
1960 * "GNUNET_FS_publish_start" already. When called on a directory,
1961 * this function will FIRST call "proc" with information about
1962 * the directory itself and then for each of the files in the
1963 * directory (but not for files in subdirectories). When called
1964 * on a file, "proc" will be called exactly once (with information
1965 * about the specific file).
1967 * @param dir the directory
1968 * @param proc function to call on each entry
1969 * @param proc_cls closure for proc
1972 GNUNET_FS_file_information_inspect (struct GNUNET_FS_FileInformation *dir,
1973 GNUNET_FS_FileInformationProcessor proc,
1978 * Destroy publish-structure. Clients should never destroy publish
1979 * structures that were passed to "GNUNET_FS_publish_start" already.
1981 * @param fi structure to destroy
1982 * @param cleaner function to call on each entry in the structure
1983 * (useful to clean up client_info); can be NULL; return
1984 * values are ignored
1985 * @param cleaner_cls closure for cleaner
1988 GNUNET_FS_file_information_destroy (struct GNUNET_FS_FileInformation *fi,
1989 GNUNET_FS_FileInformationProcessor cleaner,
1994 * Options for publishing. Compatible options
1995 * can be OR'ed together.
1997 enum GNUNET_FS_PublishOptions
2000 * No options (use defaults for everything).
2002 GNUNET_FS_PUBLISH_OPTION_NONE = 0,
2005 * Simulate publishing. With this option, no data will be stored
2006 * in the datastore. Useful for computing URIs from files.
2008 GNUNET_FS_PUBLISH_OPTION_SIMULATE_ONLY = 1
2012 * Publish a file or directory.
2014 * @param h handle to the file sharing subsystem
2015 * @param fi information about the file or directory structure to publish
2016 * @param namespace namespace to publish the file in, NULL for no namespace
2017 * @param nid identifier to use for the publishd content in the namespace
2018 * (can be NULL, must be NULL if namespace is NULL)
2019 * @param nuid update-identifier that will be used for future updates
2020 * (can be NULL, must be NULL if namespace or nid is NULL)
2021 * @param options options for the publication
2022 * @return context that can be used to control the publish operation
2024 struct GNUNET_FS_PublishContext *
2025 GNUNET_FS_publish_start (struct GNUNET_FS_Handle *h,
2026 struct GNUNET_FS_FileInformation *fi,
2027 struct GNUNET_FS_Namespace *namespace,
2030 enum GNUNET_FS_PublishOptions options);
2034 * Stop a publication. Will abort incomplete publications (but
2035 * not remove blocks that have already been published) or
2036 * simply clean up the state for completed publications.
2037 * Must NOT be called from within the event callback!
2039 * @param pc context for the publication to stop
2042 GNUNET_FS_publish_stop (struct GNUNET_FS_PublishContext *pc);
2046 * Signature of a function called as the continuation of a KBlock or
2047 * SBlock publication.
2049 * @param cls closure
2050 * @param uri URI under which the block is now available, NULL on error
2051 * @param emsg error message, NULL on success
2053 typedef void (*GNUNET_FS_PublishContinuation)(void *cls,
2054 const struct GNUNET_FS_Uri *uri,
2059 * Publish a KBlock on GNUnet.
2061 * @param h handle to the file sharing subsystem
2062 * @param ksk_uri keywords to use
2063 * @param meta metadata to use
2064 * @param uri URI to refer to in the KBlock
2065 * @param expirationTime when the KBlock expires
2066 * @param anonymity anonymity level for the KBlock
2067 * @param priority priority for the KBlock
2068 * @param cont continuation
2069 * @param cont_cls closure for cont
2072 GNUNET_FS_publish_ksk (struct GNUNET_FS_Handle *h,
2073 const struct GNUNET_FS_Uri *ksk_uri,
2074 const struct GNUNET_CONTAINER_MetaData *meta,
2075 const struct GNUNET_FS_Uri *uri,
2076 struct GNUNET_TIME_Absolute expirationTime,
2079 enum GNUNET_FS_PublishOptions options,
2080 GNUNET_FS_PublishContinuation cont,
2085 * Publish an SBlock on GNUnet.
2087 * @param h handle to the file sharing subsystem
2088 * @param namespace namespace to publish in
2089 * @param identifier identifier to use
2090 * @param update update identifier to use
2091 * @param meta metadata to use
2092 * @param uri URI to refer to in the SBlock
2093 * @param expirationTime when the SBlock expires
2094 * @param anonymity anonymity level for the SBlock
2095 * @param priority priority for the SBlock
2096 * @param cont continuation
2097 * @param cont_cls closure for cont
2100 GNUNET_FS_publish_sks (struct GNUNET_FS_Handle *h,
2101 struct GNUNET_FS_Namespace *namespace,
2102 const char *identifier,
2104 const struct GNUNET_CONTAINER_MetaData *meta,
2105 const struct GNUNET_FS_Uri *uri,
2106 struct GNUNET_TIME_Absolute expirationTime,
2109 enum GNUNET_FS_PublishOptions options,
2110 GNUNET_FS_PublishContinuation cont,
2115 * Type of a function called by "GNUNET_FS_get_indexed_files".
2117 * @param cls closure
2118 * @param filename the name of the file
2119 * @param file_id hash of the contents of the indexed file
2120 * @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort
2122 typedef int (*GNUNET_FS_IndexedFileProcessor) (void *cls,
2123 const char *filename,
2124 const GNUNET_HashCode *file_id);
2128 * Iterate over all indexed files.
2130 * @param h handle to the file sharing subsystem
2131 * @param iterator function to call on each indexed file
2132 * @param iterator_cls closure for iterator
2133 * @param cont continuation to call when done;
2134 * reason should be "TIMEOUT" (on
2135 * error) or "PREREQ_DONE" (on success)
2136 * @param cont_cls closure for cont
2139 GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h,
2140 GNUNET_FS_IndexedFileProcessor iterator,
2142 GNUNET_SCHEDULER_Task cont,
2149 * @param h handle to the file sharing subsystem
2150 * @param filename file to unindex
2151 * @param cctx initial value for the client context
2152 * @return NULL on error, otherwise handle
2154 struct GNUNET_FS_UnindexContext *
2155 GNUNET_FS_unindex_start (struct GNUNET_FS_Handle *h,
2156 const char *filename,
2161 * Clean up after completion of an unindex operation.
2166 GNUNET_FS_unindex_stop (struct GNUNET_FS_UnindexContext *uc);
2170 * Publish an advertismement for a namespace.
2172 * @param h handle to the file sharing subsystem
2173 * @param ksk_uri keywords to use for advertisment
2174 * @param namespace handle for the namespace that should be advertised
2175 * @param meta meta-data for the namespace advertisement
2176 * @param anonymity for the namespace advertismement
2177 * @param priority for the namespace advertisement
2178 * @param expiration for the namespace advertisement
2179 * @param rootEntry name of the root of the namespace
2180 * @param cont continuation
2181 * @param cont_cls closure for cont
2184 GNUNET_FS_namespace_advertise (struct GNUNET_FS_Handle *h,
2185 struct GNUNET_FS_Uri *ksk_uri,
2186 struct GNUNET_FS_Namespace *namespace,
2187 const struct GNUNET_CONTAINER_MetaData *meta,
2190 struct GNUNET_TIME_Absolute expiration,
2191 const char *rootEntry,
2192 GNUNET_FS_PublishContinuation cont,
2197 * Create a namespace with the given name; if one already
2198 * exists, return a handle to the existing namespace.
2200 * @param h handle to the file sharing subsystem
2201 * @param name name to use for the namespace
2202 * @return handle to the namespace, NULL on error
2204 struct GNUNET_FS_Namespace *
2205 GNUNET_FS_namespace_create (struct GNUNET_FS_Handle *h,
2210 * Delete a namespace handle. Can be used for a clean shutdown (free
2211 * memory) or also to freeze the namespace to prevent further
2212 * insertions by anyone.
2214 * @param namespace handle to the namespace that should be deleted / freed
2215 * @param freeze prevents future insertions; creating a namespace
2216 * with the same name again will create a fresh namespace instead
2218 * @return GNUNET_OK on success, GNUNET_SYSERR on error
2221 GNUNET_FS_namespace_delete (struct GNUNET_FS_Namespace *namespace,
2226 * Callback with information about local (!) namespaces.
2227 * Contains the names of the local namespace and the global
2230 * @param cls closure
2231 * @param name human-readable identifier of the namespace
2232 * @param id hash identifier for the namespace
2234 typedef void (*GNUNET_FS_NamespaceInfoProcessor) (void *cls,
2236 const GNUNET_HashCode *id);
2240 * Build a list of all available local (!) namespaces The returned
2241 * names are only the nicknames since we only iterate over the local
2244 * @param h handle to the file sharing subsystem
2245 * @param cb function to call on each known namespace
2246 * @param cb_cls closure for cb
2249 GNUNET_FS_namespace_list (struct GNUNET_FS_Handle *h,
2250 GNUNET_FS_NamespaceInfoProcessor cb,
2255 * Function called on updateable identifiers.
2257 * @param cls closure
2258 * @param last_id last identifier
2259 * @param last_uri uri used for the content published under the last_id
2260 * @param last_meta metadata associated with last_uri
2261 * @param next_id identifier that should be used for updates
2264 (*GNUNET_FS_IdentifierProcessor)(void *cls,
2265 const char *last_id,
2266 const struct GNUNET_FS_Uri *last_uri,
2267 const struct GNUNET_CONTAINER_MetaData *last_meta,
2268 const char *next_id);
2272 * List all of the identifiers in the namespace for which we could
2273 * produce an update. Namespace updates form a graph where each node
2274 * has a name. Each node can have any number of URI/meta-data entries
2275 * which can each be linked to other nodes. Cycles are possible.
2277 * Calling this function with "next_id" NULL will cause the library to
2278 * call "ip" with a root for each strongly connected component of the
2279 * graph (a root being a node from which all other nodes in the Scc
2282 * Calling this function with "next_id" being the name of a node will
2283 * cause the library to call "ip" with all children of the node. Note
2284 * that cycles within an SCC are possible (including self-loops).
2286 * @param namespace namespace to inspect for updateable content
2287 * @param next_id ID to look for; use NULL to look for SCC roots
2288 * @param ip function to call on each updateable identifier
2289 * @param ip_cls closure for ip
2292 GNUNET_FS_namespace_list_updateable (struct GNUNET_FS_Namespace *namespace,
2293 const char *next_id,
2294 GNUNET_FS_IdentifierProcessor ip,
2299 * Options for searching. Compatible options
2300 * can be OR'ed together.
2302 enum GNUNET_FS_SearchOptions
2305 * No options (use defaults for everything).
2307 GNUNET_FS_SEARCH_OPTION_NONE = 0,
2310 * Only search the local host, do not search remote systems (no P2P)
2312 GNUNET_FS_SEARCH_OPTION_LOOPBACK_ONLY = 1
2318 * Start search for content.
2320 * @param h handle to the file sharing subsystem
2321 * @param uri specifies the search parameters; can be
2322 * a KSK URI or an SKS URI.
2323 * @param anonymity desired level of anonymity
2324 * @param options options for the search
2325 * @param cctx initial value for the client context
2326 * @return context that can be used to control the search
2328 struct GNUNET_FS_SearchContext *
2329 GNUNET_FS_search_start (struct GNUNET_FS_Handle *h,
2330 const struct GNUNET_FS_Uri *uri,
2332 enum GNUNET_FS_SearchOptions options,
2339 * @param sc context for the search that should be paused
2342 GNUNET_FS_search_pause (struct GNUNET_FS_SearchContext *sc);
2346 * Continue paused search.
2348 * @param sc context for the search that should be resumed
2351 GNUNET_FS_search_continue (struct GNUNET_FS_SearchContext *sc);
2355 * Stop search for content.
2357 * @param sc context for the search that should be stopped
2360 GNUNET_FS_search_stop (struct GNUNET_FS_SearchContext *sc);
2366 * Options for downloading. Compatible options
2367 * can be OR'ed together.
2369 enum GNUNET_FS_DownloadOptions
2372 * No options (use defaults for everything).
2374 GNUNET_FS_DOWNLOAD_OPTION_NONE = 0,
2377 * Only download from the local host, do not access remote systems (no P2P)
2379 GNUNET_FS_DOWNLOAD_OPTION_LOOPBACK_ONLY = 1,
2382 * Do a recursive download (that is, automatically trigger the
2383 * download of files in directories).
2385 GNUNET_FS_DOWNLOAD_OPTION_RECURSIVE = 2,
2388 * Do not append temporary data to
2389 * the target file (for the IBlocks).
2391 GNUNET_FS_DOWNLOAD_NO_TEMPORARIES = 4,
2394 * Internal option used to flag this download as a 'probe' for a
2395 * search result. Impacts the priority with which the download is
2396 * run and causes signalling callbacks to be done differently.
2397 * Also, probe downloads are not serialized on suspension. Normal
2398 * clients should not use this!
2400 GNUNET_FS_DOWNLOAD_IS_PROBE = (1<<31)
2407 * Download parts of a file. Note that this will store
2408 * the blocks at the respective offset in the given file. Also, the
2409 * download is still using the blocking of the underlying FS
2410 * encoding. As a result, the download may *write* outside of the
2411 * given boundaries (if offset and length do not match the 32k FS
2412 * block boundaries). <p>
2414 * The given range can be used to focus a download towards a
2415 * particular portion of the file (optimization), not to strictly
2416 * limit the download to exactly those bytes.
2418 * @param h handle to the file sharing subsystem
2419 * @param uri the URI of the file (determines what to download); CHK or LOC URI
2420 * @param meta known metadata for the file (can be NULL)
2421 * @param filename where to store the file, maybe NULL (then no file is
2422 * created on disk and data must be grabbed from the callbacks)
2423 * @param tempname where to store temporary file data, not used if filename is non-NULL;
2424 * can be NULL (in which case we will pick a name if needed); the temporary file
2425 * may already exist, in which case we will try to use the data that is there and
2426 * if it is not what is desired, will overwrite it
2427 * @param offset at what offset should we start the download (typically 0)
2428 * @param length how many bytes should be downloaded starting at offset
2429 * @param anonymity anonymity level to use for the download
2430 * @param options various download options
2431 * @param cctx initial value for the client context for this download
2432 * @param parent parent download to associate this download with (use NULL
2433 * for top-level downloads; useful for manually-triggered recursive downloads)
2434 * @return context that can be used to control this download
2436 struct GNUNET_FS_DownloadContext *
2437 GNUNET_FS_download_start (struct GNUNET_FS_Handle *h,
2438 const struct GNUNET_FS_Uri *uri,
2439 const struct GNUNET_CONTAINER_MetaData *meta,
2440 const char *filename,
2441 const char *tempname,
2445 enum GNUNET_FS_DownloadOptions options,
2447 struct GNUNET_FS_DownloadContext *parent);
2451 * Download parts of a file based on a search result. The download
2452 * will be associated with the search result (and the association
2453 * will be preserved when serializing/deserializing the state).
2454 * If the search is stopped, the download will not be aborted but
2455 * be 'promoted' to a stand-alone download.
2457 * As with the other download function, this will store
2458 * the blocks at the respective offset in the given file. Also, the
2459 * download is still using the blocking of the underlying FS
2460 * encoding. As a result, the download may *write* outside of the
2461 * given boundaries (if offset and length do not match the 32k FS
2462 * block boundaries). <p>
2464 * The given range can be used to focus a download towards a
2465 * particular portion of the file (optimization), not to strictly
2466 * limit the download to exactly those bytes.
2468 * @param h handle to the file sharing subsystem
2469 * @param sr the search result to use for the download (determines uri and
2470 * meta data and associations)
2471 * @param filename where to store the file, maybe NULL (then no file is
2472 * created on disk and data must be grabbed from the callbacks)
2473 * @param tempname where to store temporary file data, not used if filename is non-NULL;
2474 * can be NULL (in which case we will pick a name if needed); the temporary file
2475 * may already exist, in which case we will try to use the data that is there and
2476 * if it is not what is desired, will overwrite it
2477 * @param offset at what offset should we start the download (typically 0)
2478 * @param length how many bytes should be downloaded starting at offset
2479 * @param anonymity anonymity level to use for the download
2480 * @param options various download options
2481 * @param cctx initial value for the client context for this download
2482 * @return context that can be used to control this download
2484 struct GNUNET_FS_DownloadContext *
2485 GNUNET_FS_download_start_from_search (struct GNUNET_FS_Handle *h,
2486 struct GNUNET_FS_SearchResult *sr,
2487 const char *filename,
2488 const char *tempname,
2492 enum GNUNET_FS_DownloadOptions options,
2497 * Stop a download (aborts if download is incomplete).
2499 * @param dc handle for the download
2500 * @param do_delete delete files of incomplete downloads
2503 GNUNET_FS_download_stop (struct GNUNET_FS_DownloadContext *dc,
2508 /* ******************** Directory API *********************** */
2511 #define GNUNET_FS_DIRECTORY_MIME "application/gnunet-directory"
2512 #define GNUNET_FS_DIRECTORY_MAGIC "\211GND\r\n\032\n"
2513 #define GNUNET_FS_DIRECTORY_EXT ".gnd"
2516 * Does the meta-data claim that this is a directory?
2517 * Checks if the mime-type is that of a GNUnet directory.
2519 * @return GNUNET_YES if it is, GNUNET_NO if it is not, GNUNET_SYSERR if
2520 * we have no mime-type information (treat as 'GNUNET_NO')
2523 GNUNET_FS_meta_data_test_for_directory (const struct GNUNET_CONTAINER_MetaData *md);
2527 * Set the MIMETYPE information for the given
2528 * metadata to "application/gnunet-directory".
2530 * @param md metadata to add mimetype to
2533 GNUNET_FS_meta_data_make_directory (struct GNUNET_CONTAINER_MetaData *md);
2537 * Suggest a filename based on given metadata.
2539 * @param md given meta data
2540 * @return NULL if meta data is useless for suggesting a filename
2543 GNUNET_FS_meta_data_suggest_filename (const struct GNUNET_CONTAINER_MetaData *md);
2547 * Function used to process entries in a directory.
2549 * @param cls closure
2550 * @param filename name of the file in the directory
2551 * @param uri URI of the file
2552 * @param metadata metadata for the file; metadata for
2553 * the directory if everything else is NULL/zero
2554 * @param length length of the available data for the file
2555 * (of type size_t since data must certainly fit
2556 * into memory; if files are larger than size_t
2557 * permits, then they will certainly not be
2558 * embedded with the directory itself).
2559 * @param data data available for the file (length bytes)
2561 typedef void (*GNUNET_FS_DirectoryEntryProcessor)(void *cls,
2562 const char *filename,
2563 const struct GNUNET_FS_Uri *uri,
2564 const struct GNUNET_CONTAINER_MetaData *meta,
2570 * Iterate over all entries in a directory. Note that directories
2571 * are structured such that it is possible to iterate over the
2572 * individual blocks as well as over the entire directory. Thus
2573 * a client can call this function on the buffer in the
2574 * GNUNET_FS_ProgressCallback. Also, directories can optionally
2575 * include the contents of (small) files embedded in the directory
2576 * itself; for those files, the processor may be given the
2577 * contents of the file directly by this function.
2579 * @param size number of bytes in data
2580 * @param data pointer to the beginning of the directory
2581 * @param offset offset of data in the directory
2582 * @param dep function to call on each entry
2583 * @param dep_cls closure for dep
2584 * @return GNUNET_OK if this could be a block in a directory,
2585 * GNUNET_NO if this could be part of a directory (but not 100% OK)
2586 * GNUNET_SYSERR if 'data' does not represent a directory
2589 GNUNET_FS_directory_list_contents (size_t size,
2592 GNUNET_FS_DirectoryEntryProcessor dep,
2597 * Opaque handle to a directory builder.
2599 struct GNUNET_FS_DirectoryBuilder;
2602 * Create a directory builder.
2604 * @param mdir metadata for the directory
2606 struct GNUNET_FS_DirectoryBuilder *
2607 GNUNET_FS_directory_builder_create (const struct GNUNET_CONTAINER_MetaData *mdir);
2611 * Add an entry to a directory.
2613 * @param bld directory to extend
2614 * @param uri uri of the entry (must not be a KSK)
2615 * @param md metadata of the entry
2616 * @param data raw data of the entry, can be NULL, otherwise
2617 * data must point to exactly the number of bytes specified
2621 GNUNET_FS_directory_builder_add (struct GNUNET_FS_DirectoryBuilder *bld,
2622 const struct GNUNET_FS_Uri *uri,
2623 const struct GNUNET_CONTAINER_MetaData *md,
2628 * Finish building the directory. Frees the
2629 * builder context and returns the directory
2632 * @param bld directory to finish
2633 * @param rsize set to the number of bytes needed
2634 * @param rdata set to the encoded directory
2635 * @return GNUNET_OK on success
2638 GNUNET_FS_directory_builder_finish (struct GNUNET_FS_DirectoryBuilder *bld,
2643 #if 0 /* keep Emacsens' auto-indent happy */