Class EbicsFileSpooler

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

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

public class EbicsFileSpooler
Inheritance
EbicsFileSpooler
Inherited Members

Constructors

EbicsFileSpooler(EbicsFileSpoolerFolder, IEbicsContactFolder, IEbicsTransport) 

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

Parameters

aSpoolerFolder EbicsFileSpoolerFolder

The EbicsFileSpoolerFolder that shall be used by this instance to store all files. Must not be null.

aContactFolder IEbicsContactFolder

The contact folder where the EBICS contacts are stored. This is only needed by Execute() and may be null if Execute() is never called.

aTransport IEbicsTransport

Optional IEbicsTransport that shall be used. If null, then the default EbicsTransport will be used.

Exceptions

ArgumentNullException

The parameter aSpoolerFolder was null.

EbicsFileSpooler(string, EbicsFileSpoolerCredentials, IEbicsContactFolder, IEbicsTransport) 

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

Parameters

sSpoolerFolder string

Complete, rooted file path of the root spooler folder. This must not be null.

aUserCredentials EbicsFileSpoolerCredentials

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.

aContactFolder IEbicsContactFolder

The contact folder where the EBICS contacts are stored. This is only needed by Execute() and may be null if Execute() is never called.

aTransport IEbicsTransport

Optional IEbicsTransport that shall be used. If null, then the default EbicsTransport will be used.

Exceptions

ArgumentNullException

The parameter sSpoolerFolder was null.

ArgumentException

The configured spooler folder does not exist.

See Also

Fields

MAXHISTORYDAYS

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

public const int MAXHISTORYDAYS = 30

Field Value

int

Properties

SpoolerFolder 

public EbicsFileSpoolerFolder SpoolerFolder { get; }

Property Value

EbicsFileSpoolerFolder

Methods

DownloadCamt052(EbicsContact, IEbicsSecurityMedium, string)

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

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

Parameters

aContact EbicsContact
aSecurityMedium IEbicsSecurityMedium

A Authenticated security medium that will be used for authenticating and decrypting the requests. This must not be null.

sOrderType string

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

EbicsFileTransferResult

Returns the EbicsFileTransferResult from the download attempt.

Exceptions

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.

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

Parameters

aContact EbicsContact
aSecurityMedium IEbicsSecurityMedium

A Authenticated security medium that will be used for authenticating and decrypting the requests. This must not be null.

sOrderType string

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).

tFirstDate DateTime

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

EbicsFileTransferResult

Returns the EbicsFileTransferResult from the download attempt.

Exceptions

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.

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

Parameters

aContact EbicsContact
aSecurityMedium IEbicsSecurityMedium

A Authenticated security medium that will be used for authenticating and decrypting the requests. This must not be null.

sOrderType string

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).

tFirstDate DateTime

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

EbicsFileTransferResult

Returns the EbicsFileTransferResult from the download attempt.

Exceptions

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.

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

Parameters

aContact EbicsContact
aSecurityMedium IEbicsSecurityMedium

A Authenticated security medium that will be used for authenticating and decrypting the requests. This must not be null.

sOrderType string

The order type that shall be used for downloading the PDF documents. This is usually either "BKA" or "BKI". This must not be null

tFirstDate DateTime

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

EbicsFileTransferResult

Returns the EbicsFileTransferResult from the download attempt.

Exceptions

EbicsFileSpoolerException

The folder is currently locked by another process.

DownloadProtocol(EbicsContact, IEbicsSecurityMedium, string, DateTime) 

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

Parameters

aContact EbicsContact
aSecurityMedium IEbicsSecurityMedium
sOrderType string
tFirstDate DateTime

Returns

EbicsFileTransferResult

Exceptions

EbicsFileSpoolerException

The folder is currently locked by another process.

Execute()

Processes all EbicsContacts of the

public EbicsFileSpoolerResult[] Execute()

Returns

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

InvalidOperationException

No contact folder was provided to the constructor.

ExecuteActions(EbicsContact, IEbicsSecurityMedium, EbicsFileSpoolerActions)

Execute the requested EbicsFileSpoolerActions for an EbicsContact.

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

Parameters

aContact EbicsContact
aSecurityMedium IEbicsSecurityMedium

A Authenticated security medium that will be used for the requests. This must not be null.

nActions EbicsFileSpoolerActions

The EbicsFileSpoolerActions that shall be executed. If this is None, then the actions configured in SpoolerActions will be executed.

Returns

EbicsFileSpoolerResult

Remarks

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

The requested actions are executed in the following order:

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

Exceptions

