POS for .NET Device Basic Classes
Each hardware device in POS for .NET is represented by both an abstract interface, such as CashDrawer class, and a “basic” class, such as CashDrawerBasic. Basic classes derive from the underlying interface and contain basic functional support for the device. POS for .NET provides generic support for opening, claiming, and enabling the device; device statistics; and management of delivery of events to the application. In addition, each basic class contains a set of inherited and protected methods that can be implemented by the service object. This topic provides summary information about basic classes that can be used by service objects that wish to derive from the device’s basic class, rather than taking advantage of the more fully implemented device base class.
Each basic class includes a constructor that creates an instance of the class and initializes statistics for UPOS Version, the Device Category, and the Installation Date.
Common Properties and Methods
Each basic class provides overridden PosCommon property and method definitions. For each of these properties and methods, the basic class handles state validation—that is, verification that the application has opened, claimed, or enabled the device—and then calls the POS for .NET implementation of that property or method. For more information, see the PosCommon class topics.
The service object can use the CommonProperties class to update PosCommon properties that are designated read-only for the application, or to update those properties without worrying about state validation.
Each basic class includes two implemented Dispose methods for use by the service object. For information about how these work, see the .NET Framework documentation for the IDisposable class.
Opening, Claiming, and Enabling Devices
Each basic class provides the core functionality for opening, claiming, and enabling devices. Typically, though, service objects will want to override these methods to add their own custom processing.
Protected Methods and Events for Service Object Writers
Each basic class contains a group of methods and events for the service object writer.
The following protected properties are defined:
- A CommonProperties property, which returns an instance of CommonProperties with getters and setters for all PosCommon properties. The service object can use CommonProperties to update properties without worrying about state validation or whether the property is designated read-only for the application.
- An ExternallyClaimed property, which service objects can retrieve to determine if another instance of the device has been claimed (in which case, the property is set to TRUE).
- An ErrorCount property. When the service object queries for the value of ErrorCount, the basic class checks the event queue and tallies the number of ErrorEvent events found, then returns that tally as the value of ErrorCount.
- A DataCount property. POS for .NET verifies that the device has been opened, then returns the number of DataEvent events currently queued for the device.
The following protected methods are defined:
- A StateChangedEvent and delegate StateChangedEventHandler (EventArgs class). The service object can implement these to receive notification when the device’s State property has changed.
- PreFireEvent protected methods for each type of event supported by the device. Each basic class provides a default, generic implementation of PreFireEvent that returns immediately. If the service object needs to update its internal state prior to an event being sent to the application, the service object can override the default implementation of PreFireEvent and provide its own implementation for the event type in question;
- QueueEvent protected methods for each type of event supported by the device. The service object calls QueueEvent to add an event to the event queue. The basic class verifies that the device is enabled, then adds the event to the event queue, to be delivered to the application when conditions are correct. Immediately before delivery, the basic class calls the appropriate PreFireEvent to give the service object an opportunity to update its internal state. When PreFireEvent returns, the basic class delivers the event to the application;
- QueueEventAndWait protected methods. The service object calls QueueEventAndWait to add an ErrorEvent event or DirectIOEvent event to the event queue, from which the service object expects a response from the application. The basic class verifies that the device is enabled, then adds the event to the event queue, to be delivered to the application when conditions are correct. Immediately before delivery, the basic class calls PreFireEvent to give the service object an opportunity to update its internal state. When PreFireEvent returns, the basic class delivers the event to the application;
- VerifyState method, which takes two Boolean values, mustBeClaimed and mustBeEnabled. The service object can call POS for .NET’s implementation of this method to perform the necessary state validation for the device, prior to a method or property call.
- CreateStatistic method. The service object should use these methods to create custom (that is, manufacturer-specific) statistics. POS for .NET handles the creation and management of all UPOS-defined statistics.
- SetStatisticValue and IncrementStatistic methods allow the service object to update a specified statistic even if it isn’t defined as resettable (that is, these methods bypass the rules enforced by the PosCommonResetStatistic and UpdateStatistic methods).
- SetStatisticHandlers method, which allows service objects to provide external callback functions for the retrieval and setting of hardware-based statistics. If a getter isn’t defined, the basic class assumes that the statistic is software-based, and its value is maintained in the statistics XML file. If both getters and setters are defined, the basic class will call these functions whenever the statistic needs to be updated or reset. It is up to the service object to provide code to update the statistic in the hardware.
- ClearInput method. POS for .NET clears the event queues for the device and then calls the service object’s implementation of ClearInputImpl.
- ClearInputImpl method. The service object should implement this method to clear any hardware buffers for the device.