Class EbicsOrder

Namespace: Subsembly.EBICS

Assembly: Subsembly.EBICS.Core.dll

Stores the details, data, signatures and status of an EBICS order.

public class EbicsOrder

Inheritance: object

EbicsOrder

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

In order to create a new upload or download order, a new instance of this class must be created and its properties must be initialized as required. For upload orders the complete order data must be provided by setting the OrderData property.

EBICS orders are then processed online by the EbicsTransaction class. After processing is complete the final technical return code is provided through TechnicalReturnCode and the final business related return code is provided through the BusinessReturnCode property. For download orders the complete received data is decrypted and stored in OrderData.

In EBICS version 2.4 or earlier for Upload orders an order ID must be provided by the client. Starting with EBICS version 2.5 the order ID is provided by the server, instead. To handle all EBICS versions gracefully, the EbicsTransaction class will automatically create an order ID for uploads, when needed. A client application should not provide an order ID by itself, but rely on the fact that the actual order ID is available through the OrderID property after the transaction response was received.

Constructors

EbicsOrder()

public EbicsOrder()

EbicsOrder(EbicsService, EbicsTransferType, EbicsStandardOrderParams)

Creates a new Upload or Download order for EBICS 3.x.

public EbicsOrder(EbicsService aService, EbicsTransferType nTransferType, EbicsStandardOrderParams aOrderParams = null)

Parameters

aService EbicsService: The Service element for EBICS 3.x.
nTransferType EbicsTransferType
aOrderParams EbicsStandardOrderParams: Optional order parameters.

Remarks

This will create either a BTU or a BTD order, depending on the given nTransferType. Administrative orders cannot be created with this constructor.

Exceptions

ArgumentNullException
ArgumentException

EbicsOrder(string, EbicsTransferType)

Creates a new Upload or Download order with empty EbicsStandardOrderParams.

public EbicsOrder(string sOrderType, EbicsTransferType nTransferType)

Parameters

sOrderType string
nTransferType EbicsTransferType

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.

EbicsOrder(string, EbicsTransferType, EbicsStandardOrderParams)

Creates a new Upload or Download order with the given order parameters.

public EbicsOrder(string sOrderType, EbicsTransferType nTransferType, EbicsStandardOrderParams aOrderParams)

Parameters

sOrderType string: The three letter order type.
nTransferType EbicsTransferType: Direction of data transfer of this order. Must be Download or Upload.
aOrderParams EbicsStandardOrderParams: Optional order parameters.

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.

Properties

AdditionalOrderInfo

Optional additional order information introduced with EBICS 3.0.

public string AdditionalOrderInfo { get; set; }

Property Value

string

AdminOrderType

The EBICS 3.0 AdminOrderType.

public string AdminOrderType { get; set; }

Property Value

string

Remarks

If this order is sent over an EBICS 2.x connection, then this value is ignored. In order to support EBICS 2.x, the OrderType must always be filled properly with the EBICS 2.x order type.

If this is null and the order is sent over an EBICS 3.x connection, then an attempt is made to derive the appropriate AdminOrderType from the OrderType.

Exceptions

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

AuthorisationLevel

public EbicsAuthorisationLevel AuthorisationLevel { get; set; }

Property Value

EbicsAuthorisationLevel

BusinessReturnCode

The business related return code returned for this order.

public EbicsReturnCode BusinessReturnCode { get; }

Property Value

EbicsReturnCode

Remarks

This is the final business related return code that was received from the bank when processing this order. If the order was not processed, or no return code was received, then this will be null.

ErrorClass

The higher ErrorClass from the TechnicalReturnCode or BusinessReturnCode.

public EbicsErrorClass ErrorClass { get; }

Property Value

EbicsErrorClass

Remarks

If there is neither a TechnicalReturnCode nor a BusinessReturnCode, and no EbicsSecurityMediumErrorCode, then the return value is Undefined.

See Also: Success

NoData

True if the technical return code indicates Success and the business return code is EBICS_NO_DOWNLOAD_DATA_AVAILABLE.

public bool NoData { get; }

Property Value

bool

OrderAttribute

The order attributes.

public string OrderAttribute { get; set; }

Property Value

string: This is a 5 character alphanumeric token value, or null if not set.

Remarks

This value should not be set anymore because it does not exist in EBICS 3.0. The new property AuthorisationLevel should be set instead. When reading this OrderAttribute suitable order attributes are derived from the AuthorisationLevel, unless it was explicitly set.

If this value is set, then it will only be ever used, when EBICS version 2.5 or earlier is used. When EBICS 3.0 is used, the value is completely ignored.

OrderData

The complete, plain (unencrypted) order data.

public EbicsDataBuffer OrderData { get; set; }

Property Value

EbicsDataBuffer

Remarks

For upload orders this property must be set in order to provide the complete order data to be uploaded. For large data amounts a memory mapped file may be used instead of copying all data into the system main memory.

For download orders this property provides the complete received order data after the order was processed. An application has only read access to this data.

OrderID

The order number or order ID.

public string OrderID { get; set; }

Property Value

string: This must be a 4 character alphanumeric value according to the pattern [A-Z][A-Z0-9]{3}, or null if not set.

