Class EbicsFileSpoolerFolder

Root folder and organizer of a EbicsFileSpooler storage folder tree.

Inheritance
object
EbicsFileFolder
EbicsFileSpoolerFolder
Inherited Members
Namespace: Subsembly.EBICS
Assembly: Subsembly.EBICS.Core.dll
Syntax
public class EbicsFileSpoolerFolder : EbicsFileFolder
Remarks

Starting at a given root folder, the EbicsFileSpooler maintains sub-folders for each EBICS Host ID. In every Host ID folder another folder is created for each EBICS Partner ID. Inside of the partner folder the following folders are maintained to manage uploads and downloads:

pathdescription
BOX_CAMT053 This folder receives the unzipped and maybe converted CAMT 053 Customer Statement downloads. By strictly enforcing the EbicsFileName convention, every file is uniquely identified and there will not be any duplicate data.
BOX_CAMT052 This folder receives the unzipped and maybe converted CAMT 052 Customer Account Report downloads. By strictly enforcing the EbicsFileName convention, every file is uniquely identified and there will not be any duplicate data.
BOX_CAMT054 This folder receives the unzipped and maybe converted CAMT 054 Customer Debit/Credit Notification downloads. By strictly enforcing the EbicsFileName convention, every file is uniquely identified and there will not be any duplicate data.
BOX_DOCS This folder receives the unzipped documents that were received by an EBICS document download (BKA, BKI, or other). The bank supplied file names must be unique, as the file name is used to avoid duplicates.
BOX_OUTBOX

Files that shall be uploaded to the EBICS server must be placed in this folder. The file name must obey the EbicsFileName convention. In particular, the order type contained in the file name is used as the upload order type for this file. The additional data must contain a unique serial number so that all file names are unique.

After a file was uploaded, or attempted to be uploaded, it is renamed with a special file name prefix that shows the business return code of the EBICS transaction. In addition a result file with a leading dot followed by the base file name and the file name suffix .result is created which contains the XML from the EbicsFileTransferResult that was returned from the UploadFile(EbicsContact, IEbicsSecurityMedium, string, string, EbicsAuthorisationLevel).

Constructors

EbicsFileSpoolerFolder(string, EbicsFileSpoolerCredentials)

Declaration
public EbicsFileSpoolerFolder(string sSpoolerFolder, EbicsFileSpoolerCredentials aUserCredentials = null)
Parameters
Type Name Description
string sSpoolerFolder

Complete, rooted file path of the root spooler folder. This must not be null, and must refer to an existing file system folder.
EbicsFileSpoolerCredentials aUserCredentials

In a protected and encrypted spooler folder tree, these must be the credentials of the user, that wants access to the EbicsFileSpoolerFolder and its files. If given, then its properties UserName and Password must not be null.
Exceptions
Type Condition
ArgumentNullException

The parameter sSpoolerFolder was null.
ArgumentException

The given aUserCredentials did not contain a UserName and Password.
See Also

Fields

BOX_CAMT052

The name of the CAMT052 folder is "camt052".

Declaration
public const string BOX_CAMT052 = "camt052"
Field Value
Type Description
string

BOX_CAMT053

The name of the CAMT053 folder is "camt053".

Declaration
public const string BOX_CAMT053 = "camt053"
Field Value
Type Description
string

BOX_CAMT054

The name of the CAMT054 folder is "camt054".

Declaration
public const string BOX_CAMT054 = "camt054"
Field Value
Type Description
string

BOX_DOCS

The name of the DOCS folder is "docs".

Declaration
public const string BOX_DOCS = "docs"
Field Value
Type Description
string

BOX_OUTBOX

The name of the OUTBOX folder is "outbox".

Declaration
public const string BOX_OUTBOX = "outbox"
Field Value
Type Description
string

RESULTFILENAMESUFFIX

This suffix is appended to the original file name in order to produce a file name for storing the EbicsFileTransferResult of this file.

Declaration
public const string RESULTFILENAMESUFFIX = ".result"
Field Value
Type Description
string

ROOT

The constant user name of the root user is "root".

