Class FinDialog

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.

Inheritance

System.Object

FinPersist

FinDialog

FinBanking

Implements

System.IDisposable

Inherited Members

FinPersist.RootTag

FinPersist.SaveAs(String)

FinPersist.Load(String)

FinPersist.Write(Stream)

FinPersist.Read(Stream)

FinPersist.SaveXml()

FinPersist.SaveXml(String)

FinPersist.LoadXml(String)

FinPersist.ToXml(String)

FinPersist.WriteXmlDocument(XmlWriter)

FinPersist.WriteXmlDocument(XmlWriter, String)

FinPersist.ReadXmlDocument(XmlReader)

FinPersist.WriteXmlElement(XmlWriter, String, String)

FinPersist.WriteXmlElementInt(XmlWriter, String, Int32)

FinPersist.WriteXmlElementBool(XmlWriter, String, Boolean)

FinPersist.WriteXmlElementDate(XmlWriter, String, SwiftDate)

FinPersist.WriteXmlElementAcct(XmlWriter, String, FinAcct)

FinPersist.WriteXmlElementSegment(XmlWriter, String, FinSegment)

FinPersist.ReadXmlElement(XmlReader, String)

FinPersist.ReadXmlElementInt(XmlReader, String)

FinPersist.ReadXmlElementBool(XmlReader, String)

FinPersist.ReadXmlElementDate(XmlReader, String)

FinPersist.ReadXmlElementAcct(XmlReader, String)

FinPersist.ReadXmlElementSegment(XmlReader, String)

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: Subsembly.FinTS

Assembly: Subsembly.FinTS.Core.dll

Syntax

public class FinDialog : FinPersist, IDisposable

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 either of the methods ExecuteMessage(FinMessage), ExecuteSegment(FinSegment, String), or ExecuteOrder(FinOrder, String). Among them, the method ExecuteOrder(FinOrder, String) will probably the preferred choice. 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.

Declaration

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.

Declaration

public FinDialog(FinContact aContact)

Parameters

Type	Name	Description
FinContact	aContact	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

Type	Condition
System.ArgumentNullException	Parameter `aContact` was `null`.

Properties

BankNotices

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

Declaration

public FinSegments BankNotices { get; }

Property Value

Type	Description
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.

Declaration

public IFinFilter CommFilter { get; set; }

Property Value

Type	Description
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.

Declaration

public IFinCommService CommService { get; set; }

Property Value

Type	Description
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.

Declaration

public FinContact Contact { get; }

Property Value

Type	Description
FinContact

CustID

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

Declaration

public string CustID { get; }

Property Value

Type	Description
System.String

Remarks

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

DialogID

The current or most recent FinTS dialog ID.

Declaration

public string DialogID { get; }

Property Value

Type	Description
System.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.

Declaration

public FinDialogType DialogType { get; }

Property Value

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

Declaration

public string DialogTypeParam { get; }

Property Value

Type	Description
System.String

Encryption

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

Declaration

public FinEncryption Encryption { get; }

Property Value

Type	Description
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.

Declaration

public bool IsPinTan { get; }

Property Value

Type	Description
System.Boolean

Language

The language of this dialog.

Declaration

public FinLanguage Language { get; set; }

Property Value

Type	Description
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.

Declaration

public int MsgNo { get; }

Property Value

Type	Description
System.Int32

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.

Declaration

public static string ProductRegisterNo { get; set; }

Property Value

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

Exceptions

Type	Condition
System.ArgumentNullException	An attempt was made to set a `null` value.
System.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.

Declaration

public static string ProductVersion { get; set; }

Property Value

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

Exceptions

Type	Condition
System.ArgumentNullException	An attempt was made to set a `null` value.
System.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.

Declaration

public int ResponseTimeout { get; set; }

Property Value

Type	Description
System.Int32

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

Type	Condition
System.ArgumentOutOfRangeException	An attempt was made to set a negative or zero value.

SecurityFunction

The security function code that is used by this dialog.

Declaration

public int SecurityFunction { get; }

Property Value

Type	Description
System.Int32

State

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

Declaration

public FinDialogState State { get; }

Property Value

Type	Description
FinDialogState

TanProcess

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

Declaration

public FinTanProcessParameters TanProcess { get; }

Property Value

Type	Description
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

Declaration

public static TraceSwitch TraceSwitch { get; }

Property Value

Type	Description
System.Diagnostics.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.

Declaration

public string TraceText { get; }

Property Value

Type	Description
System.String

Methods

CancelDialog()

Cancel dialog without sending a termination message.

Declaration

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

Type	Condition
System.ObjectDisposedException	This FinDialog instance was already disposed.

ChangePin(String)

Changes the internally cached PIN for the current dialog.

Declaration

public void ChangePin(string sNewPin)

Parameters

Type	Name	Description
System.String	sNewPin	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.

Declaration

public void ClearTrace()

Dispose()

Declaration

public void Dispose()

