---

HBCI_API functions

These are the functions for the C-accessible type of the central OpenHBCI class HBCI::API. More...

Object Constructor
HBCI_API *	HBCI_API_new (int readonly, int retrievalOnly)
void	HBCI_API_delete (HBCI_API *h)
HBCI_Hbci *	HBCI_API_Hbci (HBCI_API *h)
File operations
HBCI_Error *	HBCI_API_loadEnvironment (HBCI_API *h, const char *filename)
HBCI_Error *	HBCI_API_saveEnvironment (const HBCI_API *h, const char *filename)
Object Retrieval
const list_HBCI_Bank *	HBCI_API_bankList (const HBCI_API *h)
HBCI_Bank *	HBCI_API_findBank (const HBCI_API *h, int country, const char *bankCode)
HBCI_Medium *	HBCI_API_findMedium (const HBCI_API *h, const char *name)
Convenience Object Retrieval
int	HBCI_API_totalAccounts (const HBCI_API *h)
int	HBCI_API_totalUsers (const HBCI_API *h)
Manage Objects
HBCI_Error *	HBCI_API_addBank (HBCI_API *h, HBCI_Bank *b, int autoDelete)
OutboxJob Management
HBCI_Error *	HBCI_API_addJob (HBCI_API *h, HBCI_OutboxJob *j)
HBCI_Error *	HBCI_API_executeQueue (HBCI_API *h, int changesAllowed)
void	HBCI_API_clearQueueByResult (HBCI_API *h, OutboxJob_Result result)
void	HBCI_API_clearQueueByStatus (HBCI_API *h, OutboxJob_Status status)
User Interaction
void	HBCI_API_setMonitor (HBCI_API *h, HBCI_ProgressMonitor *m, int autoDelete)
Factory Methods
HBCI_Bank *	HBCI_API_bankFactory (const HBCI_API *h, int country, const char *bankCode, const char *server)
HBCI_Medium *	HBCI_API_createNewMedium (HBCI_API *h, const char *mtype, int readonly, int country, const char *bankId, const char *userid, const char *name, HBCI_Error **err)
MediumType	HBCI_API_mediumType (HBCI_API *h, const char *mtype)
HBCI_MediumPluginList *	HBCI_API_enumerateMediumPlugins (HBCI_API *h)
Static Factory Methods
HBCI_User *	HBCI_API_userFactory (HBCI_Bank *b, HBCI_Medium *m, int mediumAutoDelete, const char *userid)
HBCI_Customer *	HBCI_API_customerFactory (HBCI_User *u, const char *id, const char *custName)
HBCI_Account *	HBCI_API_accountFactory (HBCI_Bank *b, const char *accountId, const char *accountSubId)
Typedefs
typedef HBCI::API	HBCI_API
	This is the C-accessible type for the central OpenHBCI class HBCI::API.

---

Detailed Description

These are the functions for the C-accessible type of the central OpenHBCI class HBCI::API.

For the "real" documentation of what you can do with objects of this class, always remember to look up the member method documentation (especially if the C function is not [yet] documented). E.g., for HBCI_API_loadEnvironment, look up the documentation of HBCI::API::loadEnvironment.

---

Typedef Documentation

typedef struct HBCI::API HBCI_API

This is the C-accessible type for the central OpenHBCI class HBCI::API. For the "real" documentation of what you can do with objects of this class, always remember to look up the member method documentation (especially if the C function is not [yet] documented). E.g., for HBCI_API_loadEnvironment(), look up the documentation of HBCI::API::loadEnvironment. Just like in C++, once you got an existing OpenHBCI configuration file and setup, you only need a few steps to use it in C: HBCI_API_loadEnvironment(): to load all known users, accounts, and banks from the configuration file create jobs (e.g. HBCI_OutboxJobGetBalance) add the jobs to the outbox (HBCI_API_addJob()) HBCI_API_executeQueue(): to perform all those jobs HBCI_API_saveEnvironment(): to finally save all data back to the configuration file

---

Function Documentation

HBCI_Account* HBCI_API_accountFactory (  HBCI_Bank *    b, const char *    accountId, const char *    accountSubId )

Creates an account object. This will NOT be automatically added to internally stored lists. Author: Martin Preuss<martin@libchipcard.de> Parameters: b  The bank that this account belongs to. accountId  The account number (id) that identifies this account. May be NULL. accountSubId  New in HBCI2.2: The suffix of the account number. May be NULL.

HBCI_Error* HBCI_API_addBank (  HBCI_API *    h, HBCI_Bank *    b, int    autoDelete )

Add a bank. Add a bank to the internally stored list. Returns : NULL on success, and a HBCI_Error on failure. Parameters: h  The object to perform this action on. b  The bank to add. autoDelete  If TRUE, then the HBCI_API takes ownership of the HBCI_Bank object and will delete it if the life time is over. If FALSE, the HBCI_API will not delete the HBCI_Bank object; instead, the caller is still responsible for its deletion.

