Using the Multi-page Image Callback Function

Multi-page image operations, implemented by the above functions, support a notification mechanism that allows you to track information about when and how the multi-page image or associated file was changed. This can be done using the functions IG_mpi_CB_set(), IG_mpi_CB_get(), IG_mpi_CB_reset(), and IG_mpi_CB_reset_all().

Use the function IG_mpi_CB_set(hMIGear, lpPrivate, lpfnUpdate, lpdwCBID) to associate new callback data with the given hMIGear handle. The second argument, lpPrivate, is any LPVOID pointer that the callback function lpfnUpdate receives through the second parameter. lpfnUpdate is a pointer to the function that implements the following interface:

	Copy Code
typedef VOID (LPACCUAPI LPFNIG_MPCB_UPDATE)( DWORD dwCBID, LPVOID lpPrivate, AT_MODE nMode, UINT nPage, UINT nCount );

The last argument of IG_mpi_CB_set(), lpdwCBID, is a pointer to the application that receives an unique DWORD identifier for the associated callback data. This ID is used to delete callback data using the function IG_mpi_CB_reset() and retrieves callback data using the function IG_mpi_CB_get(). After the IG_mpi_CB_set() function is executed, ImageGear calls the lpfnUpdate function every time a multi-page image is changed. This allows the application to react accordingly, and updates the related objects such as GUI windows. As soon as this callback function is called from the context of the thread that performed the operation, its execution is blocked until the callback function is complete. From one side, this can be used for synchronization; but from another side, it should be used carefully so that it does not affect performance.

By calling the callback function, ImageGear passes the type of changes through the nMode argument. The sense of nPage and nCount arguments depend upon nMode. The following table list all possible cases:

nMode	nPage	nCount	Description
IG_MPCBMODE_MPI_DELETE	Not used	Not used	Notifies the application that a multi-page image is going to be deleted.
IG_MPCBMODE_MPI_ASSOCIATED	Not used	Not used	Notifies the application that a multi-page image is just associated with external file.
IG_MPCBMODE_MPI_CLOSE	No used	Not used	Notifies the application that a multi-page image is going to close the associated external file.
IG_MPCBMODE_MPI_CB_SET	Not used	Not used	Notifies the application that this callback data is just set. This notification receives only the callback function that just has been set.
IG_MPCBMODE_MPI_CB_RESET	Not used	Not used	Notifies the application that this callback data is to be reset.
IG_MPCBMODE_MPI_PAGEINSERTED	Index of where new pages start	Number of new pages inserted	Notifies the application that new pages are inserted into the multi-page image.
IG_MPCBMODE_MPI_PAGEUPDATED	Index of the first updated page	Number of updated pages starting from nPage	The application updated pages in the multi-page image.
IG_MPCBMODE_MPI_PAGEDELETED	First deleted page index	Number of deleted pages	The application deleted pages in the multi-page image.
IG_MPCBMODE_MPF_PAGEINSERTED	Index of where new pages start	Number of new pages inserted	The application inserted new pages into the external file image.
IG_MPCBMODE_MPF_PAGEUPDATED	Index of the first updated page	Number of updated pages starting from nPage	The application updated pages in the associated external multi-page image file.
IG_MPCBMODE_MPF_PAGEDELETED	Index of the first deleted page	Number of deleted pages	The application deleted pages in the associated external multi-page image file.

When the application does not need to receive any more information from the callback data, it should call the function IG_mpi_CB_reset(hMIGear, dwCBID), where dwCBID is a unique identifier of the association returned by IG_mpi_CB_set().

The function IG_mpi_CB_reset_all() removes all callback data associated with all previously allocated identifiers.

See Also: