gnunet_scalarproduct_service.h (5208B)
1 /* 2 This file is part of GNUnet. 3 Copyright (C) 2013, 2014 GNUnet e.V. 4 5 GNUnet is free software: you can redistribute it and/or modify it 6 under the terms of the GNU Affero General Public License as published 7 by the Free Software Foundation, either version 3 of the License, 8 or (at your option) any later version. 9 10 GNUnet is distributed in the hope that it will be useful, but 11 WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Affero General Public License for more details. 14 15 You should have received a copy of the GNU Affero General Public License 16 along with this program. If not, see <http://www.gnu.org/licenses/>. 17 18 SPDX-License-Identifier: AGPL3.0-or-later 19 */ 20 /** 21 * @author Christian M. Fuchs 22 * @author Gaurav Kukreja 23 * 24 * @file 25 * API to the scalarproduct service 26 * 27 * @defgroup scalarproduct Scalar Product service 28 * 29 * @{ 30 */ 31 #ifndef GNUNET_SCALARPRODUCT_SERVICE_H 32 #define GNUNET_SCALARPRODUCT_SERVICE_H 33 #define GCRYPT_NO_DEPRECATED 34 35 #include <gcrypt.h> 36 37 #ifdef __cplusplus 38 extern "C" { 39 #if 0 /* keep Emacsens' auto-indent happy */ 40 } 41 #endif 42 #endif 43 44 /** 45 * Version of the scalarproduct API. 46 */ 47 #define GNUNET_SCALARPRODUCT_VERSION 0x00000044 48 49 /** 50 * Result status values for the computation. 51 */ 52 enum GNUNET_SCALARPRODUCT_ResponseStatus 53 { 54 /** 55 * Operation is still active (never returned, used internally). 56 */ 57 GNUNET_SCALARPRODUCT_STATUS_INIT = 0, 58 59 /** 60 * Operation is still active (never returned, used internally). 61 */ 62 GNUNET_SCALARPRODUCT_STATUS_ACTIVE = 1, 63 64 /** 65 * The computation was successful. 66 */ 67 GNUNET_SCALARPRODUCT_STATUS_SUCCESS, 68 69 /** 70 * We encountered some error. 71 */ 72 GNUNET_SCALARPRODUCT_STATUS_FAILURE, 73 74 /** 75 * We got an invalid response. 76 */ 77 GNUNET_SCALARPRODUCT_STATUS_INVALID_RESPONSE, 78 79 /** 80 * We got disconnected from the SCALARPRODUCT service. 81 */ 82 GNUNET_SCALARPRODUCT_STATUS_DISCONNECTED 83 }; 84 85 86 /** 87 * Opaque declaration of the SP-Handle 88 */ 89 struct GNUNET_SCALARPRODUCT_Handle; 90 91 92 GNUNET_NETWORK_STRUCT_BEGIN 93 94 /** 95 * An element key-value pair for scalarproduct 96 */ 97 struct GNUNET_SCALARPRODUCT_Element 98 { 99 /** 100 * Key used to identify matching pairs of values to multiply. 101 */ 102 struct GNUNET_HashCode key; 103 104 /** 105 * Value to multiply in scalar product, in NBO. 106 */ 107 int64_t value GNUNET_PACKED; 108 }; 109 110 GNUNET_NETWORK_STRUCT_END 111 112 113 /** 114 * Continuation called to notify client about result of the 115 * operation. 116 * 117 * @param cls closure 118 * @param status Status of the request 119 */ 120 typedef void 121 (*GNUNET_SCALARPRODUCT_ContinuationWithStatus) ( 122 void *cls, 123 enum GNUNET_SCALARPRODUCT_ResponseStatus status); 124 125 126 /** 127 * Process a datum that was stored in the scalarproduct. 128 * 129 * @param cls closure 130 * @param status Status of the request 131 * @param result result of the computation 132 */ 133 typedef void 134 (*GNUNET_SCALARPRODUCT_DatumProcessor) ( 135 void *cls, 136 enum GNUNET_SCALARPRODUCT_ResponseStatus status, 137 gcry_mpi_t result); 138 139 140 /** 141 * Entry in the request queue per client 142 */ 143 struct GNUNET_SCALARPRODUCT_ComputationHandle; 144 145 146 /** 147 * Request by Alice's client for computing a scalar product 148 * 149 * @param cfg the gnunet configuration handle 150 * @param session_key Session key should be unique to the requesting client 151 * @param peer PeerID of the other peer 152 * @param elements Array of elements of the vector 153 * @param element_count Number of elements in the @a elements vector 154 * @param cont Callback function 155 * @param cont_cls Closure for the @a cont callback function 156 * @return a new handle for this computation 157 */ 158 struct GNUNET_SCALARPRODUCT_ComputationHandle * 159 GNUNET_SCALARPRODUCT_start_computation ( 160 const struct GNUNET_CONFIGURATION_Handle *cfg, 161 const struct GNUNET_HashCode *session_key, 162 const struct GNUNET_PeerIdentity *peer, 163 const struct GNUNET_SCALARPRODUCT_Element *elements, 164 uint32_t element_count, 165 GNUNET_SCALARPRODUCT_DatumProcessor cont, 166 void *cont_cls); 167 168 169 /** 170 * Used by Bob's client to cooperate with Alice, 171 * 172 * @param cfg the gnunet configuration handle 173 * @param session_key Session key unique to the requesting client 174 * @param elements Array of elements of the vector 175 * @param element_count Number of elements in the @a elements vector 176 * @param cont Callback function 177 * @param cont_cls Closure for the @a cont callback function 178 * @return a new handle for this computation 179 */ 180 struct GNUNET_SCALARPRODUCT_ComputationHandle * 181 GNUNET_SCALARPRODUCT_accept_computation ( 182 const struct GNUNET_CONFIGURATION_Handle *cfg, 183 const struct GNUNET_HashCode *session_key, 184 const struct GNUNET_SCALARPRODUCT_Element *elements, 185 uint32_t element_count, 186 GNUNET_SCALARPRODUCT_ContinuationWithStatus cont, 187 void *cont_cls); 188 189 190 /** 191 * Cancel an ongoing computation or revoke our collaboration offer. 192 * Closes the connection to the service 193 * 194 * @param h computation handle to terminate 195 */ 196 void 197 GNUNET_SCALARPRODUCT_cancel (struct GNUNET_SCALARPRODUCT_ComputationHandle *h); 198 199 200 #if 0 /* keep Emacsens' auto-indent happy */ 201 { 202 #endif 203 #ifdef __cplusplus 204 } 205 #endif 206 207 #endif 208 209 /** @} */ /* end of group */