Class EbicsFileSpooler

The EbicsFileSpooler organizes semi-automatic uploads and downloads of EBICS files in EbicsFileSpoolerFolder.

Inheritance

System.Object

EbicsFileSpooler

Inherited Members

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)

System.Object.ToString()

Namespace: Subsembly.EBICS

Assembly: Subsembly.EBICS.Core.dll

Syntax

public class EbicsFileSpooler

Constructors

EbicsFileSpooler(EbicsFileSpoolerFolder, IEbicsContactFolder, IEbicsTransport)

Declaration

public EbicsFileSpooler(EbicsFileSpoolerFolder aSpoolerFolder, IEbicsContactFolder aContactFolder = null, IEbicsTransport aTransport = null)

Parameters

Type	Name	Description
EbicsFileSpoolerFolder	aSpoolerFolder	The EbicsFileSpoolerFolder that shall be used by this instance to store all files. Must not be null.
IEbicsContactFolder	aContactFolder	The contact folder where the EBICS contacts are stored. This is only needed by Execute() and may be null if Execute() is never called.
IEbicsTransport	aTransport	Optional IEbicsTransport that shall be used. If null, then the default EbicsTransport will be used.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter aSpoolerFolder was null.

EbicsFileSpooler(String, EbicsFileSpoolerCredentials, IEbicsContactFolder, IEbicsTransport)

Declaration

public EbicsFileSpooler(string sSpoolerFolder, EbicsFileSpoolerCredentials aUserCredentials = null, IEbicsContactFolder aContactFolder = null, IEbicsTransport aTransport = null)

Parameters

Type	Name	Description
System.String	sSpoolerFolder	Complete, rooted file path of the root spooler folder. This must not be null.
EbicsFileSpoolerCredentials	aUserCredentials	In a protected and encrypted environment the credentials of the user, that wants access to the EbicsFileSpooler and its files, must be provided through this parameter. If given, then its properties UserName and Password must not be null.
IEbicsContactFolder	aContactFolder	The contact folder where the EBICS contacts are stored. This is only needed by Execute() and may be null if Execute() is never called.
IEbicsTransport	aTransport	Optional IEbicsTransport that shall be used. If null, then the default EbicsTransport will be used.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter sSpoolerFolder was null.
System.ArgumentException	The configured spooler folder does not exist.

See Also

SpoolerFolderPath

EbicsFileSpoolerFolder

Fields

MAXHISTORYDAYS

By default the EBICS file spooler initially downloads data starting today minus MAXHISTORYDAYS.

Declaration

public const int MAXHISTORYDAYS = 30

Field Value

Type	Description
System.Int32

Properties

SpoolerFolder

Declaration

public EbicsFileSpoolerFolder SpoolerFolder { get; }

Property Value

Type	Description
EbicsFileSpoolerFolder

Methods

DownloadCamt052(EbicsContact, IEbicsSecurityMedium, String)

Download new CAMT 052 files for a given EbicsContact into the BOX_CAMT052 folder.

Declaration

public EbicsFileTransferResult DownloadCamt052(EbicsContact aContact, IEbicsSecurityMedium aSecurityMedium, string sOrderType = null)

Parameters

Type	Name	Description
EbicsContact	aContact
IEbicsSecurityMedium	aSecurityMedium	A Authenticated security medium that will be used for authenticating and decrypting the requests. This must not be null.
System.String	sOrderType	The order type that shall be used for downloading the CAMT 052 data. If this is null, then "C52" will be assumed. See CreateOrderC52(String, DateTime).

Returns

Type	Description
EbicsFileTransferResult	Returns the EbicsFileTransferResult from the download attempt.

Exceptions

Type	Condition
EbicsFileSpoolerException	The folder is currently locked by another process.

DownloadCamt053(EbicsContact, IEbicsSecurityMedium, String, DateTime)

Download new CAMT 053 files for a given EbicsContact into the BOX_CAMT053 folder.

Declaration

public EbicsFileTransferResult DownloadCamt053(EbicsContact aContact, IEbicsSecurityMedium aSecurityMedium, string sOrderType = null, DateTime tFirstDate = default(DateTime))

Parameters

Type	Name	Description
EbicsContact	aContact
IEbicsSecurityMedium	aSecurityMedium	A Authenticated security medium that will be used for authenticating and decrypting the requests. This must not be null.
System.String	sOrderType	The order type that shall be used for downloading the CAMT 053 data. If this is null, then "C53" will be assumed. See CreateOrderC53(String, DateTime, DateTime).
System.DateTime	tFirstDate	If this is the very first call to DownloadCamt053(EbicsContact, IEbicsSecurityMedium, String, DateTime) and the BOX_CAMT053 folder is empty, then this can be used to provide a desired starting date for the very first download. If this is DateTime.MinValue, then today minus MAXHISTORYDAYS is used as the very first download date. If there is already data in the BOX_CAMT053 folder, then this parameter is ignored and downloading just continues immediately following the most recent file.

