Class FinDialog

Namespace
Subsembly.FinTS
Assembly
Subsembly.FinTS.Core.dll

Central class for sending single messages on behalf of a particular FinContact. This is a low-level class that should rarely be used by application code. Instead the derived class FinBanking is the preferred way to run FinTS dialogs.

public class FinDialog : FinPersist, IDisposable
Inheritance
FinDialog
Implements
Derived
Inherited Members

Remarks

Before a FinTS dialog can be initialized, the static properties ProductRegisterNo and ProductVersion must have been initialized to some meaningful value. You get a FinTS product registration number from https://www.hbci-zka.de/register/prod_register.htm. These properties are not persisted and must be set with every application start.

For any kind of FinTS online dialog an instance of the FinDialog class must be created. A FinTS online dialog can then be initiated by calling InitDialog(FinDialogType, string, string, string). If InitDialog(FinDialogType, string, string, string) was successful, then the FinDialog instace is switched into the Online state. While being Online, financial orders can be sent in the context of the dialog using ExecuteOrder(FinVopOrder, FinOrder, FinTan, string, FinSignerRole). Once all desired online banking activities have been executed, the dialog should be orderly closed by calling TermDialog(). TermDialog() sends a final termination message to the bank and then closes the communication connection.

Constructors

FinDialog()

Creates a new FinDialog instance that has not been initialized.

public FinDialog()

Remarks

The FinDialog object is left completely uninitialized. In order to initialize object one of the FinPersist base class methods that load the object state can be called.

This constructor leaves the new instance in the Null State.

FinDialog(FinContact)

Creates a new FinDialog instance from a FinContact.

public FinDialog(FinContact aContact)

Parameters

aContact FinContact

Contact information that provides the context for the FinTS homebanking dialog. Must not be null.

Remarks

This constructor initializes the new instance to the Idle State.

Exceptions

ArgumentNullException

Parameter aContact was null.

Properties

BankNotices

All bank notices (HIKIM segments) that have been collected by the most recent dialog initialisation.

public FinSegments BankNotices { get; }

Property Value

FinSegments

Remarks

The collection is initially empty and is cleared in every call to InitDialog(FinDialogType, string, string, string) before the dialog is actually initialised.

CommFilter

The communication filter that shall be used by this dialog.

public IFinFilter CommFilter { get; set; }

Property Value

IFinFilter

Remarks

By default CreateFilter() will be called to create the communication filter when needed. The result will be stored here and will be used for the entire dialog. A custom implementation shall be set here before the dialog is actually begun.

CommService

The communication service that shall be used by this dialog.

public IFinCommService CommService { get; set; }

Property Value

IFinCommService

Remarks

By default CreateCommService() will be called to create the communication service when needed. The result will be stored here and will be used for the entire dialog. A custom implementation shall be set here before the dialog is actually begun.

Contact

The FinContact that was used to create this FinDialog.

public FinContact Contact { get; }

Property Value

FinContact

CustID

The FinTS customer ID of the current or most recent online dialog.

public string CustID { get; }

Property Value

string

Remarks

The FinTS customer ID is assigned in InitDialog(FinDialogType, string, string, string).

DialogID

The current or most recent FinTS dialog ID.

public string DialogID { get; }

Property Value

string

Remarks

Immediately after object creation this value is null. It is set to "0" whenever InitDialog(FinDialogType, string, string, string) is called. During dialog initialisation it is updated with the actual dialog ID that was assigned by the FinTS server in its dialog response message.

DialogType

The current or most recent FinTS dialog type.

public FinDialogType DialogType { get; }

Property Value

FinDialogType

Remarks

Immediately after object creation this value is None. It is set whenever InitDialog(FinDialogType, string, string, string) is called.

DialogTypeParam

The dialog type parameter that was passed to InitDialog(FinDialogType, string, string, string).

public string DialogTypeParam { get; }

Property Value

string

Encryption

The encryption function that is applied to all messages of this dialog.

public FinEncryption Encryption { get; }

Property Value

FinEncryption

Remarks

The required encryption function for a dialog is determined by the InitDialog(FinDialogType, string, string, string) method.

IsPinTan

Indicates whether this dialog is a PIN/TAN security based dialog.

public bool IsPinTan { get; }

Property Value

bool

Language

The language of this dialog.

public FinLanguage Language { get; set; }

Property Value

FinLanguage

Remarks

The language is initially derived from the default language selected by the DefaultLanguage property of the FinContact that was passed to the constructor.

If no default language was selected in the given FinContact, then the servers Default language is selected in the constructor.

MsgNo

The current message number. THis is incremented whenever a new dialog message is prepared.

public int MsgNo { get; }

Property Value

int

Remarks

