Class FinMessage

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

Inheritance

System.Object

FinMessage

Inherited Members

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 sealed class FinMessage

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(Int32)

Constructs a new message.

Declaration

public FinMessage(int nFinTSVersion)

Parameters

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

Declaration

public FinMessageBankSignature BankSignature { get; }

Property Value

Type	Description
FinMessageBankSignature

DialogID

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

Declaration

public string DialogID { get; }

Property Value

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

Declaration

public bool DialogTerminated { get; }

Property Value

Type	Description
System.Boolean

FinTSVersion

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

Declaration

public int FinTSVersion { get; }

Property Value

Type	Description
System.Int32

MessageResult

Detailed result of evaluating the message status segments.

Declaration

public FinMessageResult MessageResult { get; }

Property Value

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

Declaration

public int MsgNo { get; }

Property Value

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

Declaration

public bool MustChangePin { get; }

Property Value

Type	Description
System.Boolean

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.

Declaration

public string NewDefaultCustID { get; }

Property Value

Type	Description
System.String

Remarks

If a statuc 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.

Declaration

public string NewUserID { get; }

Property Value

Type	Description
System.String

Remarks

If a statuc 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.

Declaration

public int NumSignaturesRequired { get; set; }

Property Value

Type	Description
System.Int32

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.

Declaration

public IList Orders { get; }

Property Value

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

Declaration

public IList OrphanResponseSegments { get; }

Property Value

Type	Description
System.Collections.IList

OrphanStatusSegments

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

Declaration

public IList OrphanStatusSegments { get; }

Property Value

Type	Description
System.Collections.IList

State

The current message state.

Declaration

public FinMessageState State { get; }

Property Value

Type	Description
FinMessageState

StatusSegment

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

Declaration

public FinStatusSegment StatusSegment { get; }

Property Value

Type	Description
FinStatusSegment

Success

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

Declaration

public bool Success { get; }

Property Value

Type	Description
System.Boolean	If the message was not executed yet and no StatusSegment is available, then `false` is returned.

Methods

AddOrder(FinOrder)

Add an order.

Declaration

public void AddOrder(FinOrder aOrder)

Parameters

Type	Name	Description
FinOrder	aOrder	The order to be added.

AddOrderSegment(FinSegment)

Add an order segment to this message.

Declaration

public void AddOrderSegment(FinSegment aOrderSegment)

Parameters

Type	Name	Description
FinSegment	aOrderSegment	The order segment to be added.

BuildStatusText(Boolean)

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

Declaration

public string BuildStatusText(bool fIncludeOrders)

Parameters

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

Type	Description
System.String	Human readable text created from the status segments of this message.

EvaluateMessageResult()

DEPRECATED. Use MessageResult instead.

Declaration

public FinMessageResult EvaluateMessageResult()

Returns

Type	Description
FinMessageResult

FindOrder(Int32)

Find order with a particular order segment number.

Declaration

public FinOrder FindOrder(int nSegNo)

Parameters

Type	Name	Description
System.Int32	nSegNo	Segment nmber of order segment of the order that is sought.

Returns

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

Finds the first status with a given status code.

Declaration

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

Parameters

Type	Name	Description
System.Int32	nStatusCode	The status code to look for.
System.Boolean	fSearchOrphan	If `true`, then all the OrphanStatusSegments will be sought, too.
System.Boolean	fSearchOrders	if `true`, then all the status segments of all orders will be sought, too.

Returns

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

Declaration

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

Parameters

Type	Name	Description
FinContact	aContact
FinSignerRole	nSignerRole
FinSecureKey	aKey

Sign(FinContact, FinSignerRole, Int32, String, String)

Sign this message with PIN and TAN.

Declaration

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

Parameters

Type	Name	Description
FinContact	aContact	FinContact that identifies the signer.
FinSignerRole	nSignerRole	Role of signer.
System.Int32	nSecurityFunction	The security function selects the TAN procedure. This can be obtained from the contact if not known.
System.String	sPin	Optional PIN to be included in signature.
System.String	sTan	Optional TAN to be included in the signature.

Exceptions

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