Class EbicsUtil

Namespace
Subsembly.EBICS
Assembly
Subsembly.EBICS.Core.dll

Collection of static utility functions.

public static class EbicsUtil
Inheritance
EbicsUtil
Inherited Members

Fields

DSigNamespaceURI 

public const string DSigNamespaceURI = "http://www.w3.org/2000/09/xmldsig#"

Field Value

string

DSigSHA1URI 

public const string DSigSHA1URI = "http://www.w3.org/2000/09/xmldsig#sha1"

Field Value

string

DSigSHA256URI 

public const string DSigSHA256URI = "http://www.w3.org/2001/04/xmlenc#sha256"

Field Value

string

Properties

ApiVersion

Provides the version of the Subsembly EBICS API

public static Version ApiVersion { get; }

Property Value

Version

LatinEncoding 

public static Encoding LatinEncoding { get; }

Property Value

Encoding

UTF8Encoding 

public static Encoding UTF8Encoding { get; }

Property Value

Encoding

Methods

AppendElement(XmlElement, string, string, string)

Creates and appends a new child XML element.

public static XmlElement AppendElement(XmlElement xmlParent, string sElementTag, string sElementNamespace, string sElementValue)

Parameters

xmlParent XmlElement

The parent XML element where a new child XML element shall be appended to.

sElementTag string

The local name of the new XML element to be created.

sElementNamespace string

The namespace name of the namespace that the local name of the XML element is defined in.

sElementValue string

The string value of the XML element to create. This will become the InnerText of the new XML element. If this is null, then this method will do nothing (i.e. it will not append a XML element).

Returns

XmlElement

BuildReturnCodeMessage(EbicsReturnCode, EbicsReturnCode)

Builds a nice message from a technical and a business message.

public static string BuildReturnCodeMessage(EbicsReturnCode aTechnicalReturnCode, EbicsReturnCode aBusinessReturnCode)

Parameters

aTechnicalReturnCode EbicsReturnCode

The technical return code to present in the message. May be null if not present. The return code will only be included in the message if it is not EBICS_OK.

aBusinessReturnCode EbicsReturnCode

The business return code to present in the message. May be null if not present. The return code will only be included in the message if it is not EBICS_OK.

Returns

string

A nice message string suitable to be presented in a message box. Or null if there is nothing to be reported to the user.

Remarks

Builds a nice, human consumable message string from the given return codes. If both parameters are null, or hold an EBICS_OK return code, then no message is generated and null is returned instead.

BytesToXml(byte[]) 

public static XmlDocument BytesToXml(byte[] vb)

Parameters

vb byte[]

Returns

XmlDocument

CheckFingerprint(bool, EbicsPubKeyInfo, string) 

public static bool CheckFingerprint(bool fFromCertificate, EbicsPubKeyInfo aPubKey, string sFingerprint)

Parameters

fFromCertificate bool
aPubKey EbicsPubKeyInfo
sFingerprint string

String of hex digits and optional whitespace. Hex digits may be lower or upper case. If this is an empty string, contained only whitespace, or is null, then false will be returned. If it contains any invalid characters, then false will be returned.

Returns

bool

If the given sFingerprint is invalid, or does not match the public key, then false is returned. If the fingerprint matches the public key, then true is returned.

Exceptions

ArgumentNullException

The parameter aPubKey was null.

DataToXml(EbicsDataBuffer)

Loads an XML document from a raw data buffer.

public static XmlDocument DataToXml(EbicsDataBuffer d)

Parameters

d EbicsDataBuffer

Returns

XmlDocument

Exceptions

ArgumentNullException

The given parameter was null.

XmlException

The raw data buffer does not contain a valid XML document.

EvaluateOrderResult(EbicsOrder)

Evaluates order result and returns message text for it.

public static string EvaluateOrderResult(EbicsOrder aOrder)

Parameters

aOrder EbicsOrder

The order that was executed. Must not be null.

Returns

string