Dispose(Boolean)

Declaration

protected virtual void Dispose(bool fDisposing)

Parameters

Type	Name	Description
System.Boolean	fDisposing

ExecuteMessage(FinMessage)

Executes the given message.

Declaration

public void ExecuteMessage(FinMessage aMessage)

Parameters

Type	Name	Description
FinMessage	aMessage	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 one of the methods ExecuteSegment(FinSegment, String) or ExecuteOrder(FinOrder, String) 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

Type	Condition
System.ArgumentNullException	The parameter aMessage was `null`.
System.ObjectDisposedException	This FinDialog instance was already disposed.
System.InvalidOperationException	This FinDialog instance is not Online.

ExecuteOrder(FinOrder, String)

Executes a given order.

Declaration

public FinMessage ExecuteOrder(FinOrder aOrder, string sTan)

Parameters

Type	Name	Description
FinOrder	aOrder	Completely initialised order to be executed. This can be a simple FinOrder or any order class derived from it.
System.String	sTan	Optional TAN that shall be sent along with this message.

Returns

Type	Description
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. Finally the internal equivalent of ExecuteMessage(FinMessage) is called.

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

Type	Condition
System.ArgumentNullException	The parameter aOrder was `null`.
System.ObjectDisposedException	This FinDialog instance was already disposed.
System.InvalidOperationException	This FinDialog instance is not Online, or a security media is attached and the parameter sTan was not `null`.

ExecuteOrderWithTanInfo(FinOrder, FinTanInfo, out FinTan)

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

Declaration

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

Parameters

Type	Name	Description
FinOrder	aOrder	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.
FinTanInfo	aTanInfo	TAN information to be used for creating the additional HKTAN segment to be added to the message.
FinTan	aTanOrder	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

Type	Description
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

Type	Condition
System.ObjectDisposedException	This FinDialog instance was already disposed.
System.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).

Declaration

public FinMessage ExecuteSegment(FinSegment aSegment, string sTan)

Parameters

Type	Name	Description
FinSegment	aSegment	Fully initialised segment to be executed.
System.String	sTan	Optional TAN that shall be sent along with this message.

Returns

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

Exceptions

Type	Condition
System.ArgumentNullException	The parameter aSegment was `null`.
System.ObjectDisposedException	This FinDialog instance was already disposed.
System.InvalidOperationException	This FinDialog instance is not Online, or a security media is attached and the parameter sTan was not `null`.

GetPerformanceInfo(out Int32, out Int32, out Int32)

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

Declaration

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

Parameters

Type	Name	Description
System.Int32	nSetup	Number of milliseconds that it took to create the complete FinTS message for sending.
System.Int32	nResponse	Number of milliseconds that the FinDialog instance did wait until receiving the bank response from the communication service.
System.Int32	nProcess	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), ExecuteMessage(FinMessage), ExecuteSegment(FinSegment, String), ExecuteOrder(FinOrder, String), and TermDialog(). In order to gather the performance information for these methods, GetPerformanceInfo(out Int32, out Int32, out Int32) 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(FinOrder, String) 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.

Declaration

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

Parameters

Type	Name	Description
FinDialogType	nDialogType	Selects the type of dialog to be initiated. Usually this is Standard in order to select a standard dialog.
System.String	sCustID	Optionally provides the customer ID for the dialog initialisation. If null, then the customer ID will be determined as described in the remarks section.
System.String	sPin	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 must be `null`.
System.String	sDialogTypeParam	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

Type	Description
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

Type	Condition
System.ArgumentOutOfRangeException	One of the arguments was outside the allowed range.
System.ObjectDisposedException	This FinDialog instance was already disposed.
System.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).

Declaration

public FinDialogResult KeepAlive()

Returns

Type	Description
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()

Declaration

public FinMessage KeyBlock()

Returns

Type	Description
FinMessage

KeyChange(FinSecureKey, FinSecureKey, FinSecurityProfile)

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

Declaration

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

Parameters

Type	Name	Description
FinSecureKey	aNewUserAuthenticationKey	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.
FinSecureKey	aNewUserCipheringKey	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.
FinSecurityProfile	aNewSecurityProfile	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

Type	Description
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)

Declaration

public override void ReadXml(XmlReader aXmlReader)

Parameters

Type	Name	Description
System.Xml.XmlReader	aXmlReader

Overrides

FinPersist.ReadXml(XmlReader)

TermDialog()

Terminates and cleans up a previously initialized dialog.

Declaration

public virtual FinDialogResult TermDialog()

Returns

Type	Description
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

Type	Condition
System.ObjectDisposedException	This FinDialog instance was already disposed.

WriteXml(XmlWriter)

Declaration

public override void WriteXml(XmlWriter aXmlWriter)

Parameters

Type	Name	Description
System.Xml.XmlWriter	aXmlWriter

Overrides

FinPersist.WriteXml(XmlWriter)

Remarks

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

Implements

System.IDisposable