ImageGear uses a component structure that consists of the Core (main) ImageGear component and a number of additional components. A component is a module that can be connected to the main ImageGear module using a platform-independent API. To initialize the component functionality, attach the component to the main ImageGear module using the ImageGear component manager API. When the component is attached, it gets access to all core ImageGear functions, and the core ImageGear functionality can use the component's structures, functions, and control parameters.

Usually, ImageGear components contain functionality such as additional format filters (for example, LZW or PDF) or additional image processing functionality, like ART.

Once you have attached the component, it cannot be detached prior to unloading of the ImageGear Core module. All components are detached and unloaded automatically at the time of the ImageGear Core module unloading.

ImageGear identifies every component by its name, and during the attachment process, it calculates the physical name of the file where the component is located. By default ImageGear assumes that all components are located in the same directory where the main ImageGear module is located, however you can specify a different folder from which to load the components.

ImageGear provides the component manager API for attaching, checking, retrieving information about a component, and function requesting.

Attaching a Component

To attach (load) the component to the core ImageGear you can use the function IG_comm_comp_attach. This function attaches the component, determined by lpCompName (e.g., "PDF"), to the core ImageGear module. If a component with the specified name is already attached, this function does nothing.

Below is the list of ImageGear components and the short names that you should provide for IG_comm_comp_attach() through the lpCompName argument:

There are some components that require more information:

Core Component

ImageGear does not require that any components be attached to use core functionality.

PDF Component

ImageGear PDF support requires that the PDF component be both loaded and initialized before using any PDF functionality. Some functionality related to PDF support may require other components to be loaded. PDF annotation support will require the ArtX, VECT, and U3D components to be loaded.

    // Attach the ArtX component for annotation support.
    if (IG_comm_comp_attach("ArtX") != IGE_SUCCESS)
    {
        // This error usually occurs because a DLL or the Resource directory cannot be found.
        cout << "ArtX component error." << endl;
        return false;
    }

    // Attach CAD components for PDF annotation support.
    if (IG_comm_comp_attach("U3D") != IGE_SUCCESS ||
            IG_comm_comp_attach("VECT") != IGE_SUCCESS)
    {
        // This error usually occurs because a DLL or the Resource directory cannot be found.
        cout << "CAD or vector component error." << endl;
        return false;
    }

    // Attach and initialize the PDF component.
    if (IG_comm_comp_attach("PDF") != IGE_SUCCESS || 
            IG_PDF_initialize(NULL) != IGE_SUCCESS)
    {
        // This error usually occurs because a DLL or the Resource directory cannot be found.
        cout << "PDF component error." << endl;
        return false;
    }   

Note that the PDF component needs to be terminated after it is no longer needed.

    // Terminate the PDF component.
    IG_PDF_terminate(); 

See the PDF section for detailed information about using the PDF component features.

Checking a Component

To check if a component is already attached, use the function IG_comm_comp_check. If the component is attached, this function returns TRUE; it returns FALSE otherwise.

Retrieving Information About Attached Components

The IG_comm_comp_list function retrieves information about all attached components. It returns the number of attached components, and the complete information about the component specified by nIndex.

Calling Component API Functions

Some components only provide support for additional file formats, and don't expose any API functions, and some components provide additional API. If your application uses a component that provides additional API functions, there are a few additional steps needed to use these API functions.

There are two ways that the application can call a function implemented by the component:

Using a Component Manager Function

The first method is calling a component's API functions via a component manager function, IG_comm_function_call.

IG_comm_function_call(LPCHAR lpEntryName, ... );

Where lpEntryName is a name of the requested function in the form "<COMP_NAME>.<FUNC_NAME>", where <COMP_NAME> is a name of the component that provides the function, and <FUNC_NAME> is the name of the function.

To simplify the calling of component functions, all components provide special macros for each of their public functions. This macro is located in the header file i_<COMP_NAME>.h for each component. For instance, i_PDF.h for PDF component:

#define IG_PDF_initialize( _lpInitData ) \
            AM_COMM_FUNCTION_WRAPPER((AT_ERRCOUNT (CACCUAPI *)( LPCHAR , \
            LPVOID)) \
            ,IG_comm_function_call)("PDF.IG_PDF_initialize", \
            (LPVOID)(_lpInitData))

With the use of this macro, a call to a component function looks exactly like a call to a regular C function:

#include "i_PDF.h"
...
IG_PDF_initialize( lpInitData );

Using a Pointer

Another method is to obtain a pointer to the component function and then call this function via its pointer. Use the IG_comm_entry_request function to obtain a component function pointer.

IG_comm_entry_request(
        LPCHAR lpEntryName,
        LPAFT_ANY *lpFuncPtr,
        LPCHAR lpReason
);

• The first parameter is the name of the function in the format described above.
• The second parameter is a pointer a variable of type LPAFT_ANY, which will be overwritten with the pointer to the necessary function.
• The third parameter is a text description reason to get access for this function (it is optional and can be NULL).

The component public header contains a type declaration for all its public functions. The correct way to call such a function would be to declare the variable of the necessary function type defined in the component’s public header; use IG_comm_entry_request() to initialize this variable with the correct value and then call it.

Calling component API functions by their pointers provides better performance, because it avoids the overhead of finding a function pointer by its name. If your application does not call component functions repeatedly in time-critical routines, you can use the simple method of calling component functions via their macros.