banking.h File Reference

The main interface of the aqbanking library. More...

#include <gwenhywfar/inherit.h>
#include <gwenhywfar/types.h>
#include <gwenhywfar/db.h>
#include <gwenhywfar/stringlist.h>
#include <gwenhywfar/plugindescr.h>
#include <aqbanking/error.h>
#include <aqbanking/version.h>
#include <aqbanking/job.h>
#include <aqbanking/provider.h>
#include <aqbanking/imexporter.h>
#include <aqbanking/bankinfoplugin.h>
#include <aqbanking/bankinfo.h>
#include <aqbanking/country.h>

Go to the source code of this file.

Extensions supported by the application

#define AB_BANKING_EXTENSION_NONE   0x00000000
#define AB_BANKING_EXTENSION_NESTING_PROGRESS   0x00000001

Flags For AB_Banking_InputBox

These flags are given to AB_Banking_InputBox to modify its behaviour.

#define AB_BANKING_INPUT_FLAGS_CONFIRM   0x00000001
#define AB_BANKING_INPUT_FLAGS_SHOW   0x00000002
#define AB_BANKING_INPUT_FLAGS_NUMERIC   0x00000004
#define AB_BANKING_INPUT_FLAGS_RETRY   0x00000008
#define AB_BANKING_INPUT_FLAGS_ALLOW_DEFAULT   0x00000010

Flags For AB_Banking_MessageBox

These flags are given to AB_Banking_MessageBox to modify its behaviour. You may OR-combine the flags.
Examples:

A note about confirmation buttons: AqBanking has been designed with non-interactive applications in mind. For such an application it is important to know what button-press it has to simulate upon catching of a messagebox callback. This is what the confimation button flags are for. For informative messages the application may simply return the number of the confirmation button and be done.

However, non-interactive applications should return an error (value 0) for messages classified as dangerous (see AB_BANKING_MSG_FLAGS_SEVERITY_DANGEROUS) to avoid data loss.

#define AB_BANKING_MSG_FLAGS_TYPE_MASK   0x07
#define AB_BANKING_MSG_FLAGS_TYPE_INFO   0
#define AB_BANKING_MSG_FLAGS_TYPE_IS_INFO(fl)   ((fl & AB_BANKING_MSG_FLAGS_TYPE_MASK)==AB_BANKING_MSG_FLAGS_TYPE_INFO)
#define AB_BANKING_MSG_FLAGS_TYPE_WARN   1
#define AB_BANKING_MSG_FLAGS_TYPE_IS_WARN(fl)   ((fl & AB_BANKING_MSG_FLAGS_TYPE_MASK)==AB_BANKING_MSG_FLAGS_TYPE_WARN)
#define AB_BANKING_MSG_FLAGS_TYPE_ERROR   2
#define AB_BANKING_MSG_FLAGS_TYPE_IS_ERROR   ((fl & AB_BANKING_MSG_FLAGS_TYPE_MASK)==AB_BANKING_MSG_FLAGS_TYPE_ERROR)
#define AB_BANKING_MSG_FLAGS_CONFIRM_B1   (1<<3)
#define AB_BANKING_MSG_FLAGS_CONFIRM_B2   (2<<3)
#define AB_BANKING_MSG_FLAGS_CONFIRM_B3   (3<<3)
#define AB_BANKING_MSG_FLAGS_CONFIRM_BUTTON(fl)   ((fl & 0x3)>>3)
#define AB_BANKING_MSG_FLAGS_SEVERITY_MASK   (0x7<<5)
#define AB_BANKING_MSG_FLAGS_SEVERITY_NORMAL   (0x0<<5)
#define AB_BANKING_MSG_FLAGS_SEVERITY_IS_NORMAL(fl)
#define AB_BANKING_MSG_FLAGS_SEVERITY_DANGEROUS   (0x1<<5)
#define AB_BANKING_MSG_FLAGS_SEVERITY_IS_DANGEROUS(fl)

Flags For AB_Banking_ShowBox

#define AB_BANKING_SHOWBOX_FLAGS_BEEP   0x00000001

Prototypes For Virtual User Interaction Functions

