Application Programmers and Service Provider Reference Manual.

Objects

Interfaces (abstract Objects)

Constants and Enumerations

Comments

All DDBAC interfaces are Automation compatible dual interfaces that can be used from and implemented in almost any programming language, including Visual Basic and Visual J++.

Therefore, in an attempt to be comprehensible to programmers using any programming language, the Microsoft IDL syntax is used throughout this document. To make that syntax more readable the names of the data types have been aliased in order to correspond with the Visual Basic type names.

#define Boolean             VARIANT_BOOL
#define Byte                BYTE
#define Long                long
#define String              BSTR
#define Currency            CY
#define Date                DATE
#define Single              float
#define Double              double
#define Variant             VARIANT
#define SafeArray(_type_)   SAFEARRAY(_type_)*

#define True                VARIANT_TRUE
#define False               VARIANT_FALSE
#define Nothing             0

Instances of the BACAccount coclass represent a particular HBCI online banking Account which represents one HIUPD in the contacts UPD.

A BACAccount object can be created directly or found by using the Accounts collection in the BACContact/BACCustomer object.

The BACAccount is always a persistent, readonly object.

Methods and Properties

IBACSegment BACAccount1::FindOptimalBPDSegment(
	[in] String sSegmentType,
	[in] long nMaxSegmentVersion);

Find a matching BPD segment for the requested segmenttype.

The determined segmentversion depends on the avalailabe segments in the Bankdata collection from the BACContact that owns this Account.

With SEPA, some transactions are only possible, when IBAN and BIC of this Account are present.

Parameters

sSegmentType

The segment type is expected like "HIUEBS"

nMaxSegmentVersion

If 0 the highest possible BPD segment version will be used. Otherwise the returned BPD segment version must be less or equal than the nMaxSegmentVersion.

Return Value

Returns the matching BPD BACSegment object or null if no segment could be found.

String BACAccount::AccountNumber;

Get or set the AccountNumber ("Kontonummer")

String BACAccount::AcctName;

Get or set the AcctName ("Kontoproduktbezeichnung")

IDispatch BACAccount::AvailableTransactions;

Collection of all available transaction ("ErlaubteGeschaeftsvorfaelle").

Comments

This is a read only property. Not yet implemented.

String BACAccount::BankCode;

Get or set the BankCode ("Kreditinstitutcode")

String BACAccount::BIC;

Get or set the BIC if the account supports Sepa

String BACAccount::CountryCode;

Get or set the CountryCode ("Laenderkennzeichen")

String BACAccount::Currency;

Get or set the Currency ("Kontowaehrung")

String BACAccount::Customer;

Get or set the BACCustomer owner of this Account.

String BACAccount::CustomerID;

Get or set the CustomerID ("Kundenid")

String BACAccount::Fields([in] String sName);

Indexed property that provides access to the fields of this account

String BACAccount::IBAN;

Get or set the IBAN if the account supports Sepa

IBACContact* BACAccount::IsSepa();

Tests, if the contact supports Sepa. This information is stored separatly from ths HIUPD and contains the result of a HISPA response.

If Sepa is supported, the IBAN and BIC fields are filled.

Return Value

True if Sepa is supported

String BACAccount::NameEins;

Get or set the NameEins ("NameEins")

String BACAccount::NameZwei;

Get or set the NameZwei ("NameZwei")

String BACAccount::Segment;

Get or set the HIUPD BACSegment of this Account.

IDispatch BACAccount::SpendingLimits;

Collection of all SpendingLimits ("Kontolimit")

Comments

This is a read only property. Not yet implemented.

String BACAccount::SubAccountNumber;

Get or set the SubAccountNumber ("Unterkontomerkmal")

The BACAccountData object holds the information of all accounts that are accessible to a particular customer. In the HBCI implementation this object corresponds directly with the User Parameter Data (UPD).

Comments

An application program usually never instantiates a BACAccountData object directly. Instead it creates a customer object via BACBanking::NewCustomer which includes a BACAccountData object in the BACCustomer::AccountData property.

The Segments Collection holds all the HIUPD Segments belonging to the identified User. The Collection is indexed by the account number. The HIUPA Segment of the User is stored in the "UserData" property.

Methods and Properties

See Also

BACBankData

void BACAccountData::Clear();

Clears all stored UPD segments, clears the UserData segment and resets the Version property to zero.

IBACSegments* BACAccountData::Segments;

BACSegments collection of all HIUPD segments that are active for the current homebanking session. These segments describe the accounts that are accessible by the current contact.

void BACAccountData::SetSegment(
	[in] IBACSegment* aSegment);

Adds or updates the given UPD segment. If this is a HIUPD segment and a HIUPD segment referring to the same account already exists in the collection, then it is replaced by the new one. If the segment is the "HIUPA" segment, then the UserID and Version properties are updated according to ts contents. In any case, the object is marked as "Dirty".

Parameters

aSegment

Reference of BACSegment object to set into this account data object.

IBACSegment* BACAccountData::UserData;

This property holds the HIUPA Segment of the User. The properties UserID and Version are merely shortcuts into this Segment.

String BACAccountData::UserID;

Read-only UserID of this UPD. This field is only initialised when the BACAccountData object is instantiated by the BAC, e.g. during BACBanking::NewCustomer. When a BACAccountData object is directly instantiated by an application program, this field holds an empty string.

Long BACAccountData::Version;

Current version of UPD. 0 is a legal Version number, If you need to detect, whether the UPDs have been downloaded or not, use AccountData.Segments.Count. If > 0 UPDs are present.

The BACAccounts object is an OLE Automation Collection that holds an ordered sequence of BACAccount objects.

The BACAccount objects in the collection can be adressed solely through their numerical index. The first BACAccount object has the index zero, the last BACAccount object has the index Count-1.

Methods and Properties

void BACAccounts::Add(
	[in] BACAccount* piAccount,
	[in] Long lBeforeIndex);

Add another BACAccount object to this collection.

Parameters

piAccount

Reference of BACAccount object that shall be added to the collection. Each added reference must be unique within the collection, in other words, the same BACAccount object must not be added twice.

lBeforeIndex

Optionally the position where the segment shall be inserted into the collection can be supplied by the caller. If this index is -1 (its default value) then the segment will be added to the end of the collection.

Long BACAccounts::Count;

Read only property that provides the number of BACAccount objects in this collection.

IBACContact* BACAccounts::Item([in] Long lIndex);

The Item property provides indexed access to the BACAccount objects stored in this collection. The Item property is the default value of the BACAccounts object.

Parameters

lIndex

The individual BACAccount objects stored in this collection can be directly accessed using their positional index in the collection. The first segment has the index zero, the last segment has the index Count-1.

The BACBankData object holds all available information of a particular bank. The bank represented by an instance of the BACBankData object is uniquely identified via its CountryCode and BankCode (In germany this is 280 and the BLZ).

In the HBCI implementation this object is reponsible to manage and represent the Bank Parameter Data (BPD).

Comments

An application program usually never instantiates a BACBankData object directly. Instead it creates a customer object via BACBanking::NewCustomer which includes a BACBankData object in its BACCustomer::BankData property.

The BACBankData object implements the IBACPersistentObject interface in order to manage the BPD file. This means that the BPD data of a BACBankData object can be explicitly stored into and retrieved from a file. Usually, however, persistent storage of the BPD data is managed automatically by the BACCustomer object that hosts the BACBankData object.

In order to import a BPD file for a given BACCustomer object an application program only needs to use the IBACPersistentObject::Load method of the contained BACBankData. If the BACCustomer object is marked as persistent, it will store a working copy of the loaded BPD file in its own storage location.

Methods and Properties

See Also

BACAccountData, BACCustomer

String BACBankData::BankCode;

Unique national bank sort code of this customers bank (BLZ). This property is read-only.

void BACBankData::Clear();

Clears all stored BPD segments and resets the Version property to zero.

Long BACBankData::CountryCode;

Country code of the bank (Laenderkennzeichen). The country code for germany is 280. This property is read-only.

IBACSegments* BACBankData::Segments;

BACSegments of all BPD segments of this bank. This collection corresponds directly with the segments in the persistent BPD file.

void BACBankData::SetSegment(
	[in] IBACSegment* aSegment);

Adds or updates the given BPD segment. If a segment with the same type already exists in the collection, then it is replaced by the new one. If the segment is the "HIBPA" segment, then the BankCode, CountryCode, and Version properties are updated according to ts contents. In any case, the object is marked as "Dirty", that is, the BPD file needs to be re-written.

Parameters

aSegment

Reference of BACSegment object to set into this bank data object.

Long BACBankData::Version;

Current version of BPD stored for this bank. If no BPD have been loaded, yet, then the version number is 0. The first real version number is 1. This property is read only and is only updated when new BPD segments are

The BACBanking object is the root of the object model of the DataDesign HBCI Banking Application Components. The BACBanking object is a singleton object, that is, its state is global across all instances. Hence, it supplies the shared environment for all DDBAC objects and provides the application programmer with convenience methods.

Methods and Properties

IBACCustomers* BACBanking::Customers;

BACCustomers collection that represents all known customer contacts installed in the system.

void BACBanking::DeleteCustomer(
	[in] Long lCountryCode,
	[in] String sBankCode,
	[in] String sUserID);

Deletes a customer entry from the global contacts table.

Parameters

lCountryCode

Country code of the bank (Laenderkennzeichen). The country code for germany is 280.

sBankCode

Identification of bank (in germany this is usually the BLZ). Any homebanking dialog for this customer will be done with this bank. In special cases this may be an empty string.

sUserID

Identification of user (HBCI Benutzerkennung). This is an alpha-numeric string of up to 30 characters that is assigned by the bank when it creates an homebanking account for a person. For anonymous HBCI access this should be an empty string.

String BACBanking::GetSmartcardSecurityProgID(
	[in] IBACCardTerminal* aCT);

Detects the inserted smart card type and returns the ProgID of the security provider class that can handle it.

Parameters

aCT

Reference to card terminal object. This should be obtained through the method BACCardTerminalManager::NewCardTerminal of the BACCardTerminalManager object and not the BACBanking object. This method uses the given object in order to access the inserted smart card.

Return Value

Returns the ProgID of a security provider class that can handle the inserted smart card. Returns an empty string if the inserted card is not known.

If no card is inserted or another card terminal related error occurs an exception is raised.

Comments

This method begins by instantiating a card terminal object. Then it attempts to detect the inserted smart card type through its application ID (AID).

See Also

IBACCardTerminal

Developer Notes

This method is implemented in the IBACBanking3 interface.

IBACCardTerminal* BACBanking::NewCardTerminal();

Creates a new and initialised card terminal object.

Return Value

An implementation of the IBACCardTerminal interface.

Comments

This operation creates a suitable card terminal object as selected through the "Homebanking Kontakte" control panel applet program. Before the created object is returned its IBACCardTerminal::CardTerminalID and IBACCardTerminal::CardTerminalParameter properties are initialized according to the users selection in the control panel applet.

IBACCustomer* BACBanking::NewCustomer(
	[in] Long lCountryCode,
	[in] String sBankCode,
	[in] String sUserID);

Creates a new temporary BACCustomer object that associates the given CountryCode, BankCode, and UserID into a unique identification.

Parameters

lCountryCode

Country code of the bank (Laenderkennzeichen). The country code for germany is 280.

sBankCode

Identification of bank (in germany this is usually the BLZ). Any homebanking dialog for this customer will be done with this bank. In special cases this may be an empty string.

sUserID

Identification of user (HBCI Benutzerkennung). This is an alpha-numeric string of up to 30 characters that is assigned by the bank when it creates an homebanking account for a person. For anonymous HBCI access this should be an empty string.

Return Value

Returns the new BACCustomer object.

Comments

The new contact is not stored in the global contacts table unless one of its fields is explicitly written.

IBACDialog* BACBanking::NewDialog(
	[in] IBACCustomer* aCustomer,
	[in] IBACTransport* aTransport,
	[in] IBACSecurity* aSecurity);

Creates and initialises a new BACDialog object. The new object is strongly associated with the given BACCustomer, IBACTransport, and IBACSecurity objects.

Parameters

aCustomer

BACCustomer object that represents a homebanking contact. This can be either a temporary contact created via NewCustomer or an entry from the Customers collection. If this is Nothing then a temporary customer object is created from information derived from the given aSecurity object.

aTransport

An object that implements the IBACTransport interface. The dialog will use the services of this object to go online. The communications parameters of this object must have been initialized before it is passed to this method. The dialog merely invokes IBACTransport::Connect without any additional parameters in order to go online. If this is Nothing then a transport object is created and initialized from information derived either from the given aCustomer object or (if no aCustomer was given) from the aSecurity object.

aSecurity

Optional security component that provides the security context for the created dialog. If no security context is needed, that is, only anonymous dialog types are done with the returned dialog object, then this parameter may be Nothing. This parameter must not be Nothing if any of the other two object references is Nothing. If given, the security object must have been authenticated before it is passed to this method.

Return Value

Returns the newly created BACDialog object.

Comments

This method provides a low level possibility to construct a BACDialog object. Usually the more convenient BACCustomer::NewDialog method of the BACCustomer object will be used to create a dialog object.

IBACSegment* BACBanking::NewSegment(
	[in] String sSegmentType,
	[in] Long lVersion);

Creates a new and initialised BACSegment object of the given type. If the indicated type is not known to the DDBAC then an error is raised.

Parameters

sSegmentType

Type of segment to create (HBCI Segmentkennung). This is a short string of up to 6 characters such as "HKVVB".

lVersion

Version of segment type to create. If this is zero then, the default version that is appropriate for the default HBCI version bacVersionHBCI is used. If this is in the range 1 through 199, then exactly that segment version will be used. If this is 200 or higher, then it is assumed to be a HBCI version, and a segment version appropriate to that HBCI version will be picked.

Return Value

A BACSegment object.

String BACBanking::Options(String);

Indexed property that provides access to the DDBAC options stored in the registry. This should not be used by application code. Its purpose is to support independent security components or transport components.

Comments

The DDBAC options are stored as string values in the registry key HKLM/SOFTWARE/DataDesign/DDBAC.

When the option is read, and the requested option does not exist, then an empty string is returned. If an error (e.g. access is not granted) occurs when the registry is read, then a corresponding failure HRESULT is returned. If the registry value does not have the type REG_SZ, then DISP_E_TYPEMISMATCH is returned as the HRESULT.

void BACBanking::RunContactsCPL();

Launches the "HBCI Kontakte" Control Panel Applet. Blocks and returns after the applet was closed.

IBACCustomer* BACBanking::RunNewContactWizard();

Jumps directly into the new contact wizard of the "HBCI Kontakte" Control Panel Applet.

Return Value

Returns an instance of a BACCustomer object that corresponds with the newly created contact. If the user cancels the wizard then Nothing is returned.

IBACCustomer* BACBanking::RunNewContactWizardEx(
	[in] String sParameters);

Jumps directly into the new contact wizard of the "HBCI Kontakte" Control Panel Applet. This method allows passing an additional string parameter to the control panel.

Parameters

sParameters

Currently only a single parameter option is defined: Passing a string that starts with the captial letter 'C', a custom bitmap resource can be specified.

Return Value

Returns an instance of a BACCustomer object that corresponds with the newly created contact. If the user cancels the wizard then Nothing is returned.

Comments

The specified resource must contain a 256 color bitmap that is 120 pixels wide and 226 pixels tall. The string must be specified exactly as follows:

C[ModuleFilename],[ResourceID],0x[RR][GG][BB]

Where [ModuleFilename] provides the filename of the DLL or EXE module that contains the bitmap resource. The [ResourceID] is the numeric resource ID of the resource in the given module.

Finally, for future use a dialog background color must be given as hexadecimal RGB values with two hex digits per base color.

A complete example parameter string looks, used by the new HBCIPad sample, is:

CHBCIPAD.EXE,101,0x083863

Boolean BACBanking::SynchronizeCustomer(
	[in] IBACCustomer* aCustomer);

Runs the synchronization from the "Homebanking Kontakte" control panel applet for a given BACCustomer object.

Parameters

aCustomer

BACCustomer object that represents the homebanking contact that shall be synchronized.

Return Value

Returns True if the customer was successfully synchronized and is now ready to use. Returns False if not. Thus return value is identical to the "NeedSynchronisation" field value of the BACCustomer object.

Developer Notes

This method is implemented in the IBACBanking2 interface.

The interface IBACBlzInfo allows you to search in the Institute Database

Methods and Properties

String BACBlzInfo::FindByBLZ(
	String sBLZ);

Searches the XML for a specific Bank-Identification-Code (Bankleitzahl)

Parameters

sBLZ

The Bank-Identification-Code (Bankleitzahl) to search for

Return Value

Returns a XML string that contains the BankInfo data.

<XML>
	<BANK>
		<BLZ>70000999</BLZ>
		<NAME>DataDesign DemoBank</NAME>
		<NOTICE>MIGRATION</NOTICE>
		<SRC>E</SRC>
		<HBCI>
			<IP>hbci02.datadesign.de</IP>
			<SFX>HBCIServerSfx</SFX>
			<VER>220</VER>
			<USR>Benutzernummer</USR>
			<ID>HBCIKundeID</ID>
		</HBCI>
		<PTAN>
			<URL>http://hbci02.datadesign.de/</URL>
			<VER>220</VER>
			<ID>PTANKundeID</ID>
			<USR>PTANBenutzerkennung</USR>
			<SFX>PTANServerSfx</SFX>
		</PTAN>
	</BANK>
</XML>

String BACBlzInfo::FindByXPath(
	String sXPath);

Searches the XML with any XPath expression. You may search for NAME, CITY and so on

Parameters

sXPath

The XPath to search for

Return Value

See FindByBLZ

String BACBlzInfo::GetValue(
	String bstrXml,
	String bstrXPath);

Helperfunction to extract single value from a XML string.

Parameters

bstrXml

Contains the whole XML as returned by FindByBLZ

bstrXPath

XPath exression like: //BANK/HBCI/IP to extract the value of the BCI Server.

Return Value

Value as String, Empty String if Tag is Empty or not found.

Object give access to a configured Chipdrive. The Cardterminal will be configured by the "Chipdrive Administrator" control panel application.

Methods and Properties

IBACCardTerminal* BACCardTerminalManager::NewCardTerminal();

Creates a new and initialised card terminal object.

Return Value

An implementation of the IBACCardTerminal interface.

Comments

This operation creates a suitable card terminal object as selected through the "Homebanking Kontakte" control panel applet program. Before the created object is returned its IBACCardTerminal::CardTerminalID and IBACCardTerminal::CardTerminalParameter properties are initialized according to the users selection in the control panel applet.

IBACCardTerminal* BACCardTerminalManager::RunCPL(
	String sReservedForFuturUse);

Runs a new instance of Chipdrive Administrator.

Parameters

sReservedForFuturUse

Don't use.

Instances of the BACContact coclass represent a particular HBCI online banking contact, uniquely identified by the combination of the ID Tag.

A BACContact object can be created directly or found by using the IBACContacts collection.

The BACContact is always a persistent object, which can explicity saved, deleted and created.

The BACContact object is responsible for managing all persistent storage of contact attributes, user records, bank records and the BPD and UPD files. The current implementation maintains all its data in the configurable DataDir folder.

The BACContact Object supports the IBACCustomer4 Interface, which is needed for all the other operations. Consider the BACContact as the persistent Banking contact and the BACCustomer Object as a temporary Customer, where the operations run on. The results can be save, by calling the Save() method oder dropped by simply destroying the IBACContact.

This behaviour differs from the IBACCustomer, where, (in persistent mode) all changes are automatically saved, when the content has changed and the object is destroyed.

A BACContact Object can be identified with the "ID" value from the Fields property. This "ID" contains an unique value that can be used to load the contact at a later time using the Load() function.

Methods and Properties

IBACContact* BACContact::ActivateTANList(
	long hWnd);

Opens a wizard, which collects the neccessary data to execute a HKTLF or DKTLF

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::CanActivateTANList();

Tests, if the Contact allows HITLFS or DITLFS

Return Value

True if the function is supported.

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::CanChangeKeys();

Tests, if the Contact supports a key change on the security media.

Return Value

True if the function is supported.

Developer Notes

This method is implemented in the IBACContact3 interface.

IBACContact* BACContact::CanChangePin();

Tests, if the Contact supports pin change.

Return Value

True if the function is supported.

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::CanChangeTANMethod();

Tests, if the Contact allows to change the two-step-tan-method. This requieres a two-step contact with at leat one two-step-method

Return Value

True if the function is supported.

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::CanGenerateIniLetter();

Tests, if the Contact supports the generation of an ini-letter.

Return Value

True if the function is supported.

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::CanLockKeys();

Tests, if the Contact supports locking of the keys.

Return Value

True if the function is supported.

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::CanLockPIN();

Tests, if the Contact allows HIPSPS or DIPSPS

Return Value

True if the function is supported.

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::CanLockTANList();

Tests, if the Contact allows HITSPS or DITSPS

Return Value

True if the function is supported.

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::CanRequestTANList();

Tests, if the Contact allows HITLAS or DITLAS

Return Value

True if the function is supported.

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::CanShowTANList();

Tests, if the Contact allows HITAZS or DITAZS

Return Value

True if the function is supported.

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::CanUnlockPIN();

Tests, if the Contact allows HISASS or DISASS

Return Value

True if the function is supported.

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::CanUpgradeKeys();

Tests, if the Contact supports "Sicherheitsprofilwechsel"

Return Value

True if the function is supported.

Developer Notes

This method is implemented in the IBACContact3 interface.

IBACContact* BACContact::ChangeConnection(
	long hWnd);

Opens a wizard, which allows the user to change the communication paramters. There is no CanChangeConnection, since this would be always true.

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::ChangeHbciVersion(
	long hWnd);

Opens a wizard, which allows the user to change the HBCI Version. There is no CanChangeHbciVersion, since this would be always true.

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::ChangeKeys(
	long hWnd);

