Class EbicsContact

Collects all information required for EBICS communication of a particular user with a particular bank.

Inheritance

System.Object

EbicsElement

EbicsContact

Implements

IEbicsJsonConverter

Inherited Members

EbicsElement.BuildXmlDocument(EbicsVersion)

EbicsElement.Load(Stream, EbicsVersion)

EbicsElement.Load(String, EbicsVersion)

EbicsElement.Save(Stream, EbicsVersion)

EbicsElement.Save(String, EbicsVersion)

EbicsElement.FromBuffer(EbicsDataBuffer, EbicsVersion)

EbicsElement.ToBuffer(EbicsVersion)

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

Namespace: Subsembly.EBICS

Assembly: Subsembly.EBICS.Core.dll

Syntax

public sealed class EbicsContact : EbicsElement, IEbicsJsonConverter

Remarks

Whenever a property is changed the complete contact data is re-saved in it's ContactFolder. Thus, in order to optimize updating multiple properties the method BeginUpdate() should be called before, and the method EndUpdate() should be called after changing the properties. This ensures that the contact data is only saved once at the end of the update.

Constructors

EbicsContact()

Declaration

public EbicsContact()

EbicsContact(EbicsContact)

Creates a new EbicsContact using another EbicsContact as an initialisation template.

Declaration

public EbicsContact(EbicsContact aContact)

Parameters

Type	Name	Description
EbicsContact	aContact

Remarks

As it is a new EbicsContact it is initialised with a new ContactGuid. The new contact is not added to an IEbicsContactFolder. None of user or bank keys are copied to the newly created contact.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter `aContact`was `null`.

EbicsContact(EbicsVersion)

Creates an all new EBICS contact from scratch.

Declaration

public EbicsContact(EbicsVersion nVersion)

Parameters

Type	Name	Description
EbicsVersion	nVersion	The EBICS version for which to create a new contact. Use the value Default to create a contact for the recommended default EBICS version.

Fields

DEFAULTHOSTTIMEOUT

The default host response timeout in milliseconds.

Declaration

public const int DEFAULTHOSTTIMEOUT = 60000

Field Value

Type	Description
System.Int32

MAXHOSTIDLENGTH

Maximum length of HostID (=35).

Declaration

public const int MAXHOSTIDLENGTH = 35

Field Value

Type	Description
System.Int32

Remarks

In earlier EBICS versions the maximum length of the HostID was defined as 8 characters. In the current version it is 35 characters, which is the value that is defined here.

MAXPARTNERIDLENGTH

Maximum length of PartnerID (=35).

Declaration

public const int MAXPARTNERIDLENGTH = 35

Field Value

Type	Description
System.Int32

Remarks

In earlier EBICS versions the maximum length of the PartnerID was defined as 8 characters. In the current version it is 35 characters, which is the value that is defined here.

MAXSYSTEMIDLENGTH

Maximum length of SystemID (=35).

Declaration

public const int MAXSYSTEMIDLENGTH = 35

Field Value

Type	Description
System.Int32

Remarks

In earlier EBICS versions the maximum length of the SystemID was defined as 8 characters. In the current version it is 35 characters, which is the value that is defined here.

MAXUSERIDLENGTH

Maximum length of UserID (=35).

Declaration

public const int MAXUSERIDLENGTH = 35

Field Value

Type	Description
System.Int32

Remarks

In earlier EBICS versions the maximum length of the UserID was defined as 8 characters. In the current version it is 35 characters, which is the value that is defined here.

Properties

AuthenticationVersion

Declaration

public EbicsSecurityCode AuthenticationVersion { get; set; }

Property Value

Type	Description
EbicsSecurityCode

BankAuthenticationPubKey

Declaration

public EbicsPubKeyInfo BankAuthenticationPubKey { get; set; }

Property Value

Type	Description
EbicsPubKeyInfo

BankEncryptionPubKey

Declaration

public EbicsPubKeyInfo BankEncryptionPubKey { get; set; }

Property Value

Type	Description
EbicsPubKeyInfo

CanCreateIniLetter

Indicates whether all information and public keys that are needed by CreateIniLetter(String, String) is available in this contant.

Declaration

public bool CanCreateIniLetter { get; }

Property Value

Type	Description
System.Boolean

