Class FinMessageBuffer

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

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

public sealed class FinMessageBuffer
Inheritance
FinMessageBuffer
Inherited Members

Constructors

FinMessageBuffer(int, string, int, int)

Creates a new and empty FinMessageBuffer.

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

Parameters

nFinTSVersion int

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.

sDialogID string

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.

nMsgNo int

The message number of this message. The value must be at least zero. Zero means that the message number is not known, yet.

nRefMsgNo int

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.

public IList Buffers { get; }

Property Value

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.

public int Count { get; }

Property Value

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.

public string DialogID { get; set; }

Property Value

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.

public bool Encrypted { get; }

Property Value

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.

public int FinTSVersion { get; }

Property Value

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.

public FinSegmentBuffer FirstBuffer { get; }

Property Value

FinSegmentBuffer

LastBuffer

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

public FinSegmentBuffer LastBuffer { get; }

Property Value

FinSegmentBuffer

MsgNo

The message number of this message.

public int MsgNo { get; set; }

Property Value

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.

public int RefMsgNo { get; }

Property Value

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.

public bool Signed { get; }

Property Value

bool

Methods

Add(FinSegmentBuffer)

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

public void Add(FinSegmentBuffer aSegmentBuffer)

Parameters

aSegmentBuffer FinSegmentBuffer

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.

public bool CheckSegmentNumbers()

Returns

bool

Decrypt(byte[], IFinCipherAlgorithm)

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

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

Parameters

vbSessionKey byte[]

Session key to be used for decryption. May be null if no real decryption shall be applied.

aCipherAlgorithm IFinCipherAlgorithm

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

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.

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

Parameters

vbSessionKey byte[]

Session key to be used for encryption. May be null if no real encryption shall be applied.

aCipherAlgorithm IFinCipherAlgorithm

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.

public byte[] Hash(IFinHashAlgorithm aHashAlgorithm)

Parameters

aHashAlgorithm IFinHashAlgorithm

Hash algorithm to be used for computing the hash value. Must not be null.

Returns

byte[]

Exceptions

ArgumentNullException

Parameter aHashAlgorithm was null.

Insert(int, FinSegmentBuffer)

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

public void Insert(int i, FinSegmentBuffer aSegmentBuffer)

Parameters

i int

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.

aSegmentBuffer FinSegmentBuffer

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.

public static FinMessageBuffer Read(Stream aStream)

Parameters

aStream Stream

Stream to read message from.

Returns

FinMessageBuffer

A newly created FinMessageBuffer object. Never returns null.

Exceptions

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.

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

Parameters

aStream Stream

Stream to read message from.

fnCheckMessage Func<FinMessageBuffer, long, bool>

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

FinMessageBuffer

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

Exceptions

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.

public void RemoveAt(int i)

Parameters

i int

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.

public override string ToString()

Returns

string

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.

public void Write(Stream aStream)

Parameters

aStream Stream

Destination stream to write message buffer to.

Remarks

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