If the order failed, then an approrpiate, detailed error message text is returned. If the order succeeded then null is returned.

FormatDate(DateTime)

Format the given date in ISO 8601 date representation.

public static string FormatDate(DateTime tDate)

Parameters

tDate DateTime

Returns

string

If the given date is DateTime.MinValue, then null is returned. Otherwise an ISO date string according to the format "yyyy-MM-dd" is returned.

FormatDateTime(DateTime)

Format the given time stamp in EBICS dateTime format.

public static string FormatDateTime(DateTime tTimestamp)

Parameters

tTimestamp DateTime

Returns

string

Remarks

The EBICS dateTime format is specified as "YYYY-MM-DDTHH:MM:SS.sssZ".

FormatFingerprint(EbicsContact, EbicsPubKeyInfo)

Creates a multi-line formatted fingerprint text for the printed Ini-Letter or UI.

public static string FormatFingerprint(EbicsContact aContact, EbicsPubKeyInfo aPubKey)

Parameters

aContact EbicsContact

The EbicsContact for which to create the formatted fingerprint.

aPubKey EbicsPubKeyInfo

Returns

string

FormatFingerprint(EbicsContact, EbicsPubKeyInfo, EbicsFingerprintPart)

Creates a nicely formatted fingerprint for the printed Ini-Letter or UI.

public static string FormatFingerprint(EbicsContact aContact, EbicsPubKeyInfo aPubKey, EbicsFingerprintPart nPart)

Parameters

aContact EbicsContact

The EbicsContact for which to create the formatted fingerprint.

aPubKey EbicsPubKeyInfo
nPart EbicsFingerprintPart

Returns

string

FormatHex(byte[], int) 

public static string FormatHex(byte[] vb, int nColumns)

Parameters

vb byte[]
nColumns int

Returns

string

FormatHex(byte[], int, int, int) 

public static string FormatHex(byte[] vb, int nOffset, int nLength, int nColumns)

Parameters

vb byte[]
nOffset int
nLength int
nColumns int

Returns

string

FormatXml(XmlDocument)

Creates a nicely formatted string from the XML document.

public static string FormatXml(XmlDocument xmlDocument)

Parameters

xmlDocument XmlDocument

The XML document to be formatted. This must not be null.

Returns

string

GetAllKnownHosts()

Returns an array of all known Host-IDs.

public static string[] GetAllKnownHosts()

Returns

string[]

GetAttribute(XmlElement, string)

Get an attribute from an XML element. This method does never return an empty string, but will return null if an attribute is not present.

public static string GetAttribute(XmlElement xmlElement, string sAttributeName)

Parameters

xmlElement XmlElement
sAttributeName string

Returns

string

GetElement(XmlElement, string, string, bool)

Gets the InnerText from a XML element.

public static string GetElement(XmlElement xmlParent, string sElementTag, string sElementNamespace = null, bool fMandatory = false)

Parameters

xmlParent XmlElement

The parent XML element that contains the XML element to be retrieved.

sElementTag string

The local name of the XML element to be retrieved.

sElementNamespace string

The namespace name of the namespace that the local name of the XML element is defined in.

fMandatory bool

Returns

string

If the requested XML element exists, then its InnerText is returned. If the requested XML element does not exist, then null is returned.

GetKnownHostURL(string)

Looks up the URL for a given Host ID.

public static string GetKnownHostURL(string sHostID)

Parameters

sHostID string

The Host ID for which to look up an URL. Must not be null or an empty string.

Returns

string

If the Host ID is known, then the URL of that host is returned. If the Host ID is not known, then null is returned.

Remarks

This method is based on a very small hard coded list. Therefore, for most hosts it won't know the URL.

GetOrderTypeDescription(string)

Returns a descriptive text for a given EBICS order type.

public static string GetOrderTypeDescription(string sOrderType)

Parameters

sOrderType string

The EBICS order type consists of three upper case letters.

Returns

string

