X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_scalarproduct_service.h;h=5d61946bb2e2813a6c0d888a24afdb41332652a8;hb=634aea297cc983c3d70f65a004f698f215abe590;hp=743a7365d12c3be0e9a8c96d2c6cece25eca1807;hpb=22ab4538a2f7a21c0c831599a56d50c147de0ae5;p=oweals%2Fgnunet.git

diff --git a/src/include/gnunet_scalarproduct_service.h b/src/include/gnunet_scalarproduct_service.h
index 743a7365d..5d61946bb 100644
--- a/src/include/gnunet_scalarproduct_service.h
+++ b/src/include/gnunet_scalarproduct_service.h
@@ -1,33 +1,37 @@
 /*
       This file is part of GNUnet.
-      (C) 2013 Christian Grothoff (and other contributing authors)
+      Copyright (C) 2013, 2014 GNUnet e.V.
 
-      GNUnet is free software; you can redistribute it and/or modify
-      it under the terms of the GNU General Public License as published
-      by the Free Software Foundation; either version 2, or (at your
-      option) any later version.
+      GNUnet is free software: you can redistribute it and/or modify it
+      under the terms of the GNU Affero General Public License as published
+      by the Free Software Foundation, either version 3 of the License,
+      or (at your option) any later version.
 
       GNUnet is distributed in the hope that it will be useful, but
       WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-      General Public License for more details.
+      Affero General Public License for more details.
+     
+      You should have received a copy of the GNU Affero General Public License
+      along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-      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.
+     SPDX-License-Identifier: AGPL3.0-or-later
  */
 
 /**
- * @file include/gnunet_vectorproduct_service.h
- * @brief API to the vectorproduct service
  * @author Christian M. Fuchs
  * @author Gaurav Kukreja
+ *
+ * @file
+ * API to the scalarproduct service
+ *
+ * @defgroup scalarproduct  Scalar Product service
+ *
+ * @{
  */
-#ifndef GNUNET_VECTORPRODUCT_SERVICE_H
-#define GNUNET_VECTORPRODUCT_SERVICE_H
+#ifndef GNUNET_SCALARPRODUCT_SERVICE_H
+#define GNUNET_SCALARPRODUCT_SERVICE_H
 #define GCRYPT_NO_DEPRECATED
-// including gcrypt crashes netbeans after the next restart...
 #include <gcrypt.h>
 
 #ifdef __cplusplus
