Load a driver into memory.
Declaration:
 Copy Code |
|
|---|---|
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.
|
||
| 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:
|
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:
- Ensure that if a driver is already in memory, it is compatible with the version of PIXDFLT you are using.
- Ensure that if PIXDFLT is already in memory, it is compatible with the drivers you are trying to load.
- Ensure that the version of the driver you are loading is the latest one available.
- 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.