Class FinMessage

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

Manages building a FinTS request message and processing its corresponding response message.

public sealed class FinMessage
Inheritance
FinMessage
Inherited Members

Remarks

A FinMessage object is an abstraction that is reponsible for building a FinTS request message from scratch and processing the corresponding response message by associating all resonse segments with the provoking request segments.

During this course a FinMessage progresses through multiple states as described by the FinMessageState enumeration.

Constructors

FinMessage(int)

Constructs a new message.

public FinMessage(int nFinTSVersion)

Parameters

nFinTSVersion int

The FinTS version that will be used to sign and transmit this message.

Remarks

The constructed message will start out as a completely empty message in the Init state. An application may add any number of orders to this message by calling AddOrderSegment(FinSegment) and/or AddOrder(FinOrder). It is also possible to leave the message completely empty.

The property NumSignaturesRequired is initialised to zero, which means that no signature is required, but a single signature may be added by calling one of the overloaded Sign methods. If more than one signature shall be added to the constructed message, then the NumSignaturesRequired property must be set as desired BEFORE the first signature is added.

The FinTS version defines how the message must be constructed. In particular it defines the segment versions to be used for the signature, encryption, header and trailer segments. Thus, to ensure that the FinMessage class internally builds a correct FinTS message, the desired FinTS version must be provided. All signatures added to this message must be done by FinContact instances configured for that same FinTS version. Finally, the FinDialog used to transmit this message must use the very same FinTS version, too.

Properties

BankSignature

Provides the result of processing the bank signature of the parsed response message.

public FinMessageBankSignature BankSignature { get; }

Property Value

FinMessageBankSignature

DialogID

The dialog ID of the dialog that was used to send this message.

public string DialogID { get; }

Property Value

string

This property is initially null. It is set to the actual dialog ID of the dialog when the message is transmitted by the FinDialog class.

DialogTerminated

Flag that indicates whether the dialog was terminated after this message. Usually this flag is set when the response includes the status code 9800.

public bool DialogTerminated { get; }

Property Value

bool

FinTSVersion

The FinTS version that will be used to send this message.

public int FinTSVersion { get; }

Property Value

int

MessageResult

Detailed result of evaluating the message status segments.

public FinMessageResult MessageResult { get; }

Property Value

FinMessageResult

Remarks

The message result is evaluated when the message is parsed. Thus, accessing this property is just a quick value return.

MsgNo

The message sequence number that was assigned to this message when it was transmitted.

public int MsgNo { get; }

Property Value

int

This property is initially zero which is an invalid message sequence number. It is set to the actual message sequence number used, when the message is transmitted by the FinDialog class.

MustChangePin

Indicates whether the user must change his PIN.

public bool MustChangePin { get; }

Property Value

bool

Remarks

This flag is initialised to false. It is set to true whenever a "PIN change required" status code was contained in a dialog initialisation reponse message. Currently the following status codes are defined to require a PIN change: HBCI+ defines 9932 and 3932 and FinTS defines 3916. All these codes will trigger this flag to be set.

NewDefaultCustID

The new customer ID returned with status code 3072.

public string NewDefaultCustID { get; }

Property Value

string

Remarks

If a status code 3072 with a customer ID parameter was included in the response, then the new customer ID provided in the status parameter is available through this property. Otherwise it will be null.

NewUserID

The new user ID returned with status code 3072.

public string NewUserID { get; }

Property Value

string

Remarks

If a status code 3072 with a user ID parameter was included in the response, then the new user ID provided in the status parameter is available through this property. Otherwise it will be null.

NumSignaturesRequired

The number of signatures that will be applied to this message before sending.

public int NumSignaturesRequired { get; set; }

Property Value

int

Remarks

This property defaults to zero which is suitable for zero or one signature. If this message shall have two or three signatures, then this property must be set as desired before the first signature is added.

Orders

List of FinOrder derived class instances that hold the orders of this message.

public IList Orders { get; }

Property Value

IList

This property is never null. On a new FinMessage object an empty collection is returned.