Opens a wizard, which allows the user to change the keys in the security media.

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

Developer Notes

This method is implemented in the IBACContact3 interface.

IBACContact* BACContact::ChangePin(
	long hWnd);

Opens the changepin wizard to change the pin of a BACContact. This can be different, depending on the security media. For PIN/TAN contacts, a message ist send to the server, for smardcards, the Pin is set on the card and for files, it's set for the file. This command executes a ChangePinRq

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

IBACContact* BACContact::ChangeTANMethod(
	long hWnd);

Opens a wizard, which allows the user to select a two-step-tan-method and synchronises the account afterwards.

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::ChangeUserId(
	long hWnd);

Opens a wizard, which allows the user to change the User/CustomerID and the Contact Name. There is no CanChangeUserId, since this would be always true.

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

Developer Notes

This method is implemented in the IBACContact2 interface.

HRESULT BACContact::Create();

Creates a new, empty Contact

HRESULT BACContact::Delete();

Deletes the customers data. This executes a DeleteCustomerRq

IBACContact* BACContact::Edit(
	long hWnd);

Opens a dialog, where the user is able to change the current contacts account data. This command executes a EditContactRq

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

IBACContact* BACContact::Execute(
	long hWnd,
	String bsRequest);

Executes a request by name, the Dialogresult returns,

Parameters

hWnd

Handle of the parent window.

bsRequest

XML Request.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::GenerateIniLetter(
	long hWnd);

Opens a wizard, which allows the user generate the ini-letter

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::IsPersistant();

Tests, if the contact is already stored or if it is a new or temporary contact.

Return Value

True if the contact is stored.

Developer Notes

This method is implemented in the IBACContact2 interface.

HRESULT BACContact::Load();

Loads an existing Contact with the specified ID. This executes a ReadCustomerRq ID="bstrID"

IBACContact* BACContact::LockKeys(
	long hWnd);

Opens a dialog, where the user is able to lock contact. This command executes a LockContactRq

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

IBACContact* BACContact::LockPIN(
	long hWnd);

Opens a wizard, which collects the neccessary data to execute a HKPSP or DKPSP

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::LockTANList(
	long hWnd);

Opens a wizard, which collects the neccessary data to execute a HKSPS or DKSPS

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

Developer Notes

This method is implemented in the IBACContact2 interface.

BACDialogResults BACContact::NewWizard(
	long hWnd);

Version of new Segment correspond to BACSyntaxSegment::Version. Opens the new contact wizard to create a new BACContact. If the DialogResult is bacDialogResultOK, the BACContact object has been successfully created, has already been saved and can be used. This command executes a NewContactWizardRq request.

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

IBACContact* BACContact::QueryPin();

Sends a QueryPinRq through the callback interface, so that the application can provide a PIN if the PIN ist persistant.

The default implementation will never return a Pin here, its up to the application to provide the Pin here.

Return Value

The PIN.

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::RequestTANList(
	long hWnd);

Opens a wizard, which collects the neccessary data to execute a HKTLA or DKTLA

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

Developer Notes

This method is implemented in the IBACContact2 interface.

HRESULT BACContact::Save();

Saves the customers data. This executes a UpdateCustomerRq

IBACContact* BACContact::ShowTANList(
	long hWnd);

Opens a wizard, which collects the neccessary data to execute a HKTAZ or DKTAZ

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::Synchronize(
	long hWnd);

Opens the synchronize wizard to synchronize new BACContact. This function check for alle neccessary information, that is needed. This includes BankKeys, UserKey, test for aktual HKVVB Version. This command executes a SyncCustomerWizardRq

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

IBACContact* BACContact::UnlockPIN(
	long hWnd);

Opens a wizard, which collects the neccessary data to execute a HKSAS or DKSAS

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

Developer Notes

This method is implemented in the IBACContact2 interface.

IBACContact* BACContact::UpgradeKeys(
	long hWnd);

Opens a wizard, which allows the user to perform a "Sicherheitsprofilwechsel".

Parameters

hWnd

Handle of the parent window.

Return Value

Wether the Dialog has been closed with BACDialogResults::bacDialogResultOK or BACDialogResults::bacDialogResultCancelled

Developer Notes

This method is implemented in the IBACContact3 interface.

The BACContacts object is an OLE Automation Collection that holds an ordered sequence of BACContact objects.

The collection is empty until PopulateContacts is called.

The BACContact objects in the collection can be adressed solely through their numerical index. The first BACCustomer object has the index zero, the last BACContact object has the index Count-1.

Methods and Properties

Long BACContacts::Count;

Read only property that provides the number of BACContact objects in this collection.

Long BACContacts::FindContact(
	[in] String sContact);

Finds a particular BACCustomer object identified by its unique contact name.

Parameters

sContact

Unique contact ID.

Return Value

If the BACContact object was found its index is returned. If no matching BACContact object is found then -1 is returned.

IBACContact* BACContacts::Item([in] Long lIndex);

The Item property provides indexed access to the BACContact objects stored in this collection. The Item property is the default value of the BACContacts object.

Parameters

lIndex

The individual BACContact objects stored in this collection can be directly accessed using their positional index in the collection. The first segment has the index zero, the last segment has the index Count-1.

Long BACContacts::Populate(
	[in] String sFilter);

Populates the list by generating a ListCustomersRq.

Parameters

sFilter

The XML XPath Filter, which will be passed to ListCustomersRq Filter="xx" An empty string will return all contacts.

Instances of the BACCustomer coclass represent a particular HBCI online banking contact, uniquely identified by the combination of CountryCode, BankCode and UserID.

The actual CustomerID is a property of the BACDialog session object and is bound when a dialog is begun with BACDialog::BeginDialog. The CustomerID that is stored as a BACCustomer field is only a default value that is used when no CustomerID was explicitly passed to BACDialog::BeginDialog.

A BACCustomer object can be created explicitly through the BACBanking::NewCustomer method. A collection of user installed contacts is available through the BACBanking::Customers collection. Usually an application will pick one of the installed contacts.

The BACCustomer object comes in two flavours, Persistent and Transient. A persistent BACCustomer object is tied to the local contact storage (DDUSERS.DAT, UPD, and BPD files). On the other hand, a transient BACCustomer object holds all properties, UPD, and BPD only in volatile memory and never accesses the local contact storage.

The third possibility to create a BACCustomer object is through invoking BACBanking::NewDialog with a null reference for the customer object parameter. In this case, the DDBAC will automatically create a suitable BACCustomer object based on information extracted directly from the security object.

Through the pseudo field "Transient", a client program can determine whether a given BACCustomer object is transient or persistent. If this field is returned as zero or an empty string, then the BACCustomer object is persistent. For a transient object this field is returned as "1".

A BACCustomer should be generally thread as a temporary Customer to do some actions with, all data changed during this interaction will not be stored.

The persistent BACCustomer object is kept for compatibilitiy reasons. The persistant Contact is now represanted by the BACContact Object. Please refer to this object for persistant contact.

The account data is maintained by the BACAccountData object that is held in the AccountData property. The account data corresponds with the HBCI User Parameter Data (UPD). The persistent account data is loaded from the corresponding UPD file when the AccountData property is accessed for the first time. The UPD file is written back whenever the data is updated. An update usually only occurs during initialisation of the online dialog when the account information for the user has changed.

The bank data is maintained by the BACBankData object that is referenced by the BankData property. The bank data corresponds with the HBCI Bank Parameter Data (BPD). The bank data is handled largely similar to the account data. Note, however, that the bank data of a bank is shared by all contacts that refer to the same bank.

Methods and Properties

See Also

BACBanking::NewCustomer, BACBanking::Customers, BACDialog::BeginDialog, BACDialog::CustomerID, BACAccountData, BACBankData

IBACAccountData* BACCustomer::AccountData;

BACAccountData object that holds information about all accounts that the customer can work with.

Comments

In the HBCI implementation, the accounts information is stored in a HBCI conformant UPD file.

IBACSecurity BACCustomer::Authenticate(
	[in] String sPassphrase);

Hidden internal method that returns an authenticated security object for this customer.

Parameters

sPassphrase

Secret password or PIN that is used to protect access to the security media. This passphrase is used to authenticate the security media associated with this customer.

Return Value

Returns the authenticated security object. If authentication fails, then the security object will raise an error.

IBACSecurity BACCustomer::AuthenticateUI();

Hidden internal method that returns an authenticated security object for this customer.

This method differs from Authenticate in that it prompts the user to enter the passphrase or PIN. As such it is more convenient and can support class 2 smart card readers with protected PIN entry.

Return Value

Returns the authenticated security object. If authentication fails, then the method will raise an error. If the user cancels the PIN entry then this method returns with a null (VisualBasic Nothing) return value.

Developer Notes

This method is implemented in the IBACCustomer3 interface.

String BACCustomer::BankCode;

Unique national bank sort code of this customers bank (BLZ). This property is read-only.

IBACBankData* BACCustomer::BankData;

Reference to BACBankData object that holds information about the bank identified by this object.

Comments

In the HBCI implementation, the bank information is stored in a HBCI conformant BPD file.

Long BACCustomer::CountryCode;

Country code of the bank (Laenderkennzeichen). The country code for germany is 280. This property is read-only.

String BACCustomer::Fields([in] String sName);

Indexed property that provides access to the fields of this customers record in the global customer table.

The global customer table maintains a dynamic set of string value fields that are accessed by name. An application program is allowed to add any additional fields of its own, as long as the chosen field name does begin with an underscore ('_') character. Fields added by the application are stored and retrieved along with the DDBAC defined fields.

Comments

Currently the following values are stored in the DDUSERS.DAT file.

Contact

This field holds the human readable name of this contact (aka BACCustomer) record. It is assigned by the "Homebanking Kontakte" control panel applet when the contact is set up.

SecurityProgID

This field holds the COM ProgID of the security provider component that is responsible for handling the security media of this contact. It is assigned by the "Homebanking Kontakte" control panel applet when the contact is set up.

SecurityMediaID

This field holds the optional security media ID for this contact. For software based RDH security this is the actual filename of the keyfile. This field is assigned by the "Homebanking Kontakte" control panel applet when the contact is set up. If security media is a DDV chipcard this field contains the "ContactIndex" of DDV smartcard, where 1 is the first contact at smartcard. If security media is a FST keyfile field contains also information about user name and contact index of FST file, SecurityMediaID is build like: %filename%?UserName=%username%&ContactIndex=%contactindex%".

SecurityMediaType

This field indicates the security media type. The possible values are enumerated in BACSecurityMediaTypes. This field is assigned by the "Homebanking Kontakte" control panel applet when the contact is set up.

CustomerSystemStatus

This field contains a copy of the security components IBACSecurity::Parameter attribute of the same name. The field is assigned by the "Homebanking Kontakte" control panel applet when the contact is set up.

BankName

This field holds an optional human readable bank name. It is derived from the security media during contact set up.

CustomerID

This field holds the default CustomerID. It is derived from the security media during contact set up. If this is empty, then the UserID will be used as the default CustomerID.

BankUserID

This field holds the BankUserID. It is derived from the security media during contact set up.

CommunicationsService

This field holds the CommunicationsService required for this contact. It is derived from the security media during contact set up. If this is empty, then this value will be read from the security media.

CommunicationsAddress

This field holds the CommunicationsAddress required for this contact. It is derived from the security media during contact set up. If this is empty, then this value will be read from the security media.

CommunicationsAddressSuffix

This field holds the CommunicationsAddressSuffix required for this contact. It is derived from the security media during contact set up. If this is empty, then this value will be read from the security media.

CustomerSystemID

This field holds the dynamically synchronized customer system ID (if it is used at all). It is assigned during synchronization whenever the CustomerSystemStatus is "1".

SignatureID

This fields holds the monotonically increasing signature ID for this contact.

HBCIVersion

HBCI Version of customer.

NeedSynchronisation

Starting with Release 2,0,7,0 of the DDBAC a pseudo field "NeedSynchronisation" (spelling!) is implemented. Reading this field returns "1" if this BACCustomer must be synchronized before it can be used. It returns "0" if the BACCustomer is ready for use. Previous DDBAC versions do not know this field name and therefore return an empty string as the result.

ManualUPD

Starting with Release 2,1 of DDBAC field ManualUPD is added. It's value is "1" for all credit institution who don't send UPD data to client, otherwise the value is "0". If ManualUPD returns "1" user have to manually enter account information.

UPDVersion

UPDVersion, if the data is synchronized otherwise blank

BPDVersion

BPDVersion, if the data is synchronized otherwise blank

ID

Returns a unique ID for this contact if it is persistant, which can be used to reference the Contact and load it at a later time. (See BACContact).

HKVVBVersion

Alternate HKVVB Version. Default is Version 2. If the HBCIVersion is greater than 3.0 some insitutes require HKVVB Version 3.

ManualITan

If set to "1" the DDBAC does not automatically check for HITANS and does not supply HKTAN segments. Default is: "0".

ITanSupported

Returns 1 if the customers UPD contains a HKTAN Segment.

ITANVerfahren

Comma separated lst of allowed ITANVerfahren for this Customer (returned in HIRMS with Code 3920 during synchronisation)

Sicherheitsfunktion

Can be used to specify a specific ITAN security process. If not set, the first entry in HITANS in the BPD will be used. Refer to documentation and samples.

ProductName

Can be optionally used to override the value in the HKVVB Segment. Default is DDBAC/"Processname".

ProductVersion

Can be optionally used to override the value in the HKVVB Segment. Default is the current version number of the DDBAC.dll.

SecurityMediaID

The currently assigned security media ID, like "Chipkarte.DDV.Type0" or "Chipkarte.RDH.ZKA". See documentation for further details.

SecurityMediaDescription (Readonly)

Description of the used security media.

MinPinLength (Readonly)

Minimal PIN length.

MaxPinLength (Readonly)

Maximal PIN length.

PinOnlyNumeric (Readonly)

"1" if only numeric PINs are allowed

PinRequirements (Readonly)

Every PIN must match the rules descriped here.

CanChangeKeys (Readonly)

"1" if the private key can be changed

CanUpgradeKeys (Readonly)

"1" if the keys can be upgraded (Sicherheitsprofilwechsel)

RemainingSignatures (read only)

Return the number of remaining signatures before the card expires. Is empty if the medium has no limited number of signatures.

Parameters

sName

The individual fields are indexed by the field name.

String BACCustomer::GetCustomerSystemID(
	[in] IBACSecurity* piSecurity);

Hidden internal method that returns the right CustomerSystemID.

Parameters

piSecurity

Required reference to an authenticated security object.

Return Value

Returns the assigned CustomerSystemID, "0" or an empty string.

Comments

If the CustomerSystemStatus of this contact is "0", then CustomerSystemIDs are not used and therefore "0" is returned.

Otherwise, if the SecurityMediaStatus is "0" or an empty string, then the fields of this BACCustomer object are queried for a CustomerSystemID. If the SecurityMediaStatus is "1", then the Parameters property of the given security object (if any) is queried. If no CustomerSystemID was found an empty string is returned.

Developer Notes

This method is implemented in the IBACCustomer2 interface.

String BACCustomer::GetSignatureID(
	[in] IBACSecurity* piSecurity);

Hidden internal method that returns the next unused SignatureID and increments the stored value, such that the returned value will never be returned again.

Parameters

piSecurity

Required reference to an authenticated security object.

Return Value

Returns the next SignatureID or "0".

Comments

If the CustomerSystemStatus is 0, then the SignatureID is completely managed by the security object. In this case, this method simply returns the value of the "SignatureID" parameter of the security object. It is the responsibility of the security object to increment this counter appropriately.

Otherwise, the SecurityMediaStatus of the security object is checked. If it is "0" or an empty string, then an attempt is made to read a SignatureID from a field of the BACCustomer object. If this results in an nonempty string, then we assume this is the right one. The BACCustomer field "SignatureID" always holds the NEXT SignatureID that shall be assigned, thus if we are retrieving this value successfully, then we increment and update it. If an empty string was returned, then a warning message is logged and the special SignatureID value "0" is returned to the caller.

If the SecurityMediaStatus is "1", then an attempt is made to obtain a SignatureID from the security object. If that succeeds, the obtained SignatureID is returned. If we still do not have a SignatureID, then a warning message is logged and the special SignatureID value "0" is returned.

Developer Notes

This method is implemented in the IBACCustomer2 interface.

IBACDialog* BACCustomer::NewDialog(
	[in] String sPassphrase);

Creates a new BACDialog object using the information stored in this contact. This is a convenience method that ultimately invokes BACBanking::NewDialog.

Parameters

sPassphrase

Secret password or PIN that is used to protect access to the security media. If the security media is a smartcard, then this probably a simple PIN. If the security media is a plain file, then this should be a long and complex password, hence it is called a passphrase. This passphrase is used to authenticate the security media associated with this contact before passing it to the dialog object.

Return Value

Returns the newly created BACDialog object.

Comments

This method starts by attempting to instantiate a security object using the ProgID from the Field "SecurityProgID". If this field is empty or the method fails to create the security provider for another reason, then the failure is propagated to the caller.

Next the security object is authenticated using the given passphrase and the value from the "SecurityMediaID" Field of this BACCustomer. An empty security media ID is propagated to the security object. If authentication fails, then this method fails, too.

The transport provider object named by the field "CommunicationsProgID" is instantiated and initialized with the communication parameters from the fields "CommunicationsAddress" and "CommunicationsAddressSuffix".

Finally, using the security and transport objects a new dialog is created via BACBanking::NewDialog. The BACCustomer object does not keep any references to the security or transport objects. Hence they will be released along with the BACDialog object.

IBACDialog* BACCustomer::NewDialogUI();

Creates a new BACDialog object using the information stored in this contact. This is a convenience method that ultimately invokes BACBanking::NewDialog.

This method differs from NewDialog in that it prompts the user to enter the passphrase or PIN. As such it is more convenient and can support class 2 smart card readers with protected PIN entry.

Return Value

Returns the newly created BACDialog object. If authentication fails, then the method will raise an error. If the user cancels the PIN entry then this method returns with a null (VisualBasic Nothing) return value.

Developer Notes

This method is implemented in the IBACCustomer3 interface.

void BACCustomer::SetCustomerSystemID(
	[in] IBACSecurity* piSecurity,
	[in] String sCustomerSystemID);

Hidden internal method that returns the right CustomerSystemID.

Parameters

piSecurity

Required reference to an authenticated security object.

sCustomerSystemID

Nonempty CustomerSystemID assigned by the HBCI server.

Comments

This method is called whenever a HISYN with a CustomerSystemID was received in an online dialogue. Note that this method is invoked by the BACDialog object for all HISYN segments that carry a new CustomerSystemID, regardless of the actual CustomerSystemStatus or SecurityMediaStatus indicated by the security media.

First of all, if the CustomerSystemStatus is not "1", then a warning message is logged and the method returns without storing anything.

If the SecurityMediaStatus of the contact is "0" or an empty string, then the CustomerSystemID is stored in this BACCustomer object's field of that name. As the SignatureID is tied to the CustomerSystemID, the SignatureID counter stored with the BACCustomer is also reset to one.

If the SecurityMediaStatus is "1", then the given sCustomerSystemID is written to the security media, replacing whatever was previously stored for it.

Developer Notes

This method is implemented in the IBACCustomer2 interface.

void BACCustomer::SignMessage(
	[in] IBACMessage* piMessage,
	[in] String sPassphrase,
	[in] BACSignerRole nSignerRole);

Adds an explicit signature to the given BACMessage. The "TAN" in the BACCustomer Object can be used to provide a TAN if Pin/Tan based security is used. This will avoid additional UI requests.

Parameters

piMessage

This is the message that will be signed. It must be either in the bacMessageInit or the bacMessageSigned state and must be ready to accept another signature.

sPassphrase

Secret password or PIN that is used to protect access to the security media. This passphrase is used to authenticate the security media associated with this customer before it is used to create the signature.

nSignerRole

Determines the role of the signer that signs this message. By default the role bacSignerConfirms is assumed for the signature.

void BACCustomer::SignMessageUI(
	[in] IBACMessage* piMessage,
	[in] BACSignerRole nSignerRole);

Adds an explicit signature to the given BACMessage.

This method differs from SignMessage in that it prompts the user to enter the passphrase or PIN. As such it is more convenient and can support class 2 smart card readers with protected PIN entry.

Parameters

piMessage

This is the message that will be signed. It must be either in the bacMessageInit or the bacMessageSigned state and must be ready to accept another signature.

nSignerRole

Determines the role of the signer that signs this message. By default the role bacSignerConfirms is assumed for the signature.

Comments

If authentication fails, then the method will raise an error. If the user cancels the PIN entry then this method returns successful, but does not sign the message.

Developer Notes

This method is implemented in the IBACCustomer3 interface.

Long BACCustomer::TransactionNeedsTAN(
	[in] String sSegmentType);

This method determines whether a TAN is required for th given segment type. It does so by searching the BPD for information.

Parameters

sSegmentType

Type of transaction segment that shall be sent.

Return Value

Returns the number of TANs required for the given transaction type. Currently only either 0 or 1 is returned.

Developer Notes

This method is implemented in the IBACCustomer4 interface.

void BACCustomer::UpdateAccountInformation(
	[in] IBACDialog* piDialog);

The new Sepa standard defines additional Accountdatadata like IBAN or BIC which must be retrieved separatly from the UPD information.

This function uses the given Dialog to send a HKSPA for each Accound in the UPD. The response for every BACAccount ist stored in the BACAccounts collection. This collection is persistand, and will be available when the Account is loaded.

Parameters

piDialog

This Dialog will be used to send the HKSPA request.

Comments

This function ist automatically called when new UPD or BPDs are received during BeginDialog or when the Account is being synchronised.

The BACCustomer will not be automatically saved.

Developer Notes

This method is implemented in the IBACContact3 interface.

void BACCustomer::UpdateAccountInformation(
	[in] IBACDialog* piDialog);

