Class FinDataElement

Represents a single HBCI data element.

Inheritance

object

FinDataElement

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Subsembly.FinTS

Assembly: Subsembly.FinTS.Core.dll

Syntax

public class FinDataElement

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.

Declaration

public FinDataElement()

FinDataElement(FinByteBuffer)

Creates a binary data element from a given FinByteBuffer.

Declaration

public FinDataElement(FinByteBuffer aByteBuffer)

Parameters

Type	Name	Description
FinByteBuffer	aByteBuffer

FinDataElement(SwiftDate)

Declaration

public FinDataElement(SwiftDate aDate)

Parameters

Type	Name	Description
SwiftDate	aDate

FinDataElement(SwiftTime)

Declaration

public FinDataElement(SwiftTime aTime)

Parameters

Type	Name	Description
SwiftTime	aTime

FinDataElement(bool)

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

Declaration

public FinDataElement(bool fBoolData)

Parameters

Type	Name	Description
bool	fBoolData

FinDataElement(byte[])

Creates a binary data element from a byte array

Declaration

public FinDataElement(byte[] vbBinaryData)

Parameters

Type	Name	Description
byte[]	vbBinaryData	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.

Type

Name

Description

byte[]

vbBinaryData

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.

Declaration

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

Parameters

Type	Name	Description
byte[]	vbBinaryData	Byte array that contains the binary data. This must not be null. 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.
int	nOffset	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.
int	nLength	Length of the actual content from the vbBinaryData byte array. Offset plus length must lie within the bounds of the byte array.

Type

Name

Description

byte[]

vbBinaryData

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

int

nOffset

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.

int

nLength

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.

Declaration

public FinDataElement(decimal nDecimalData)

Parameters

Type	Name	Description
decimal	nDecimalData

FinDataElement(int)

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

Declaration

public FinDataElement(int nIntegerData)

Parameters

Type	Name	Description
int	nIntegerData

FinDataElement(long)

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

Declaration

public FinDataElement(long nLongIntegerData)

Parameters

Type	Name	Description
long	nLongIntegerData

FinDataElement(string)

Creates a simple string data element.

Declaration

public FinDataElement(string sStringData)

Parameters

Type	Name	Description
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.

Type

Name

Description

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.

Properties

BinaryData

Access to the binary data of this binary data element.

Declaration

public FinByteBuffer BinaryData { get; set; }

Property Value

Type	Description
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

Type	Condition
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.

Declaration

public byte[] BinaryDataArray { get; }

Property Value

Type	Description
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

Type	Condition
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.

Declaration

public int BinaryDataLength { get; }

Property Value

Type	Description
int

Remarks

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

BinaryData BinaryDataArray BinaryDataOffset

Exceptions

Type	Condition
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.

Declaration

public int BinaryDataOffset { get; }

Property Value

Type	Description
int

Remarks

BinaryData BinaryDataArray BinaryDataLength

Exceptions

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

BoolData

Declaration

public bool BoolData { get; set; }

Property Value

Type	Description
bool

DEG

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

Declaration

public int DEG { get; }

Property Value

Type	Description
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

Declaration

public SwiftDate DateData { get; set; }

Property Value

Type	Description
SwiftDate

DecimalData

Access this string data element as a decimal value.

Declaration

public decimal DecimalData { get; set; }

Property Value

Type	Description
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

Type	Condition
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.

Declaration

public string DtaData { get; set; }

Property Value

Type	Description
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

Type	Condition
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.

Declaration

public int GD { get; }

Property Value

Type	Description
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.

Declaration

public int IntegerData { get; set; }

Property Value

Type	Description
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

Type	Condition
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.

Declaration

public bool IsBinaryData { get; }

Property Value

Type	Description
bool

IsNull

Indicates whether this is a null data element.

Declaration

public bool IsNull { get; }

Property Value

Type	Description
bool

IsStringData

Indicates whether this is a string data element.

Declaration

public bool IsStringData { get; }

Property Value

Type	Description
bool

Length

Proides the logical length of this data element.

Declaration

public int Length { get; }

Property Value

Type	Description
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.

Declaration

public long LongIntegerData { get; set; }

Property Value

Type	Description
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

Type	Condition
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.

Declaration

public string StringData { get; set; }

Property Value

Type	Description
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

Type	Condition
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

Declaration

public SwiftTime TimeData { get; set; }

Property Value

Type	Description
SwiftTime

Methods

SetBinaryData(byte[])

Sets the binary data content of this data elements.

Declaration

public void SetBinaryData(byte[] vbBinaryData)

Parameters

Type	Name	Description
byte[]	vbBinaryData	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.

Declaration

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

Parameters

Type	Name	Description
byte[]	vbBinaryData	Byte array that contains the binary data. Setting a null byte array is not permitted, even if the provided length is zero, too.
int	nOffset	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.
int	nLength	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[])