If the requested order type is known, then a short, descriptive text is returned. If the order type is not known, then a replacement string including the sOrderType is returned.

Exceptions

ArgumentNullException

The parameter sOrderType was null.

ArgumentException

The parameter sOrderType was an empty string.

IsAdminOrderType(string)

Returns true if the given order type is a known admistrative order type.

public static bool IsAdminOrderType(string sOrderType)

Parameters

sOrderType string

Returns

bool

Exceptions

ArgumentNullException

The parameter sOrderType was null.

ArgumentException

The given order type did not consist of exactly three upper case letters in the range from A-Z or digits.

IsBIC(string)

Check whether a string is a syntactically valid BIC.

public static bool IsBIC(string sBIC)

Parameters

sBIC string

Returns

bool

Remarks

This method does not do any semantic validation of the, it only performs some simple syntactical checks.

IsDigits(string)

Checks whether a string solely consists of digits.

public static bool IsDigits(string s)

Parameters

s string

The string to be checked.

Returns

bool

If the given string was null, then false is returned. If the given string was empty, then true is returned. If the string contains only digits, then true is returned, otherwise false is returned.

IsDigitsOrUpperAscii(string)

Checks whether a string solely consists of digits and upper ASCII characters.

public static bool IsDigitsOrUpperAscii(string s)

Parameters

s string

The string to be checked.

Returns

bool

If the given string was null, then false is returned. If the given string was empty, then true is returned. If the string contains only upper ASCII characters in the range 'A' through 'Z' or digits in the range '0' through '9', then true is returned, otherwise false is returned.

IsIBAN(string)

Check whether a string is a syntactically valid IBAN.

public static bool IsIBAN(string sIBAN)

Parameters

sIBAN string

Returns

bool

IsUpperAscii(string)

Checks whether a string solely consists of upper ASCII characters.

public static bool IsUpperAscii(string s)

Parameters

s string

The string to be checked.

Returns

bool

If the given string was null, then false is returned. If the given string was empty, then true is returned. If the string contains only upper ASCII characters in the range 'A' through 'Z', then true is returned, otherwise false is returned.

IsValidHostID(string)

Determines whether the given HostID is syntactically correct. It does not validate whether the HostID is a known HostID.

public static bool IsValidHostID(string sHostID)

Parameters

sHostID string

A HostID or null.

Returns

bool

If the HostID looks like a valid HostID, then true is returned. If the HostID is invalid or null, then false is returned.

IsValidHostURL(string) 

public static bool IsValidHostURL(string sHostURL)

Parameters

sHostURL string

Returns

bool

IsValidID(string)

Validates the ID of an EBICS party, i.e. a UserID, PartnerID or SystemID.

public static bool IsValidID(string sID)

Parameters

sID string

The ID to validate. If this is null, then false will be returned.

Returns

bool

If the ID has a valid syntax, then true is returned. Otherwise false is returned.

Remarks

Older EBICS versions did only allow up to eight upper case characters and digits in IDs according to the pattern [A-Z0-9]{1,8}. Since EBICS 2.4 the allowed range was extended according to the pattern [a-zA-Z0-9,=]{1,35}. This method validates the ID according to the new pattern.

IsValidIDChar(char)

A valid ID consists of up to 35 valid ID chars.

public static bool IsValidIDChar(char ch)

Parameters

ch char

Returns

bool

Remarks

Older EBICS versions did only allow up to eight upper case characters and digits in IDs according to the pattern [A-Z0-9]{1,8}. Since EBICS 2.4 the allowed range was extended according to the pattern [a-zA-Z0-9,=]{1,35}. This method validates the ID according to the new pattern.

IsValidOrderID(string) 

public static bool IsValidOrderID(string sOrderID)

Parameters

sOrderID string

Returns

bool

IsValidOrderType(string) 

public static bool IsValidOrderType(string sOrderType)

Parameters

sOrderType string

Returns

bool

