AB_BANKING Job-API
[AB_BANKING (Main Interface)]

This group contains the job API ("main interface") function group. More...

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)

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

This group contains the job API ("main interface") function group.

This is the preferred API for new programs. New features will first be implemented here.


Define Documentation

#define AB_BANKING_INPUT_FLAGS_ALLOW_DEFAULT   0x00000010
 

allow a default value to be used instead of an entered one. A graphical UI should add a "default" button to the dialog.

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

#define AB_BANKING_INPUT_FLAGS_CONFIRM   0x00000001
 

input must be confirmed (e.g. by asking for the same input twice)

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

#define AB_BANKING_INPUT_FLAGS_NUMERIC   0x00000004
 

numeric input is requested (e.g. for PINs)

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

#define AB_BANKING_INPUT_FLAGS_RETRY   0x00000008
 

if set then this is a retry (esp. when getting a PIN)

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

#define AB_BANKING_INPUT_FLAGS_SHOW   0x00000002
 

input may be shown (otherwise it should be hidden, e.g. for passwords)

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

#define AB_BANKING_MSG_FLAGS_CONFIRM_B1   (1<<3)
 

button 1 is the confirmation button

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

#define AB_BANKING_MSG_FLAGS_CONFIRM_B2   (2<<3)
 

button 2 is the confirmation button

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

#define AB_BANKING_MSG_FLAGS_CONFIRM_B3   (3<<3)
 

button 3 is the confirmation button

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

#define AB_BANKING_MSG_FLAGS_CONFIRM_BUTTON fl   )     ((fl & 0x3)>>3)
 

Determine which button is the confirmation button

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

#define AB_BANKING_MSG_FLAGS_SEVERITY_DANGEROUS   (0x1<<5)
 

Message is considered dangerous and thus should be attended to by a humanoid ;-)

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

#define AB_BANKING_MSG_FLAGS_SEVERITY_IS_DANGEROUS fl   ) 
 

Value:

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

#define AB_BANKING_MSG_FLAGS_SEVERITY_IS_NORMAL fl   ) 
 

Value:

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

#define AB_BANKING_MSG_FLAGS_SEVERITY_MASK   (0x7<<5)
 

Check for the severity of the message. This allows non-interactive backends to react on the message accordingly. The backend calling this function thus allows the frontend to detect when the message is important regarding data security. E.g. a message like "Shall I delete this file" should be considered dangerous (since this might result in a data loss). However, the messae "Just started" is not that dangerous ;-)

The following example allows to determine whether a message is dangerous:

 if ( ( flags & AB_BANKING_MSG_FLAGS_SEVERITY_MASK) ==
      AB_BANKING_MSG_FLAGS_SEVERITY_DANGEROUS) {
      fprintf(stderr, "This is dangerous.\n");
 }

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

#define AB_BANKING_MSG_FLAGS_SEVERITY_NORMAL   (0x0<<5)
 

Message does not affect security or induce any problem to the system

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

#define AB_BANKING_MSG_FLAGS_TYPE_ERROR   2
 

The message is a error message

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

#define AB_BANKING_MSG_FLAGS_TYPE_INFO   0
 

The message is a simple information.

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

#define AB_BANKING_MSG_FLAGS_TYPE_IS_ERROR   ((fl & AB_BANKING_MSG_FLAGS_TYPE_MASK)==AB_BANKING_MSG_FLAGS_TYPE_ERROR)
 

check whether the given flags represent an error message

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

#define AB_BANKING_MSG_FLAGS_TYPE_IS_INFO fl   )     ((fl & AB_BANKING_MSG_FLAGS_TYPE_MASK)==AB_BANKING_MSG_FLAGS_TYPE_INFO)
 

check whether the given flags represent an info message

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

#define AB_BANKING_MSG_FLAGS_TYPE_IS_WARN fl   )     ((fl & AB_BANKING_MSG_FLAGS_TYPE_MASK)==AB_BANKING_MSG_FLAGS_TYPE_WARN)
 

check whether the given flags represent a warning message

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

#define AB_BANKING_MSG_FLAGS_TYPE_MASK   0x07
 

Defines the mask to catch the message type. E.g. a check whether a message is a warning could be performed by:

 if ( ( flags & AB_BANKING_MSG_FLAGS_TYPE_MASK) ==
      AB_BANKING_MSG_FLAGS_TYPE_WARN) {
      fprintf(stderr, "This is a warning.\n");
 }

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

#define AB_BANKING_MSG_FLAGS_TYPE_WARN   1
 

The message is a warning

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

