Class FinMessageBuffer
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
intThe 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
stringThe 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
intThe message number of this message. The value must be at least zero. Zero means that the message number is not known, yet.
nRefMsgNo
intThe 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
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
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
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
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
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
LastBuffer
Provides the last payload FinSegmentBuffer instance or null
if there are none.
public FinSegmentBuffer LastBuffer { get; }
Property Value
MsgNo
The message number of this message.
public int MsgNo { get; set; }
Property Value
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
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
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
FinSegmentBufferFinSegment 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
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
IFinCipherAlgorithmProvides 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
IFinCipherAlgorithmProvides 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
IFinHashAlgorithmHash 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
intIndex 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
FinSegmentBufferFinSegment 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
StreamStream 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
StreamStream 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 returnnull
.
Returns
- FinMessageBuffer
A newly created FinMessageBuffer object or
null
, if fnCheckMessage returnedfalse
.
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
intIndex 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
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
StreamDestination stream to write message buffer to.
Remarks
This is where the HNHBK header segment, and the HNHBS trailer segment are actually generated.