The new Sepa standard defines additional Accountdatadata like IBAN or BIC which must be retrieved separatly from the UPD information.

This function uses the given Dialog to send a HKSPA for each Accound in the UPD. The response for every BACAccount ist stored in the BACAccounts collection. This collection is persistand, and will be available when the Account is loaded.

Parameters

piDialog

This Dialog will be used to send the HKSPA request.

Comments

This function ist automatically called when new UPD or BPDs are received during BeginDialog or when the Account is being synchronised.

The BACCustomer will not be automatically saved.

Developer Notes

This method is implemented in the IBACCustomer5 interface.

String BACCustomer::UserID;

The UserID (HBCI Benutzerkennung) of this customer. This property is read-only.

The BACCustomers object is an OLE Automation Collection that holds an ordered sequence of BACCustomer objects. It cannot be instantiated by applications but solely exists in the BACBanking::Customers property of the BACBanking object.

The BACCustomer objects in the collection can be adressed solely through their numerical index. The first BACCustomer object has the index zero, the last BACCustomer object has the index Count-1.

Methods and Properties

Long BACCustomers::Count;

Read only property that provides the number of BACCustomer objects in this collection.

Long BACCustomers::FindContact(
	[in] String sContact);

Finds a particular BACCustomer object identified by its unique contact name.

Parameters

sContact

Unique contact name.

Return Value

If the BACCustomer object was found its index is returned. If no matching BACCustomer object is found then -1 is returned.

Long BACCustomers::FindCustomer(
	[in] Long lCountryCode,
	[in] String sBankCode,
	[in] String sUserID);

Finds a particular BACCustomer object identified by its unique contact parameters.

Parameters

lCountryCode

Country code.

sBankCode

Bank code.

sUserID

User ID.

Return Value

If the BACCustomer object was found its index is returned. If no matching BACCustomer object is found then -1 is returned.

IBACCustomer* BACCustomers::Item([in] Long lIndex);

The Item property provides indexed access to the BACCustomer objects stored in this collection. The Item property is the default value of the BACCustomers object.

Parameters

lIndex

The individual BACCustomer objects stored in this collection can be directly accessed using their positional index in the collection. The first segment has the index zero, the last segment has the index Count-1.

The BACDataObject class is a small helper class that can be used to set and retrieve small binary data elements inside a segment.

When an application has to send the contents of a file inside a binary data element it instantiates a BACDataObject and invokes its Load() method in order to associate it with the file to be sent. It then sets the object as the value of a segments data element. Everything else happens automatically.

Methods and Properties

void BACDataObject::GetData(
	[in, out] SafeArray(Byte) aData);

Returns the data of this data object. The entire data is returned.

Parameters

aData

Byte array that will be replaced with a new array that contains the entire data of this object.

String BACDataObject::GetString();

Returns the data of this data object as a String. The entire data is returned in a single string.

Return Value

The returned string contains the entire data of this object. Although this is an Unicode string, only the low order byte of each character is used to hold the actual binary data. The returned string may contain NUL characters.

Developer Notes

This method is implemented in the IBACDataObject2 interface.

void BACDataObject::PutData(
	[in, out] SafeArray(Byte) aData);

Provide the data for this data object. The supplied data replaces any previuosly held data.

Parameters

aData

Byte array that contains the new data for this object.

void BACDataObject::PutString(
	[in] String sData);

Provides the data for this data object as a String. The supplied data replaces any previuosly held data.

Parameters

sData

String that contains the new data for this object. Although this is an Unicode string, only the low order byte of each character is used as the actual binary data. This string may contain NUL characters.

Developer Notes

This method is implemented in the IBACDataObject2 interface.

void BACDataObject::ReadFromObject(
	[in] IUnknown* piObject);

Retrieves the data for this data object from the given source object. The source object data replaces all data that this data object currently holds.

Parameters

piObject

Reference to source object. The source object's class must implement the IPersistStream interface. The data for this data object is retrieved from the source object through the IPersistStream::Save() method. The dirty flag of the object won't be cleared by this invocation.

All DDBAC persistent objects implement the IPersistStream interface and therefore can be used with this method.

Developer Notes

This method is implemented in the IBACDataObject2 interface.

void BACDataObject::WriteToObject(
	[in] IUnknown* piObject);

Sends the data for this data object to the given destination object. The destination object is re-initialized with the data from this data object.

Parameters

piObject

Reference to destination object. The destination object's class must implement the IPersistStream interface. The data of this data object is sent to the destination object through the IPersistStream::Load() method.

All DDBAC persistent objects implement the IPersistStream interface and therefore can be used with this method.

Developer Notes

This method is implemented in the IBACDataObject2 interface.

The BACDialog object represents the online dialog of a customer with a particular bank.

Methods, Properties and Events

void BACDialog::Abort();

Forcibly abort the current Dialog. This means any pending activity is cancelled and the transport connection is torn down. This method is always synchronous, when it returns, the dialog really was aborted.

Boolean BACDialog::Asynchronous;

This property determines whether online operations will be synchronous or asynchronous. By default this property is False whenever a BACDialog object is created. An application that wants asynchronous online operations must explicitly set this property to True after instantiating the BACDialog object.

Comments

If synchronous operation is selected and the operation does not complete within the timeout limit, the dialog will be forcibly aborted and an error is raised.

If asynchronous operation is selected, then all methods will return immediately performing the actual online operation asynchronously in the background.

Boolean BACDialog::AutoSignature;

This property determines whether outgoing messages will be automatically signed, or not. By default this will be set to "True" to have all messages signed.

Comments

Regardless of the setting of this property, if no security object is available messages will not be signed.

IBACSegments* BACDialog::BankNotices;

This BACSegments collection receives all HIKIM segments that were received from the bank since this dialog was started.

IBACMessage* BACDialog::BeginDialog(
	[in] BACDialogTypes nDialogType,
	[in] String sCustomerID,
	[in] IBACMessage* aBeginDialogMessage);

Begins a homebanking online session, aka. dialog. All homebanking transactions must be submitted in the context of an online dialog. A homebanking online dialog is closed down with the EndDialog method.

Parameters

nDialogType

Selects the type of dialog that shall be begun. HBCI defines several different dialog types which differ in various ways. Foremost the differ in their usage of signatures and encryption and in the contents of the initialization message. The default dialog type is bacDialogStandard. If dialog initialization is successful, the properties DialogType, and AutoSignature will be set according to this parameter (i.e. AutoSignature is turned off for any anonymous dialogs and turned on for non-anonymous dialog types).

sCustomerID

Selects the CustomerID for the online dialog. The CustomerID cannot be changed while an online dialog is in progress. If this is an empty string, then the UserID of the associated BACCustomer object will be used. For anonymous dialog types

aBeginDialogMessage

Optional initialisation message that shall be sent during dialog initialisation. This parameter can be set to "Nothing". In this case the BACDialog object will create suitable initialisation message depending on the selected dialog type.

An application might want to provide its own initialisation message in order to support system specific customisations.

Return Value

If an initialisation message was provided by the caller, then that same message will be returned. If "Nothing" was provided, then the created initialisation message is returned.

Comments

This method begins by attempting to establish a transport connection using the supplied transport object. The transport object is not initialized by this method, that is, the communication parameters must have been established in the transport object before this method is called. Usually all this is done by the BACCustomer::NewDialog method and therefore there is no need to worry.

If no initialization message was provided by the caller through the aBeginDialogMessage parameter then this method will create its own. The dialog type determines which segments will be included in the initialization message. See BACDialogTypes for more information.

The dialog type also determines whether the property AutoSignature is set to True or False by this method. If it is set to True, then the supplied security object is used to automatically sign all outgoing messages.

In the initialisation reponse, the connected bank may include an update to the BPD. If such an update occurs, the BACBankData object associated with the BACCustomer is automatically updated with the new BPD. The BACBankData::Version property of the BACBankData object can be checked to determine whether the BPD have been updated. Any update will be automatically saved.

The bank may also respond with an update of the user parameters UPD. If such update occurs, the corresponding BACAccountData object is updated and persisted automatically. The BACAccountData::Version property of the BACAccountData object can be checked to determine whether the UPD have been updated.

Optionally, the bank may include short notices (i.e. "HIKIM" segments) in the initialisation reponse. These notices must be presented to the user and must be persistently stored for later reference by the application program. If any such notices are received, they are stored in the BankNotices collection. There is no special return value indicating the reception of bank notices, hence, the application must check the BankNotices collection after completion of the dialog initialisation.

Whenever the dialog initialisation fails, the dialog is automatically terminated before the operation completes. If the dialog was begun successfully, then the method EndDialog must be invoked in order to orderly terminate the dialog.

IBACCustomer* BACDialog::Customer;

This read only property holds a reference of the BACCustomer object that was supplied when this BACDialog object was created.

String BACDialog::CustomerID;

Read-only property that returns the CustomerID (HBCI Kunden ID)that was assigned to the dialog in the BeginDialog call.

Comments

If an empty string was passed to BeginDialog, then this property contains the substituted value, either the UserID or "9999999999" as appropriate to the dialog type.

String BACDialog::DialogID;

String property that holds the current Dialog-ID that was assigned by the bank system during dialog initialisation. Initialised to the literal String "0".

BACDialogTypes BACDialog::DialogType;

Read-only property that indicates the type of the current dialog.

Comments

This property is initialized as bacDialogNone and is set to the requested dialog type by the BeginDialog method. Whenever a dialog is terminated the value of this property is reset to bacDialogNone.

See Also

BACDialogTypes

IBACMessage* BACDialog::EndDialog(
	[in] IBACMessage* aEndDialogMessage);

End dialog.

Parameters

aEndDialogMessage

Termination message that shall be sent during dialog shutdown. This should be "Nothing" to indicate that the termination message shall be created by this method.

Return Value

If a termination message was provided by the caller, then that same message will be returned. If "Nothing" was provided, then the created default termination message is returned.

Comments

This methods terminates the homebanking dialog by sending a dialog termination message to the bank. The caller optionally supplies the actual termination message object through the aEndDialogMessage parameter.

Finally, the transport is physically disconnected.

void BACDialog::ExecuteMessage(
	[in] IBACMessage* aMessage);

Submit the given message online.

Parameters

aMessage

Reference of BACMessage object to submit online.

Comments

The BACDialog must be in the state bacDialogReady when this method is invoked, otherwise an exception will be raised.

The returned "HIRMG" segment is checked and its information is copied into the HBCIResult and HBCIResultCode properties.

The returned "HIRMS" segments are directly associated with each transaction and are therefore stored in the BACTransaction::Acknowledgement property of the corresponding BACTransaction objects.

IBACMessage* BACDialog::ExecuteSegment(
	[in] IBACSegment* aSegment);

Submit the given segment online. Convenience method that takes an OrderSegment packs it into a BACTransaction into a BACMessage and executes it. The result is the BACMessage.

Parameters

aSegment

Reference of BACSegment object to submit online.

IBACMessage* BACDialog::ExecuteSpecial(
	[in] BACSpecialTransactionTypes nTransactionType,
	[in] IBACMessage* aMessage);

Perform a very special online transaction such as user key update or key blocking.

Parameters

nTransactionType

Type of special transaction to perform. The transaction type selects the appropriate behaviour and the default message that is generated when aMessage is Nothing.

aMessage

Optional reference of BACMessage object to submit online. If this is omitted a default message is generated.

Comments

This method is needed because it is not possible to perform some types of online transactions using ExecuteMessage.

For example, it is not possible to update a key by simply invoking ExecuteMessage with a HKSAK segment. the difference is, that the updated key must be made active during the transaction, after the message was sent but before the response was received. If an error is encountered in the response, the new key must not be made active at all.

After all, this method will mostly be used by the "HBCI Kontakte" Control Panel Applet only.

String BACDialog::HBCIResult;

Read only property that provides the HBCI error description for the HBCIResultCode property. This string includes the entire HBCI Acknowledgement.

Long BACDialog::HBCIResultCode;

Read only property that indicates the most recent asynchronously reported HBCI error code of the most recent activity. The HBCI error code is defined as an unsigned value in the range from 0 upto 9999. In addition, the value 10000 will be used to indicate internal errors that cannot be naturally represented as valid HBCI error codes. Such errors are usually related to system or programmer errors.

The HBCIResultCode property is only set when an error is reported asynchronously during background activity. This means that the method that did initiate the background activity did already synchronously return with a success indicator.

Whenever the HBCIResultCode is set, the property HBCIResult may or may not contain additional information that can be presented to the user.

Whenever a method of the BACDialog object is invoked all error properties are cleared first.

See Also

HBCIResult

Long BACDialog::HBCIVersion;

This property holds the HBCI version that this dialog is using. It is initialised to the global bacVersionHBCI when a BACDialog object is created. If an application wants to override this default, it must set this property before invoking BeginDialog.

Comments

The HBCI version number appears in every HBCI message and must not be changed during a dialog. An attempt to write this property in another state than bacDialogIdle will raise an exception.

BACDialogLanguages BACDialog::Language;

This property selects the language to be used for this dialog. It holds a value from the BACDialogLanguages enumeration.

Comments

The initial default value is bacDialogLanguageDefault. An application can choose another language by setting this property before invoking the BeginDialog method.

An application may only choose a language that is actually supported by the HBCI system. The set of supported languages can be determined from the HIBPA segment from the BACBankData object.

Long BACDialog::NextMessageSeqNo;

Long property that holds the next message sequence number that will be assigned by ExecuteMessage. This is initialised to 1 when the BACDialog was created and whenever BeginDialog is invoked. It is incremented each time a message is sent through ExecuteMessage.

BACDialog::OnActivityComplete(
	[in] Long lHBCIResultCode);

This event is fired whenever an asynchronous activity completes with or without error.

Parameters

lHBCIResultCode

Indicates whether the activity completed successfully or not. This value is identical to the property HBCIResultCode.

BACDialog::OnReceiveProgress(
	[in] Long lBytesReceived);

This event is fired periodically while a message is received from the bank. An application may use this event to implement a GUI progress indicator -- although it will have a hard time doing so, because it won't know how much data will be received in total.

Parameters

lBytesReceived

This provides the number of bytes that were already received.

BACDialog::OnSendProgress(
	[in] Long lBytesSent,
	[in] Long lBytesTotal);

This event is fired periodically while a message is transmitted to the bank. An application may use this event to implement a GUI progress indicator.

Parameters

lBytesSent

This provides the number of bytes that were already sent.

lBytesTotal

This provides the total number of bytes that are to be sent during this transmission.

BACDialog::OnStateChange(
	[in] BACDialogStates nNewState);

This event is fired whenever the state of the dialog changes.

Parameters

nNewState

The new state that was entered. If queried, the State property will already indicate that same state.

IBACSecurity* BACDialog::Security;

This read only property holds a reference of the security object that was supplied when this BACDialog object was created. This property may also hold a null reference.

BACDialogStates BACDialog::State;

Read-only state property that indicates the current state of this BACDialog. It is set to one of the values of the BACDialogStates enumeration.

Variant BACDialog::SynchronizationResult;

This read-only property receives the returned result value from a synchronization. The actual type of the returned value depends on the type of the synchronized item.

Long BACDialog::Timeout;

This property defines the response timeout in milliseconds that is applied to all methods that perfom an online message exchange. It is initialised to the default timeout read from the DDBAC option "ResponseTimeout".

Comments

Setting this property will change the timeout for that dialog only, the default value will not be altered. The default value can be changed through the BACBanking::Options property of the BACBanking object. Changing the default value affects all dialogs created thereafter.

IBACTransport* BACDialog::Transport;

This read only property holds a reference of the transport object that was supplied when this BACDialog object was created.

A BACMessage object is the entity of a single online transaction. As such it collects all information that is sent to the homebanking server in a single HBCI message and all information from the corresponding HBCI response message.

Comments

When a BACMessage object is created it must be filled with BACTransaction objects representing the individual homebanking orders. Usually, an application program puts only a single BACTransaction object into the BACMessage, but it is free to use the message to bundle any number of transactions. However, individual banks may restrict the extend of bundling. The actual message limitations imposed by the bank system can be determined through its BPD. That is, through the data of the "HIBPA" segment of the banks BACBankData object (see HBCI IV.2: Number of business transaction types).

After adding the desired transactions to a BACMessage object one or more users may sign these transactions. Once a user signature was added to a message no more modifications are allowed. The number of signatures required can be determined through the BPD parameters for the transaction types contained in the message (see HBCI IV.6: Number of signatures permitted). The property NumSignaturesRequired is initially zero and must be set during the initialisation phase if more than one signature will follow. The default value zero allows zero signatures or a single signature only.

A BACMessage object can be persistently stored in any state. A BACMessage object is stored as a stream of HBCI segments. The first segment in this stream is a DDBAC custom segment that contains the properties State, NumSignaturesRequired, DialogID, SequenceNumber and HBCIVersion. It is followed by the HBCI representation of all other directly or indirectly contained segments. The segments are stored in the following order:

DDMSG   1       State num(..5);
		NumSignaturesRequired num(1);
		Dialogid id;
		SequenceNumber num(..4)
		HBCIVersion num(..3)
HNSHK   0..3    Signatures(i).SignatureHeaderSegment
HK___   0..     Transactions(i).OrderSegment
HNSHA   0..3    Signatures(i).SignatureValueSegment
HIRMG   0..1    Acknowledgement
HIRMS   0..     Transactions(i).Acknowledgement
HI___   0..     Transactions(i).ResponseSegments
HI___   0..     OrphanResponseSegments

Methods and Properties

IBACSegment* BACMessage::Acknowledgement;

Read only property that contains the acknowledgement segment (HIRMG) that was returned for this message. If no acknowledgement was returned, yet, then this property is not available.

Comments

Generally the acknowledgement is only available when the BACMessage is in the bacMessageDone state. In any other state this property won't be available.

Developer Notes

Actually the acknowledgement segment is attached when the raw response message is processed by the hidden private ParseMessageBuffer method.

void BACMessage::AddSignature(
	[in] IBACCustomer* piCustomer,
	[in] IBACSecurity* piSecurity,
	[in] BACSignerRole nSignerRole);

Private method that is used by the BACCustomer object to add its signature to this BACMessage object.

Parameters

piCustomer

BACCustomer object that represents the signer. Information from this object is inserted into the generated signature.

piSecurity

Security component that represents the security media of the person that signs this message and identifies him.

nSignerRole

Determines the role of the signer that signs this message.

Comments

The AddSignature method can be invoked when the BACMessage object is in the bacMessageInit state in order to add the first signature to this message. This will implicitly switch the message into the bacMessageSigned state. If the property NumSignaturesRequired has the value zero when this method is invoked, it is assumed that there will only be this single signature. The property NumSignaturesRequired will be adjusted to one and thus no further signatures will be allowed.

The AddSignature method can also be invoked when the BACMessage object is in the bacMessageSigned state and further signatures are required. That is, the property NumSignaturesRequired has a higher value than the count of signatures in the Signatures collection.

Developer Notes

If this is the first signature then this method will assign sequence numbers to all order segments of the contained transactions. The first transaction receives the sequence number NumSignaturesRequired plus two.

void BACMessage::AddTransaction(
	[in] IBACSegment* piOrderSegment);

Through this method additional transactions can be added to this message.

Parameters

piOrderSegment

BACSegment object that holds the HBCO order segment with the transaction request details. This will be attached to the BACTransaction::OrderSegment property of the new BACTransaction object.

Comments

Transactions can only be added to a message that is in the bacMessageInit state. Once a message was signed no further transactions can be added.

String BACMessage::DialogID;

Read only property that stores the HBCI dialog ID that was assigned to this message when it was executed online. The default value is "0".

IBACMessageBuffer* BACMessage::GenerateMessageBuffer(
	[in] IBACCustomer* piCustomer,
	[in] IBACSecurity* piSecurity,
	[in] Long lHBCIVersion,
	[in] String sDialogID,
	[in] Long lMsgSeqNo,
	[in] Boolean fEncrypt);

Private method that is used by the BACDialog object to extract the eqivalent raw HBCI message from this BACMessage object for the purpose of sending it online.

Parameters

piCustomer

Identifies the customer on who's behalf the message will be sent. Currently this parameter is only needed when the message is encrypted.

piSecurity

Security component that will be used to encrypt the message - if it will be encrypted at all. See fEncrypt.

lHBCIVersion

HBCI version number that shall be inserted into the message header segment (HNHBK). Should always the same as the property HBCIVersion of BACMessage and as property HBCIVersion of BACDialog.

sDialogID

Dialog ID that shall be inserted into the message header segment. This dialog ID is also stored in the DialogID property of this message object. If this is an initialization message than the parameter may be an empty string. In this case the actual dialog ID is adopted from the response message passed to ParseMessageBuffer.

lMsgSeqNo

Message sequence number of this message. The message sequence number counts the messages of a dialog, starting with the sequence number 1 for the first message. A response message must have a matching sequence number, otherwise it will be rejected by ParseMessageBuffer. The message sequence number is also stored in the property SequenceNumber for future reference.

The combination of the DialogID and the SequenceNumber uniquely identify a message of a particular customer. The HBCI status protocol refers to past messages using these two values.

fEncrypt

Boolean flag that selects whether the generated message shall be encrypted or not.

Return Value

Internal message buffer that contains the raw generated HBCI message. The generated message buffer contains the entire HBCI message including message header and trailer. The message body is optionally encrypted.

Comments

This method may be invoked in the bacMessageInit or bacMessageSigned states. If the method is successful, then the BACMessage switches into the bacMessageSent state. The value of the property NumSignaturesRequired must equal the count of signatures in the Signatures collection, otherwise the method fails.

If the message is in the bacMessageInit state then this method will assign sequence numbers to all order segments of the contained transactions. The first transaction receives the sequence number two.

Long BACMessage::HBCIVersion;

Property that defines the HBCI version for this message.

Comments

Initially this property contains the value zero in order to indicate that the HBCI version is not explicitly defined for this message. The HBCI version can be defined by setting this property.