#define AB_BANKING_SHOWBOX_FLAGS_BEEP   0x00000001
 

Make the frontend beep. This should rarely be used, and only in situations where it is very important to get the users attention (e.g. when asking for a PIN on a card reader).

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


Typedef Documentation

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)
 

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

typedef int(* AB_BANKING_GETTAN_FN)(AB_BANKING *ab, const char *token, const char *title, const char *text, char *buffer, int minLen, int maxLen)
 

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

typedef void(* AB_BANKING_HIDEBOX_FN)(AB_BANKING *ab, GWEN_TYPE_UINT32 id)
 

Please see AB_Banking_HideBox for details.

One way of passing arbitrary additional data to this callback is by means of the AB_Banking_GetUserData function.

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

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)
 

Please see AB_Banking_InputBox for details.

One way of passing arbitrary additional data to this callback is by means of the AB_Banking_GetUserData function.

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

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)
 

Please see AB_Banking_MessageBox for details.

One way of passing arbitrary additional data to this callback is by means of the AB_Banking_GetUserData function. However, the recommended way is to use Gwenhywfars' heritage functions (see GWEN_INHERIT_SETDATA).

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

typedef int(* AB_BANKING_PRINT_FN)(AB_BANKING *ab, const char *docTitle, const char *docType, const char *descr, const char *text)
 

This function is used to make the application print something. The same restrictions noted above apply to the text parameter (utf-8, maybe containing HTML). Please see AB_Banking_Print for details.

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

typedef int(* AB_BANKING_PROGRESS_ADVANCE_FN)(AB_BANKING *ab, GWEN_TYPE_UINT32 id, GWEN_TYPE_UINT32 progress)
 

Please see AB_Banking_ProgressAdvance for details.

One way of passing arbitrary additional data to this callback is by means of the AB_Banking_GetUserData function.

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

typedef int(* AB_BANKING_PROGRESS_END_FN)(AB_BANKING *ab, GWEN_TYPE_UINT32 id)
 

Please see AB_Banking_ProgressEnd for details.

One way of passing arbitrary additional data to this callback is by means of the AB_Banking_GetUserData function.

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

typedef int(* AB_BANKING_PROGRESS_LOG_FN)(AB_BANKING *ab, GWEN_TYPE_UINT32 id, AB_BANKING_LOGLEVEL level, const char *text)
 

Please see AB_Banking_ProgressLog for details.

One way of passing arbitrary additional data to this callback is by means of the AB_Banking_GetUserData function.

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

typedef GWEN_TYPE_UINT32(* AB_BANKING_PROGRESS_START_FN)(AB_BANKING *ab, const char *title, const char *text, GWEN_TYPE_UINT32 total)
 

Please see AB_Banking_ProgressStart for details.

One way of passing arbitrary additional data to this callback is by means of the AB_Banking_GetUserData function.

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

typedef int(* AB_BANKING_SETPINSTATUS_FN)(AB_BANKING *ab, const char *token, const char *pin, AB_BANKING_PINSTATUS status)
 

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

typedef int(* AB_BANKING_SETTANSTATUS_FN)(AB_BANKING *ab, const char *token, const char *tan, AB_BANKING_TANSTATUS status)
 

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

typedef GWEN_TYPE_UINT32(* AB_BANKING_SHOWBOX_FN)(AB_BANKING *ab, GWEN_TYPE_UINT32 flags, const char *title, const char *text)
 

Please see AB_Banking_ShowBox for details.

One way of passing arbitrary additional data to this callback is by means of the AB_Banking_GetUserData function.

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


Enumeration Type Documentation

enum AB_BANKING_LOGLEVEL
 

This is used with AB_Banking_ProgressLog to tell the function about the severity of the message. The implementation of this function may then decide on this argument about whether to show or repress this message.

Enumerator:
AB_Banking_LogLevelPanic  extremely important message (just before abort())
AB_Banking_LogLevelEmergency  very important message
AB_Banking_LogLevelError  error message
AB_Banking_LogLevelWarn  warning
AB_Banking_LogLevelNotice  notice (important information)
AB_Banking_LogLevelInfo  information (not that important)
AB_Banking_LogLevelDebug  simple debug message
AB_Banking_LogLevelVerbous  verbous debug message

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

enum AB_BANKING_PINSTATUS
 

Enumerator:
AB_Banking_PinStatusBad 
AB_Banking_PinStatusUnknown 
AB_Banking_PinStatusOk 

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

enum AB_BANKING_TANSTATUS
 

