use enum GNUNET_ATS_Network_Type instead of uint32_t where appropriate

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

diff --git a/src/include/gnunet_peerinfo_service.h b/src/include/gnunet_peerinfo_service.h
index 158eae6022f08e7fc46b756061f5f20c500ff6c5..9608d37024ce5f6edff850199e087371ee88b528 100644 (file)
--- a/src/include/gnunet_peerinfo_service.h
+++ b/src/include/gnunet_peerinfo_service.h
@@ -58,7 +58,6 @@ struct GNUNET_PEERINFO_Handle *
 GNUNET_PEERINFO_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 
 
-
 /**
  * Disconnect from the peerinfo service.  Note that all iterators must
  * have completed or have been cancelled by the time this function is
@@ -72,6 +71,22 @@ void
 GNUNET_PEERINFO_disconnect (struct GNUNET_PEERINFO_Handle *h);
 
 
+/**
+ * Continuation called with a status result.
+ *
+ * @param cls closure
+ * @param emsg error message, NULL on success
+ */
+typedef void (*GNUNET_PEERINFO_Continuation)(void *cls,
+                                            const char *emsg);
+
+
+/**
+ * Opaque handle to cancel 'add' operation.
+ */
+struct GNUNET_PEERINFO_AddContext;
+
+
 /**
  * Add a host to the persistent list.  This method operates in
  * semi-reliable mode: if the transmission is not completed by
@@ -82,10 +97,29 @@ GNUNET_PEERINFO_disconnect (struct GNUNET_PEERINFO_Handle *h);
  *
  * @param h handle to the peerinfo service
  * @param hello the verified (!) HELLO message
+ * @param cont continuation to call when done, NULL is allowed
+ * @param cont_cls closure for 'cont'
+ * @return handle to cancel add operation; all pending
+ *         'add' operations will be cancelled automatically
+ *        on disconnect, so it is not necessary to keep this
+ *        handle (unless 'cont' is NULL and at some point
+ *        calling 'cont' must be prevented)
  */
-void
+struct GNUNET_PEERINFO_AddContext *
 GNUNET_PEERINFO_add_peer (struct GNUNET_PEERINFO_Handle *h,
-                          const struct GNUNET_HELLO_Message *hello);
+                          const struct GNUNET_HELLO_Message *hello,
+                         GNUNET_PEERINFO_Continuation cont,
+                         void *cont_cls);
+
+
+/**
+ * Cancel pending 'add' operation.  Must only be called before
+ * either 'cont' or 'GNUNET_PEERINFO_disconnect' are invoked.
+ *
+ * @param ac handle for the add operation to cancel
+ */
+void
+GNUNET_PEERINFO_add_peer_cancel (struct GNUNET_PEERINFO_AddContext *ac);
 
 
 /**
@@ -111,28 +145,28 @@ struct GNUNET_PEERINFO_IteratorContext;
 
 
 /**
- * Call a method for each known matching host and change its trust
- * value.  The callback method will be invoked once for each matching
- * host and then finally once with a NULL pointer.  After that final
- * invocation, the iterator context must no longer be used.
+ * Call a method for each known matching host.  The callback method
+ * will be invoked once for each matching host and then finally once
+ * with a NULL pointer.  After that final invocation, the iterator
+ * context must no longer be used.
  *
- * Instead of calling this function with 'peer == NULL'
- * it is often better to use 'GNUNET_PEERINFO_notify'.
+ * Instead of calling this function with 'peer == NULL' it is often
+ * better to use 'GNUNET_PEERINFO_notify'.
  *
  * @param h handle to the peerinfo service
+ * @param include_friend_only include HELLO messages for friends only
  * @param peer restrict iteration to this peer only (can be NULL)
  * @param timeout how long to wait until timing out
  * @param callback the method to call for each peer
  * @param callback_cls closure for callback
- * @return NULL on error (in this case, 'callback' is never called!),
- *         otherwise an iterator context
+ * @return iterator context
  */
 struct GNUNET_PEERINFO_IteratorContext *
 GNUNET_PEERINFO_iterate (struct GNUNET_PEERINFO_Handle *h,
+                        int include_friend_only,
                          const struct GNUNET_PeerIdentity *peer,
                          struct GNUNET_TIME_Relative timeout,
-                         GNUNET_PEERINFO_Processor callback,
-                         void *callback_cls);
+                         GNUNET_PEERINFO_Processor callback, void *callback_cls);
 
 
 
@@ -155,17 +189,21 @@ struct GNUNET_PEERINFO_NotifyContext;
 /**
  * Call a method whenever our known information about peers
  * changes.  Initially calls the given function for all known
- * peers and then only signals changes.  Note that it is
- * possible (i.e. on disconnects) that the callback is called
- * twice with the same peer information.
+ * peers and then only signals changes.
+ *
+ * If include_friend_only is set to GNUNET_YES peerinfo will include HELLO
+ * messages which are intended for friend to friend mode and which do not
+ * have to be gossiped. Otherwise these messages are skipped.
  *
  * @param cfg configuration to use
+ * @param include_friend_only include HELLO messages for friends only
  * @param callback the method to call for each peer
  * @param callback_cls closure for callback
  * @return NULL on error
  */
 struct GNUNET_PEERINFO_NotifyContext *
 GNUNET_PEERINFO_notify (const struct GNUNET_CONFIGURATION_Handle *cfg,
+                       int include_friend_only,
                         GNUNET_PEERINFO_Processor callback, void *callback_cls);