Declaration
public const string ROOT = "root"
Field Value
Type Description
string

Properties

IsProtected

Indicates whether this EbicsFileSpooler instance is using Access Control with encrypted files.

Declaration
public bool IsProtected { get; }
Property Value
Type Description
bool

Methods

AddAccessControlEntry(EbicsFileFolder, EbicsFileSpoolerCredentials)

Declaration
public EbicsFileSpoolerAccessControlEntry AddAccessControlEntry(EbicsFileFolder aFileFolder, EbicsFileSpoolerCredentials aUserCredentials)
Parameters
Type Name Description
EbicsFileFolder aFileFolder
EbicsFileSpoolerCredentials aUserCredentials
Returns
Type Description
EbicsFileSpoolerAccessControlEntry

AppendOkay(string, string, EbicsFileSpoolerResult)

Declaration
public void AppendOkay(string sHostID, string sPartnerID, EbicsFileSpoolerResult aSpoolerResult)
Parameters
Type Name Description
string sHostID
string sPartnerID
EbicsFileSpoolerResult aSpoolerResult

CreateAccessControlEntry(EbicsFileFolder, EbicsFileSpoolerCredentials)

Creates a new EbicsFileSpoolerAccessControlEntry that enables an user to access the given file folder.

Declaration
public EbicsFileSpoolerAccessControlEntry CreateAccessControlEntry(EbicsFileFolder aFileFolder, EbicsFileSpoolerCredentials aUserCredentials)
Parameters
Type Name Description
EbicsFileFolder aFileFolder
EbicsFileSpoolerCredentials aUserCredentials

The credentials of the new user to create an access control entry for.
Returns
Type Description
EbicsFileSpoolerAccessControlEntry
Remarks

This EbicsFileSpooler instance must have been created by the "root" user, in order to use this method.

The returned EbicsFileSpoolerAccessControlEntry was not saved or added to an access control list. It is up to the caller to obtain the correct access control list via ObtainAccessControlList(EbicsFileFolder), add the new entry, and finally call UpdateAccessControlList(EbicsFileFolder, EbicsFileSpoolerAccessControlList).

See Also

GetBoxFolder(string, string, string, bool)

Declaration
public EbicsFileFolder GetBoxFolder(string sHostID, string sPartnerID, string sBoxName, bool fCreate)
Parameters
Type Name Description
string sHostID
string sPartnerID
string sBoxName
bool fCreate
Returns
Type Description
EbicsFileFolder

GetCamt052Folder(string, string)

Declaration
public EbicsFileFolder GetCamt052Folder(string sHostID, string sPartnerID)
Parameters
Type Name Description
string sHostID
string sPartnerID
Returns
Type Description
EbicsFileFolder

GetCamt053Folder(string, string)

Declaration
public EbicsFileFolder GetCamt053Folder(string sHostID, string sPartnerID)
Parameters
Type Name Description
string sHostID
string sPartnerID
Returns
Type Description
EbicsFileFolder

GetCamt054Folder(string, string)

Declaration
public EbicsFileFolder GetCamt054Folder(string sHostID, string sPartnerID)
Parameters
Type Name Description
string sHostID
string sPartnerID
Returns
Type Description
EbicsFileFolder

GetContactFolder()

Creates an IEbicsContactFolder implementation according to the configuration.

Declaration
public IEbicsContactFolder GetContactFolder()
Returns
Type Description
IEbicsContactFolder
Remarks

If a SUBSEMBLY_EBICS_CONTACTFOLDERPATH is configured, then it will take precedence over the EbicsFileSpoolerContactFolder and thus will be returned. If there is no explicitly configured ContactFolderPath, then a EbicsFileSpoolerContactFolder instance for this spooler folder will be returned.

GetDocsFolder(string, string)

Declaration
public EbicsFileFolder GetDocsFolder(string sHostID, string sPartnerID)
Parameters
Type Name Description
string sHostID
string sPartnerID
Returns
Type Description
EbicsFileFolder

GetFolder(string, bool)

