• API Overview
  • EBICS API
  • FinTS API
  • XS2A API
  • SEPA API
Search Results for

    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.WriteXmlElementTime(XmlWriter, String, SwiftTime)
    FinPersist.WriteXmlElementAmt(XmlWriter, String, SwiftAmt)
    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.ReadXmlElementTime(XmlReader, String)
    FinPersist.ReadXmlElementAmt(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
    In This Article
    Back to top Copyright 2009-2025 Subsembly GmbH