Class FinDataElement

Namespace: Subsembly.FinTS

Assembly: Subsembly.FinTS.Core.dll

Represents a single HBCI data element.

public class FinDataElement

Inheritance: object

FinDataElement

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

There are three kinds of data elements that can be represented by this class. Simple string data elements, binary data elements and null data elements. A null data element can be used as a placeholder that is later updated with a string or binary value. A null data element cannot be serialized into an HBCI segment data stream.

A FinDataElement instance always holds just a reference to the provided string or binary value. It never makes a copy of the value data. This is never a problem with strings, because strings are immutable. But it may be a problem with binary data, because any changes made to the provided byte array will also change the content of the FinDataElement.

Constructors

FinDataElement()

Creates a null data element.

public FinDataElement()

FinDataElement(FinByteBuffer)

Creates a binary data element from a given FinByteBuffer.

public FinDataElement(FinByteBuffer aByteBuffer)

Parameters

aByteBuffer FinByteBuffer

FinDataElement(SwiftDate)

public FinDataElement(SwiftDate aDate)

Parameters

aDate SwiftDate

FinDataElement(SwiftTime)

public FinDataElement(SwiftTime aTime)

Parameters

aTime SwiftTime

FinDataElement(bool)

Creates a simple string data element with the given boolean content.

public FinDataElement(bool fBoolData)

Parameters

fBoolData bool

FinDataElement(byte[])

Creates a binary data element from a byte array

public FinDataElement(byte[] vbBinaryData)

Parameters

vbBinaryData byte[]

Binary content of this data element. This must not be null. There is no explicit restriction on the length of the byte array, even zero length arrays are allowed.

The new FinDataElement instance will keep a reference to the provided binary data. Therefore any subsequent changes of the content of the binary data array will also change the content of this data element.

FinDataElement(byte[], int, int)

Creates a binary data element from a subrange of a given byte array.

public FinDataElement(byte[] vbBinaryData, int nOffset, int nLength)

Parameters

vbBinaryData byte[]

Byte array that contains the binary data. This must not be null.

nOffset int

Offset into the vbBinaryData byte array where the actual content data starts. Of course, this offset must lie within the bounds of the byte array.

nLength int

Length of the actual content from the vbBinaryData byte array. Offset plus length must lie within the bounds of the byte array.

FinDataElement(decimal)

Creates a simple string data element with the given decimal content.

public FinDataElement(decimal nDecimalData)

Parameters

nDecimalData decimal

FinDataElement(int)

Creates a simple string data element with the given integer content.

public FinDataElement(int nIntegerData)

Parameters

nIntegerData int

FinDataElement(long)

Creates a simple string data element with the given long integer content.

public FinDataElement(long nLongIntegerData)

Parameters

nLongIntegerData long

FinDataElement(string)

Creates a simple string data element.

public FinDataElement(string sStringData)

Parameters

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.

Properties

BinaryData

Access to the binary data of this binary data element.

public FinByteBuffer BinaryData { get; set; }

Property Value

FinByteBuffer

Remarks

Setting this property replaces the content of this data element with the given binary data. It will turn a string data element or a null data element into a binary data element.

Setting a null FinByteBuffer is not permitted. Reading this property on a null data element or a data element with string content will throw an exception. There is no explicit restriction on the size of the binary data, even zero sized binary data is allowed.

The binary data must not include the '@' length '@' prefix, as this prefix is implicitly added when the actual segment stream is generated.

IsStringData

Exceptions

InvalidOperationException: When reading this property an InvalidOperationException is thrown if this data element is not a binary data element (i.e. it is a string data element or a null data element).

BinaryDataArray

Access to the binary data array of this binary data element.

public byte[] BinaryDataArray { get; }

Property Value

byte[]

Remarks

Returns a reference to the byte array that contains the binary data. Only a subrange of this byte array contains the actual binary content of this binary data element. Therefore the properties BinaryDataOffset and BinaryDataLength must also be read in order to determine the content subrange.

IsBinaryData BinaryData BinaryDataOffset BinaryDataLength SetBinaryData(byte[]) SetBinaryData(byte[], int, int)

Exceptions

InvalidOperationException: Reading this property on a null data element or a data element with simple string content will throw an InvalidOperationException.

BinaryDataLength

Provides the length of this binary data element.

public int BinaryDataLength { get; }

Property Value

int

Remarks

There is no explicit restriction on the length of the byte array, even zero lengths are allowed.

BinaryData BinaryDataArray BinaryDataOffset

Exceptions

InvalidOperationException: Reading this property on a null data element or a data element with simple string content will throw an InvalidOperationException.

BinaryDataOffset

Starting offset of actual binary content in the byte array provided by BinaryDataArray.

public int BinaryDataOffset { get; }

Property Value

int

Remarks

BinaryData BinaryDataArray BinaryDataLength

Exceptions

InvalidOperationException: Reading this property on a null data element or a data element with simple string content will throw an InvalidOperationException.

BoolData

public bool BoolData { get; set; }

Property Value

bool

DEG

Provides the DEG position that was assigend to this data element by the FinSegment container.

public int DEG { get; }

Property Value

int

Remarks

Initially a data element has no assigned position. Only when it is put inside a FinSegment container, the container will assign a DEG,GD position to it. As long as no position was assigned, this property will have the value zero.

If a position was assigned this is the 1-based DEG position.

DateData

public SwiftDate DateData { get; set; }

Property Value

SwiftDate

DecimalData

