
1. Introduction
===============

This document explains what an application needs to perform to setup
and use AqBanking.


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

3. Call AB_Banking_Fini
   This allows AqBanking to write its configuration back.
   You should always call this function to avoid data inconsistencies.

4. 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. 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. Call AB_Banking_Init
    This makes AqBanking prepare the plugin framework.

 3. Call AB_Banking_OnlineInit
    This makes AqBanking actually read its configuration. Without this call
    online banking is not possible.

---------------------------------------------------------- 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. Add this job to a job list 

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

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

---------------------------------------------------------- X8

11. Call AB_Banking_OnlineFini
    This allows AqBanking to write its configuration back.
    You should always call this function to avoid data inconsistencies.

12. Call AB_Banking_Fini
    This releases all ressources assigned to AqBanking.
    
    Please note that before calling this function you MUST free all AqBanking
    objects you own.

13. 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 4 to 10 may be performed multiple times.
Most likely an application will perform steps 1-3 and 11-13 only upon
startup and then later loop between steps 4 and 10.