If none is defined, then the HBCI version is derived from the BACCustomer object given to AddSignature. If the BACCustomer object does not define a HBCI version, too, then the default version HBCI 2.0.1 is assumed. If the HBCI version is already explicitly defined when AddSignature is called, then the HBCI version defined in the BACCustomer object is ignored.

Developer Notes

This property is implemented in the IBACMessage2 interface.

Long BACMessage::NumSignaturesRequired;

Number of signatures that must be added to this BACMessage object before the message can be assumed to be complete. The property NumSignaturesRequired is initially zero and must be set during the initialisation phase if more than one signature shall follow. The default value zero allows zero signatures or a single signature only.

Comments

Currently HBCI limits the maximum number of signatures per message to three.

IBACSegments* BACMessage::OrphanResponseSegments;

This BACSegments collection holds all BACSegment objects of response segments that were not associated with a transaction. Initially, when a BACMessage is created, this collection is empty.

Developer Notes

Actually this collection is filled by the hidden private ParseMessageBuffer method.

BACMessageFlags BACMessage::ParseMessageBuffer(
	[in] IBACMessageBuffer* piBuf,
	[in] IBACCustomer* piCustomer,
	[in] IBACSecurity* piSecurity);

Private method that is used by the BACDialog object to hand over the response message to the originating BACMessage object.

Parameters

piBuf

Internal message buffer that contains the raw HBCI response message.

piCustomer

Identifies the customer on who's behalf the message will be received. This customer must be associated with the given piSecurity object.

piSecurity

Security component that will be used to decrypt the message (if it is encrypted at all) and to verify the bank signature (if any).

Return Value

Returns flags that indicate whether the parsed message was encrypted and/or signed. Note that if the message was signed, the signature was successfully verified. If a signature is present that can not be verified, then an error is raised.

Comments

This method must only be invoked in the bacMessageSent state. It parses the given message buffer, adding the contained response segments to the appropriate collections and properties. The message is then automatically switched into the bacMessageDone state.

The given message buffer must contain only the raw message body without bank signature and without message header or trailer segments. It must not be encrypted.

Long BACMessage::SequenceNumber;

Read only property that stores the message sequence number of this message. The sequence number is assigned when the message is transmitted online. Before that it is zero.

IBACSignatures* BACMessage::Signatures;

This BACSignatures collection holds all BACSignature objects (i.e. user signatures) that have been added to this message. Initially, when a BACMessage is created, this collection is empty.

Comments

This collection is an ordered sequence. Each subsequently added signature is added to the front of this sequence, effectively signing not only the message but all previous signatures, too.

The collection itself cannot be modified. Additional signatures can only be added by the BACCustomer::SignMessage method of the BACCustomer object and by automatic signatures of the BACDialog object.

Developer Notes

Actually all signatures must be added through the hidden private AddSignature method.

BACMessageStates BACMessage::State;

Read only property that indicates the current state of this BACMessage object. BACMessageStates enumerates the possible states.

IBACTransactions* BACMessage::Transactions;

This BACTransactions collection holds all BACTransaction objects of this message. Initially, when a BACMessage is created, this collection is empty.

Comments

This collection is an ordered sequence where new transactions are always added at the end of the sequence. The collection itself is read-only. New transactions can only be added by the AddTransaction method.

The BACMessageBuffer stores the raw data of a single (perhaps partial) HBCI message. The stored message data is accessed through an IStream interface implemented by the buffer. The buffer recognises and works with segment boundaries and the message trailer.

The methods of the BACMessageBuffer object allow random access to the message data at any segment boundary. Individual segments can be erased and inserted. Segments can be located by type or number.

The IBACMessageBuffer operations always identify a segment by its index. The index is the position of the segment inside the message buffer. That is, the first segment of the message buffer always has the index zero. The index is not related to the segment number that appears in the segment header of a segment.

Methods and Properties

Developer Notes

The BACMessageBuffer object is an internal object that should only be accessed by service provider components and should never be accessed by application programs directly.

void BACMessageBuffer::CopyToStream(
	[in] Long lBegin,
	[in] Long lEnd,
	[in] IUnknown* piStm);

Copies the indicated range of segments from this message buffer to the given stream.

Parameters

lBegin

Start of range. See the same parameter of CreateStream for a detailed description.

lEnd

End of range. See the same parameter of CreateStream for a detailed description.

piStm

Unknown object that implements the IStream interface.

IUnknown* BACMessageBuffer::CreateStream(
	[in] Long lBegin,
	[in] Long lEnd,
	[in] Long lAccessMode);

Returns an IStream interface through which the buffered message data can be accessed. The message buffer is locked

Parameters

lBegin

Index of the contained segment where the returned stream shall be initially positioned. The returned stream will be positioned at the beginning of that segment. Often this is zero to create a stream that begins with the first segment of the message.

This parameter can have a negative value. In that case it is assumed to be an offset from the end of the message. For example, -1 can be used to designate the last segment.

This parameter can also be LONG_MAX which is taken as a synonym for the count of segments in the buffer. Hence, if LONG_MAX is given, the stream will be positioned at the very end of the message buffer. Of course, this is only useful for appending segments to the buffer. Note that it is not possible to append data to the message buffer if it already contains a message trailer (HNHBS) as its last segment.

lEnd

When the stream shall be created for reading from the message buffer, then this parameter specifies the index of the segment where reading should stop. The returned stream covers all segments starting at lBegin, up to, but excluding lEnd. When the stream shall be created for writing, then this should be LONG_MAX. This parameter can also have negative values in order to specify an offset from the end of the buffer.

The segment designated by lEnd must be the same or after the segment designated by lBegin.

lAccessMode

This parameter selects the desired access mode for the stream. The provided value must be picked from the standard OLE STGM enumeration (see IStorage::CreateStream).

Return Value

Through this out parameter the new stream object is returned. When the method fails, then NULL is returned instead. The caller must invoke QueryInterface() on the returned IUnknown in order to obtain either the IStream or the ISequentialStream interface of the stream object.

When the stream was created for reading, only the Read() method of the IStream interface must be invoked. If the stream was created for writing, only the Write() method must be invoked. All other methods are not implemented and return E_NOTIMPL.

Comments

Returns a stream interface that presents the raw data of a sequence of segments from the message buffer as a single continous byte stream. The actual behaviour of the returned stream object depends on whether the stream was created for reading or writing. Currently only the following values are supported for the parameter lAccessMode:

STGM_READ + STGM_SHARE_EXCLUSIVE

The stream is created for read access only. The message buffer is exclusively locked for the lifetime of the returned stream.

STGM_WRITE + STGM_SHARE_EXCLUSIVE

The stream is created for write access only. The message buffer is exclusively locked for the lifetime of the returned stream.

If the stream was created for reading, then the method ensures that the message length data element of the message header is correct. Hence, the caller no longer needs to care about setting that message length correctly.

If the stream was created for reading then the caller can read the data from the range of segments defined by the lBegin and lEnd parameters. If the end of this range is encountered, IStream::Read returns S_FALSE together with the remaining data.

If the stream was created for writing, then the written data will be inserted in front of the segment selected by the lBegin parameter. The lEnd parameter is ignored. The implementation refuses to write any data beyond a HNHBS (message trailer) segment. An attempt to continue writing into a stream past the final character of a previously written HNHBS is refused by returning S_FALSE from IStream::Write together with the actual number of bytes that were written. If more data is written than the allowed by the MaxLength property, IStream::Write will return STG_E_MEDIUMFULL.

String BACMessageBuffer::DebugGetSegment(
	[in] Long lIndex);

Returns the entire raw segment data from a segment in this message buffer.

Parameters

lIndex

Zero based index of segment that shall be returned.

Return Value

Returns the entire raw segment data inside a string. Note that this data may contain embedded nul characters!

void BACMessageBuffer::DebugSetSegment(
	[in] Long lIndex,
	[in] String sSegmentData);

Explicitly sets the entire raw segment data for a segment in this message buffer.

Parameters

lIndex

Zero based index of segment that shall be set. If this index set to LONG_MAX or equals the total number of segments, then the new segment data will be appended to the end of the buffer.

sSegmentData

Entire raw segment data that shall be set as the new segment data.

void BACMessageBuffer::Decrypt(
	[in] String sHexSessionKey);

Attempts to decrypt the message buffer using the given session key and the 2-Key-Triple-DES algorithm.

Parameters

sHexSessionKey

2-Key-Triple-DES key in hexadecimal representation. This key consists of actually two concatenated 8 byte keys.

Comments

When this function is called the message buffer must contain only a single HNVSD segment with the version number 1 and the sequence number 999. If it contains any other segment then an error is raised.

The data contained in the HNVSD segment is decrypted and replace the HNVSD segment. If the decrypted data cannot be legally dissected into a sequence of HBCI segments then an error is raised.

void BACMessageBuffer::Encrypt(
	[in] String sHexSessionKey);

Encryptes the entire contents of this message buffer using the given session key and the 2-Key-Triple-DES algorithm.

Parameters

sHexSessionKey

2-Key-Triple-DES key in hexadecimal representation. This key consists of actually two concatenated 8 byte keys.

Comments

The encrypted message buffer then contains a single HNVSD segment

void BACMessageBuffer::EraseSegments(
	[in] Long lBegin,
	[in] Long lEnd);

Erases a range of segments from this message buffer.

Parameters

lBegin

Index of the first segment to be erased. As usual, this can be negative. If this index equals the number of segments in the buffer or LONG_MAX, then this method does nothing.

lEnd

Index of the first segment shall not be erased. That is, all segments starting at lBegin up to, but excluding lEnd are erased. As usual, this can be negative. If this is LONG_MAX, then all segments up to the end of the buffer are erased. In order to erase the entire buffer set lBegin to 0 and lEnd to LONG_MAX.

Long BACMessageBuffer::FindSegmentByNumber(
	[in] Long lSegmentNumber);

Scans the message buffer, looking for a segment with the given segment number. If one is found, the index of the segment is returned in the plSegIndex parameter.

Parameters

lSegmentNumber

Segment number as it appears in the segment header. HBCI rules restrict this parameter to the range 1 through 999.

Return Value

Returns the index of the segment found. If no matching segment was found, then this is set to -1.

Long BACMessageBuffer::FindSegmentByType(
	[in] String sSegmentType);

Scans the message buffer, looking for a segment of a given type. Returns the index of the first matching segment.

Parameters

sSegmentType

Segment type as a string. This string is something like "HNHBS", "HIISA", etc.

Return Value

Returns the index of the segment or -1 if no matching segment was found.

String BACMessageBuffer::Hash();

Computes the RIPE-MD 160 Message Digest (Hash value) over the entire contents of this message buffer.

Return Value

Returns the 20 byte hash value in hexadecimal representation (40 hex digits).

Long BACMessageBuffer::Length;

Length of the entire message buffer in bytes (read only). The value is not guaranteed to be meaningful while the message buffer is written to.

Long BACMessageBuffer::MaxLength;

This property can be used to limit the maximum size of the message buffer in bytes (read/write). If this property is set to zero, then there is no limit on the size of the message buffer, other than the amount of available memory.

When the message buffer is constructed the property is initialised to zero.

It is not possible to truncate a buffer by setting a maximum length smaller than the actual length. An attempt to do so will return a failure.

Long BACMessageBuffer::SegmentCount;

Number of segments that are currently stored in this message buffer (read only). The value is not guaranteed to be meaningful while the message buffer is written to.

void BACMessageBuffer::SegmentInfo(
	[in] Long lIndex,
	[in, out] String* psSegmentType,
	[in, out] Long* plSegmentNumber,
	[in, out] Long* plSegmentSize);

Returns information about a particular stored segment.

Parameters

lIndex

Index of the segment to obtain information for.

psSegmentType

Through this string the segment type (Segmentkennung) of the segment is returned. The previous contents of the string is discarded.

plSegmentNumber

Through this long integer the segment number (Segmentnummer) of the segment is returned. The previous contents of the long integer are ignored.

plSegmentSize

Through this long integer the size of the segment in bytes is returned. The previous contents of the long integer are ignored.

The BACMonitor object is a global singleton that receives all diagnostic output from the various DDBAC components. By default it writes all such output to the debugging console using the Win32 API OutputDebugString(). In addition it fires an event whenever it writes a string to the debugging console. Hence, an application can intercept all such output and handle it as needed.

The BACMonitor is only an in-proc singleton, that means, each process gets its own instance. As all DDBAC components are in-proc all output from an application will be funneled through the same monitor. If two applications are run each has its own monitor.

Methods, Properties and Events

BACMonitor::AfterEncryptMessageBuffer(
	[in] IBACMessageBuffer* piMsgBuf);

This event is fired after a message buffer was encrypted. The message now contains nothing but the HNVSK and the HNVSD segment.

Parameters

piMsgBuf

Message buffer.

BACMonitor::AfterSignMessageBuffer(
	[in] IBACMessageBuffer* piMsgBuf);

This event is fired after a signature was added to a generated message. At this time no message header or trailer is in the buffer. The generate signature header is the first segment in the buffer. The new signature trailer is the last segment in the buffer. This event is fired for each signature that is added to the message buffer.

Parameters

piMsgBuf

Message buffer.

BACMonitor::BeforeEncryptMessageBuffer(
	[in] IBACMessageBuffer* piMsgBuf);

This event is fired before a message buffer is encrypted. All data that will be encrypted is in the message buffer.

Parameters

piMsgBuf

Message buffer.

BACMonitor::BeforeSignMessageBuffer(
	[in] IBACMessageBuffer* piMsgBuf);

This event is fired before a signature is added to a generated message. At this time no message header or trailer is in the buffer. The BeforeSignMessageBuffer event is fired after the signature header was added to the message, thusm immediately before the actual signature is computed.

Parameters

piMsgBuf

Message buffer.

BACMonitor::BeforeTransmitMessageBuffer(
	[in] IBACMessageBuffer* piMsgBuf);

This event is fired immediately before a message buffer is transmitted. The message buffer contains the entire message exactly as it will be sent over the wire.

Parameters

piMsgBuf

Message buffer.

BACMonitor::OnTrace(
	[in] String sText);

This event is fired whenever something is traced.

Parameters

sText

Text string to be traced.

BACMonitor::OnTracePerformance(
	[in] Long lEntry,
	[in] Long lBeforeSend,
	[in] Long lAfterReceive,
	[in] Long lExit);

This event is fired whenever performance data of the most recent message exchange is traced.

The performance data is collected by the internal execute message routine that is used from BACDialog::BeginDialog, BACDialog::ExecuteMessage, and BACDialog::EndDialog. The performance data consists of four millisecond timestamps taken during the executing of the message.

Parameters

lEntry

System timestamp in milliseconds taken immediately at the entry to the internal execute message routine.

lBeforeSend

System timestamp taken immediately before the constructed message buffer is passed to the transport object for transmission.

lAfterReceive

System timestamp taken immediately after the response message buffer was returned from the transport object.

lExit

System timestamp taken immediately before the internal execute message routine returns.

Comments

The difference between lBeforeSend and lEntry reflects the internal processing time needed to construct the binary message buffer, including any signature and ciphering.

The difference between lBeforeSend and lAfterReceive reflects the time required for transmitting the message and receiving the response.

The difference between lAfterReceive and lExit reflects the internal processing time needed to evaluate the binary message buffer containing the response, including any signature verification and de-ciphering.

void BACMonitor::Trace(
	[in] Long lSeverity,
	[in] String sText);

Trace the given text string.

Parameters

lSeverity

Severity level (reserved parameter that should be zero).

sText

Text that shall be traced.

The purpose of the BACSegment class is to scan, create, manage, and store HBCI message segments. Hence, the BACSegment object is the work horse of the BAC. BACSegment objects are often used as subordinate objects or method parameters and therefore have a key role in the BAC architecture. Understanding the BACSegment object is vital to successful use of the BAC.

From the point of view of the application programmer, a BACSegment is primarily a collection of related named data items. The implementor of the BACSegment class, however, usually focuses on its relation to the HBCI message segment.

The BACSegment object supports the IBACTransmogrify interface. Syntax for XML is generated by the BACSyntax element names.

Example of an HIRMS Segment as XML

<SEGMENT TYPE="HIRMS" VERSION="2" SEQNO="4" REFSEQNO="3">
	<Rueckmeldung>
		<Code>9210</Code>
		<Bezugsdatenelement>3,3</Bezugsdatenelement>
		<Text>BLZ existiert nicht</Text>
	</Rueckmeldung>
</SEGMENT>

Methods and Properties

Variant BACSegment::Item([in] Variant vGroup, [in] Variant vElement);

This indexed property can be used to retrieve or assign data element values of this segment. This is the default property of the segment class.

Comments

The type of the accessed element is a Variant in order to be capable of holding any type of element. The mapping of the actual Variant type of the element to the HBCI types is documented in "DataDesign HBCI Banking Application Components (DDBAC)".

Parameters

vGroup

Name (String) or position (Long) of group. This is the primary index.

In order to be consistent with the HBCI specification, the first accessible data element has the index number 2. The segment header (which would have the index number 1) is not accessible through this property. The BACSegment class has special directly accessible properties to hold the data elements of the segment header.

vElement

Optional name (String) or position (Long) of DE within DEG. If this is omitted, then the first, perhaps also the only, element of a DEG will accessed.

The first element of a DEG has the numeric index 1.

Long BACSegment::RefSeqNo;

This property holds the sequence number of that this segment refers to. If no sequence number is available the result is 0.

Long BACSegment::SeqNo;

This property holds the sequence number of the segment within a message. The DDBAC initialise this property when building or scanning a HBCI message.

void BACSegment::SetValue(
	[in] String sGroupName,
	[in] Long lGroupPos,
	[in] String sElementName,
	[in] Long lElementPos,
	[in] Variant vValue);

Explicitly set a data element with all its keys.

Parameters

sGroupName

Optional name of group. If this is the empty string, then the group is not named.

lGroupPos

Optional position of group. If this is zero, then the group position is assumed to be unknown.

sElementName

Optional name of element. If this is the empty string, then the element is not named.

lElementPos

Optional position of element. If this is zero, then the element position is assumed to be unknown.

vValue

Value to assign to the given keys.

String BACSegment::Type;

This property defines the type of the segment. It holds the segment name string, for example, "HIUPD", etc...

Long BACSegment::Version;

This property defines the version of the segment. This is usually of no concern to the application programmer.

The BACSegments object is an OLE Automation Collection that holds an ordered sequence of BACSegment objects.

The collection is a persistent object that implements the IBACPersistentObject base interface. Thus the entire collection can be persisted in a single stream or file. The persistent data stream is a continous sequence of HBCI segments.

The segments in the collection can be adressed solely through their numerical index. The first segment has the index zero, the last segment has the index Count-1. Various methods for finding segments with specific attributes exist. All these methods return the index position of the first matching segment that was found in the collection or -1 if nothing was found.

Methods and Properties

void BACSegments::Add(
	[in] IBACSegment* piSegment,
	[in] Long lBeforeIndex);

Add another BACSegment object to this collection.

Parameters

piSegment

Reference of BACSegment object that shall be added to the collection. Each added reference must be unique within the collection, in other words, the same BACSegment object must not be added twice.

lBeforeIndex

Optionally the position where the segment shall be inserted into the collection can be supplied by the caller. If this index is -1 (its default value) then the segment will be added to the end of the collection.

void BACSegments::Clear();

Removes all BACSegment objects from this collection.

Long BACSegments::Count;

Read only property that provides the number of BACSegment objects in this collection.

Long BACSegments::FindSegment(
	[in] IBACSegment* piSegment);

Finds a particular instance of a BACSegment object inside the collection.

Parameters

piSegment

Reference of BACSegment object that exists in this collection. This reference is compared to each contained BACSegment object reference. The index of the first matching object will be returned.

Return Value

If the segment was found its index is returned. If no matching segment is found then -1 is returned.

Long BACSegments::FindSegmentSeqNo(
	[in] Long lSeqNo);

Finds a segment that has a particular sequence number inside the collection.

Parameters

lSeqNo

Sequence number of the segment to look for. The value is compared to the BACSegment::SeqNo property of each contained BACSegment.

Return Value

If the segment was found its index is returned. If no matching segment is found then -1 is returned.

Long BACSegments::FindSegmentType(
	[in] String sType,
	[in] Long lVersion);

Finds a segment of a particular type and version inside the collection.

Parameters

sType

Type of segment to look for. This string is compared to the BACSegment::Type property of each contained BACSegment.

lVersion

Version of the segment to look for. If this is zero (the defaultvalue) then any version of the requested segment type is accepted. Otherwise the value is compared to the BACSegment::Version property of each contained BACSegment.

Return Value

If the segment was found its index is returned. If no matching segment is found then -1 is returned.

IBACSegment* BACSegments::Item([in] Long lIndex);

The Item property provides indexed access BACSegment objects stored in this collection. The Item property is the default value of the BACSegments object.

Parameters

lIndex

The individual BACSegment objects stored in this collection can be directly accessed using their positional index in the collection. The first segment has the index zero, the last segment has the index Count-1.

void BACSegments::Remove(
	[in] Long lIndex);

Remove BACSegment object from collection.

Parameters

lIndex

Index of BACSegment object to be removed from this collection. This must be in the range from zero to Count-1.

Comments

Note that the index of every segment inside the collection may change as a result of this call.

Instances of the BACSepaMessage coclass represent a Sepa message.

A BACSepaMessage object can be created directly.

Methods and Properties

IBACSepaOrder BACSepaMessage::Add();

Add a BACSepaOrder object to this transaction.

BSTR BACSepaMessage::Descriptor;

Get the sepa pain Descriptor of this transaction.

DATE BACSepaMessage::ExecutionDate;

The execution date of this transaction.

IBACAccount BACSepaMessage::FromAccount;

Set or get the ordering BACAccount.

If the SepaMessage is attached to a BACSegment, the segments "Auftraggeberkontoverbindung" will be filled with the account data too.

BSTR* BACSepaMessage::GetValue();