Remarks

OrderParams

Any EbicsElement implementation that provides the order parameters.

public EbicsOrderParams OrderParams { get; set; }

Property Value

EbicsOrderParams

Remarks

With EBICS 2.x only, usually an instance of EbicsStandardOrderParams was provided here. Since EBICS 3.0 this should be a EbicsBTDOrderParams or EbicsBTUOrderParams instance. For special adminstrative order types, this may be a special order parameter type.

If this is a EbicsStandardOrderParams instance, and the order is sent over an EBICS 3.0 connection using the BTD or BTU AdminOrderType, then an attempt is made to create suitable EbicsBTDOrderParams or EbicsBTUOrderParams order parameters from the given OrderType, Service, and EbicsStandardOrderParams.

OrderSignatures

Collection of user signatures over the order data.

public EbicsOrderSignatures OrderSignatures { get; }

Property Value

EbicsOrderSignatures

OrderType

The EBICS 2.x order type. If possible, this should also be set when the order will be sent over an EBICS 3.0 connection.

public string OrderType { get; set; }

Property Value

string: This is a 3 character alphanumeric value according to the pattern [A-Z0-9]{3}, or null if not set.

Remarks

If no EBICS 3.0 EbicsBTFOrderParams has been provided in OrderParams, and this order is sent over an EBICS 3.0 connection, then an attempt is made to derive a suitable EbicsBTFOrderParams from the given order type. If this is not possible, then the order cannot be sent over an EBICS 3.0 connection.

To ensure compatibility with EBICS 3.0, the Service or OrderParams should be set in addition to the OrderType.

If this OrderType is not set, then this order cannot be sent over an EBICS 2.x connection. In order to support EBICS 2.x and EBICS 3.0 connections, OrderType and Service or OrderParams must be set appropriately.

Exceptions

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

Service

The EBICS 3.0 service element. This is used when sending the order over an EBICS 3.0 (or later) connection. It is ignored for older EBICS versions.

public EbicsService Service { get; set; }

Property Value

EbicsService

Remarks

If a well-known OrderType was set, and this property was not set, then an attempt is made to create a suitable EbicsService by using the EbicsServiceMap.

See Also: EbicsServiceMap

Success

Is true if, and only if, both return codes indicate a successful completion of the order.

public bool Success { get; }

Property Value

bool

Remarks

If either the TechnicalReturnCode or the BusinessReturnCode have not been received (i.e. are still null), then this property will be false.

See Also: ErrorClass

SuccessOrNoData

SuccessOrNoData

True if the return code indicates Success or if the business return code is EBICS_NO_DOWNLOAD_DATA_AVAILABLE.

public bool SuccessOrNoData { get; }

Property Value

bool

TechnicalReturnCode

The technical return code returned for this order.

public EbicsReturnCode TechnicalReturnCode { get; }

Property Value

EbicsReturnCode

Remarks

This is the final technical return code that was received from the bank when processing this order. If the order was not processed, or no return code was received, then this will be null.

Transaction

The EbicsTransaction instance that was used to execute this order.

public EbicsTransaction Transaction { get; }

Property Value

EbicsTransaction

TransactionID

The Transaction ID that was assigned during execution of this Order.

public string TransactionID { get; }

Property Value

string

TransactionState

The current and final EbicsTransactionState from executing this Order.

public EbicsTransactionState TransactionState { get; }

Property Value

EbicsTransactionState

TransactionTraceText

The EBICS trace text that was collected by the Transaction executing this order.

public string TransactionTraceText { get; }

Property Value

string

TransferType

Determines the transfer type of this order.

public EbicsTransferType TransferType { get; set; }

Property Value

EbicsTransferType

Exceptions

ArgumentException

Upload

Determines the transfer type of this order.

public bool Upload { get; set; }

Property Value

bool: If true, then this is an Upload order, if false, then this is a Download order. The default value is false.

Methods

CreateNextOrderID()

Creates another likely unique order ID.

public static string CreateNextOrderID()

Returns

string

Remarks

This method creates a different order ID every second, wrapping after 46656 seconds, or approximately 13 hours. A static counter ensures that unique order IDs are generated if this method is called quicker than once per second. Also, the first character of the order ID changes every day, wrapping after 26 days. Thus, if your orders are maintained in the host system for longer than 26 days, then there is a minimal chance of getting a duplicate order ID if you send another order at the very same second 26 days later.

ProcessResponseOrderData(EbicsVersion)

Override in derived class for processing of response OrderData.

public virtual void ProcessResponseOrderData(EbicsVersion nVersion)

Parameters

nVersion EbicsVersion

Remarks

This method is invoked by ProcessResponse(XmlDocument) (and thus also indirectly by Execute(IEbicsTransport)) whenever response order data was received in a download transaction. A derived class that implements a download order should override this method in order to process the received OrderData.

Sign(EbicsContact, IEbicsSecurityMedium)

Sign this order by a given contact.

public virtual EbicsSecurityMediumErrorCode Sign(EbicsContact aContact, IEbicsSecurityMedium aSecurityMedium)

Parameters

aContact EbicsContact
aSecurityMedium IEbicsSecurityMedium: 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

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.