ImageGear for C and C++ on Linux v18.10 - Updated
Use the Multi-Page Image Callback Function
User Guide > How to Work with... > Common Operations > Manipulating Image Data > Work with Multi-Page Documents (HMIGEAR) > Use 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:

Manipulating Image Data

Using Callback Functions