-remove GNUNET_MQ_impl_send_commit, make it part of send_continue, to ensure calling...

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

diff --git a/src/include/gnunet_set_service.h b/src/include/gnunet_set_service.h
index 78f4468d44d46b394276ef374fdd7e6b8bc55e75..920424b80fc8ddefadd55ec7cf2314dd508a2e90 100644 (file)
--- a/src/include/gnunet_set_service.h
+++ b/src/include/gnunet_set_service.h
@@ -208,8 +208,7 @@ typedef int (*GNUNET_SET_ElementIterator) (void *cls,
  * @param other_peer the other peer
  * @param context_msg message with application specific information from
  *        the other peer
- * @param request request from the other peer, use GNUNET_SET_accept
- *        Will be NULL if the listener failed.
+ * @param request request from the other peer (never NULL), use GNUNET_SET_accept
  *        to accept it, otherwise the request will be refused
  *        Note that we can't just return value from the listen callback,
  *        as it is also necessary to specify the set we want to do the
@@ -243,14 +242,14 @@ GNUNET_SET_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
 /**
  * Add an element to the given set.
  * After the element has been added (in the sense of being
- * transmitted to the set service), cont will be called.
- * Calls to add_element can be queued
+ * transmitted to the set service), @a cont will be called.
+ * Calls to #GNUNET_SET_add_element can be queued
  *
  * @param set set to add element to
  * @param element element to add to the set
  * @param cont continuation called after the element has been added
- * @param cont_cls closure for cont
- * @return GNUNET_OK on success, GNUNET_SYSERR if the
+ * @param cont_cls closure for @a cont
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
  *         set is invalid (e.g. the set service crashed)
  */
 int
@@ -269,8 +268,8 @@ GNUNET_SET_add_element (struct GNUNET_SET_Handle *set,
  * @param set set to remove element from
  * @param element element to remove from the set
  * @param cont continuation called after the element has been removed
- * @param cont_cls closure for cont
- * @return GNUNET_OK on success, GNUNET_SYSERR if the
+ * @param cont_cls closure for @a cont
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
  *         set is invalid (e.g. the set service crashed)
  */
 int
@@ -301,7 +300,7 @@ GNUNET_SET_destroy (struct GNUNET_SET_Handle *set);
  * @param result_mode specified how results will be returned,
  *        see 'GNUNET_SET_ResultMode'.
  * @param result_cb called on error or success
- * @param result_cls closure for result_cb
+ * @param result_cls closure for @a result_cb
  * @return a handle to cancel the operation
  */
 struct GNUNET_SET_OperationHandle *
@@ -315,8 +314,10 @@ GNUNET_SET_prepare (const struct GNUNET_PeerIdentity *other_peer,
 
 
 /**
- * Wait for set operation requests for the given application id
- * 
+ * Wait for set operation requests for the given application ID.
+ * If the connection to the set service is lost, the listener is
+ * re-created transparently with exponential backoff.
+ *
  * @param cfg configuration to use for connecting to
  *            the set service
  * @param operation operation we want to listen for
@@ -336,6 +337,8 @@ GNUNET_SET_listen (const struct GNUNET_CONFIGURATION_Handle *cfg,
 
 /**
  * Cancel the given listen operation.
+ * After calling cancel, the listen callback for this listen handle
+ * will not be called again.
  *
  * @param lh handle for the listen operation
  */
@@ -348,7 +351,7 @@ GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh);
  * GNUNET_SET_listen, as the 'struct GNUNET_SET_Request' becomes invalid
  * afterwards.
  * Call GNUNET_SET_commit to provide the local set to use for the operation,
- * and to begin the exchange with the remote peer. 
+ * and to begin the exchange with the remote peer.
  *
  * @param request request to accept
  * @param result_mode specified how results will be returned,
@@ -372,7 +375,7 @@ GNUNET_SET_accept (struct GNUNET_SET_Request *request,
  * set information and call the result callback with the
  * result information.
  *
- * @param oh handle to the set operation 
+ * @param oh handle to the set operation
  * @param set the set to use for the operation
  * @return GNUNET_OK on success, GNUNET_SYSERR if the
  *         set is invalid (e.g. the set service crashed)
@@ -402,9 +405,8 @@ GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh);
  * @param set the set to iterate over
  * @param iter the iterator to call for each element
  * @param cls closure for 'iter'
- * @return GNUNET_YES if every element was iterated over, GNUNET_NO
- *         if the iterator prematurely stopped, GNUNET_SYSERR if the set
- *         is invalid (e.g. the server crashed, disconnected)
+ * @return GNUNET_YES if the iteration started successfuly,
+ *         GNUNET_SYSERR if the set  is invalid (e.g. the server crashed, disconnected)
  */
 int
 GNUNET_SET_iterate (struct GNUNET_SET_Handle *set, GNUNET_SET_ElementIterator iter, void *cls);