Main Interface


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).


Constructor, Destructor, Init, Fini

This object is prepared to be inherited (using GWEN_INHERIT_SETDATA).

AB_BANKINGAB_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

Typedefs

typedef struct AB_BANKING AB_BANKING


Define Documentation

#define AB_BANKING_EXTENSION_NONE   0x00000000

Definition at line 88 of file aqbanking/banking.h.


Typedef Documentation

typedef struct AB_BANKING AB_BANKING

Object to be operated on by functions in this group (AB_BANKING).

Definition at line 27 of file aqbanking/banking.h.


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.

int AB_Banking_Fini ( AB_BANKING ab  ) 

Deinitializes AqBanking thus allowing it to save its data and to unload backends.

Returns:
0 if ok, error code otherwise (see Error Codes)
Parameters:
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.

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.

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.

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

int AB_Banking_Init ( AB_BANKING ab  ) 

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 interface

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


Generated on Thu Aug 19 20:22:14 2010 for aqbanking by  doxygen 1.5.6