Class FinSegment

A container of FinDataElement instances that holds the data of a single HBCI segment.

Inheritance
object
FinSegment
Inherited Members
Namespace: Subsembly.FinTS
Assembly: Subsembly.FinTS.Core.dll
Syntax
public class FinSegment

Constructors

FinSegment()

Creates an all empty segment to be populated with data elements later.

Declaration
public FinSegment()

FinSegment(string, int)

Creates an empty FinTS segment of the given segment type.

Declaration
public FinSegment(string sSegmentType, int nSegmentVersion)
Parameters
Type Name Description
string sSegmentType

The segment type of the new segment, e.g. "HKUEB". This must not be empty or longer than 6 characters.
int nSegmentVersion

FinSegment(string, int, int?)

Creates an empty FinTS segment of the given segment type.

Declaration
public FinSegment(string sSegmentType, int nSegmentVersion, int? nRefSegNo)
Parameters
Type Name Description
string sSegmentType

The segment type of the new segment, e.g. "HKUEB". This must not be empty or longer than 6 characters.
int nSegmentVersion
int? nRefSegNo

Optional reference segment number.

Properties

Elements

Provides the complete collection of FinDataElement instances of this segment, including the segment header elements.

Declaration
public IList Elements { get; }
Property Value
Type Description
IList

this[int, int]

Direct access to the data elements stored in this container, indexed by its DEG,GD position.

Declaration
public FinDataElement this[int nDEG, int nGD] { get; set; }
Parameters
Type Name Description
int nDEG
int nGD
Property Value
Type Description
FinDataElement
Remarks

In either case the given nDEG and nGD indices are 1-based and must not be zero or negative.

Attempting to retrieve a data element that does not exist will return a null reference.

Inserting a data element using this indexer will implicitly update the DEG and GD properties of the given data element in order to match the explicitly given nDEG and nGD indices.

MaxDEG

Provides the highest DEG position that this segment uses.

Declaration
public int MaxDEG { get; }
Property Value
Type Description
int
Remarks

For an empty segment this is still 1, as the segment header is always there.

RefSegNo

Convenient access to the reference segment number of this segment.

Declaration
public int RefSegNo { get; set; }
Property Value
Type Description
int
Remarks

This property is just a short-cut to the optional integer element at position 1,4. When setting this property the provided integer must be in the allowed range from 1 through 999.

SegNo

Convenient access to the segment number of this segment.

Declaration
public int SegNo { get; set; }
Property Value
Type Description
int
Remarks

This property is just a short-cut to the integer element at position 1,2. When setting this property the provided integer must exceed 1.

SegTypeIssuer

The issuer of this segment type. This is a single letter.

Declaration
public char SegTypeIssuer { get; }
Property Value
Type Description
char
Remarks

All FinTS defined standard segments start with the letter 'H'. Segments defined by other parties start with another letter, e.g. 'D' for Segments defined by the Sparkasse organisation. This property provides convenient access to this starting letter of the segment Type.

If the segment Type was not set, then this property returns 'H'.

Type

Convenient access to the segment type element of this segment.

Declaration
public string Type { get; set; }
Property Value
Type Description
string
Remarks

This property is just a short-cut to the string element at position 1,1. When setting this property the provided string must not be empty and must not be longer than 6 characters.

Version

Convenient access to the segment version of this segment.

Declaration
public int Version { get; set; }
Property Value
Type Description
int
Remarks

This property is just a short-cut to the integer element at position 1,3. When setting this property the provided integer must be in the allowed range from 0 through 999.

Methods

ElementExists(int, int)

Declaration
public bool ElementExists(int nDEG, int nGD)
Parameters
Type Name Description
int nDEG
int nGD
Returns
Type Description
bool

GenerateBytes()

Declaration
public FinSegmentBuffer GenerateBytes()
Returns
Type Description
FinSegmentBuffer

GetAccount(int, bool)

Reads an account data element group and returns a new FinAcct instance for it.

Declaration
public FinAcct GetAccount(int nDEG, bool fWithSubAcctCharacteristic)
Parameters
Type Name Description
int nDEG

