ImageGear for C and C++ on Windows v19.2 - Updated
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.