Gets a value inside the sepa pain message xml.

Boolean BACSepaMessage::IsIBANValid();

Validates the IBAN.

void BACSepaMessage::LoadXML();

Loads an external sepa pain message.

IBACSepaOrders* BACSepaMessage::Orders;

BACSepaOrders of all orders segments of this transaction.

IBACAccount BACSepaMessage::Recipient;

Get or set the Recipient of this order.

void BACSepaMessage::Remove(
	[in] Long lIndex);

Remove BACSepaOrder object from collection.

Parameters

lIndex

Index of BACSepaOrder object to be removed from this collection. This must be in the range from zero to Count-1.

IBACSegment BACSepaMessage::Segment;

Attaches this SepaMessage to a BACSegment.

If the BACSegment is an order segment:

The properties set in this BACSepaMessage will create a Sepa Pain Message Xml which will be filled into the segments "SEPAPainMessage" field. The SEPADesriptor will be filled with the selected SEPA Descriptor.

If the BACSegment is an response segment:

The properties in this BACSepaMessage can be used to retrieve data from the Sepa Pain Message.

BSTR BACSepaMessage::SetValue();

Sets a value inside the sepa pain message xml.

BSTR* BACSepaMessage::Verify();

Validate the inside sepa pain message.

Returns S_OK and an empty String in Reason if the verification succeeds. Returns S_FALSE if the verfication fails, and the error description from the MSXML implementation (not end-user conform). Returns an Error if the currently installed MSXML does not support schema verification. (i.E: Windows 2000, Windows 98)

BSTR BACSepaMessage::xml;

Get the sepa pain formatted xml of this transaction.

Instances of the BACSepaOrder coclass represent a particular order inside a Sepa transaction.

A BACSepaOrder object can be created directly or found by using the Orders collection in the BACSepaTransaction object.

Methods and Properties

CURRENCY BACSepaOrder::Amount;

This field holds the actual transaction amount. If the transaction is a debit transaction or a reversal of credit transaction, then this value is negative.

Comments

The property CurrencyCode in the BACSepaOrder interface provides the currency code to this amount.

BSTR BACSepaOrder::CurrencyCode;

This is the currency code of this order.

BSTR* BACSepaOrder::GetValue(
	[in] BSTR sPath);

Gets a value inside the sepa pain order xml.

Parameters

sPath

The xpath that contains the desired value. For Example: "/DrctDbtTx/MndtRltdInf/MndtId"

Return Value

The value or an empty string if the tag does not exist.

IBACSepaMessage BACSepaOrder::Message;

Get the BACSepaMessage, which this order belongs too.

BSTR BACSepaOrder::Purpose;

Get or set the sepa pain formatted Purpose of this order.

BSTR BACSepaOrder::SetValue(
	[in] BSTR sPath,
	[in] BSTR sValue);

Sets a value inside the sepa pain order xml.

Parameters

sPath

The xpath that should contain the given value. The tag is created if it does not exist. The tag will be created at the schema location for this tag. For Example: "/DrctDbtTx/MndtRltdInf/MndtId"

sValue

The value to be set

IBACAccount BACSepaOrder::ToAccount;

Set or get the BACAccount recipient.

BSTR BACSepaOrder::xml;

Get or set the sepa pain formatted xml of this order.

The BACSepaOrders object is an OLE Automation Collection that holds an ordered sequence of BACSepaOrder objects.

The orders in the collection can be adressed solely through their numerical index. The first segment has the index zero, the last segment has the index Count-1. Various methods for finding segments with specific attributes exist. All these methods return the index position of the first matching segment that was found in the collection or -1 if nothing was found.

Methods and Properties

void BACSepaOrders::Clear();

Removes all BACSepaOrder objects from this collection.

Long BACSepaOrders::Count;

Read only property that provides the number of BACSegment objects in this collection.

BACSepaOrder* BACSepaOrders::Item([in] Long lIndex);

The Item property provides indexed access BACSegment objects stored in this collection. The Item property is the default value of the BACSegments object.

Parameters

lIndex

The individual BACSepaOrder objects stored in this collection can be directly accessed using their positional index in the collection. The first segment has the index zero, the last segment has the index Count-1.

The BACSignature object represents a single user signature in the context of the BACMessage::Signatures collection of the BACMessage object.

Comments

A BACSignature object cannot be explicitly created by an application. It is implicitly created when a new signature is added to the BACMessage by BACCustomer::AddSignature or the BACDialog object.

Methods and Properties

IBACSegment* BACSignature::SignatureHeaderAcknowledgement;

Read only property that contains the acknowledgement segment (HIRMS) that was returned for the signature header of this signature. If no corresponding acknowledgement was returned, then this property is null.

IBACSegment* BACSignature::SignatureHeaderSegment;

Read only property that contains the signature header segment (HNSHK) of this segment.

IBACSegment* BACSignature::SignatureValueAcknowledgement;

Read only property that contains the acknowledgement segment (HIRMS) that was returned for the signature value of this signature. If no corresponding acknowledgement was returned, then this property is null.

IBACSegment* BACSignature::SignatureValueSegment;

Read only property that contains the signature value segment (HNSHA) of this segment.

The BACSignatures object is an OLE Automation Collection that holds an ordered sequence of BACSignature objects. It appears in the BACMessage::Signatures property of the BACMessage object.

Methods and Properties

Long BACSignatures::Count;

Read only property that provides the number of BACSignature objects in this collection.

Long BACSignatures::FindSignatureHeaderSeqNo(
	[in] Long lSeqNo);

Finds a signature that has an BACSignature::SignatureHeaderSegment with a particular sequence number.

Parameters

lSeqNo

Sequence number of the BACSignature::SignatureHeaderSegment to look for. The value is compared to the BACSegment::SeqNo property of each contained BACSignature::SignatureHeaderSegment.

Return Value

If the signature was found its index is returned. If no matching signature is found then -1 is returned.

Long BACSignatures::FindSignatureValueSeqNo(
	[in] Long lSeqNo);

Finds a signature that has an BACSignature::SignatureValueSegment with a particular sequence number.

Parameters

lSeqNo

Sequence number of the BACSignature::SignatureValueSegment to look for. The value is compared to the BACSegment::SeqNo property of each contained BACSignature::SignatureValueSegment.

Return Value

If the signature was found its index is returned. If no matching signature is found then -1 is returned.

IBACSignature* BACSignatures::Item([in] Long lIndex);

The Item property provides indexed access BACSignature objects stored in this collection. The Item property is the default value of the BACSignatures object.

Parameters

lIndex

The individual BACSignature objects stored in this collection can be directly accessed using their positional index in the collection. The first signature has the index zero, the last signature has the index Count-1.

This object is the entry point of syntax description with the DDBAC. You can use all objects with the prefix "BACSyntax" to get and set a description of the syntax of the HBCI segments.

At a starting point you need always a BACSyntax object. With the BACSyntax object you can set a new segment syntax with BACSyntax::Add or you get an existing segment syntax with BACSyntax::FindSegment. BACSyntax::FindSegment returns a BACSyntaxSegment object, this represents the whole description of a HBCI segement. The property BACSyntaxSegment::SyntaxElements of the BACSyntaxSegment object gives you access to the BACSyntaxElements object. The BACSyntaxElements object is a collection of BACSyntaxElement objects.

The syntax object model:

BACSyntax
	BACSyntaxSegment
		BACSyntaxElements
			BACSyntaxElement
			BACSyntaxElement
			BACSyntaxElement
			....
	BACSyntaxSegment
		BACSyntaxElements
			BACSyntaxElement
			....
	....

Methods and Properties

void BACSyntax2::AddSchema(
	String sName,
	Long lVersion,
	String sSchema,
	String sSegmentDescription);

Adding a new syntax description to the BACSyntax collection. New syntax will be used instead of the standard elements. The major key is the BACSyntaxSegment::Name, BACSyntaxSegment::Version pair. So you can overwrite the syntax of an existing segment by adding a new BACSyntaxSegment object with the same name and version as the existing.

Parameters

sName

Type of new Segment correspond to BACSyntaxSegment::Name.

lVersion

Version of new Segment correspond to BACSyntaxSegment::Version.

sSchema

Schema of new Segment, format of this schema is not documented. At beginning with version 2.2.1 of DDBAC SDK there will be a new tool for definig custom segments.

sSegmentDescription

Description string of new segment correspond to BACSyntaxSegment::Description. Parameter is optional.

void BACSyntax::Add(
	BACSyntaxSegment newSyntaxSegment);

Adding a new syntax description to the BACSyntax collection. New syntax will be used instead of the standard elements. The major key is the BACSyntaxSegment::Name, BACSyntaxSegment::Version pair. So you can overwrite the syntax of an existing segment by adding a new BACSyntaxSegment object with the same name and version as the existing.

Parameters

newSyntaxSegment

The new syntax. You can create a new object from scratch or modify an existing.

void BACSyntax::Clear();

Removes all added syntax segments. Standard elements can not be removed (standard elements are elements from the Dat-file).

String BACSyntax::ConvertFormat(
	BACFormatType typ);

It is just a helper method for converting the enum in a readable String. For example BACFormatNumeric is converted to "Numeric".

Parameters

typ

Enum value which should be converted.

Return Value

The String of the format. For example "Numeric".

String BACSyntax::FileName;

No longer supported. Raises an E_NOTIMPL exception.

BACSyntaxSegment BACSyntax::FindSegment(
	String strName,
	Long lVersion);

Searching for a segment in the collection. First will be searched at the new segments (added with Add), then at the segments stored in the file FileName.

Parameters

strName

Name of the segment (see BACSyntaxSegment::Name).

lVersion

Version of the segment (see BACSyntaxSegment::Version).

Return Value

Returns an reference on the BACSyntaxSegment object. If segment is not existing, no object will be returned.

Long BACSyntax::FindSegmentVersion(
	String strName,
	Long lHBCIVersion);

Searching for the segment version in a specific HBCI version.

Parameters

strName

Name of the segment (see BACSyntaxSegment::Name).

lHBCIVersion

HBCI version of the segment (see BACSyntaxSegment::HBCIVersion)..

Return Value

Returning the version of the segment in this HBCI version. Is the segment not present in the HBCI version, the value -1 is returned.

Long BACSyntax::MajorFileVersion;

No longer supported. Raises an E_NOTIMPL exception.

Long BACSyntax::MinorFileVersion;

No longer supported. Raises an E_NOTIMPL exception.

void BACSyntax::Remove(
	String strName,
	Long lVersion);

Removes the syntax segment if it was added. Standard elements can not be removed (standard elements are elements from the Dat-file "ddHBCI.DAT").

Parameters

strName

Name of the segment (see BACSyntaxSegment::Name).

lVersion

Version of the segment (see BACSyntaxSegment::Version).

The BACSyntaxElement object is the elementary object of the DDBAC segment syntax description objects. It describes a new atomic syntax element. A complete segment syntax uses a sequence of BACSyntaxElement objects to define the segment.

The BACSyntaxElement object is a passive property container with no methods. The sum of the individual properties define the syntax requirements of the data element.

Methods and Properties

String BACSyntaxElement::Delimiter;

Delimiter between this and the next element. The delimiter dependence on the format. Is the format bacFormatDEG then the delimiter is the seperate character after the DEG this can only be a "+" or "'". All other tuples (GD and GDG) must be delimited with a colon ":".

As delimiter is "+", "'" and ":" legal.

BACFormatType BACSyntaxElement::Format;

Defines the data type of the element. The possible values are enumerated as BACFormatType. If the data type is BACFormatObject then the property ObjectClass further identifies the class of the object.

Long BACSyntaxElement::MaxCount;

The Count field indicates how often the DEG, DE, GD, or GDG must be iterated (lower bound - MinCount) and may be iterated (upper bound - MaxCount). In such, it implies whether the element is optional or mandatory. If MinCount is 0, then the element is completely optional. If element is required then MinCount must be at least 1.

MaxCount is not optional so if HBCI gives no upper bound specify maximal value is 2097152.

Long BACSyntaxElement::MaxLength;

Specify the maximum length of the data element or the number of data elements in a group (DEG).

MaxLength is not optional so if HBCI gives no upper bound specify maximal value of type Long, this is 2147483647.

Lenght at normal format:

Format is bacFormatAlphanumeric. MinLength is 1 and MaxLength is 6 so the bounds are 1..6. The element must contain at least one element, up to six. A possible value is "HKUEB".

Length at a group format:

Format is bacFormatDEG. MinLength and MaxLength should be equal. MinLength and MaxLength contains the nummer of GD elements in the DEG. The correct value for the DEG "Segementkopf" is 4 for MinLenght and 4 for MaxLength.

Long BACSyntaxElement::MinCount;

Represents the count of repetition of the element in the segment. If MinCount is zero then the element is optional. See also MaxCount.

Long BACSyntaxElement::MinLength;

Specify the length of the format. For more details see MaxLength.

String BACSyntaxElement::Name;

Name of the data element that can be used to access an instance of this element through the BACSegment object. The name is also useful for generating readable parser/generator error messages.

Value examples are "Segmentkopf", "Segmentkennung" and "BPDVersion".

The property Name can consist of any printable characters, except whitespace. It must not end with a trailing digit.

String BACSyntaxElement::ObjectClass;

The Format proptery must have the value bacFormatObject. Contains the class name of the object for parsing and generating the HBCI message. You can support your own class for parsing and generating a HBCI message if you change this property. Your class has to implement the interface IPersistStream. IPersistStream is not an automation interface so this class can not be coded in VB. The parser calls IPersitStream::Load and the generator IPersisStream::Save.

At the moment the DDBAC defines this classes:

The BACSyntaxElements object is a collection object that contains BACSyntaxElement objects. The collection offers methods for creating a new syntax or changing the existent. You can find a BACSyntaxElement object by using one of the find methods.

Example

Changing the syntax of a BACSyntaxElements object

Dim Syntax	 As New BACSyntax
Dim seg      As BACSyntaxSegment
Dim elements As BACSyntaxElements
Dim elm      As BACSyntaxElement

Set seg = Syntax.FindSegment("HIAUBS", 3)
Set elements = seg.SyntaxElements

For Each elm In elements
	' don't change the group
	If Not elm.Format = bacFormatDEG Then
		elm.Format = bacFormatText
	End If
Next

' replacing the old syntax by the new
Syntax.Add seg

Methods and Properties

BACSyntaxElement BACSyntaxElements::Add(
	String sName,
	BACFormatType nFormatType,
	Long lMinLength,
	Long lMaxLength,
	Long lMinCount,
	Long lMaxCount,
	String strDelimiter,
	String strObjectClass);

Add a new BACSyntaxElement object at the end of the collection and return a reference of the new object. The new BACSyntaxElement object is initalized with all properties given by the method.

Parameters

sName

The name of the syntax element (see BACSyntaxElement::Name).

nFormatType

The format of the syntax element (see BACFormatType).

lMinLength

The minimal length of the syntax element (see BACSyntaxElement::MinLength).

lMaxLength

The maximal length of the syntax element (see BACSyntaxElement::MaxLength).

lMinCount

The minmal count of the syntax element (see BACSyntaxElement::MinCount).

lMaxCount

The maximal count of the syntax element (see BACSyntaxElement::MaxCount).

strDelimiter

The delimiter of the syntax element (see BACSyntaxElement::Delimiter).

strObjectClass

The type of the object of the syntax element (see BACSyntaxElement::ObjectClass).

Return Value

Returns an reference on the new object.

BACSyntaxElement BACSyntaxElements::AddNew();

Add a new BACSyntaxElement object at the end of the collection and returning a reference of the new object. The new object is empty and should be initalized.

void BACSyntaxElements::Clear();

All BACSyntaxElement objects will be destroyed.

Long BACSyntaxElements::Count;

Count of all BACSyntaxElement objects in the collection.

BACSyntaxElement BACSyntaxElements::FindElementByName(
	String sName);

Looking for an BACSyntaxElement object in the collection (see also FindElementByPos).

Parameters

sName

Name of element looking for.

Return Value

Returns an reference on the BACSyntaxElement object. If element is not existing, no object will be returned.

BACSyntaxElement BACSyntaxElements::FindElementByPos(
	Long lGroup,
	Long lElement);

Searching for an element in the collection.

Parameters

lGroup

Position of the group. Index for 1st group is 1. The first group is the Segmenthead (Segmentkopf).

lElement

Position of the element in the group. Index for 1st GD is 1. The default value is 0. If lElement is 0 then there is no DEG element and the DE element is returned or it is a DEG group and the specifier of the DEG is returned

Return Value

Returns an reference of the BACSyntaxElement object. If element is not existing, no object will be returned.

Example

Searching for "Segmentkopf"

Dim Syntax	As New BACSyntax
Dim Seg		As BACSyntaxSegment
Dim Elem		As BACSyntaxElement

Set Seg = Syntax.FindSegment("HKVVB", 2)

Set Elem = Seg.SyntaxElements.FindElementByPos(1)
' Elem.Name should be "Segmentkopf"

Set Elem = Seg.SyntaxElements.FindElementByPos(1,1)
' Elem.Name should be "Segmentkennung"

IBACSyntaxElement* BACSyntaxElements::Item;

The Item property provides indexed access to the BACSyntaxElement objects stored in this collection. The Item property is the default value of the BACSyntaxElements object.

Parameters

lIndex

The individual BACSyntaxElement objects stored in this collection can be directly accessed using their positional index in the collection. The first element has the index zero, the last element has the index -1.

This object holds all information about the syntax of one HBCI segment. In the property SyntaxElements is the syntax stored and the rest of the properties give some additional information. The key to distinguish between two segments are the properties Name and Version this mus be unequivocal.

Methods and Properties

String BACSyntaxSegment::Description;

Description of the segment. Examples are "Auslandsueberweisung", "Verarbeitungsvorbereitung" and "Identifikation".

String BACSyntaxSegment::Name;

Name of the segment, it is the short mark of HBCI segments. Examples are "HKAUB", "HKVVB" and "HKIDN".

BACSyntaxElements BACSyntaxSegment::SyntaxElements;

The syntax elements which represend the actual syntax. For more information see BACSyntaxElements.

String BACSyntaxSegment::Version;

HBCI version of this segment.

The BACTransaction object encapsulates the details of a single homebanking transaction. A BACTransaction object can only appear inside the BACMessage::Transactions collection of the BACMessage object. It cannot be instantiated on its own.

Methods and Properties

IBACSegment* BACTransaction::Acknowledgement;

This is the HIRMS BACSegment that was replied by the bank for this transaction. If the transaction was not submitted, yet, then this is an empty object.

IBACSegment* BACTransaction::OrderSegment;

This is a BACSegment object that holds the parameters for this transaction.

IBACSegments* BACTransaction::ResponseSegments;

This BACSegments collection holds all reponse data segments that were returned for this transaction. If no response data was returned (yet) then this is an empty collection.

The BACTransactions object is an OLE Automation Collection that holds an ordered sequence of BACTransaction objects. It appears only in the BACMessage::Transactions property of the BACMessage object.

Methods and Properties

Long BACTransactions::Count;

Read only property that provides the number of BACTransaction objects in this collection.

Long BACTransactions::FindTransaction(
	[in] IBACTransaction* piTransaction);

Finds a particular instance of a BACTransaction object inside the collection.

Parameters

piTransaction

Reference of BACTransaction object that exists in this collection. This reference is compared to each contained BACTransaction object reference. The index of the first matching object will be returned.

Return Value

If the Transaction was found its index is returned. If no matching Transaction is found then -1 is returned.

Long BACTransactions::FindTransactionSeqNo(
	[in] Long lSeqNo);

Finds a transaction that has an BACTransaction::OrderSegment with a particular sequence number.

Parameters

lSeqNo

Sequence number of the BACTransaction::OrderSegment to look for. The value is compared to the BACSegment::SeqNo property of each contained BACTransaction::OrderSegment.

Return Value

If the transaction was found its index is returned. If no matching transaction is found then -1 is returned.

Long BACTransactions::FindTransactionType(
	[in] String sType,
	[in] Long lVersion);

Finds a transaction of a particular type and version inside the collection.

Parameters

sType

Type of BACTransaction::OrderSegment to look for. This string is compared to the BACSegment::Type property of each contained transactions's BACTransaction::OrderSegment.

lVersion

Version of the BACTransaction::OrderSegment to look for. If this is zero (the defaultvalue) then any version of the requested segment type is accepted. Otherwise the value is compared to the BACSegment::Version property of each contained transactions's BACTransaction::OrderSegment.

Return Value

If the transaction was found then its index is returned. If no matching transaction is found then -1 is returned.

IBACTransaction* BACTransactions::Item([in] Long lIndex);

The Item property provides indexed access BACTransaction objects stored in this collection. The Item property is the default value of the BACTransactions object.

Parameters

lIndex

The individual BACTransaction objects stored in this collection can be directly accessed using their positional index in the collection. The first transaction has the index zero, the last transaction has the index Count-1.

String IBACBankInfo::FindBIC(
	String sIBAN,
	Bool pfGood);

Searches the BLZ-Database for a specific BIC.

Parameters

sIBAN

The IBAN or BLZ to search the BIC for

pfGood

Checks the publishing date of the database and returns false, if the database is older than 3 months. In this case, the database file (DDBACBLZ.dll) should be updated.

Return Value

Returns the BIC or an empty string if the BIC cannot be found.

Developer Notes

The database contains records for german "DE" IBANs, all other countrycodes will return an empty string.

String IBACBankInfo::GenerateIBAN(
	String bstrCountryCode,
	String bstrValue1,
	String bstrValue2,
	String bstrValue3,
	String bstrValue4);

Generates an IBAN.

If this method is used to generate IBANs, the end user must be warned, that the results must be verified. In Germany only the account-holding bank can submit the valid IBAN.

Parameters

bstrCountryCode

The Countrycode to generate an IBAN

bstrValue1

Depends on the Countrycode, usually contains the Bankcode

bstrValue2

