TwainGetImage

Retrieves a Bitmap handle to the next image from the currently open Data Source. This is called from your GUI window's message loop when it detects the twain device is signaling that your script should retrieve another image. The twain device signals this by setting GuiObject to TWAIN and GuiSignal to XFER.

Synopsis

error = TwainGetImage(Subroutine)

Args

Subroutine is the name of some subroutine in your script that TwainGetImage will call, and pass a handle to the next image's bitmap. Your subroutine will return a 1 to free the bitmap, a 0 not to free the bitmap (and you are responsible for freeing it yourself), or an empty string to cancel the acquire operation (ie, cause the twain device to send no more signals for further images).

Returns

An empty string if the image is successfully retrieved, or an error code if not.

Notes

TwainGetImage can be called only after once calling TwainAcquire to start the acquire process, and only when the twain device signals that an image is ready to be retrieved. TwainQuery can be called to check whether an acquire process is happening.

If your subroutine returns an empty string to cancel the acquire process, this causes TwainGetImage to return an error. Alternately, you can abort the acquire operation by calling TwainCancel instead of TwainGetImage.

If you wish to skip downloading a particular image, but continue on downloading further images, then instead of calling TwainGetImage to retrieve that particular image, call TwainAck to skip that image.

Before calling TwainGetImage, you may wish to first call TwainGetImageInfo to fill in some stem variable with information about the image that you will be retrieving. In this way, you can better decide whether to actually retrieve the image by calling TwainGetImage, or skip it by calling TwainAck, or cancel by calling TwainCancel.