@@ -38,221 +42,156 @@ extern "C" {
 #endif
 
 /**
- * Version of the vectorproduct API.
+ * Version of the scalarproduct API.
  */
-#define GNUNET_VECTORPRODUCT_VERSION 0x00000042
+#define GNUNET_SCALARPRODUCT_VERSION 0x00000044
 
 /**
- * Message type passed from client to service 
- * to initiate a request or responder role
+ * Result status values for the computation.
  */
-struct GNUNET_VECTORPRODUCT_client_request {
-  /**
-   * GNUNET message header
-   */
-  struct GNUNET_MessageHeader header;
-
-  /**
-   * how many elements the vector in payload contains
-   */
-  uint16_t element_count GNUNET_PACKED; 
-
-  /**
-   * how many bytes the mask has
-   */
-  uint16_t mask_length GNUNET_PACKED;
-  
-  /**
-   * the transaction/session key used to identify a session
-   */
-  struct GNUNET_HashCode key;
-
-  /**
-   * the identity of a remote peer we want to communicate with
-   */
-  struct GNUNET_PeerIdentity peer;
+enum GNUNET_SCALARPRODUCT_ResponseStatus
+{
 
   /**
-   * followed by long vector[element_count] | [unsigned char mask[mask_bytes]]
+   * Operation is still active (never returned, used internally).
    */
-};
+  GNUNET_SCALARPRODUCT_STATUS_INIT = 0,
 
-/**
- * Message type passed from service client
- * to finalize a session as requester or responder
- */
-struct GNUNET_VECTORPRODUCT_client_response {
   /**
-   * GNUNET message header
+   * Operation is still active (never returned, used internally).
    */
-  struct GNUNET_MessageHeader header;
+  GNUNET_SCALARPRODUCT_STATUS_ACTIVE = 1,
 
   /**
-   * 0 if no product attached
+   * The computation was successful.
    */
-  uint32_t product_length GNUNET_PACKED;
+  GNUNET_SCALARPRODUCT_STATUS_SUCCESS,
 
   /**
-   * the transaction/session key used to identify a session
+   * We encountered some error.
    */
-  struct GNUNET_HashCode key;
+  GNUNET_SCALARPRODUCT_STATUS_FAILURE,
 
   /**
-   * the identity of a remote peer we want to communicate with
+   * We got an invalid response.
    */
-  struct GNUNET_PeerIdentity peer;
+  GNUNET_SCALARPRODUCT_STATUS_INVALID_RESPONSE,
 
   /**
-   * followed by product of length product_length (or nothing)
+   * We got disconnected from the SCALARPRODUCT service.
    */
+  GNUNET_SCALARPRODUCT_STATUS_DISCONNECTED
 };
 
-enum GNUNET_VECTORPRODUCT_ResponseStatus {
-  GNUNET_VECTORPRODUCT_Status_Success = 0,
-  GNUNET_VECTORPRODUCT_Status_Failure,
-  GNUNET_VECTORPRODUCT_Status_Timeout,
-  GNUNET_VECTORPRODUCT_Status_InvalidResponse,
-  GNUNET_VECTORPRODUCT_Status_ServiceDisconnected
-};
-
-struct GNUNET_VECTORPRODUCT_Handle {
-  /**
-   * Our configuration.
-   */
-  const struct GNUNET_CONFIGURATION_Handle *cfg;
-
-  /**
-   * Current connection to the vectorproduct service.
-   */
-  struct GNUNET_CLIENT_Connection *client;
-
-  /**
-   * Handle for statistics.
-   */
-  struct GNUNET_STATISTICS_Handle *stats;
 
-  /**
-   * Current head of priority queue.
-   */
-  struct GNUNET_VECTORPRODUCT_QueueEntry *queue_head;
+/**
+ * Opaque declaration of the SP-Handle
+ */
+struct GNUNET_SCALARPRODUCT_Handle;
 
-  /**
-   * Current tail of priority queue.
-   */
-  struct GNUNET_VECTORPRODUCT_QueueEntry *queue_tail;
 
-  /**
-   * Are we currently trying to receive from the service?
-   */
-  int in_receive;
+GNUNET_NETWORK_STRUCT_BEGIN
 
+/**
+ * An element key-value pair for scalarproduct
+ */
+struct GNUNET_SCALARPRODUCT_Element
+{
   /**
-   * Current transmit handle.
+   * Key used to identify matching pairs of values to multiply.
    */
-  struct GNUNET_CLIENT_TransmitHandle *th;
+  struct GNUNET_HashCode key;
 
   /**
-   * TODO: What else should/could go here?
+   * Value to multiply in scalar product, in NBO.
    */
+  int64_t value GNUNET_PACKED;
 };
 
-typedef void (*GNUNET_VECTORPRODUCT_ResponseMessageHandler) (void *cls,
-        const struct GNUNET_MessageHeader *msg,
-        enum GNUNET_VECTORPRODUCT_ResponseStatus status);
+GNUNET_NETWORK_STRUCT_END
+
 
 /**
  * Continuation called to notify client about result of the
  * operation.
  *
  * @param cls closure
- * @param success GNUNET_SYSERR on failure (including timeout/queue drop)
- *                GNUNET_NO if content was already there
- *                GNUNET_YES (or other positive value) on success
- * @param msg NULL on success, otherwise an error message
+ * @param status Status of the request
  */
-typedef void (*GNUNET_VECTORPRODUCT_ContinuationWithStatus) (void *cls,
-        const struct GNUNET_HashCode * key,
-        enum GNUNET_VECTORPRODUCT_ResponseStatus status);
+typedef void
+(*GNUNET_SCALARPRODUCT_ContinuationWithStatus) (void *cls,
+                                                enum GNUNET_SCALARPRODUCT_ResponseStatus status);
+
+
 /**
- * Process a datum that was stored in the vectorproduct.
- * 
+ * Process a datum that was stored in the scalarproduct.
+ *
  * @param cls closure
- * @param key Sessioon key
- * @param peer PeerID of the peer with whom the scalar product was calculated.
  * @param status Status of the request
- * @param size Size of the received message
- * @param data Pointer to the data
- * @param type Type of data
+ * @param result result of the computation
  */
-typedef void (*GNUNET_VECTORPRODUCT_DatumProcessor) (void *cls,
-        const struct GNUNET_HashCode * key,
-        const struct GNUNET_PeerIdentity * peer,
-        enum GNUNET_VECTORPRODUCT_ResponseStatus status,
-        const struct GNUNET_VECTORPRODUCT_client_response *msg);
+typedef void
+(*GNUNET_SCALARPRODUCT_DatumProcessor) (void *cls,
+                                        enum GNUNET_SCALARPRODUCT_ResponseStatus status,
+                                        gcry_mpi_t result);
+
 
 /**
- * Request the Scalar Product Evaluation
- * 
- * @param h handle to the master context
- * @param key Session key - unique to the requesting client
- * @param peer PeerID of the other peer
- * @param element_count Number of elements in the vector
- * @param mask_bytes number of bytes in the mask
- * @param elements Array of elements of the vector
- * @param mask Array of the mask
- * @param timeout Relative timeout for the operation
- * @param cont Callback function
- * @param cont_cls Closure for the callback function
+ * Entry in the request queue per client
  */
-struct GNUNET_VECTORPRODUCT_QueueEntry *
-GNUNET_VECTORPRODUCT_request(struct GNUNET_VECTORPRODUCT_Handle *h,
-        const struct GNUNET_HashCode * key,
-        const struct GNUNET_PeerIdentity *peer,
-        uint16_t element_count,
-        uint16_t mask_bytes,
-        int32_t * elements, const unsigned char * mask,
-        struct GNUNET_TIME_Relative timeout,
-        GNUNET_VECTORPRODUCT_DatumProcessor cont,
-        void *cont_cls);
+struct GNUNET_SCALARPRODUCT_ComputationHandle;
+
 
 /**
- * Called by the responder client to prepare response
- * 
- * @param h handle to the master context
- * @param key Session key - unique to the requesting client
- * @param element_count Number of elements in the vector
- * @param mask_bytes number of bytes in the mask
+ * Request by Alice's client for computing a scalar product
+ *
+ * @param cfg the gnunet configuration handle
+ * @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 mask Array of the mask
- * @param timeout Relative timeout for the operation
+ * @param element_count Number of elements in the @a elements vector
  * @param cont Callback function
- * @param cont_cls Closure for the callback function
+ * @param cont_cls Closure for the @a cont callback function
+ * @return a new handle for this computation
  */
-struct GNUNET_VECTORPRODUCT_QueueEntry *
-GNUNET_VECTORPRODUCT_prepare_response(struct GNUNET_VECTORPRODUCT_Handle *h,
-        const struct GNUNET_HashCode * key,
-        uint16_t element_count,
-        int32_t* elements,
-        struct GNUNET_TIME_Relative timeout,
-        GNUNET_VECTORPRODUCT_ContinuationWithStatus cont,
-        void *cont_cls);
+struct GNUNET_SCALARPRODUCT_ComputationHandle *
+GNUNET_SCALARPRODUCT_start_computation (const struct GNUNET_CONFIGURATION_Handle *cfg,
+                              const struct GNUNET_HashCode *session_key,
+                              const struct GNUNET_PeerIdentity *peer,
+                              const struct GNUNET_SCALARPRODUCT_Element *elements,
+                              uint32_t element_count,
+                              GNUNET_SCALARPRODUCT_DatumProcessor cont,
+                              void *cont_cls);
+
 
 /**
- * Connect to the vectorproduct service.
+ * Used by Bob's client to cooperate with Alice,
  *
- * @param cfg configuration to use
- * @return handle to use to access the service
+ * @param cfg the gnunet configuration handle
+ * @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 @a elements vector
+ * @param cont Callback function
+ * @param cont_cls Closure for the @a cont callback function
+ * @return a new handle for this computation
  */
-struct GNUNET_VECTORPRODUCT_Handle *
-GNUNET_VECTORPRODUCT_connect(const struct GNUNET_CONFIGURATION_Handle * cfg);
+struct GNUNET_SCALARPRODUCT_ComputationHandle *
+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);
+
 
 /**
- * Disconnect from the vectorproduct service.
- * 
- * @param h handle to the vectorproduct
+ * Cancel an ongoing computation or revoke our collaboration offer.
+ * Closes the connection to the service
+ *
+ * @param h computation handle to terminate
  */
 void
-GNUNET_VECTORPRODUCT_disconnect(struct GNUNET_VECTORPRODUCT_Handle * h);
+GNUNET_SCALARPRODUCT_cancel (struct GNUNET_SCALARPRODUCT_ComputationHandle *h);
 
 
 #if 0                           /* keep Emacsens' auto-indent happy */
@@ -263,3 +202,5 @@ GNUNET_VECTORPRODUCT_disconnect(struct GNUNET_VECTORPRODUCT_Handle * h);
 #endif
 
 #endif
+
+/** @} */  /* end of group */