Class FinMessageBuffer

Holds the bytes of a single HBCI message and manages the HNHBK header segment and the HNHBS trailer segment.

Inheritance

object

FinMessageBuffer

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Subsembly.FinTS

Assembly: Subsembly.FinTS.Core.dll

Syntax

public sealed class FinMessageBuffer

Constructors

FinMessageBuffer(int, string, int, int)

Creates a new and empty FinMessageBuffer.

Declaration

public FinMessageBuffer(int nFinTSVersion, string sDialogID, int nMsgNo, int nRefMsgNo = 0)

Parameters

Type	Name	Description
int	nFinTSVersion	The FinTS (or HBCI) version that this message is based upon. Syntactically this must be in the range from 0 through 999, however, it should be a version that this code actually supports. For HBCI 2.0.1 this must be 201, for HBCI 2.1 it must be 210, for HBCI 2.2 it must be 220, for FinTS 3.0 it must be 300.
string	sDialogID	The dialog ID of the dialog that this message will be sent in. This may be null if the dialog ID is not known, yet. Otherwise it must not be an empty string and must not be longer than 30 characters.
int	nMsgNo	The message number of this message. The value must be at least zero. Zero means that the message number is not known, yet.
int	nRefMsgNo	The message number of the message that this message refers to, or zero if this is a client message. Only server messages must set this to a non-zero value.

Properties

Buffers

Provides the collection of the payload FinSegmentBuffer instances.

Declaration

public IList Buffers { get; }

Property Value

Type	Description
IList

Remarks

The returned collection only includes the payload segments and excludes the header and trailer segments.

Count

Provides the total number of segments in this message buffer, including the header and trailer segments.

Declaration

public int Count { get; }

Property Value

Type	Description
int

Remarks

As the header and trailer segments are included in the returned count, a logical empty message buffer will have a Count of 2.

DialogID

The dialog ID of this message.

Declaration

public string DialogID { get; set; }

Property Value

Type	Description
string

Remarks

The dialog ID appears in the HNHBK message header segment. If the DialogID is null, then the HNHBK segment will contain the string "unbekannt" instead.

Encrypted

Determines whether this message buffer holds an encrypted FinTS message.

Declaration

public bool Encrypted { get; }

Property Value

Type	Description
bool

Remarks

An encrypted FinTS message solely consists of the two payload segments HNVSK and HNVSD. Any other message is considered to be un-encrypted and will result in a false return value.

FinTSVersion

The FinTS (or HBCI) version of this message.

Declaration

public int FinTSVersion { get; }

Property Value

Type	Description
int

Remarks

The FinTS version appears in the HNHBK message header segment. It must be defined when the FinMessageBuffer is constructed and cannot be changed thereafter.

FirstBuffer

Provides the first payload FinSegmentBuffer instance or null if there are none.

Declaration

public FinSegmentBuffer FirstBuffer { get; }

Property Value

Type	Description
FinSegmentBuffer

LastBuffer

Provides the last payload FinSegmentBuffer instance or null if there are none.

Declaration

public FinSegmentBuffer LastBuffer { get; }

Property Value

Type	Description
FinSegmentBuffer

MsgNo

The message number of this message.

Declaration

public int MsgNo { get; set; }

Property Value

Type	Description
int

Remarks

The message number appears in the HNHBK message header segment and the HNHBS message trailer segment.

RefMsgNo

The referenced message number of this message.

Declaration

public int RefMsgNo { get; }

Property Value

Type	Description
int

Remarks

A message reference may be included in the HNHBK message header of a server message. This message reference consists of a dialog ID and a referenced message number. In all cases the dialog ID of the message reference must be equal to the dialog ID of the message itself. Therefore only a referenced message number is stored in the FinMessageBuffer.

This property is zero, if this message does not reference another message. In this case the HNHBK will not include a message reference.

Signed

Indicates if the this message buffer contains at least one signature.

Declaration

public bool Signed { get; }

Property Value

Type	Description
bool

Methods

Add(FinSegmentBuffer)

Adds a payload segment buffer to the end of the payload of this message buffer.

Declaration

public void Add(FinSegmentBuffer aSegmentBuffer)

Parameters

Type	Name	Description
FinSegmentBuffer	aSegmentBuffer	FinSegment buffer that shall be added to this message buffer. Must not be null.

CheckSegmentNumbers()

Allows to check the segment numbers of an encrypted or plain message (strictly monotonically increasing) after being parsed.

Declaration

public bool CheckSegmentNumbers()

Returns

Type	Description
bool

Decrypt(byte[], IFinCipherAlgorithm)

Replaces the content of this message data with the decrypted content from the given HNVSD segment.

Declaration

public void Decrypt(byte[] vbSessionKey, IFinCipherAlgorithm aCipherAlgorithm)

Parameters