typedef int(* AB_BANKING_MESSAGEBOX_FN )(AB_BANKING *ab, GWEN_TYPE_UINT32 flags, const char *title, const char *text, const char *b1, const char *b2, const char *b3)
typedef int(* AB_BANKING_INPUTBOX_FN )(AB_BANKING *ab, GWEN_TYPE_UINT32 flags, const char *title, const char *text, char *buffer, int minLen, int maxLen)
typedef GWEN_TYPE_UINT32(* AB_BANKING_SHOWBOX_FN )(AB_BANKING *ab, GWEN_TYPE_UINT32 flags, const char *title, const char *text)
typedef void(* AB_BANKING_HIDEBOX_FN )(AB_BANKING *ab, GWEN_TYPE_UINT32 id)
typedef GWEN_TYPE_UINT32(* AB_BANKING_PROGRESS_START_FN )(AB_BANKING *ab, const char *title, const char *text, GWEN_TYPE_UINT32 total)
typedef int(* AB_BANKING_PROGRESS_ADVANCE_FN )(AB_BANKING *ab, GWEN_TYPE_UINT32 id, GWEN_TYPE_UINT32 progress)
typedef int(* AB_BANKING_PROGRESS_LOG_FN )(AB_BANKING *ab, GWEN_TYPE_UINT32 id, AB_BANKING_LOGLEVEL level, const char *text)
typedef int(* AB_BANKING_PROGRESS_END_FN )(AB_BANKING *ab, GWEN_TYPE_UINT32 id)
typedef int(* AB_BANKING_PRINT_FN )(AB_BANKING *ab, const char *docTitle, const char *docType, const char *descr, const char *text)

Prototypes For Virtual Security Functions

typedef int(* AB_BANKING_GETPIN_FN )(AB_BANKING *ab, GWEN_TYPE_UINT32 flags, const char *token, const char *title, const char *text, char *buffer, int minLen, int maxLen)
typedef int(* AB_BANKING_SETPINSTATUS_FN )(AB_BANKING *ab, const char *token, const char *pin, AB_BANKING_PINSTATUS status)
typedef int(* AB_BANKING_GETTAN_FN )(AB_BANKING *ab, const char *token, const char *title, const char *text, char *buffer, int minLen, int maxLen)
typedef int(* AB_BANKING_SETTANSTATUS_FN )(AB_BANKING *ab, const char *token, const char *tan, AB_BANKING_TANSTATUS status)
enum  AB_BANKING_PINSTATUS { AB_Banking_PinStatusBad = -1, AB_Banking_PinStatusUnknown, AB_Banking_PinStatusOk }
enum  AB_BANKING_TANSTATUS { AB_Banking_TanStatusBad = -1, AB_Banking_TanStatusUnknown, AB_Banking_TanStatusUsed, AB_Banking_TanStatusUnused }

Constructor, Destructor, Init, Fini

AB_BANKINGAB_Banking_new (const char *appName, const char *dname)
AB_BANKINGAB_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_SuspendProvider (AB_BANKING *ab, const char *backend)
int AB_Banking_IsProviderActive (AB_BANKING *ab, const char *backend)
int AB_Banking_ResumeProvider (AB_BANKING *ab, const char *backend)
int AB_Banking_FindWizard (AB_BANKING *ab, const char *backend, const char *frontends, GWEN_BUFFER *pbuf)
AQBANKING_DEPRECATED int AB_Banking_GetWizardPath (AB_BANKING *ab, const char *backend, 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)
int AB_Banking_GetUserDataDir (const AB_BANKING *ab, GWEN_BUFFER *buf)
void AB_Banking_SetUserDataDir (AB_BANKING *ab, const char *s)
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)

Working With Accounts

AqBanking controls a list of accounts. You can ask it for the full list (AB_Banking_GetAccounts) or directly request a specific account (AB_Banking_GetAccount).

AB_ACCOUNT_LIST2AB_Banking_GetAccounts (const AB_BANKING *ab)
AB_ACCOUNTAB_Banking_GetAccount (const AB_BANKING *ab, GWEN_TYPE_UINT32 uniqueId)
AB_ACCOUNTAB_Banking_GetAccountByCodeAndNumber (const AB_BANKING *ab, const char *bankCode, const char *accountId)

Plugin Handling

