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.

Declaration

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.

Declaration

public FinOrder(FinSegment aOrderSegment, FinAcct aOrderAcct)

Parameters

Type	Name	Description
FinSegment	aOrderSegment	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.
FinAcct	aOrderAcct

Properties

DialogID

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

Declaration

public string DialogID { get; }

Property Value

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

Declaration

public bool Executed { get; }

Property Value

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

Declaration

public bool HvbDistOrder { get; set; }

Property Value

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

Declaration

public int MsgNo { get; }

Property Value

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

OrderAcct

Order account.

Declaration

public FinAcct OrderAcct { get; }

Property Value

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

Declaration

public SwiftAmt OrderAmount { get; set; }

Property Value

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

Declaration

public int OrderChallengeClass { get; set; }

Property Value

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

Declaration

public string OrderChallengeParameter { get; set; }

Property Value

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

Declaration

public string OrderID { get; }

Property Value

Type	Description
string

OrderSegNo

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

Declaration

public int OrderSegNo { get; }

Property Value

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

Declaration

public FinSegment OrderSegment { get; }

Property Value

Type	Description
FinSegment

OrderType

Convenience accessor to the segment type of the order segment.

Declaration

public string OrderType { get; }

Property Value

Type	Description
string

OrderVisualizationClass

The visualization class of this order.

Declaration

public int OrderVisualizationClass { get; set; }

Property Value

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

Declaration

public FinSegment ResponseSegment { get; }

Property Value

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

Declaration

public FinSegments ResponseSegments { get; }

Property Value

Type	Description
FinSegments

StatusSegment

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

Declaration

public FinStatusSegment StatusSegment { get; }

Property Value

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

Declaration

public int StatusThreshold { get; set; }

Property Value

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

Declaration

public bool Success { get; }

Property Value

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

Declaration

public string TanOrderRef { get; }

Property Value

Type	Description
string

Methods

AddOrderVisualizationParameter(FinDataElement)

Adds another visualization parameters to this order.

Declaration

public void AddOrderVisualizationParameter(FinDataElement aVisualizationParameter)

Parameters

Type	Name	Description
FinDataElement	aVisualizationParameter	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.

Declaration

public FinDataElement[] GetOrderVisualizationParameters()

Returns

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

Declaration

protected virtual bool InsertScrollRef(string sScrollRef)

Parameters

Type	Name	Description
string	sScrollRef	Scroll reference that was returned and shall be inserted into the order segment. This is not null.

Returns

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

Declaration

protected virtual void OnExecuteComplete(FinDialog aDialog)

Parameters

Type	Name	Description
FinDialog	aDialog	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)

Declaration

public override void ReadXml(XmlReader aXmlReader)

Parameters

Type	Name	Description
XmlReader	aXmlReader

Overrides

FinPersist.ReadXml(XmlReader)

SetOrderID(string)

Set the value for the OrderID property.

Declaration

protected void SetOrderID(string sOrderID)

Parameters

Type	Name	Description
string	sOrderID

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.

Declaration

protected void SetOrderSegment(FinSegment aOrderSegment)

Parameters

Type	Name	Description
FinSegment	aOrderSegment

Exceptions

Type	Condition
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)

Declaration

public override void WriteXml(XmlWriter aXmlWriter)

Parameters

Type	Name	Description
XmlWriter	aXmlWriter

Overrides

FinPersist.WriteXml(XmlWriter)