post-management-instances-INSTANCE-auth.h (6769B)
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-management-instances-INSTANCE-auth.h 19 * @brief C interface for the POST /management/instances/$INSTANCE/auth endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_MANAGEMENT_INSTANCES_INSTANCE_AUTH_H 23 #define _TALER_MERCHANT__POST_MANAGEMENT_INSTANCES_INSTANCE_AUTH_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Handle for a POST /management/instances/$INSTANCE/auth request. 30 */ 31 struct TALER_MERCHANT_PostManagementInstancesAuthHandle; 32 33 34 /** 35 * Response details for a POST /management/instances/$INSTANCE/auth request. 36 */ 37 struct TALER_MERCHANT_PostManagementInstancesAuthResponse 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 * Details on #MHD_HTTP_ACCEPTED. 52 */ 53 struct TALER_MERCHANT_MfaChallengeResponse accepted; 54 } details; 55 56 }; 57 58 59 /** 60 * Options for POST /management/instances/$INSTANCE/auth. 61 */ 62 enum TALER_MERCHANT_PostManagementInstancesAuthOption 63 { 64 /** 65 * Sentinel value, end of options. 66 */ 67 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_AUTH_OPTION_END = 0, 68 69 /** 70 * Set the authentication password. If not set (or set to NULL), 71 * the "external" authentication method is used. 72 * Value type: const char *. 73 */ 74 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_AUTH_OPTION_PASSWORD 75 }; 76 77 78 /** 79 * Value for a POST /management/instances/$INSTANCE/auth option. 80 */ 81 struct TALER_MERCHANT_PostManagementInstancesAuthOptionValue 82 { 83 /** 84 * Which option is being set. 85 */ 86 enum TALER_MERCHANT_PostManagementInstancesAuthOption option; 87 88 /** 89 * Specific option value. 90 */ 91 union 92 { 93 94 /** 95 * Value if @e option is 96 * #TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_AUTH_OPTION_PASSWORD. 97 */ 98 const char *password; 99 100 } details; 101 }; 102 103 104 /** 105 * Set password. 106 * 107 * @param pw password to set 108 * @return representation of the option 109 */ 110 #define TALER_MERCHANT_post_management_instances_auth_option_password(pw) \ 111 (const struct TALER_MERCHANT_PostManagementInstancesAuthOptionValue) \ 112 { \ 113 .option = TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_AUTH_OPTION_PASSWORD, \ 114 .details.password = (pw) \ 115 } 116 117 118 /** 119 * Set up POST /management/instances/$INSTANCE/auth operation. 120 * Note that you must explicitly start the operation after 121 * possibly setting options. 122 * 123 * @param ctx the context 124 * @param url base URL of the merchant backend 125 * @param instance_id identifier of the instance 126 * @return handle to operation 127 */ 128 struct TALER_MERCHANT_PostManagementInstancesAuthHandle * 129 TALER_MERCHANT_post_management_instances_auth_create ( 130 struct GNUNET_CURL_Context *ctx, 131 const char *url, 132 const char *instance_id); 133 134 135 /** 136 * Set options for POST /management/instances/$INSTANCE/auth operation. 137 * 138 * @param[in,out] piah the handle to set options for 139 * @param num_options length of the @a options array 140 * @param options array of option values (terminated with _END) 141 */ 142 void 143 TALER_MERCHANT_post_management_instances_auth_set_options_ ( 144 struct TALER_MERCHANT_PostManagementInstancesAuthHandle *piah, 145 unsigned int num_options, 146 const struct TALER_MERCHANT_PostManagementInstancesAuthOptionValue options[]); 147 148 149 /** 150 * Maximum number of options for set_options macro. 151 */ 152 #define TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_AUTH_OPTIONS_ARRAY_MAX_SIZE 4 153 154 /** 155 * Set options for POST /management/instances/$INSTANCE/auth operation. 156 * Variadic macro wrapper around 157 * #TALER_MERCHANT_post_management_instances_auth_set_options_(). 158 * 159 * @param piah the handle to set options for 160 * @param ... option values (automatically terminated with _END) 161 */ 162 #define TALER_MERCHANT_post_management_instances_auth_set_options(piah, ...) \ 163 do { \ 164 struct TALER_MERCHANT_PostManagementInstancesAuthOptionValue __opts[] = { \ 165 __VA_ARGS__, \ 166 { .option = TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_AUTH_OPTION_END } \ 167 }; \ 168 TALER_MERCHANT_post_management_instances_auth_set_options_ ( \ 169 piah, \ 170 sizeof (__opts) / sizeof (__opts[0]) - 1, \ 171 __opts); \ 172 } while (0) 173 174 175 #ifndef TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_AUTH_RESULT_CLOSURE 176 /** 177 * Type of the closure used by 178 * the #TALER_MERCHANT_PostManagementInstancesAuthCallback. 179 */ 180 #define TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_AUTH_RESULT_CLOSURE void 181 #endif /* TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_AUTH_RESULT_CLOSURE */ 182 183 /** 184 * Callback for a POST /management/instances/$INSTANCE/auth request. 185 * 186 * @param cls closure 187 * @param iar response details 188 */ 189 typedef void 190 (*TALER_MERCHANT_PostManagementInstancesAuthCallback)( 191 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_AUTH_RESULT_CLOSURE *cls, 192 const struct TALER_MERCHANT_PostManagementInstancesAuthResponse *iar); 193 194 195 /** 196 * Start POST /management/instances/$INSTANCE/auth operation. 197 * 198 * @param[in,out] piah operation to start 199 * @param cb function to call with the merchant's result 200 * @param cb_cls closure for @a cb 201 * @return status code, #TALER_EC_NONE on success 202 */ 203 enum TALER_ErrorCode 204 TALER_MERCHANT_post_management_instances_auth_start ( 205 struct TALER_MERCHANT_PostManagementInstancesAuthHandle *piah, 206 TALER_MERCHANT_PostManagementInstancesAuthCallback cb, 207 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_AUTH_RESULT_CLOSURE *cb_cls); 208 209 210 /** 211 * Cancel POST /management/instances/$INSTANCE/auth operation. This function 212 * must not be called by clients after the 213 * TALER_MERCHANT_PostManagementInstancesAuthCallback has been invoked (as in 214 * those cases it'll be called internally by the implementation already). 215 * 216 * @param[in] piah operation to cancel 217 */ 218 void 219 TALER_MERCHANT_post_management_instances_auth_cancel ( 220 struct TALER_MERCHANT_PostManagementInstancesAuthHandle *piah); 221 222 223 #endif /* _TALER_MERCHANT__POST_MANAGEMENT_INSTANCES_INSTANCE_AUTH_H */