There are two working scenarios of how ImageGear processes non-image data.
The first one is the LOAD operation:
- Application registers special callback function of type LPAFT_IG_METAD_ITEM_GET_CB.
- The application calls some of the filter loading functions (like IG_fltr_load_file()), and during the LOAD operation, the format filter calls the registered callback function to pass data for each item decoded from the image.
The reverse WRITE operation is more complex:
- Application registers callback functions of types LPAFT_IG_METAD_ITEM_SET_CB and LPAFT_IG_METAD_ITEM_ADD_CB.
- Application calls some filter writing functions (like IG_fltr_save_file()).
- While performing WRITE operation ImageGear uses callback functions to modify existing items or add additional items to required dataset.
ImageGear provides special LPAFT_ callback functions for the non-image data processing described in this section. It also preserves the "old" callback functionality (LPFNIG_ callback functions) required for image processing control and perfection. Please see Working with ImageGear Callback Functions for detailed information about the structure of the ImageGear callback functionality.
You can see from the declaration below that LPAFT_IG_METAD_ITEM_GET_CB accepts parameters that provide all necessary information about one data item. All parameters except the first one are fields of the data structure AT_DATALIST_ITEM described in Non-Image data format:
 Copy Code |
|
|---|---|
LPAFT_IG_METAD_ITEM_GET_CB(LPVOID lpPrivate, LPCHAR ItemName, DWORD ItemID, AT_MODE ItemType, LPVOID ItemValue, AT_MODE ValueType, DWORD ValueLength, AT_BOOL ReadOnlyValue ) |
|
By implementing and providing a callback function of this type, the application can receive every decoded item and process it as needed.
Some items from the dataset are informational only and cannot be changed during the WRITE operation. So, if the ReadOnlyValue field is set to TRUE, then the item will not be changed during the WRITE operation. Actually, during this operation, the format filter prepares all necessary items and puts required values to them to make sure that the file format itself is not violated. For example, if an item requires a particular number of strips in the image, then if the value of this item is changed, the image cannot be loaded.
The format filter prepares a minimal set of items and default values for them, and before writing its values to the output stream it calls the callback function of type LPAFT_IG_METAD_ITEM_SET_CB so that the application can change its values. In addition, the format filter may call the function of type LPAFT_IG_METAD_ITEM_ADD_CB to get additional items to append the dataset. The application should provide its implementation in such a way that it returns TRUE until it is necessary to insert more items. If this function returns FALSE, all custom items have been added, and the filter can proceed.
|
It may happen that the application provides an item with the name or ID of a different type than the format filter is expecting. For example, the format filter may expect the item named SOFTWARE with text as a String, but the application provides its value as an Integer. In this case the filter may ignore this item and trigger a warning that this type of item is not expected. Also, the application may provide an item that the format filter is not able to handle because it does not fit the format defined by the corresponding image file format. In this case it may simply ignore the item and give a warning. |
The exact specification of the callback function types can be found in Core Component API Function Reference, but the following is a quick reference for better understanding:
| Copy Code |
|
|---|---|
LPAFT_IG_METAD_ITEM_SET_CB)(LPVOID lpPrivate, LPCHAR ItemName, DWORD ItemID, AT_MODE ItemType, LPVOID ItemValue, AT_MODE ValueType, DWORD ValueLength, AT_BOOL ReadOnlyValue, LPVOID *NewItemValue, LPAT_MODE *NewValueType, LPDWORD *NewValueLength ) |
|
*NewItemValue, *NewValueType, *NewValueLength are arguments with a new value for a given item. If ReadOnlyValue is TRUE, the value of this item is unchangeable.
You can add a new non-image item during the filter WRITE operation using the callback function prototype:
| Copy Code |
|
|---|---|
LPAFT_IG_METAD_ITEM_ADD_CB(LPVOID lpPrivate, LPCHAR ItemName, DWORD ItemID, AT_MODE ItemType, LPVOID ItemValue, AT_MODE ValueType, DWORD ValueLength, AT_BOOL ReadOnlyValue ) |
|
All arguments in this function are parameters for the new item and its value.
To exchange the non-image tag information provided by these three callback functions between the application and the internal ImageGear structure levels, you should use two functions:
| Copy Code |
|
|---|---|
IG_fltr_metad_callback_get(LPVOID *lpPrivate, LPAFT_IG_METAD_ITEM_SET_CB *lplpfnSetCB, LPAFT_IG_METAD_ITEM_ADD_CB *lplpfnAddCB, LPAFT_IG_METAD_ITEM_GET_CB *lplpfnGetCB ) IG_fltr_metad_callback_set(LPVOID *lpPrivate, LPAFT_IG_METAD_ITEM_SET_CB *lplpfnSetCB, LPAFT_IG_METAD_ITEM_ADD_CB *lplpfnAddCB, LPAFT_IG_METAD_ITEM_GET_CB *lplpfnGetCB ) |
|
The first function allows you to provide the current callback non-image tag data from the internal ImageGear structure to an application level during load/save processes. If some callback information is not necessary, you can set the respective argument of this function to NULL. For instance, if you do not need information about newly added non-image items, set lplpfnAddCB = NULL.
The second _set() function provides the new non-image callback data from the application level to the internal ImageGear level during the load/save processes. Again, if some callback information is not necessary, you can set the respective argument of this function to NULL.
An example of how to use these callback functions is too complex to include in this manual. The GUI implementation that is provided in the source form demonstrates all aspects of working with these callback functions.