CheckScanner Class
2/27/2008
Defines the programmatic interface for a UPOS Check Scanner device.
Namespace: Microsoft.PointOfService
Assembly: Microsoft.PointOfService (in microsoft.pointofservice.dll)
Syntax
'Declaration
Public MustInherit Class CheckScanner
Inherits PosCommon
public abstract class CheckScanner : PosCommon
public ref class CheckScanner abstract : public PosCommon
public abstract class CheckScanner extends PosCommon
public abstract class CheckScanner extends PosCommon
Remarks
The main purpose of a Check Scanner device is to capture the image of a personal or business check for electronic check conversion. However, other documents (vouchers, signature receipts, and more) may be scanned if they fall within the capture size parameters of the check scanner.
The CheckScanner interface has the following minimal set of capabilities:
Reads image data from a Check Scanner device.
Has programmatic control of check insertion, reading, and removal. For some Check Scanner devices, this will require no processing in the application because the device may automate many of these functions.
The CheckScanner interface has the following additional capabilities:
The Check Scanner device may store successive check images in its hardware memory.
Cropping of areas of interest within the check image may be supported by the Check Scanner device to help reduce the memory needed to transmit or store the check image data.
The RetrieveImage method’s data is deposited in the ImageData property in binary form.
The Check Scanner device can allow for retrieval of images that are stored in its hardware memory.
The Check Scanner device may support image tag data information to identify the check image.
The application reads the contents of the ImageData property when it wants to additionally process the check image.
The Check Scanner device may be physically attached to or incorporated into a check validation print device and a MICR device. If this is the case, as soon as a check is inserted through check scanner methods, the check can still be used by the printer and MICR control before check removal.
The basic programming model for the CheckScanner interface is as follows:
The Check Scanner device is opened, claimed, and enabled.
When the BeginInsertion method is called, the check scanner is ready to read the check within the specified time as indicated by the time-out value. If the check is not inserted before the time-out value expires, an exception is thrown.
If there is a time-out, the Check Scanner device remains in a state that enables a check to be inserted. The application may provide an operator prompt that requests that a check be inserted. Following this prompt, the application would then reissue the BeginInsertion method and wait for the check to be inserted.
As soon as a check is inserted, the BeginInsertion method returns and the application calls the EndInsertion method. This results in the Check Scanner device exiting the check insertion mode and causes the check image to be captured.
Following the EndInsertion method, the scan image data is stored in a working buffer memory area and the service object generates a StatusUpdateEvent event to indicate that a successful scan image process has occurred. No DataEvent event is queued because data has not been transferred to the ImageData property at this point.
The application must use the RetrieveImage method to retrieve the current scan image data. However, if the check image was not successfully captured by the device, the service object queues an ErrorEvent event to indicate the capture was not successful.
If the application has set the AutoDisable property to true, the device is automatically disabled when the image is successfully captured.
A queued DataEvent event can be delivered to the application when it has set the DataEventEnabled property to true and other event delivery requirements are met. Just before delivering this event, the service object copies data into specific properties, and disables additional data events by setting the DataEventEnabled property to false. This causes later input data to be queued by the service object while the application processes the current input and associated properties. When the application has finished the current input and is ready for more data, it enables events by setting DataEventEnabled to true.
If the CapAutoSize property is set to true, when the DataEvent event is delivered, the height and width of the captured image are automatically stored in the corresponding DocumentHeight and DocumentWidth properties. If the CapAutoSize property is false, the application must set the DocumentHeight and the DocumentWidth property values before the BeginInsertion method being invoked.
If the CapDefineCropArea property is set to true. Then the application can use the DefineCropArea method to define crop areas in the captured image.
If the application has to retrieve the image or a cropped part of the image, it calls the RetrieveImage method. The image data is sent from the device to the service object and stored in the ImageData property. When the corresponding DataEvent event is delivered, the current image (or cropped part of the current image) may be accessed by the application reading the image file that is contained in the ImageData property.
If the CapStoreImageFiles property is set to true, the current image or cropped image can be stored in the memory by using the StoreImage method.
Any stored image may be retrieved by using the RetrieveMemory method. The stored image may be identified by using the by parameter and requesting that the image be located by the value of the FileId, FileIndex, or ImageTagData properties.
ErrorEvent events are queued if the service object encounters errors while you read the check, and are delivered to the application when the DataEventEnabled property is set to true and other event delivery requirements are met.
All input data queued by the service object may be deleted by the application calling the ClearInput method.
After you process the EndInsertionDataEvent event, the application can query the CapMicrDevice property to determine whether the device supports Magnetic Ink Character Recognition (MICR). If the CapMicrDevice property is set to true, a MICR read function may be performed in a “single pass” or “multiple pass” cycle before the check being removed from the device. If the CapConcurrentMicr property is set to true, the device can support a “single pass” MICR read during an image scan. If CapConcurrentMicr and ConcurrentMicr are both set to true, the MICR data would be read and calling the MICR's BeginInsertion and EndInsertion methods would not be needed to reposition the check for MICR reading.
Additionally, after it processes a DataEvent event, the application should query the CapValidationDevice property to determine whether validation printing can be performed on the check before check removal. If this property is true, the application may call the POS Printer Interface’s BeginInsertion and EndInsertion methods. This positions the check for validation printing. The Printer's validation printing methods can then be used to perform validation printing.
If the CapImageTagData property is set to true, an identifying name—for example, the transaction number, date and time, or some other naming element—could be used to determine the image data. The identifying name is set in the ImageTagData property.
When the check is no longer needed in the device, the application must call the BeginRemoval method of the check scanner, the MICR (if CapMicrDevice is true), or the POS printer (if CapValidationDevice is true), also specifying a time-out value. This method will throw an exception if the check is not removed within the time-out period. In this case, the application can perform any additional prompting before calling the method again. As soon as the check is removed, the application should call the same device’s EndRemoval method to take the device out of removal mode.
To accommodate many different check scanning devices, the application should follow this sequence of method calls even though the device may not physically require one or more of the methods. An example may be a check scanner that is “auto armed” and can detect the presence of a check and automatically starting a check scan and MICR read cycle. In this case, the BeginInsertion, EndInsertion, BeginRemoval, and EndRemoval method calls may actually do no more than return from the service object.
The model assumes that the device has a work area that can be used in the following ways:
When a document is scanned, its image will be loaded as raw data into this work area. When the RetrieveImage method is invoked, the data from the work area may be modified by a previously defined crop area, as specified by the cropAreaID parameter, and loaded into the ImageData property. The work area will still contain the original scanned image data. Additional RetrieveImage method calls by by using different crop area criteria can then be employed to load the ImageData property.
The work area contains image data either from a recently scanned image or because of a RetrieveMemory method. Before invoking the StoreImage method, the FileIndex property is set to the correct index number (as maintained by the service object) and if you use it, the FileId and ImageTagData properties are set. When the StoreImage method is invoked, the data from the work area may be modified by a previously defined crop area, as specified by the cropAreaID parameter, and stored in the device memory. The work area will still contain the original scanned image data. Additional StoreImage method calls by using different crop area criteria can then be employed to store the image data in the device’s memory. The RemainingImagesEstimate property is adjusted to reflect the approximate number of additional images that may be stored in the device memory, based on the file size history of stored images.
When the RetrieveMemory method is invoked, the work area is loaded with an image data file that was stored in the device memory. The FileIndex, FileId, or ImageTagData properties may be used to locate the stored image. The ImageData property is also loaded with the retrieved image data.
To accommodate the various storage and retrieval architectures that are used for the Check Scanner device class, the model has been designed to allow for three different addressing ways to locate stored image data: FileIndex, FileId, and ImageTagData.
The FileIndex is an addressing scheme that is automatically provided by the service object to physically store and retrieve the file data. The definition of file data in this case includes any and all the following: image data, tag data information (the data that is appended and included with the image data file), and a file identification (a file name associated with the image data file). The FileIndex is only used by the service object to save and retrieve the scan data and its associated data elements.
The FileId is a “file name” that may be provided automatically by the hardware device or the service. It may also be populated by the application before calling a StoreImage method. As soon as it is created, it remains with the ImageData and can be used to locate a specific file for uploading to the POS system and post-processing applications.
The ImageTagData is a set of information about the image that has been scanned. Typically it contains information about when the image was captured (date and time, for example), store number, lane number, clerk identification, and more This data is typically appended to the ImageData and remains a part of the combined data file as a record of the origin of the data.
The check scanner is an exclusive-use device, and follows the following constraints:
The application must claim the device before you enable it.
The application must claim and enable the device before the device begins reading input, or before you call methods that manipulate the device.
Inheritance Hierarchy
System.Object
Microsoft.PointOfService.PosDevice
Microsoft.PointOfService.PosCommon
Microsoft.PointOfService.CheckScanner
Microsoft.PointOfService.BasicServiceObjects.CheckScannerBasic
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.