Declaration
public EbicsFileFolder GetFolder(string sPath, bool fCreate)
Parameters
Type Name Description
string sPath

The relative path from the root spooler folder. If this is null, then the root folder path is returned. This path must have been built according to local file system requirements.
bool fCreate
Returns
Type Description
EbicsFileFolder

GetHostFolders()

Declaration
public EbicsFileFolder[] GetHostFolders()
Returns
Type Description
EbicsFileFolder[]

GetJournalEntry(string, string, EbicsFileName)

Declaration
public EbicsFileSpoolerJournalEntry GetJournalEntry(string sHostID, string sPartnerID, EbicsFileName aFileName)
Parameters
Type Name Description
string sHostID
string sPartnerID
EbicsFileName aFileName
Returns
Type Description
EbicsFileSpoolerJournalEntry

GetLastOkay(string, string)

Declaration
public EbicsFileSpoolerResult GetLastOkay(string sHostID, string sPartnerID)
Parameters
Type Name Description
string sHostID
string sPartnerID
Returns
Type Description
EbicsFileSpoolerResult

GetOutboxFolder(string, string)

Declaration
public EbicsFileFolder GetOutboxFolder(string sHostID, string sPartnerID)
Parameters
Type Name Description
string sHostID
string sPartnerID
Returns
Type Description
EbicsFileFolder

GetPartnerFolder(string, string, bool)

Declaration
public EbicsFileFolder GetPartnerFolder(string sHostID, string sPartnerID, bool fCreate)
Parameters
Type Name Description
string sHostID
string sPartnerID
bool fCreate
Returns
Type Description
EbicsFileFolder

GetPartnerFolders(string)

Declaration
public EbicsFileFolder[] GetPartnerFolders(string sHostID)
Parameters
Type Name Description
string sHostID
Returns
Type Description
EbicsFileFolder[]

HasAccess(EbicsFileFolder)

Indicates whether this instance has access to the requested folder, with the credentials that were given to the ctor.

Declaration
public bool HasAccess(EbicsFileFolder aFileFolder)
Parameters
Type Name Description
EbicsFileFolder aFileFolder
Returns
Type Description
bool

LoadOrderResult(string, string, EbicsFileName)

Declaration
public EbicsFileTransferResult LoadOrderResult(string sHostID, string sPartnerID, EbicsFileName aFileName)
Parameters
Type Name Description
string sHostID
string sPartnerID
EbicsFileName aFileName
Returns
Type Description
EbicsFileTransferResult

ObtainAccessControlList(EbicsFileFolder)

Loads or creates an EbicsFileSpoolerAccessControlList for the given folder.

Declaration
public EbicsFileSpoolerAccessControlList ObtainAccessControlList(EbicsFileFolder aFileFolder)
Parameters
Type Name Description
EbicsFileFolder aFileFolder
Returns
Type Description
EbicsFileSpoolerAccessControlList

OpenRead(EbicsFileFolder, EbicsFileName)

Declaration
public Stream OpenRead(EbicsFileFolder aFileFolder, EbicsFileName aFileName)
Parameters
Type Name Description
EbicsFileFolder aFileFolder
EbicsFileName aFileName

Name of the file in this folder that shall be opened. This must not be null and must refer to an actually existing file. The properties IsHidden and IsEncrypted must have been set to match the actual file.
Returns
Type Description
Stream

If the file was opened successfully, then a non-seekable read-only Stream from it is returned. If the file is encrypted, then the returned Stream will decrypt the content on-thy-fly.
Remarks

The file is always opened with exclusive, non-shared access.

OpenRead(EbicsFileFolder, string, bool)

Declaration
public Stream OpenRead(EbicsFileFolder aFileFolder, string sFileName, bool fIsEncrypted)
Parameters
Type Name Description
EbicsFileFolder aFileFolder
string sFileName

The file system file name without any path information. The location of the file is given by the aFileFolder parameter.
bool fIsEncrypted

If this is true, then the file is assumed to be encrypted.
Returns
Type Description
Stream

OpenWrite(EbicsFileFolder, EbicsFileName)

