SET service: accurate results for symmetric mode

[oweals/gnunet.git] / src / include / gnunet_fs_service.h

diff --git a/src/include/gnunet_fs_service.h b/src/include/gnunet_fs_service.h
index aa2f2076c840af526f32e0ff2ccb8d29c49c2eb7..f9c56db641cea19464a0bf0c21c5a9c24cbd8feb 100644 (file)
--- a/src/include/gnunet_fs_service.h
+++ b/src/include/gnunet_fs_service.h
@@ -1,6 +1,6 @@
 /*
      This file is part of GNUnet
-     (C) 2004--2013 Christian Grothoff (and other contributing authors)
+     Copyright (C) 2004--2013 Christian Grothoff (and other contributing authors)
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
@@ -14,8 +14,8 @@
 
      You should have received a copy of the GNU General Public License
      along with GNUnet; see the file COPYING.  If not, write to the
-     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-     Boston, MA 02111-1307, USA.
+     Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+     Boston, MA 02110-1301, USA.
 */
 /**
  * @file include/gnunet_fs_service.h
@@ -88,8 +88,10 @@ struct GNUNET_FS_Uri;
  * @param is_mandatory is the keyword mandatory (in a search)
  * @return #GNUNET_OK to continue to iterate, #GNUNET_SYSERR to abort
  */
-typedef int (*GNUNET_FS_KeywordIterator) (void *cls, const char *keyword,
-                                          int is_mandatory);
+typedef int
+(*GNUNET_FS_KeywordIterator) (void *cls,
+                              const char *keyword,
+                              int is_mandatory);
 
 
 
@@ -160,7 +162,8 @@ GNUNET_FS_uri_ksk_remove_keyword (struct GNUNET_FS_Uri *uri,
  * @return NULL on error
  */
 struct GNUNET_FS_Uri *
-GNUNET_FS_uri_parse (const char *uri, char **emsg);
+GNUNET_FS_uri_parse (const char *uri,
+                     char **emsg);
 
 
 /**
@@ -231,15 +234,19 @@ GNUNET_FS_uri_loc_get_expiration (const struct GNUNET_FS_Uri *uri);
 
 /**
  * Construct a location URI (this peer will be used for the location).
+ * This function should only be called from within gnunet-service-fs,
+ * as it requires the peer's private key which is generally unavailable
+ * to processes directly under the user's control.  However, for
+ * testing and as it logically fits under URIs, it is in this API.
  *
- * @param baseUri content offered by the sender
- * @param cfg configuration information (used to find our hostkey)
+ * @param base_uri content offered by the sender
+ * @param sign_key private key of the peer
  * @param expiration_time how long will the content be offered?
  * @return the location URI, NULL on error
  */
 struct GNUNET_FS_Uri *
-GNUNET_FS_uri_loc_create (const struct GNUNET_FS_Uri *baseUri,
-                          const struct GNUNET_CONFIGURATION_Handle *cfg,
+GNUNET_FS_uri_loc_create (const struct GNUNET_FS_Uri *base_uri,
+                          const struct GNUNET_CRYPTO_EddsaPrivateKey *sign_key,
                           struct GNUNET_TIME_Absolute expiration_time);
 
 
@@ -283,7 +290,8 @@ GNUNET_FS_uri_dup (const struct GNUNET_FS_Uri *uri);
  *  if keywords is not legal (i.e. empty).
  */
 struct GNUNET_FS_Uri *
-GNUNET_FS_uri_ksk_create (const char *keywords, char **emsg);
+GNUNET_FS_uri_ksk_create (const char *keywords,
+                          char **emsg);
 
 
 /**
@@ -434,8 +442,9 @@ GNUNET_FS_uri_ksk_create_from_meta_data (const struct GNUNET_CONTAINER_MetaData
  * @return #GNUNET_OK on success
  */
 int
-GNUNET_FS_getopt_set_keywords (struct GNUNET_GETOPT_CommandLineProcessorContext
-                               *ctx, void *scls, const char *option,
+GNUNET_FS_getopt_set_keywords (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
+                               void *scls,
+                               const char *option,
                                const char *value);
 
 
@@ -452,8 +461,9 @@ GNUNET_FS_getopt_set_keywords (struct GNUNET_GETOPT_CommandLineProcessorContext
  * @return #GNUNET_OK on success
  */
 int
-GNUNET_FS_getopt_set_metadata (struct GNUNET_GETOPT_CommandLineProcessorContext
-                               *ctx, void *scls, const char *option,
+GNUNET_FS_getopt_set_metadata (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
+                               void *scls,
+                               const char *option,
                                const char *value);
 
 
@@ -1693,16 +1703,21 @@ struct GNUNET_FS_Handle;
  */
 struct GNUNET_FS_Handle *
 GNUNET_FS_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
-                 const char *client_name, GNUNET_FS_ProgressCallback upcb,
-                 void *upcb_cls, enum GNUNET_FS_Flags flags, ...);
+                 const char *client_name, 
+                GNUNET_FS_ProgressCallback upcb,
+                 void *upcb_cls, 
+                enum GNUNET_FS_Flags flags,
+                ...);
 
 
 /**
  * Close our connection with the file-sharing service.
- * The callback given to GNUNET_FS_start will no longer be
+ * The callback given to #GNUNET_FS_start() will no longer be
  * called after this function returns.
+ * This function MUST NOT be called from within the
+ * callback itself.
  *
- * @param h handle that was returned from GNUNET_FS_start
+ * @param h handle that was returned from #GNUNET_FS_start()
  */
 void
 GNUNET_FS_stop (struct GNUNET_FS_Handle *h);