SDK - Callback Suites - pi_MetaMarkup
 

This callback suite provides the plug-in with a suite of functions for manipulating mark-up metadata. It is recommended that plug-ins use this suite instead of writing mark-up data directly; the reason for this is that it transfers the burden of standards conformance to the host and thus makes your plug-in more future-proof.

This interface is used for working with MARK metadata via an instance of an object of type pimm_MARK. The interface itself is encapsulated in an object of type pi_METAMARKUP. Both objects are defined in plugin.h.

create() creates a new blank mark-up data buffer.

import() creates a new blank mark-up data buffer and initializes it with the contents of the raw data provided.

destroy() destroys the mark-up data buffer and frees all memory used by it. Must be called for all buffers after use.

append() adds the mark-up fragment to the mark-up data buffer. It’s useful for cases in which the mark-up data has been compiled in pieces.

get_tag() and set_tag() retrieve and modify (respectively) the value of the specified tag. If “value” is null when calling the set function, the refrenced tag will be removed from the mark-up.

bpp_get() and bpp_set() retrieve and modify (respectively) the value of the image.bpp (bits per pixel) tag.

exif_get() and exif_set() retrieve and modify (respectively) the exif.* group of tags (EXIF metadata). The exif data is passed in and out in binary format as per the EXIF standard; host is responsible for converting this data to and from the textual representation used by the MARK attachment. This saves the plug-in the burden of implementing an EXIF conversion library. When you call exif_get(), the host dereferences exif and sz_exif and checks if they point to valid exif data (header-less EXIF data is accepted by later versions). If so, the host will attempt to initialize the EXIF object with that data before inserting values from markup. The host will then return the new data and its size without attempting to free the original buffer; doing that is the caller’s responsibility. exif_loadXMP() modifies the EXIF metadata based on the data contained in the provided XMP metadata. The XMP data should be a null-terminated string containing UTF-encoded XML. If it is not possible to guarantee that the string is null-terminated, then the limit_or_zero parameter should be set to the exact length of the string, otherwise it should be set to zero.

The internal implementation of pi_MetaMarkup is neither defined nor fixed, and is purely host dependent. Do not attempt to access the reserved portion of the object.