post-orders-ORDER_ID-claim.h (6922B)
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-orders-ORDER_ID-claim.h 19 * @brief C interface for the POST /orders/$ORDER_ID/claim endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_ORDERS_ORDER_ID_CLAIM_H 23 #define _TALER_MERCHANT__POST_ORDERS_ORDER_ID_CLAIM_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options for the POST /orders/$ORDER_ID/claim request. 30 */ 31 enum TALER_MERCHANT_PostOrdersClaimOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_POST_ORDERS_CLAIM_OPTION_END = 0, 37 38 /** 39 * Claim token for the order. 40 */ 41 TALER_MERCHANT_POST_ORDERS_CLAIM_OPTION_TOKEN 42 43 }; 44 45 46 /** 47 * Value for an option for the POST /orders/$ORDER_ID/claim request. 48 */ 49 struct TALER_MERCHANT_PostOrdersClaimOptionValue 50 { 51 52 /** 53 * Type of the option being set. 54 */ 55 enum TALER_MERCHANT_PostOrdersClaimOption option; 56 57 /** 58 * Specific option value. 59 */ 60 union 61 { 62 63 /** 64 * Value if @e option is 65 * #TALER_MERCHANT_POST_ORDERS_CLAIM_OPTION_TOKEN. 66 */ 67 const struct TALER_ClaimTokenP *token; 68 69 } details; 70 71 }; 72 73 74 /** 75 * Handle for a POST /orders/$ORDER_ID/claim request. 76 */ 77 struct TALER_MERCHANT_PostOrdersClaimHandle; 78 79 80 /** 81 * Response details for a POST /orders/$ORDER_ID/claim request. 82 */ 83 struct TALER_MERCHANT_PostOrdersClaimResponse 84 { 85 86 /** 87 * HTTP response details. 88 */ 89 struct TALER_MERCHANT_HttpResponse hr; 90 91 /** 92 * Details depending on the HTTP status code. 93 */ 94 union 95 { 96 97 /** 98 * Details on #MHD_HTTP_OK. 99 */ 100 struct 101 { 102 103 /** 104 * The claimed contract terms. 105 */ 106 const json_t *contract_terms; 107 108 /** 109 * Hash of the contract terms. 110 */ 111 struct TALER_PrivateContractHashP h_contract_terms; 112 113 /** 114 * Merchant signature over the contract terms. 115 */ 116 struct TALER_MerchantSignatureP merchant_sig; 117 118 } ok; 119 120 } details; 121 122 }; 123 124 125 /** 126 * Terminate the list of the options. 127 * 128 * @return the terminating object of struct TALER_MERCHANT_PostOrdersClaimOptionValue 129 */ 130 #define TALER_MERCHANT_post_orders_claim_option_end_() \ 131 (const struct TALER_MERCHANT_PostOrdersClaimOptionValue) \ 132 { \ 133 .option = TALER_MERCHANT_POST_ORDERS_CLAIM_OPTION_END \ 134 } 135 136 /** 137 * Set claim token. 138 * 139 * @param t claim token to use 140 * @return representation of the option as a struct TALER_MERCHANT_PostOrdersClaimOptionValue 141 */ 142 #define TALER_MERCHANT_post_orders_claim_option_token(t) \ 143 (const struct TALER_MERCHANT_PostOrdersClaimOptionValue) \ 144 { \ 145 .option = TALER_MERCHANT_POST_ORDERS_CLAIM_OPTION_TOKEN, \ 146 .details.token = (t) \ 147 } 148 149 150 /** 151 * Set the requested options for the operation. 152 * 153 * @param poch the request to set the options for 154 * @param num_options length of the @a options array 155 * @param options an array of options 156 * @return #GNUNET_OK on success, 157 * #GNUNET_NO on failure, 158 * #GNUNET_SYSERR on internal error 159 */ 160 enum GNUNET_GenericReturnValue 161 TALER_MERCHANT_post_orders_claim_set_options_ ( 162 struct TALER_MERCHANT_PostOrdersClaimHandle *poch, 163 unsigned int num_options, 164 const struct TALER_MERCHANT_PostOrdersClaimOptionValue *options); 165 166 167 /** 168 * Set the requested options for the operation. 169 * 170 * @param poch the request to set the options for 171 * @param ... the list of the options 172 * @return #GNUNET_OK on success, 173 * #GNUNET_NO on failure, 174 * #GNUNET_SYSERR on internal error 175 */ 176 #define TALER_MERCHANT_post_orders_claim_set_options(poch,...) \ 177 TALER_MERCHANT_post_orders_claim_set_options_ ( \ 178 poch, \ 179 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 180 ((const struct TALER_MERCHANT_PostOrdersClaimOptionValue[]) \ 181 {__VA_ARGS__, TALER_MERCHANT_post_orders_claim_option_end_ () } \ 182 )) 183 184 185 /** 186 * Set up POST /orders/$ORDER_ID/claim operation. 187 * Note that you must explicitly start the operation after 188 * possibly setting options. 189 * 190 * @param ctx the context 191 * @param url base URL of the merchant backend 192 * @param order_id identifier of the order to claim 193 * @param nonce wallet nonce for claiming 194 * @return handle to operation 195 */ 196 struct TALER_MERCHANT_PostOrdersClaimHandle * 197 TALER_MERCHANT_post_orders_claim_create ( 198 struct GNUNET_CURL_Context *ctx, 199 const char *url, 200 const char *order_id, 201 const struct GNUNET_CRYPTO_EddsaPublicKey *nonce); 202 203 204 #ifndef TALER_MERCHANT_POST_ORDERS_CLAIM_RESULT_CLOSURE 205 /** 206 * Type of the closure used by 207 * the #TALER_MERCHANT_PostOrdersClaimCallback. 208 */ 209 #define TALER_MERCHANT_POST_ORDERS_CLAIM_RESULT_CLOSURE void 210 #endif /* TALER_MERCHANT_POST_ORDERS_CLAIM_RESULT_CLOSURE */ 211 212 /** 213 * Callback for a POST /orders/$ORDER_ID/claim request. 214 * 215 * @param cls closure 216 * @param ocr response details 217 */ 218 typedef void 219 (*TALER_MERCHANT_PostOrdersClaimCallback)( 220 TALER_MERCHANT_POST_ORDERS_CLAIM_RESULT_CLOSURE *cls, 221 const struct TALER_MERCHANT_PostOrdersClaimResponse *ocr); 222 223 224 /** 225 * Start POST /orders/$ORDER_ID/claim operation. 226 * 227 * @param[in,out] poch operation to start 228 * @param cb function to call with the merchant's result 229 * @param cb_cls closure for @a cb 230 * @return status code, #TALER_EC_NONE on success 231 */ 232 enum TALER_ErrorCode 233 TALER_MERCHANT_post_orders_claim_start ( 234 struct TALER_MERCHANT_PostOrdersClaimHandle *poch, 235 TALER_MERCHANT_PostOrdersClaimCallback cb, 236 TALER_MERCHANT_POST_ORDERS_CLAIM_RESULT_CLOSURE *cb_cls); 237 238 239 /** 240 * Cancel POST /orders/$ORDER_ID/claim operation. This function must not be 241 * called by clients after the TALER_MERCHANT_PostOrdersClaimCallback has 242 * been invoked (as in those cases it'll be called internally by the 243 * implementation already). 244 * 245 * @param[in] poch operation to cancel 246 */ 247 void 248 TALER_MERCHANT_post_orders_claim_cancel ( 249 struct TALER_MERCHANT_PostOrdersClaimHandle *poch); 250 251 252 #endif /* _TALER_MERCHANT__POST_ORDERS_ORDER_ID_CLAIM_H */