HBCI_Error* HBCI_API_addJob (  HBCI_API *    h, HBCI_OutboxJob *    j )

Adds a job to the internal outbox queue. Unlike in former versions you still have access to the jobs, since you only supply a pointer with this method. The HBCI_API will take ownership of this job and will delete it when it gets deleted itself, or when you call clearQueueBy{Result,Status}. So please note that your pointer to the OutboxJob might get invalid if you call clearQueueBy{Result,Status}. For now no error is returned, but maybe later this method will check if the given job fits into the current queue. Parameters: h  The object to perform this action on. j  The job to add. The HBCI_API will take ownership of this job and will delete it when it gets deleted itself, or when you call clearQueueBy{Result,Status}.

HBCI_Bank* HBCI_API_bankFactory (  const HBCI_API *    h, int    country, const char *    bankCode, const char *    server )

Creates a bank object. This will NOT be automatically added to internally stored lists. Parameters: h  The object to perform this action on. country  The ISO-3166 country code of this bank. ("280" is for Germany; see also HBCI_Bank_countryCode.) bankCode  The bank code of this bank. server  The IP address of the HBCI server of this bank in dotted notation.

const list_HBCI_Bank* HBCI_API_bankList (  const HBCI_API *    h )

Returns the list of known banks. List of known banks. May be used for browsing or saving them to disk. Parameters: h  The object to perform this action on. Returns : The list of all known banks.

void HBCI_API_clearQueueByResult (  HBCI_API *    h, OutboxJob_Result    result )

Remove all jobs with the given result code. Parameters: h  The object to perform this action on. result  The result code, where all jobs with that result code are removed from the queue. If HBCI_JOB_RESULT_NONE is given then ALL jobs are removed.

void HBCI_API_clearQueueByStatus (  HBCI_API *    h, OutboxJob_Status    status )

Remove all jobs with the given status code. Parameters: h  The object to perform this action on. status  The status code, where all jobs with that status code are removed from the queue. If HBCI_JOB_RESULT_NONE is given then ALL jobs are removed.

HBCI_Medium* HBCI_API_createNewMedium (  HBCI_API *    h, const char *    mtype, int    readonly, int    country, const char *    bankId, const char *    userid, const char *    name, HBCI_Error **    err )