Immediately after object creation this value is zero. It is set to zero again, whenever InitDialog(FinDialogType, string, string, string) is called. Immediately after InitDialog(FinDialogType, string, string, string) it will be one, as this is the message number that was assigned to the initialization message.

ProductRegisterNo

The registration number that was assigned to your product.

public static string ProductRegisterNo { get; set; }

Property Value

string

The registration number must not be longer than 25 characters. This must be set before a FinTS dialog can be initialized!

Exceptions

ArgumentNullException

An attempt was made to set a null value.

ArgumentException

An attempt was made to set an empty string, or a string that was longer than 25 characters.

ProductVersion

The product version string that will be sent in the HKVVB segment during dialog initialisation.

public static string ProductVersion { get; set; }

Property Value

string

The product version string must not be longer than 5 characters. This must be set before a FinTS dialog can be initialized!

Exceptions

ArgumentNullException

An attempt was made to set a null value.

ArgumentException

An attempt was made to set a string that was longer than 5 characters or empty.

ResponseTimeout

The communication service response timeout in milliseconds.

public int ResponseTimeout { get; set; }

Property Value

int

Remarks

This timeout determines the maximum waiting time for a server response after a request message was successfully transmitted. If the server does not respond within this timeout, then the operation is aborted and an error is returned to the caller. In such case, it cannot be known whether the server ever received the message and whether the contained orders have been processed.

The response timeout is initially derived from the default response timeout selected by the DefaultResponseTimeout property of the FinContact that was passed to the constructor.

If no default response timeout is provided by the FinContact, then the classic 2 minutes timeout will be set by the constructor.

The ResponseTimeout property can be changed at any time and thus can be selected individually for every order sent.

Exceptions

ArgumentOutOfRangeException

An attempt was made to set a negative or zero value.

SecurityFunction

The security function code that is used by this dialog.

public int SecurityFunction { get; }

Property Value

int

State

Indicates the dialog state that this FinDialog instance is currently in.

public FinDialogState State { get; }

Property Value

FinDialogState

TanProcess

The parameters of the TAN process that is used with this dialog.

public FinTanProcessParameters TanProcess { get; }

Property Value

FinTanProcessParameters

Remarks

This value is null if the current dialog is no PIN/TAN dialog at all, or if no special TAN process is in use.

TraceSwitch 

public static TraceSwitch TraceSwitch { get; }

Property Value

TraceSwitch

Remarks

This global TraceSwitch controls the amount of detail that is traced through the system Trace. It can be configured externally through its name "Subsembly.FinTS.TraceSwitch". The default value at construction time is TraceLevel.Off.

TraceText

Returns the HBCI tracing collected so far.

public string TraceText { get; }

Property Value

string

Methods

CancelDialog()

Cancel dialog without sending a termination message.

public virtual void CancelDialog()

Remarks

This method shall only be used in order to recover from error situations that make it impossible to send an orderly termination message via TermDialog().

If this method is called in the Idle State, then it simply does nothing.

Exceptions

ObjectDisposedException

This FinDialog instance was already disposed.

ChangePin(string)

Changes the internally cached PIN for the current dialog.

public void ChangePin(string sNewPin)

Parameters

sNewPin string

The new PIN that shall be included with all subsequent messages.

Remarks

This method must be called after a successful online PIN change in order to establish the changed PIN for subsequent messages. This method does not send a PIN change message. It is up to the caller to send a PIN change message (DKPAE or HKPAE) before calling this function.

ClearTrace()

Clears the HBCI tracing.

public void ClearTrace()

Dispose() 

public void Dispose()

Dispose(bool) 

protected virtual void Dispose(bool fDisposing)

Parameters

fDisposing bool

ExecuteMessage(FinMessage)

Executes the given message.

public void ExecuteMessage(FinMessage aMessage)

Parameters

aMessage FinMessage

Completely initialised message to be sent.

Remarks

This is a very low level method that can be used to send any type of message. Usually ExecuteOrder(FinVopOrder, FinOrder, FinTan, string, FinSignerRole) is a better choice.

ExecuteMessage is the only choice if any of the following is true:

  • A single FinTS message containing more than one order shall be sent.
  • A FinTS message with more than one signature shall be sent.
  • A FinTS message that is not signed by the Contact shall be sent.

ExecuteMessage does not support automatic handling of scroll references.

Exceptions

ArgumentNullException

The parameter aMessage was null.

ObjectDisposedException

This FinDialog instance was already disposed.

InvalidOperationException

This FinDialog instance is not Online.

ExecuteOrder(FinOrder, string)

Executes a given order.

public FinMessage ExecuteOrder(FinOrder aOrder, string sTan)

Parameters

aOrder FinOrder

Completely initialised order to be executed. This can be a simple FinOrder or any order class derived from it.

sTan string

