Class FinOrder

Namespace
Subsembly.FinTS
Assembly
Subsembly.FinTS.Core.dll

Base class that holds all segments that participate in a single FinTS order.

public class FinOrder : FinPersist
Inheritance
FinOrder
Derived
Inherited Members

Remarks

Usually a class derived from FinOrder is constructed through one of the specialized builder classes. Only if no specialized builder is available, then a FinOrder may be constructed from a manually built FinSegment that holds the order segment.

The ExecuteOrder(FinVopOrder, FinOrder, FinTan, string, FinSignerRole) method of the FinDialog class takes a FinOrder instance as its parameter. ExecuteOrder(FinVopOrder, FinOrder, FinTan, string, FinSignerRole) and the FinOrder class closely work together in order to execute the order online, in the context of the FinDialog. See ExecuteOrder(FinVopOrder, FinOrder, FinTan, string, FinSignerRole) for more information.

Once a FinOrder instance was executed by ExecuteOrder(FinVopOrder, FinOrder, FinTan, string, FinSignerRole), it is switched into the Executed state. In this state the result of the order is processed by the application. A FinOrder instance that was already executed cannot be executed again. For every order a new FinOrder instance must be created.

The FinOrder can be used as it is in order to conduct any kind of transaction. To do so, the order segment and response segments must be manually processed.

The FinOrder is also used as the base class for specialised transaction types such as FinAcctBal. It can also be used as a base class for your own specialised transaction types.

Constructors

FinOrder()

This default ctor should only be used for loading a previously persisted instance of this FinOrder.

public FinOrder()

Remarks

If the FinOrder was persisted via its FinPersist base class, then this constructor may be called and the order be loaded from the persisted state.

FinOrder(FinSegment, FinAcct)

Creates a generic FinOrder instance, using the given order segment.

public FinOrder(FinSegment aOrderSegment, FinAcct aOrderAcct)

Parameters

aOrderSegment FinSegment

The order segment that contains the order details of this order. This segment will be sent to the FinTS server when ExecuteOrder(FinVopOrder, FinOrder, FinTan, string, FinSignerRole) is called with this FinOrder instance.

aOrderAcct FinAcct

Properties

DialogID

Provides the Dialog ID of the FinTS dialog during which the order was sent.

public string DialogID { get; }

Property Value

string

May be null if the FinOrder was not executed, yet.

Executed

Indicates whether this FinOrder instance was already Executed by ExecuteOrder(FinVopOrder, FinOrder, FinTan, string, FinSignerRole).

public bool Executed { get; }

Property Value

bool

When ExecuteOrder(FinVopOrder, FinOrder, FinTan, string, FinSignerRole) completes executing the given FinOrder instance it will set its Executed flag, regardless of whether the order was executed successfully or whether the FinTS server returned an error code.

HvbDistOrder

If true, then this is a very special HypoVereinsbank partially signed order.

public bool HvbDistOrder { get; set; }

Property Value

bool

Remarks

Orders with this flag are wrapped in a pair of BNLSK and BNLSA segments, when the message is built by the FinMessage class. This is a very special HypoVereinsbank extension and is not supported by any other bank.

MsgNo

Provides the message sequence number of the FinTS message that carried this order.

public int MsgNo { get; }

Property Value

int

May be zero if the FinOrder was not executed, yet.

OrderAcct

Order account.

public FinAcct OrderAcct { get; }

Property Value

FinAcct

Remarks

The order account must be provided to the ctor by the corresponding order builder class. It may be null, if, any only if, there is no order account for this order type. The order account may be required for building the HKTAN segment when using the Smart-TAN procedure.

OrderAmount

Optional order amount.

public SwiftAmt OrderAmount { get; set; }

Property Value

SwiftAmt

Remarks

The order amount is only available when it was initialized by the corresponding order builder class. Otherwise the initial null value is returned.

The order amount may be required for building the HKTAN segment when using the Smart-TAN procedure. If it is not provided by the order builder, then it can be set by the application before this order is sent.

OrderChallengeClass

The TAN procedure challenge class of this order.

public int OrderChallengeClass { get; set; }

Property Value

int

Remarks

The default value of this property is 90, which is the miscellaneous challenge class. A particual order builder shall set this property according to the order type.

The order challenge class may be required for building the HKTAN segment when using the Smart-TAN procedure. If it is not provided by the order builder, then it can be set by the application before this order is sent.

OrderChallengeParameter

An optional TAN procedure challenge parameter that may be required for this order.

public string OrderChallengeParameter { get; set; }

Property Value

string

Remarks

The default value of this property is null. If, according to the TAN procedure Smart-TAN, a special challenge parameter is needed, then the order builder shall set this property accordingly.

The order challenge parameter may be required for building the HKTAN segment when using the Smart-TAN procedure. If it is not provided by the order builder, then it can be set by the application before this order is sent.

OrderID

Provides the optional Order ID that was returned for this order.

public string OrderID { get; }

Property Value

string

OrderSegNo

Convenience accessor to the segment sequence number of the order segment.

public int OrderSegNo { get; }

Property Value

int

OrderSegment