Returns

Type	Description
EbicsFileTransferResult	Returns the EbicsFileTransferResult from the download attempt.

Exceptions

Type	Condition
EbicsFileSpoolerException	The folder is currently locked by another process.

DownloadCamt054(EbicsContact, IEbicsSecurityMedium, String, DateTime)

Download new CAMT 054 files for a given EbicsContact into the BOX_CAMT054 folder.

Declaration

public EbicsFileTransferResult DownloadCamt054(EbicsContact aContact, IEbicsSecurityMedium aSecurityMedium, string sOrderType = null, DateTime tFirstDate = default(DateTime))

Parameters

Type	Name	Description
EbicsContact	aContact
IEbicsSecurityMedium	aSecurityMedium	A Authenticated security medium that will be used for authenticating and decrypting the requests. This must not be null.
System.String	sOrderType	The order type that shall be used for downloading the CAMT 054 data. If this is null, then "C54" will be assumed. See CreateOrderC54(String, DateTime).
System.DateTime	tFirstDate	If this is the very first call to DownloadCamt054(EbicsContact, IEbicsSecurityMedium, String, DateTime) and the BOX_CAMT054 folder is empty, then this can be used to provide a desired starting date for the very first download. If this is DateTime.MinValue, then today minus MAXHISTORYDAYS is used as the very first download date. If there is already data in the BOX_CAMT054 folder, then this parameter is ignored and downloading just continues immediately following the most recent file.

Returns

Type	Description
EbicsFileTransferResult	Returns the EbicsFileTransferResult from the download attempt.

Exceptions

Type	Condition
EbicsFileSpoolerException	The folder is currently locked by another process.

DownloadDocs(EbicsContact, IEbicsSecurityMedium, String, DateTime)

Download PDF document files for a given EbicsContact into the BOX_DOCS folder.

Declaration

public EbicsFileTransferResult DownloadDocs(EbicsContact aContact, IEbicsSecurityMedium aSecurityMedium, string sOrderType, DateTime tFirstDate = default(DateTime))

Parameters

Type	Name	Description
EbicsContact	aContact
IEbicsSecurityMedium	aSecurityMedium	A Authenticated security medium that will be used for authenticating and decrypting the requests. This must not be null.
System.String	sOrderType	The order type that shall be used for downloading the PDF documents. This is usually either "BKA" or "BKI". This must not be null
System.DateTime	tFirstDate	If this is the very first call to DownloadDocs(EbicsContact, IEbicsSecurityMedium, String, DateTime) for the given sOrderType, and the BOX_DOCS folder does not contain any entry for the that sOrderType, then this can be used to provide a desired starting date for the very first download. If this is DateTime.MinValue, then today minus MAXHISTORYDAYS is used as the very first download date. If there is already data in the BOX_DOCS folder, then this parameter is ignored and downloading just continues immediately following the most recent file of the selected sOrderType.

Returns

Type	Description
EbicsFileTransferResult	Returns the EbicsFileTransferResult from the download attempt.

Exceptions

Type	Condition
EbicsFileSpoolerException	The folder is currently locked by another process.

DownloadProtocol(EbicsContact, IEbicsSecurityMedium, String, DateTime)

Declaration

public EbicsFileTransferResult DownloadProtocol(EbicsContact aContact, IEbicsSecurityMedium aSecurityMedium, string sOrderType = null, DateTime tFirstDate = default(DateTime))

Parameters

Type	Name	Description
EbicsContact	aContact
IEbicsSecurityMedium	aSecurityMedium
System.String	sOrderType
System.DateTime	tFirstDate

Returns

Type	Description
EbicsFileTransferResult

Exceptions

Type	Condition
EbicsFileSpoolerException	The folder is currently locked by another process.

Execute()

Processes all EbicsContacts of the

Declaration

public EbicsFileSpoolerResult[] Execute()

Returns

Type	Description
EbicsFileSpoolerResult[]	For every EbicsContact that has some SpoolerActions activated, the EbicsFileSpoolerResult from executing these actions is returned. If no contacts have any SpoolerActions activated, then an empty array will be returned.

Remarks

This method always processes all contacts with any SpoolerActions. When an error occurs while processing a contact, it continues with the next contact that has any activated SpoolerActions.

Exceptions

Type	Condition
System.InvalidOperationException	No contact folder was provided to the constructor.

ExecuteActions(EbicsContact, IEbicsSecurityMedium, EbicsFileSpoolerActions)

Execute the requested EbicsFileSpoolerActions for an EbicsContact.

Declaration

public EbicsFileSpoolerResult ExecuteActions(EbicsContact aContact, IEbicsSecurityMedium aSecurityMedium, EbicsFileSpoolerActions nActions)

