1 /*************************************************************************** 2 begin : Mon Mar 01 2004 3 copyright : (C) 2018 by Martin Preuss 4 email : martin@libchipcard.de 5 6 *************************************************************************** 7 * This file is part of the project "AqBanking". * 8 * Please see toplevel file COPYING of that project for license details. * 9 ***************************************************************************/ 10 11 /** @file aqbanking/provider.h 12 * @short This file is used by AqBanking and provider backends. 13 */ 14 15 16 #ifndef AQBANKING_PROVIDER_H 17 #define AQBANKING_PROVIDER_H 18 19 #include <aqbanking/error.h> /* for AQBANKING_API */ 20 21 #include <gwenhywfar/misc.h> 22 #include <gwenhywfar/list2.h> 23 #include <gwenhywfar/inherit.h> 24 #include <gwenhywfar/xml.h> 25 26 27 #define AB_PROVIDER_FLAGS_COMPLETE_DAY_REPORTS 0x00000001 28 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 typedef struct AB_PROVIDER AB_PROVIDER; 35 GWEN_INHERIT_FUNCTION_DEFS(AB_PROVIDER) 36 GWEN_LIST2_FUNCTION_DEFS(AB_PROVIDER, AB_Provider) 37 38 typedef struct AB_PROVIDER_DESCRIPTION AB_PROVIDER_DESCRIPTION; 39 GWEN_INHERIT_FUNCTION_DEFS(AB_PROVIDER_DESCRIPTION) 40 GWEN_LIST_FUNCTION_DEFS(AB_PROVIDER_DESCRIPTION, AB_ProviderDescription) 41 GWEN_LIST2_FUNCTION_DEFS(AB_PROVIDER_DESCRIPTION, AB_ProviderDescription) 42 43 #ifdef __cplusplus 44 } 45 #endif 46 47 48 #include <aqbanking/banking.h> 49 50 51 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 55 /** @addtogroup G_AB_PROVIDER 56 * 57 * @brief This group represents backends. (Don't use in applications) 58 * 59 * <p> 60 * (<i>Provider</i> is simply another word for <i>backend</i>.) 61 * </p> 62 * 63 * <p> 64 * Functions in this group <b>MUST NEVER</b> be used by applications or 65 * depending libraries ! They may only be called by AqBanking or a provider 66 * on its own. 67 * </p> 68 * 69 * <p> 70 * Writing an online banking provider for AqBanking is easy. There are only 71 * a few callback functions which must be set by the provider (marked as 72 * <i>Virtual Functions</i> below). 73 * </p> 74 * 75 * <p> 76 * The work of a provider is based on jobs (see @ref AB_JOB). 77 * AqBanking also works based on jobs. If the application wants to create 78 * a job AqBanking calls the function @ref AB_Provider_UpdateJob. This 79 * function lets the provider prepare some parameters for the job given (e.g. 80 * the maximum number of purpose lines for transfer jobs etc). These limits 81 * are used by applications when preparing a job. 82 * </p> 83 * <p> 84 * If the application is finished preparing the job it calls 85 * @ref AB_Banking_EnqueueJob. After the application has enqueued all jobs 86 * it calls @ref AB_Banking_ExecuteQueue. This function now sends all jobs 87 * to their respective providers using @ref AB_Provider_AddJob. When all 88 * jobs for a given provider are added AqBanking calls 89 * @ref AB_Provider_Execute on this provider. This functions really sends the 90 * jobs to the bank server or creates DTAUS discs or whatever the provider is 91 * supposed to do. 92 * After that AqBanking calls @ref AB_Provider_ResetQueue to make sure no job 93 * is left in the providers queue after execution. 94 * </p> 95 * <p> 96 * Another base class used between AqBanking and providers is @ref AB_ACCOUNT. 97 * An account stores a reference to its associated provider. 98 * When executing @ref AB_Banking_Init AqBanking calls the provider function 99 * @ref AB_Provider_ExtendAccount on every account to let the backend 100 * initialize the account. 101 * </p> 102 * <p> 103 * It is the same with @ref AB_USER. 104 * </p> 105 */ 106 /*@{*/ 107 108 /** 109 * Returns the name of the backend (e.g. "aqhbci"). 110 */ 111 const char *AB_Provider_GetName(const AB_PROVIDER *pro); 112 113 /** 114 * Returns the escaped name of the backend. This is needed when using the 115 * name of the backend to form a file path. 116 */ 117 const char *AB_Provider_GetEscapedName(const AB_PROVIDER *pro); 118 /** 119 * Returns the Banking object that this Provider belongs to. 120 */ 121 AB_BANKING *AB_Provider_GetBanking(const AB_PROVIDER *pro); 122 123 124 uint32_t AB_Provider_GetFlags(const AB_PROVIDER *pro); 125 126 /** 127 * This copies the name of the folder for AqBanking's backend data into 128 * the given GWEN_Buffer. This folder is reserved for this backend. 129 * Please note that this folder does not necessarily exist, but the backend 130 * is free to create it. 131 * @return 0 if ok, error code otherwise (see @ref AB_ERROR) 132 * @param pro pointer to the provider object 133 * @param buf buffer to append the path name to 134 */ 135 int AB_Provider_GetUserDataDir(const AB_PROVIDER *pro, GWEN_BUFFER *buf); 136 137 138 /*@}*/ /* defgroup */ 139 140 #ifdef __cplusplus 141 } 142 #endif 143 144 145 146 147 #endif /* AQBANKING_PROVIDER_H */ 148 149 150 151 152 153 154 155 156 157