client_manager: add API for async operations

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

diff --git a/src/include/gnunet_scalarproduct_service.h b/src/include/gnunet_scalarproduct_service.h
index 7a1eec91a48bc8c4c9f9c53fa7c70f41ffd92471..02920abd30d2a0f6f6775e9a9043ddf2cde584d0 100644 (file)
--- a/src/include/gnunet_scalarproduct_service.h
+++ b/src/include/gnunet_scalarproduct_service.h
@@ -1,6 +1,6 @@
 /*
       This file is part of GNUnet.
-      (C) 2013 Christian Grothoff (and other contributing authors)
+      Copyright (C) 2013, 2014 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
@@ -39,14 +39,38 @@ extern "C" {
 /**
  * Version of the scalarproduct API.
  */
-#define GNUNET_SCALARPRODUCT_VERSION 0x00000042
+#define GNUNET_SCALARPRODUCT_VERSION 0x00000044
 
+/**
+ * Result status values for the computation.
+ */
 enum GNUNET_SCALARPRODUCT_ResponseStatus
 {
-  GNUNET_SCALARPRODUCT_Status_Success = 0,
-  GNUNET_SCALARPRODUCT_Status_Failure,
-  GNUNET_SCALARPRODUCT_Status_InvalidResponse,
-  GNUNET_SCALARPRODUCT_Status_ServiceDisconnected
+
+  /**
+   * Operation is still active (never returned, used internally).
+   */
+  GNUNET_SCALARPRODUCT_STATUS_ACTIVE = 0,
+
+  /**
+   * The computation was successful.
+   */
+  GNUNET_SCALARPRODUCT_STATUS_SUCCESS,
+
+  /**
+   * We encountered some error.
+   */
+  GNUNET_SCALARPRODUCT_STATUS_FAILURE,
+
+  /**
+   * We got an invalid response.
+   */
+  GNUNET_SCALARPRODUCT_STATUS_INVALID_RESPONSE,
+
+  /**
+   * We got disconnected from the SCALARPRODUCT service.
+   */
+  GNUNET_SCALARPRODUCT_STATUS_DISCONNECTED
 };
 
 
@@ -56,6 +80,27 @@ enum GNUNET_SCALARPRODUCT_ResponseStatus
 struct GNUNET_SCALARPRODUCT_Handle;
 
 
+GNUNET_NETWORK_STRUCT_BEGIN
+
+/**
+ * An element key-value pair for scalarproduct
+ */
+struct GNUNET_SCALARPRODUCT_Element
+{
+  /**
+   * Key used to identify matching pairs of values to multiply.
+   */
+  struct GNUNET_HashCode key;
+
+  /**
+   * Value to multiply in scalar product, in NBO.
+   */
+  int64_t value GNUNET_PACKED;
+};
+
+GNUNET_NETWORK_STRUCT_END
+
+
 /**
  * Continuation called to notify client about result of the
  * operation.
@@ -63,8 +108,9 @@ struct GNUNET_SCALARPRODUCT_Handle;
  * @param cls closure
  * @param status Status of the request
  */
-typedef void (*GNUNET_SCALARPRODUCT_ContinuationWithStatus) (void *cls,
-                                                             enum GNUNET_SCALARPRODUCT_ResponseStatus status);
+typedef void
+(*GNUNET_SCALARPRODUCT_ContinuationWithStatus) (void *cls,
+                                                enum GNUNET_SCALARPRODUCT_ResponseStatus status);
 
 
 /**
@@ -74,58 +120,58 @@ typedef void (*GNUNET_SCALARPRODUCT_ContinuationWithStatus) (void *cls,
  * @param status Status of the request
  * @param result result of the computation
  */
