get-private-otp-devices-DEVICE_ID.h (9225B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2014-2026 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Lesser General Public License as published by the Free Software 7 Foundation; either version 2.1, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. 12 13 You should have received a copy of the GNU Lesser General Public License along with 14 TALER; see the file COPYING.LGPL. If not, see 15 <http://www.gnu.org/licenses/> 16 */ 17 /** 18 * @file src/include/taler/merchant/get-private-otp-devices-DEVICE_ID.h 19 * @brief C interface for GET /private/otp-devices/$DEVICE_ID of the merchant backend 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__GET_PRIVATE_OTP_DEVICES_DEVICE_ID_H 23 #define _TALER_MERCHANT__GET_PRIVATE_OTP_DEVICES_DEVICE_ID_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Handle for a GET /private/otp-devices/$DEVICE_ID request. 30 */ 31 struct TALER_MERCHANT_GetPrivateOtpDeviceHandle; 32 33 34 /** 35 * Response details for a GET /private/otp-devices/$DEVICE_ID request. 36 */ 37 struct TALER_MERCHANT_GetPrivateOtpDeviceResponse 38 { 39 40 /** 41 * HTTP response details. 42 */ 43 struct TALER_MERCHANT_HttpResponse hr; 44 45 /** 46 * Details depending on the HTTP status code. 47 */ 48 union 49 { 50 51 /** 52 * Details on #MHD_HTTP_OK. 53 */ 54 struct 55 { 56 57 /** 58 * Human-readable description of the OTP device. 59 */ 60 const char *otp_device_description; 61 62 /** 63 * Current counter value of the OTP device (for HOTP). 64 */ 65 uint64_t otp_ctr; 66 67 /** 68 * Current timestamp in seconds (for TOTP). 69 */ 70 uint64_t otp_timestamp_s; 71 72 /** 73 * POS confirmation text with OTP codes that 74 * would be returned for a purchase over the 75 * amount given in the query for the respective 76 * time and algorithm. NULL if the confirmation 77 * could not be computed based on the query and 78 * OTP algorithm. 79 */ 80 const char *otp_code; 81 82 /** 83 * OTP algorithm used. 84 */ 85 enum TALER_MerchantConfirmationAlgorithm otp_alg; 86 87 } ok; 88 89 } details; 90 91 }; 92 93 94 /** 95 * Possible options we can set for the GET /private/otp-devices/$DEVICE_ID request. 96 */ 97 enum TALER_MERCHANT_GetPrivateOtpDeviceOption 98 { 99 /** 100 * End of list of options. 101 */ 102 TALER_MERCHANT_GET_PRIVATE_OTP_DEVICE_OPTION_END = 0, 103 104 /** 105 * Set a fake time for OTP code computation. 106 */ 107 TALER_MERCHANT_GET_PRIVATE_OTP_DEVICE_OPTION_FAKETIME, 108 109 /** 110 * Set a price amount for OTP code computation. 111 */ 112 TALER_MERCHANT_GET_PRIVATE_OTP_DEVICE_OPTION_PRICE 113 114 }; 115 116 117 /** 118 * Value for an option for the GET /private/otp-devices/$DEVICE_ID request. 119 */ 120 struct TALER_MERCHANT_GetPrivateOtpDeviceOptionValue 121 { 122 123 /** 124 * Type of the option being set. 125 */ 126 enum TALER_MERCHANT_GetPrivateOtpDeviceOption option; 127 128 /** 129 * Specific option value. 130 */ 131 union 132 { 133 134 /** 135 * Value if @e option is 136 * #TALER_MERCHANT_GET_PRIVATE_OTP_DEVICE_OPTION_FAKETIME. 137 */ 138 struct GNUNET_TIME_Timestamp faketime; 139 140 /** 141 * Value if @e option is 142 * #TALER_MERCHANT_GET_PRIVATE_OTP_DEVICE_OPTION_PRICE. 143 */ 144 struct TALER_Amount price; 145 146 } details; 147 148 }; 149 150 151 /** 152 * Set up GET /private/otp-devices/$DEVICE_ID operation. 153 * Note that you must explicitly start the operation after 154 * possibly setting options. 155 * 156 * @param ctx the context 157 * @param url base URL of the merchant backend 158 * @param otp_device_id identifier of the OTP device to retrieve 159 * @return handle to operation 160 */ 161 struct TALER_MERCHANT_GetPrivateOtpDeviceHandle * 162 TALER_MERCHANT_get_private_otp_device_create ( 163 struct GNUNET_CURL_Context *ctx, 164 const char *url, 165 const char *otp_device_id); 166 167 168 /** 169 * Terminate the list of the options. 170 * 171 * @return the terminating object of struct TALER_MERCHANT_GetPrivateOtpDeviceOptionValue 172 */ 173 #define TALER_MERCHANT_get_private_otp_device_option_end_() \ 174 (const struct TALER_MERCHANT_GetPrivateOtpDeviceOptionValue) \ 175 { \ 176 .option = TALER_MERCHANT_GET_PRIVATE_OTP_DEVICE_OPTION_END \ 177 } 178 179 /** 180 * Set a fake time for OTP code computation. 181 * 182 * @param t the timestamp to use 183 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOtpDeviceOptionValue 184 */ 185 #define TALER_MERCHANT_get_private_otp_device_option_faketime(t) \ 186 (const struct TALER_MERCHANT_GetPrivateOtpDeviceOptionValue) \ 187 { \ 188 .option = \ 189 TALER_MERCHANT_GET_PRIVATE_OTP_DEVICE_OPTION_FAKETIME, \ 190 .details.faketime = (t) \ 191 } 192 193 /** 194 * Set a price amount for OTP code computation. 195 * 196 * @param a the amount to use 197 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOtpDeviceOptionValue 198 */ 199 #define TALER_MERCHANT_get_private_otp_device_option_price(a) \ 200 (const struct TALER_MERCHANT_GetPrivateOtpDeviceOptionValue) \ 201 { \ 202 .option = \ 203 TALER_MERCHANT_GET_PRIVATE_OTP_DEVICE_OPTION_PRICE, \ 204 .details.price = (a) \ 205 } 206 207 208 /** 209 * Set the requested options for the operation. 210 * 211 * If any option fail other options may be or may be not applied. 212 * 213 * @param god the request to set the options for 214 * @param num_options length of the @a options array 215 * @param options an array of options 216 * @return #GNUNET_OK on success, 217 * #GNUNET_NO on failure, 218 * #GNUNET_SYSERR on internal error 219 */ 220 enum GNUNET_GenericReturnValue 221 TALER_MERCHANT_get_private_otp_device_set_options_ ( 222 struct TALER_MERCHANT_GetPrivateOtpDeviceHandle *god, 223 unsigned int num_options, 224 const struct TALER_MERCHANT_GetPrivateOtpDeviceOptionValue *options); 225 226 227 /** 228 * Set the requested options for the operation. 229 * 230 * If any option fail other options may be or may be not applied. 231 * 232 * It should be used with helpers that create required options, for example: 233 * 234 * TALER_MERCHANT_get_private_otp_device_set_options ( 235 * god, 236 * TALER_MERCHANT_get_private_otp_device_option_faketime (ts), 237 * TALER_MERCHANT_get_private_otp_device_option_price (amount)); 238 * 239 * @param god the request to set the options for 240 * @param ... the list of the options, each option must be created 241 * by helpers TALER_MERCHANT_get_private_otp_device_option_NAME(VALUE) 242 * @return #GNUNET_OK on success, 243 * #GNUNET_NO on failure, 244 * #GNUNET_SYSERR on internal error 245 */ 246 #define TALER_MERCHANT_get_private_otp_device_set_options(god,...) \ 247 TALER_MERCHANT_get_private_otp_device_set_options_ ( \ 248 god, \ 249 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 250 ((const struct TALER_MERCHANT_GetPrivateOtpDeviceOptionValue[]) \ 251 {__VA_ARGS__, TALER_MERCHANT_get_private_otp_device_option_end_ () } \ 252 )) 253 254 255 #ifndef TALER_MERCHANT_GET_PRIVATE_OTP_DEVICE_RESULT_CLOSURE 256 /** 257 * Type of the closure used by 258 * the #TALER_MERCHANT_GetPrivateOtpDeviceCallback. 259 */ 260 #define TALER_MERCHANT_GET_PRIVATE_OTP_DEVICE_RESULT_CLOSURE void 261 #endif /* TALER_MERCHANT_GET_PRIVATE_OTP_DEVICE_RESULT_CLOSURE */ 262 263 /** 264 * Callback for a GET /private/otp-devices/$DEVICE_ID request. 265 * 266 * @param cls closure 267 * @param ogr response details 268 */ 269 typedef void 270 (*TALER_MERCHANT_GetPrivateOtpDeviceCallback)( 271 TALER_MERCHANT_GET_PRIVATE_OTP_DEVICE_RESULT_CLOSURE *cls, 272 const struct TALER_MERCHANT_GetPrivateOtpDeviceResponse *ogr); 273 274 275 /** 276 * Start GET /private/otp-devices/$DEVICE_ID operation. 277 * 278 * @param[in,out] god operation to start 279 * @param cb function to call with the merchant's result 280 * @param cb_cls closure for @a cb 281 * @return status code, #TALER_EC_NONE on success 282 */ 283 enum TALER_ErrorCode 284 TALER_MERCHANT_get_private_otp_device_start ( 285 struct TALER_MERCHANT_GetPrivateOtpDeviceHandle *god, 286 TALER_MERCHANT_GetPrivateOtpDeviceCallback cb, 287 TALER_MERCHANT_GET_PRIVATE_OTP_DEVICE_RESULT_CLOSURE *cb_cls); 288 289 290 /** 291 * Cancel GET /private/otp-devices/$DEVICE_ID operation. This function 292 * must not be called by clients after the 293 * TALER_MERCHANT_GetPrivateOtpDeviceCallback has been invoked 294 * (as in those cases it'll be called internally by the 295 * implementation already). 296 * 297 * @param[in] god operation to cancel 298 */ 299 void 300 TALER_MERCHANT_get_private_otp_device_cancel ( 301 struct TALER_MERCHANT_GetPrivateOtpDeviceHandle *god); 302 303 304 #endif /* _TALER_MERCHANT__GET_PRIVATE_OTP_DEVICES_DEVICE_ID_H */