The DEG position of the account data element group to be read.
bool fWithSubAcctCharacteristic

If this is true, then a DEG including a subaccount characteristic according to HBCI 2.2 and later will be expected. If this is false, then an old fashioned DEG is expected. Note that this flag must be appropriately set, even if the given account information does not include a subaccount characteristic, because it influences the expected overall layout of the DEG.
Returns
Type Description
FinAcct

If the data element group is nonempty and contains a syntactically valid account specification, then the account information is stored in a new FinAcct instance and returned to the caller. If the DEG is completely empty, then null is returned.

GetAmount(int, int)

Gets the amount from a btg MVE.

Declaration
public SwiftAmt GetAmount(int nDEG, int nGD)
Parameters
Type Name Description
int nDEG
int nGD
Returns
Type Description
SwiftAmt

GetBalance(int, int)

Gets a balance (sdo) MVE.

Declaration
public SwiftBalance GetBalance(int nDEG, int nGD = 1)
Parameters
Type Name Description
int nDEG

The DEG that contains the balance.
int nGD

The GD where the balance group starts inside the DEG. If omitted, then the default value is 1 which is perfect for a DEG that contains nothing but a balance.
Returns
Type Description
SwiftBalance

If the given DEG is all empty, then null is returned. If it contains a balance, then the balance is parsed and returned in a new SwiftBalance instance.

GetBinaryElement(int, int)

Declaration
public FinByteBuffer GetBinaryElement(int nDEG, int nGD)
Parameters
Type Name Description
int nDEG
int nGD
Returns
Type Description
FinByteBuffer

The binary data from the segment, wrapped by a new FinByteBuffer, or null, if the data element does not exist at all.
Exceptions
Type Condition
InvalidOperationException

If the data element is not empty and is not a binary data element (i.e. it is a non-empty string data element), then an InvalidOperationException is thrown.

GetBoolElement(int, int)

Declaration
public bool GetBoolElement(int nDEG, int nGD)
Parameters
Type Name Description
int nDEG
int nGD
Returns
Type Description
bool

GetDataElement(int, int)

Declaration
public FinDataElement GetDataElement(int nDEG, int nGD)
Parameters
Type Name Description
int nDEG
int nGD
Returns
Type Description
FinDataElement

GetDateElement(int, int)

Declaration
public SwiftDate GetDateElement(int nDEG, int nGD)
Parameters
Type Name Description
int nDEG
int nGD
Returns
Type Description
SwiftDate

GetDecimalElement(int, int)

Declaration
public decimal GetDecimalElement(int nDEG, int nGD)
Parameters
Type Name Description
int nDEG
int nGD
Returns
Type Description
decimal

GetIntegerElement(int, int)

Declaration
public int GetIntegerElement(int nDEG, int nGD)
Parameters
Type Name Description
int nDEG
int nGD
Returns
Type Description
int

The value of the integer data element, or zero, if the data element does not exist.
Exceptions
Type Condition
InvalidOperationException

If the addressed data element is a binary data element, then an InvalidOperationException is thrown.
FormatException

If the data from the data element contains a character that is not a decimal digit, then aFormatException is thrown.
OverflowException

If the resulting integer value could not fit into the positive range of an integer (Int32), then an OverflowException is thrown.

GetIntlAccount(int, int)

Get an international account data (kti) MVE.

Declaration
public FinAcct GetIntlAccount(int nDEG, int nGD)
Parameters
Type Name Description
int nDEG
int nGD

First position where to begin. In order to read a DEG that contains nothing but the "kti", this must be 1.
Returns
Type Description
FinAcct

GetOptionalIntegerElement(int, int)

Declaration
public int? GetOptionalIntegerElement(int nDEG, int nGD)
Parameters
Type Name Description
int nDEG
int nGD
Returns
Type Description
int?

GetSignedAmount(int, int)

Gets the amount from a btgv MVE.

Declaration
public SwiftAmt GetSignedAmount(int nDEG, int nGD)
Parameters
Type Name Description
int nDEG
int nGD
Returns
Type Description
SwiftAmt

GetStringElement(int, int)

Gets the string data from the string data element at the requested position.

