1. Introduction
===============
This document explains what an application needs to perform to setup
and use AqBanking.
If you are writing an application and want to use AqBanking's
features, there are two possibilities:
- Use the "Application Layer API" (maybe this should better be called
"ImExporter Layer API"), which requires the least coding effort on
the application side. In particular, this API means that the
application will not deal with the AB_JOB objects but only
AB_IMEXPORTER_CONTEXT objects.
- Or you can use the "Main Interface API" (also called "High level
API" sometimes), which offers the highest flexibility by its access
to AB_JOB objects.
This document describes the second approach, where the application
constructs AB_JOB objects and passed data from and to these objects.
2. Application Coding Overview
==============================
This section gives an overview of the necessary initialisation and
de-initialisation steps of AqBanking, and how the banking jobs fit
into this frame.
1. Create an instance of AB_BANKING (AB_Banking_new())
2. Set all (!) callbacks for virtual functions
The class AB_BANKING (file "banking.h") uses several callback
functions which should be set by the application which uses
AqBanking. These are callbacks which allow AqBanking or any of its
plugins to interact with the user. See the section "Virtual
Functions" in the Doxygen documentation of AB_BANKING.
Note: For some callbacks, if no function has been set, then the
program flow will terminate when these callbacks would have been
needed. This might lead to unexpected termination, so you should
make sure you set all callback functions in AB_BANKING.
3. Call AB_Banking_Init
This makes AqBanking actually read its configuration. Before this call
AqBanking can not work.
4. Do whatever you want (see section 4)
5. Call AB_Banking_Fini
This allows AqBanking to write its configuration back.
You should always call this function to avoid data inconsistencies.
6. Free the AqBanking object (AB_Banking_free())
This function releases all data currently owned by AqBanking.
You should always call this function to avoid memory leaks.
Please note that you still have to call the corresponding *_free()
functions of any AqBanking object you own. This MUST be done before
AB_Banking_free() is called.
3. First Time
=============
This section describes the program flow for the initial setup of the
AqBanking configuration. The general initialisation steps from section
2 are not repeated here but have to be performed beforehand.
When you start using AqBanking there probably is no account setup so
you will have to do it now:
1. Ask AqBanking for a list of available backends
(AB_Banking_GetProviderDescrs()); "provider" is simply another word
for "backend".
2. Present this list to the user to pick one of them (or pick a fixed
one, e.g. "aqhbci").
3. Activate the chosen backend(s).
This also imports a possibly available account list from the backends.
4. Ask AqBanking about the account list (if the backend already was setup
it might have returned an account list which in that case has been
imported to AqBanking)
5. Map the AqBanking-accounts to your application accounts. Either you
retrieve an account by AB_Banking_GetAccountByCodeAndNumber(), or
you set an alias for an account by AB_Banking_SetAccountAlias() and
can retrieve it later by AB_Banking_GetAccountByAlias().
Some backends - e.g. AqHBCI - allow transparent updates of account
information. This is automatically used by AqBanking whenever an account is
loaded from AqBanking's configuration file.
If the backend does not have an account list (e.g. because is has not been
setup yet) you can invoke the backend setup wizard
(AB_Banking_FindWizard()). You can get a list of available wizards for a
given backend via AB_Banking_GetWizardDescrs().
4. Performing Jobs
==================
This section describes the program flow for the normal operation of
online banking jobs with AqBanking. The general initialisation steps
from section 2 are repeated here for an easier overview.
To perform a job - such as getting the balance of an account, retrieving
transaction statements, transferring money etc - you need to take the
following steps (Example: Getting the balance of an account):
1. Create an instance of AB_BANKING (AB_Banking_new())
2. Set all (!) callbacks for virtual functions
The class AB_BANKING (file "banking.h") uses several callback
functions which should be set by the application which uses
AqBanking. These are callbacks which allow AqBanking or any of
its plugins to interact with the user. See the section "Virtual
Functions" in the Doxygen documentation of AB_BANKING.
Note: For some callbacks, if no function has been set, then the
program flow will terminate when these callbacks would have been
needed. This might lead to unexpected termination, so you should
make sure you set all callback functions in AB_BANKING.
3. Call AB_Banking_Init
This makes AqBanking actually read its configuration. Before this call
AqBanking can not work.
---------------------------------------------------------- X8
4. Create the job to get the balance by AB_JobGetBalance_new(), which
also means you have to find the correct AB_ACCOUNT beforehand.
5. Check whether this job is available with the account chosen:
AB_Job_CheckAvailability()
This function also does setup the parameters for the job (well, this
particular job has no parameters, but one parameter for JobGetTransactions
is the maximum number of days the bank server stores transaction
statements for).
6. Check the parameters (if any)
As described above this job has no parameters.
7. Set arguments for the job (if any)
Besides the account which has been given to the constructor this job
has no further arguments.
8. Enqueue this job with the execution queue
AB_Banking_EnqueueJob()
9. Optionally add all "pending" jobs:
Get them with
AB_Banking_GetPendingJobs()
and add any of them using
AB_Banking_EnqueueJob()
You might choose to only add those pending jobs which have been created
by your application.
Please note that you MUST NOT call
AB_Banking_DelPendingJob()
for jobs you enqueued, because when a pending job is enqueued it will be
MOVED from the pending queue to the execution queue.
10. Execute the queue
AB_Banking_ExecuteQueue()
This function sends all enqueued jobs to their backends which will then
do the necessary communication with the bank server etc.
11. Check for the status of each job.
AB_Job_GetStatus()
This function returns the status of the job.
Some jobs might have the status "pending". Those jobs have been processed
by the backend but did not yield a result quite yet. So you will have to
re-enqueue such a job later to make the backend check whether meanwhile
some results are available (see step 9)
If the job has been finished you may apply the information returned (in
this case the balance of an account).
12. Remove the job from the list of finished jobs.
AB_Banking_DelFinishedJob()
This is only needed if the job has been finished. If you don't delete the
job from the finished queue it will stay there forever (since only the
application which created the job may delete it).
Please note that this function does not free the job, so before going to
the next step you have to free the job now using AB_Job_free().
---------------------------------------------------------- X8
13. Call AB_Banking_Fini
This allows AqBanking to write its configuration back.
You should always call this function to avoid data inconsistencies.
Please note that before calling this function you MUST free all AqBanking
objects you own.
14. Release all AqBanking data (AB_Banking_free())
This function releases all data currently owned by AqBanking.
You should always call this function to avoid memory leaks.
Actually, steps 3 to 13 may be performed multiple times.
Most likely an application will perform steps 1-3 and 13-14 only upon
startup and then later loop between steps 4 and 12.
