ImageGear for C and C++ on Windows v19.10 - Updated
IG_ISIS_run_zone
API Reference Guide > ISIS Component API Reference > ISIS Component Functions Reference > Pipe Functions > IG_ISIS_run_zone

Invoke an ISIS pipe and run a zone.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_ISIS_run_zone(
        HISISDRV hDriver,
        LPBYTE lpBuffer,
        WORD wSize
);

Arguments:

Name Type Description
hDriver HISISDRV The handle of the head (first) driver in the ISIS pipe. Usually this is either a scanner driver or a file-reading driver.
lpBuffer LPBYTE A pointer to a character array buffer used by IG_ISIS_run_zone. This array should be 8192 bytes in size, as a larger buffer area is not needed.
wSize WORD The size of lpBuffer. Must be at least 1 and at most 32K-1. We recommend always using a size of 8192. In testing various scanners, files, and ISIS pipes, this value produced maximum throughput without wasting memory.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Supported Raster Image Formats:

Depends on the scanner driver.

Remarks:

The IG_ISIS_run_zone function combines the functionality of several independent stack, page, and zone functions to make invoking a pipe a one-step process.

IG_ISIS_run_zone is the easiest way to invoke an ISIS pipe. It causes the head (first) driver to start generating data and sending chunks of data to the next driver in the pipe. Each chunk of data is the amount that will fit into lpBuffer. This, in turn, causes data for a single run (usually a page) to flow through the pipe and produce output. Each IG_ISIS_run_zone call processes exactly one zone (which may be at most a page, and at least a sub-area of a page).

A zone may be an entire page side, a sub-area of the page, or one of multiple sub-areas that can be defined with certain scanner drivers (by using IG_ISIS_TAG_WINDOW). In typical scanning cases, a zone is a single page. Your application can rely on a zone returning a page, as this is the default behavior for all scanners. Special programming is required to access any other type of behavior.

Call IG_ISIS_run_zone only after properly loading, linking, and setting parameters on an ISIS pipe.

Calling IG_ISIS_run_zone on a scanner driver causes the scanner to scan a page and output data into the ISIS pipe to which the scanner driver is linked.

After calling IG_ISIS_run_zone, check the return value. If the return value is not IGE_SUCCESS, then an error occurred (for example, a paper jam), and the page should be considered incomplete. If the return value is IGE_SUCCESS, then the page (zone) completed and no more data is available. Another IG_ISIS_run_zone must be called to process the another page (zone).

IG_ISIS_run_zone consists of, among other functions, the following three key functions:

Omitted from these functions is IG_ISIS_drv_run_zone, which is used to pass tags to the head driver just before starting data transfer. This function is needed when the head driver is not a data generator but tags still need to be set. Therefore, there are several cases in which you may want to use the separate functions to invoke an ISIS pipe:

Example:

The following example uses IG_ISIS_run_zone to implement a basic scanning loop. Compare this to the example of using the separate IG_ISIS_drv_run... functions.

 
Copy Code
#define BUFSIZE 8192
AT_ERRCOUNT ScanBatch(HISISDRV hDriver)
{
        LONG lValue;
        AT_ERRCOUNT nErrCount;
        char Buffer[BUFSIZE];
        nErrCount = IG_ISIS_drv_is_page_loaded(hDriver, IG_ISIS_FEEDER_FEED, &lValue);
        if (nErrCount != IGE_SUCCESS)
                return nErrCount;
        while (lValue & IG_ISIS_DRV_STACKPAGE) {
                nErrCount = IG_ISIS_run_zone(hDriver, Buffer, BUFSIZE);
                if (nErrCount != IGE_SUCCESS)
                        return nErrCount;
                nErrCount = IG_ISIS_drv_is_page_loaded(hDriver, IG_ISIS_FEEDER_FEED, &lValue);
                if (nErrCount != IGE_SUCCESS)
                        return nErrCount;
        }
return IGE_SUCCESS;
}

Background

An ISIS pipe exists to transfer image data from one entity (scanner, file, memory) to another. IG_ISIS_run_zone invokes several separate ISIS functions that can also be called independently by an application, if desired. Following is the actual code that is used to define IG_ISIS_run_zone:

 
Copy Code
if ((nErrCount = IG_ISIS_drv_start_stack(hDriver, &hStack)) == IGE_SUCCESS) {
        if ((nErrCount = IG_ISIS_drv_start_page(hStack, &hPage)) == IGE_SUCCESS) {
                if ((nErrCount = IG_ISIS_drv_start_zone(hPage, &hZone)) == IGE_SUCCESS) {
                    if ((nErrCount = IG_ISIS_drv_forward(hZone, 0)) == IGE_SUCCESS)
                                nErrCount = IG_ISIS_drv_start_data(hZone);
                        if (nErrCount == IGE_SUCCESS) {
                                do {
                                        nErrCount = IG_ISIS_drv_put_data(hZone, buffer, size, 0);
                                } while (nErrCount == IGE_SUCCESS);
                    }
                        nErrCount = IG_ISIS_drv_end_zone(hZone);
                }
                 nErrCount = IG_ISIS_drv_end_page(hPage);
}
nErrCount = IG_ISIS_drv_end_stack(hStack);
return nErrCount;