ContactFolder

The ContactFolder from which this EbicsContact instance was loaded.

Declaration

public IEbicsContactFolder ContactFolder { get; set; }

Property Value

Type	Description
IEbicsContactFolder

ContactGuid

A GUID that uniquely identifies this contact.

Declaration

public Guid ContactGuid { get; }

Property Value

Type	Description
System.Guid

Remarks

This property is managed automatically by the EbicsContact class and therefore can only be read. A newly created EbicsContact will always get a new GUID. If an EbicsContact instance is stored, its GUID is stored with it, and also restored when loaded.

This GUID is used as the primary key when storing an EbicsContact in an IEbicsContactFolder.

ContactName

Optional human readable contact name.

Declaration

public string ContactName { get; set; }

Property Value

Type	Description
System.String	The contact name may be `null` or a nonempty string of up to 256 characters. The default value of this property is `null`.

Exceptions

Type	Condition
System.ArgumentException	An attempt was made to set an empty contact name string.

CountryCode

Two letter ISO country code. If this is not set, then "DE" will be assumed.

Declaration

public string CountryCode { get; set; }

Property Value

Type	Description
System.String

Remarks

The country code is needed to adopt to national variations in the EBICS implementation. In particular it is needed to enable keys with certificates in France.

DefaultAuthorisationLevel

The default authorisation level for signatures created by this user.

Declaration

public EbicsAuthorisationLevel DefaultAuthorisationLevel { get; set; }

Property Value

Type	Description
EbicsAuthorisationLevel

Remarks

This authorisation level is only applied, if the AuthorisationLevel was not explicitly set. If this is Null, then a default signature will be assumed by Send(EbicsOrder, IEbicsSecurityMedium, IEbicsTransport).

EncryptionVersion

Declaration

public EbicsSecurityCode EncryptionVersion { get; set; }

Property Value

Type	Description
EbicsSecurityCode

HaveBankKeys

Declaration

public bool HaveBankKeys { get; }

Property Value

Type	Description
System.Boolean

HaveUserKeys

Declaration

public bool HaveUserKeys { get; }

Property Value

Type	Description
System.Boolean

HostID

Declaration

public string HostID { get; set; }

Property Value

Type	Description
System.String

HostTimeout

Response timeout for each message in milliseconds.

Declaration

public int HostTimeout { get; set; }

Property Value

Type	Description
System.Int32	Time in milliseconds. Must not be negative. The value zero means that the timeout is not set, and thus the DEFAULTHOSTTIMEOUT shall be used.

Remarks

After sending a request message to the EBICS host, the transaction engine will at most wait HostTimeout milliseconds for a response message from the EBICS host. If the EBICS host does not respond within this timeout, then the transaction is aborted.

HostURL

The complete URL to the EBICS host including the https: prefix.

Declaration

public string HostURL { get; set; }

Property Value

Type	Description
System.String

IniLetterNeeded

Stored flag that indicates whether an Ini-Letter must probably be sent for this contact.

Declaration