ArgumentNullException

The parameter aContact was null.

InvalidOperationException

The parameter nActions was None and no actions have been configured in SpoolerActions.

ExecuteActions(EbicsContact, string, EbicsFileSpoolerActions) 

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

Parameters

aContact EbicsContact
sPassword string

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.

nActions EbicsFileSpoolerActions

The EbicsFileSpoolerActions that shall be executed. If this is None, then the actions configured in SpoolerActions will be executed.

Returns

EbicsFileSpoolerResult

Exceptions

ArgumentNullException

The parameter aContact was null.

GetBoxFolder(EbicsContact, string, bool)

Gets the BOX folder with the given name.

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

Parameters

aContact EbicsContact
sBoxName string
fCreate bool

Returns

EbicsFileFolder

Exceptions

ArgumentNullException

Either the parameter aContact, or sBoxName, was null.

ArgumentException

The parameter sBoxName was an empty string.

GetCamt052Folder(EbicsContact)

Gets the BOX_CAMT052 folder.

public EbicsFileFolder GetCamt052Folder(EbicsContact aContact)

Parameters

aContact EbicsContact

Returns

EbicsFileFolder

Remarks

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

Exceptions

ArgumentNullException

The parameter aContact was null.

GetCamt053Folder(EbicsContact)

Gets the BOX_CAMT053 folder.

public EbicsFileFolder GetCamt053Folder(EbicsContact aContact)

Parameters

aContact EbicsContact

Returns

EbicsFileFolder

Remarks

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

Exceptions

ArgumentNullException

The parameter aContact was null.

GetCamt054Folder(EbicsContact)

Gets the BOX_CAMT054 folder.

public EbicsFileFolder GetCamt054Folder(EbicsContact aContact)

Parameters

aContact EbicsContact

Returns

EbicsFileFolder

Remarks

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

Exceptions

ArgumentNullException

The parameter aContact was null.

GetDocsFolder(EbicsContact)

Gets the BOX_DOCS folder.

public EbicsFileFolder GetDocsFolder(EbicsContact aContact)

Parameters

aContact EbicsContact

Returns

EbicsFileFolder

Remarks

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

Exceptions

ArgumentNullException

The parameter aContact was null.

GetOutboxFolder(EbicsContact)

Gets the BOX_OUTBOX folder.

public EbicsFileFolder GetOutboxFolder(EbicsContact aContact)

Parameters

aContact EbicsContact

Returns

EbicsFileFolder

Remarks

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

Exceptions

ArgumentNullException

The parameter aContact was null.

GetPassword(EbicsContact) 

public static string GetPassword(EbicsContact aContact)

Parameters

aContact EbicsContact

Returns

string

GetPasswordPlaceholder(EbicsContact)

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

public static string GetPasswordPlaceholder(EbicsContact aContact)

Parameters

aContact EbicsContact

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

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.

public static EbicsFileSpoolerFolder GetSpoolerFolder(EbicsFileSpoolerCredentials aCredentials)

Parameters

aCredentials EbicsFileSpoolerCredentials

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

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.

public static void StorePassword(EbicsContact aContact, string sPassword)

Parameters

aContact EbicsContact

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.

sPassword string

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

SubmitFileUpload(EbicsContact, string, string, string)

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

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

Parameters

aContact EbicsContact
sSourceFilePath string

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.

sOrderType string

The EBICS OrderType that shall be used to upload the file.

sFileId string

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

EbicsFileName

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

Exceptions

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.

public EbicsFileName SubmitSepaUpload(EbicsContact aContact, SepaDocument aSepaDocument)

Parameters

aContact EbicsContact
aSepaDocument SepaDocument

Returns

EbicsFileName

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

Exceptions

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.

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

Parameters

aContact EbicsContact

The contact to be authenticated. This must not be null.

sPassword string

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.

aSecurityMedium IEbicsSecurityMedium

If successful, then the authenticated IEbicsSecurityMedium is returned through this parameter. This is null on failure.

sLastErrorText string

Returns

EbicsFileSpoolerResultCode

Exceptions

ArgumentNullException

The parameter aContact was null.

UploadOutbox(EbicsContact, IEbicsSecurityMedium)

Upload the entire pending content of the BOX_OUTBOX.

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

Parameters

aContact EbicsContact
aSecurityMedium IEbicsSecurityMedium

A Authenticated security medium that will be used for signing and decrypting the requests. This must not be null.

Returns

EbicsFileTransferResult[]

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

Exceptions

EbicsFileSpoolerException

The folder is currently locked by another process.