Enumerator:
AB_Banking_TanStatusBad 
AB_Banking_TanStatusUnknown 
AB_Banking_TanStatusUsed 
AB_Banking_TanStatusUnused 

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


Function Documentation

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.

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

AB_BANKINFO_CHECKRESULT AB_Banking_CheckAccount AB_BANKING ab,
const char *  country,
const char *  branchId,
const char *  bankId,
const char *  accountId
 

This function checks whether the given combination represents a valid account. It loads the appropriate bank checker module and lets it check the information.

Parameters:
ab AqBanking main object
country ISO country code ("de" for Germany, "at" for Austria etc)
branchId optional branch id (not needed for "de")
bankId bank id ("Bankleitzahl" for "de")
accountId account id

int AB_Banking_CheckIban const char *  iban  ) 
 

Checks whether a given international bank account number (IBAN) is valid or not.

Returns:
0 if valid, 1 if not and -1 on error
Parameters:
iban IBAN (e.g. "DE88 2008 0000 09703 7570 0")

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.

Returns:
0 if ok, error code otherwise (see (Error Codes))
Parameters:
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_DeferJob AB_BANKING ab,
AB_JOB j
 

Removes a job from the queue but keeps it for later re-enqueuing. This function does not free the given job, the caller still is the owner. Deferred jobs are preserved across shutdowns. You can later re-enqueue such a job using AB_Banking_EnqueueJob.

Returns:
0 if ok, error code otherwise (see (Error Codes))
Parameters:
ab pointer to the AB_BANKING object
j job to be dequeued

int AB_Banking_DelArchivedJob AB_BANKING ab,
AB_JOB j
 

Removes a finished job from its folder. You can use either a job returned via AB_Banking_GetFinishedJobs or a job you previously added to the execution queue after the queue has been executed.

int AB_Banking_DelDeferredJob AB_BANKING ab,
AB_JOB j
 

Removes a deferred job from its folder. You can use either a job returned via AB_Banking_GetFinishedJobs or a job you previously added to the execution queue after the queue has been executed.

int AB_Banking_DelFinishedJob AB_BANKING ab,
AB_JOB j
 

Removes a finished job from its folder. You can use either a job returned via AB_Banking_GetFinishedJobs or a job you previously added to the execution queue after the queue has been executed.

int AB_Banking_DelPendingJob AB_BANKING ab,
AB_JOB j
 

Removes a pending job from its folder. This function does not free the job. The job MUST be one of those returned via AB_Banking_GetPendingJobs.

int AB_Banking_DequeueJob AB_BANKING ab,
AB_JOB j
 

Removes a job from the queue. This function does not free the given job, the caller still is the owner. Dequeued jobs however are NOT preserved across shutdowns.

Returns:
0 if ok, error code otherwise (see (Error Codes))
Parameters:
ab pointer to the AB_BANKING object
j job to be dequeued

int AB_Banking_EnqueueJob AB_BANKING ab,
AB_JOB j
 

Enqueues a job. This function does not take over the ownership of the job. However, this function makes sure that the job will not be deleted as long as it is in the queue (by calling AB_Job_Attach). So it is safe for you to call AB_Job_free on an enqueued job directly after enqueuing it (but it doesn't make much sense since you would not be able to check for a result).

Returns:
0 if ok, error code otherwise (see (Error Codes))
Parameters:
ab pointer to the AB_BANKING object
j job to be enqueued

int AB_Banking_EnqueuePendingJobs AB_BANKING ab,
int  mineOnly
 

This function enqueues all pending jobs so that they will be send the next time AB_Banking_ExecuteQueue is called. You should call this function directly before calling AB_Banking_ExecuteQueue to let the backend update the status of the pending jobs. There is special treatment for "pending" marked jobs in backends: The backends check for the final result of them instead of executing them again when added to the queue. This is used by jobs which do not return an immediate result (such as transfer jobs which are first accepted by the bank and actually checked later. In such a case the bank sends a temporary result code which might be replaced by a final result later).

Parameters:
ab pointer to the AB_BANKING object
mineOnly if 0 then all pending jobs for all applications are enqueued, otherwise only the pending jobs for the currently running application are enqueued

int AB_Banking_ExecuteJobList AB_BANKING ab,
AB_JOB_LIST2 jl2
 

This function sends all enqueued jobs from the given list to their respective backend.

The jobs in the list MUST BE enqueued jobs! It is not allowed to use any arbitrary jobs.

The purpose of this function is to let the application directly influence the list of jobs to be executed. For instance an application might decide to only execute it's own jobs, or only jobs for a special account etc.

The way to use this function is to call AB_Banking_GetEnqueuedJobs, select the jobs out of the list returned (or the whole list) and use this list.

This function calls AB_Job_free on every one of the jobs in the given list (because there is a central list of enqueued jobs). So if you are still interested in the jobs in the list after this function has been called you should call AB_Job_Attach on those jobs you want to keep.

Also, upon return all jobs in this list are removed from the todo queue. For the rest see info for function AB_Banking_ExecuteQueue.

Returns:
0 if ok, error code otherwise (see (Error Codes))
Parameters:
ab pointer to the AB_BANKING object
jl2 list of enqueued jobs to execute

int AB_Banking_ExecuteQueue AB_BANKING ab  ) 
 

