Class FinSegment

Namespace: Subsembly.FinTS

Assembly: Subsembly.FinTS.Core.dll

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

public class FinSegment

Inheritance: object

FinSegment

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Extension Methods: FinTanProcessStepExtensions.GetTanProcessStep(FinSegment, int, int)

FinTanProcessStepExtensions.SetTanProcessStep(FinSegment, int, int, FinTanProcessStep)

Constructors

FinSegment()

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

public FinSegment()

FinSegment(string, int)

Creates an empty FinTS segment of the given segment type.

public FinSegment(string sSegmentType, int nSegmentVersion)

Parameters

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

FinSegment(string, int, int?)

Creates an empty FinTS segment of the given segment type.

public FinSegment(string sSegmentType, int nSegmentVersion, int? nRefSegNo)

Parameters

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

Properties

Elements

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

public IList Elements { get; }

Property Value

IList

this[int, int]

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

public FinDataElement this[int nDEG, int nGD] { get; set; }

Parameters

nDEG int
nGD int

Property Value

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.

public int MaxDEG { get; }

Property Value

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.

public int RefSegNo { get; set; }

Property Value

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.

public int SegNo { get; set; }

Property Value

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.

public char SegTypeIssuer { get; }

Property Value

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.

public string Type { get; set; }

Property Value

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.

public int Version { get; set; }

Property Value

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)

public bool ElementExists(int nDEG, int nGD)

Parameters

nDEG int
nGD int

Returns

bool

GenerateBytes()

public FinSegmentBuffer GenerateBytes()

Returns

FinSegmentBuffer

GetAccount(int, bool)

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

public FinAcct GetAccount(int nDEG, bool fWithSubAcctCharacteristic)

Parameters

nDEG int: The DEG position of the account data element group to be read.
fWithSubAcctCharacteristic bool: 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

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.

public SwiftAmt GetAmount(int nDEG, int nGD)

Parameters

nDEG int
nGD int

Returns

SwiftAmt

GetBalance(int, int)

Gets a balance (sdo) MVE.

public SwiftBalance GetBalance(int nDEG, int nGD = 1)

Parameters

nDEG int: The DEG that contains the balance.
nGD int: 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

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)

public FinByteBuffer GetBinaryElement(int nDEG, int nGD)

Parameters

nDEG int
nGD int

Returns

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

Exceptions

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)

public bool GetBoolElement(int nDEG, int nGD)

Parameters

nDEG int
nGD int

Returns

bool

GetDataElement(int, int)

public FinDataElement GetDataElement(int nDEG, int nGD)

Parameters

nDEG int
nGD int

Returns

FinDataElement

GetDateElement(int, int)

public SwiftDate GetDateElement(int nDEG, int nGD)

Parameters

nDEG int
nGD int

Returns

SwiftDate

GetDecimalElement(int, int)

public decimal GetDecimalElement(int nDEG, int nGD)

Parameters

nDEG int
nGD int

Returns

decimal

GetIntegerElement(int, int)

public int GetIntegerElement(int nDEG, int nGD)

Parameters

nDEG int
nGD int

Returns

int: The value of the integer data element, or zero, if the data element does not exist.

Exceptions

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.

public FinAcct GetIntlAccount(int nDEG, int nGD)

Parameters

nDEG int
nGD int: First position where to begin. In order to read a DEG that contains nothing but the "kti", this must be 1.

Returns

FinAcct

GetOptionalIntegerElement(int, int)

public int? GetOptionalIntegerElement(int nDEG, int nGD)

Parameters

nDEG int
nGD int

Returns

int?

GetSignedAmount(int, int)

Gets the amount from a btgv MVE.

public SwiftAmt GetSignedAmount(int nDEG, int nGD)

Parameters

nDEG int
nGD int

Returns

SwiftAmt

GetStringElement(int, int)

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

public string GetStringElement(int nDEG, int nGD)

Parameters

nDEG int: The 1-based DEG position of the sought data element. This must not be zero.
nGD int: 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

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)

public SwiftTime GetTimeElement(int nDEG, int nGD)

Parameters

nDEG int
nGD int

Returns

SwiftTime

GetTimestamp(int, int)

Gets a timestamp MVE (tsp)

public DateTime GetTimestamp(int nDEG, int nGD = 1)

Parameters

nDEG int: The DEG that contains the timestamp.
nGD int: 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

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.