GWEN_PLUGIN_DESCRIPTION_LIST2 * AB_Banking_GetProviderDescrs (AB_BANKING *ab)
GWEN_PLUGIN_DESCRIPTION_LIST2 * AB_Banking_GetWizardDescrs (AB_BANKING *ab, const char *pn)
GWEN_PLUGIN_DESCRIPTION_LIST2 * AB_Banking_GetDebuggerDescrs (AB_BANKING *ab, const char *pn)
GWEN_PLUGIN_DESCRIPTION_LIST2 * AB_Banking_GetImExporterDescrs (AB_BANKING *ab)
AB_IMEXPORTERAB_Banking_GetImExporter (AB_BANKING *ab, const char *name)
GWEN_DB_NODE * AB_Banking_GetImExporterProfiles (AB_BANKING *ab, const char *name)

Enqueueing, Dequeueing and Executing Jobs

AqBanking has several job lists:
  • enqueued jobs
  • finished jobs
  • pending jobs
  • archived jobs

Enqued jobs are a different from all the other jobs, because AqBanking holds a unique list of those enqueued jobs.

For example if you ask AqBanking for a list of finished jobs it reads the folder which contains those jobs and loads them one by one. This means if you call AB_Banking_GetFinishedJobs multiple times you get multiple representations of the finished jobs. You should have this in mind when manipulating those jobs/job lists returned.

Enqueued jobs however have only one representation, i.e. if you call AB_Banking_GetEnqueuedJobs multiple times you will always get a list which contains pointers to the very same enqueued jobs.

However, if you enqueue a job, execute the queue and later call AB_Banking_GetFinishedJobs you will again have multiple representations of the jobs you once had in the enqueued list, because after AB_Banking_GetFinishedJobs always creates a new representation of a job.

Enqueued jobs are preserved across shutdowns. As soon as a job has been sent to the appropriate backend it will be removed from the queue.

int AB_Banking_EnqueueJob (AB_BANKING *ab, AB_JOB *j)
int AB_Banking_DequeueJob (AB_BANKING *ab, AB_JOB *j)
int AB_Banking_DeferJob (AB_BANKING *ab, AB_JOB *j)
int AB_Banking_EnqueuePendingJobs (AB_BANKING *ab, int mineOnly)
int AB_Banking_ExecuteQueue (AB_BANKING *ab)
int AB_Banking_ExecuteJobList (AB_BANKING *ab, AB_JOB_LIST2 *jl2)
AB_JOB_LIST2AB_Banking_GetEnqueuedJobs (const AB_BANKING *ab)

Handling Finished Jobs

Finished jobs are those which have been handled by AB_Banking_ExecuteQueue.

Those jobs are saved into their particular folder directly after the queue has been executed. There is only one function you can call for those jobs: AB_Banking_DelFinishedJob.

Applications might use this group to check for the results of jobs formerly marked as pending and to apply these results to the corresponding accounts.

AB_JOB_LIST2AB_Banking_GetFinishedJobs (AB_BANKING *ab)
int AB_Banking_DelFinishedJob (AB_BANKING *ab, AB_JOB *j)

Handling Deferred Jobs

Deferred jobs are those which have been enqueued at some point and later deferred so that AB_Banking_ExecuteQueue won't include them.

You can re-enqueue this job at any time using AB_Banking_EnqueueJob.

AB_JOB_LIST2AB_Banking_GetDeferredJobs (AB_BANKING *ab)
int AB_Banking_DelDeferredJob (AB_BANKING *ab, AB_JOB *j)

Handling Pending Jobs

Pending jobs are those which have been handled by AB_Banking_ExecuteQueue but which did not yet return a result (like transfer jobs with some backends, which might be accepted by the bank but which are not immediately executed).

Those jobs are saved into their particular folder directly after the queue has been executed. You may requeue those jobs later (using AB_Banking_EnqueueJob) to allow the corresponding backend to check whether there is a result available for a pending job. If that's the case the job will be moved from the pending folder to the finished folder (accessible via AB_Banking_GetFinishedJobs).

AB_JOB_LIST2AB_Banking_GetPendingJobs (AB_BANKING *ab)
int AB_Banking_DelPendingJob (AB_BANKING *ab, AB_JOB *j)

Handling Archived Jobs

Archived jobs are those which have been handled by AB_Banking_ExecuteQueue and then later deleted from the list of finished jobs via any AB_Banking_Del(-XYZ-)Job function except AB_Banking_DelArchivedJob

AB_JOB_LIST2AB_Banking_GetArchivedJobs (AB_BANKING *ab)
int AB_Banking_DelArchivedJob (AB_BANKING *ab, AB_JOB *j)

Virtual User Interaction Functions

