CashChanger Class (POS for .NET v1.12 SDK Documentation)
2/27/2008
Defines the programmatic interface for a UPOS Cash Changer device.
Namespace: Microsoft.PointOfService
Assembly: Microsoft.PointOfService (in microsoft.pointofservice.dll)
Syntax
'Declaration
Public MustInherit Class CashChanger
Inherits PosCommon
public abstract class CashChanger : PosCommon
public ref class CashChanger abstract : public PosCommon
public abstract class CashChanger extends PosCommon
public abstract class CashChanger extends PosCommon
Remarks
Capabilities
The cash changer has the following capabilities:
Reports the cash units and corresponding unit counts available in the cash changer.
Dispenses a specified amount of cash from the device in either bills, coins, or both into a user-specified exit.
Dispenses a specified number of cash units from the device in either bills, coins, or both into a user-specified exit.
Reports jam conditions within the device.
Supports more than one currency.
The cash changer may also have the following additional capabilities:
Reporting the fullness levels of the cash units of a cash changer. Conditions which can be indicated include empty, almost empty, full, and almost full states.
Reporting of a possible (or probable) cash count discrepancy in the data reported by the ReadCashCounts method.
Programming Model
The general model of a cash changer is as follows:
Supports several cash types such as coins, bills, and combinations of coins and bills. The supported cash type for a particular currency is noted by the list of cash units in the CurrencyCashList property.
Consists of any combination of features to help carry out the cash-processing functions such as a cash entry holding bin, several slots or bins that can hold the cash, and cash exits.
Provides programmatic control only for the dispensing of cash. The acceptance of cash by the device (for example, to replenish cash) cannot be controlled by the APIs provided in this model. The application can call the ReadCashCounts method to retrieve the current unit count for each cash unit.
May have multiple exits. The number of exits is specified in the DeviceExits property. The application chooses a dispensing exit by setting the CurrentExit property. The cash units that may be dispensed to the current exit are indicated by the ExitCashList property. When the CurrentExit value is 1, the exit is considered the primary exit, typically used during usual processing for dispensing cash to a customer following a retail transaction. When the CurrentExit property is a value greater than 1, the exit is considered an auxiliary exit. An auxiliary exit typically is used for special purposes such as dispensing quantities or types of cash not targeted for the primary exit.
Dispensing cash into the exit specified by the CurrentExit property is performed by calling either the DispenseChange or DispenseCash method. With the DispenseChange method, the application specifies a total amount to dispense, and it is the responsibility of the cash changer device or the service object to dispense the correct amount of cash from the various slots or bins. With the DispenseCash method, the application specifies a count of each cash unit to dispense.
Dispenses cash either synchronously or asynchronously, depending on the value of the AsyncMode property.
When AsyncMode is false, the cash dispensing methods are performed synchronously and the dispensing method returns the completion status to the application.
When the AsyncMode property is true and the DispenseChange or DispenseCash method is successful, the method is performed asynchronously and its completion is indicated by a StatusUpdateEvent event containing StatusAsync as its Status value. The method’s completion status is set in the AsyncResultCode and AsyncResultCodeExtended properties.
The values of the AsyncResultCode and AsyncResultCodeExtended properties are the same as those returned in the ErrorCode and ErrorCodeExtended properties when synchronous dispensing is chosen.
The ReadCashCounts method cannot be performed while an asynchronous method is being performed because doing this might report incorrect cash counts.
Can support more than one currency. The CurrencyCode property can be set to the currency, selecting from a currency in CurrencyCodeList. The properties and methods CurrencyCashList, ExitCashList, DispenseCash, DispenseChange and ReadCashCounts all act upon the current currency only.
Sets the cash slot (or cash bin) conditions in the DeviceStatus property to show empty and almost empty status, and in the FullStatus property to show full and almost full status. If there are one or more empty cash slots, DeviceStatus is Empty, and if there are one or more full cash slots, then FullStatus is Full.
The cash acceptance model is as follows:
The DispenseChange and DispenseCash methods are independent of the cash acceptance function. The AsyncMode property value does not affect cash acceptance methods.
If the CapDeposit property is true, cash acceptance is supported and the BeginDeposit, FixDeposit, and EndDeposit methods are in use. Cash dispensing is disabled while cash acceptance is in progress. Also, cash acceptance is disabled while cash dispensing is in progress.
When the application calls the BeginDeposit method, the DepositCounts and DepositAmount properties are initialized to zero.
When the cash changer accepts cash, the value of the DepositCounts and DepositAmount properties increase, and a DataEvent event is raised if the CapDepositDataEvent property is true.
If the CapPauseDeposit property is true, the application can pause cash acceptance by calling the PauseDeposit method with a parameter of Pause. Then, the value of the DepositCounts and DepositAmount properties is fixed. If the application wants to resume cash acceptance, it calls the PauseDeposit method again with a parameter value of Restart. By reading either the DepositCounts or DepositAmount property, the application can get the exact amount of accepted cash, and compare the accepted cash total with the sale amount. If the accepted cash is equal to or greater than the amount of the sale, the application calls the FixDeposit method. If the accepted cash is less than amount of the sale, the application calls the PauseDeposit method with Restart. To get the total amount of accepted cash, the application should repeat the PauseDeposit method.
When the FixDeposit method is called, the cash changer stops accepting cash and the value of the DepositCounts and DepositAmount is fixed.
If it is necessary, the application can calculate the change by using the DepositCounts and DepositAmount properties after the FixDeposit method. After the FixDeposit method is called, the application cannot resume cash acceptance and must call the EndDeposit method to complete the cash acceptance process.
To exit the cash acceptance process, the application must call the EndDeposit method.
The values of the success parameter of the EndDeposit method have the following meanings:
Change: The application dispenses cash. This is typically used to dispense change due from a sale.
NoChange: The application does not dispense cash. This typically indicates that the total amount of accepted cash is equal to the total amount of the sale.
Repay: The application repays the total amount of cash. This typically is a cancellation of the sale. Repay can only be used when CapRepayDeposit is true. If CapRepayDeposit is false, the application must dispense the total amount of accepted cash by calling either the DispenseChange or DispenseCash method. Some cash changers may not repay accepted cash, depending on the cash changer mechanism.
When the ClearInput method is run, all queued DataEvent events associated with cash acceptance are cleared. But the value of the DepositCounts and DepositAmount properties are not cleared.
Device Sharing
The cash changer is an exclusive-use device. Its device sharing rules are as follows:
The application must claim the device the application enables it.
The application must claim and enable the device before accessing some properties, dispensing or collecting, or receiving status update events.
Inheritance Hierarchy
System.Object
Microsoft.PointOfService.PosDevice
Microsoft.PointOfService.PosCommon
Microsoft.PointOfService.CashChanger
Microsoft.PointOfService.BasicServiceObjects.CashChangerBasic
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread-safe. Any instance members are not guaranteed to be thread-safe.