This function sends all jobs in the queue to their corresponding backends and allows those backends to process it.

The queue is always empty upon return.

Jobs which have been finished (even errornous jobs) are move from the queue to the list of finished jobs. Those jobs are preserved across shutdowns.

This means that if you are handling the response for a just executed job directly after queue execution you should remove the finished job by calling AB_Banking_DelFinishedJob on it after handling its results.

If a job is marked as pending after execution it will be moved to the list of pending jobs, so AB_Banking_DelFinishedJob will not work on this job. Those jobs are also preserved across shutdowns.

You should call AB_Banking_Save() before calling this function here to make sure that a crash in a backend will not destroy too much data.

Returns:
0 if ok, error code otherwise (see (Error Codes))
Parameters:
ab pointer to the AB_BANKING object

const AB_COUNTRY* AB_Banking_FindCountryByCode AB_BANKING ab,
const char *  code
 

Searches for information about a country by its ISO country code (e.g. "DE"=Germany, "AT"=Austria etc). The code may contain jokers ("?") and wildcards ("*") and is case insensitive.

const AB_COUNTRY* AB_Banking_FindCountryByLocalName AB_BANKING ab,
const char *  name
 

Searches for information about a country by its local name (in the currently selected language). The name may contain jokers ("?") and wildcards ("*") and is case insensitive.

const AB_COUNTRY* AB_Banking_FindCountryByName AB_BANKING ab,
const char *  name
 

Searches for information about a country by its international name (in English). The name may contain jokers ("?") and wildcards ("*") and is case insensitive.

const AB_COUNTRY* AB_Banking_FindCountryByNumeric AB_BANKING ab,
int  numid
 

Searches for information about a country by its ISO numeric code (e.g. 280=Germany etc).

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

AB_ACCOUNT* AB_Banking_GetAccount const AB_BANKING ab,
GWEN_TYPE_UINT32  uniqueId
 

This function does an account lookup based on the given unique id. This id is assigned by AqBanking when an account is created.

AqBanking remains the owner of the object returned (if any), so you must not free it.

Please also note that the object returned is only valid until AB_Banking_Fini() has been called (or until the corresponding backend for this particular account has been deactivated).

Returns:
The account, or NULL if it is not found.
Parameters:
ab pointer to the AB_BANKING object
uniqueId unique id of the account assigned by AqBanking

AB_ACCOUNT* AB_Banking_GetAccountByCodeAndNumber const AB_BANKING ab,
const char *  bankCode,
const char *  accountId
 

This function does an account lookup based on the given bank code and account number. No wildards or jokers allowed.

AqBanking remains the owner of the object returned (if any), so you must not free it.

Please also note that the object returned is only valid until AB_Banking_Fini() has been called (or until the corresponding backend for this particular account has been deactivated).

Returns:
The account, or NULL if it is not found.
Parameters:
ab pointer to the AB_BANKING object
bankCode bank code (use 0 if your country does not use bank codes)
accountId account number

AB_ACCOUNT_LIST2* AB_Banking_GetAccounts const AB_BANKING ab  ) 
 

Returns a list of currently known accounts, or NULL if there are no accounts. The returned list is owned by the caller, so he is responsible for freeing it (using AB_Account_List2_free).

Please note that even while the list is owned by the caller the accounts in that list are not! Sou you may not free any of those accounts in the list (e.g. by calling AB_Account_List2_freeAll).

Returns:
The list of accounts, or NULL if there are none.
Parameters:
ab pointer to the AB_BANKING object

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.

Parameters:
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.

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

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

AB_JOB_LIST2* AB_Banking_GetArchivedJobs AB_BANKING ab  ) 
 

Loads all archived jobs from their folder. The caller is responsible for freeing the jobs returned (as opposed to AB_Banking_GetEnqueuedJobs).

Archived jobs are jobs which have been deleted via any AB_Banking_Del(-XYZ-)Job function except AB_Banking_DelArchivedJob

