flush peer respect value on disconnect
[oweals/gnunet.git] / src / fs / fs_api.h
index d43da2028f55cc9f4ea5feb84c458371f4e7077f..157662a65b52b5ae51417690e08003cdf152a20c 100644 (file)
@@ -416,15 +416,17 @@ struct GNUNET_FS_FileInformation
  * @param cls closure
  * @param client handle to use for FS communication
  */
-typedef void (*GNUNET_FS_QueueStart) (void *cls,
-                                      struct GNUNET_CLIENT_Connection * client);
+typedef void
+(*GNUNET_FS_QueueStart) (void *cls,
+                         struct GNUNET_CLIENT_Connection *client);
 
 
 /**
  * The job must now stop to run and should destry the client handle as
  * soon as possible (ideally prior to returning).
  */
-typedef void (*GNUNET_FS_QueueStop) (void *cls);
+typedef void
+(*GNUNET_FS_QueueStop) (void *cls);
 
 
 
@@ -530,6 +532,16 @@ struct GNUNET_FS_SearchResult
    */
   struct GNUNET_FS_Handle *h;
 
+  /**
+   * Kept in a DLL while probing.
+   */
+  struct GNUNET_FS_SearchResult *next;
+
+  /**
+   * Kept in a DLL while probing.
+   */
+  struct GNUNET_FS_SearchResult *prev;
+
   /**
    * Search context this result belongs to; can be NULL
    * for probes that come from a directory result.
@@ -591,12 +603,6 @@ struct GNUNET_FS_SearchResult
    */
   GNUNET_SCHEDULER_TaskIdentifier probe_cancel_task;
 
-  /**
-   * Task we use to report periodically to the application that the
-   * probe is still running.
-   */
-  GNUNET_SCHEDULER_TaskIdentifier probe_ping_task;
-
   /**
    * When did the current probe become active?
    */
@@ -651,8 +657,11 @@ struct GNUNET_FS_SearchResult
  * @return queue handle
  */
 struct GNUNET_FS_QueueEntry *