Declaration
public Stream OpenWrite(EbicsFileFolder aFileFolder, EbicsFileName aFileName)
Parameters
Type Name Description
EbicsFileFolder aFileFolder
EbicsFileName aFileName

Name of the file in this folder that shall be created. This must not be null. If this refers to an existing file, then it will be overwritten. Regardless of the current value of the property IsEncrypted, the file will be encrypted if, and only if, the property IsProtected is true.
Returns
Type Description
Stream

If the file was opened successfully, then a non-seekable write-only Stream to it is returned. If the file is encrypted, then the returned Stream will encrypt the content on-thy-fly.
Remarks

The file is always opened with exclusive, non-shared access.

OpenWrite(EbicsFileFolder, string, bool)

Declaration
public Stream OpenWrite(EbicsFileFolder aFileFolder, string sFileName, bool fIsEncrypted)
Parameters
Type Name Description
EbicsFileFolder aFileFolder
string sFileName

The file system file name without any path information. The location of the file is given by the aFileFolder parameter.
bool fIsEncrypted

If this is true, then the file will be encrypted.
Returns
Type Description
Stream

If the file was opened successfully, then a non-seekable write-only Stream to it is returned. If the file is encrypted, then the returned Stream will encrypt the content on-thy-fly.
Remarks

The file is always opened with exclusive, non-shared access.

SetupAccessControl(EbicsFileSpoolerCredentials)

Sets up full access control for a currently unprotected EbicsFileSpooler spooler folder.

Declaration
public void SetupAccessControl(EbicsFileSpoolerCredentials aRootCredentials)
Parameters
Type Name Description
EbicsFileSpoolerCredentials aRootCredentials

The root credentials. The UserName must be ROOT, and the Password must not be null.
Remarks

Setting up access protection DOES NOT encrypt any existing files in the spooler folder tree. Only new files that are added to the spooler folders are encrypted and protected.

Successfully setting up access control implicitly switches this EbicsFileSpooler to use the given root access for all subsequent operations. Hence, it is possible to immediately set up users via CreateAccessControlEntry(EbicsFileFolder, EbicsFileSpoolerCredentials) after the method returns.

Setting up access control is not thread synchronised and therefore the caller must ensure that it is not called from multiple threads.

Exceptions
Type Condition
InvalidOperationException

File access control was already established, or this EbicsFileSpooler instance was already created with user credentials.

SubmitFileUpload(string, string, string, string, string)

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

Declaration
public EbicsFileName SubmitFileUpload(string sHostID, string sPartnerID, string sSourceFilePath, string sOrderType, string sFileId = null)
Parameters
Type Name Description
string sHostID
string sPartnerID
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.
string sOrderType

The EBICS OrderType that shall be used to upload the file.
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
ArgumentNullException

One of the required parameters was null.
EbicsFileSpoolerException

The BOX_OUTBOX folder is currently locked by another process.

SubmitSepaUpload(string, string, SepaDocument)

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

Declaration
public EbicsFileName SubmitSepaUpload(string sHostID, string sPartnerID, SepaDocument aSepaDocument)
Parameters
Type Name Description
string sHostID
string sPartnerID
SepaDocument aSepaDocument
Returns
Type Description
EbicsFileName

Returns the EbicsFileName of the order file that was created in the BOX_OUTBOX folder.
Exceptions
Type Condition
ArgumentNullException

One of the parameters was null.
ArgumentException

One of the parameters was invalid.
EbicsFileSpoolerException

The BOX_OUTBOX folder is currently locked by another process.

UpdateAccessControlList(EbicsFileFolder, EbicsFileSpoolerAccessControlList)

Rewrites the complete access control list file into the given folder.

Declaration
public void UpdateAccessControlList(EbicsFileFolder aFileFolder, EbicsFileSpoolerAccessControlList aAccessControlList)
Parameters
Type Name Description
EbicsFileFolder aFileFolder
EbicsFileSpoolerAccessControlList aAccessControlList

An access control list that must have been previously obtained through ObtainAccessControlList(EbicsFileFolder).