Please note that since this function loads all jobs from their folder the returned list might contain another representation of jobs you once created and enqueued into the execution queue.

AB_BANKINFO* AB_Banking_GetBankInfo AB_BANKING ab,
const char *  country,
const char *  branchId,
const char *  bankId
 

This functions retrieves information about a given bank. It loads the appropriate bank checker module and asks it for information about the given bank. The caller is responsible for freeing the object returned (if any) by calling AB_BankingInfo_free.

Parameters:
ab AqBanking main object
country ISO country code ("de" for Germany, "at" for Austria etc)
branchId optional branch id (not needed for "de")
bankId bank id ("Bankleitzahl" for "de")

int AB_Banking_GetBankInfoByTemplate AB_BANKING ab,
const char *  country,
AB_BANKINFO tbi,
AB_BANKINFO_LIST2 bl
 

This function retrieves information about banks. It loads the appropriate bank checker module and asks it for a list of AB_BANKINFO objects which match the given template. Empty fields in this template always match. Service entries (AB_BANKINFO_SERVICE) are not compared. Matching entries are added to the given list. The caller is responsible for freeing the objects returned (if any) by calling AB_BankingInfo_free (or by calling AB_BankingInfo_List_freeAll).

Parameters:
ab AqBanking main object
country ISO country code ("de" for Germany, "at" for Austria etc)
tbi template to compare against
bl list to which matching banks are added

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

AB_JOB_LIST2* AB_Banking_GetDeferredJobs AB_BANKING ab  ) 
 

Loads all deferred jobs from their folder. The caller is responsible for freeing the jobs returned (as opposed to AB_Banking_GetEnqueuedJobs).

Please note that since this function loads all jobs from their folder the returned list might contain another representation of jobs you once created and enqueued into the execution queue.

AB_JOB_LIST2* AB_Banking_GetEnqueuedJobs const AB_BANKING ab  ) 
 

Returns a new list which contains the currently enqueued jobs. If the queue is empty NULL is returned.

Please note that AqBanking still remains the owner of those jobs in the list returned (if any). So you MUST NOT call AB_Job_List2_FreeAll on this list. However, you MUST call AB_Job_List2_free when you no longer need the list to avoid memory leaks.

This list is only valid until one of the following functions is called:

After one of these functions has been called you are only allowed to call AB_Job_List2_free on that list, the elements of this list are no longer valid.
Returns:
0 if ok, error code otherwise (see (Error Codes))
Parameters:
ab pointer to the AB_BANKING object

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

AB_JOB_LIST2* AB_Banking_GetFinishedJobs AB_BANKING ab  ) 
 

Loads all finished jobs from their folder. The caller is responsible for freeing the jobs returned (as opposed to AB_Banking_GetEnqueuedJobs).

Please note that since this function loads all jobs from their folder the returned list might contain another representation of jobs you once created and enqueued into the execution queue.

AB_IMEXPORTER* AB_Banking_GetImExporter AB_BANKING ab,
const char *  name
 

Loads an importer/exporter backend with the given name. You can use AB_Banking_GetImExporterDescrs to retrieve a list of available backends. AqBanking remains the owner of the object returned (if any), so you must not free it.

GWEN_PLUGIN_DESCRIPTION_LIST2* AB_Banking_GetImExporterDescrs AB_BANKING ab  ) 
 

Returns a list2 of available importers and exporters. 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

GWEN_DB_NODE* AB_Banking_GetImExporterProfiles AB_BANKING ab,
const char *  name
 

Loads all available profiles for the given importer/exporter. This includes global profiles as well as local ones.

Local profiles overwrite global ones, allowing the user to customize the profiles.

The GWEN_DB returned contains one group for every loaded profile. Every group has the name of the profile it contains. Every group contains at least a variable called name which contains the name of the profile, too. The remaining content of each group is completely defined by the importer/exporter.

You can use GWEN_DB_GetFirstGroup and GWEN_DB_GetNextGroup to browse the profiles.

The caller becomes the new owner of the object returned (if any). This makes him/her responsible for freeing it via GWEN_DB_Group_free.

You can use any of the subgroups below the returned one as argument to AB_ImExporter_Import.

Parameters:
ab pointer to the AB_BANKING object
name name of the importer whose profiles are to be read

AB_JOB_LIST2* AB_Banking_GetPendingJobs AB_BANKING ab  ) 
 

Loads all pending jobs from their folder. The caller is responsible for freeing the jobs returned (as opposed to AB_Banking_GetEnqueuedJobs).