Type	Name	Description
byte[]	vbSessionKey	Session key to be used for decryption. May be null if no real decryption shall be applied.
IFinCipherAlgorithm	aCipherAlgorithm	Provides the cipher algorithm to be applied to the data in order to decrypt it. If this is null, then no decryption will be applied and the data is assumed to be plain text.

Exceptions

Type	Condition
FinParseException	If the HNVSD segment is malformed, or its encrypted data is malformed, then a FinParseException is thrown.

Encrypt(byte[], IFinCipherAlgorithm)

Encrypts all payload segment buffers into a single HNVSD segment buffer.

Declaration

public void Encrypt(byte[] vbSessionKey, IFinCipherAlgorithm aCipherAlgorithm)

Parameters

Type	Name	Description
byte[]	vbSessionKey	Session key to be used for encryption. May be null if no real encryption shall be applied.
IFinCipherAlgorithm	aCipherAlgorithm	Provides the cipher algorithm to be applied to the data in order to encrypt it. If this is null, then no encryption will be applied and the data will be inserted as plain text.

Remarks

After this operation, the payload of this message buffer consists of a single HNVSD version 1 segment with the segment number 999. Inside the encrypted data element of the HNVSD segment is the encrypted data of the previous message buffer payload.

Hash(IFinHashAlgorithm)

Compute a hash value over the net data of this message.

Declaration

public byte[] Hash(IFinHashAlgorithm aHashAlgorithm)

Parameters

Type	Name	Description
IFinHashAlgorithm	aHashAlgorithm	Hash algorithm to be used for computing the hash value. Must not be null.

Returns

Type	Description
byte[]

Exceptions

Type	Condition
ArgumentNullException	Parameter aHashAlgorithm was null.

Insert(int, FinSegmentBuffer)

Insert a payload segment buffer at the given position into this message buffer.

Declaration

public void Insert(int i, FinSegmentBuffer aSegmentBuffer)

Parameters

Type	Name	Description
int	i	Index where the segment buffer shall be inserted. The index 0 inserts the segment buffer as the first payload segment after the implicit HNHBK message header.
FinSegmentBuffer	aSegmentBuffer	FinSegment buffer that shall be inserted this message buffer. Must not be null.

Read(Stream)

Reads a complete FinTS message from a stream into a new FinMessageBuffer instance.

Declaration

public static FinMessageBuffer Read(Stream aStream)

Parameters

Type	Name	Description
Stream	aStream	Stream to read message from.

Returns

Type	Description
FinMessageBuffer	A newly created FinMessageBuffer object. Never returns null.

Exceptions

Type	Condition
ArgumentNullException	The parameter aStream was null.
FinParseException	If the input stream does not provide a syntactically valid FinTS message, then a FinParseException is thrown. Syntactically valid means, that the input stream could be dissected into segments and data elements. The content of the data elements is completely irrelevant.

Read(Stream, Func<FinMessageBuffer, long, bool>)

Reads a complete FinTS message from a stream into a new FinMessageBuffer instance.

Declaration

public static FinMessageBuffer Read(Stream aStream, Func<FinMessageBuffer, long, bool> fnCheckMessage)

Parameters

Type	Name	Description
Stream	aStream	Stream to read message from.
Func<FinMessageBuffer, long, bool>	fnCheckMessage	Optional check function that will be invoked directly after parsing the message header(HNHBK) and allows checking of message-length (as specified in HNHBK), and the parameter that were provided via the ctor for the given message buffer. fnCheckMessage signals an error by simply returning false or by throwing an exception. If fnCheckMessage returns false, Read will return null.

Returns

Type	Description
FinMessageBuffer	A newly created FinMessageBuffer object or null, if fnCheckMessage returned false.

Exceptions

Type	Condition
Exception	Possible exceptions thrown by fnCheckMessage.
ArgumentNullException	The parameter aStream was null.
FinParseException	If the input stream does not provide a syntactically valid FinTS message, then a FinParseException is thrown. Syntactically valid means, that the input stream could be dissected into segments and data elements. The content of the data elements is completely irrelevant.

RemoveAt(int)

Removes a payload segment buffer at the given position.

Declaration

public void RemoveAt(int i)

Parameters

Type	Name	Description
int	i	Index of the segment buffer that be removed. The index 0 removes the first payload segment after the implicit HNHBK message header.

ToString()

Converts the content of this message buffer into a readable string for diagnostic purposes.

Declaration

public override string ToString()

Returns

Type	Description
string

Overrides

object.ToString()

Remarks

All data elements that are known to contain a secret PIN are masked out with bullet characters in the returned string. Also, the complete data contained in a HNVSD segment is masked out with bullets. All segments are separated by Environment.Newline.

Write(Stream)

Writes the complete message buffer to the given stream.

Declaration

public void Write(Stream aStream)

Parameters

Type	Name	Description
Stream	aStream	Destination stream to write message buffer to.

Remarks

This is where the HNHBK header segment, and the HNHBS trailer segment are actually generated.