Optional TAN that shall be sent along with this message.

Returns

FinMessage

The final FinMessage of the executed order is returned. This must be evaluated in order to determine whether execution was successful.

Remarks

Creates a new FinMessage and adds the given order to it. If this is a non-anonymous dialog type, then the message is signed by the associated Contact.

If the order status response includes a scroll reference, then the FinOrder is asked to update the order segment with the scroll reference. If it complies, then the message is sent again, including the scroll reference. This procedure repeats until no more scroll reference is included in the response status. During the process, all response data segments are added to the FinOrder such that finally the complete response data is available.

Exceptions

ArgumentNullException

The parameter aOrder was null.

ObjectDisposedException

This FinDialog instance was already disposed.

InvalidOperationException

This FinDialog instance is not Online, or a security media is attached and the parameter sTan was not null.

ExecuteOrder(FinVopOrder, FinOrder, FinTan, string, FinSignerRole)

Creates a FinMessage with the given orders, signs and executes it.

public FinMessage ExecuteOrder(FinVopOrder aVopOrder, FinOrder aOrder, FinTan aTanOrder, string sTan = null, FinSignerRole nRole = FinSignerRole.SignerIsIssuer)

Parameters

aVopOrder FinVopOrder

Optional Verification of Payee order (HKVPP, HKVOO, or HKVPA).

aOrder FinOrder

The actual business order.

aTanOrder FinTan

Optional 2-step TAN request (HKTAN).

sTan string

Optional TAN to be included in the message signature.

nRole FinSignerRole

The role of the signature. This is defaulted to SignerIsIssuer.

Returns

FinMessage

ExecuteOrderWithTanInfo(FinOrder, FinTanInfo, out FinTan)

Submits the given order along with a HKTAN segment with TAN process 4.

public FinMessage ExecuteOrderWithTanInfo(FinOrder aOrder, FinTanInfo aTanInfo, out FinTan aTanOrder)

Parameters

aOrder FinOrder

Completely initialised order to be executed. This order is only submitted an is not executed, yet. Any response data expected will only be returned after sending the actual TAN.

aTanInfo FinTanInfo

TAN information to be used for creating the additional HKTAN segment to be added to the message.

aTanOrder FinTan

This is the FinTan order object that was created from the aTanInfo. After execution it holds the result of the HITAN, which also includes the FinChallengeInfo instance returned through the HITAN segment.

Returns

FinMessage

The final FinMessage of the executed order is returned. This must be evaluated in order to determine whether execution was successful.

Remarks

Use this method in order to send any orders that require a TAN when the two-step TAN process is in use. This method does not send the actual TAN, but only starts the two-step TAN process. When successful, the returned message includes a challenge to be presented to the user.

This method creates a new FinMessage and adds the given order and a new FinTan order instance to it. A reference to the constructed and executed message is returned from this method

This method does not support scroll references! This is not as bad as it may sound, because orders requiring a TAN are usually no queries and thus return little if any data at all.

Exceptions

ObjectDisposedException

This FinDialog instance was already disposed.

InvalidOperationException

This FinDialog instance is not Online, or the DialogType is not Standard, or a security media is attached, or the SecurityFunction does not indicate use of iTAN.

ExecuteSegment(FinSegment, string)

Wraps a given segment in a default FinOrder and executes it via ExecuteOrder(FinOrder, string).

public FinMessage ExecuteSegment(FinSegment aSegment, string sTan)

Parameters

aSegment FinSegment

Fully initialised segment to be executed.

sTan string

Optional TAN that shall be sent along with this message.

Returns

FinMessage

The complete FinMessage of the executed segment is returned. This must be evaluated in order to determine whether execution was successful.

Exceptions

ArgumentNullException

The parameter aSegment was null.

ObjectDisposedException

This FinDialog instance was already disposed.

InvalidOperationException

This FinDialog instance is not Online, or a security media is attached and the parameter sTan was not null.

GetPerformanceInfo(out int, out int, out int)

Provides information about the performance of the most recent online banking operation.

public void GetPerformanceInfo(out int nSetup, out int nResponse, out int nProcess)

Parameters

nSetup int

Number of milliseconds that it took to create the complete FinTS message for sending.

nResponse int

Number of milliseconds that the FinDialog instance did wait until receiving the bank response from the communication service.

nProcess int

Number of milliseconds that it took to completely process the returned FinTS message.

Remarks

Performance information is recorded by the following FinDialog methods: InitDialog(FinDialogType, string, string, string), ExecuteOrder(FinVopOrder, FinOrder, FinTan, string, FinSignerRole), and TermDialog(). In order to gather the performance information for these methods, GetPerformanceInfo(out int, out int, out int) must be called immediately after calling the measured method. If any of these methods returns through an exception, the performance values are meaningless.