Please note that since this function loads all jobs from their folder the returned list might contain another representation of jobs you once created and enqueued into the execution queue.

So you should only use jobs returned by this function for other functions in this particular function group.

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
 

This function retrieves the PIN for the given token. If the application hasn't set any other GetPin function, this function will call AB_Banking_InputBox for the user input.

Parameters:
ab Banking interface
flags Flags, see AB_Banking_InputBox and AB_BANKING_INPUT_FLAGS_CONFIRM
token A unique identification of what PIN is required. To be used for automated PIN lookup.
title Title of the input box (in UTF-8)
text Text of the box: UTF-8, with both a normal text and a HTML variant of the text in the same string. See text restrictions note above.
buffer Buffer to store the response in. Must have at least room for maxLen bytes
minLen Minimal length of input that is required before the returned answer is accepted (if 0 then there is no low limit)
maxLen Size of the buffer including the trailing NULL character. This means that if you want to ask the user for a PIN of at most 4 characters you need to supply a buffer of at least 5 bytes and provide a 5 as maxLen.

int AB_Banking_GetPinCacheEnabled const AB_BANKING ab  ) 
 

Returns nonzero (TRUE) if PIN caching across jobs until the end of this session is enabled. Returns zero (FALSE) if caching across jobs is disabled.

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.

int AB_Banking_GetTan AB_BANKING ab,
const char *  token,
const char *  title,
const char *  text,
char *  buffer,
int  minLen,
int  maxLen
 

This function retrieves a TAN for the given token. If the application hasn't set any other GetTan function, this function will call AB_Banking_InputBox for the user input.

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/.banking".

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_GetWizardDescrs AB_BANKING ab,
const char *  pn
 

Returns a list2 of wizard 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).

AQBANKING_DEPRECATED int AB_Banking_GetWizardPath AB_BANKING ab,
const char *  backend,
GWEN_BUFFER *  pbuf
 

Deprecated:

void AB_Banking_HideBox AB_BANKING ab,
GWEN_TYPE_UINT32  id
 

Hides a message box previously shown by a call to AB_Banking_ShowBox.

This function MUST return immediately (non-blocking).

Parameters:
ab banking interface
id id returned by AB_Banking_ShowBox. If 0 then the last message shown is referred to.

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

int AB_Banking_InputBox AB_BANKING ab,
GWEN_TYPE_UINT32  flags,
const char *  title,
const char *  text,
char *  buffer,
int  minLen,
int  maxLen
 

Ask the user for input.

This function is blocking.

Parameters:
ab banking interface
flags flags, see AB_BANKING_INPUT_FLAGS_CONFIRM ff.
title title of the input box
text Text of the box: UTF-8, with both a normal text and a HTML variant of the text in the same string. See text restrictions note above.
buffer buffer to store the response in. Must have at least room for maxLen bytes
minLen minimal length of input (if 0 then there is no low limit)
maxLen size of the buffer including the trailing NULL character. This means that if you want to ask the user for a PIN of at most 4 characters you need to supply a buffer of at least 5 bytes and provide a 5 as maxLen.
Returns:
Zero on success, nonzero when the user requested abort or there was any error. The special value AB_ERROR_DEFAULT_VALUE should be returned if the flag AB_BANKING_INPUT_FLAGS_ALLOW_DEFAULT was given and the user has chosen to use the default value (e.g. pressed the "default" button in a GUI).

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 either suspended or inactive.

AB_COUNTRY_CONSTLIST2* AB_Banking_ListCountriesByLocalName AB_BANKING ab,
const char *  name
 

Returns a list of informations about countries whose local name (in the currently selected language) matches the given argument. The list returned must be freed using AB_Country_ConstList2_free() by the caller. The elements of that list are all const. The name may contain jokers ("?") and wildcards ("*") and is case insensitive.

AB_COUNTRY_CONSTLIST2* AB_Banking_ListCountriesByName AB_BANKING ab,
const char *  name
 

Returns a list of informations about countries whose international name (in English) matches the given argument. The list returned must be freed using AB_Country_ConstList2_free() by the caller. The elements of that list are all const. The name may contain jokers ("?") and wildcards ("*") and is case insensitive.

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
 

Show a message box with optional buttons. The message box may either contain 1, 2 or three buttons. If only one button is wanted then b1 should hold a pointer to the button text (b2 and b3 must be NULL) In two-button mode b1 and b2 must be valid (b3 must be NULL) In three-button-mode b1, b2 and b3 must be valid pointers. The return value tells which button the user pressed:

  • 1: button 1
  • 2: button 2
  • 3: button 3