Depends on the Countrycode, usually contains the Accountnumber

bstrValue3

Depends on the Countrycode, usually contains the Branchcode

bstrValue4

Depends on the Countrycode

The parameters are used as follows:

Country Value1           Value2           Value3          Value4
DE      Bankleitzahl(8)  Kontonummer(10)

Return Value

Returns the generated IBAN.

Boolean IBACBankInfo::IsIBANValid(
	[in] String sIBAN);

Validates an IBAN.

Parameters

sIBAN

The IBAN to be validated.

Return Value

Returns true if the checksum of the IBAN is valid.

The interface IBACCardTerminal is the generic base interface that must be implemented by all DDBAC compliant smart card terminal provider objects. It defines a complete set of generic smart card terminal operations.

A card terminal object can be in one of three states: "Closed", "Opened", "ICC". Any raised error will return the object into the "Closed" state.

Comments

The Implementation based on the CT-API recogizes the "Eutelis" specification for HBCI compliant smart card terminals as the minimum set of required functionality.

Any errorneous CT-API return values (other than zero) are indicated in the HRESULT as OLE Automation exceptions. The designated return value parameter is used to carry the status word (SW1:SW2).

Methods and Properties

Developer Notes

The IBACCardTerminal interface defines the internal interface to a card terminal provider component. It should never be accessed by application programs directly.

String IBACCardTerminal2::DriverVersion;

Returns the smartcard reader version if available.

BACSmartcardState IBACCardTerminal2::SmartcardState;

Property that informs about smartcard state at chipdrive. See description of states at BACSmartcardState.

Long IBACCardTerminal3::PerformChangePin(
	[in] String sHexCommandTemplate);

Performs card reader local PIN entry and verification.

Parameters

sHexCommandTemplate

Template of verification command string in hexadecimal representation. The locally entered PIN will be inserted into this template before the command is sent to the smart card. This value will be passed directly to the CT-BCS implementation.

Return Value

Status word (SW1:SW2) that was returned in the response data. The status word value 0x16400 means that the PIN input timed out. The value 0x16401 means that the user aborted the PIN input by pressing cancel on the card reader. Any other return values are the actual status word from the smart card.

Comments

If the user aborts locally at the card reader, or the PIN entry times out, then an exception with an appropriate display text is raised.

If the card reader does not support local PIN entry, then the exception E_NOTIMPL is raised. The caller is responsible for using another way of verification then.

See Also

CardTerminal Basic Command Set (CT-BCS) specification, Version 1.0, 15. April 1999.

Long IBACCardTerminal3::PerformVerification(
	[in] String sHexCommandTemplate,
	[in] Long nInsertionPosition,
	[in] Long nLengthOfPIN,
	[in] Long nPINCoding);

Performs card reader local PIN entry and verification.

Parameters

sHexCommandTemplate

Template of verification command string in hexadecimal representation. The locally entered PIN will be inserted into this template before the command is sent to the smart card. This value will be passed directly to the CT-BCS implementation.

nInsertionPosition

Position in command template where the locally entered PIN shall be inserted. This value must be in the range 0 through 255 and will be passed directly to the CT-BCS implementation.

nLengthOfPIN

Length of PIN to prompt for. This must be in the range 0 through 15. The value will be passed directly to the CT-BCS implementation.

nPINCoding

Normally the value 2 is used, see CT-BCS reference for detailed information.

Return Value

Status word (SW1:SW2) that was returned in the response data. The status word value 0x16400 means that the PIN input timed out. The value 0x16401 means that the user aborted the PIN input by pressing cancel on the card reader. Any other return values are the actual status word from the smart card.

Comments

If the user aborts locally at the card reader, or the PIN entry times out, then an exception with an appropriate display text is raised.

If the card reader does not support local PIN entry, then the exception E_NOTIMPL is raised. The caller is responsible for using another way of verification then.

See Also

CardTerminal Basic Command Set (CT-BCS) specification, Version 1.0, 15. April 1999.

Boolean IBACCardTerminal3::SupportsVerification;

Indicates whether the attached card reader device actually supports local pin verification through the PerformVerification method. The property is False if local verification is not supported and PerformVerification would raise E_NOTIMPL.

BACSmartcardState IBACCardTerminal4::RequestForSmartcard(
	[in] String sDescription);

Request the user for insert a smartcard. Function shows a dialog which asks user for smartcard.

Parameters

sDescription

Readable description of smartcard type. Description should not exceed 50 characters.

Return Value

Property that informs about smartcard state at chipdrive. See description of states at BACSmartcardState.

String IBACCardTerminal::CardTerminalID;

Property that selects a particular installed smart card reader and driver.

Comments

This is a generic property which meaning can be defined by an implementation. It shall, however, always be used for the purpose of identifying a particular smart card reader.

The CT-API based implementation uses this property to select the actual path and name of the CT-API DLL file. It uses a default value of "CT32.DLL"

The PC/SC Smart Card API based implementation uses this parameter to receive the name of the smart card reader to connect to. By default the single installed default card reader is used.

String IBACCardTerminal::CardTerminalParameter;

Property that further qualifies the CardTerminalID property.

Comments

The CT-API based implementation uses this property to receive the port number of the desired smart card reader. The PC/SC based implementation ignores this property.

void IBACCardTerminal::CloseCT();

Close card terminal.

Comments

Releases any acquired resources and shuts the card terminal down. This operation may be followed by an OpenCT invocation or by a final object release.

Note that an implementation of this interface must gracefully shut down upon a final release, even if this operation was not invoked.

void IBACCardTerminal::EjectICC();

Power down and (optionally) eject ICC. This operation may be issued to conserve power between subsequent sessions.

Comments

The purpose of this command is to return into the open card terminal state. If this is not possible, then an error shall be raised. If it is possible to return into this state, then any problems should be ignored and the operation shall succeed.

Note that the caller may issue CloseCT without issuing EjectICC first.

Long IBACCardTerminal::ExecuteCommand(
	[in] String sHexCommand,
	[in, out] String* psHexResponse);

Sends command to ICC and returns its response (if any).

Parameters

sHexCommand

Command string in hexadecimal representation.

psHexResponse

Response string in hexadecimal representation. The Status word (SW1:SW2) was removed from this string and is returned in the methods result. Hence, this may be an empty string.

Return Value

Status word (SW1:SW2) that was returned in the response data.

Comments

If the command cannot be successfully transmitted to the ICC or no reponse was received, then this operation is required to raise an IErrorInfo instance with a description that is suitable to be displayed to the user. In case of any error the card terminal is implicitly closed.

void IBACCardTerminal::OpenCT();

Open card terminal. Only if this operation was successful then any of the other operations in this interface may be invoked.

Comments

Before this operation is invoked the caller must select the desired smart card reader by setting the CardTerminalID and CardTerminalParameter properties.

If the requested card terminal cannot be successfully opened for any reason, then this operation is required to raise an IErrorInfo instance with a description that is suitable to be displayed to the user.

Note that the DDBACCPL invokes this operation in order to test whether a selected card terminal is available. Hence, an implementation is required to ensure that the card terminal is physically attached and ready for use.

void IBACCardTerminal::RequestICC();

Obtain access to inserted ICC. This operation must be successfully completed before an ICC command can be executed.

Comments

If no ICC is inserted at the time this operation is invoked or if the operation fails for any other reason (e.g. inserted type of card not supported), then this operation is required to raise an IErrorInfo instance with a description that is suitable to be displayed to the user. This means, the message should not be to technical, but rather guide the user to resolve the problem.

If this function completes successfully, then a card is inserted and ready to be used.

BACCardTerminalStates IBACCardTerminal::State;

Read-only property that returns the current state of this IBACCardTerminal instance.

IBACAccounts IBACContact::Accounts;

Return a collection of Accounts which belong to this contact

Developer Notes

This method is implemented in the IBACContact3 interface.

IBACAccounts IBACContact::Accounts;

Return a collection of Accounts which belong to this contact

Developer Notes

This method is implemented in the IBACCustomer5 interface.

The IBACPersistentObject interface is an abstract base from which all persistent BAC objects are derived.

Comments

Several objects of the BAC support object persistence. This means, that the entire object can be persistently stored in some storage location, and recreated later by restoring it from that storage. The following BAC objects support persistency:

• BACBankData (BPD)
• BACAccountData (UPD)
• BACSegment
• BACMessage
• BACDataObject

These objects support persistency by implementing the standard COM interfaces IPersist, IPersistFile, IPersistStream, IPersistStreamInit, and IPersistMemory. If possible, clients shall use these interfaces in order to store and retrieve persistent objects. However, Visual Basic cannot use these interfaces.

In order to support incapable clients, each persistent object also implements the helper methods of the IBACPersistentObject interface in its default interface. These helper methods make the IPersistFile interface available to all Automation compatible clients.

Hint: Most databases support direct storage of objects that support the IPersistStream interface. Usually this is accomplished by defining a field of type "OLE Object" or similar. Such a field can then be used to store an object directly.

Methods and Properties

String IBACPersistentObject::CurrentFilename;

Read-only property that returns the current filename of this persistent object. The current filename is established by Load and SaveAs. This may be an empty string if the object was newly created and not saved, yet.

See Also

IPersistFile::GetCurFile in the COM specification.

Boolean IBACPersistentObject::IsDirty;

Boolean read-only property that indicates whether this object was changed since it was last saved to its current filename. This flag is set whenever the object is changed and is cleared by Save and SaveAs. It is not cleared by SaveCopyAs.

See Also

IPersistFile::IsDirty in the COM specification.

void IBACPersistentObject::Load(
	[in] String sFilename);

Loads the object data from the given file. The object is reinitialised with the loaded data.

Parameters

sFilename

Complete path and filename of storage location. This name is remembered for subsequent Save invocations. The remembered name is available through the CurrentFilename property.

See Also

IPersistFile::Load in the COM specification.

void IBACPersistentObject::Save();

Saves the object using the current filename. The existing file of that name will be silently overwritten. The current filename is set by the Load and SaveAs methods.

This methods clears the internal IsDirty flag.

See Also

IPersistFile::Save in the COM specification.

void IBACPersistentObject::SaveAs(
	[in] String sFilename);

Saves the object using the given filename.

Parameters

sFilename

Complete path and filename of storage location. Any existing file of that name will be overwritten. This name will then be remembered as the CurrentFilename of this object.

See Also

IPersistFile::Save in the COM specification.

void IBACPersistentObject::SaveCopyAs(
	[in] String sFilename);

Saves the object using the given filename, but will not remember that name. The CurrentFilename property will remain unchanged.

Parameters

sFilename

Complete path and filename of storage location. Any existing file of that name will be overwritten.

See Also

IPersistFile::Save in the COM specification.

The interface IBACSecurity is the generic base interface that must be implemented by all DDBAC security provider components. It provides an overly complete set of generic security operations that are required to implement the HBCI security procedures. The abstraction of the security provider component models that of a security media such as a chipcard and its operations. It is the goal of this interface to fully support all chipcard features, yet allow an entirely software based implementation.

Some methods declared in this interface are not applicable to all security providers, for example, not all security providers can generate keys. An implementation of an unsupported method is obliged to return the standard HRESULT E_NOTIMPL.

Chipcard based security providers are required to use the IBACCardTerminal interface for access to the chipcard.

A security component manages up to six different keys enumerated in the BACKeyIDs enumeration. The temporary keys are used during an update of the corresponding active keys.

Methods and Properties

Developer Notes

The IBACSecurity interface defines the internal interface to a security provider component. It should never be accessed by application programs directly.

void IBACSecurity2::DeactivateKey(
	[in] Long nKeyID);

Resets the key state from bacKeyStatusActive to bacKeyStatusInactive.

Parameters

nKeyID

Selects the key that shall be deactivated.

Comments

This method switches a key state from bacKeyStatusActive to bacKeyStatusInactive. If the key is in any other state, then this method returns an error.

If the security media does not support deactivating the key refered to by nKeyID, then this method should do nothing and return.

See Also

GeneratePrivateKey, ActivateKey

void IBACSecurity2::EraseKey(
	[in] Long nKeyID);

Physically erases the indicated key with all its attributes.

Parameters

nKeyID

Selects the key that shall be erased.

Comments

This method completely and physically (if possible) erases the indicated key, regardless of the keys current state. After the key was erased its key status is bacKeyStatusNull.

If the security media does not support erasing the key refered to by nKeyID, then this method should do nothing and return.

See Also

GeneratePrivateKey, ActivateKey

void IBACSecurity4::AuthenticateUI(
	[in] String sSecurityMediaID);

Authenticates the user and thus opens up access to the security media. The actual security media must be identified by its security media ID.

Parameters

sSecurityMediaID

Unique identification of the desired security media.

Comments

This method is identical to IBACSecurity::Authenticate, but does not have a passphrase parameter. Instead this method will pop up a dialog box and prompt the user itself. If this method is implemented by smart card based security components it provides special support for class 2 smart card readers with own pinpad for PIN entry.

Note that even if this method is implemented, the caller must be prepared to catch a E_NOTIMPL exception and gracefully degrade to using its own PIN entry dialog box.

If the user cancelled the PIN entry at the card reader, then the security object will not be authenticated and this method returns S_FALSE.

void IBACSecurity::ActivateKey(
	[in] Long nKeyID);

Activates the indicated key. The detailed bahaviour depends on the type of key that is activated.

Parameters

nKeyID

Selects the key that shall be activated.

Comments

If nKeyID refers to a bank key or a user key (not a temporary key) then this method solely changes its status from bacKeyStatusInactive to bacKeyStatusActive.

If nKeyID refers to a temporary key then that key will be copied over the corresponding user key. The destination user key receives the key status bacKeyStatusActive. The temporary key is erased and thus receives the new key status bacKeyStatusNull.

If nKeyID refers to a key that is already active (not possible for a temporary key) then this method does nothing.

Note that support of temporary keys is optional.

See Also

GeneratePrivateKey

void IBACSecurity::Authenticate(
	[in] String sSecurityMediaID,
	[in] String sPassphrase);

Authenticates the user and thus opens up access to the security media. The actual security media must be identified by its security media ID.

Parameters

sSecurityMediaID

Unique identification of the desired security media. The actual structure of this string depends on the implementation of the security provider and the nature of the security media. This could be a drive letter, a filename or some smartcard application identification. If a security provider supports only a single security media (e.g. some special purpose hard and fast installed crypto hardware), it may even ignore this parameter.

If a single security media can contain mutiple separate keysets for one or more HBCI contacts, then the security media ID must also identify the proper keyset.

sPassphrase

Secret password or PIN that is used to protect access to the security media. This passphrase authenticates the user against the security media, that is, is ensures that only the right user can access the security media.

If the security media is a smartcard, then this probably a simple PIN. If the security media is a plain file, then this should be a long and complex password, hence it is called a passphrase.

Comments

When a security provider object is newly created it is not associated with any security media and is in an unauthorized state. In the unauthorized state no access to any security media is possible, hence, no other operations can be performed. Only after a successful authentication by this method the security media becomes accessible and security operations can be performed with the private keys contained on it.

Any authentication failure is indicated by raising an appropriate error with a user friendly descriptive error text in the associated ErrorInfo object.

void IBACSecurity::ChangePassphrase(
	[in] String sNewPassphrase);

Changes the passphrase that is used to protect access to the security media. If the passphrase cannot be changed, then this method will not be implemented.

Parameters

sNewPassphrase

New passphrase.

String IBACSecurity::DecryptSessionKey(
	[in] Long nKeyID,
	[in] String sHexCryptogram);

Decrypts the session key.

Parameters

nKeyID

Key ID of key that shall be used to decrypt the session key. Usually this should refer to the active ciphering key of the user bacUserCipheringKeyID. During a key update this may also refer to the temporary ciphering key bacTempCipheringKeyID. A reference to another key may be rejected by the security component.

sHexCryptogram

Hexadecimal representation of encrypted session key.

Return Value

Hexadecimal representation of the original unencrypted session key.

String IBACSecurity::EncryptSessionKey(
	[in] Long nKeyID,
	[in] String sHexSessionKey);

Encrypts the rather small session key using the indicated public key.

Parameters

nKeyID

Key ID of key that shall be used for encryption. Usually this should refer to the active ciphering key of the bank bacBankCipheringKeyID. A reference to another key may be rejected by the security component.

sHexSessionKey

Hexadecimal representation of the HBCI session key that was used to do the bulk encryption of the message data. Currently the HBCI session key consists of 128 bits.

Return Value

Hexadecimal representation of encrypted session key.

Comments

The current HBCI specification requires that the bulk encryption of the message data has to be done using a random session key and the 2K3DES algorithm. Only the encryption of the session key is done according to the chosen security procedure.

void IBACSecurity::GeneratePrivateKey(
	[in] Long nKeyID);

Generates a new private key (or asymetric key pair). If the security provider does not support generation of keys, then this method will not be implemented.

Parameters

nKeyID

Selects which key shall be generated. This must not refer to a bank key.

Comments

This method can generate an user key or a temporary key. An user key usually needs only to be generated during the first time initialization of the security media. For subsequent key updates a temporary key shall be generated and subsequently activated via ActivateKey after it was accepted by the bank.

The newly generated key always receives the key status bacKeyStatusInactive. This method also creates a suitable key name for the new key and perhaps resets the signature ID counter.

If an user key is generated, then the key number and version are reset according to the needs of the security media (usually either zero or one). The country code, bank code and user ID parts of the key name are chosen according to the authenticated user (see Parameters). The key type is either "S" or "V" according to the key ID.

If a temporary key is generated, then the key name is copied from the corresponding user key and the key version is incremented by one. If the corresponding user key does not exist, then an initial key name as described above is generated for the key.

void IBACSecurity::ImportPublicKey(
	[in] Long nKeyID,
	[in] Long nKeyNumber,
	[in] Long nKeyVersion,
	[in] String sHexPublicModulus,
	[in, defaultvalue(0)] Long nCertificateType,
	[in, defaultvalue("")] String sHexCertificate);

Imports the public part of an asymmetric key pair and all associated key attributes into this security provider. This method is not implemented by symmetric security procedures. The BACDialog object invokes this method for every HIISA segment that it receives. It is also invoked during setup of a new HBCI contact by the contact wizard.

Parameters

nKeyID

Key ID of key that shall be imported. Usually this should refer to the one of the bank keys (i.e. bacBankCipheringKeyID or bacBankSignatureKeyID). A reference to another key may be rejected by the security component.

nKeyNumber

Key number from the key name. This should be extracted from the HIISA segment key name group.

nKeyVersion

Key version from the key name. This should be extracted from the HIISA segment key name group.

sHexPublicModulus

Hexadecimal representation of the public modulus (i.e. the public part of the key pair). Note that the public exponent is defined to be always 2^16+1 (65537, 0x10001) and cannot be changed.

nCertificateType

HBCI defined certificate type. The value zero indicates that no certificate is present. If a certificate is present the security component must validate it or otherwise reject the imported key.

sHexCertificate

The certificate itself in hex representation. An empty string if no certificate is given.

Comments

The imported key receives the key status bacKeyStatusInactive. It can subsequently be made active using the method ActivateKey. The imported key is immediately persistently stored onto the security media.

The imported key can only be used to verify signatures using the VerifySignature method or to encrypt a session key using the EncryptSessionKey method. The public key cannot be used to create a signature or to decrypt data - these operations need the private parts of a key.

See Also

KeyAttribute

String IBACSecurity::KeyAttribute(
	[in] Long nKeyID,
	[in] Long nKeyAttributeID);

Indexed read-only property that returns the selected key attribute inside a string.

Parameters

nKeyID

Unique KeyID of the desired asymmetric key. One of the well known constant key IDs from the BACKeyIDs enumeration can be used.

nKeyAttributeID

This selects the key attribute to be returned. This should be one of the constant key attribute IDs from the BACKeyAttributes enumeration.

String IBACSecurity::Parameter([in] String sName);

Indexed property that provides named access to the parameters of the security provider. Only some of these properties can be changed, most are read only.

Comments

The definition of the IBACSecurity Interface includes a set of standard parameters that must be available through this property. Nevertheless, additional specialised parameters may be available by some security providers.

If a parameter is read that is not known by the security provider it is obliged to return an empty string.

The following standard parameters are defined:

SecurityProcedureCode (read only)

This parameter provides the security procedure code of the security procedure that is implemented by the security provider. This must be a three character string such as "RDH" or "DDV". The actual security procedure codes are defined by the HBCI segment HISHV.

SecurityProcedureVersion (read only)

This parameter provides the implemented security procedure version. The returned value must be a number in the range from zero through 999. The actual security procedure versions are defined by the HBCI segment HISHV.

CustomerSystemStatus (read only)

This parameter provides the CustomerSystemStatus value as required by the HBCI HKIDN segment. If the returned CustomerSystemStatus is "1", then a CustomerSystemID is required for this security procedure. If no CustomerSystemID is required, then "0" must be returned. This value is "2" if the CustomerSystemID ist stored on the security media. (RDH-2)

SignatureID (read only)

This read only parameter must be supported if the indicated CustomerSystemStatus parameter has the value "0", or both, the CustomerSystemStatus and the SecurityMediaStatus are "1". The signature ID is a monotonically increasing signature counter that must be incremented after each successful signature done with SignMessageDigest. The current value of this parameter is assumed to be effective for the very next signature.

IsUniqueSignatureID (read only)

Shall return "1" when the security provider component guarantees that the provided SignatureID is a unique monotonically increasing counter. Usually this guarantee is only possible when the SignatureID is maintained on a smart card.

CustomerSystemID (read/write)

Returns the stored CustomerSystemID, if any. If the security media does not store the CustomerSystemID, or if no CustomerSystemID was assigned, yet, then an empty string is returned.

Only when the "CustomerSystemStatus" and the "SecurityMediaStatus" are "1", then this parameter is written whenever a HISYN with a CustomerSystemID was received in an online dialogue. As the SignatureID is tied to the CustomerSystemID, the SignatureID counter should be reset to one whenever a new CustomerSystemID is written.