Remarks

This property is for read only access to the list of orders. Orders must be added to the message through the AddOrderSegment(FinSegment) or AddOrder(FinOrder) methods.

OrphanResponseSegments

A list of response segments that could not be assigned to any of its orders.

public IList OrphanResponseSegments { get; }

Property Value

IList

OrphanStatusSegments

A list of status segments (HIRMS) that could not be assigned to any of its orders.

public IList OrphanStatusSegments { get; }

Property Value

IList

State

The current message state.

public FinMessageState State { get; }

Property Value

FinMessageState

StatusSegment

The message status segment (HIRMG) that was received for this message.

public FinStatusSegment StatusSegment { get; }

Property Value

FinStatusSegment

Success

Convenience property that provides direct access to the Success property of the StatusSegment.

public bool Success { get; }

Property Value

bool

If the message was not executed yet and no StatusSegment is available, then false is returned.

Methods

AddOrder(FinOrder)

Add an order.

public void AddOrder(FinOrder aOrder)

Parameters

aOrder FinOrder

The order to be added. If this is null, then nothing will be added.

AddOrderSegment(FinSegment)

Add an order segment to this message.

public void AddOrderSegment(FinSegment aOrderSegment)

Parameters

aOrderSegment FinSegment

The order segment to be added.

BuildStatusText(bool)

Builds a human readable text string from the status segments of this message.

public string BuildStatusText(bool fIncludeOrders)

Parameters

fIncludeOrders bool

If true, then all the status segments from the orders are included in the returned text. If false, then only the general status segment (HIRMG) and the orphan status segments are included in the returned text.

Returns

string

Human readable text created from the status segments of this message.

EvaluateMessageResult()

DEPRECATED. Use MessageResult instead.

public FinMessageResult EvaluateMessageResult()

Returns

FinMessageResult

FindOrder(int)

Find order with a particular order segment number.

public FinOrder FindOrder(int nSegNo)

Parameters

nSegNo int

Segment nmber of order segment of the order that is sought.

Returns

FinOrder

If an order with the given segment nuber was found, then its reference is returned. If no such order exists, then null is returned.

FindStatusCode(int, bool, bool)

Finds the first status with a given status code.

public FinStatus FindStatusCode(int nStatusCode, bool fSearchOrphan, bool fSearchOrders)

Parameters

nStatusCode int

The status code to look for.

fSearchOrphan bool

If true, then all the OrphanStatusSegments will be sought, too.

fSearchOrders bool

if true, then all the status segments of all orders will be sought, too.

Returns

FinStatus

If a status with the given code was found, then a FinStatus instance is returned for it. If the status code does not exist anywhere in the message, then null is returned.

Remarks

The search starts with the general StatusSegment. Next the OrphanStatusSegments are sought, if the fSearchOrphan flag was set. Finally the status segments of all orders are sought, if the fSearchOrders flag was set.

Sign(FinContact, FinSignerRole, FinSecureKey)

Sign this message with a crypto key from the given security media.

public void Sign(FinContact aContact, FinSignerRole nSignerRole, FinSecureKey aKey)

Parameters

aContact FinContact
nSignerRole FinSignerRole
aKey FinSecureKey

Sign(FinContact, FinSignerRole, int, string, string)

Sign this message with PIN and TAN.

public void Sign(FinContact aContact, FinSignerRole nSignerRole, int nSecurityFunction, string sPin, string sTan)

Parameters

aContact FinContact

FinContact that identifies the signer.

nSignerRole FinSignerRole

Role of signer.

nSecurityFunction int

The security function selects the TAN procedure. This can be obtained from the contact if not known.

sPin string

Optional PIN to be included in signature.

sTan string

Optional TAN to be included in the signature.

Exceptions

InvalidOperationException

If this FinMessage is neither in the Init nor in the Signed state.

If the given FinContact is anonymous, i.e. does not have a user ID assigned to it.

If the FinTSVersion of this message does not match the FinTSVersion of the given FinContact.