IG_mpi_file_open

This function associates a multi-page image with an external image file.

Declaration:

	Copy Code
AT_ERRCOUNT ACCUAPI IG_mpi_file_open_W( const LPAT_WCHAR lpwszFileName, HMIGEAR hMIGear, AT_MODE nFormat, AT_MODE nOpenMode );

Arguments:

Name	Type	Description
lpwszFileName	const LPAT_WCHAR	Path and name of the file to be associated with a given multi-page image, specified as a wide string (UTF-16).
hMIGear	HMIGEAR	A HIGEAR handle to the allocated multi-page image.
nFormat	AT_MODE	The format of the file, such as IG_FORMAT_UNKNOWN or IG_FORMAT_TIF. See enumIGFormats for a list of all available IG_FORMAT_... constants.
nOpenMode	AT_MODE	An AT_MODE constant (see enumIG_MP_OPENMODE), such as IG_MP_OPENMODE_READONLY or IG_MP_OPENMODE_READWRITE.

Return Value:

Returns 0 if successful. Otherwise, returns the number of ImageGear errors that occurred during this function call.

Supported Raster Image Formats:

All pixel formats supported by ImageGear Professional.

Remarks:

This function allows you to associate a multi-page image with an external image file. After the association is made, you can then use different page manipulation functions, such as page load, save, delete, and swap. With this association operation, ImageGear allows you to store internal data, allowing you to make page operations faster than if using IG_fltr_... functions. This file can be opened with two modes:

IG_MP_OPENMODE_READONLY

This mode is used when only page loading is necessary. It does not allow you to change the external file. When the image is opened with read only access, it sets the number of pages in the multi-page image equal to the number of pages in the external file using IG_mpi_page_count_set() function.
IG_MP_OPENMODE_READWRITE

This mode opens the file for read-write access and allows all possible page operations with the external file. The multi-page image is not changed.

Not all filters support all page manipulation operations. Use the function IG_fltr_info_get, which returns the information about all supported features of a particular filter.

IG_MP_OPENMODE_NONE is also accepted as a value for nOpenMode and, in this case, this call is equivalent to the IG_mpi_close call.

The nFormat parameter is used only if a new image file is to be created and nOpenMode= IG_MP_OPENMODE_READWRITE. In this case, the file of the specified format is created. In all other cases this parameter is ignored.

This function may work slower on PDF and PostScript images that contain Unicode symbols in file names (symbols that are not present in the system's active code page), compared to images whose file names don't contain such symbols.