If the frontend can not determine which button has been pressed (e.g. if no button was pressed but the user rather aborted the dialog by simply closing the box) it should return 0.

This function is blocking.

Returns:
the number of the button pressed (1=b1, 2=b2, 3=b3), any other value should be considered an error, including 0)
Parameters:
ab banking interface
flags flags, see AB_BANKING_MSG_FLAGS_TYPE_MASK ff.
title title of the message box
text Text of the box: UTF-8, with both a normal text and a HTML variant of the text in the same string. See text restrictions note above.
b1 text for the first button (required), should be something like "Ok" (see text restrictions note above)
b2 text for the optional second button
b3 text for the optional third button

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.

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/.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_Print AB_BANKING ab,
const char *  docTitle,
const char *  docType,
const char *  descr,
const char *  text
 

This function makes the application print something.

Parameters:
ab banking interface
docTitle title of the document. This might be presented to the user
docType an unique identifier of the document to be printed. This can be used by the application to separate printer settings for different document types. The name itself has no meaning and can be choosen freely by the caller. However, backends should append their name and a colon to keep this argument unique. This argument should not be translated.
descr an optional description about what the document contains. This might be shown to the user (see text restriction notes above).
text text to be printed (see text restriction notes above).

int AB_Banking_ProgressAdvance AB_BANKING ab,
GWEN_TYPE_UINT32  id,
GWEN_TYPE_UINT32  progress
 

Advances the progress bar an application might present to the user and checks whether the user wants to abort the operation currently in progress.

On graphical user interfaces this function should also check for user interaction and/or update the GUI (e.g. by calling qApp->processEvents() when using QT/KDE).

This function MUST return immediately (non-blocking).

Returns:
0 if ok, !=0 if the current operation is to be aborted
Parameters:
ab banking interface
id id assigned by AB_Banking_ProgressStart (if 0 then the last started progress dialog is referred to)
progress new value for progress. A special value is AB_BANKING_PROGRESS_NONE which means that the progress is unchanged. This might be used as a keepalive call to a GUI.

int AB_Banking_ProgressEnd AB_BANKING ab,
GWEN_TYPE_UINT32  id
 

Flags the end of the current operation. In graphical user interfaces this call should allow the user to close the progress dialog window.

On graphical user interfaces a call to this function should disable the abort button. It would be best not to close the dialog on receiption of this call but to simply enable a dialog closing (otherwise the user will not be able to see the log messages).

This function MUST return immediately (non-blocking).

Parameters:
ab banking interface
id id assigned by AB_Banking_ProgressStart (if 0 then the last started progress dialog is referred to)

int AB_Banking_ProgressLog AB_BANKING ab,
GWEN_TYPE_UINT32  id,
AB_BANKING_LOGLEVEL  level,
const char *  text
 

Adds a log message to the referred process dialog.

This function MUST return immediately (non-blocking).

Parameters:
ab banking interface
id id assigned by AB_Banking_ProgressStart (if 0 then the last started progress dialog is referred to)
level log level (see AB_Banking_LogLevelPanic ff.)
text Text of the box: UTF-8, with both a normal text and a HTML variant of the text in the same string. See text restrictions note above.

GWEN_TYPE_UINT32 AB_Banking_ProgressStart AB_BANKING ab,
const char *  title,
const char *  text,
GWEN_TYPE_UINT32  total
 

This function is called when a long term operation is started. Theoretically nesting is allowed, however, you should refrain from opening multiple progress dialogs to avoid confusion of the user.

This function must return immediately (i.e. it MUST NOT wait for user interaction).

On graphical user interfaces such a dialog should contain a widget for the text presented here, a progress bar, a text widget to collect the log messages received via AB_Banking_ProgressLog and a button to allow the user to abort the current operation monitored by this dialog window.

Between a call to this function and one to AB_Banking_ProgressEnd the user should not be allowed to close the dialog window.

This function MUST return immediately (non-blocking).

Returns:
id to be used with the other AB_Banking_Progress functions.
Parameters:
ab banking interface
title title of the dialog
text Text of the box: UTF-8, with both a normal text and a HTML variant of the text in the same string. See text restrictions note above.
total total number of steps of the operation started (i.e. value which represents 100%)

int AB_Banking_ResumeProvider AB_BANKING ab,
const char *  backend
 

This function reverts AB_Banking_SuspendProvider.

You should call this function directly after running a wizard on that backend to reenable it.

int AB_Banking_Save AB_BANKING ab  ) 
 

Saves all data. You may call this function periodically (especially after doing setup stuff).

