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