SecurityMediaID (read/write)

Starting at version 2.2.0.9 this proptery is added. This field holds the optional security media ID for this contact. For software based RDH security this is the actual filename of the keyfile. This field is assigned by the "Homebanking Kontakte" control panel applet when the contact is set up. If security media is a DDV chipcard this field contains the "ContactIndex" of DDV smartcard, where 1 is the first contact at smartcard. If security media is a FST keyfile field contains also information about user name and contact index of FST file, SecurityMediaID is build like: %filename%?UserName=%username%&ContactIndex=%contactindex%".
If a new SecurityMediaID is set, keyfile will be converted. Note, only DDBAC keyfiles can be written.

CID (read only)

Through this Parameter the card ID of a chipcard can be returned as a hex string. Security components that are chipcard based shall supply this parameter if it is required to be inserted into the signature header segment's CID field.

CanChangePassphrase (read only)

Starting at version 2.2.0.18 this documentation is added. If it is possible changing the passphrase (PIN) of security medium it will be "1" returned, otherwise "0" or "".

Status (read/write)

Starting at version 2.2.0.18 this documentation is added. Use this parameter for setting status of security medium. This property is only implemented at DDBACRDH component. Status can be one of the BACSecurityMediaStatus status values. The Status is primary used at new contact wizard of DDBAC. It is used to keep track of status if a error occur.

UserName (read)

Starting at version 2.2.0.18 this documentation is added. This parameter is only implemented at DDBACRDH component. It is specially used for FST key files. This property is for internal use only!

ContactIndex (read/write)

Starting at version 2.2.0.18 this documentation is added. Depending of security medium it can store multiple contact informaion. Use this parameter to mark a contact as active. All security functions use the active contact of security medium. First contact at security medium is "1". At new contact wizard user select the desired contact from security medium. Wizard use this parameter to show information about all contacts of security medium.

ContactCapacity (read only)

Starting at version 2.2.0.18 this documentation is added. Use this parameter for asking the security medium how many contacts can be stored. At DDV smartcards 5 are common. If nothing is returned only one is possible.

CardVersion (read only)

Starting at version 2.2.0.18 this documentation is added. This parameter is only used at DBACDDV component. Value "0" indicates DDV Typ 0 smartcards and "1" is for DDV Typ 1. DDV Typ 1 smartcards are specified at HBCI version 2.2.

CountryCode, BankCode, UserID, CustomerID, BankUserID, HBCIVersion, CommunicationsService, CommunicationsAddress, CommunicationsAddressSuffix

If the security media stores HBCI contact parameters, as it usually should, then these parameter provide the details. The HBCI contact setup wizard writes these properties with the values entered by the user.

RandomBytes (read only)

Generates 16 Random Bytes using the smartcard. Returns the random bytes as a 32 Byte long HexString oder an emoty string if random bytes are not supported.

BankHash (read/write)

Returns the hashvalue of the Banks chipering key as a HexString. If the card does not support this feature, an empty string will be returned. This value can be used to verify the bankkey without interacting with the customer.

IsAuthenticated (read only)

Returns "1" if the security medium ist in an authenticated state, otherwise "0"

KeyTransmitStatus (read/write)

Returns the actual KeyTransmitStatus as described in FinTS as a Hex Value (8bit). If the card does not support this feature, an empty string will be returned.

Sicherheitsfunktion (read/write)

Used für 2-Step TAN Procedure. This value is initialized when the first message is sigend and will be used until the dialog ends, since it is not allowed to change the Sicherheitsfunktion during a dialog.

EraseCurrentContact (write)

Deletes the current HBCI contact parameters and marks the contact as free

RemainingSignatures (read)

Return the number of remaining signatures before the card expires

String IBACSecurity::SignMessageDigest(
	[in] Long nKeyID,
	[in] String sHexMessageDigest);

Creates an electronic signature for a given message digest (MD).

Parameters

nKeyID

Key ID of key that shall be used to create the signature. Usually this should refer to the active signature key of the user bacUserSignatureKeyID. A reference to another key may be rejected by the security component.

sHexMessageDigest

Hexadecimal representation of the message digest that shall be signed. Currently the HBCI specification requires that the message digest is computed using the RIPEMD-160 algorithm, hence it will be a 20 byte (40 hex digits) hash value.

Return Value

Hexadecimal representation of signature. The size of the signature depends on the actual security procedure.

Boolean IBACSecurity::VerifySignature(
	[in] Long nKeyID,
	[in] String sHexMessageDigest,
	[in] String sHexSignature);

Verifies the given signature against the also given message digest.

Parameters

nKeyID

Key ID of key that shall be used to verify the signature. Usually this should refer to the active signature key of the bank bacBankignatureKeyID. A reference to another key may be rejected by the security component.

sHexMessageDigest

Hexadecimal representation of the MD.

sHexSignature

Hexadecimal representation of signature.

Return Value

If the signature is valid, then the result value will be True. If the signature did not match the message digest, then the result value will be False.

The interface IBACSecurityCardTerminal can be implemented by smart card based security provider objects. If it is implemented, the application may set or query the card terminal object used by the security provider object.

Methods and Properties

IBACCardTerminal IBACSecurityCardTerminal::CardTerminal;

This property provides access to the card terminal object that is used by this security provider object.

Comments

The property my be read at any time. Immediately after the security provider object is created, there is no card terminal object associated with it, hence this property will be read back as null. The property may only be written before the IBACSecurity::Authenticate or IBACSecurity4::AuthenticateUI method was called.

String IBACSegment2::GetXML();

Converts the entire data into XML.

Return Value

Returns a XML string that contains the object data. The typedefinition of XML you can see at specified object.

Developer Notes

Function uses the Microsoft XML 3.0 Parser, so it has to be installed.

String IBACSegment2::PutXML(
	String sXML);

Read object data from XML.

Parameters

sXML

XML representation of object data. The typedefinition of XML you can see at specified object.

Developer Notes

Function uses the Microsoft XML 3.0 Parser, so it has to be installed.

String IBACSegment3::Verify();

Verify the data in the segment.

Return Value

Checks the Segment against the HBCI Syntax and returns S_OK if the Segment is valid.

The interface IBACTransmogrify is a generic interface for serialization of an object in an XML representation. An object supporting this interface can be initialized by reading an XML stream.

String IBACTransmogrify::GetXML();

Converts the entire data into XML.

Return Value

Returns a XML string that contains the object data. The typedefinition of XML you can see at specified object.

Developer Notes

Function uses the Microsoft XML 3.0 Parser, so it have to be installed.

String IBACTransmogrify::PutXML(
	String sXML);

Read object data from XML.

Parameters

sXML

XML representation of object data. The typedefinition of XML you can see at specified object.

Developer Notes

Function uses the Microsoft XML 3.0 Parser, so it have to be installed.

This is a common base interface that is used for the communication between the BACDialog and BACTransport objects. Basically, the BACDialog object uses the generic transport services of the transport object solely through this interface.

Comments

The HBCI transport interface defines a minimal asynchronous communication API for sending and receiving message buffers, tailored to be usable for an HBCI 2.0 application or server, only. Hence, you won't find sophisiticated transport functionality here.

Usually an actual implementation of this interface adds its own transport specific methods in an interface that is derived from this interface. This derived interface may then be published to the application programmer.

The IBACTransport interface is asynchronous, that is, it usually returns immediately from every method invocation, executing the actual operation asynchronously in the background. The client of the IBACTransport interface can establish a callback interface to be informed about the progress of the backgound operation. It does so by passing an implementation of the IBACTransportCallback interface to the IBACTransport::Advise method.

Methods and Properties

Developer Notes

The IBACTransport interface defines the internal interface to a transport provider component. It should never be accessed by application programs directly.

The IBACTransport2 is used to pass additional, named parameters

String IBACTransport2::Parameter([in] String sName);

Indexed property that provides named access to the parameters of the tranport provider.

Comments

Additional Headers to be sent with the http request. Default: Pragma: no-cache\r\nContent-Type: application/x-vnd.hbci\r\n

void IBACTransport2::SendReceiveXml(
	[in] String sXml,
	[out] String psResult);

Loads the object data from the given file. The object is reinitialised with the loaded data.

Parameters

sXml

XML Data to be sent

psResult

XML Data received

Long IBACTransport::Advise(
	[in] IBACTransportCallback* piCallback);

Install a callback interface.

Parameters

piCallback

Interface that will be called back whenever something interesting occurs. This object must implement the IBACTransportCallback interface in order to receive any callbacks.

Return Value

Receives an identifier for this advise connection. This must be passed to Unadvise.

void IBACTransport::Cancel();

Requests that any outstanding operations are forcibly stopped and the transport returns to the idle error state.

Comments

This method may be invoked in any state. However, in the states bacTransIdle and bacTransError it is completely ignored and does nothing at all.

As a result of the method invocation, the transport object switches into the bacTransError state. If there was an active operation, the callback method IBACTransportCallback::Error is invoked. The indicated error code will be bacTransErrCancelled.

String IBACTransport::CommunicationsAddress;

Property that selects the communications address to connect to.

Comments

This property must be set to the communications address as it appears in the HIKOM segment. For a "T-Online" access this is the gateway page number. For a "TCP/IP" access this is the IP address in dotted decimal notation (e.g. 123.123.123.123).

String IBACTransport::CommunicationsAddressSuffix;

Property that selects the communications address suffix to connect to.

Comments

This property must be set to the communications address suffix code as it appears in the HIKOM segment. For a "T-Online" access this is the regional code. For "TCP/IP" this is not defined by HBCI. However, the BACTransportTCPIP implementation uses this parameter to optionally select the IP port which is 3000 by default.

void IBACTransport::Connect();

Initiate establishing of a new transport connection.

Comments

This method must only be invoked if the transport object is currently in either the bacTransIdle or the bacTransError state. In the latter case, the transport object attempts to clear the error condition before trying to establish another connection. In any other state, an immediate failure will be returned.

This method only initiates the connection and returns to the caller as soon as possible. When this method returns successfully the state has been switched to the bacTransConnecting state.

When the connection becomes available, the transport object switches into the bacTransConnected state and invokes the IBACTransportCallback::Connected method of an installed callback interface.

Whenever a communication failure is encountered during a connection, the transport object is obliged to tear down the connection and switch into the bacTransError state. Only after the errorneous connection is completely idle again, the transport object must invoke the callback method IBACTransportCallback::Error.

void IBACTransport::Disconnect();

Initiate tearing down of the transport connection.

Comments

This method must only be invoked if the transport object is currently in the bacTransConnected state. In any other state, a failure will be returned.

In response to this method invocation the transport object switches into the bacTransDisconnecting state and returns to the caller. Once the connection is completely torn down, the transport switches into the bacTransIdle state and invokes the callback method IBACTransportCallback::Disconnected.

See Also

Connect

BACTransportErrors IBACTransport::Error;

Read-only property that provides the error code associated with the bacTransError state. In any other state the value of this property is meaningless. The possible error codes are enumerated in the BACTransportErrors enumeration.

void IBACTransport::SendReceive(
	[in] IBACMessageBuffer* piOutgoingMessageBuffer,
	[in] IBACMessageBuffer* piIncomingMessageBuffer);

Initiate sending and receiving of a pair of messages.

Parameters

piOutgoingMessageBuffer

Message buffer object that contains the HBCI message to be sent.

piIncomingMessageBuffer

This buffer will receive the complete response HBCI message.

Comments

This method must only be invoked if the transport object is currently in the bacTransConnected state. In any other state, a failure will be returned.

In response to this method invocation the transport object switches into the bacTransSending state and returns to the caller as soon as possible. During the background send operation the transport object periodically invokes the IBACTransportCallback::SendProgress callback method to indicate its progress. Once the entire message has been sent the transport switches automatically into the bacTransReceiving state.

During the background receive operation the transport object periodically invokes the IBACTransportCallback::ReceiveProgress callback method to indicate its progress. Once the entire response message has been received the transport switches back into the bacTransConnected state and invokes the callback method IBACTransportCallback::SendReceiveComplete.

Note that the completeness of the receive operation is determined by the message buffer object which tells its caller when it has collected a complete message.

See Also

Connect

BACTransportStates IBACTransport::State;

Read-only property that indicates the current state of the transport object. The value of this property is one of the BACTransportStates enumeration.

void IBACTransport::Unadvise(
	[in] Long lCookie);

Remove previously installed callback interface.

Parameters

lCookie

Identifies the advise connection that shall be released.

Comments

This method releases any previously installed callback interface. As a result, no more callback methods will be invoked.

An object that implements this interface must be passed to the IBACTransport::Advise method. The transport object will then asynchronously invoke the callback at appropriate times.

While a callback is executing it must not re-enter the transport object. Any attempt to do so will be refused with an E_UNEXPECTED failure.

There is only one object that implements this interface, namely the BACDialog object.

Methods and Properties

Developer Notes

The IBACTransportCallback interface defines the internal callback interface to be invoked by transport provider component. It must never be accessed by application programs directly.

See Also

IBACTransport

void IBACTransportCallback::Connected();

This event method is invoked when the initiated IBACTransport::Connect operation is complete and a connection was successfully established. The transport object was switched into the bacTransConnected state.

void IBACTransportCallback::Disconnected();

This event method is invoked when the initiated IBACTransport::Disconnect operation is complete and the connection was orderly shut down. The transport object was switched into the bacTransIdle state.

void IBACTransportCallback::Error();

This event method is invoked when the previous transport operation failed due to a transport error. The transport object was switched into the bacTransError state.

void IBACTransportCallback::ReceiveProgress(
	Long lBytesReceived);

This callback method should be invoked periodically during a receive operation in order to inform the client about the actual progress. A client may use this callback to implement a GUI progress indicator -- although it will have a hard time doing so, because it won't know how much data will be received in total.

Parameters

lBytesReceived

This provides the number of bytes that were already received.

void IBACTransportCallback::SendProgress(
	[in] Long lBytesSent,
	[in] Long lBytesTotal);

This callback method should be invoked periodically during a send operation in order to inform the client about the actual progress. A client may use this callback to implement a GUI progress indicator.

Parameters

lBytesSent

This provides the number of bytes that were already sent.

lBytesTotal

This provides the total number of bytes that are to be sent during this send operation.

void IBACTransportCallback::SendReceiveComplete();

This event method is invoked when the initiated IBACTransport::SendReceive operation is complete and a complete response message was received. The transport object was switched into the bacTransConnected state.

void IBACTransportCallback::StateChange(
	[in] BACTransportStates nNewState);

This callback method must be invoked by the transport object whenever it enters a new state. A client is allowed to immediately invoke another suitable operation during the execution of this callback method.

Parameters

nNewState

New state that is entered.

Enumerates the possible states of the IBACCardTerminal interface.

enum BACCardTerminalStates
{
	bacCTClosed,
	bacCTOpen,
	bacCTICCReady

};

Members

bacCTClosed

Card terminal object instantiated but not opened.

bacCTOpen

Card terminal was successfully opened.

bacCTICCReady

A card was successfully requested and is now ready.

Enumerates the possible values of the BACDialog::Language property. Refer to this property for a detailed discussion of the individual flags.

enum BACDialogLanguages
{
	bacDialogLanguageDefault,
	bacDialogLanguageGerman,
	bacDialogLanguageEnglish,
	bacDialogLanguageFrench

};

Members

bacDialogLanguageDefault

Bank chooses dialog language.

bacDialogLanguageGerman

Dialog language is german.

bacDialogLanguageEnglish

Dialog language is english.

bacDialogLanguageFrench

Dialog language is french.

Enumerates the possible results in UI dialogs

enum BACDialogResults
{
	bacDialogResultOK,
	bacDialogResultCancelled

};

Members

bacDialogResultOK

Bank chooses dialog language.

bacDialogResultCancelled

Dialog language is german.

Enumerates the possible states of the BACDialog object. Refer to BACDialog::State for a detailed discussion of the individual states.

enum BACDialogStates
{
	bacDialogIdle,
	bacDialogBeginning,
	bacDialogReady,
	bacDialogExecuting,
	bacDialogEnding,
	bacDialogAborted

};

Members

bacDialogIdle

There is no connection or dialog at all.

bacDialogBeginning

The dialog is connecting to the bank.

bacDialogReady

The dialog is ready to accept messages.

bacDialogExecuting

The dialog is executing a message.

bacDialogEnding

The dialog is disconnecting from the bank.

bacDialogAborted

The dialog was aborted.

Enumerates the possible dialog types that can be initiated by the BACDialog::BeginDialog method.

enum BACDialogTypes
{
	bacDialogNone,
	bacDialogStandard,
	bacDialogAnonymous,
	bacDialogSynchronizeCustomerSystemID,
	bacDialogSynchronizeMessageSeqNo,
	bacDialogSynchronizeSignatureID,
	bacDialogRequestCommunicationParameters,
	bacDialogUpdateUserKeys,
	bacDialogRequestBankKeys,
	bacDialogSubmitUserKeys,
	bacDialogBlockUserKeys,
	bacDialogBlockUserKeysAnonymous

};

Comments

The dialog type determines whether the outgoing message are encrypted or not. The dialog type also determines which segments will be included in the dialog initialization message sent to the bank system.

The current dialog type is stored in the BACDialog::DialogType property.

Members

bacDialogNone

There is no current dialog. The dialog type is assigned by the BACDialog::BeginDialog method and is cleared to bacDialogNone by the BACDialog::EndDialog method or an abnormal dialog abortion.

bacDialogStandard

Standard HBCI Dialog (HBCI 2.0.1 Kap.: VIII.3.1 "Standarddialog"). Outgoing dialog messages are encrypted and usually have at least one signature. Initialization message type is N6 and thus includes HKIDN, HKVVB and the appropriate HKISA segments.

bacDialogAnonymous

Anonymous HBCI Dialog (HBCI 2.0.1 Kap.: VIII.3.2 "Anonymer Dialog"). Outgoing dialog messages are neither signed nor encrypted. The BACDialog::AutoSignature option is turned off. Initialization message type is N7 and thus includes HKIDN and HKVVB only.

bacDialogSynchronizeCustomerSystemID

Synchronization Dialog (HBCI 2.0.1 Kap.: VIII.3.3 "Synchronisierung"). Outgoing dialog messages are signed and encrypted. Initialization message type is N18 and thus includes HKIDN, HKVVB, the appropriate HKISA segments and a HKSYN segment. The HKSYN segment will request synchronization of the customer system ID.

bacDialogSynchronizeMessageSeqNo

Similar to bacDialogSynchronizeCustomerSystemID, but this type requests synchronization of the message sequence number.

bacDialogSynchronizeSignatureID

Similar to bacDialogSynchronizeCustomerSystemID, but this type requests synchronization of the signature ID.

bacDialogRequestCommunicationParameters

Special Dialog for retrieval of Communication Parameters (HBCI 2.0.1 Kap.: VIII.3.4 "Kommunikationszugang"). This is an anonymous dialog type. Initialization message type is N7 and thus includes HKIDN and HKVVB only.

bacDialogUpdateUserKeys

Submission of an Update of the Public User Keys (HBCI 2.0.1 Kap.: VIII.3.5 "Änderung eines öffentlichen Schluessels des Kunden"). Outgoing dialog messages are signed and encrypted. Initialization message type is N6 and thus includes HKIDN, HKVVB and the appropriate HKISA segments.

bacDialogRequestBankKeys

Special Dialog for the initial retrieval of the Public Bank Keys (HBCI 2.0.1 Kap.: VIII.3.6 "Erstmalige Anforderung der öffentlichen Schlüssel des Kreditinstituts"). This is an anonymous dialog type. Initialization message type is N10 and thus includes HKIDN, HKVVB and always two HKISA segments.

bacDialogSubmitUserKeys

Special Dialog for the initial submission of the Public User Keys (HBCI 2.0.1 Kap.: VIII.3.7 "Erstmalige Übermittlung der öffentlichen Schlüssel des Kunden"). Outgoing dialog messages are encrypted. Initialization message type is N12 and thus includes HKIDN and two HKSAK segments.

bacDialogBlockUserKeys

Secure blocking of user keys (HBCI 2.0.1 Kap.: VIII.3.8 "Schlüsselsperrung durch den Kunden"). Outgoing dialog messages are signed and encrypted. Initialization message type is N6 and thus includes HKIDN, HKVVB and the appropriate HKISA segments.

bacDialogBlockUserKeysAnonymous

Anonymous blocking of user keys (HBCI 2.0.1 Kap.: VIII.3.8 "Schlüsselsperrung durch den Kunden"). This is an anonymous dialog type variation of bacDialogBlockUserKeys. Outgoing dialog messages are neither signed but nor encrypted. Initialization message type is N7 and thus includes HKIDN and HKVVB only.

See Also

BACDialog::BeginDialog

Enumerates the possible formats of the BACSyntaxElement::Format property. Most formats needs an explicit length qualification.

enum BACFormatType
{
	bacFormatUnknown,
	bacFormatAlphanumeric,
	bacFormatText,
	bacFormatNumeric,
	bacFormatDigits,
	bacFormatFloat,
	bacFormatDTAText,
	bacFormatByteVector,
	bacFormatHexString,
	bacFormatObject,
	bacFormatYesNo,
	bacFormatDate,
	bacFormatVirtualDate,
	bacFormatTime,
	bacFormatID,
	bacFormatCountryCode,
	bacFormatCurrency,
	bacFormatValue,
	bacFormatDEG,
	bacFormatGDG,
	bacFormatUnicode,
	bacFormatRawText

};

Members

bacFormatUnknown

Format is not known. Should not be used.

bacFormatAlphanumeric

Format is alphanumeric. Represents the HBCI format "an".

bacFormatText

Format is text. Represents the HBCI format "txt".

bacFormatNumeric

Format is numeric. Represents the HBCI format "num".

bacFormatDigits

Format is digits. Represents the HBCI format "dig".

bacFormatFloat

Format is float Represents the HBCI format "float".

bacFormatDTAText