Creates a new Medium object (and perhaps a new medium file). The newly created object will not be added to internally stored lists; also, no bank, user, or customer object is being created. In case of a DDV medium (chip card) there is not much to be done since all the information is on the DDV chipcard -- therefore simply the Medium object is created and returned. In case of a RDH medium (keyfile), this method will perform the following steps: Create the keyfile if it does not exist. If a file with the same name does exist already, then this method will assume that this file already is a keyfile and will return the MediumRDHBase object with the path of that file (without further checking, i.e. if that file isn't a keyfile, you will run into errors upon medium mounting). For a new file, create the given user on the medium. For a new file, generate new sign and crypt keys for this user Save the new keyfile and return the MediumRDHBase object pointing to that file. Please note that under no circumstances this method will overwrite a file. If the file already exists, then this method assumes that the file contains a valid medium. In that case no keys will be created. You can try to mount the medium after calling this method to check if the existing file really is a medium. But beware: when changing data in the medium prior to mounting it (e.g. by creating new keys) then the file may be overwritten by the medium class. (see also HBCI::MediumRDHBase ) Returns : Pointer to the new medium created. If something went wront, NULL is returned and *err contains the pointer to the HBCI_Error describing the error. Parameters: h  The object to perform this action on. mtype  chooses the kind of medium to be created readonly  FIXME: what is this? country  ISO-3166 country code. In HBCI, "280" stands for Germany (see also HBCI_Bank_countryCode()) bankId  The bank code of the bank of this user (German "Bankleitzahl") userid  The user ID of the user; assigned by the bank name  For DDV media (chip card), this should be the unique card number stored on the card, or simply an empty string. For RDH media (keyfile), this MUST be the full path and filename of the keyfile. err  Pointer to HBCI_Error* that receives the Error, if one occurred.

HBCI_Customer* HBCI_API_customerFactory (  HBCI_User *    u, const char *    id, const char *    custName )

Creates a customer object. This will NOT be automatically added to the given user. Parameters: u  The user this customer (role) belongs to id  The customer ID that the bank assigned to this customer. custName  The name of this customer. You can choose this name as you like, e.g. "business", "private" or whatever you prefer. I.e. you can set this to any arbitrary string you consider helpful.

void HBCI_API_delete (  HBCI_API *    h )

Default Destructor. Parameters: h  The object to destroy.

HBCI_MediumPluginList* HBCI_API_enumerateMediumPlugins (  HBCI_API *    h )

FIXME: Document this Returns : Returns a new plugin list which is then owned by the caller, or NULL if an error occurred. HBCI_MediumPluginList_delete() has to be called when this is no longer needed. If an exception occurred and was caught, NULL will be returned.

HBCI_Error* HBCI_API_executeQueue (  HBCI_API *    h, int    changesAllowed )

Execute jobs in queue. This method executes all jobs in the outbox queue. The jobs remain in the queue until they get removed and deleted via HBCI_API_clearQueueByStatus() or via HBCI_API_clearQueueByResult(). Since from C you cannot pass any (reference-counting) HBCI::Pointer to this method, your C pointers will be pointing to garbage after you called HBCI_API_clearQueueBy{Status,Result}. Therefore make sure you do not use the HBCI_OutboxJob... pointers any longer after you called HBCI_API_clearQueue... Parameters: h  The object to perform this action on. changesAllowed  Specifies whether the jobs in the queue are allowed to change your OpenHBCI data. This affects both HBCI-specific data such as the UPD/BPD (user/bank parameter data) [FIXME: is this correct?] as well as financial data of your accounts such as balance, transactions and standing orders. If this flag is false, then NO changes are made in your OpenHBCI data at all.

HBCI_Bank* HBCI_API_findBank (  const HBCI_API *    h, int    country, const char *    bankCode )

Search for a bank. Searches for a bank in the internally stored list. No joker or wildcard allowed. Parameters: h  The object to perform this action on. country  Country code bankCode  Bank code

HBCI_Medium* HBCI_API_findMedium (  const HBCI_API *    h, const char *    name )

Searches for a medium of the given name. It therefore checks the media of all already knowncustomers. Parameters: h  The object to perform this action on. name  medium name (card number in case of a chip card (DDV), file path and name in case of a keyfile (RDH))

HBCI_Hbci* HBCI_API_Hbci (  HBCI_API *    h )

Upcast. Parameters: h  The object to upcast to HBCI_Hbci.

HBCI_Error* HBCI_API_loadEnvironment (  HBCI_API *    h, const char *    filename )

Load all banks, users and accounts. Parameters: h  The object to perform this action on. filename  The name of the file where data is loaded from.

MediumType HBCI_API_mediumType (  HBCI_API *    h, const char *    mtype )

This method returns the enum MediumType of the named mediumtype. The responsible plugin is loaded if needed. Author: Martin Preuss<martin@libchipcard.de> Parameters: h  The object to perform this action on. mtype  named type (like "DDVCard", "RDHFile" etc)

HBCI_API* HBCI_API_new (  int    readonly, int    retrievalOnly )

Constructor. Author: Christian Stimming <stimming@tuhh.de> Parameters: readonly  if true then no jobs are allowed which actually do something with your account at the bank. (e.g. JobSingleTransfer) retrievalOnly  If set to true, OpenHBCI will only store the minimum of data per account required for subsequent retrieval of account data. I.e. it will not store the balance, transactions, and standing orders of an account.

HBCI_Error* HBCI_API_saveEnvironment (  const HBCI_API *    h, const char *    filename )

Save all banks, users, accounts. Parameters: h  The object to perform this action on. filename  The name of the file where data is saved to.

void HBCI_API_setMonitor (  HBCI_API *    h, HBCI_ProgressMonitor *    m, int    autoDelete )

Set the current progress monitor. Set a new progress monitor to be used. Parameters: h  The object to perform this action on. m  pointer to the monitor to use autoDelete  If TRUE, then the HBCI_API takes ownership of the HBCI_ProgressMonitor object and will delete it if the life time is over. If FALSE, the HBCI_API will not delete the HBCI_ProgressMonitor object; instead, the caller is still responsible for its deletion.

int HBCI_API_totalAccounts (  const HBCI_API *    h )

Returns the total number of accounts that exist within all banks of this API. Author: Christian Stimming <stimming@tuhh.de> Returns : Number of accounts in this API.

int HBCI_API_totalUsers (  const HBCI_API *    h )

Returns the total number of users that exist within all banks of this API. Author: Christian Stimming <stimming@tuhh.de> Returns : Number of users in this API.

HBCI_User* HBCI_API_userFactory (  HBCI_Bank *    b, HBCI_Medium *    m, int    mediumAutoDelete, const char *    userid )

Creates a user object. This will NOT be automatically added to internally stored lists. Parameters: b  The bank that this user belongs to. m  The security medium this user owns. mediumAutoDelete  If TRUE, then the HBCI_API takes ownership of the HBCI_Medium object and will delete it if the life time is over. If FALSE, the HBCI_API will not delete the HBCI_Medium object; instead, the caller is still responsible for its deletion. userid  The user id that identifies this user to his bank.

---