The order segment that contains the order details of this order. This segment will be sent to the FinTS server when ExecuteOrder(FinVopOrder, FinOrder, FinTan, string, FinSignerRole) is called with this FinOrder instance. This is never null.

public FinSegment OrderSegment { get; }

Property Value

FinSegment

OrderType

Convenience accessor to the segment type of the order segment.

public string OrderType { get; }

Property Value

string

OrderVisualizationClass

The visualization class of this order.

public int OrderVisualizationClass { get; set; }

Property Value

int

Remarks

This value is required when building a HKTAN version 5 segment for this order. It is not required for older HKTAN segments, or if a HKTAN is never built for this order.

The default value is zero, which actually applies to no order type. Hence, if a HKTAN version 5 will ever be built for this order, then this property must properly initialized, first. Usually the specialized order builder does this for you.

ResponseSegment

Convenience property that provides direct access to a single response segment.

public FinSegment ResponseSegment { get; }

Property Value

FinSegment

Remarks

If, and only if, the ResponseSegments collection contains just a single segment, then this segment is returned. If no response segments are available, or more than one response segment is available, then null is returned.

ResponseSegments

Provides access to the FinSegments collection that contains the response data segments of this order.

public FinSegments ResponseSegments { get; }

Property Value

FinSegments

StatusSegment

Provides the HIRMS status segment that was replied to this order.

public FinStatusSegment StatusSegment { get; }

Property Value

FinStatusSegment

May be null if no HIRMS status segment was received for this FinOrder or the FinOrder was not executed, yet.

StatusThreshold

The minimum status code of interest for this order.

public int StatusThreshold { get; set; }

Property Value

int

An HBCI status code threshold value in the range from zero through 10000. The value 10000 effectively suppresses all status output. The default value is zero.

Remarks

This property can be used by the application in order to indicate the minimum response status code that it is interested in. By default the status threshold is zero, indicating that all status responses are important. It may make sense to set a higher threshold for inquiry orders in order to suppress the warnings for an empty result set.

Success

Convenience property that provides direct access to the Success property of the StatusSegment.

public bool Success { get; }

Property Value

bool

If the order was not executed yet and no StatusSegment is available, then false is returned. If the order was executed and there are ResponseSegments but no StatusSegment, then true is returned, anyway.

TanOrderRef

The TAN order reference from OrderRef, if one was used.

public string TanOrderRef { get; }

Property Value

string

Methods

AddOrderVisualizationParameter(FinDataElement)

Adds another visualization parameters to this order.

public void AddOrderVisualizationParameter(FinDataElement aVisualizationParameter)

Parameters

aVisualizationParameter FinDataElement

A data element that holds the visualization parameter. This may be null if an empty visualization parameter shall be added.

Remarks

The visualization parameters are required when building a HKTAN version 5 segment for this order. It is not required for older HKTAN segments, or if a HKTAN is never built for this order.

Usually the specialized order builder will add all necessary visualization parameters for you.

GetOrderVisualizationParameters()

Gets all the visualization parameters for this order.

public FinDataElement[] GetOrderVisualizationParameters()

Returns

FinDataElement[]

Returns an array with all the visualization parameters that have been added through AddOrderVisualizationParameter(FinDataElement). The returned array may contain null values, representing unused visualization parameter positions.

InsertScrollRef(string)

Inserts the given scroll reference into the order segment.

protected virtual bool InsertScrollRef(string sScrollRef)

Parameters

sScrollRef string

Scroll reference that was returned and shall be inserted into the order segment. This is not null.

Returns

bool

If this FinOrder derived class actually supports automatic handling of scroll references, and the given scroll reference was inserted into the order segment, then true must be returned. If handling of scroll references is not supported by the derived class, then false must be returned.

Remarks

If a scroll reference was returned, then this method is invoked in order to prepare the order segment for an immediate follow-up transaction.

The generic FinOrder base implementation of this method always returns false. A specialised derived order class must override this method in order to implement support for automatic handling of scroll references.

OnExecuteComplete(FinDialog)

Indicates that the FinOrder was executed to the derived class.

protected virtual void OnExecuteComplete(FinDialog aDialog)

Parameters

aDialog FinDialog

The dialog instance that was used to send the order. This is never null.

Remarks

A derived class may override this method in order to do any post processing on the executed FinOrder.

ReadXml(XmlReader) 

public override void ReadXml(XmlReader aXmlReader)

Parameters

aXmlReader XmlReader

SetOrderID(string)

Set the value for the OrderID property.

protected void SetOrderID(string sOrderID)

Parameters

sOrderID string

Remarks

If applicable, this method shall be called in a derived classes OnExecuteComplete(FinDialog) override in order to set the new Order ID that was extracted from the response data segment.

SetOrderSegment(FinSegment)

Sets the order segment of this FinOrder from the constructor in derived classes.

protected void SetOrderSegment(FinSegment aOrderSegment)

Parameters

aOrderSegment FinSegment

Exceptions

ArgumentNullException

An attempt was made to set a null reference.

InvalidOperationException

An attempt was made to set the order segment, but this FinOrder instance has already an order segment.

WriteXml(XmlWriter) 

public override void WriteXml(XmlWriter aXmlWriter)

Parameters

aXmlWriter XmlWriter