Declaration
public string GetStringElement(int nDEG, int nGD)
Parameters
Type Name Description
int nDEG

The 1-based DEG position of the sought data element. This must not be zero.
int nGD

The 1-based GD position of the sought data element. This must not be zero. If you seek a top level DE, then use 1 as its GD position.
Returns
Type Description
string

If a string data element is found at the requested position, then its string data is returned. If no data element is found at the requested position, then null is returned. If another type of data element is found at the requested position, then a InvalidOperationException is thrown.

GetTimeElement(int, int)

Declaration
public SwiftTime GetTimeElement(int nDEG, int nGD)
Parameters
Type Name Description
int nDEG
int nGD
Returns
Type Description
SwiftTime

GetTimestamp(int, int)

Gets a timestamp MVE (tsp)

Declaration
public DateTime GetTimestamp(int nDEG, int nGD = 1)
Parameters
Type Name Description
int nDEG

The DEG that contains the timestamp.
int nGD

The GD where the timestamp group starts inside the DEG. If omitted, then the default value is 1 which is perfect for a DEG that contains nothing but a timestamp.
Returns
Type Description
DateTime

If the given DEG is all empty, then DateTime.MinValue is returned. If it contains a timestamp, then it is parsed and returned as a DateTime.

MaxGD(int)

Provides the highest GD position that is in use by a given DEG.

Declaration
public int MaxGD(int nDEG)
Parameters
Type Name Description
int nDEG
Returns
Type Description
int

The highest GD position that is in use by the given DEG. If the given DEG has no elements at all, then zero is returned.

ParseBytes(FinByteBuffer)

Parses the given byte buffer as a HBCI segment until the segment delimiter was consumed.

Declaration
public int ParseBytes(FinByteBuffer aBuffer)
Parameters
Type Name Description
FinByteBuffer aBuffer

A FinByteBuffer or a derived instance such as FinSegmentBuffer that provides the byte data to be parsed into this segment.
Returns
Type Description
int

Returns the number of bytes that were parsed.

ParseBytes(byte[], int, int)

Parses the given byte sequence as a HBCI segment until the segment delimiter was consumed.

Declaration
public int ParseBytes(byte[] vbSegmentBytes, int nOffset, int nLength)
Parameters
Type Name Description
byte[] vbSegmentBytes

Byte array that contains the HBCI segment bytes that shall be parsed.
int nOffset

Offset into byte array of the first byte to be parsed.
int nLength

Maximum number of bytes to be parsed from the given byte array. The given length must comprise a complete HBCI segment.
Returns
Type Description
int

Returns the number of bytes that were parsed.

Read(Stream, int, bool)

Reads a complete segment from a stream.

Declaration
public static FinSegment Read(Stream aStream, int nMaxSize, bool fSkipWhitespace)
Parameters
Type Name Description
Stream aStream

Stream to read segment data from.
int nMaxSize

The maximum size of the segment to be read. If the segment exceeds this limit, then a FinParseException will be thrown.
bool fSkipWhitespace
Returns
Type Description
FinSegment

If a segment was successfully read, then a new FinSegment instance that holds that segment data is returned. If the input stream was empty, then null is returned.

SetAccount(int, bool, FinAcct)

Set a complete data element group (DEG) with the given account information.

Declaration
public void SetAccount(int nDEG, bool fWithSubAcctCharacteristic, FinAcct aAcct)
Parameters
Type Name Description
int nDEG

The DEG position of the data element group that shall receive the account information.
bool fWithSubAcctCharacteristic

If this is true, then a DEG including a subaccount characteristic according to HBCI 2.2 and later will be created. If this is false, then an old fashioned DEG is created. Note that this flag must be appropriately set, even if the given account information does not include a subaccount characteristic, because it influences the overall layout of the DEG.
FinAcct aAcct

The account information to be set. This must not be null.

SetAmount(int, int, SwiftAmt)

Declaration
public void SetAmount(int nDEG, int nGD, SwiftAmt aAmt)
Parameters
Type Name Description
int nDEG
int nGD
SwiftAmt aAmt

SetBinaryElement(int, int, FinByteBuffer)

