Event Driven Scanning

Event Driven Scanning (sometimes called Asynchronous scanning) is based on an event-driven programming model. Programs using Event Driven Scanning accomplish their tasks primarily by responding to COM events fired by ScanningManager.

A program initiates scanning by calling ScanningManager.Scan method, which returns immediately, as it is simply a request to start the scanning cycle. Scanning then begins and the program responds to events from ScanningManager. See ScanningManagerEvents Summary.

Parameters to those events provide access to data and image clips acquired by ScanTools Runtime, and information about any errors that occur. The scanning session might be terminated by ScanTools Runtime, for example when all forms are scanned and the user clicks the Stop button on the ScanTools error dialog, or by the solution program, via a call to ScanningManager.Stop.

These events are received during the scanning cycle, in the order of occurrence:

• SessionInit
• DocInit
• SheetInit
• SheetAcquired
• FormIdentified
• Resolved
• PreScore
• XPrint
• Clip
• SheetStacked
• SheetComplete or SheetCancelled
• DocStacked
• DocComplete or DocRejected
• SessionComplete

The following events are only received if the program is performing its own custom error handling:

• ScanError
• ScannerButtonPressed
• ServerMessageBox

The following events are only received when performing scanner setup:

• ScannerSearch
• ScannerSearchComplete
• ScannerFound

All events have as a parameter an instance of ScanEventArgs, which is valid only within the scope of the event handler. The properties and methods of ScanEventArgs include:

• Data objects and methods — Document, Sheet, IsFieldResolved
• Helper objects — ClipHelper, OmrHelper
• Error objects — Errors, ServerMessage, ScannerButtonPressed
• Methods to request actions from ScanTools Plus — CancelDocument, RejectDocument

The availablity of individual properties and methods of ScanEventArgs and its child objects depends on the event (see the ScanEventArgs Access Matrix); for example, RejectDocument() can only be called at the DocStacked event and will return an error at other times.

The complete ASCII record (including score and conversion fields) for a document is available in the Document.DataRecordInNCSFormat property.

You can use the Document.ConnectionString property to open an ADO connection to DataServices and get SQL access to document data. Other methods of Document and Sheet facilitate access via Data Services by returning the serial number, sheet number, the names of the resolved fields, and the names of the archive index fields.

The ClipHelper object contains many properties and methods that support the taking of image clips during scanning, possibly based on scan-time criteria.

To implement event driven scanning, your solution program code should do the following:

1. Create an instance of ScanningManager.. By default ScanningManager assumes that you do not want to customize error handling. However you can call ScanningManager.SetKernelErrorMode to request that scanning errors and/or general errors result in the firing of ScanError or ServerMessageBox events respectively, rather than the appearance of the ScanTools Plus dialogs.
2. Call ScanningManager.SetClientWindowHandle with the handle of a window over which ScanTools Plus dialogs are to be displayed. This ensures that all dialogs and messages displayed by ScanTools Plus are visible to the user. Pass in a value of –1 to request ScanTools Plus to create System Modal dialogs and message boxes.
3. Create an instance of SessionInfo. This object has numerous properties that you can modify to configure your scanning session. Some of these properties have default values so you can selectively modify properties that are relevant to your application. Some of the more commonly used properties are the Application, ApplicationDirectory, DataFile and DataDirectory. The ApplicationDirectory and DataDirectory properties are required. If you leave the DataFile property blank, ScanningManager will create a data file called XYZ.dat where XYZ is the application number specified for the session. If you want the scanning session to automatically end (scanning to stop) after a fixed number of documents have been scanned, set SessionInfo.StopAfter to the #documents. If you leave the SessionInfo.StopAfter property at its default value of 0, scanning will continue until you explicitly issue a stop.
4. Set up a handler for the SessionInit event which is the logical time to allocate data structures, open files and perform any one-time initialization.
5. If your application requires access to scanned data after each sheet is scanned, set up a handler for the SheetComplete event.
6. If your application requires access to scanned data after each document is scanned, set up handlers for the DocComplete and DocRejected events.
7. Set up a handler for the SessionComplete event to be notified when a scanning session is complete and the data file is available. This is a good point to deallocate resources and close files. A scanning session may be stopped in these ways:
   • When a user selects the Stop button on the Scanner Error Dialog.
   • If SessionInfo.StopAfter is set to a non zero value and the specified number of documents have been scanned.
   • When ScanningManager.Stop is called.
8. Set up other event handlers depending on the scan-time information and control you require. For example, handle the Clip event to take image clips based on data from the current document and sheet. To ensure that any data and clips you have acquired by the time of the DocComplete event is for the current document only, clear your data structures at the FormIdentified event when Sheet.Number = 1. To modify the print string, handle the XPrint event. At DocStacked, all the document’s data is available; if desired, ScanEventArgs.RejectDocument can be called at this event and ScanTools Plus will not write the document’s record to the data file.
9. Make a call to ScanningManager.Scan passing your SessionInfo object as a parameter. The Scan method returns immediately, after which scanning actually begins and your event handlers will be called as events occur.

See also

ScanningManagerEvents Summary

How to Manage the Connection to ScanTools Plus Link Runtime

How to Diagnose a Scanner

How to Handle General Errors

How to Handle Scanner Errors

Updating the Output Record with Data Services

Set Up the Scanner

Also see the sample programs installed with the SDK; they provide specific ways of implementing event-driven scanning. Installed Samples Overview