The performance values for ExecuteOrder(FinVopOrder, FinOrder, FinTan, string, FinSignerRole) are only meaningful, if no resending with a scroll reference was done.

The timing values are based on the System.Environment.TickCount property and therefore are only of platform depending limited accuracy.

InitDialog(FinDialogType, string, string, string)

Sends a single FinTS dialog initialization message.

public FinDialogResult InitDialog(FinDialogType nDialogType, string sCustID, string sPin, string sDialogTypeParam = null)

Parameters

nDialogType FinDialogType

Selects the type of dialog to be initiated. Usually this is Standard in order to select a standard dialog.

sCustID string

Optionally provides the customer ID for the dialog initialisation. If null, then the customer ID will be determined as described in the remarks section.

sPin string

If no security media is attached to the contact of this dialog, then a PIN for online authentication must be supplied in this parameter. If a security media is attached, then this parameter may be the passphrase for the security media.

sDialogTypeParam string

Optional, additional parameter for the given dialog type. The actual meaning of this parameter depends on the nDialogType. This is only used for special administration dialog types. Usually this is always null.

Returns

FinDialogResult

Returns a FinDialogResult. As a special case, this method guarantees that the initialization message is always available through the LastMessage property.

Remarks

This method determines the customer ID for the dialog initialisation as follows. If an explixit non-null customer ID is given in the sCustID parameter, it is used. If not, then the dialog type is checked. For anonymous dialogs the special customer ID "9999999999" will be used. For non-anonymous dialogs the FinContact of this FinDialog is queried for a "DefaultCustID". If a "DefaultCustID" is set, then it will be used. If no "DefaultCustID" is provided by the FinContact then the UserID of the FinContact will be used as the CustID for the dialog.

Exceptions

ArgumentOutOfRangeException

One of the arguments was outside the allowed range.

ObjectDisposedException

This FinDialog instance was already disposed.

InvalidOperationException

This FinDialog is not in the Idle State, or the security media is not Authenticated, or a security media is attached and a PIN or TAN was supplied, or no security media is attached and no PIN was supplied.

KeepAlive()

Sends HKLIF message (which is not signed and not encrypted) using the current message number (without incrementing it).

public FinDialogResult KeepAlive()

Returns

FinDialogResult

Returns a result which is either Success, or Error. In the latter case this dialog has been terminated. Only when the result indicates success, then this dialog is still valid. May also return ErrorProtocol, or Exception when an unexpected response was received from the server. If this case the dialog is also assumed to be terminated.

KeyBlock() 

public FinMessage KeyBlock()

Returns

FinMessage

KeyChange(FinSecureKey, FinSecureKey, FinSecurityProfile)

Sends a RDH key change message which may changes the security media and optionally the security profile.

public FinMessage KeyChange(FinSecureKey aNewUserAuthenticationKey, FinSecureKey aNewUserCipheringKey, FinSecurityProfile aNewSecurityProfile)

Parameters

aNewUserAuthenticationKey FinSecureKey

The new user authentication key that shall be changed to. If the key change message was positively acknowledged by the bank, then this key is elevated to the Active key state. This must not be null.

aNewUserCipheringKey FinSecureKey

The new user ciphering key that shall be changed to. If the key change message was positively acknowledged by the bank, then this key is elevated to the Active key state. This must not be null.

aNewSecurityProfile FinSecurityProfile

The new security profile to be used. This may be the same as the old security profile, if no security profile change is wanted. This must not be null.

Returns

FinMessage

Remarks

Before this method is called a dialog of type KeyChange must have been opened.

This method sends the temporary user keys from the security media that is attached to the contact. Therefore the caller must ensure that new temporary keys have been generated before this method is invoked.

ReadXml(XmlReader) 

public override void ReadXml(XmlReader aXmlReader)

Parameters

aXmlReader XmlReader

TermDialog()

Terminates and cleans up a previously initialized dialog.

public virtual FinDialogResult TermDialog()

Returns

FinDialogResult

Returns a FinDialogResult. If a HKEND message was sent,then it is available through the LastMessage property.

Remarks

If there is an active online dialog, then this method terminates it by sending a dialog termination message (HKEND) to the server. If there is no active dialog, then this method still cleans up this FinDialog instance and returns it to the Idle.

Exceptions

ObjectDisposedException

This FinDialog instance was already disposed.

WriteXml(XmlWriter) 

public override void WriteXml(XmlWriter aXmlWriter)

Parameters

aXmlWriter XmlWriter

Remarks

State
FinContact
	...
Language
ResponseTimeout
DialogID
DialogType
CustID
IsPinTan
SCA
SecurityFunction
FinTSVersion
NextMsgNo
Pin
PendingOrder
	Tag
	...