After a multi-page image is created, it can be associated with an external image. This allows you to set a relationship between a page array of a given multi-page image and pages of a multi-page file. After making that association, but before closing the file, ImageGear stores format-related information in memory. This does not apply to pages, however; this data should be loaded by IG_mpf_page_load after association. This allows you to perform page manipulation operations, such as page loads, saves, swaps, or deletes quickly, without scanning all of the format structure of the associated file image. This may be useful if the number of pages in the file is large. It also improves the performance of these operations.

Use the function IG_mpi_file_open() to open or create an external multi-page file and associate it with the multi-page image given by the HMIGEAR object. Use the fourth parameter of this function to specify two open modes. If IG_MP_OPENMODE_READONLY is specified, then the file opened has read-only access. Only these operations are allowed. They need not change the file (for example, page loading).

If IG_MP_OPENMODE_READWRITE is used, then the file is opened with read-write access, and all supported operations are allowed. Not all format filters support such operations, such as page insert, delete, and swap. The function IG_fltr_info_get() can be used to get information about all implemented features of some particular format.

The third parameter of this function provides the format identifier (one from defined IG_FORMAT_... constants in accucnst.h) and is used only when the file image opens in IG_MP_OPENMODE_READWRITE mode. The file does not exist, and it is ignored in other cases. This parameter is used to specify the format of the image to be created.

Example:

#include "accucnst.h"
 ...
HMIGEAR hMIGear;        /* HMIGEAR handle returned   */
AT_ERRCOUNT nErrCount;     /* number of errors reported */
 ...
nErrCount = IG_mpi_create(&hMIGear, 0);
if (!nErrCount)
{
nErrCount = IG_mpi_file_open("picture.tif", hMIGear, IG_FORMAT_UNKNOWN, 
IG_MP_OPENMODE_READONLY);
                 ...
        nErrCount = IG_mpi_close( hMIGear );
}else
                /* error handling */
 ...

If this function is opened for read-only access, then the page array of multi-page images is set to the number of pages that is equal to the number of pages in the external file. If the file is opened for read-write access, then the multi-page image is not changed.

Use the function IG_mpi_close() to disassociate a multi-page image from an external file, close the file, and free all correspondent resources.