Returns:
0 if ok, error code otherwise (see (Error Codes))
Parameters:
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_SetGetPinFn AB_BANKING ab,
AB_BANKING_GETPIN_FN  f
 

void AB_Banking_SetGetTanFn AB_BANKING ab,
AB_BANKING_GETTAN_FN  f
 

void AB_Banking_SetHideBoxFn AB_BANKING ab,
AB_BANKING_HIDEBOX_FN  f
 

void AB_Banking_SetInputBoxFn AB_BANKING ab,
AB_BANKING_INPUTBOX_FN  f
 

void AB_Banking_SetMessageBoxFn AB_BANKING ab,
AB_BANKING_MESSAGEBOX_FN  f
 

void AB_Banking_SetPinCacheEnabled AB_BANKING ab,
int  enabled
 

Enable or disable the internal caching of PINs across jobs during one full session. If the parameter is nonzero (TRUE), then every entered PIN will be cached throughout the rest of this session and is not asked for again. If the parameter is zero (FALSE), then PINs will only be cached during one queue execution, but not across several queue executions or several jobs. In other words, if this is FALSE, then after each AB_Banking_ExecuteQueue() the internal PIN cache will be cleared.

Note: There has to be *some* Pin caching during the execution of one job, because the medium is accessed several time. It would therefore be very inconvenient for the user having to enter the PIN several times during one job. Therefore we decided to implement an internal PIN cache.

Parameters:
ab The banking object
enabled If nonzero (TRUE), then caching across jobs is enabled. If zero (FALSE), caching across jobs is disabled.

int AB_Banking_SetPinStatus AB_BANKING ab,
const char *  token,
const char *  pin,
AB_BANKING_PINSTATUS  status
 

Sets a status for the given token and its given pin. This way, aqbanking will keep track of whether an entered PIN might have been wrong so it isn't used again.

void AB_Banking_SetPrintFn AB_BANKING ab,
AB_BANKING_PRINT_FN  f
 

void AB_Banking_SetProgressAdvanceFn AB_BANKING ab,
AB_BANKING_PROGRESS_ADVANCE_FN  f
 

void AB_Banking_SetProgressEndFn AB_BANKING ab,
AB_BANKING_PROGRESS_END_FN  f
 

void AB_Banking_SetProgressLogFn AB_BANKING ab,
AB_BANKING_PROGRESS_LOG_FN  f
 

void AB_Banking_SetProgressStartFn AB_BANKING ab,
AB_BANKING_PROGRESS_START_FN  f
 

void AB_Banking_SetSetPinStatusFn AB_BANKING ab,
AB_BANKING_SETPINSTATUS_FN  f
 

void AB_Banking_SetSetTanStatusFn AB_BANKING ab,
AB_BANKING_SETTANSTATUS_FN  f
 

void AB_Banking_SetShowBoxFn AB_BANKING ab,
AB_BANKING_SHOWBOX_FN  f
 

int AB_Banking_SetTanStatus AB_BANKING ab,
const char *  token,
const char *  tan,
AB_BANKING_TANSTATUS  status
 

Sets a status for the given token and its given TAN. This way, applications can keep track of whether an entered TAN might have been used.

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

void AB_Banking_SetUserDataDir AB_BANKING ab,
const char *  s
 

Set the user data dir. You should only use this on very special occasions. Clearly: You should normally not use this function, the default which AqBanking uses for the user data folder is quite suitable.

GWEN_TYPE_UINT32 AB_Banking_ShowBox AB_BANKING ab,
GWEN_TYPE_UINT32  flags,
const char *  title,
const char *  text
 

Shows a box with the given text. This function should return immediately, it should especially NOT wait for user input. This is used to show very important notices the user should see but which don't need user interaction. The message box will be removed later via AB_Banking_HideBox. It is ok to allow the user to prematurely close the box.

It is required for every call to this function to be followed later by a corresponding call to AB_Banking_HideBox.

This function MUST return immediately (non-blocking).

Returns:
returns an id to be presented to AB_Banking_HideBox.
Parameters:
ab banking interface
flags flags, see AB_BANKING_SHOWBOX_FLAGS_BEEP ff
title title of the box
text Text of the box: UTF-8, with both a normal text and a HTML variant of the text in the same string. See text restrictions note above.

int AB_Banking_SuspendProvider AB_BANKING ab,
const char *  backend
 

This function temporarily disables a backend. This status is not preserved across shutdown.

You should call this function directly before running a wizard on that backend, otherwise changes in the settings made by the wizard will most likely be silently overwritten.


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