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

Load one or more drivers, then initialize and link them.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_ISIS_drv_load_init_pipe(
        LPSTR lpszRoot,
        LPSTR lpszName,
        LPHISISDRV lphDriver,
        AT_MODE nFlags
);

Arguments:

Name Type Description
lpszRoot LPSTR Reserved for future use. Currently lpszRoot must be (char FAR *) 0. Future implementations may allow an application to specify where to find a driver or other special information.
lpszName LPSTR Driver name string. Multiple drivers are specified as a single string with each driver name separated by a pipe symbol (?|?). Under Microsoft Windows, the extension .PXW is added to the specified name(s) automatically.
lphDriver LPHISISDRV A pointer to a buffer to accept the handle to the head (first) driver, which is returned when the driver loads. This handle references the pipe until the pipe is removed from memory with IG_ISIS_drv_unload_pipe
nFlags AT_MODE

A bit field containing one or more of the following values. Currently, the following bits of nFlags are defined:

  • IG_ISIS_DRV_LOAD_NEED_ PAGESIZE
  • IG_ISIS_DRV_LOAD_SUPRESS_ DIALOG
    • FALSE: If the driver was already in memory and was not loaded from \WINDOWS\PIXTRAN or from this application's executable directory, display a warning message to the user and load another instance only if the user wants to proceed.
    • TRUE: Do not display warning dialog upon loading another instance of a driver that was already loaded from the "wrong" place 2.

      Recommended values are shown in bold type.

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:

This function does not process image pixels.

Remarks:

IG_ISIS_drv_load_init_pipe loads one or more drivers into memory, initializes each driver, and then links them into an ISIS pipe according to the order in which they are specified. This function is functionally equivalent to using IG_ISIS_drv_load, IG_ISIS_drv_init, and IG_ISIS_drv_link multiple times to load, initialized, and link all drivers in a pipe.

IG_ISIS_drv_load_init_pipe automates the process of loading, initializing, and linking drivers to form an ISIS pipe. For applications that require simple linear ISIS pipes with no special processing or minidrivers, IG_ISIS_drv_load_init_pipe is the easiest way to set up a pipe. Keep in mind that you can only reference the entire pipe, because lphDriver is a handle to the head driver only. Also, if your application requires that a pipe's flow be split, or that a callback be used to create a minidriver, or that drivers that remain in memory be linked and unlinked on the fly, then you must use the separate three-step process of calling IG_ISIS_drv_load, IG_ISIS_drv_init, and IG_ISIS_drv_link (and IG_ISIS_drv_split).

Your application must check that the specified driver was indeed loaded by IG_ISIS_drv_load before performing any other operations. If, for example, IG_ISIS_drv_init (which should be the very next function call) tries to initialize a driver that is not loaded, unpredictable results will occur, possibly including system crashes.

Once run, all drivers in the pipe can be used by IG_ISIS_run_zone to process pages as specified by each driver. For example, an application could load, initialize, and link a scanner driver, a file compression driver, and a file writing driver to scan, compress and save a file in one operation. In this scenario, all three drivers are loaded, initialized, and linked with one function call.

IG_ISIS_drv_load_init_pipe works equally well on single drivers and portions of a pipe. You can, for example, load all of a pipe except the scanner driver, then load the scanner driver separately (so that it can be kept in memory).

The foundation of using ISIS is understanding ISIS pipes. An ISIS pipe is a linked set of drivers that is established prior to any scanning or image processing. Once all desired drivers are linked, IG_ISIS_run_zone is used to invoke the pipe, causing each driver to perform its intended operation in turn. This pipe structure requires that the desired functionality be implemented as drivers, and allows large image files to be processed without copying the image data from one full-page buffer to another. The result is much faster and more efficient than alternative image processing schemes.

See Also:

IG_ISIS_drv_init

IG_ISIS_drv_link

IG_ISIS_drv_load

IG_ISIS_drv_split

IG_ISIS_run_zone