ImageGear for C and C++ on Linux v19.10 - Updated
Attaching Components
User Guide > How to Work with... > Attaching Components

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:

Component Name Component Abbreviation
ImageGear Core Component "CORE"
ImageGear ART Component "ART"
ImageGear JBIG2 Component "JBIG2"
ImageGear JPEG 2000 Component "JPEG2K"
ImageGear LZW Component "LZW"
ImageGear Medical Component "MED"
ImageGear PDF Component "PDF"

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.

C and C++
Copy Code
    // 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.

C and C++
Copy Code
    // Terminate the PDF component.
    IG_PDF_terminate(); 

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

C and C++
Copy Code
C and C++
Copy Code

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.

C and C++
Copy Code
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.

C and C++
Copy Code
#define IG_IC_clean_borders_ex( hIGear, nLeftBorderSize, nRightBorderSize,
nTopBorderSize, nBottomBorderSize, nMinLinesNum, nMinLineWidth)
    ((AT_ERRCOUNT (CACCUAPI *)(LPCHAR, HIGEAR, UINT, UINT, UINT, UINT, UINT, UINT))
IG_comm_function_call)("CLN.IG_IC_clean_borders_ex",  hIGear, nLeftBorderSize,
nRightBorderSize,  nTopBorderSize,  nBottomBorderSize,  nMinLinesNum,
nMinLineWidth)

C and C++
Copy Code
#include "i_CLN.h"
…
IG_IC_clean_borders_ex( hIGear, nLeftBorderSize, nRightBorderSize,
 nTopBorderSize, nBottomBorderSize, nMinLinesNum, nMinLineWidth);

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:

C and C++
Copy Code
#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:

C and C++
Copy Code
#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.

C and C++
Copy Code
IG_comm_entry_request(
        LPCHAR lpEntryName,
        LPAFT_ANY *lpFuncPtr,
        LPCHAR lpReason
);

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.