post-private-categories.h (6714B)
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 include/taler/taler-merchant/post-private-categories.h 19 * @brief C interface for the POST /private/categories endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_PRIVATE_CATEGORIES_H 23 #define _TALER_MERCHANT__POST_PRIVATE_CATEGORIES_H 24 25 #include <taler/taler-merchant/common.h> 26 27 28 /** 29 * Possible options for the POST /private/categories request. 30 */ 31 enum TALER_MERCHANT_PostPrivateCategoriesOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_POST_PRIVATE_CATEGORIES_OPTION_END = 0, 37 38 /** 39 * Internationalized names (JSON). 40 */ 41 TALER_MERCHANT_POST_PRIVATE_CATEGORIES_OPTION_NAME_I18N 42 43 }; 44 45 46 /** 47 * Value for an option for the POST /private/categories request. 48 */ 49 struct TALER_MERCHANT_PostPrivateCategoriesOptionValue 50 { 51 52 /** 53 * Type of the option being set. 54 */ 55 enum TALER_MERCHANT_PostPrivateCategoriesOption option; 56 57 /** 58 * Specific option value. 59 */ 60 union 61 { 62 63 /** 64 * Value if @e option is 65 * #TALER_MERCHANT_POST_PRIVATE_CATEGORIES_OPTION_NAME_I18N. 66 */ 67 const json_t *name_i18n; 68 69 } details; 70 71 }; 72 73 74 /** 75 * Handle for a POST /private/categories request. 76 */ 77 struct TALER_MERCHANT_PostPrivateCategoriesHandle; 78 79 80 /** 81 * Response details for a POST /private/categories request. 82 */ 83 struct TALER_MERCHANT_PostPrivateCategoriesResponse 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 * Numeric identifier of the newly created category. 105 */ 106 uint64_t category_id; 107 108 } ok; 109 110 } details; 111 112 }; 113 114 115 /** 116 * Terminate the list of the options. 117 * 118 * @return the terminating object 119 */ 120 #define TALER_MERCHANT_post_private_categories_option_end_() \ 121 (const struct TALER_MERCHANT_PostPrivateCategoriesOptionValue) \ 122 { \ 123 .option = TALER_MERCHANT_POST_PRIVATE_CATEGORIES_OPTION_END \ 124 } 125 126 /** 127 * Set internationalized names. 128 * 129 * @param n names JSON object 130 * @return representation of the option 131 */ 132 #define TALER_MERCHANT_post_private_categories_option_name_i18n(n) \ 133 (const struct TALER_MERCHANT_PostPrivateCategoriesOptionValue) \ 134 { \ 135 .option = TALER_MERCHANT_POST_PRIVATE_CATEGORIES_OPTION_NAME_I18N, \ 136 .details.name_i18n = (n) \ 137 } 138 139 140 /** 141 * Set the requested options for the operation. 142 * 143 * @param ppch the request to set the options for 144 * @param num_options length of the @a options array 145 * @param options an array of options 146 * @return #GNUNET_OK on success, 147 * #GNUNET_NO on failure, 148 * #GNUNET_SYSERR on internal error 149 */ 150 enum GNUNET_GenericReturnValue 151 TALER_MERCHANT_post_private_categories_set_options_ ( 152 struct TALER_MERCHANT_PostPrivateCategoriesHandle *ppch, 153 unsigned int num_options, 154 const struct TALER_MERCHANT_PostPrivateCategoriesOptionValue *options); 155 156 157 /** 158 * Set the requested options for the operation. 159 * 160 * @param ppch the request to set the options for 161 * @param ... the list of the options 162 * @return #GNUNET_OK on success, 163 * #GNUNET_NO on failure, 164 * #GNUNET_SYSERR on internal error 165 */ 166 #define TALER_MERCHANT_post_private_categories_set_options(ppch,...) \ 167 TALER_MERCHANT_post_private_categories_set_options_ ( \ 168 ppch, \ 169 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 170 ((const struct TALER_MERCHANT_PostPrivateCategoriesOptionValue[]) \ 171 {__VA_ARGS__, TALER_MERCHANT_post_private_categories_option_end_ () } \ 172 )) 173 174 175 /** 176 * Set up POST /private/categories operation. 177 * Note that you must explicitly start the operation after 178 * possibly setting options. 179 * 180 * @param ctx the context 181 * @param url base URL of the merchant backend 182 * @param name human-readable name of the category 183 * @return handle to operation 184 */ 185 struct TALER_MERCHANT_PostPrivateCategoriesHandle * 186 TALER_MERCHANT_post_private_categories_create ( 187 struct GNUNET_CURL_Context *ctx, 188 const char *url, 189 const char *name); 190 191 192 #ifndef TALER_MERCHANT_POST_PRIVATE_CATEGORIES_RESULT_CLOSURE 193 /** 194 * Type of the closure used by 195 * the #TALER_MERCHANT_PostPrivateCategoriesCallback. 196 */ 197 #define TALER_MERCHANT_POST_PRIVATE_CATEGORIES_RESULT_CLOSURE void 198 #endif /* TALER_MERCHANT_POST_PRIVATE_CATEGORIES_RESULT_CLOSURE */ 199 200 /** 201 * Callback for a POST /private/categories request. 202 * 203 * @param cls closure 204 * @param cpr response details 205 */ 206 typedef void 207 (*TALER_MERCHANT_PostPrivateCategoriesCallback)( 208 TALER_MERCHANT_POST_PRIVATE_CATEGORIES_RESULT_CLOSURE *cls, 209 const struct TALER_MERCHANT_PostPrivateCategoriesResponse *cpr); 210 211 212 /** 213 * Start POST /private/categories operation. 214 * 215 * @param[in,out] ppch operation to start 216 * @param cb function to call with the merchant's result 217 * @param cb_cls closure for @a cb 218 * @return status code, #TALER_EC_NONE on success 219 */ 220 enum TALER_ErrorCode 221 TALER_MERCHANT_post_private_categories_start ( 222 struct TALER_MERCHANT_PostPrivateCategoriesHandle *ppch, 223 TALER_MERCHANT_PostPrivateCategoriesCallback cb, 224 TALER_MERCHANT_POST_PRIVATE_CATEGORIES_RESULT_CLOSURE *cb_cls); 225 226 227 /** 228 * Cancel POST /private/categories operation. This function must not be 229 * called by clients after the TALER_MERCHANT_PostPrivateCategoriesCallback 230 * has been invoked (as in those cases it'll be called internally by the 231 * implementation already). 232 * 233 * @param[in] ppch operation to cancel 234 */ 235 void 236 TALER_MERCHANT_post_private_categories_cancel ( 237 struct TALER_MERCHANT_PostPrivateCategoriesHandle *ppch); 238 239 240 #endif /* _TALER_MERCHANT__POST_PRIVATE_CATEGORIES_H */