Class EbicsOrder

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

Inheritance

System.Object

EbicsOrder

EbicsOrderAZV

EbicsOrderCamt

EbicsOrderDownloadZip

EbicsOrderHAA

EbicsOrderHCA

EbicsOrderHCS

EbicsOrderHIA

EbicsOrderHPB

EbicsOrderHPD

EbicsOrderHVD

EbicsOrderHVList

EbicsOrderHVPick

EbicsOrderHVT

EbicsOrderHxD<TResponseOrderData>

EbicsOrderINI

EbicsOrderProtocol

EbicsOrderPUB

EbicsOrderSepa

EbicsOrderSPR

EbicsOrderSRZ

EbicsOrderWSS

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 EbicsOrder

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

Declaration

public EbicsOrder()

EbicsOrder(EbicsService, EbicsTransferType, EbicsStandardOrderParams)

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

Declaration

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

Parameters

Type	Name	Description
EbicsService	aService	The Service element for EBICS 3.x.
EbicsTransferType	nTransferType
EbicsStandardOrderParams	aOrderParams	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

Type	Condition
System.ArgumentNullException
System.ArgumentException

EbicsOrder(String, EbicsTransferType)

Creates a new Upload or Download order with empty EbicsStandardOrderParams.

Declaration

public EbicsOrder(string sOrderType, EbicsTransferType nTransferType)

Parameters

Type	Name	Description
System.String	sOrderType
EbicsTransferType	nTransferType

Exceptions

Type	Condition
System.ArgumentNullException	The parameter sOrderType was null.
System.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.

Declaration

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

Parameters

Type	Name	Description
System.String	sOrderType	The three letter order type.
EbicsTransferType	nTransferType	Direction of data transfer of this order. Must be Download or Upload.
EbicsStandardOrderParams	aOrderParams	Optional order parameters.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter sOrderType was null.
System.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.

Declaration

public string AdditionalOrderInfo { get; set; }

Property Value

Type	Description
System.String

AdminOrderType

The EBICS 3.0 AdminOrderType.

Declaration

public string AdminOrderType { get; set; }

Property Value

Type	Description
System.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

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

AuthorisationLevel

Declaration

public EbicsAuthorisationLevel AuthorisationLevel { get; set; }

Property Value

Type	Description
EbicsAuthorisationLevel

BusinessReturnCode

The business related return code returned for this order.

Declaration

public EbicsReturnCode BusinessReturnCode { get; }

Property Value

Type	Description
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.

Declaration

public EbicsErrorClass ErrorClass { get; }

Property Value

Type	Description
EbicsErrorClass

Remarks

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

See Also

Success

OrderAttribute

The order attributes.

Declaration

public string OrderAttribute { get; set; }

Property Value

Type	Description
System.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.

Declaration

public EbicsDataBuffer OrderData { get; set; }

Property Value

Type	Description
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.

Declaration

public string OrderID { get; set; }

Property Value

Type	Description
System.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

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.

OrderParams

Any EbicsElement implementation that provides the order parameters.

Declaration

public EbicsOrderParams OrderParams { get; set; }

Property Value

Type	Description
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.

Declaration

public EbicsOrderSignatures OrderSignatures { get; }

Property Value

Type	Description
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.

Declaration

public string OrderType { get; set; }

Property Value

Type	Description
System.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

Type	Condition
System.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.

Declaration

public EbicsService Service { get; set; }

Property Value

Type	Description
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.

Declaration

public bool Success { get; }

Property Value

Type	Description
System.Boolean

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.

Declaration

public bool SuccessOrNoData { get; }

Property Value

Type	Description
System.Boolean

TechnicalReturnCode

The technical return code returned for this order.

Declaration

public EbicsReturnCode TechnicalReturnCode { get; }

Property Value

Type	Description
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.

Declaration

public EbicsTransaction Transaction { get; }

Property Value

Type	Description
EbicsTransaction

TransactionID

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

Declaration

public string TransactionID { get; }

Property Value

Type	Description
System.String

TransactionState

The current and final EbicsTransactionState from executing this Order.

Declaration

public EbicsTransactionState TransactionState { get; }

Property Value

Type	Description
EbicsTransactionState

TransactionTraceText

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

Declaration

public string TransactionTraceText { get; }

Property Value

Type	Description
System.String

TransferType

Determines the transfer type of this order.

Declaration

public EbicsTransferType TransferType { get; set; }

Property Value

Type	Description
EbicsTransferType

Exceptions

Type	Condition
System.ArgumentException

Upload

Determines the transfer type of this order.

Declaration

public bool Upload { get; set; }

Property Value

Type	Description
System.Boolean	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.

Declaration

public static string CreateNextOrderID()

Returns

Type	Description
System.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.

Declaration

public virtual void ProcessResponseOrderData(EbicsVersion nVersion)

Parameters

Type	Name	Description
EbicsVersion	nVersion

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.

Declaration

public virtual EbicsSecurityMediumErrorCode Sign(EbicsContact aContact, IEbicsSecurityMedium aSecurityMedium)

Parameters

Type	Name	Description
EbicsContact	aContact
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.