Declaration
public void SetBinaryElement(int nDEG, int nGD, FinByteBuffer aByteBuffer)
Parameters
Type Name Description
int nDEG
int nGD
FinByteBuffer aByteBuffer

SetBinaryElement(int, int, byte[])

Declaration
public void SetBinaryElement(int nDEG, int nGD, byte[] vbBytes)
Parameters
Type Name Description
int nDEG
int nGD
byte[] vbBytes

SetBinaryElement(int, int, byte[], int, int)

Declaration
public void SetBinaryElement(int nDEG, int nGD, byte[] vbBytes, int nOffset, int nLength)
Parameters
Type Name Description
int nDEG
int nGD
byte[] vbBytes
int nOffset
int nLength

SetBoolElement(int, int, bool)

Declaration
public void SetBoolElement(int nDEG, int nGD, bool fBoolData)
Parameters
Type Name Description
int nDEG
int nGD
bool fBoolData

SetDataElement(int, int, FinDataElement)

Declaration
public void SetDataElement(int nDEG, int nGD, FinDataElement de)
Parameters
Type Name Description
int nDEG
int nGD
FinDataElement de

SetDateElement(int, int, SwiftDate)

Declaration
public void SetDateElement(int nDEG, int nGD, SwiftDate aDate)
Parameters
Type Name Description
int nDEG
int nGD
SwiftDate aDate

SetDecimalElement(int, int, decimal)

Declaration
public void SetDecimalElement(int nDEG, int nGD, decimal nDecimalData)
Parameters
Type Name Description
int nDEG
int nGD
decimal nDecimalData

SetIntegerElement(int, int, int)

Declaration
public void SetIntegerElement(int nDEG, int nGD, int nIntegerData)
Parameters
Type Name Description
int nDEG
int nGD
int nIntegerData

SetIntlAccount(int, int, FinAcct, bool)

Set an international account data (kti) MVE.

Declaration
public void SetIntlAccount(int nDEG, int nGD, FinAcct aAcct, bool fDomesticAcctAllowed)
Parameters
Type Name Description
int nDEG
int nGD

First position where to begin. In order to fill a DEG that contains nothing but the "kti", this must be 1.
FinAcct aAcct
bool fDomesticAcctAllowed

If false, then only IBAN and BIC will be set. See DomesticAcctAllowed.

SetStringElement(int, int, string)

Inserts or updates a string data element at the requested position.

Declaration
public void SetStringElement(int nDEG, int nGD, string sStringData)
Parameters
Type Name Description
int nDEG

The 1-based DEG position of the sought data element. This must not be zero.
int nGD

The 1-based GD position of the sought data element. This must not be zero. If you seek a top level DE, then use 1 as its GD position.
string sStringData

Simple string content of this data element. This must not be null. There is no explicit restriction on the length of the string, even zero length strings are allowed.

The string data must not be escaped with '?' characters, as escaping is handled implicitly when the actual segment stream is parsed or generated.
Remarks

If there was a data element at the requested position and it has been replaced, then the Exists property will be true. If no data element was stored at the requested position, then the Exists property will be false

SetTimeElement(int, int, SwiftTime)

Declaration
public void SetTimeElement(int nDEG, int nGD, SwiftTime aTime)
Parameters
Type Name Description
int nDEG
int nGD
SwiftTime aTime

SetTimestamp(int, int, DateTime)

Sets a timestamp MVE (tsp)

Declaration
public void SetTimestamp(int nDEG, int nGD, DateTime tTimestamp)
Parameters
Type Name Description
int nDEG
int nGD
DateTime tTimestamp

If this is DateTime.MinValue, then nothing will be set at all. Otherwise at least the date element will be set. If the time of day portion of the timestamp is all zero, then no time element will be set. So care must be taken if you want to set a time stamp with the explicit time "00:00:00".

ToString()

Formats the segment as a string for tracing.

Declaration
public override string ToString()
Returns
Type Description
string
Overrides

Write(Stream)

Writes this segment to a stream.

Declaration
public void Write(Stream aStream)
Parameters
Type Name Description
Stream aStream

Extension Methods