

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.