Access this string data element as a decimal value.

public decimal DecimalData { get; set; }

Property Value

decimal

Remarks

The string representation of a decimal must contain nothing but digits and an optional single comma ',' as the fraction separator. Leading and trailing zeroes are allowed. The allowed range covers the entire range of the Decimal type.

Setting this property replaces the content of this data element with the string representation of the given decimal value. It will turn a binary data element or a null data element into a string data element.

Exceptions

InvalidOperationException: When reading this property an InvalidOperationException is thrown if this data element is not a string data element (i.e. it is a binary data element or a null data element).
FormatException: When reading this property the FormatException is thrown when the string data contains a character that is not a decimal digit.
OverflowException: When reading this property the OverflowException is thrown when the resulting value could not fit into the Decimal type.

DtaData

Access to DTAUS encoded string data element.

public string DtaData { get; set; }

Property Value

string

Remarks

Setting this property replaces the content of this data element with the DTAUS encoded equivalent of the given string. It will turn a binary data element or a null data element into a string data element.

Setting a null string is not permitted. Reading this property on a null data element or a data element with binary content will throw an exception. There is no explicit restriction on the length of the string, even zero length strings are allowed.

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

IsStringData

Exceptions

InvalidOperationException: When reading this property an InvalidOperationException is thrown if this data element is not a string data element (i.e. it is a binary data element or a null data element).

GD

Provides the GD position that was assigend to this data element by the FinSegment container.

public int GD { get; }

Property Value

int

Remarks

If a position was assigned this is the 1-based GD position inside its DEG container. If this data element is a single top-level DE, then the GD position will by 1.

DEG

IntegerData

Access this string data element as an integer value.

public int IntegerData { get; set; }

Property Value

int

Remarks

The string representation of an integer must contain nothing but digits. Leading zeroes are allowed. The numeric range of the integer value is from 0 throgh 2147483647.

Setting this property replaces the content of this data element with the string representation of the given integer value. It will turn a binary data element or a null data element into a string data element.

Exceptions

InvalidOperationException: When reading this property an InvalidOperationException is thrown if this data element is not a string data element (i.e. it is a binary data element or a null data element).
FormatException: When reading this property the FormatException is thrown when the string data contains a character that is not a decimal digit.
OverflowException: When reading this property the OverflowException is thrown when the resulting value could not fit into the positive range of an integer (Int32).

IsBinaryData

Indicates whether this is a binary data element.

public bool IsBinaryData { get; }

Property Value

bool

IsNull

Indicates whether this is a null data element.

public bool IsNull { get; }

Property Value

bool

IsStringData

Indicates whether this is a string data element.

public bool IsStringData { get; }

Property Value

bool

Length

Proides the logical length of this data element.

public int Length { get; }

Property Value

int

Remarks

The logical length is the net length of the element. For a string based element it is the length of the string without any escapes. For a binary element it is the length of the raw binary data without the '@length@' prefix. In either case it is exactly that length that is restricted by the segment syntax description.

LongIntegerData

Access this string data element as a long integer value.

public long LongIntegerData { get; set; }

Property Value

long

Remarks

The string representation of an integer must contain nothing but digits. Leading zeroes are allowed. The numeric range of the integer value is from 0 throgh 9223372036854775807.

Exceptions

InvalidOperationException: When reading this property an InvalidOperationException is thrown if this data element is not a string data element (i.e. it is a binary data element or a null data element).
FormatException: When reading this property the FormatException is thrown when the string data contains a character that is not a decimal digit.
OverflowException: When reading this property the OverflowException is thrown when the resulting value could not fit into the positive range of a long integer (Int64).

StringData

Access to the simple string data of this string data element.

public string StringData { get; set; }

Property Value

string

Remarks

Setting this property replaces the content of this data element with the value of the given string. It will turn a binary data element or a null data element into a string data element.

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

IsStringData

Exceptions

InvalidOperationException: When reading this property an InvalidOperationException is thrown if this data element is not a string data element (i.e. it is a binary data element or a null data element).

TimeData

public SwiftTime TimeData { get; set; }

Property Value

SwiftTime

Methods

SetBinaryData(byte[])

Sets the binary data content of this data elements.

public void SetBinaryData(byte[] vbBinaryData)

Parameters

vbBinaryData byte[]: Byte array that contains the binary data. Setting a null byte array is not permitted. The entire array will be used as the binary content of this binary data element.

Remarks

Setting the binary content of this data element replaces any previous content it might have had. It will turn a string data element or a null data element into a binary data element.

This FinDataElement instance keeps a reference to the provided binary data. Therefore any changes of the content of the binary data array will also change the content of this data element.

SetBinaryData(byte[], int, int)

Sets the binary data content of this data elements.

public void SetBinaryData(byte[] vbBinaryData, int nOffset, int nLength)

Parameters

vbBinaryData byte[]: Byte array that contains the binary data. Setting a null byte array is not permitted, even if the provided length is zero, too.
nOffset int: Offset into the vbBinaryData byte array where the actual content data starts. Of course, this offset must lie within the bounds of the byte array.
nLength int: Length of the actual content from the vbBinaryData byte array. Offset plus length must lie within the bounds of the byte array.

Remarks

Setting the binary content of this data element replaces any previous content it might have had. It will turn a string data element or a null data element into a binary data element.

This FinDataElement instance keeps a reference to the provided binary data. Therefore any changes of the content of the binary data array will also change the content of this data element.

SetBinaryData(byte[])