Main Interface
This group contains the main API function group.
More...
Typedefs |
typedef struct AB_BANKING | AB_BANKING |
Constructor, Destructor, Init, Fini |
This object is prepared to be inherited (using GWEN_INHERIT_SETDATA).
|
AB_BANKING * | AB_Banking_new (const char *appName, const char *dname, uint32_t extensions) |
void | AB_Banking_free (AB_BANKING *ab) |
void | AB_Banking_GetVersion (int *major, int *minor, int *patchlevel, int *build) |
int | AB_Banking_Init (AB_BANKING *ab) |
int | AB_Banking_Fini (AB_BANKING *ab) |
int | AB_Banking_OnlineInit (AB_BANKING *ab, uint32_t guiid) |
int | AB_Banking_OnlineFini (AB_BANKING *ab, uint32_t guiid) |
Working With Backends |
Working with backends - as far as the frontend is concerned - is very simple.
An application typically does this upon initial setup:
|
const GWEN_STRINGLIST * | AB_Banking_GetActiveProviders (const AB_BANKING *ab) |
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) |
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) |
Extensions supported by the application |
|
#define | AB_BANKING_EXTENSION_NONE 0x00000000 |
Detailed Description
This group contains the main API function group.
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).
Define Documentation
#define AB_BANKING_EXTENSION_NONE 0x00000000 |
Typedef Documentation
Function Documentation
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.
- Parameters:
-
| 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:
KDE Applications | kde;qt;gtk;gnome |
QT Applications | qt;kde;gtk;gnome |
GNOME Applications | gnome;gtk;qt;kde |
GTK Applications | gtk;gnome;qt;kde |
You can always add an asterisk ("*") to the list to accept any other frontend (or pass a NULL pointer to accept the first valid frontend). |
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.
- Parameters:
-
| 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:
KDE Applications | kde;qt;gtk;gnome |
QT Applications | qt;kde;gtk;gnome |
GNOME Applications | gnome;gtk;qt;kde |
GTK Applications | gtk;gnome;qt;kde |
Alternatively, you can always add an asterisk ("*") to the list to accept any other frontend, or pass a NULL pointer to accept the first valid frontend. |
Deinitializes AqBanking thus allowing it to save its data and to unload backends.
- Returns:
- 0 if ok, error code otherwise (see Error Codes)
- Parameters:
-
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.
const char* AB_Banking_GetAppName |
( |
const AB_BANKING * |
ab |
) |
|
Returns the application name as given to AB_Banking_new.
- Parameters:
-
| 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/.aqbanking/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.
- Returns:
- 0 if ok, error code otherwise (see Error Codes)
- Parameters:
-
| 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 !
- Parameters:
-
| 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.
- Parameters:
-
| 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 !
- Parameters:
-
| ab | pointer to the AB_BANKING object |
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.
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.
- Parameters:
-
| 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/.aqbanking".
- Returns:
- 0 if ok, error code otherwise (see Error Codes)
- Parameters:
-
| ab | pointer to the AB_BANKING object |
| buf | GWEN_BUFFER to append the path name to |
void AB_Banking_GetVersion |
( |
int * |
major, |
|
|
int * |
minor, |
|
|
int * |
patchlevel, |
|
|
int * |
build | |
|
) |
| | |
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 !
- Parameters:
-
| ab | pointer to the AB_BANKING object |
Initializes AqBanking. This actually reads the configuration file, thus loading account settings and backends as needed.
- Returns:
- 0 if ok, error code otherwise (see Error Codes)
- Parameters:
-
AB_BANKING* AB_Banking_new |
( |
const char * |
appName, |
|
|
const char * |
dname, |
|
|
uint32_t |
extensions | |
|
) |
| | |
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: 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. 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).
- Returns:
- new instance of AB_BANKING
- Parameters:
-
| 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/.aqbanking". 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/.aqbanking/settings.conf". |
int AB_Banking_OnlineFini |
( |
AB_BANKING * |
ab, |
|
|
uint32_t |
guiid | |
|
) |
| | |
int AB_Banking_OnlineInit |
( |
AB_BANKING * |
ab, |
|
|
uint32_t |
guiid | |
|
) |
| | |
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.
- Parameters:
-
| ab | Pointer to the AB_BANKING object |
| user_data | Arbitrary pointer to be stored in the AB_BANKING |