All text passed to the frontend via one of the following functions is expected to be an UTF-8 string which may contain newlines but no other control characters. Text delivered as argument called text throughout the documentation in this group may contain HTML tags. If it does a non-HTML version must be supplied, too. The text MUST begin with the non-HTML version, so that a frontend not capable of parsing HTML can simply exclude the HTML part by cutting before "<html".

This is an example for HTML and non-HTML text:

 const char *text;

 text="This is the non-HTML text"
      "<html>"
      "And this is the <b>HTML</b> version."
      "</html>"

Frontends capable of parsing HTML (such as the KDE frontend) will extract the HTML information and show only that part of the string.

Other frontends have to extract the non-HTML information and show only that.

int AB_Banking_MessageBox (AB_BANKING *ab, GWEN_TYPE_UINT32 flags, const char *title, const char *text, const char *b1, const char *b2, const char *b3)
int AB_Banking_InputBox (AB_BANKING *ab, GWEN_TYPE_UINT32 flags, const char *title, const char *text, char *buffer, int minLen, int maxLen)
GWEN_TYPE_UINT32 AB_Banking_ShowBox (AB_BANKING *ab, GWEN_TYPE_UINT32 flags, const char *title, const char *text)
void AB_Banking_HideBox (AB_BANKING *ab, GWEN_TYPE_UINT32 id)
GWEN_TYPE_UINT32 AB_Banking_ProgressStart (AB_BANKING *ab, const char *title, const char *text, GWEN_TYPE_UINT32 total)
int AB_Banking_ProgressAdvance (AB_BANKING *ab, GWEN_TYPE_UINT32 id, GWEN_TYPE_UINT32 progress)
int AB_Banking_ProgressLog (AB_BANKING *ab, GWEN_TYPE_UINT32 id, AB_BANKING_LOGLEVEL level, const char *text)
int AB_Banking_ProgressEnd (AB_BANKING *ab, GWEN_TYPE_UINT32 id)
int AB_Banking_Print (AB_BANKING *ab, const char *docTitle, const char *docType, const char *descr, const char *text)

Setters For Virtual User Interaction Functions

The functions in this group set the corresponding callback function pointers.

void AB_Banking_SetMessageBoxFn (AB_BANKING *ab, AB_BANKING_MESSAGEBOX_FN f)
void AB_Banking_SetInputBoxFn (AB_BANKING *ab, AB_BANKING_INPUTBOX_FN f)
void AB_Banking_SetShowBoxFn (AB_BANKING *ab, AB_BANKING_SHOWBOX_FN f)
void AB_Banking_SetHideBoxFn (AB_BANKING *ab, AB_BANKING_HIDEBOX_FN f)
void AB_Banking_SetProgressStartFn (AB_BANKING *ab, AB_BANKING_PROGRESS_START_FN f)
void AB_Banking_SetProgressAdvanceFn (AB_BANKING *ab, AB_BANKING_PROGRESS_ADVANCE_FN f)
void AB_Banking_SetProgressLogFn (AB_BANKING *ab, AB_BANKING_PROGRESS_LOG_FN f)
void AB_Banking_SetProgressEndFn (AB_BANKING *ab, AB_BANKING_PROGRESS_END_FN f)
void AB_Banking_SetPrintFn (AB_BANKING *ab, AB_BANKING_PRINT_FN f)

Virtual Security Functions And Associated Functions

int AB_Banking_GetPin (AB_BANKING *ab, GWEN_TYPE_UINT32 flags, const char *token, const char *title, const char *text, char *buffer, int minLen, int maxLen)
void AB_Banking_SetPinCacheEnabled (AB_BANKING *ab, int enabled)
int AB_Banking_GetPinCacheEnabled (const AB_BANKING *ab)
int AB_Banking_SetPinStatus (AB_BANKING *ab, const char *token, const char *pin, AB_BANKING_PINSTATUS status)
int AB_Banking_GetTan (AB_BANKING *ab, const char *token, const char *title, const char *text, char *buffer, int minLen, int maxLen)
int AB_Banking_SetTanStatus (AB_BANKING *ab, const char *token, const char *tan, AB_BANKING_TANSTATUS status)
int AB_Banking_GetAlwaysAskForCert (const AB_BANKING *ab)
void AB_Banking_SetAlwaysAskForCert (AB_BANKING *ab, int i)

