A program should first call AB_Banking_Init to allow AqBanking to load its configuration files and initialize itself. After that you may call any other function of this group (most likely the program will request a list of managed account via AB_Banking_GetAccounts).
When the program has finished its work it should call AB_Banking_Fini as the last function of AqBanking (just before calling AB_Banking_free).
Extensions supported by the application | |
#define | AB_BANKING_EXTENSION_NONE 0x00000000 |
#define | AB_BANKING_EXTENSION_NESTING_PROGRESS 0x00000001 |
Constructor, Destructor, Init, Fini | |
AB_BANKING * | AB_Banking_new (const char *appName, const char *dname) |
AB_BANKING * | AB_Banking_newExtended (const char *appName, const char *dname, GWEN_TYPE_UINT32 extensions) |
void | AB_Banking_free (AB_BANKING *ab) |
int | AB_Banking_Init (AB_BANKING *ab) |
int | AB_Banking_Fini (AB_BANKING *ab) |
int | AB_Banking_Save (AB_BANKING *ab) |
Working With Backends | |
Working with backends - as far as the frontend is concerned - is very simple. An application typically does this upon initial setup:
Please note that for security reasons a backend is only used when it has explicitly been activated. So if any backend is added to AqBanking by installing it you will still need to activate it to make use of it.
However, the activation state is preserved across shutdowns of AqBanking, so a backend remains active until it is explicitly deactivated. | |
const GWEN_STRINGLIST * | AB_Banking_GetActiveProviders (const AB_BANKING *ab) |
int | AB_Banking_ActivateProvider (AB_BANKING *ab, const char *backend) |
int | AB_Banking_DeactivateProvider (AB_BANKING *ab, const char *backend) |
int | AB_Banking_IsProviderActive (AB_BANKING *ab, const char *backend) |
int | AB_Banking_FindWizard (AB_BANKING *ab, const char *backend, const char *frontends, GWEN_BUFFER *pbuf) |
int | AB_Banking_FindDebugger (AB_BANKING *ab, const char *backend, const char *frontends, GWEN_BUFFER *pbuf) |
Application Data | |
Applications may let AqBanking store global application specific data. In addition, account specific data can also be stored using AB_Account_GetAppData. | |
const char * | AB_Banking_GetAppName (const AB_BANKING *ab) |
const char * | AB_Banking_GetEscapedAppName (const AB_BANKING *ab) |
GWEN_DB_NODE * | AB_Banking_GetAppData (AB_BANKING *ab) |
GWEN_DB_NODE * | AB_Banking_GetSharedData (AB_BANKING *ab, const char *name) |
int | AB_Banking_GetUserDataDir (const AB_BANKING *ab, GWEN_BUFFER *buf) |
int | AB_Banking_GetAppUserDataDir (const AB_BANKING *ab, GWEN_BUFFER *buf) |
int | AB_Banking_GetSharedDataDir (const AB_BANKING *ab, const char *name, GWEN_BUFFER *buf) |
void * | AB_Banking_GetUserData (AB_BANKING *ab) |
void | AB_Banking_SetUserData (AB_BANKING *ab, void *user_data) |
Plugin Handling | |
GWEN_PLUGIN_DESCRIPTION_LIST2 * | AB_Banking_GetProviderDescrs (AB_BANKING *ab) |
GWEN_PLUGIN_DESCRIPTION_LIST2 * | AB_Banking_GetWizardDescrs (AB_BANKING *ab) |
GWEN_PLUGIN_DESCRIPTION_LIST2 * | AB_Banking_GetDebuggerDescrs (AB_BANKING *ab, const char *pn) |
Handling SSL Certificates | |
int | AB_Banking_GetAlwaysAskForCert (const AB_BANKING *ab) |
void | AB_Banking_SetAlwaysAskForCert (AB_BANKING *ab, int i) |
Typedefs | |
typedef AB_BANKING | AB_BANKING |
#define AB_BANKING_EXTENSION_NESTING_PROGRESS 0x00000001 |
If this flag is set then the application allows nesting progress dialogs. If the application does it might be best to use the toplevel progress widget and just add a progress bar to it. If this flag is not set then AqBanking keeps track of the nesting level and dismisses further calls to AB_Banking_ProgressStart until AB_Banking_ProgressEnd has been called often enough to reset the nesting counter. I.e. the application will not receive nesting calls to AB_Banking_ProgressStart.
Definition at line 95 of file aqbanking/banking.h.
#define AB_BANKING_EXTENSION_NONE 0x00000000 |
Definition at line 84 of file aqbanking/banking.h.
typedef struct AB_BANKING AB_BANKING |
Object to be operated on by functions in this group (AB_BANKING).
Definition at line 26 of file aqbanking/banking.h.
int AB_Banking_ActivateProvider | ( | AB_BANKING * | ab, | |
const char * | backend | |||
) |
Activates a backend. It remains active (even across shutdowns of AqBanking) until it is explicitly deactivated (using AB_Banking_DeactivateProvider).
This function automatically imports all accounts presented by the backend.
ab | banking interface | |
backend | name of the backend (such as "aqhbci". You can retrieve such a backend either from the list of active backends (AB_Banking_GetActiveProviders) or from an plugin description retrieved via AB_Banking_GetProviderDescrs (call GWEN_PluginDescription_GetName on that plugin description). |
int AB_Banking_DeactivateProvider | ( | AB_BANKING * | ab, | |
const char * | backend | |||
) |
Deactivates a backend. This is the default state for backends until they have explicitly been activated by AB_Banking_ActivateProvider.
ab | banking interface | |
backend | name of the backend (such as "aqhbci". You can retrieve such a name either from the list of active backends (AB_Banking_GetActiveProviders) or from an plugin description retrieved via AB_Banking_GetProviderDescrs (call GWEN_PluginDescription_GetName on that plugin description). |
int AB_Banking_FindDebugger | ( | AB_BANKING * | ab, | |
const char * | backend, | |||
const char * | frontends, | |||
GWEN_BUFFER * | pbuf | |||
) |
This function simpifies debugger handling. It searches for a debugger for the given backend and the given frontends.
ab | pointer to the AB_BANKING object | |||||||||
backend | name of the backend (such as "aqhbci". You can retrieve such a name either from the list of active backends (AB_Banking_GetActiveProviders) or from an plugin description retrieved via AB_Banking_GetProviderDescrs (call GWEN_PluginDescription_GetName on that plugin description). | |||||||||
frontends | This is a semicolon separated list of acceptable frontends The following lists merely are suggestions:
|
int AB_Banking_FindWizard | ( | AB_BANKING * | ab, | |
const char * | backend, | |||
const char * | frontends, | |||
GWEN_BUFFER * | pbuf | |||
) |
This function simpifies wizard handling. It searches for a wizard for the given frontends.
ab | pointer to the AB_BANKING object | |||||||||
backend | This argument is no longer being used. For aqbanking >= 2.0.1 it can be NULL, but for aqbanking <= 2.0.0 it must be set to non-null. The argument is completely ignored since aqbanking>=1.9.0. | |||||||||
frontends | A semicolon-separated list of acceptable frontends, or NULL. The following strings are suggested:
|
int AB_Banking_Fini | ( | AB_BANKING * | ab | ) |
Deinitializes AqBanking thus allowing it to save its data and to unload backends.
ab | banking interface |
void AB_Banking_free | ( | AB_BANKING * | ab | ) |
Destroys the given instance of AqBanking. Please note that if AB_Banking_Init has been called on this object then AB_Banking_Fini should be called before this function.
const GWEN_STRINGLIST* AB_Banking_GetActiveProviders | ( | const AB_BANKING * | ab | ) |
Returns a list of the names of currently active providers.
int AB_Banking_GetAlwaysAskForCert | ( | const AB_BANKING * | ab | ) |
This influences the behaviour of AqBanking when new certificates are received. If the returned value is !=0 then the user will be asked for every single certificate received.
GWEN_DB_NODE* AB_Banking_GetAppData | ( | AB_BANKING * | ab | ) |
Returns a GWEN_DB_NODE which can be used to store/retrieve data for the currently running application. The group returned MUST NOT be freed ! AqBanking is able to separate and store the data for every application.
ab | pointer to the AB_BANKING object |
const char* AB_Banking_GetAppName | ( | const AB_BANKING * | ab | ) |
Returns the application name as given to AB_Banking_new.
ab | pointer to the AB_BANKING object |
int AB_Banking_GetAppUserDataDir | ( | const AB_BANKING * | ab, | |
GWEN_BUFFER * | buf | |||
) |
Returns the name of the user folder for application data. Normally this is something like "/home/me/.banking/apps". Your application may choose to create folders below this one to store user data. If you only add AqBanking to an existing program to add home banking support you will most likely use your own folders and thus won't need this function.
ab | pointer to the AB_BANKING object | |
buf | GWEN_BUFFER to append the path name to |
GWEN_PLUGIN_DESCRIPTION_LIST2* AB_Banking_GetDebuggerDescrs | ( | AB_BANKING * | ab, | |
const char * | pn | |||
) |
Returns a list2 of debugger descriptions for the given backend. You must free this list after using it via GWEN_PluginDescription_List2_freeAll. Please note that a simple GWEN_PluginDescription_List2_free would not suffice, since that would only free the list but not the objects stored within the list !
ab | pointer to the AB_BANKING object | |
pn | name of the backend (such as "aqhbci". You can retrieve such a name either from the list of active backends (AB_Banking_GetActiveProviders) or from an plugin description retrieved via AB_Banking_GetProviderDescrs (call GWEN_PluginDescription_GetName on that plugin description). |
const char* AB_Banking_GetEscapedAppName | ( | const AB_BANKING * | ab | ) |
Returns the escaped version of the application name. This name can safely be used to create file paths since all special characters (like '/', '.' etc) are escaped.
ab | pointer to the AB_BANKING object |
GWEN_PLUGIN_DESCRIPTION_LIST2* AB_Banking_GetProviderDescrs | ( | AB_BANKING * | ab | ) |
Returns a list2 of provider descriptions. You must free this list after using it via GWEN_PluginDescription_List2_freeAll. Please note that a simple GWEN_PluginDescription_List2_free would not suffice, since that would only free the list but not the objects stored within the list !
ab | pointer to the AB_BANKING object |
GWEN_DB_NODE* AB_Banking_GetSharedData | ( | AB_BANKING * | ab, | |
const char * | name | |||
) |
Returns a GWEN_DB_NODE which can be used to store/retrieve data shared across multiple applications.
ab | pointer to the AB_BANKING object | |
name | name of the share. Special names are those of frontends and backends, so these names MUST NOT be used for applications (but they may be used by the corresponding frontends, e.g. the QT frontend QBanking used "qbanking" to store some frontend specific settings). |
int AB_Banking_GetSharedDataDir | ( | const AB_BANKING * | ab, | |
const char * | name, | |||
GWEN_BUFFER * | buf | |||
) |
Returns the path to a folder to which shared data can be stored. This might be used by multiple applications if they wish to share some of their data, e.g. QBankManager and AqMoney3 share their transaction storage so that both may work with it. Please note that this folder does not necessarily exist, but you are free to create it.
void* AB_Banking_GetUserData | ( | AB_BANKING * | ab | ) |
Returns the void pointer that was stored by AB_Banking_SetUserData(). This might be useful for passing data to the callback functions.
On the other hand, we strongly encourage using the GWEN_INHERIT macros to store non-trivial data structures in this object.
ab | Pointer to the AB_BANKING object |
int AB_Banking_GetUserDataDir | ( | const AB_BANKING * | ab, | |
GWEN_BUFFER * | buf | |||
) |
Returns the name of the user folder for AqBanking's data. Normally this is something like "/home/me/.banking".
ab | pointer to the AB_BANKING object | |
buf | GWEN_BUFFER to append the path name to |
GWEN_PLUGIN_DESCRIPTION_LIST2* AB_Banking_GetWizardDescrs | ( | AB_BANKING * | ab | ) |
Returns a list2 of wizard descriptions. You must free this list after using it via GWEN_PluginDescription_List2_freeAll. Please note that a simple GWEN_PluginDescription_List2_free would not suffice, since that would only free the list but not the objects stored within the list !
ab | pointer to the AB_BANKING object |
int AB_Banking_Init | ( | AB_BANKING * | ab | ) |
Initializes AqBanking. This actually reads the configuration file, thus loading account settings and backends as needed.
ab | banking interface |
int AB_Banking_IsProviderActive | ( | AB_BANKING * | ab, | |
const char * | backend | |||
) |
This function checks whether the given backend is currently active. It returns 0 if the backend is inactive.
AB_BANKING* AB_Banking_new | ( | const char * | appName, | |
const char * | dname | |||
) |
Creates an instance of AqBanking. Though AqBanking is quite object oriented (and thus allows multiple instances of AB_BANKING to co-exist) you should avoid having multiple AB_BANKING objects in parallel.
This is just because the backends are loaded dynamically and might not like to be used with multiple instances of AB_BANKING in parallel.
You should later free this object using AB_Banking_free.
This function does not actually load the configuration file or setup AqBanking, that is performed by AB_Banking_Init.
Please note that this function sets a new handler for incoming SSL certificates using GWEN_NetTransportSSL_SetAskAddCertFn2(), so if you want to handle this in your application yourself you must overwrite this handler after calling this function here.
Please note: This function internally calls AB_Banking_newExtended with the value 0 for extensions. So if your program supports any extension you should call AB_Banking_newExtended instead of this function.
appName | name of the application which wants to use AqBanking. This allows AqBanking to separate settings and data for multiple applications. | |
dname | Path for the directory containing the user data of AqBanking. You should in most cases present a NULL for this parameter, which means AqBanking will choose the default user data folder which is "$HOME/.banking". The configuration file "settings.conf" file is searched for in this folder. NOTE: Versions of AqBanking before 1.2.0.16 used this argument to specify the path and name (!) of the configuration file, whereas now this specifies only the path. It is now impossible to specify the name; aqbanking will always use its default name "settings.conf". For AqBanking < 1.2.0.16, the default configuration file was "$HOME/.aqbanking.conf". This file is now also searched for, but if it exists it will be moved to the new default path and name upon AB_Banking_Fini. The new path will be "$HOME/.banking/settings.conf". |
AB_BANKING* AB_Banking_newExtended | ( | const char * | appName, | |
const char * | dname, | |||
GWEN_TYPE_UINT32 | extensions | |||
) |
This does the same as AB_Banking_new. In addition, the application may state here the extensions it supports. See AB_BANKING_EXTENSION_NONE and following. This is used to keep the number of callbacks to the application small (otherswise whenever we add a flag which changes the expected behaviour of a GUI callback we would have to introduce a new callback in order to maintain binary compatibility).
int AB_Banking_Save | ( | AB_BANKING * | ab | ) |
Saves all data. You may call this function periodically (especially after doing setup stuff).
ab | banking interface |
void AB_Banking_SetAlwaysAskForCert | ( | AB_BANKING * | ab, | |
int | i | |||
) |
This influences the behaviour of AqBanking when new certificates are received. If the given value is !=0 then the user will be asked for every single certificate received.
void AB_Banking_SetUserData | ( | AB_BANKING * | ab, | |
void * | user_data | |||
) |
Save the void pointer that can be retrieved by AB_Banking_GetUserData(). This might be useful for passing data to the callback functions.
On the other hand, we strongly encourage using the GWEN_INHERIT macros to store non-trivial data structures in this object.
ab | Pointer to the AB_BANKING object | |
user_data | Arbitrary pointer to be stored in the AB_BANKING |