-GNUNET_FS_queue_ (struct GNUNET_FS_Handle *h, GNUNET_FS_QueueStart start,
-                  GNUNET_FS_QueueStop stop, void *cls, unsigned int blocks,
+GNUNET_FS_queue_ (struct GNUNET_FS_Handle *h,
+                  GNUNET_FS_QueueStart start,
+                  GNUNET_FS_QueueStop stop,
+                  void *cls,
+                  unsigned int blocks,
                  enum GNUNET_FS_QueuePriority priority);
 
 
@@ -673,7 +682,7 @@ GNUNET_FS_dequeue_ (struct GNUNET_FS_QueueEntry *qe);
  *            that the caller might need to go backwards
  *            a bit at times
  * @param max maximum number of bytes that should be
- *            copied to buf; readers are not allowed
+ *            copied to @a buf; readers are not allowed
  *            to provide less data unless there is an error;
  *            a value of "0" will be used at the end to allow
  *            the reader to clean up its internal state
@@ -682,12 +691,15 @@ GNUNET_FS_dequeue_ (struct GNUNET_FS_QueueEntry *qe);
  * @return number of bytes written, usually "max", 0 on error
  */
 size_t
-GNUNET_FS_data_reader_file_ (void *cls, uint64_t offset, size_t max, void *buf,
+GNUNET_FS_data_reader_file_ (void *cls,
+                             uint64_t offset,
+                             size_t max,
+                             void *buf,
                              char **emsg);
 
 
 /**
- * Create the closure for the 'GNUNET_FS_data_reader_file_' callback.
+ * Create the closure for the #GNUNET_FS_data_reader_file_() callback.
  *
  * @param filename file to read
  * @return closure to use
@@ -705,23 +717,26 @@ GNUNET_FS_make_file_reader_context_ (const char *filename);
  *            that the caller might need to go backwards
  *            a bit at times
  * @param max maximum number of bytes that should be
- *            copied to buf; readers are not allowed
+ *            copied to @a buf; readers are not allowed
  *            to provide less data unless there is an error;
  *            a value of "0" will be used at the end to allow
  *            the reader to clean up its internal state
  * @param buf where the reader should write the data
  * @param emsg location for the reader to store an error message
- * @return number of bytes written, usually "max", 0 on error
+ * @return number of bytes written, usually @a max, 0 on error
  */
 size_t
-GNUNET_FS_data_reader_copy_ (void *cls, uint64_t offset, size_t max, void *buf,
+GNUNET_FS_data_reader_copy_ (void *cls,
+                             uint64_t offset,
+                             size_t max,
+                             void *buf,
                              char **emsg);
 
 
 /**
  * Notification of FS that a search probe has made progress.
  * This function is used INSTEAD of the client's event handler
- * for downloads where the GNUNET_FS_DOWNLOAD_IS_PROBE flag is set.
+ * for downloads where the #GNUNET_FS_DOWNLOAD_IS_PROBE flag is set.
  *
  * @param cls closure, always NULL (!), actual closure
  *        is in the client-context of the info struct
@@ -731,7 +746,7 @@ GNUNET_FS_data_reader_copy_ (void *cls, uint64_t offset, size_t max, void *buf,
  *         for this operation; should be set to NULL for
  *         SUSPEND and STOPPED events).  The value returned
  *         will be passed to future callbacks in the respective
- *         field in the GNUNET_FS_ProgressInfo struct.
+ *         field in the `struct GNUNET_FS_ProgressInfo`.
  */
 void *
 GNUNET_FS_search_probe_progress_ (void *cls,
@@ -757,7 +772,8 @@ GNUNET_FS_publish_main_ (void *cls,
  * @param file_id computed hash, NULL on error
  */
 void
-GNUNET_FS_unindex_process_hash_ (void *cls, const struct GNUNET_HashCode * file_id);
+GNUNET_FS_unindex_process_hash_ (void *cls,
+                                 const struct GNUNET_HashCode *file_id);
 
 
 /**
@@ -883,6 +899,7 @@ GNUNET_FS_download_start_downloading_ (struct GNUNET_FS_DownloadContext *dc);
 void
 GNUNET_FS_search_start_probe_ (struct GNUNET_FS_SearchResult *sr);
 
+
 /**
  * Remove serialization/deserialization file from disk.
  *
@@ -891,7 +908,8 @@ GNUNET_FS_search_start_probe_ (struct GNUNET_FS_SearchResult *sr);
  * @param ent entity identifier
  */
 void
-GNUNET_FS_remove_sync_file_ (struct GNUNET_FS_Handle *h, const char *ext,
+GNUNET_FS_remove_sync_file_ (struct GNUNET_FS_Handle *h,
+                             const char *ext,
                              const char *ent);
 
 
@@ -903,7 +921,8 @@ GNUNET_FS_remove_sync_file_ (struct GNUNET_FS_Handle *h, const char *ext,
  * @param uni unique name of parent
  */
 void
-GNUNET_FS_remove_sync_dir_ (struct GNUNET_FS_Handle *h, const char *ext,
+GNUNET_FS_remove_sync_dir_ (struct GNUNET_FS_Handle *h,
+                            const char *ext,
                             const char *uni);
 
 
@@ -983,7 +1002,7 @@ GNUNET_FS_download_sync_ (struct GNUNET_FS_DownloadContext *dc);
  * Create SUSPEND event for the given publish operation
  * and then clean up our state (without stop signal).
  *
- * @param cls the 'struct GNUNET_FS_PublishContext' to signal for
+ * @param cls the `struct GNUNET_FS_PublishContext` to signal for
  */
 void
 GNUNET_FS_publish_signal_suspend_ (void *cls);
@@ -1003,7 +1022,7 @@ GNUNET_FS_search_signal_suspend_ (void *cls);
  * Create SUSPEND event for the given download operation
  * and then clean up our state (without stop signal).
  *
- * @param cls the 'struct GNUNET_FS_DownloadContext' to signal for
+ * @param cls the `struct GNUNET_FS_DownloadContext` to signal for
  */
 void
 GNUNET_FS_download_signal_suspend_ (void *cls);
@@ -1013,7 +1032,7 @@ GNUNET_FS_download_signal_suspend_ (void *cls);
  * Create SUSPEND event for the given unindex operation
  * and then clean up our state (without stop signal).
  *
- * @param cls the 'struct GNUNET_FS_UnindexContext' to signal for
+ * @param cls the `struct GNUNET_FS_UnindexContext` to signal for
  */
 void
 GNUNET_FS_unindex_signal_suspend_ (void *cls);
@@ -1137,12 +1156,28 @@ struct GNUNET_FS_Handle
    */
   struct GNUNET_FS_QueueEntry *pending_tail;
 
+  /**
+   * Head of active probes.
+   */
+  struct GNUNET_FS_SearchResult *probes_head;
+
+  /**
+   * Tail of active probes.
+   */
+  struct GNUNET_FS_SearchResult *probes_tail;
+
   /**
    * Task that processes the jobs in the running and pending queues
    * (and moves jobs around as needed).
    */
   GNUNET_SCHEDULER_TaskIdentifier queue_job;
 
+  /**
+   * Task we use to report periodically to the application that
+   * certain search probes (from @e probes_head) are still running.
+   */
+  GNUNET_SCHEDULER_TaskIdentifier probe_ping_task;
+
   /**
    * Average time we take for a single request to be satisfied.
    * FIXME: not yet calcualted properly...
@@ -1187,6 +1222,11 @@ struct GNUNET_FS_PublishContext
    */
   struct GNUNET_FS_Handle *h;
 
+  /**
+   * Connection to FS service (only used for LOC URI signing).
+   */
+  struct GNUNET_CLIENT_Handle *fs_client;
+
   /**
    * Our top-level activity entry (if we are top-level, otherwise NULL).
    */
@@ -1563,7 +1603,7 @@ struct GNUNET_FS_SearchContext
   char *emsg;
 
   /**
-   * Map that contains a "struct GNUNET_FS_SearchResult" for each result that
+   * Map that contains a `struct GNUNET_FS_SearchResult` for each result that
    * was found in the search.  The key for each entry is the XOR of
    * the key and query in the CHK URI (as a unique identifier for the
    * search result).
@@ -1768,6 +1808,15 @@ void
 GNUNET_FS_free_download_request_ (struct DownloadRequest *dr);
 
 
+/**
+ * Stop the ping task for this search result.
+ *
+ * @param sr result to start pinging for.
+ */
+void
+GNUNET_FS_stop_probe_ping_task_ (struct GNUNET_FS_SearchResult *sr);
+
+
 /**
  * Context for controlling a download.
  */
@@ -1912,7 +1961,7 @@ struct GNUNET_FS_DownloadContext
   /**
    * ID of a task that is using this struct and that must be cancelled
    * when the download is being stopped (if not
-   * GNUNET_SCHEDULER_NO_TASK).  Used for the task that adds some
+   * #GNUNET_SCHEDULER_NO_TASK).  Used for the task that adds some
    * artificial delay when trying to reconnect to the FS service or
    * the task processing incrementally the data on disk, or the
    * task requesting blocks, etc.