Setters For Virtual Security Functions

void AB_Banking_SetGetPinFn (AB_BANKING *ab, AB_BANKING_GETPIN_FN f)
void AB_Banking_SetSetPinStatusFn (AB_BANKING *ab, AB_BANKING_SETPINSTATUS_FN f)
void AB_Banking_SetGetTanFn (AB_BANKING *ab, AB_BANKING_GETTAN_FN f)
void AB_Banking_SetSetTanStatusFn (AB_BANKING *ab, AB_BANKING_SETTANSTATUS_FN f)

Getting Bank/Account Information

Functions in this group retrieve information about credit institutes and allow checking of bank code/account id combinations. These functions load the appropriate checker plugins for selected countries.

AB_BANKINFOAB_Banking_GetBankInfo (AB_BANKING *ab, const char *country, const char *branchId, const char *bankId)
int AB_Banking_GetBankInfoByTemplate (AB_BANKING *ab, const char *country, AB_BANKINFO *tbi, AB_BANKINFO_LIST2 *bl)
AB_BANKINFO_CHECKRESULT AB_Banking_CheckAccount (AB_BANKING *ab, const char *country, const char *branchId, const char *bankId, const char *accountId)
int AB_Banking_CheckIban (const char *iban)

Getting Country Information

Functions in this group retrieve information about countries (name, code, numeric code).

const AB_COUNTRYAB_Banking_FindCountryByName (AB_BANKING *ab, const char *name)
const AB_COUNTRYAB_Banking_FindCountryByLocalName (AB_BANKING *ab, const char *name)
const AB_COUNTRYAB_Banking_FindCountryByCode (AB_BANKING *ab, const char *code)
const AB_COUNTRYAB_Banking_FindCountryByNumeric (AB_BANKING *ab, int numid)
AB_COUNTRY_CONSTLIST2 * AB_Banking_ListCountriesByName (AB_BANKING *ab, const char *name)
AB_COUNTRY_CONSTLIST2 * AB_Banking_ListCountriesByLocalName (AB_BANKING *ab, const char *name)

Request Functions

int AB_Banking_RequestBalance (AB_BANKING *ab, const char *bankCode, const char *accountNumber)
int AB_Banking_RequestTransactions (AB_BANKING *ab, const char *bankCode, const char *accountNumber, const GWEN_TIME *firstDate, const GWEN_TIME *lastDate)
int AB_Banking_RequestStandingOrders (AB_BANKING *ab, const char *bankCode, const char *accountNumber)
int AB_Banking_RequestDatedTransfers (AB_BANKING *ab, const char *bankCode, const char *accountNumber)
int AB_Banking_GatherResponses (AB_BANKING *ab, AB_IMEXPORTER_CONTEXT *ctx)

Mapping Application Accounts to Online Accounts

Functions in this group provide an optional service for account mapping. Most applications assign unique ids to their own accounts. This unique id can be mapped to an account of AqBanking.

void AB_Banking_SetAccountAlias (AB_BANKING *ab, AB_ACCOUNT *a, const char *alias)
AB_ACCOUNTAB_Banking_GetAccountByAlias (AB_BANKING *ab, const char *alias)

Defines

#define AB_PM_LIBNAME   "aqbanking"
#define AB_PM_SYSCONFDIR   "sysconfdir"
#define AB_PM_DATADIR   "datadir"
#define AB_BANKING_PROGRESS_NONE   0xffffffff
#define AB_BANKING_PROGRESS_ONE   0xfffffffe

Typedefs

typedef AB_BANKING AB_BANKING

Enumerations

enum  AB_BANKING_LOGLEVEL {
  AB_Banking_LogLevelPanic = 0, AB_Banking_LogLevelEmergency, AB_Banking_LogLevelError, AB_Banking_LogLevelWarn,
  AB_Banking_LogLevelNotice, AB_Banking_LogLevelInfo, AB_Banking_LogLevelDebug, AB_Banking_LogLevelVerbous
}


Detailed Description

The main interface of the aqbanking library.

Definition in file aqbanking/banking.h.


Define Documentation

#define AB_PM_DATADIR   "datadir"
 

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

#define AB_PM_LIBNAME   "aqbanking"
 

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

#define AB_PM_SYSCONFDIR   "sysconfdir"
 

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


Generated on Sat Jan 7 04:22:41 2006 for aqbanking by  doxygen 1.4.6