Parameters

Type	Name	Description
EbicsContact	aContact
IEbicsSecurityMedium	aSecurityMedium	A Authenticated security medium that will be used for the requests. This must not be null.
EbicsFileSpoolerActions	nActions	The EbicsFileSpoolerActions that shall be executed. If this is None, then the actions configured in SpoolerActions will be executed.

Returns

Type	Description
EbicsFileSpoolerResult

Remarks

Explicitly requested actions are executed regardless of the setting of the SpoolerActions property.

The requested actions are executed in the following order:

• UploadOutbox
• DownloadC53
• DownloadC52
• DownloadC54
• DownloadBKA
• DownloadBKI
• DownloadHAC

If any action produces an EBICS error, processing of further actions is aborted.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter aContact was null.
System.InvalidOperationException	The parameter nActions was None and no actions have been configured in SpoolerActions.

ExecuteActions(EbicsContact, String, EbicsFileSpoolerActions)

Declaration

public EbicsFileSpoolerResult ExecuteActions(EbicsContact aContact, string sPassword = null, EbicsFileSpoolerActions nActions = EbicsFileSpoolerActions.None)

Parameters

Type	Name	Description
EbicsContact	aContact
System.String	sPassword	Optional password for authentication. If this is null, then a password must have been stored in the SpoolerSecret of the contact. If this is an empty string, then it will be used as an empty password.
EbicsFileSpoolerActions	nActions	The EbicsFileSpoolerActions that shall be executed. If this is None, then the actions configured in SpoolerActions will be executed.

Returns

Type	Description
EbicsFileSpoolerResult

Exceptions

Type	Condition
System.ArgumentNullException	The parameter aContact was null.

GetBoxFolder(EbicsContact, String, Boolean)

Gets the BOX folder with the given name.

Declaration

public EbicsFileFolder GetBoxFolder(EbicsContact aContact, string sBoxName, bool fCreate)

Parameters

Type	Name	Description
EbicsContact	aContact
System.String	sBoxName
System.Boolean	fCreate

Returns

Type	Description
EbicsFileFolder

Exceptions

Type	Condition
System.ArgumentNullException	Either the parameter aContact, or sBoxName, was null.
System.ArgumentException	The parameter sBoxName was an empty string.

GetCamt052Folder(EbicsContact)

Gets the BOX_CAMT052 folder.

Declaration

public EbicsFileFolder GetCamt052Folder(EbicsContact aContact)

Parameters

Type	Name	Description
EbicsContact	aContact

Returns

Type	Description
EbicsFileFolder

Remarks

If the requested folder does not exist, yet, then it will be created.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter aContact was null.

GetCamt053Folder(EbicsContact)

Gets the BOX_CAMT053 folder.

Declaration

public EbicsFileFolder GetCamt053Folder(EbicsContact aContact)

Parameters

Type	Name	Description
EbicsContact	aContact

Returns

Type	Description
EbicsFileFolder

Remarks

If the requested folder does not exist, yet, then it will be created.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter aContact was null.

GetCamt054Folder(EbicsContact)

Gets the BOX_CAMT054 folder.

Declaration

public EbicsFileFolder GetCamt054Folder(EbicsContact aContact)

Parameters

Type	Name	Description
EbicsContact	aContact

Returns

Type	Description
EbicsFileFolder

Remarks

If the requested folder does not exist, yet, then it will be created.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter aContact was null.

GetDocsFolder(EbicsContact)

Gets the BOX_DOCS folder.

Declaration

public EbicsFileFolder GetDocsFolder(EbicsContact aContact)

Parameters

Type	Name	Description
EbicsContact	aContact

Returns

Type	Description
EbicsFileFolder

Remarks

If the requested folder does not exist, yet, then it will be created.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter aContact was null.

GetOutboxFolder(EbicsContact)

Gets the BOX_OUTBOX folder.

Declaration

public EbicsFileFolder GetOutboxFolder(EbicsContact aContact)

Parameters

Type	Name	Description
EbicsContact	aContact

Returns

Type	Description
EbicsFileFolder

Remarks

If the requested folder does not exist, yet, then it will be created.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter aContact was null.

GetPassword(EbicsContact)

Declaration

public static string GetPassword(EbicsContact aContact)

Parameters

Type	Name	Description
EbicsContact	aContact

Returns

Type	Description
System.String

GetPasswordPlaceholder(EbicsContact)

If the security media password is stored in the contact, then a suitable placeholder text is returned.

Declaration

public static string GetPasswordPlaceholder(EbicsContact aContact)

Parameters

Type	Name	Description
EbicsContact	aContact	The contact that was used to store the encrypted password. The encrypted password is stored in the SpoolerSecret property of the EbicsContact. This must not be null.

Returns