public bool IniLetterNeeded { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

This is just a stored flag and no real indication of the user state. The flag is set, whenever all new keys are created for the user. It is reset, whenever an Ini-Letter is generated.

Parameters

Collection of additional custom parameters

Declaration

public EbicsParameters Parameters { get; }

Property Value

Type	Description
EbicsParameters

Remarks

This EbicsParameters collection can be used to store additional custom parameters with this contact.

PartnerID

Declaration

public string PartnerID { get; set; }

Property Value

Type	Description
System.String

SecurityMedium

The value for the EBICS SecurityMedium XML element.

Declaration

public string SecurityMedium { get; set; }

Property Value

Type	Description
System.String

SecurityMediumAssemblyName

Optional name of assembly that contains a custom implementation of the IEbicsSecurityMedium interface for this contact.

Declaration

public string SecurityMediumAssemblyName { get; set; }

Property Value

Type	Description
System.String

SecurityMediumClassName

Name of class that implements the IEbicsSecurityMedium interface for this contact.

Declaration

public string SecurityMediumClassName { get; set; }

Property Value

Type	Description
System.String	If this is `null`, then a default implementation based on the SecurityMediumType will be used. The default value is `null`

SecurityMediumID

Declaration

public string SecurityMediumID { get; set; }

Property Value

Type	Description
System.String

SecurityMediumType

Selects the implementation of the user's security medium.

Declaration

public EbicsSecurityMediumType SecurityMediumType { get; set; }

Property Value

Type	Description
EbicsSecurityMediumType

ServiceMap

The EbicsServiceMap that shall be used with this contact.

Declaration

public EbicsServiceMap ServiceMap { get; set; }

Property Value

Type	Description
EbicsServiceMap

Remarks

This value is temporary and is not persisted. It must be set again whenever a EbicsContact is loaded.

If the ServiceMap is not set, then a well known service map for the CountryCode will be returned, if available. If there is no well known service map, then the universal Default service map will be returned. Hence, the return value is never null.

SignatureVersion

Declaration

public EbicsSecurityCode SignatureVersion { get; set; }

Property Value

Type	Description
EbicsSecurityCode

SpoolerActions

Chooses whether this contact opts-in to automated EBICS Spooler processing.

Declaration

public EbicsFileSpoolerActions SpoolerActions { get; set; }

Property Value

Type	Description
EbicsFileSpoolerActions	By default all contacts are excluded from automated EBICS Spooler processing. This boolean must be set in order to opt-in.

SpoolerOrderTypeC52

The classic EBICS order type that the EBICS spooler uses for CAMT 052 downloads.

Declaration

public string SpoolerOrderTypeC52 { get; set; }

Property Value

Type	Description
System.String	If this is `null`, then the default "C52" is used. This may be set to "VMK" to download SWIFT MT-942 and have it converted automatically to CAMT 052.

Exceptions

Type	Condition
System.ArgumentException	An attempt was made to set a non-null value that is not a valid order type.

SpoolerOrderTypeC53

The classic EBICS order type that the EBICS spooler uses for CAMT 053 downloads.

Declaration

public string SpoolerOrderTypeC53 { get; set; }

Property Value

Type	Description
System.String	If this is `null`, then the default "C53" is used. This may be set to "STA" to download SWIFT MT-940 and have it converted automatically to CAMT 053.

Exceptions

Type	Condition
System.ArgumentException	An attempt was made to set a non-null value that is not a valid order type.

SpoolerOrderTypeC54

The classic EBICS order type that the EBICS spooler uses for CAMT 054 downloads.

Declaration

public string SpoolerOrderTypeC54 { get; set; }

Property Value

Type	Description
System.String	If this is `null`, then the default "C54" is used.

Exceptions

Type	Condition
System.ArgumentException	An attempt was made to set a non-null value that is not a valid order type.

SpoolerOrderTypeHAC

The classic EBICS order type that the EBICS spooler uses for EBICS protocol downloads.

Declaration

public string SpoolerOrderTypeHAC { get; set; }

Property Value

Type	Description
System.String	If this is `null`, then the default "HAC" is used. This may be set to "PTK" to download old style text protocols.

Exceptions

Type	Condition
System.ArgumentException	An attempt was made to set a non-null value that is not a valid order type.

SpoolerSecret

This field is reserved for the EBICS spooler to store secret data needed for execution.

Declaration

public string SpoolerSecret { get; set; }

Property Value

Type	Description
System.String	This value is only meaningful to the EbicsFileSpooler. To store a password the EbicsFileSpooler method StorePassword(EbicsContact, String) must be used. A masked password pattern for the stored password can be obtained via GetPasswordPlaceholder(EbicsContact). Setting this property to `null` effectively clears any stored password.

SystemID

Declaration

public string SystemID { get; set; }

Property Value

Type	Description
System.String

UserAuthenticationPubKey

Declaration

public EbicsPubKeyInfo UserAuthenticationPubKey { get; }

Property Value

Type	Description
EbicsPubKeyInfo

UserEncryptionPubKey

Declaration

public EbicsPubKeyInfo UserEncryptionPubKey { get; }

Property Value

Type	Description
EbicsPubKeyInfo

UserID

Declaration

public string UserID { get; set; }

Property Value

Type	Description
System.String

UserSignaturePubKey

Declaration

public EbicsPubKeyInfo UserSignaturePubKey { get; }

Property Value

Type	Description
EbicsPubKeyInfo

UsesCertificates

Indicates whether this EBICS user uses keys with X.509 certificates.

Declaration

public bool UsesCertificates { get; }

Property Value

Type	Description
System.Boolean

Remarks

Starting with EBICS 3.0 the usage of X.509 certificates is mandatory. When connecting to a French system, X.509 certificates are also mandatory for older EBICS versions.

Version

Declaration

public EbicsVersion Version { get; set; }

Property Value

Type	Description
EbicsVersion

Methods

AdoptSecurityKeyFile(String, String, Boolean, Boolean, out String)

Adopt the given key file as the security medium for this EbicsContact.

Declaration

public bool AdoptSecurityKeyFile(string sKeyFilePath, string sKeyFilePassword, bool fAdoptContact, bool fInternalizeKeyFile, out string sErrorMessage)

Parameters

Type	Name	Description
System.String	sKeyFilePath	Complete path and filename to the key file to be adopted. The EbicsContact will store a reference to this path, so the key file must remain at this location, even after it was adopted, unless the parameter fInternalizeKeyFile was `true`.
System.String	sKeyFilePassword
System.Boolean	fAdoptContact	If `true`, then an attempt is made to read EBICS contact data (HostID, UserID, etc.) from the key file. The contact data from the key file will overwrite the existing contact data in this contact.
System.Boolean	fInternalizeKeyFile	If `true`, then all key data, including the private keys, will be imported into this contact. The external key file is no longer needed after the key file was imported. The internalized key file will still require the entry of the same key file password.
System.String	sErrorMessage

Returns

Type	Description
System.Boolean

AdoptSecurityMedium(IEbicsSecurityMedium)

Adopt the given security medium for this EbicsContact.

Declaration

public void AdoptSecurityMedium(IEbicsSecurityMedium aSecurityMedium)

Parameters

Type	Name	Description
IEbicsSecurityMedium	aSecurityMedium	The security medium that shall be adopted. This can be in any state. It is NOT released by this method. It is up to the caller to release the security when he is done with it.

Remarks

This method will set all security and security medium related properties of this instance to effectively adopt the given security medium. It may also change the Version if needed to match the security medium.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter `aSecurityMedium` was `null`.

Authenticate(String)

Obtains a new authenticated security medium instance for this contact.

Declaration

public IEbicsSecurityMedium Authenticate(string sPassword)

Parameters

Type	Name	Description
System.String	sPassword	The password (or PIN) that shall be used to authenticate the security medium configured for this contact.

Returns

Type	Description
IEbicsSecurityMedium	Always returns an authenticated IEbicsSecurityMedium instance. This never returns `null`, as errors are thrown as exceptions.

Exceptions

Type	Condition
System.InvalidOperationException	No security medium is configured for this contact.
EbicsException	If the security medium could not be authenticated, then an EbicsException will be thrown.

BeginUpdate()

Begin a series of property changes.

Declaration

public void BeginUpdate()

Remarks

Changing multiple properties should be optimized by calling this method before changing the properties and EndUpdate() after changing the properties.

BlockKeys(IEbicsSecurityMedium, IEbicsTransport)

Creates an EbicsOrderSPR instance and uses it to block the users keys at the bank (SPR).

Declaration

public EbicsOrderSPR BlockKeys(IEbicsSecurityMedium aSecMedium, IEbicsTransport aTransport = null)

Parameters

Type	Name	Description
IEbicsSecurityMedium	aSecMedium	Authenticated security medium of the user. Must not be `null`.
IEbicsTransport	aTransport	An IEbicsTransport implementation for sending the HTTP request. If this is `null`, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

Returns

Type	Description
EbicsOrderSPR	Returns the created EbicsOrderSPR instance. This can be used to check whether the request was successful.

BuildXml(XmlDocument, EbicsVersion)

Declaration

public override XmlElement BuildXml(XmlDocument xmlDocument, EbicsVersion nEbicsVersion)

Parameters

Type	Name	Description
System.Xml.XmlDocument	xmlDocument
EbicsVersion	nEbicsVersion	The given EBICS version is currently ignored but should be Contact in order to ensure compatibility with future versions.

Returns

Type	Description
System.Xml.XmlElement

Overrides

EbicsElement.BuildXml(XmlDocument, EbicsVersion)

Remarks

This method always builds an XML element according to its own rules using an unnamed default namespace.

ChangeKeys(IEbicsSecurityMedium, EbicsSecurityCode, EbicsSecurityCode, EbicsSecurityCode, IEbicsTransport)

Creates a complete set of new user keys (signature, authentication and encryption) and initiates a user key update via HCS upload order.

Declaration

public EbicsOrderHCS ChangeKeys(IEbicsSecurityMedium aSecMedium, EbicsSecurityCode nSignatureVersion, EbicsSecurityCode nAuthenticationVersion, EbicsSecurityCode nEncryptionVersion, IEbicsTransport aTransport = null)

Parameters

Type	Name	Description
IEbicsSecurityMedium	aSecMedium	Authenticated security medium of the user for the new keys. Must not be `null`. This security medium must implement IEbicsSecurityMediumPrivKeys, hence smart cards are not supported.
EbicsSecurityCode	nSignatureVersion	New User Signature Key Version. This must be either A004, A005, or A006. If this contact already uses H005, or later, then A004 is not allowed.
EbicsSecurityCode	nAuthenticationVersion	The Version of the new Authentication Key. This must be either X001, or X002.
EbicsSecurityCode	nEncryptionVersion	The Version of the new Encryption Key. This must be either E001, or E002.
IEbicsTransport	aTransport	An IEbicsTransport implementation for sending the HTTP request. If this is `null`, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

Returns

Type	Description
EbicsOrderHCS

Exceptions

Type	Condition
System.ArgumentNullException	Either `aSecMedium` or `aTransport` was `null`.
System.ArgumentException	An invalid value for `nSignatureVersion`, `nAuthenticationVersion`, or `nEncryptionVersion` was given.
System.InvalidOperationException	The given `aSecMedium` does not support management of private keys.

ChangeSystemKeys(IEbicsSecurityMedium, EbicsSecurityCode, EbicsSecurityCode, IEbicsTransport)

Creates an EbicsOrderHCA instance and uses it to change the system keys (HCA)

Declaration

public EbicsOrderHCA ChangeSystemKeys(IEbicsSecurityMedium aSecMedium, EbicsSecurityCode nAuthenticationVersion, EbicsSecurityCode nEncryptionVersion, IEbicsTransport aTransport = null)

Parameters

Type	Name	Description
IEbicsSecurityMedium	aSecMedium	Authenticated security medium of the user. Must not be `null`. This security medium must implement IEbicsSecurityMediumPrivKeys, hence smart cards are not supported.
EbicsSecurityCode	nAuthenticationVersion	The Version of the new Authentication Key. This must be either X001, or X002.
EbicsSecurityCode	nEncryptionVersion	The Version of the new Encryption Key. This must be either E001, or E002.
IEbicsTransport	aTransport	An IEbicsTransport implementation for sending the HTTP request. If this is `null`, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

Returns

Type	Description
EbicsOrderHCA	Returns the EbicsOrderHCA that was built and sent. This can be used to determine whether the key change transaction was successful.

Exceptions

Type	Condition
System.ArgumentNullException	Either `aSecMedium` or `aTransport` was `null`.
System.ArgumentException	An invalid value for `nAuthenticationVersion` or `nEncryptionVersion` was given.
System.InvalidOperationException	The given `aSecMedium` does not support management of private keys.

ChangeUserKey(IEbicsSecurityMedium, EbicsSecurityCode, IEbicsTransport)

Creates an EbicsOrderPUB instance and uses it to change the users signature key (PUB).

Declaration

public EbicsOrderPUB ChangeUserKey(IEbicsSecurityMedium aSecMedium, EbicsSecurityCode nSignatureVersion, IEbicsTransport aTransport = null)

Parameters

Type	Name	Description
IEbicsSecurityMedium	aSecMedium	Authenticated security medium of the user for the new key. Must not be `null`. This security medium must implement IEbicsSecurityMediumPrivKeys, hence smart cards are not supported.
EbicsSecurityCode	nSignatureVersion	New User Signature Key Version. This must be either A004, A005, or A006. If this contact already uses H005, or later, then A004 is not allowed.
IEbicsTransport	aTransport	An IEbicsTransport implementation for sending the HTTP request. If this is `null`, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

Returns

Type	Description
EbicsOrderPUB	Returns the EbicsOrderPUB that was built and sent. This can be used to determine whether the key change transaction was successful.

Exceptions

Type	Condition
System.ArgumentNullException	Either `aSecMedium` or `aTransport` was `null`.
System.ArgumentException	An invalid value for `nSignatureVersion` was given.
System.InvalidOperationException	The given `aSecMedium` does not support management of private keys.

Clone()

Declaration

public EbicsContact Clone()

Returns

Type	Description
EbicsContact

Remarks

see EbicsContact(EbicsContact)

CreateContact(JsonObject)

Creates an new EbicsContact from its json representation.

Declaration

public static EbicsContact CreateContact(JsonObject jsonContact)

Parameters

Type	Name	Description
JsonObject	jsonContact	json representation of an EbicsContact. The version property is mandatory.

Returns

Type	Description
EbicsContact

Exceptions

Type	Condition
System.ArgumentNullException	The specified jsonContact was `null`.
System.ArgumentException	The specified jsonContact doesn't contain a 'version' element.

CreateIniLetter(String)

Creates an Ini-Letter document that can be printed or converted to a PDF.

Declaration

public ReportDocument CreateIniLetter(string sFooterText)

Parameters

Type	Name	Description
System.String	sFooterText	Optional text that is added at the bottom of each page. If this is `null`, then a default footer test is added. In order to remove the footer, pass an empty string in this parameter.

Returns

Type	Description
Subsembly.Printing.ReportDocument

Remarks

Invoke the methods CreatePDF or WritePDF on the returned document in order to create a binary PDF representation.

CreateIniLetter(String, String)

Creates an Ini-Letter document that can be printed or converted to a PDF.

Declaration

public ReportDocument CreateIniLetter(string sAddressLines, string sFooterText)

Parameters

Type	Name	Description
System.String	sAddressLines	Optional address text that is included at the top of the first page. The address lines must be separated by CRLF or just LF characters.
System.String	sFooterText	Optional text that is added at the bottom of each page. If this is `null`, then a default footer test is added. In order to remove the footer, pass an empty string in this parameter.

Returns

Type	Description
Subsembly.Printing.ReportDocument

Remarks

Invoke the methods CreatePDF or WritePDF on the returned document in order to create a binary PDF representation.

CreateSecurityMedium()

Creates a new instance of the IEbicsSecurityMedium implementation required for this contact.

Declaration

public IEbicsSecurityMedium CreateSecurityMedium()

Returns

Type	Description
IEbicsSecurityMedium

DownloadBankKeys(IEbicsSecurityMedium, IEbicsTransport)

Creates an EbicsOrderHPB instance and uses it to download the bank keys (HPB).

Declaration

public EbicsOrderHPB DownloadBankKeys(IEbicsSecurityMedium aSecMedium, IEbicsTransport aTransport = null)

Parameters

Type	Name	Description
IEbicsSecurityMedium	aSecMedium	Authenticated security medium of the user. Must not be `null`.
IEbicsTransport	aTransport	An IEbicsTransport implementation for sending the HTTP request. If this is `null`, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

Returns

Type	Description
EbicsOrderHPB	If the transaction was sent, then the completed EbicsOrderHPB instance is returned. If the transaction could not be built, then `null` is returned. Even if successful, the downloaded bank keys are NOT stored in the given EbicsContact. The downloaded bank keys are only returned through the EbicsOrderHPB instance. It is up to the caller to store these bank keys in this contact.

EndUpdate()

Finish a series of property changes.

Declaration

public void EndUpdate()

ExportKeys(String, String, String, Boolean)

Export all user keys and user data from this contact into a new, external key file.

Declaration

public EbicsSecurityMediumErrorCode ExportKeys(string sFilename, string sContactPassword, string sKeyFilePassword, bool fAdoptKeyFile)

Parameters

Type	Name	Description
System.String	sFilename	The complete path of the new key file that shall be created.
System.String	sContactPassword	The password for this contact.
System.String	sKeyFilePassword	Password that will be used for the new key file.
System.Boolean	fAdoptKeyFile	If this is `true`, then this EbicsContact will be reconfigured to reference the newly created external key file and dismiss the previous security medium.

Returns

Type	Description
EbicsSecurityMediumErrorCode	If the export was successful, then the explicit value Success is returned. If the export failed, then a suitable error code will be returned.

Exceptions

Type	Condition
System.ArgumentNullException	Any of the parameters was `null`.

ExpulseSecurityMedium()

Reset all any any information about the security medium associated with this contact.

Declaration

public void ExpulseSecurityMedium()

FromJson(JsonObject)

Initializes an EbicsContact from its json representation. FromJson(JsonObject).

Declaration

public void FromJson(JsonObject jsonObject)

Parameters

Type	Name	Description
JsonObject	jsonObject

ImportKeys(String)

Declaration

public EbicsSecurityMediumErrorCode ImportKeys(string sPassword)

Parameters

Type	Name	Description
System.String	sPassword

Returns

Type	Description
EbicsSecurityMediumErrorCode

LoadContact(String)

Load an EbicsContact from a file where it was previously saved.

Declaration

public static EbicsContact LoadContact(string sFileName)

Parameters

Type	Name	Description
System.String	sFileName

Returns

Type	Description
EbicsContact

ModifyContact(JsonObject)

Declaration

public void ModifyContact(JsonObject jsonObjectChanges)

Parameters

Type	Name	Description
JsonObject	jsonObjectChanges

ParseXml(XmlElement, EbicsVersion)

Declaration

public override void ParseXml(XmlElement xmlElement, EbicsVersion nEbicsVersion)

Parameters

Type	Name	Description
System.Xml.XmlElement	xmlElement
EbicsVersion	nEbicsVersion	The given EBICS version is currently ignored but should be Contact in order to ensure compatibility with future versions.

Overrides

EbicsElement.ParseXml(XmlElement, EbicsVersion)

Remarks

This method always expects an XML element that was built by BuildXml(XmlDocument, EbicsVersion) which uses an unnamed default namespace.

Send(EbicsOrder, IEbicsSecurityMedium, IEbicsTransport)

Send an EBICS order, authenticated by this contact.

Declaration

public EbicsErrorClass Send(EbicsOrder aOrder, IEbicsSecurityMedium aSecurityMedium, IEbicsTransport aTransport = null)

Parameters

Type	Name	Description
EbicsOrder	aOrder
IEbicsSecurityMedium	aSecurityMedium	Authenticated security medium which will be used to create the authentication signature on the EBICS request. Must not be `null`. The referenced security medium must be in the Authenticated state.
IEbicsTransport	aTransport	An IEbicsTransport implementation for sending the HTTP request. If this is `null`, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

Returns

Type	Description
EbicsErrorClass	Returns the worse error class from the technical and business return codes (if any). If some error with the security medium occured, then SecurityMediumError is returned. If the transaction failed completely without ever receiving a return code, then an exception is thrown.

Remarks

This method automatically signs any upload orders that require a signature, unless they are already signed.

Exceptions

Type	Condition
System.ArgumentNullException	One of the arguments was `null`.
System.ArgumentException	Either the given EbicsOrder was incomplete or the security medium was not in the Authenticated state.

Declaration

public EbicsErrorClass Send(EbicsOrder aOrder, string sPassword)

Parameters

Type	Name	Description
EbicsOrder	aOrder
System.String	sPassword	The password or PIN that shall be used to authenticate the security medium configured for this contact. This must not be `null`.

Returns

Type	Description
EbicsErrorClass

Remarks

This method does not work with smart card readers with secure PIN entry.

Exceptions

Type	Condition
System.InvalidOperationException	This contact is not ready for sending orders.
EbicsException	The security medium is not available or could not be authenticated.

Send(EbicsOrder, String, IEbicsTransport)

Send an EBICS order on behalf of this contact.

Declaration

public EbicsErrorClass Send(EbicsOrder aOrder, string sPassword, IEbicsTransport aTransport = null)

Parameters

Type	Name	Description
EbicsOrder	aOrder
System.String	sPassword	The password or PIN that shall be used to authenticate the security medium configured for this contact. This must not be `null`.
IEbicsTransport	aTransport	An IEbicsTransport implementation for sending the HTTP request. If this is `null`, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

Returns

Type	Description
EbicsErrorClass

Remarks

This method does not work with smart card readers with secure PIN entry.

Exceptions

Type	Condition
System.InvalidOperationException	This contact is not ready for sending orders.
EbicsException	The security medium is not available or could not be authenticated.

SendSystemKeys(IEbicsSecurityMedium, IEbicsTransport)

Creates an EbicsOrderHIA instance and uses it to sends the system keys to the bank (HIA).

Declaration

public EbicsOrderHIA SendSystemKeys(IEbicsSecurityMedium aSecMedium, IEbicsTransport aTransport = null)

Parameters

Type	Name	Description
IEbicsSecurityMedium	aSecMedium	Authenticated security medium of the user. Must not be `null`.
IEbicsTransport	aTransport	An IEbicsTransport implementation for sending the HTTP request. If this is `null`, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

Returns

Type	Description
EbicsOrderHIA	If the transaction was sent, then the completed EbicsOrderHIA instance is returned. If the transaction could not be built, then `null` is returned.

SendUserKey(IEbicsSecurityMedium, IEbicsTransport)

Creates an EbicsOrderINI instance and uses it to sends the users signature key to the bank (INI).

Declaration

public EbicsOrderINI SendUserKey(IEbicsSecurityMedium aSecMedium, IEbicsTransport aTransport = null)

Parameters

Type	Name	Description
IEbicsSecurityMedium	aSecMedium	Authenticated security medium of the user. Must not be `null`.
IEbicsTransport	aTransport	An IEbicsTransport implementation for sending the HTTP request. If this is `null`, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

Returns

Type	Description
EbicsOrderINI	If the transaction was sent, then the completed EbicsOrderINI instance is returned. If the transaction could not be built, then `null` is returned.

Sign(EbicsOrder, IEbicsSecurityMedium)

Add a signature (EU) to the given order.

Declaration

public EbicsSecurityMediumErrorCode Sign(EbicsOrder aOrder, IEbicsSecurityMedium aSecurityMedium)

Parameters

Type	Name	Description
EbicsOrder	aOrder	The order to be signed. This must be completely set up and include all order data.
IEbicsSecurityMedium	aSecurityMedium	Authenticated security medium which will be used to create the electronic signature (EU) for the order. Must not be `null`. The referenced security medium must be in the Authenticated state.

Returns

Type	Description
EbicsSecurityMediumErrorCode	If there was an error with the security media while producing the signature, then an appropriate error code is returned. If the signature was produced successfully, then Success is returned.

Exceptions

Type	Condition
System.ArgumentNullException	One of the arguments was `null`.
System.ArgumentException	Either the given EbicsOrder was incomplete or the security medium was not in the Authenticated state.
System.InvalidOperationException	This EbicsContact was not completely initialized.

ToJson(JsonObject)

Converts an EbicsContact to its json representation. ToJson(JsonObject).

Declaration

public JsonObject ToJson(JsonObject jsonObject)

Parameters

Type	Name	Description
JsonObject	jsonObject

Returns

Type	Description
JsonObject

ToString()

Declaration

public override string ToString()

Returns

Type	Description
System.String	Usually returns the ContactName. If the contact name is `null`, then a string representation of the ContactGuid is returned instead.

Overrides

System.Object.ToString()

Implements

IEbicsJsonConverter

Extension Methods

EbicsExtensionMethods.AuthenticateSecurityMedium(EbicsContact, IWin32Window)

EbicsExtensionMethods.Sign(EbicsContact, IWin32Window, EbicsOrder)

EbicsExtensionMethods.Send(EbicsContact, IWin32Window, EbicsOrder)

EbicsExtensionMethods.InternalizeKeyFile(EbicsContact, IWin32Window)

EbicsContactExtensions.BuildXml(EbicsContact, XmlDocument)

EbicsContactExtensions.BuildXmlDocument(EbicsContact)

EbicsContactExtensions.ParseXml(EbicsContact, XmlElement)

EbicsContactExtensions.Load(EbicsContact, Stream)

EbicsContactExtensions.Load(EbicsContact, String)

EbicsContactExtensions.Save(EbicsContact, Stream)

EbicsContactExtensions.Save(EbicsContact, String)

EbicsContactExtensions.FromBuffer(EbicsContact, EbicsDataBuffer)

EbicsContactExtensions.ToBuffer(EbicsContact)

EbicsJsonConverterExtensions.ToJson(IEbicsJsonConverter)