Callback functions can be used to get and set non-image data during normal load and save operations. It is also possible to use callback functions with the IG_fltr_metad_update_file() function to operate on only the non-image data in a file. This function creates a new file with an exact copy of the source file's pixel data and with new non-image data. Pixel data is not decoded, but is copied directly from the source to the destination file. This function is currently supported with the following file formats only:

IG_fltr_metad_update_file() obtains new non-image data from the following callback functions:

IG_fltr_metad_update_file() function can be used as follows:

Load necessary page to get metadata.
Change metadata (add / delete / change metadata tags or metadata values).
Call IG_fltr_metad_update_file() function. nPageNumber and lFormatType parameter values should correspond to the loaded page and source file format.

The destination file will be a copy of the source file with the new non-image data for the specified page.

The application may then delete the source file and rename the destination file with the name of the source file.

Usage of metadata update function is demonstrated in the Filter sample. Use the following steps to test this feature:

Open a TIF image using File/Open menu item.
Add or modify tag(s) using Image/Metadata/Data Structure dialog.
Create a file with updated metadata using File/Update metadata menu item. Source file name and page number correspond to the last loaded page in the filter sample.

All changes made in the Metadata dialog will be lost if any function that returns metadata is called before calling IG_fltr_metad_update_file() (i.e., loading a new file, getting file info, or preview).

The function also allows the conversion between JP2 file format and JPEG 2000 raw codestream. Use the FILE_FORMAT control parameter of the JPEG 2000 format filter to control the destination file format.

Working with XMP Metadata

Extensible Metadata Platform (XMP) is an XML-based standard for storage and interchange of metadata, developed by Adobe Systems Inc. The standard defines the rules for storage and processing of the metadata, and provides a number of schemas for storage of information that is typically associated with images and documents, such as Title, Author, Creation date/time, Rating, etc. Applications can add their own schemas to store arbitrary information.

XMP metadata can be attached to files of various formats, such as TIFF, JPEG, PSD and PDF, or stored as a standalone file.

ImageGear provides the following ways for working with XMP metadata:

Accessing XMP properties via the ImageGear Metadata API. In this mode, ImageGear decodes XMP properties and sends them to the application via metadata callbacks.
Working with unprocessed XMP metadata. In this mode, ImageGear passes XMP to the application as a byte array, treating it as a single tag of the containing metadata format.

By default, ImageGear parses the XMP stream into its metadata structure, and does not provide the Raw XMP stream. If you don't want ImageGear to parse the XMP stream, and prefer to instead access the unprocessed XMP stream, set global control parameter XMP.Parse to FALSE.

During saving, if XMP.Parse is TRUE, ImageGear expects a tree under the XMP tag, and serializes this tree into the output file. If XMP.Parse is FALSE, ImageGear expects a byte array in the XMP tag, and saves it verbatim to the file.

Since the XMP standard identifies schema properties using string names, rather than numbers, ImageGear also uses names to identify XMP properties. However, it uses numeric identifiers to differentiate between the kinds of entities, such as Description (schema), Array, Property, Qualifier, etc. All properties have ID = ImGearXMPTagIDs.Property, but differ by their names.

See XMP Non-Image Data Structure for a description of XMP metadata structure in ImageGear.

Example:

Representation of XMP metadata tree.

XMP
- http://ns.adobe.com/xap/1.0/
  - About = ""
  - Namespace
    - Prefix = "xmp"
    - URI = "http://ns.adobe.com/xap/1.0/"
  - Properties
    - xap:Rating
      - Value = 4
    - xap:Identifier
      - Value = "1234.0345.34532.234231"
- http://purl.org/dc/elements/1.1/
- Namespace
  - Prefix = "dc"
  - URI = http://purl.org/dc/elements/1.1/
- Properties
  - dc:subject
    - Bag
  - Item
    - Value = "Test subject 1"
  - Item
    - Value = "Test subject 2"
  - dc:title
    - Alt
  - Item
    - Lang = "x-default"
    - Value = "XMP Support Specification"