post-private-token.h (8376B)
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/post-private-token.h 19 * @brief C interface for the POST /private/token endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_PRIVATE_TOKEN_H 23 #define _TALER_MERCHANT__POST_PRIVATE_TOKEN_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Handle for a POST /private/token request. 30 */ 31 struct TALER_MERCHANT_PostPrivateTokenHandle; 32 33 34 /** 35 * Possible options for the POST /private/token request. 36 */ 37 enum TALER_MERCHANT_PostPrivateTokenOption 38 { 39 /** 40 * End of list of options. 41 */ 42 TALER_MERCHANT_POST_PRIVATE_TOKEN_OPTION_END = 0, 43 44 /** 45 * Duration for the token validity. 46 */ 47 TALER_MERCHANT_POST_PRIVATE_TOKEN_OPTION_DURATION, 48 49 /** 50 * Whether the token may be refreshed. 51 */ 52 TALER_MERCHANT_POST_PRIVATE_TOKEN_OPTION_REFRESHABLE, 53 54 /** 55 * Description for the token. 56 */ 57 TALER_MERCHANT_POST_PRIVATE_TOKEN_OPTION_DESCRIPTION 58 59 }; 60 61 62 /** 63 * Value for an option for the POST /private/token request. 64 */ 65 struct TALER_MERCHANT_PostPrivateTokenOptionValue 66 { 67 68 /** 69 * Type of the option being set. 70 */ 71 enum TALER_MERCHANT_PostPrivateTokenOption option; 72 73 /** 74 * Specific option value. 75 */ 76 union 77 { 78 79 /** 80 * Value if @e option is 81 * #TALER_MERCHANT_POST_PRIVATE_TOKEN_OPTION_DURATION. 82 */ 83 struct GNUNET_TIME_Relative duration; 84 85 /** 86 * Value if @e option is 87 * #TALER_MERCHANT_POST_PRIVATE_TOKEN_OPTION_REFRESHABLE. 88 */ 89 bool refreshable; 90 91 /** 92 * Value if @e option is 93 * #TALER_MERCHANT_POST_PRIVATE_TOKEN_OPTION_DESCRIPTION. 94 */ 95 const char *description; 96 97 } details; 98 99 }; 100 101 102 /** 103 * Response details for a POST /private/token request. 104 */ 105 struct TALER_MERCHANT_PostPrivateTokenResponse 106 { 107 108 /** 109 * HTTP response details. 110 */ 111 struct TALER_MERCHANT_HttpResponse hr; 112 113 /** 114 * Details depending on the HTTP status code. 115 */ 116 union 117 { 118 119 /** 120 * Details on #MHD_HTTP_OK. 121 */ 122 struct 123 { 124 125 /** 126 * The access token (RFC 8959 secret-token: URI). 127 */ 128 const char *access_token; 129 130 /** 131 * The scope of the token. 132 */ 133 const char *scope; 134 135 /** 136 * Whether the token may be refreshed. 137 */ 138 bool refreshable; 139 140 /** 141 * When the token expires. 142 */ 143 struct GNUNET_TIME_Timestamp expiration; 144 145 } ok; 146 147 /** 148 * Details on #MHD_HTTP_ACCEPTED. 149 */ 150 struct TALER_MERCHANT_MfaChallengeResponse accepted; 151 152 } details; 153 154 }; 155 156 157 /** 158 * Terminate the list of the options. 159 * 160 * @return the terminating object 161 */ 162 #define TALER_MERCHANT_post_private_token_option_end_() \ 163 (const struct TALER_MERCHANT_PostPrivateTokenOptionValue) \ 164 { \ 165 .option = TALER_MERCHANT_POST_PRIVATE_TOKEN_OPTION_END \ 166 } 167 168 /** 169 * Set duration for token validity. 170 * 171 * @param d the duration 172 * @return representation of the option 173 */ 174 #define TALER_MERCHANT_post_private_token_option_duration(d) \ 175 (const struct TALER_MERCHANT_PostPrivateTokenOptionValue) \ 176 { \ 177 .option = TALER_MERCHANT_POST_PRIVATE_TOKEN_OPTION_DURATION, \ 178 .details.duration = (d) \ 179 } 180 181 /** 182 * Set whether token is refreshable. 183 * 184 * @param r true if token may be refreshed 185 * @return representation of the option 186 */ 187 #define TALER_MERCHANT_post_private_token_option_refreshable(r) \ 188 (const struct TALER_MERCHANT_PostPrivateTokenOptionValue) \ 189 { \ 190 .option = TALER_MERCHANT_POST_PRIVATE_TOKEN_OPTION_REFRESHABLE, \ 191 .details.refreshable = (r) \ 192 } 193 194 /** 195 * Set description for the token. 196 * 197 * @param d description string 198 * @return representation of the option 199 */ 200 #define TALER_MERCHANT_post_private_token_option_description(d) \ 201 (const struct TALER_MERCHANT_PostPrivateTokenOptionValue) \ 202 { \ 203 .option = TALER_MERCHANT_POST_PRIVATE_TOKEN_OPTION_DESCRIPTION, \ 204 .details.description = (d) \ 205 } 206 207 208 /** 209 * Set the requested options for the operation. 210 * 211 * @param ppth the request to set the options for 212 * @param num_options length of the @a options array 213 * @param options an array of options 214 * @return #GNUNET_OK on success, 215 * #GNUNET_NO on failure, 216 * #GNUNET_SYSERR on internal error 217 */ 218 enum GNUNET_GenericReturnValue 219 TALER_MERCHANT_post_private_token_set_options_ ( 220 struct TALER_MERCHANT_PostPrivateTokenHandle *ppth, 221 unsigned int num_options, 222 const struct TALER_MERCHANT_PostPrivateTokenOptionValue *options); 223 224 225 /** 226 * Set the requested options for the operation. 227 * 228 * @param ppth the request to set the options for 229 * @param ... the list of the options 230 * @return #GNUNET_OK on success, 231 * #GNUNET_NO on failure, 232 * #GNUNET_SYSERR on internal error 233 */ 234 #define TALER_MERCHANT_post_private_token_set_options(ppth,...) \ 235 TALER_MERCHANT_post_private_token_set_options_ ( \ 236 ppth, \ 237 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 238 ((const struct TALER_MERCHANT_PostPrivateTokenOptionValue[]) \ 239 {__VA_ARGS__, TALER_MERCHANT_post_private_token_option_end_ () } \ 240 )) 241 242 243 /** 244 * Set up POST /private/token operation. 245 * Note that you must explicitly start the operation after 246 * possibly setting options. 247 * 248 * @param ctx the context 249 * @param url base URL of the merchant backend 250 * @param instance_id identifier of the instance 251 * @param scope scope for the token 252 * @return handle to operation 253 */ 254 struct TALER_MERCHANT_PostPrivateTokenHandle * 255 TALER_MERCHANT_post_private_token_create ( 256 struct GNUNET_CURL_Context *ctx, 257 const char *url, 258 const char *instance_id, 259 const char *scope); 260 261 262 #ifndef TALER_MERCHANT_POST_PRIVATE_TOKEN_RESULT_CLOSURE 263 /** 264 * Type of the closure used by 265 * the #TALER_MERCHANT_PostPrivateTokenCallback. 266 */ 267 #define TALER_MERCHANT_POST_PRIVATE_TOKEN_RESULT_CLOSURE void 268 #endif /* TALER_MERCHANT_POST_PRIVATE_TOKEN_RESULT_CLOSURE */ 269 270 /** 271 * Callback for a POST /private/token request. 272 * 273 * @param cls closure 274 * @param ptr response details 275 */ 276 typedef void 277 (*TALER_MERCHANT_PostPrivateTokenCallback)( 278 TALER_MERCHANT_POST_PRIVATE_TOKEN_RESULT_CLOSURE *cls, 279 const struct TALER_MERCHANT_PostPrivateTokenResponse *ptr); 280 281 282 /** 283 * Start POST /private/token operation. 284 * 285 * @param[in,out] ppth operation to start 286 * @param cb function to call with the merchant's result 287 * @param cb_cls closure for @a cb 288 * @return status code, #TALER_EC_NONE on success 289 */ 290 enum TALER_ErrorCode 291 TALER_MERCHANT_post_private_token_start ( 292 struct TALER_MERCHANT_PostPrivateTokenHandle *ppth, 293 TALER_MERCHANT_PostPrivateTokenCallback cb, 294 TALER_MERCHANT_POST_PRIVATE_TOKEN_RESULT_CLOSURE *cb_cls); 295 296 297 /** 298 * Cancel POST /private/token operation. This function must not be 299 * called by clients after the TALER_MERCHANT_PostPrivateTokenCallback 300 * has been invoked (as in those cases it'll be called internally by the 301 * implementation already). 302 * 303 * @param[in] ppth operation to cancel 304 */ 305 void 306 TALER_MERCHANT_post_private_token_cancel ( 307 struct TALER_MERCHANT_PostPrivateTokenHandle *ppth); 308 309 310 #endif /* _TALER_MERCHANT__POST_PRIVATE_TOKEN_H */