PosCommon Information for Service Object Developers
2/27/2008
At the base of the POS for .NET Server Object class tree (Interface, Basic, Base) is PosCommon. This class is a direct implementation of the "Common Properties, Methods, and Events" chapter in the UPOS specification.
Each POS for .NET Basic class overrides or implements PosCommon properties and methods which are of particular importance to a Service Object developer. This topic provides information about these methods and properties.
CapPowerReporting Property
Once POS for .NET has successfully opened a device, it tries to retrieve the current value of the CapPowerReporting property. The PowerReporting class is initialized to None, indicating that the Service Object is not able to provide power reporting. If, however, the Service Object's device does support power reporting, the Service Object may set PowerReporting to Standard or Advanced in the Service Object's method.
CapStatisticsReporting Property
POS for .NET verifies that the device has been opened and then retrieves the current value of the CapStatisticsReporting property.
When statistics are created for the device, POS for .NET sets CapStatisticsReporting to true.
CapUpdateStatistics Property
POS for .NET verifies that the device has been opened and then retrieves the current value of the CapUpdateStatistics property.
When statistics are created for the device, and if those statistics can be reset or updated, then POS for .NET sets CapUpdateStatistics to true.
Claimed Property
POS for .NET verifies that the device has been opened, and then retrieves the current value of the Claimed property.
Claimed is initialized to false. Claimed should be set to true when the application calls the Claim method, then set back to false when the application calls the Release method.
DeviceDescription Property
POS for .NET verifies that the device has been opened, and then retrieves the current value of the DeviceDescription property.
DeviceEnabled Property
DeviceEnabled is a read/write property.
It can be used to return the object's current state; enabled or disabled. If this object has not been previously opened and enabled, this property returns false.
This property is also used to enable or disable the device by setting the property of the value to true or false. It is common for Service Objects to override this property and perform its hardware initialization and release here.
DeviceName Property
POS for .NET verifies that the device has been opened, and then retrieves the current value of the DeviceName property.
Within Base class implementations, this value is set automatically based on the contents of the ServiceObject attribute.
If you are not deriving from a POS for .NET Base class, and are instead deriving from an Interface-level or Basic-level class, then DeviceName should be set by the Service Subject during the Open method.
FreezeEvents Property
FreezeEvents is a read/write property.
POS for .NET verifies that the device has been opened and claimed, then retrieves or sets the current value of the FreezeEvents property. When this property is set to true, POS for .NET queues events until this property is set to false, not that the queuing mechanism can vary from one device type to another.
The FreezeEvents property is initialized to false.
PowerNotify Property
PowerNotify is a read/write property.
POS for .NET verifies that the device has been opened, then retrieves or sets the current value of PowerNotify. If PowerNotify is set, then power state notifications will be sent to the application.
PowerNotify is initialized to Disabled.
Attempting to set PowerNotify can cause the following exceptions to be thrown.
| Value | Meaning |
|---|---|
Illegal |
One of the following conditions has occurred:
|
PowerState Property
POS for .NET verifies that the device has been opened, and then retrieves the current value of the PowerState property. If CapPowerReporting is set to None, PowerNotify is set to Disabled, or DeviceEnabled set to false, PowerState is returned as Unknown.
PowerState is initialized to Unknown. When PowerNotify is set to Enabled and DeviceEnabled is true, PowerState should be updated as the Service Object detects power condition changes. POS for .NET detects the state change when the Service Object sets PowerState and—if PowerNotify is set to Enabled—queues a StatusUpdateEvent event, notifying the application.
Setting PowerState can cause the following exceptions to be thrown.
| Value | Meaning |
|---|---|
Illegal |
One of the following conditions has occurred:
|
ServiceObjectDescription Property
POS for .NET verifies that the device has been opened, and then retrieves the current value of the ServiceObjectDescription property. The Service Object developer should not have to set this value, since it is set by the POS for .NET Basic class using the description information provided in the ServiceObject attribute.
ServiceObjectVersion Property
POS for .NET verifies that the device has been opened, and then retrieves the current value of the ServiceObjectVersion property. The Service Object developer should not have to set this value, since it is set by the POS for .NET Basic class using the version information provided in the ServiceObject attribute.
State Property
No device state verification is required—the application can retrieve the current value of the State property.at any time.
State is initialized to Closed. If the Service Object sets State to an invalid ControlState value, POS for .NET throws an Illegal exception. Changes in State cause POS for .NET to queue a StateChangedEvent event.
Claim Method
POS for .NET verifies that the application has the device opened.
If the timeout parameter is set to a value less than -1, POS for .NET throws an exception. If the timeout value is set to -1, the Claim method will wait forever.
If the device is already claimed by the application, POS for .NET simply returns.
If the device is in use by another application, timeout is reached; POS for .NET throws a time-out exception.
If Claim is successful, POS for .NET loads the statistics for the device and sets the Claimed property to true.
Close Method
If the application calls the Close method when State is set to Closed, POS for .NET throws a Closed exception. If State is set to Busy, POS for .NET throws a Busy exception.
If the DeviceEnabled method when Claimed is set to false, POS for .NET throws an Illegal exception. If State is set to Busy, POS for .NET calls the ClearOutput method. If the device is enabled, POS for .NET sets DeviceEnabled to false. POS for .NET clears the event queue, and then sets Claimed to false.
ResetStatistic Method
POS for .NET verifies that the application has opened, claimed, and enabled the device, then calls the ResetStatistic method.
ResetStatistics() Method
POS for .NET verifies that the application has opened, claimed, and enabled the device, then calls the ResetStatistics method.
ResetStatistics(categories parameter) Method
POS for .NET verifies that the application has opened, claimed, and enabled the device, then calls the ResetStatistics method.
ResetStatistics(string parameter) Method
POS for .NET verifies that the application has opened, claimed, and enabled the device, then calls the ResetStatistics method.
RetrieveStatistic Method
POS for .NET verifies that the application has opened, claimed, and enabled the device, then calls the RetrieveStatistic method.
RetrieveStatistics() Method
POS for .NET verifies that the application has opened, claimed, and enabled the device, then calls the RetrieveStatistics method.
RetrieveStatistics(categories parameter) Method
POS for .NET verifies that the application has opened, claimed, and enabled the device, then calls the RetrieveStatistics method.
RetrieveStatistics(string parameter) Method
POS for .NET verifies that the application has opened, claimed, and enabled the device, then calls the RetrieveStatistics method.
UpdateStatistic Method
POS for .NET verifies that the application has opened, claimed, and enabled the device, then calls the UpdateStatistic method.
UpdateStatistics(categories parameter) Method
POS for .NET verifies that the application has opened, claimed, and enabled the device, then calls the UpdateStatistics method.
UpdateStatistics(statistic array parameter) Method
POS for .NET verifies that the application has opened, claimed, and enabled the device, then calls the UpdateStatistics method.