taler_wallet_core_lib.h (5859B)
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 * Must not be called from a wallet message or log callback. 135 */ 136 void 137 TALER_WALLET_destroy(struct TALER_WALLET_Instance *twi); 138 139 /** 140 * Handler for messages that should be logged. 141 * 142 * @param stream NOT YET IMPLEMENTED: indicator for the stream that 143 * the message is coming from, 144 */ 145 typedef void (*TALER_LogFn)(void *handler_p, int stream, const char *msg); 146 147 /** 148 * Redirect stderr and stdout to a function. 149 * 150 * Workaround for platforms where stderr is not visible in logs. 151 * 152 * @return 0 on success, error code otherwise 153 */ 154 int 155 TALER_start_redirect_std(TALER_LogFn logfn, void *handler_p); 156 157 /** 158 * Set the HTTP client implementation to be used by the wallet. 159 * Must be called before #TALER_WALLET_run. 160 * 161 * @param twi wallet-core instance 162 * @param impl HTTP client implementation 163 */ 164 void 165 TALER_set_http_client_implementation(struct TALER_WALLET_Instance *twi, 166 struct JSHttpClientImplementation *impl); 167 168 /** 169 * Set the reference CuRL-based HTTP client implementation as the one 170 * to be used by the wallet. 171 * 172 * @param twi wallet-core instance 173 */ 174 void 175 TALER_set_curl_http_client(struct TALER_WALLET_Instance *twi); 176 177 #ifdef __APPLE__ 178 #pragma mark - 179 #endif 180 /** 181 * Build JSHttpClientImplementation struct for native HTTP client implementation to be used by the wallet. 182 * 183 * @param req_create HTTP client implementation 184 * @param req_cancel HTTP client implementation 185 * @param handler_p Pointer to Handler's "this" 186 * or NULL if allocation failed 187 */ 188 struct JSHttpClientImplementation * 189 TALER_pack_http_client_implementation(JSHttpReqCreateFn req_create, 190 JSHttpReqCancelFn req_cancel, 191 void *handler_p); 192 193 #endif /*_TALER_WALLET_LIB_H */