Type	Description
System.String	If nothing was stored, then null is returned. Otherwise a placeholder string with the same length as the stored password, consisting solely of asterisk characters is returned.

Remarks

It is by no means possible to retrieve the password actually stored.

GetSpoolerFolder(EbicsFileSpoolerCredentials)

Obtains a EbicsFileSpoolerFolder instance for the configured spooler folder.

Declaration

public static EbicsFileSpoolerFolder GetSpoolerFolder(EbicsFileSpoolerCredentials aCredentials)

Parameters

Type	Name	Description
EbicsFileSpoolerCredentials	aCredentials	As an option the user credentials can be supplied. If this is null, then an attempt is made to get the credentials that are stored in the environment. If there are no credentials stored, then the EbicsFileSpoolerFolder is created for un-protected access.

Returns

Type	Description
EbicsFileSpoolerFolder	If there is no SpoolerFolderPath configured, then null is returned.

StorePassword(EbicsContact, String)

Stores the security media password for automated use by the EbicsFileSpooler.

Declaration

public static void StorePassword(EbicsContact aContact, string sPassword)

Parameters

Type	Name	Description
EbicsContact	aContact	The contact that is used to store the encrypted password. The encrypted password is stored in the SpoolerSecret property of the EbicsContact. This must not be null.
System.String	sPassword	The security media password to be stored. If this is null, then any stored password is cleared. An empty string will be stored as an empty password.

See Also

GetPasswordPlaceholder(EbicsContact)

SubmitFileUpload(EbicsContact, String, String, String)

Copies a file into the BOX_OUTBOX folder for uploading by the spooler.

Declaration

public EbicsFileName SubmitFileUpload(EbicsContact aContact, string sSourceFilePath, string sOrderType, string sFileId = null)

Parameters

Type	Name	Description
EbicsContact	aContact
System.String	sSourceFilePath	Full path to file that shall be uploaded to the server. This file must exist outside of the spooler folder. It will be copied into the BOX_OUTBOX with a new file name, generated from the sOrderType and the sFileId. The file name extension of the source file will also be used for the file copied into the BOX_OUTBOX.
System.String	sOrderType	The EBICS OrderType that shall be used to upload the file.
System.String	sFileId	Optional file ID that will be used to generate a unique file name. If this is null then a unique time stamp will be used to create a unqiue file ID.

Returns

Type	Description
EbicsFileName	Returns the EbicsFileName of the order file that was created in the BOX_OUTBOX folder.

Exceptions

Type	Condition
System.ArgumentNullException	One of the required parameters was null.

SubmitSepaUpload(EbicsContact, SepaDocument)

Writes the given SEPA payment initiation document into the BOX_OUTBOX folder for uploading by the spooler.

Declaration

public EbicsFileName SubmitSepaUpload(EbicsContact aContact, SepaDocument aSepaDocument)

Parameters

Type	Name	Description
EbicsContact	aContact
SepaDocument	aSepaDocument

Returns

Type	Description
EbicsFileName	Returns the EbicsFileName of the order file that was created in the BOX_OUTBOX folder.

Exceptions

Type	Condition
System.ArgumentNullException	One of the parameters was null.

TryAuthenticateContact(EbicsContact, String, out IEbicsSecurityMedium, out String)

Attempt to create and authenticate the security medium for a contact.

Declaration

public EbicsFileSpoolerResultCode TryAuthenticateContact(EbicsContact aContact, string sPassword, out IEbicsSecurityMedium aSecurityMedium, out string sLastErrorText)

Parameters

Type	Name	Description
EbicsContact	aContact	The contact to be authenticated. This must not be null.
System.String	sPassword	Optional password for authentication. If this is null, then a password must have been stored in the SpoolerSecret of the contact. If this is an empty string, then it will be used as an empty password.
IEbicsSecurityMedium	aSecurityMedium	If successful, then the authenticated IEbicsSecurityMedium is returned through this parameter. This is null on failure.
System.String	sLastErrorText

Returns

Type	Description
EbicsFileSpoolerResultCode

Exceptions

Type	Condition
System.ArgumentNullException	The parameter aContact was null.

UploadOutbox(EbicsContact, IEbicsSecurityMedium)

Upload the entire pending content of the BOX_OUTBOX.

Declaration

public EbicsFileTransferResult[] UploadOutbox(EbicsContact aContact, IEbicsSecurityMedium aSecurityMedium)

Parameters

Type	Name	Description
EbicsContact	aContact
IEbicsSecurityMedium	aSecurityMedium	A Authenticated security medium that will be used for signing and decrypting the requests. This must not be null.

Returns

Type	Description
EbicsFileTransferResult[]	Returns a EbicsFileTransferResult array that contains the result of every outbox file upload that was attempted.

Exceptions

Type	Condition
EbicsFileSpoolerException	The folder is currently locked by another process.