Format is alphanumeric but uses only the DTAUS0 character set. Represents the HBCI format "an".

bacFormatByteVector

Format is binary. Only for internal use. It's a one dimensional safearray of byte. Represents the HBCI format "bin".

bacFormatHexString

Format is binary. It is used at the key management segments it represents a string in a hexadecimal notation. Represents the HBCI format "bin".

bacFormatObject

Format is binary.

Data elements of type "bacFormatObject" are treated very specially by the ddBAC. Actually, all binary data blobs must be available as objects implementing the COM standard IPersistStreamInit interface. Hence, any persistent COM object can be used as a source or destination for HBCI binary data. A "bacFormatObject" data element cannot have a default value. Hence, if an optional "bacFormatObject" data element is not provided by the application it will always be omitted from the message (i.e. be empty).

In order to set a "bacFormatObject" data element the provided value must be a persistent object passed through an IUnknown pointer. This object is required to implement the IPersistStreamInit interface. Then, when the actual message is serialised, the binary data is obtained by asking the object to persist itself through a given IStream interface. The entire data that was written to this IStream by the object becomes the binary data that is inserted into the message.

When an inbound message is broken up into its data elements all "bacFormatObject" elements are streamed back into appropriate persistent objects. Thus, when reading the data element the application will always receive an object (i.e. an IUnknown pointer), unless the data element was omitted. How is the "appropriate" type of object determined?

The ddBAC use the BACSyntaxElement::ObjectClass property of the BACSyntaxElement object a.k.a. a ProgID. Using this ProgID the ddBAC try to instantiate a corresponding object and obtains its IPersistStreamInit interface. Using this interface the object is restored from an IStream that holds the binary data of the message.

Although an application program could provide its very own binary data objects, the ddBAC include several standard objects for convenience.

bacFormatYesNo

Format is Yes/No. Represents the HBCI format "jn". Possible values are Y,J,N.

bacFormatDate

Format is used for date. Represents the HBCI format "dat".

bacFormatVirtualDate

Format is used for virtual date. Represents the HBCI format "vdat".

bacFormatTime

Format is used for time. Represents the HBCI format "tim".

bacFormatID

Format is used for identification. Represents the HBCI format "id".

bacFormatCountryCode

Format is used for country code. Represents the HBCI format "ctr".

bacFormatCurrency

Format is used for currency, example "EUR". Represents the HBCI format "cur".

bacFormatValue

Format is used for a value of an amount. Represents the HBCI format "wrt".

bacFormatDEG

Format specify an element group, in HBCI a DEG. The format names "bacFormatDEG" and "bacFormatGDG" indicate the begin of a sequence of elements that resemble a data element group. The difference is that a DEG may only appear at the highest syntax level and is delimited with a plus "+" or tick "'" character, whereas a GDG may only appear inside a DEG and is always delimited with a colon ":".

The iteration count of the "bacFormatDEG" and "bacFormatGDG" elements applies to the group as a whole. Both tuples require the presence of an explicit length field. This length field must be a single number and must not be a range. It is interpreted as the number of subsequent elements that belong to this group.

The "bacFormatDEG" element assigns a name to the DEG, however,the name of a "bacFormatGDG" tuple is ignored and should be empty for future compatibility. The elements of a "bacFormatGDG" group inherit the DEG name of the containing "bacFormatDEG". There is an implementation restriction that requires that the first GD of a GDG must be a mandatory element!

bacFormatGDG

Special flag for GDG inside a syntax descriptor. Represents the HBCI format "GDG". This Syntax is used at "HIVDBS". For more information see bacFormatDEG

bacFormatUnicode

Unicode string element for international applications. The Unicode data is binary encoded. The syntax token for such an element is "uc".

bacFormatRawText

Text where white characters are not trimmed. Such an element is used for testing an HBCI server. The syntax token for such an element is "rawtxt".

The BACGlobals enumeration lists all global constants that do not belong into any other enumeration.

Most importantly this enumeration contains definitions for the basic DDBAC HRESULT error codes. These error codes are returned as HRESULT values 0x800A2710 through 0x800A2716. The high word is always 0x800A and the low word is the hex representation of the actual error code. In Visual Basic the error codes are returned in the Err.Number property.

enum BACGlobals
{
	bacVersionHBCI,
	bacErrorCantBuildMessage,
	bacErrorTransportFailure,
	bacErrorCantParseMessage,
	bacErrorDialogAborted,
	bacErrorTimeout,
	bacErrorSecurity,
	bacErrorCustomerSystemID,
	bacErrorNoPINTANSecurity

};

Members

bacVersionHBCI

201 - This is the version number of the HBCI version that was current at the time this version of the DDBAC components was released. This is also the default version assigned to each newly created BACDialog object.

bacErrorCantBuildMessage

10000 - The HBCI message or segment could not be created. Usually this means that a required data element is missing or an invalid data element was supplied. The error is in the client application.

bacErrorTransportFailure

10001 - The transport connection failed. A detailed error message is written to the HBCILOG.TXT, if enabled.

bacErrorCantParseMessage

10002 - The HBCI message received from the bank could not be interpreted. Usually this means that the bank sent an errorneous HBCI message.

bacErrorDialogAborted

10003 - The dialog was aborted upon request from the client application.

bacErrorTimeout

10004 - The dialog was forcibly aborted by the DDBAC because no bank response was received within the configured response timeout.

bacErrorSecurity

10005 - An error originating from some security problem occured.

bacErrorCustomerSystemID

10006 - An attempt was made to begin a dialog without a valid customer system ID. This means that the customer or client applications needs to successfully synchronize the HBCI contact before it can begin a dialog.

bacErrorNoPINTANSecurity

10007 - The connected HBCI does neither support HBCI+ with PIN/TAN security nor FinTS with PIN/TAN security.

Enumerates the well known key attributes used by security components. Refer to the documentation of the IBACSecurity::KeyAttribute property for more information about these values.

enum BACKeyAttributes
{
	bacKeyStatus,
	bacKeyNumber,
	bacKeyVersion,
	bacKeyModulus,
	bacKeyCertificateType,
	bacKeyCertificate

};

Members

bacKeyStatus

Status from BACKeyStatus enumeration.

bacKeyNumber

Key number from HBCI key name.

bacKeyVersion

Key version from HBCI key name.

bacKeyModulus

Public modulus value as hex string.

bacKeyCertificateType

Type of certificate (0 means none).

bacKeyCertificate

Transparent certificate as hex string.

Enumeration of the well known KeyID values. KeyID values are used as parameters to many IBACSecurity interface methods. Refer to the documentation of the IBACSecurity interface for more information about these values.

enum BACKeyIDs
{
	bacInvalidKeyID,
	bacUserCipheringKeyID,
	bacUserSignatureKeyID,
	bacBankCipheringKeyID,
	bacBankSignatureKeyID,
	bacTempCipheringKeyID,
	bacTempSignatureKeyID,
	bacUserPINKeyID,
	bacUserPINTANKeyID

};

Members

bacInvalidKeyID

This is the null KeyID. It is always invalid. It can be used to mark invalid KeyID variables in your code.

bacUserCipheringKeyID

KeyID of the active ciphering key of the authenticated user.

bacUserSignatureKeyID

KeyID of the active signature key of the authenticated user.

bacBankCipheringKeyID

KeyID of the active ciphering key of the associated bank.

bacBankSignatureKeyID

KeyID of the active signature key of the associated bank.

bacTempCipheringKeyID

KeyID of the temporary ciphering key. Note that a temporary key can never be active.

bacTempSignatureKeyID

KeyID of the temporary signature key. Note that a temporary key can never be active.

bacUserPINKeyID

Dummy KeyID that indicates a signature with a PIN only.

bacUserPINTANKeyID

Dummy KeyID that indicates a signature with a PIN and a TAN only.

Developer Notes

The key ID values have been chosen to be identical to the corresponding KID values of the Giesecke & Devrient HBCI RSA Chipcard.

Enumerates the possible key status values returned through the IBACSecurity::KeyAttribute property by security components. Refer to the documentation of the IBACSecurity::KeyAttribute property for more information about these values.

If the DDV security procedure is used the key status is always bacKeyStatusActive. Other key states are only possible when the RDH security procedure is used.

Note that an application program usually does not need to deal with keys and key status. All required key management is implemented in the HBCI contacts control panel applet.

enum BACKeyStatus
{
	bacKeyStatusNull,
	bacKeyStatusInactive,
	bacKeyStatusActive,
	bacKeyStatusExtern

};

Members

bacKeyStatusNull

The corresponding key does not exist (yet). If this is a user or temporary key it can be generated using the method IBACSecurity::GeneratePrivateKey. If this is a bank key it can be imported into the security media using the method IBACSecurity::ImportPublicKey. In either case the resulting key status is bacKeyStatusInactive

bacKeyStatusInactive

The key exists, but is not active yet. If this is a user key then this means that the key needs to be initially submitted to the HBCI system (See dialog type bacDialogSubmitUserKeys). During submission the key is activated via IBACSecurity::ActivateKey. If the corresponding key is a temporary key then it can be submitted using a key update dialog (See dialog type bacDialogUpdateUserKeys). During this dialog the temporary key is activated using IBACSecurity::ActivateKey. Finally, if this is a bank key, then it means that the user must manually authenticate that key by verifying it against the Ini Letter of the bank. Once the user acknowledges the key it is manually activated using IBACSecurity::ActivateKey.

bacKeyStatusActive

The key is active and ready to be used. Note that a temporary key can never have this status.

bacKeyStatusExtern

The Key is not stored on this media and has not been initialized yet. This Key must be imported before usage (i.E: ZKA Chipcard has no BankChipherKey and is set to this state until the Key has been imported from an external resource).

Enumerates the possible key transmit status values returned through the "BACKeyTransmitStatus" Parameter by security components.

enum BACKeyTransmitStatus
{
	KTS_MustSubmit,
	KTS_ISO9796,
	KTS_BankKeyValidated,
	KTS_MustSubmitChipherKey,
	KTS_MustSubmitSignatureKey,
	KTS_KeysLocked,
	KTS_Error

};

Members

KTS_MustSubmit

Bit1 Erstmalige Übermittlung der Kundenschlüssel notwendig '1'b - Ja '0'b - Nein

KTS_ISO9796

Bit2 Institutsrechner erwartet Signaturen nach ISO9796 mit AnnexA

KTS_BankKeyValidated

Bit3 Institutsschlüssel validiert

KTS_MustSubmitChipherKey

Bit4 Ausstehende Übermittlung des neuen öffentlichen Chiffrierschlüssels des Kunden bei Schlüsseländerung6

KTS_MustSubmitSignatureKey

Bit5 Ausstehende Übermittlung des neuen öffentlichen Signierschlüssels des Kunden bei Schlüsseländerung7

KTS_KeysLocked

Bit6 Schlüsselsperre mit Erfolg durchgeführt (Info, da terminierte Sperrung erst in der Zukunft wirksam werden kann)

KTS_Error

Bit7 Leitungsprobleme bei Übermittlung neuer Schlüssel

Enumerates a set of bits that indicate message features. Message flags are returned by the internal private method BACMessage::ParseMessageBuffer.

enum BACMessageFlags
{
	bacMessageFlagNone,
	bacMessageFlagSignature,
	bacMessageFlagEncrypted

};

Members

bacMessageFlagNone

No message flag applies.

bacMessageFlagSignature

The message has at least one signature.

bacMessageFlagEncrypted

The message is encrypted.

Enumerates the possible states of a BACMessage object. The current state of a BACMessage can be read through the BACMessage::State property.

enum BACMessageStates
{
	bacMessageInit,
	bacMessageSigned,
	bacMessageSent,
	bacMessageDone

};

Members

bacMessageInit

This is the initial state of the BACMessage object. As long as the BACMessage is in this state new transactions can be added to the BACMessage::Transactions collection. If more than one signature shall be added to this message then the BACMessage::NumSignaturesRequired property must be set to the desired value during this state.

bacMessageSigned

This state is entered when the first signature is added to the message using the BACMessage::AddSignature method.

bacMessageSent

This state is entered as soon as the logical message was converted into HBCI format for online transmission. Technically this happens when the private method GenerateMessageBuffer was invoked.

bacMessageDone

This state is entered when the online response was parsed and added to this message. In this state the response segments are available to the application program for further processing. Technically this state is entered when the private method ParseMessageBuffer was invoked. This is the final state of a BACMessage object.

Enumerates the possible security media status values available through the IBACSecurity::Parameter property by security components. Refer to the documentation of the IBACSecurity::Parameter property for more information about these values.

Note that an application program usually does not need to deal with security medias and their status.

enum BACSecurityMediaStatus
{
	bacSecurityMediaStatusNull,
	bacSecurityMediaStatusSubmitUserKeys,
	bacSecurityMediaStatusActive,
	bacSecurityMediaStatusBlockUserKeys,
	bacSecurityMediaStatusUpdateUserKeys

};

Members

bacSecurityMediaStatusNull

'00' Inital value after generating a new security media.

bacSecurityMediaStatusSubmitUserKeys

'01' Alle erforderlichen Bankverbindungsdaten und Schlüssel sind vorhanden. Das Kundensystem führt jetzt eine erstmalige Übermittlung der Kundenschlüssel wird durch. Erst nach einer erfolgreichen Übermittlung der Kundenschlüssel wird der Status auf '02' gesetzt. Siehe: I.5.2 Ersteinreichung.

bacSecurityMediaStatusActive

'02' Die RDH Sicherheitsdatei ist komplett und einsatzbereit.

bacSecurityMediaStatusBlockUserKeys

'03' Dieser Status wird geschrieben bevor vom Kundensystem eine Sperrung eingeleitet wird. Nach erfolgreicher Sperrung werden die Kundenschlüssel gelöscht und der Status auf '00' gesetzt. Siehe: I.5.4 Schlüsselsperrung.

bacSecurityMediaStatusUpdateUserKeys

'04' Dieser Status wird geschrieben bevor vom Kundensystem eine Schlüsseländerung eingeleitet wird. Nach erfolgreicher Schlüsseländerung wird der Status wieder auf '02' gesetzt. Siehe: I.5.3 Schlüsseländerung.

Enumerates the possible security media types available through the IBACSecurity::Parameter property by security components. Refer to the documentation of the IBACSecurity::Parameter property for more information about these values.

enum BACSecurityMediaTypes
{
	bacSecurityMediaFile,
	bacSecurityMediaSmartcard,
	bacSecurityMediaBTX,
	bacSecurityMediaPINTAN

};

Members

bacSecurityMediaFile

0 - The security medium is a file. The SecurityMediaID identifies the filename of the security file. In addition the SecurityMediaID may contain a UserName and other information.

bacSecurityMediaSmartcard

1 - The security medium is a smart card. The SecurityMediaID identifies the ContactIndex of the corresponding smart card entry.

bacSecurityMediaBTX

3 - This is a traditional BTX homebanking contact. This enumerator is reserved for internal use.

bacSecurityMediaPINTAN

4 - The security medium is a PIN and a TAN list. This implies that the HBCI+ protocol is used.

Enumerates the possible roles of a signer that signs a message according to HBCI 2.0.1 Kap. VI.5.2.1 Nr. 5. The signer role must be explicitly stated when invoking the method BACCustomer::AddSignature of the BACCustomer object. The values of the enumerators correspond directly with the values required by HBCI.

enum BACSignerRole
{
	bacSignerIsIssuer,
	bacSignerConfirms,
	bacSignerWitness,
	bacSignerSynchronizeCustomerSystemID,
	bacSignerSynchronizeSignatureID,
	bacSignerSubmitUserKeys

};

Members

bacSignerIsIssuer

The signer is the issuer of the message. This is the default role that is implicitly assumed by automatic signatures supplied by the BACDialog object (see Property BACDialog::AutoSignature).

bacSignerConfirms

The signer confirms the message, but is not its issuer. This is the default role for an explicit signature added by the BACCustomer object.

bacSignerWitness

The signer witnesses the contents of the message but cannot be held reponsible for it.

bacSignerSynchronizeCustomerSystemID

This special role indicates that the signer is performing a bacDialogSynchronizeCustomerSystemID dialog. This type of dialog has very special requirements for the signature.

bacSignerSynchronizeSignatureID

This special role indicates that the signer is performing a bacDialogSynchronizeSignatureID dialog. This type of dialog has very special requirements for the signature.

bacSignerSubmitUserKeys

This special role indicates that the signer is performing a bacDialogSubmitUserKeys dialog. This type of dialog has very special requirements for the signature.

Enumerates the possible states of smartcards at an chipdirve.

enum BACSmartcardState
{
	bacSmartcardNotFound,
	bacSmartcardInserted

};

Members

bacSmartcardNotFound

No smartcard is in the reader.

bacSmartcardInserted

A smartcard is in the reader.

Enumerates the possible special dialog types that can be initiated by the BACDialog::ExecuteSpecial method.

enum BACSpecialTransactionTypes
{
	bacSpecialTransactionBlockUserKeys,
	bacSpecialTransactionUpdateSignatureKey,
	bacSpecialTransactionUpdateCipheringKey

};

Members

bacSpecialTransactionBlockUserKeys

Block the user keys (HKSSP). This type of special transaction can be issued either during a bacDialogBlockUserKeys dialog or during a bacDialogBlockUserKeysAnonymous dialog.

bacSpecialTransactionUpdateSignatureKey

Update the active signature key of the user. This flag can be combined (binary or) with bacSpecialTransactionUpdateCipheringKey. This type of special transaction can be issued only during a bacDialogUpdateUserKeys dialog.

bacSpecialTransactionUpdateCipheringKey

Update the active ciphering key of the user. This flag can be combined (binary or) with bacSpecialTransactionUpdateSignatureKey. This type of special transaction can be issued only during a bacDialogUpdateUserKeys dialog.

Enumerates the possible asynchronous errors of the IBACTransport interface. The current error code can be queried through the IBACTransport::Error property. Whenever an asynchronous transport error is detected, the transport component sets the IBACTransport::Error property, switches into the bacTransError state, and invokes all appropriate callbacks.

enum BACTransportErrors
{
	bacTransOK,
	bacTransErrConnectionLost,
	bacTransErrConnectionFailed,
	bacTransErrSendFailed,
	bacTransErrReceiveFailed,
	bacTransErrCancelled

};

Members

bacTransOK

Initial value that indicates that no error was encountered so far.

bacTransErrConnectionLost

The transport connection was unexpectedly lost. This could be because the remote side did forcibly drop the transport connection, or due to some failure in the transport medium.

bacTransErrConnectionFailed

The requested connection could not be established.

bacTransErrSendFailed

A transport error occured during sending of data.

bacTransErrReceiveFailed

A transport error occured during reception of data.

bacTransErrCancelled

The transport connection was forcibly cancelled by the client.

See Also

IBACTransport, IBACTransport::Error

Enumerates constants that identify the various possible transport services. This enumeration is in accordance with HBCI.

enum BACTransportServices
{
	bacTransServiceUnknown,
	bacTransServiceTOnline,
	bacTransServiceTCPIP,
	bacTransServiceHTTP,
	bacTransServiceHTTPBase64,
	bacTransServiceWinHTTP,
	bacTransServiceCOM

};

Members

bacTransServiceUnknown

Special constant zero that is used to identify an unknown transport or an uninitialised variable of this type. This value is illegal for HBCI.

bacTransServiceTOnline

T-Online service with BTXFIF protocol. This service is currently not supported by the DDBAC.

bacTransServiceTCPIP

Raw TCP/IP service at port 3000. This is the default HBCI Internet protocol.

bacTransServiceHTTP

Tunneling of HBCI as the payload of HTTP messages. This is the version defined by the Bankverlag.

bacTransServiceHTTPBase64

Tunneling of HBCI as the payload of HTTP messages. This is the version defined by PPI. It differs from bacTransServiceHTTP as it defines a base 64 encoding for the HTTP content.

bacTransServiceWinHTTP

Same as HTTP but uses the WinHttp Library (Server) instead of WinINet (Client)

bacTransServiceCOM

the transport service is COM. messages are handed over to COM objects. the Comm Adress will be used as the COM components prog id.

Enumerates the visible states of the IBACTransport interface and thus the client transport object. The current state of the transport object can be queried through reading the IBACTransport::State property. In addition, all state changes of the transport object are announced through the IBACTransportCallback::StateChange callback method.

enum BACTransportStates
{
	bacTransIdle,
	bacTransError,
	bacTransConnecting,
	bacTransConnected,
	bacTransSending,
	bacTransReceiving,
	bacTransDisconnecting

};

Members

bacTransIdle

The transport object is disconnected and idle. In this state a new connection can be attempted by invoking (IBACTransport::Connect).

bacTransError

The transport object did abort the previous transport operation due to a communication failure. In order to cleanly recover to a known state, the communication path was disconnected. Hence, in this state a new connection can be attempted via IBACTransport::Connect. In this state the property IBACTransport::Error can be read to determine the exact cause of the failure. This state is also entered in response to a IBACTransport::Cancel request. In this case, the IBACTransport::Error property will be set to bacTransErrCancelled.

bacTransConnecting

A new connection was initiated - awaiting availability. This state is synchronously entered when the IBACTransport::Connect method did successfully initiate a connection.

bacTransConnected

A transport connection is established. This state is entered when an initiated connection (state bacTransConnecting) becomes available and whenever a IBACTransport::SendReceive completes. In this state the method IBACTransport::SendReceive may be invoked.

bacTransSending

The transport is currently sending data. This state is synchronously entered in response to IBACTransport::SendReceive. Once the entire message has been sent, the transport object automatically switches into the bacTransReceiving state.

bacTransReceiving

The transport is currently receiving data. This state is entered after all message data was successfully sent and the response message is now collected. When a complete message was received the transport switches back into the bacTransConnected state.

bacTransDisconnecting

The transport object is currently tearing down the connection due to a client request (IBACTransport::Disconnect). When the connection was completely closed, the state bacTransIdle is entered.