Returns true if, and only if, the parameter is non-null and a syntactically correct order type that consists of exactly three upper case letters in the range from A-Z or digits.

NextSibling(XmlElement)

Get next XML sibling element with the same name.

public static XmlElement NextSibling(XmlElement xmlElement)

Parameters

xmlElement XmlElement

The XML element from which to find the next sibling with the same name. This must not be null.

Returns

XmlElement

If another sibling XML element is found, then it is returned. If there is no adjacent XML element sibling with the same name, then null is returned.

Remarks

This methods simplifies walking over a sequence of similar XML elements. While looking for the next XML element sibling it skips over all whitespace and comment nodes that may appear in between.

ParseDate(string)

Tries to parse a given ISO 8601 date representation.

public static DateTime ParseDate(string sDate)

Parameters

sDate string

The date string to be parsed. Only the date portion of this string is parsed, any time specification is ignored. If the parameter is null, then the value DateTime.MinValue is returned.

Returns

DateTime

Exceptions

FormatException

ParseDateTime(string)

Parses an ISO date and time specification with time zone information.

public static DateTime ParseDateTime(string sDateTime)

Parameters

sDateTime string

The string to parse. Whitespace will be trimmed from this string, before it is parsed. If the resulting string is null or empty, then DateTime.MinValue will be returned.

Returns

DateTime

Exceptions

FormatException

The parameter sDateTime contains a malformed ISO date string.

SetAttribute(XmlElement, string, string) 

public static void SetAttribute(XmlElement xmlElement, string sAttributeName, string sAttributeValue)

Parameters

xmlElement XmlElement
sAttributeName string
sAttributeValue string

Squeeze(string)

Removes all the whitespaces in the specified string and returns the cleaned string.

public static string Squeeze(string s)

Parameters

s string

Returns

string

If the parameter was null, then this method returns null. In any other case, it returnes the cleaned, maybe all empty, string.

StreamToXml(Stream) 

public static XmlDocument StreamToXml(Stream aStream)

Parameters

aStream Stream

Stream to read XML document from. This stream will not be closed.

Returns

XmlDocument

Trim(string)

Trims whitespace from a string.

public static string Trim(string s)

Parameters

s string

String to be trimmed. May be null.

Returns

string

If the parameter s was null, then null is returned, otherwise the trimmed string is returned. If the given string consists solely of whitespace, then an empty string will be returned.

See Also

Trim(string, int)

Trims whitespace from a string.

public static string Trim(string s, int nMaxLength)

Parameters

s string

String to be trimmed. May be null.

nMaxLength int

The max length of the trimmed string to be returned. If the string is longer than this max length, then it is truncated at the max length.

Returns

string

TryParseDateTime(string)

Tries to parse an ISO date and time specification with time zone information.

public static DateTime TryParseDateTime(string sDateTime)

Parameters

sDateTime string

The string to parse. Whitespace will be trimmed from this string, before it is parsed. If the resulting string is null or empty, then DateTime.MinValue will be returned.

Returns

DateTime

Remarks

This method does not throw an exception, when the given sDateTime is malformed. Instead it just returns DateTime.MinValue.

XmlToBytes(XmlDocument) 

public static byte[] XmlToBytes(XmlDocument xmlDocument)

Parameters

xmlDocument XmlDocument

Returns

byte[]

XmlToData(XmlDocument)

Serializes an XML document into a raw data buffer.

public static EbicsDataBuffer XmlToData(XmlDocument xmlDocument)

Parameters

xmlDocument XmlDocument

Returns

EbicsDataBuffer

Exceptions

ArgumentNullException

The given parameter was null.

XmlToStream(XmlDocument, Stream)

Serializes an XML document into the given byte stream.

public static void XmlToStream(XmlDocument xmlDocument, Stream aStream)

Parameters

xmlDocument XmlDocument
aStream Stream

The stream to write the XML document to. This stream will not be closed!

Remarks

The document will be written using UTF-8 encoding and will not have a byte order mark.