POS Exception Handling (POS for .NET v1.14 SDK Documentation)
Error handling in Microsoft Point of Service for .NET (POS for .NET) is built on the object-oriented model of throwing and catching exceptions. Different exceptions are thrown in response to run-time errors, and each exception contains information about the error that triggered it in the form of an ErrorCode.
The ErrorCode property of a thrown exception holds information about the cause of the error. Possible values for this property represent the full set of standard Unified Point Of Service (UnifiedPOS) error codes. For more information about the mapping between UnifiedPOS error codes and the POS for .NET ErrorCode values, see POS for .NET Exception Classes.
POS for .NET provides four exception classes to help applications better handle errors. These are PosException, PosControlException, PosManagementException, and PosLibraryException:
- PosException is an abstract class that holds general exception data. PosException fulfills a role similar to that of the System.Exception class in the .NET Framework, and is the POS for .NET implementation of the UposException class in the UnifiedPOS specification. All other POS for .NET exception classes are derived from PosException.
- PosControlException is the standard exception thrown by POS for .NET Service Objects. PosControlException contains a ErrorCode property which holds information about the cause of the exception.
- PosLibraryException holds the exception data generated by PosExplorer during class operations. PosLibraryException does not contain an ErrorCode property.
- PosManagementException holds the exception data generated by POS for .NET management APIs. PosManagementException does not contain an ErrorCode property.
Error Handling in POS for .NET
Error handling in POS for .NET is compliant with UnifiedPOS specification guidelines. Error handling is event-driven, uses error codes to store exception information, and is largely implementation-specific.
Handling errors in POS for .NET follows this general procedure:
An error is thrown by event-driven input.
The device changes its State property to indicate that it has encountered an error.
An ErrorEvent event is queued to alert the application that an error has occurred. The ErrorEvent is added to the end of the queue.
If one or more DataEvent events are queued in front of the ErrorEvent event, another ErrorEvent is queued and added at the head of queue. This warns the application about the error quickly so it can respond in an implementation-specific manner prior to processing any queued DataEvents.
If the applications properties are configured to accept events (DataEventEnabled is true and FreezeEvents is false), it responds to the ErrorEvent event in a manner determined by the ErrorResponse property, as indicated in the following table.
Value Meaning of Response Clear Clears any buffered DataEvent events and ErrorEvent events, exits the Error state, and changes the device State to Idle. ContinueInput Acknowledges the error and directs the device to continue processing. The device remains in the Error state and will deliver additional data events as directed by the DataEventEnabled property. When all input has been delivered, and the DataEventEnabled property is again set to true, another ErrorEvent is delivered with the locus Input. Retry Directs the device to retry the input. The Error state is exited, and State is changed to Idle. This response is only selected when the device chapter specifically allows it and when the locus is Input. The application may also take implementation-specific steps to respond to the error at this time.
