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:

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:

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