-typedef void (*GNUNET_SCALARPRODUCT_DatumProcessor) (void *cls,
-                                                     enum GNUNET_SCALARPRODUCT_ResponseStatus status,
-                                                     gcry_mpi_t result);
+typedef void
+(*GNUNET_SCALARPRODUCT_DatumProcessor) (void *cls,
+                                        enum GNUNET_SCALARPRODUCT_ResponseStatus status,
+                                        gcry_mpi_t result);
+
 
 /**
  * Entry in the request queue per client
  */
 struct GNUNET_SCALARPRODUCT_ComputationHandle;
 
+
 /**
  * Request by Alice's client for computing a scalar product
  *
  * @param cfg the gnunet configuration handle
- * @param key Session key should be unique to the requesting client
+ * @param session_key Session key should be unique to the requesting client
  * @param peer PeerID of the other peer
  * @param elements Array of elements of the vector
- * @param element_count Number of elements in the vector
- * @param mask Array of the mask
- * @param mask_bytes number of bytes in the mask
+ * @param element_count Number of elements in the @a elements vector
  * @param cont Callback function
- * @param cont_cls Closure for @a cont
+ * @param cont_cls Closure for the @a cont callback function
  * @return a new handle for this computation
  */
 struct GNUNET_SCALARPRODUCT_ComputationHandle *
-GNUNET_SCALARPRODUCT_request (const struct GNUNET_CONFIGURATION_Handle *cfg,
-                              const struct GNUNET_HashCode *key,
+GNUNET_SCALARPRODUCT_start_computation (const struct GNUNET_CONFIGURATION_Handle *cfg,
+                              const struct GNUNET_HashCode *session_key,
                               const struct GNUNET_PeerIdentity *peer,
-                              const int32_t *elements,
+                              const struct GNUNET_SCALARPRODUCT_Element *elements,
                               uint32_t element_count,
-                              const unsigned char *mask,
-                              uint32_t mask_bytes,
                               GNUNET_SCALARPRODUCT_DatumProcessor cont,
-                              void * cont_cls);
+                              void *cont_cls);
+
 
 /**
  * Used by Bob's client to cooperate with Alice,
  *
  * @param cfg the gnunet configuration handle
- * @param key Session key unique to the requesting client
+ * @param session_key Session key unique to the requesting client
  * @param elements Array of elements of the vector
- * @param element_count Number of elements in the vector
+ * @param element_count Number of elements in the @a elements vector
  * @param cont Callback function
- * @param cont_cls Closure for @a cont
+ * @param cont_cls Closure for the @a cont callback function
  * @return a new handle for this computation
  */
 struct GNUNET_SCALARPRODUCT_ComputationHandle *
-GNUNET_SCALARPRODUCT_response (const struct GNUNET_CONFIGURATION_Handle *cfg,
-                               const struct GNUNET_HashCode *key,
-                               const int32_t *elements,
-                               uint32_t element_count,
-                               GNUNET_SCALARPRODUCT_ContinuationWithStatus cont,
-                               void *cont_cls);
+GNUNET_SCALARPRODUCT_accept_computation (const struct GNUNET_CONFIGURATION_Handle *cfg,
+                                         const struct GNUNET_HashCode *key,
+                                         const struct GNUNET_SCALARPRODUCT_Element *elements,
+                                         uint32_t element_count,
+                                         GNUNET_SCALARPRODUCT_ContinuationWithStatus cont,
+                                         void *cont_cls);
 
 
 /**
@@ -137,20 +183,6 @@ GNUNET_SCALARPRODUCT_response (const struct GNUNET_CONFIGURATION_Handle *cfg,
 void
 GNUNET_SCALARPRODUCT_cancel (struct GNUNET_SCALARPRODUCT_ComputationHandle *h);
 
-
-/**
- * Cancel ALL ongoing computation or revoke our collaboration offer.
- * Closes ALL connections to the service
- *
- * FIXME: this should take an argument, and we should
- * have an explicit 'connect' API which returns an opaque
- * connection handle.  Avoid (globals) in the library!
- * @deprecated in this form
- */
-void
-GNUNET_SCALARPRODUCT_disconnect ();
-
-
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
 #endif