taler_wallet_core_lib.h (5734B)
1 /* 2 This file is part of GNU Taler 3 Copyright (C) 2014-2022 Taler Systems SA 4 5 GNU Taler is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 3, or (at your option) any later version. 8 9 GNU 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 Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 */ 16 17 /** 18 * C interface to the functionality of wallet-core. 19 * 20 * Currently, the underlying implementation uses the JS implementation of 21 * wallet-core, but this may (or may not) change in the future. 22 * 23 * @author Florian Dold 24 */ 25 #ifndef _TALER_WALLET_LIB_H 26 #define _TALER_WALLET_LIB_H 27 28 #include "quickjs/quickjs-http.h" 29 30 /** 31 * Opaque handle to a Taler wallet-core instance. 32 */ 33 struct TALER_WALLET_Instance; 34 35 /** 36 * Handler for messages from the wallet. 37 * 38 * @param handler_p opaque closure for the message handler 39 * @param message message from wallet-core as a JSON string 40 */ 41 typedef void (*TALER_WALLET_MessageHandlerFn)(void *handler_p, const char *message); 42 43 enum TALER_WALLET_LogLevel { 44 TALER_WALLET_LOG_TRACE = 1, 45 TALER_WALLET_LOG_INFO = 2, 46 TALER_WALLET_LOG_MESSAGE = 3, 47 TALER_WALLET_LOG_WARN = 4, 48 TALER_WALLET_LOG_ERROR = 5 49 }; 50 51 /** 52 * Handler for log message from wallet-core. 53 * 54 * @param log_p opaque closure for the log handler 55 * @param level log level of the log message 56 * @param tag log tag (usually the file from which the message gets logged) 57 * @param msg the log message 58 */ 59 typedef void (*TALER_WALLET_LogHandlerFn)(void *log_p, 60 enum TALER_WALLET_LogLevel level, 61 const char *tag, 62 const char *msg); 63 64 /** 65 * Create a new wallet-core instance.. 66 */ 67 struct TALER_WALLET_Instance * 68 TALER_WALLET_create(void); 69 70 /** 71 * Set a handler for notification and response messages. 72 * Must be called before the wallet runs. 73 * 74 * Caution: The handler will be called from a different thread. 75 */ 76 void 77 TALER_WALLET_set_message_handler(struct TALER_WALLET_Instance *twi, 78 TALER_WALLET_MessageHandlerFn handler_f, 79 void *handler_p); 80 81 /** 82 * Set a handler for log messages from wallet-core. 83 * Must be called before the wallet runs. 84 * 85 * Caution: The log message handler will be called from a different thread. 86 */ 87 void 88 TALER_WALLET_set_log_handler(struct TALER_WALLET_Instance *twi, 89 TALER_WALLET_LogHandlerFn handler_f, 90 void *handler_p); 91 92 /** 93 * Set/override the JS file with the wallet-core implementation. 94 * Must be called before the wallet runs. 95 */ 96 // FIXME: Not implemented! 97 //void 98 //TALER_WALLET_set_jsfile(struct TALER_WALLET_Instance *twi, 99 // const char *filename); 100 101 /** 102 * Send a message to wallet-core. 103 * 104 * Responses will be sent asynchronously to the message handler 105 * set with #TALER_WALLET_set_message_handler. 106 */ 107 int 108 TALER_WALLET_send_request(struct TALER_WALLET_Instance *twi, 109 const char *request); 110 111 /** 112 * Run wallet-core in a thread. 113 * 114 * This function creates a new thread and returns immediately. 115 * 116 * Returns 0 on success or a non-zero error code otherwise. 117 */ 118 int 119 TALER_WALLET_run(struct TALER_WALLET_Instance *twi); 120 121 /** 122 * Block until the wallet returns. 123 */ 124 void 125 TALER_WALLET_join(struct TALER_WALLET_Instance *twi); 126 127 /** 128 * Destroy the wallet handle and free resources associated with it. 129 * 130 * Note that for a graceful shutdown of the wallet, 131 * an appropriate shutdown message should be sent first, 132 * and destroy() should only be called after the wallet has 133 * sent a response to the shutdown message. 134 */ 135 //void 136 //TALER_WALLET_destroy(struct TALER_WALLET_Instance *twi); 137 138 /** 139 * Handler for messages that should be logged. 140 * 141 * @param stream NOT YET IMPLEMENTED: indicator for the stream that 142 * the message is coming from, 143 */ 144 typedef void (*TALER_LogFn)(void *handler_p, int stream, const char *msg); 145 146 /** 147 * Redirect stderr and stdout to a function. 148 * 149 * Workaround for platforms where stderr is not visible in logs. 150 * 151 * @return 0 on success, error code otherwise 152 */ 153 int 154 TALER_start_redirect_std(TALER_LogFn logfn, void *handler_p); 155 156 /** 157 * Set the HTTP client implementation to be used by the wallet. 158 * 159 * @param twi wallet-core instance 160 * @param impl HTTP client implementation 161 */ 162 void 163 TALER_set_http_client_implementation(struct TALER_WALLET_Instance *twi, 164 struct JSHttpClientImplementation *impl); 165 166 /** 167 * Set the reference CuRL-based HTTP client implementation as the one 168 * to be used by the wallet. 169 * 170 * @param twi wallet-core instance 171 */ 172 void 173 TALER_set_curl_http_client(struct TALER_WALLET_Instance *twi); 174 175 #pragma mark - 176 /** 177 * Build JSHttpClientImplementation struct for native HTTP client implementation to be used by the wallet. 178 * 179 * @param req_create HTTP client implementation 180 * @param req_cancel HTTP client implementation 181 * @param handler_p Pointer to Handler's "this" 182 * or NULL if allocation failed 183 */ 184 struct JSHttpClientImplementation * 185 TALER_pack_http_client_implementation(JSHttpReqCreateFn req_create, 186 JSHttpReqCancelFn req_cancel, 187 void *handler_p); 188 189 #endif /*_TALER_WALLET_LIB_H */