1 /* 2 * gnc-ab-utils.h -- 3 * 4 * This program is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU General Public License as 6 * published by the Free Software Foundation; either version 2 of 7 * the License, or (at your option) any later version. 8 * 9 * This program is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 * GNU General Public License for more details. 13 * 14 * You should have received a copy of the GNU General Public License 15 * along with this program; if not, contact: 16 * 17 * Free Software Foundation Voice: +1-617-542-5942 18 * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 19 * Boston, MA 02110-1301, USA gnu@gnu.org 20 */ 21 22 /** 23 * @addtogroup Import_Export 24 * @{ 25 * @addtogroup AqBanking 26 * @{ 27 * @file gnc-ab-utils.h 28 * @brief AqBanking utility functions 29 * @author Copyright (C) 2002 Christian Stimming <stimming@tuhh.de> 30 * @author Copyright (C) 2008 Andreas Koehler <andi5.py@gmx.net> 31 */ 32 33 #ifndef GNC_AB_UTILS_H 34 #define GNC_AB_UTILS_H 35 36 #include <glib.h> 37 #include <gtk/gtk.h> 38 #include <aqbanking/banking.h> 39 #include <gwenhywfar/version.h> 40 41 #include "Account.h" 42 43 G_BEGIN_DECLS 44 45 /** A define that combines the aqbanking version number into one single 46 * integer number. Assumption: Both MINOR and PATCHLEVEL numbers are 47 * in the interval [0..99]. */ 48 #define AQBANKING_VERSION_INT (10000 * AQBANKING_VERSION_MAJOR + 100 * AQBANKING_VERSION_MINOR + AQBANKING_VERSION_PATCHLEVEL) 49 50 /** A define that combines the gwenhywfar version number into one single 51 * integer number. Assumption: Both MINOR and PATCHLEVEL numbers are 52 * in the interval [0..99]. */ 53 #define GWENHYWFAR_VERSION_INT (10000 * GWENHYWFAR_VERSION_MAJOR + 100 * GWENHYWFAR_VERSION_MINOR + GWENHYWFAR_VERSION_PATCHLEVEL) 54 55 #if AQBANKING_VERSION_INT >= 59900 56 # define AQBANKING6 1 57 # define GNC_AB_ACCOUNT_SPEC AB_ACCOUNT_SPEC 58 # define GNC_AB_ACCOUNT_SPEC_LIST AB_ACCOUNT_SPEC_LIST 59 # define GNC_AB_JOB AB_TRANSACTION 60 # define GNC_AB_JOB_LIST2 AB_TRANSACTION_LIST2 61 # define GNC_AB_JOB_LIST2_ITERATOR AB_TRANSACTION_LIST2_ITERATOR 62 # define GNC_AB_JOB_STATUS AB_TRANSACTION_STATUS 63 # define GNC_GWEN_DATE GWEN_DATE 64 #else 65 # define GNC_AB_ACCOUNT_SPEC AB_ACCOUNT 66 # define GNC_AB_ACCOUNT_SPEC_LIST AB_ACCOUNT_LIST2 67 # define GNC_AB_JOB AB_JOB 68 # define GNC_AB_JOB_LIST2 AB_JOB_LIST2 69 # define GNC_AB_JOB_LIST2_ITERATOR AB_JOB_LIST2_ITERATOR 70 # define GNC_AB_JOB_STATUS AB_JOB_STATUS 71 # define GNC_GWEN_DATE GWEN_TIME 72 #endif 73 #if GWENHYWFAR_VERSION_INT >= 49900 74 # define GWENHYWFAR5 75 #endif 76 77 #define GNC_PREFS_GROUP_AQBANKING "dialogs.import.hbci" 78 #define GNC_PREF_FORMAT_SWIFT940 "format-swift-mt940" 79 #define GNC_PREF_FORMAT_SWIFT942 "format-swift-mt942" 80 #define GNC_PREF_FORMAT_DTAUS "format-dtaus" 81 #define GNC_PREF_USE_TRANSACTION_TXT "use-ns-transaction-text" 82 #define GNC_PREF_VERBOSE_DEBUG "verbose-debug" 83 84 typedef struct _GncABImExContextImport GncABImExContextImport; 85 86 #define AWAIT_BALANCES 1 << 1 87 #define FOUND_BALANCES 1 << 2 88 #define IGNORE_BALANCES 1 << 3 89 #define AWAIT_TRANSACTIONS 1 << 4 90 #define FOUND_TRANSACTIONS 1 << 5 91 #define IGNORE_TRANSACTIONS 1 << 6 92 93 /** 94 * Initialize the gwenhywfar library by calling GWEN_Init() and setting up 95 * gwenhywfar logging. 96 */ 97 void gnc_GWEN_Init(void); 98 99 /** 100 * Finalize the gwenhywfar library. 101 */ 102 void gnc_GWEN_Fini(void); 103 104 /** 105 * If there is a cached AB_BANKING object, return it initialized. Otherwise, 106 * create a new AB_BANKING, let it load its environment from its default 107 * configuration and cache it. 108 * 109 * @return The AB_BANKING object 110 */ 111 AB_BANKING *gnc_AB_BANKING_new(void); 112 113 /** 114 * Delete the AB_BANKING @a api. If this is also the one that was cached by 115 * gnc_AB_BANKING_new(), then all references are deleted, too. 116 * 117 * @param api AB_BANKING or NULL for the cached AB_BANKING object 118 */ 119 void gnc_AB_BANKING_delete(AB_BANKING *api); 120 121 /** 122 * Finish the AB_BANKING @a api. If this is also the one that was cached by 123 * gnc_AB_BANKING_new(), then finish only if the decremented reference count 124 * reaches zero. After this call, you may only call gnc_AB_BANKING_new() to get 125 * the api again in a properly initialized state. 126 * 127 * @param api AB_BANKING object 128 * @return Zero on success 129 */ 130 gint gnc_AB_BANKING_fini(AB_BANKING *api); 131 132 /** 133 * Get the corresponding AqBanking account to the GnuCash account @a gnc_acc. 134 * Of course this only works after the GnuCash account has been set up for 135 * AqBanking use, i.e. the account's hbci data have been set up and populated. 136 * 137 * @param api The AB_BANKING to get the GNC_AB_ACCOUNT_SPEC from 138 * @param gnc_acc The GnuCash account to query for GNC_AB_ACCOUNT_SPEC reference data 139 * @return The GNC_AB_ACCOUNT_SPEC found or NULL otherwise 140 */ 141 GNC_AB_ACCOUNT_SPEC *gnc_ab_get_ab_account(const AB_BANKING *api, Account *gnc_acc); 142 143 /** 144 * Print the value of @a value with two decimal places and @a value's 145 * currency appended, or 0.0 otherwise 146 * 147 * @param value AB_VALUE or NULL 148 * @return A newly allocated string 149 */ 150 gchar *gnc_AB_VALUE_to_readable_string(const AB_VALUE *value); 151 152 /** 153 * Return the job as string. 154 * 155 * @param value GNC_AB_JOB or NULL 156 * @return A newly allocated string 157 */ 158 gchar *gnc_AB_JOB_to_readable_string(const GNC_AB_JOB *job); 159 160 /** 161 * Return the job_id as string. 162 * 163 * @param job_id 164 * @return A newly allocated string 165 */ 166 gchar *gnc_AB_JOB_ID_to_string(gulong job_id); 167 168 /** 169 * Retrieve the merged "remote name" fields from a transaction. The returned 170 * string must be g_free'd by the caller. If there was no "remote name" field, 171 * NULL (!) is returned. 172 * 173 * @param ab_trans AqBanking transaction 174 * @return A newly allocated string or NULL otherwise 175 */ 176 gchar *gnc_ab_get_remote_name(const AB_TRANSACTION *ab_trans); 177 178 /** 179 * Retrieve the merged purpose fields from a transaction. The returned string 180 * must be g_free'd by the caller. If there was no purpose, an empty (but 181 * allocated) string is returned. 182 * 183 * @param ab_trans AqBanking transaction 184 * @return A newly allocated string, may be "" 185 */ 186 gchar *gnc_ab_get_purpose(const AB_TRANSACTION *ab_trans, gboolean is_ofx); 187 188 /** 189 * Create the appropriate description field for a GnuCash Transaction by the 190 * information given in the AB_TRANSACTION @a ab_trans. The returned string 191 * must be g_free'd by the caller. 192 * 193 * @param ab_trans AqBanking transaction 194 * @return A newly allocated string, may be "" 195 */ 196 gchar *gnc_ab_description_to_gnc(const AB_TRANSACTION *ab_trans, gboolean is_ofx); 197 198 /** 199 * Create the appropriate memo field for a GnuCash Split by the information 200 * given in the AB_TRANSACTION @a ab_trans. The returned string must be 201 * g_free'd by the caller. 202 * 203 * @param ab_trans AqBanking transaction 204 * @return A newly allocated string, may be "" 205 */ 206 gchar *gnc_ab_memo_to_gnc(const AB_TRANSACTION *ab_trans); 207 208 /** 209 * Create an unbalanced and dirty GnuCash transaction with a split to @a gnc_acc 210 * from the information available in the AqBanking transaction @a ab_trans. 211 * 212 * @param ab_trans AqBanking transaction 213 * @param gnc_acc Account of to use for the split 214 * @return A dirty GnuCash transaction or NULL otherwise 215 */ 216 Transaction *gnc_ab_trans_to_gnc(const AB_TRANSACTION *ab_trans, Account *gnc_acc); 217 218 /** 219 * Import balances and transactions found in a AB_IMEXPORTER_CONTEXT into 220 * GnuCash. By using @a awaiting the caller can specify what the user will 221 * expect to receive. By using @a execute_txns, transactions in @a context can 222 * be used to generate corresponding AqBanking jobs, e.g. after a file import. 223 * 224 * @param context AB_IMEXPORTER_CONTEXT to import 225 * 226 * @param awaiting Information the caller expects to receive or wants to ignore, 227 * bitmask of AWAIT_* or IGNORE_* values 228 * 229 * @param execute_txns If @a awaiting contains AWAIT_TRANSACTIONS, whether to 230 * create an aqbanking job for each of the transactions found 231 * 232 * @param api If @a execute_txns is TRUE, the AB_BANKING to get 233 * GNC_AB_ACCOUNT_SPECs from 234 * 235 * @param parent Widget to set new dialogs transient for, may be NULL 236 * 237 * @return A new GncABImExContextImport object which must be freed with 238 * g_free(), or NULL otherwise. If execute_txns is TRUE, additionally 239 * gnc_ab_ieci_get_job_list() must be called and the result freed with 240 * AB_Job_List2_FreeAll() 241 */ 242 GncABImExContextImport *gnc_ab_import_context( 243 AB_IMEXPORTER_CONTEXT *context, guint awaiting, gboolean execute_txns, 244 AB_BANKING *api, GtkWidget *parent); 245 246 /** 247 * Extract awaiting from @a data. 248 * 249 * @param ieci The return value of gnc_ab_import_context() 250 * @return The initial awaiting bitmask plus IGNORE_* for unexpected and then 251 * ignored items, and FOUND_* for non-empty items 252 */ 253 guint gnc_ab_ieci_get_found(GncABImExContextImport *ieci); 254 255 /** 256 * Extract the job list from @a data. 257 * 258 * @param ieci The return value of gnc_ab_import_context() 259 * @return The list of jobs, freeable with AB_Job_List2_FreeAll() 260 */ 261 GNC_AB_JOB_LIST2 *gnc_ab_ieci_get_job_list(GncABImExContextImport *ieci); 262 263 /** 264 * Run the generic transaction matcher dialog. 265 * 266 * @param ieci The return value of gnc_ab_import_context() 267 * @return The return value of gnc_gen_trans_list_run(). 268 */ 269 gboolean gnc_ab_ieci_run_matcher(GncABImExContextImport *ieci); 270 271 272 /** 273 * get the GWEN_DB_NODE from AqBanking configuration files 274 * 275 * @return a GWEN_DB containing all permanently accepted SSL certificates (hashed). 276 */ 277 GWEN_DB_NODE *gnc_ab_get_permanent_certs(void); 278 279 /** 280 * Creates an online ID from bank code and account number. 281 * 282 * The returned string must be g_free'd by the caller. 283 * 284 * @param bankcode Bank code 285 * @param accountnumber Account number 286 * @return an online ID 287 */ 288 gchar* gnc_ab_create_online_id(const gchar *bankcode, const gchar *accountnumber); 289 290 291 #if (AQBANKING_VERSION_INT >= 60400) 292 /** 293 * Obtain the list of templates based on the aqbanking account spec's target accounts. 294 * 295 * @param ab_abb aqbanking account spec. 296 * @return A GList of newly allocated GncABTransTempls 297 */ 298 GList* 299 gnc_ab_trans_templ_list_new_from_ref_accounts(GNC_AB_ACCOUNT_SPEC *ab_acc); 300 #endif 301 302 G_END_DECLS 303 304 /** @} */ 305 /** @} */ 306 307 #endif /* GNC_AB_UTILS_H */ 308