public int MaxGD(int nDEG)

Parameters

nDEG int

Returns

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.

public int ParseBytes(FinByteBuffer aBuffer)

Parameters

aBuffer FinByteBuffer: A FinByteBuffer or a derived instance such as FinSegmentBuffer that provides the byte data to be parsed into this segment.

Returns

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.

public int ParseBytes(byte[] vbSegmentBytes, int nOffset, int nLength)

Parameters

vbSegmentBytes byte[]: Byte array that contains the HBCI segment bytes that shall be parsed.
nOffset int: Offset into byte array of the first byte to be parsed.
nLength int: Maximum number of bytes to be parsed from the given byte array. The given length must comprise a complete HBCI segment.

Returns

int: Returns the number of bytes that were parsed.

Read(Stream, int, bool)

Reads a complete segment from a stream.

public static FinSegment Read(Stream aStream, int nMaxSize, bool fSkipWhitespace)

Parameters

aStream Stream: Stream to read segment data from.
nMaxSize int: The maximum size of the segment to be read. If the segment exceeds this limit, then a FinParseException will be thrown.
fSkipWhitespace bool

Returns

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.

public void SetAccount(int nDEG, bool fWithSubAcctCharacteristic, FinAcct aAcct)

Parameters

nDEG int: The DEG position of the data element group that shall receive the account information.
fWithSubAcctCharacteristic bool: 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.
aAcct FinAcct: The account information to be set. This must not be null.

SetAmount(int, int, SwiftAmt)

public void SetAmount(int nDEG, int nGD, SwiftAmt aAmt)

Parameters

nDEG int
nGD int
aAmt SwiftAmt

SetBinaryElement(int, int, FinByteBuffer)

public void SetBinaryElement(int nDEG, int nGD, FinByteBuffer aByteBuffer)

Parameters

nDEG int
nGD int
aByteBuffer FinByteBuffer

SetBinaryElement(int, int, byte[])

public void SetBinaryElement(int nDEG, int nGD, byte[] vbBytes)

Parameters

nDEG int
nGD int
vbBytes byte[]

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

public void SetBinaryElement(int nDEG, int nGD, byte[] vbBytes, int nOffset, int nLength)

Parameters

nDEG int
nGD int
vbBytes byte[]
nOffset int
nLength int

SetBoolElement(int, int, bool)

public void SetBoolElement(int nDEG, int nGD, bool fBoolData)

Parameters

nDEG int
nGD int
fBoolData bool

SetDataElement(int, int, FinDataElement)

public void SetDataElement(int nDEG, int nGD, FinDataElement de)

Parameters

nDEG int
nGD int
de FinDataElement

SetDateElement(int, int, SwiftDate)

public void SetDateElement(int nDEG, int nGD, SwiftDate aDate)

Parameters

nDEG int
nGD int
aDate SwiftDate

SetDecimalElement(int, int, decimal)

public void SetDecimalElement(int nDEG, int nGD, decimal nDecimalData)

Parameters

nDEG int
nGD int
nDecimalData decimal

SetIntegerElement(int, int, int)

public void SetIntegerElement(int nDEG, int nGD, int nIntegerData)

Parameters

nDEG int
nGD int
nIntegerData int

SetIntlAccount(int, int, FinAcct, bool)

Set an international account data (kti) MVE.

public void SetIntlAccount(int nDEG, int nGD, FinAcct aAcct, bool fDomesticAcctAllowed)

Parameters

nDEG int
nGD int: First position where to begin. In order to fill a DEG that contains nothing but the "kti", this must be 1.
aAcct FinAcct
fDomesticAcctAllowed bool: 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.

public void SetStringElement(int nDEG, int nGD, string sStringData)

Parameters

nDEG int

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

nGD int

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.

sStringData string

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)

public void SetTimeElement(int nDEG, int nGD, SwiftTime aTime)

Parameters

nDEG int
nGD int
aTime SwiftTime

SetTimestamp(int, int, DateTime)

Sets a timestamp MVE (tsp)

public void SetTimestamp(int nDEG, int nGD, DateTime tTimestamp)

Parameters

nDEG int
nGD int
tTimestamp DateTime: 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.

public override string ToString()

Returns

string

Write(Stream)

Writes this segment to a stream.

public void Write(Stream aStream)

Parameters

aStream Stream