Load a driver into memory.

Declaration:

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_load(
        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 or pointer to a callback function. If the IG_ISIS_DRV_LOAD_DIRECT bit of nFlags is FALSE, then lpszName is the filename of a driver. Search location rules are given under "Usage" below. Often, scanner driver filenames are identified by using the IG_ISIS_drv_get_scan_name function. Under Microsoft Windows, the extension .PXW is added to the specified name automatically. If the IG_ISIS_DRV_LOAD_DIRECT bit of nFlags is TRUE, then (INT32?(FAR?pascal?*)??lpszName points to the proc instance of a driver function. This form is useful if you are an advanced programmer and you want to include some driver functionality in your program (called a "minidriver"), but you do not want to create a complete driver. This is most often used to create a "callback" function for your scanning chain. Under Microsoft Windows, the function passed in must be included as an export in the DEF file.
lphDriver	LPHISISDRV	A pointer to a buffer to accept the handle to the driver returned when the driver loads. This handle references the driver until the driver is removed from memory with IG_ISIS_drv_unload.
nFlags	AT_MODE	A bit field containing one or more of the following values. Currently, four bits of nFlags are defined: IG_ISIS_DRV_LOAD_DIRECT FALSE: lpcName is the filename of the driver to load. TRUE: lpcName points to the proc instance of a driver function supplied by the application developer. IG_ISIS_DRV_LOAD_NEED_ PAGESIZE FALSE: Get IG_ISIS_TAG_PAGESIZE directly from the scanner driver. TRUE: Cause IG_ISIS_TAG_PAGESIZE to be available even if the scanner driver did not implement it. IG_ISIS_DRV_LOAD_NO_FILTERS FALSE: Load filters as specified in SETSCAN.INI. TRUE: Override other settings and do not load filters. 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 loads a driver into memory so that it may be initialized and linked into an ISIS pipe.

You must load each driver that you intend to use, initialize it, then link it with other (previously-loaded and initialized) drivers to form an ISIS pipe. To do this, you use a combination of IG_ISIS_drv_load, IG_ISIS_drv_init, and IG_ISIS_drv_link or IG_ISIS_drv_split. For applications that require simple linear ISIS pipes with no special processing or minidrivers, it is much less work to use the IG_ISIS_drv_load_init_pipe function which can load, initialize, and link all specified drivers in one operation.

Once loaded, initialized, and linked, the driver (and all other linked drivers in the pipe) are used by IG_ISIS_run_zone to process pages as specified by each driver. For example, an application could load 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, three separate drivers need to be loaded, initialized, and linked.

There are several good reasons to use the three separate functions for loading, initializing, and linking drivers as opposed to the single IG_ISIS_drv_load_init_pipe:

• Using IG_ISIS_drv_split to split a pipe into two driver inputs requires the three step method.
• Using the IG_ISIS_DRV_LOAD_DIRECT field of nFlags to point to a driver function (that is, to create a minidriver) requires the use of the three step method.
• In applications where drivers are changed frequently, the three-step method is preferred. Loading drivers from disk into memory is expensive in terms of time. However, there is functionally no performance hit for linking and unlinking drivers. Some application developers may want to load all of the drivers needed during an application instance, and then just link and unlink them as needed. This design requires using the three-step method.

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.

Driver Loading Algorithm:

The toolkit uses a special driver loading algorithm to ensure that your application loads the correct version of a driver, even when multiple versions of a driver exist. Keep in mind that some version of the driver you are trying to load may already be loaded in memory, due to some other application or another instance of your application. Once a driver is loaded, loading it again simply references the same driver with a new instance handle. It is not possible to load different copies of a file of the same name.

Each time your application loads a driver that is not already in memory, the toolkit goes through this special driver loading algorithm to:

1. Ensure that if a driver is already in memory, it is compatible with the version of PIXDFLT you are using.
2. Ensure that if PIXDFLT is already in memory, it is compatible with the drivers you are trying to load.
3. Ensure that the version of the driver you are loading is the latest one available.
4. Provide backward compatibility for older ISIS applications that do not load their drivers from the "correct" place. (The correct place is now \WINDOWS\SYSTEM for all toolkit libraries and \WINDOWS\PIXTRAN for all ISIS drivers.) Many older ISIS applications load their drivers from the application directory, but future support for this capability may be dropped at any time.

   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.

See Also:

IG_ISIS_drv_init

IG_ISIS_drv_link

IG_ISIS_drv_load_init_pipe

IG_ISIS_drv_split

IG_ISIS_run_zone

©2014. Accusoft Corporation. All Rights Reserved.